◆ KOVO
GitHub
Menu

API Reference

@kovojs/core

Generated from 1 public subpath — 91 exports, 91 documented. Do not edit by hand.

@kovojs/core#

Component model, diagnostics registry, routes, queries, forms, storage, and webhook verifiers.

Source: packages/core/src/index.ts

Functions#

createFileSystemStorage#

Create an object store backed by a directory on the local filesystem. Object metadata is kept in sidecar JSON files alongside each blob.

Parameter Type Description
options FileSystemStorageOptions The root directory under which objects are stored.
(returns) StorageCapability A StorageCapability backed by the filesystem.
ts
function createFileSystemStorage(options: FileSystemStorageOptions): StorageCapability;

Example

ts
import { createFileSystemStorage } from '@kovojs/core';

const storage = createFileSystemStorage({ root: './uploads' });

createMemoryStorage#

Create an in-memory object store implementing StorageCapability. Useful for tests and local development where uploads should not touch disk or a bucket.

Parameter Type Description
options MemoryStorageOptions Optional now clock for deterministic lastModified values.
(returns) StorageCapability A StorageCapability backed by a Map.
ts
function createMemoryStorage(options: MemoryStorageOptions = {}): StorageCapability;

Example

ts
import { createMemoryStorage } from '@kovojs/core';

const storage = createMemoryStorage();
await storage.put('avatars/1.png', new Uint8Array([1, 2, 3]));

createS3CompatibleStorage#

Adapt any S3-compatible object client (AWS S3, R2, MinIO, …) to the StorageCapability interface, so the same upload code works across backends.

Parameter Type Description
options S3CompatibleStorageOptions The bucket and an S3CompatibleObjectClient implementation.
(returns) StorageCapability A StorageCapability backed by the given client and bucket.
ts
function createS3CompatibleStorage(options: S3CompatibleStorageOptions): StorageCapability;

normalizeStorageKey#

Normalize a storage key: trim, collapse slashes, and reject path-traversal so keys cannot escape their prefix.

Parameter Type Description
key string The raw object key.
(returns) string The normalized key.
ts
function normalizeStorageKey(key: string): string;

Example

ts
import { normalizeStorageKey } from '@kovojs/core';

const key: string = normalizeStorageKey('/avatars//1.png');

storageBodyToBytes#

Materialize any StorageBody (string, ArrayBuffer, typed array, or stream) into a single Uint8Array.

Parameter Type Description
body StorageBody The storage body to read.
(returns) Promise<Uint8Array> The body's bytes as a Uint8Array.
ts
async function storageBodyToBytes(body: StorageBody): Promise<Uint8Array>;

Example

ts
import { storageBodyToBytes } from '@kovojs/core';

const bytes: Uint8Array = await storageBodyToBytes('hello');

customVerifier#

Wrap a custom verification function as a named webhook verifier, for schemes that HMAC presets do not cover.

Parameter Type Description
name string Identifier recorded on the verifier and its custom:<name> scheme.
verify (request: WebhookVerificationRequest) => Promise<boolean> | boolean Predicate over the raw request returning whether it is authentic.
(returns) CustomWebhookVerifier A CustomWebhookVerifier.
ts
function customVerifier(
  name: string,
  verify: (request: WebhookVerificationRequest) => Promise<boolean> | boolean,
): CustomWebhookVerifier;

Example

ts
import { customVerifier, type WebhookHeaders } from '@kovojs/core';

function tokenFrom(headers: WebhookHeaders): string | undefined {
  if ('get' in headers && typeof headers.get === 'function') {
    const value = headers.get('x-token');
    return typeof value === 'string' ? value : undefined;
  }
  return undefined;
}

export const verifier = customVerifier(
  'static-token',
  (request) => tokenFrom(request.headers) === 'expected',
);

hmacSignature#

Build an HMAC webhook verifier that checks a signature header against the raw payload bytes before any parsing — the default for machine endpoints (SPEC §9.1). Provider-specific recipes can be written locally on top of this helper; standardWebhooks remains the shared non-vendor preset.

Parameter Type Description
options HmacSignatureOptions Secret(s), header name, encoding, payload derivation, and tolerance.
(returns) HmacSignatureVerifier An HmacSignatureVerifier with an async verify.
ts
function hmacSignature(options: HmacSignatureOptions): HmacSignatureVerifier;

Example

ts
import { hmacSignature } from '@kovojs/core';

export const verifier = hmacSignature({
  encoding: 'hex',
  header: 'x-signature',
  payload: (request) => request.payload,
  secret: 'whsec_test',
});

standardWebhooks#

Preset HMAC verifier for the Standard Webhooks spec (webhook-id, webhook-timestamp, webhook-signature headers).

Parameter Type Description
options StandardWebhooksOptions The Standard Webhooks signing secret(s).
(returns) HmacSignatureVerifier An HmacSignatureVerifier configured for Standard Webhooks.
ts
function standardWebhooks(options: StandardWebhooksOptions): HmacSignatureVerifier;

Example

ts
import { standardWebhooks } from '@kovojs/core';

export const verifier = standardWebhooks({ secret: 'whsec_test' });

component#

Declare a UI component with optional query bindings, optional serializable island state, and a render function. The compiler derives the component's load-bearing name and live refresh target from the exported binding, module path, queries, and authored keys; queries and state are passed to render at runtime. Authored components are plain TSX — the compiler derives stamps, bindings, names, and the client module, so you never write derivable data-bind/kovo-* attributes by hand (SPEC §4.1, §4.8).

Parameter Type Description
definition Definition & { render: ( queries: any, state: any, slots: ComponentRenderSlots<ComponentDefinitionMutations<Definition>… render plus optional queries, state, and disableServerRefresh.
(returns) Component<Definition> A Component descriptor the compiler lowers and the server renders.
ts
function component<const Definition extends ComponentDefinitionShape>(
  definition: Definition & {
    render: (
      queries: any,
      state: any,
      slots: ComponentRenderSlots<ComponentDefinitionMutations<Definition>>,
    ) => any;
  },
): Component<Definition>;

Example

ts
import { component } from '@kovojs/core';

type CounterState = { count: number };

export const Counter = component({
  state: (): CounterState => ({ count: 0 }),
  render: (_queries: Record<string, never>, state: CounterState) =>
    `<button>${state.count}</button>`,
});

ErrorBoundary#

Declare a tree-local unexpected-error boundary. Server JSX catches descendant render failures and renders fallback; typed mutation failures remain normal <FieldError> / <FormError> state (SPEC §9.2).

ts
function ErrorBoundary(props: ErrorBoundaryProps): ComponentRenderResult;

route#

Declare a route descriptor: a typed path plus its param/search shapes. This is the registry-level seed used for typed links (href, Link, redirect); to also attach a server page handler, use route from @kovojs/server, which extends this with page, guards, and meta (SPEC §6.4).

Parameter Type Description
path Path URL pattern; :name segments become typed params.
options RouteOptions<Params, Search> Optional params/search shapes and prefetch policy.
(returns) Route<Path, Params, Search> A Route descriptor keyed by path.
ts
function route<
  const Path extends string,
  Params extends Record<string, string> = PathParams<Path>,
  Search extends Record<string, JsonValue> = Record<string, JsonValue>,
>(path: Path, options: RouteOptions<Params, Search> = {}): Route<Path, Params, Search>;

Example

ts
import { route } from '@kovojs/core';

export const productRoute = route('/products/:id', {
  params: { id: '' },
  prefetch: 'conservative',
});

href#

Build a URL string for a registered route, substituting :param segments and appending typed search values. Params for the path are required and type-checked against the route's declared shape (SPEC §6.4).

Parameter Type Description
path Path A registered route path.
options RouteHrefOptions<RouteFor<Path>> params for the path segments and optional search.
(returns) string The encoded URL string.
ts
function href<const Path extends RegistryKey<RouteRegistry>>(
  path: Path,
  options: RouteHrefOptions<RouteFor<Path>>,
): string;

Example

ts
import { href } from '@kovojs/core';

const url: string = href('/products/:id', { params: { id: 'p1' } });

Build a typed link descriptor ({ href }) for a registered route. Same typing as href, returned as an object you can spread onto an anchor (SPEC §6.4).

Parameter Type Description
path Path A registered route path.
options RouteHrefOptions<RouteFor<Path>> params for the path segments and optional search.
(returns) LinkDescriptor A LinkDescriptor carrying the resolved href.
ts
function Link<const Path extends RegistryKey<RouteRegistry>>(
  path: Path,
  options: RouteHrefOptions<RouteFor<Path>>,
): LinkDescriptor;

Example

ts
import { Link } from '@kovojs/core';

const link = Link('/products/:id', { params: { id: 'p1' } });
const anchor = `<a href="${link.href}">View</a>`;

redirect#

Build a 303 redirect to a registered route. Return it from a route page or mutation handler to send the browser to a typed destination (SPEC §6.4).

Parameter Type Description
path Path A registered route path.
options RouteHrefOptions<RouteFor<Path>> params for the path segments and optional search.
(returns) Redirect A Redirect with status: 303 and the resolved location.
ts
function redirect<const Path extends RegistryKey<RouteRegistry>>(
  path: Path,
  options: RouteHrefOptions<RouteFor<Path>>,
): Redirect;

Example

ts
import { redirect } from '@kovojs/core';

const toProduct = redirect('/products/:id', { params: { id: 'p1' } });
// toProduct.status === 303

query#

Reference a registered query by key for component bindings. This is the client-facing query handle (just { key }); the server-side query with a loader and read set is query from @kovojs/server (SPEC §10.2).

Parameter Type Description
key Key A registered query key.
(returns) Query<Key, Result> A typed Query handle whose result reflects the registry entry.
ts
function query<
  const Key extends RegistryKey<QueryRegistry>,
  Result = Key extends keyof QueryRegistry ? QueryRegistry[Key] : unknown,
>(key: Key): Query<Key, Result>;

Example

ts
import { query } from '@kovojs/core';

export const cart = query('cart');

formFields#

Assert and return the exhaustive field list of a form. TypeScript rejects the call unless fields names every input field of the form, so renaming a field surfaces as a type error at every call site (SPEC §6.3).

Parameter Type Description
_form Definition The form whose fields are being enumerated.
fields CompleteFormFields<Definition, Fields> The complete tuple of the form's field names.
(returns) Fields The same fields tuple, typed.
ts
function formFields<
  Definition extends Form<string, any, unknown>,
  const Fields extends readonly FormFieldName<Definition>[],
>(_form: Definition, fields: CompleteFormFields<Definition, Fields>): Fields;

FieldError#

Render a field-scoped mutation failure message. The compiler injects the enclosing typed form's failure slot and validates name against the mutation input schema (SPEC §6.3 / §9.2).

ts
function FieldError<Failure = unknown>(props: FieldErrorProps<Failure>): string;

FormError#

Render a form-scoped mutation failure message. Validation failures stay field-scoped; declared coded failures render here by default (SPEC §9.2).

ts
function FormError<Failure = unknown>(props: FormErrorProps<Failure>): string;

event#

Declare a typed client event with a serializable payload. Handlers dispatch and listen for events by this name; serverFactKeys marks payload fields the server is allowed to populate (SPEC §4.3).

Parameter Type Description
name Name Event name used when dispatching and listening.
options EventOptions<Payload> Optional serverFactKeys naming server-provided payload fields.
(returns) EventDefinition<Name, Payload> An EventDefinition whose payload type is Payload.
ts
function event<const Name extends string, Payload extends JsonValue = JsonValue>(
  name: Name,
  options: EventOptions<Payload> = {},
): EventDefinition<Name, Payload>;

Example

ts
import { event } from '@kovojs/core';

export const itemAdded = event<'item-added', { id: string }>('item-added');

Types & interfaces#

DiagnosticCode#

The string-literal union of every KV### diagnostic code the framework can emit.

ts
type DiagnosticCode =
  | 'KV201'
  | 'KV210'
  | 'KV211'
  | 'KV212'
  | 'KV220'
  | 'KV221'
  | 'KV222'
  | 'KV223'
  | 'KV224'
  | 'KV225'
  | 'KV226'
  | 'KV227'
  | 'KV228'
  | 'KV230'
  | 'KV231'
  | 'KV232'
  | 'KV233'
  | 'KV234'
  | 'KV235'
  | 'KV236'
  | 'KV237'
  | 'KV238'
  | 'KV239'
  | 'KV240'
  | 'KV241'
  | 'KV242'
  | 'KV301'
  | 'KV302'
  | 'KV303'
  | 'KV304'
  | 'KV310'
  | 'KV311'
  | 'KV320'
  | 'KV330'
  | 'KV402'
  | 'KV403'
  | 'KV404'
  | 'KV405'
  | 'KV406'
// … truncated (5 more lines); see the package source for the full declaration.

DiagnosticSeverity#

Severity tier of a diagnostic, from blocking error down to advisory notice.

ts
type DiagnosticSeverity = 'error' | 'warn' | 'lint' | 'notice';

FileSystemStorageOptions#

Options for the filesystem-backed storage: the root directory objects are stored under.

ts
interface FileSystemStorageOptions {
  root: string;
}

MemoryStorageOptions#

Options for the in-memory storage: an optional clock used for deterministic modified times.

ts
interface MemoryStorageOptions {
  now?: () => Date;
}

S3CompatibleGetObjectInput#

Input to an S3-compatible get-object call: the target bucket and key.

ts
interface S3CompatibleGetObjectInput {
  bucket: string;
  key: string;
}

S3CompatibleGetObjectOutput#

Output of an S3-compatible get-object call: the object metadata plus the object body.

ts
interface S3CompatibleGetObjectOutput extends S3CompatibleObjectMetadata {
  body: StorageBody;
}

S3CompatibleHeadObjectInput#

Input to an S3-compatible head-object call: the target bucket and key.

ts
interface S3CompatibleHeadObjectInput {
  bucket: string;
  key: string;
}

S3CompatibleObjectClient#

The minimal S3-compatible client an app supplies: get, head, and put object operations.

ts
interface S3CompatibleObjectClient {
  getObject(input: S3CompatibleGetObjectInput): Promise<S3CompatibleGetObjectOutput | undefined>;
  headObject(input: S3CompatibleHeadObjectInput): Promise<S3CompatibleObjectMetadata | undefined>;
  putObject(input: S3CompatiblePutObjectInput): Promise<S3CompatiblePutObjectOutput>;
}

S3CompatibleObjectMetadata#

Object metadata returned by an S3-compatible client: content length, content type, etag, modified time, and custom metadata.

ts
interface S3CompatibleObjectMetadata {
  contentLength?: number;
  contentType?: string;
  etag?: string;
  lastModified?: Date | string;
  metadata?: Readonly<Record<string, string>>;
}

S3CompatiblePutObjectInput#

Input to an S3-compatible put-object call: target bucket and key, the body, and optional content type and metadata.

ts
interface S3CompatiblePutObjectInput {
  body: StorageBody;
  bucket: string;
  contentType?: string;
  key: string;
  metadata?: Readonly<Record<string, string>>;
}

S3CompatiblePutObjectOutput#

Output of an S3-compatible put-object call: the object metadata plus an optional size.

ts
interface S3CompatiblePutObjectOutput extends S3CompatibleObjectMetadata {
  size?: number;
}

S3CompatibleStorageOptions#

Options for S3-compatible storage: the bucket, the underlying object client, and an optional key prefix.

ts
interface S3CompatibleStorageOptions {
  bucket: string;
  client: S3CompatibleObjectClient;
  prefix?: string;
}

StorageBody#

The accepted body shapes when writing an object: a string, raw bytes, or a byte stream.

ts
type StorageBody = string | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array>;

StorageCapability#

The object-storage interface an app uses to read, write, stat, and stream objects by key.

ts
interface StorageCapability {
  get(key: string): Promise<StorageGetResult | undefined>;
  put(key: string, body: StorageBody, options?: StoragePutOptions): Promise<StoragePutResult>;
  stat(key: string): Promise<StorageObjectInfo | undefined>;
  stream(key: string): Promise<StorageStreamResult | undefined>;
}

StorageGetResult#

Result of reading an object fully into memory: its descriptive information plus the object bytes.

ts
interface StorageGetResult extends StorageObjectInfo {
  body: Uint8Array;
}

StorageObjectInfo#

Descriptive information about a stored object: its key, size, and optional content type, etag, modified time, and metadata.

ts
interface StorageObjectInfo {
  contentType?: string;
  etag?: string;
  key: string;
  lastModified?: Date;
  metadata?: Readonly<Record<string, string>>;
  size: number;
}

StoragePutOptions#

Optional metadata to attach when writing an object: content type, etag, and custom key/value metadata.

ts
interface StoragePutOptions {
  contentType?: string;
  etag?: string;
  metadata?: Readonly<Record<string, string>>;
}

StoragePutResult#

Result of writing an object: the stored object's descriptive information.

ts
interface StoragePutResult extends StorageObjectInfo {}

StorageStreamResult#

Result of opening an object as a stream: its descriptive information plus a readable byte stream of the body.

ts
interface StorageStreamResult extends StorageObjectInfo {
  body: ReadableStream<Uint8Array>;
}

CustomWebhookVerifier#

A verifier for a bespoke webhook scheme: a named scheme plus an async verify of the request.

ts
interface CustomWebhookVerifier {
  kind: 'custom';
  name: string;
  scheme: string;
  verify(request: WebhookVerificationRequest): Promise<boolean>;
}

HmacMultiSignature#

Whether a signature header may carry multiple candidate signatures, or a function that splits them out.

ts
type HmacMultiSignature = boolean | ((signatureHeader: string) => readonly string[]);

HmacSecret#

A signing secret: a string, raw bytes, or a value with an explicit encoding.

ts
type HmacSecret =
  | string
  | Uint8Array
  | {
      encoding?: 'base64' | 'base64url' | 'utf8';
      value: string | Uint8Array;
    };

HmacSignatureEncoding#

Encoding of an HMAC signature as it appears in the signature header.

ts
type HmacSignatureEncoding = 'base64' | 'base64url' | 'hex';

HmacSignatureOptions#

Configuration for an HMAC-signature verifier: header, encoding, payload, secret(s), and optional tolerance and multi-signature handling.

ts
interface HmacSignatureOptions {
  encoding: HmacSignatureEncoding;
  header: string;
  multiSig?: HmacMultiSignature;
  name?: string;
  payload: HmacSignaturePayload;
  scheme?: string;
  secret: HmacSecret | readonly HmacSecret[];
  tolerance?: HmacSignatureTolerance;
}

HmacSignaturePayload#

What gets signed: the request payload directly, or a function that derives the signed bytes from the request and context.

ts
type HmacSignaturePayload =
  | WebhookPayload
  | ((
      request: WebhookVerificationRequest,
      context: HmacSignaturePayloadContext,
    ) => Promise<WebhookPayload> | WebhookPayload);

HmacSignaturePayloadContext#

Context passed to a custom payload builder: the signature header value and a header lookup.

ts
interface HmacSignaturePayloadContext {
  header(name: string): string | undefined;
  signatureHeader: string;
}

HmacSignatureTolerance#

Replay-protection window: the allowed clock skew in seconds plus how to read the request timestamp.

ts
interface HmacSignatureTolerance {
  header?: string;
  seconds: number;
  timestamp?: (
    request: WebhookVerificationRequest,
    context: HmacSignaturePayloadContext,
  ) => number | string | undefined;
}

HmacSignatureVerifier#

A configured HMAC-signature verifier: its options, resolved config, and an async verify of the request.

ts
interface HmacSignatureVerifier {
  config: HmacSignatureOptions;
  kind: 'hmac';
  name: string;
  resolved: ResolvedHmacSignatureConfig;
  scheme: string;
  verify(request: WebhookVerificationRequest): Promise<boolean>;
}

ResolvedHmacSignatureConfig#

The resolved, defaults-applied view of an HMAC verifier's configuration.

ts
interface ResolvedHmacSignatureConfig {
  encoding: HmacSignatureEncoding;
  header: string;
  kind: 'hmac';
  multiSig: boolean;
  name: string;
  scheme: string;
  toleranceSeconds?: number;
}

StandardWebhooksOptions#

Options for the Standard Webhooks preset: the signing secret(s).

ts
interface StandardWebhooksOptions {
  secret: HmacSecret | readonly HmacSecret[];
}

WebhookHeaders#

The request headers a verifier reads, accepted as a Headers, a Map, a record, or any object exposing get.

ts
type WebhookHeaders =
  | Headers
  | Map<string, string>
  | Record<string, WebhookHeaderValue>
  | { get(name: string): WebhookHeaderValue };

WebhookHeaderValue#

A single header value as seen by a verifier: a string, a list of strings, or absent.

ts
type WebhookHeaderValue = null | string | readonly string[] | undefined;

WebhookPayload#

The raw request body a webhook verifier signs over: a string or raw bytes.

ts
type WebhookPayload = string | ArrayBuffer | ArrayBufferView;

WebhookVerificationRequest#

The inbound webhook request a verifier checks: its headers, raw payload, and an optional verification clock.

ts
interface WebhookVerificationRequest {
  headers: WebhookHeaders;
  now?: Date | number;
  payload: WebhookPayload;
}

WebhookVerifier#

A configured webhook verifier: either an HMAC-signature verifier or a custom-scheme verifier.

ts
type WebhookVerifier = HmacSignatureVerifier | CustomWebhookVerifier;

JsonValue#

Any value that survives a JSON round-trip; the boundary type for island state and wire payloads (SPEC §4.1).

ts
type JsonValue =
  | null
  | boolean
  | number
  | string
  | JsonValue[]
  | { [key: string]: JsonValue };

ComponentRenderResult#

Opaque non-callback result of a component's render — the compiler lowers it to HTML/IR.

ts
type ComponentRenderResult =
  | boolean
  | null
  | number
  | readonly ComponentRenderResult[]
  | string
  | undefined
  | { readonly [key: string]: unknown };

ErrorBoundaryProps#

Props accepted by the server-bound <ErrorBoundary /> render fallback helper.

ts
interface ErrorBoundaryProps {
  children?: ComponentRenderResult;
  fallback: ComponentRenderResult | ((error: unknown) => ComponentRenderResult);
  target?: string;
}

ComponentErrorBoundary#

Component-local fallback used by generated live-target renderers for unexpected errors.

ts
interface ComponentErrorBoundary {
  fallback: ComponentRenderResult | ((error: unknown) => ComponentRenderResult);
  target?: string;
}

ComponentMutationFormState#

Render state for one typed mutation form instance.

ts
interface ComponentMutationFormState<Failure> {
  failure: Failure | null;
}

ComponentMutationForms#

Render state keyed by a component's declared mutation handles.

ts
type ComponentMutationForms<Mutations extends ComponentMutationDefinitions> = {
  [Name in keyof Mutations]: ComponentMutationFormState<FormFailure<Mutations[Name]>>;
};

ComponentRenderSlots#

Render-time composition values for children, named slots, and mutation form state (SPEC §4.5/§6.3).

ts
type ComponentRenderSlots<
  Mutations extends ComponentMutationDefinitions = NoComponentMutations,
> = ComponentRenderSlotValues & ComponentRenderFormsSlot<Mutations>;

ComponentDefinition#

Typed body of a component: its query bindings, island state factory, and render.

ts
interface ComponentDefinition<
  RenderQueries = Record<string, unknown>,
  State extends JsonValue = JsonValue,
  Mutations extends ComponentMutationDefinitions = NoComponentMutations,
  QueryBindings = Record<string, unknown>,
> {
  /** Force-off escape hatch for inferred server refresh targets (SPEC §4.1). */
  disableServerRefresh?: boolean;
  /** Removed: query-backed components infer refresh targets; use `disableServerRefresh` to opt out. */
  fragmentTarget?: never;
  /** Unexpected render-error fallback for full-page and live-target renders (SPEC §9.2). */
  errorBoundary?: ComponentErrorBoundary;
  mutations?: Mutations;
  queries?: QueryBindings;
  state?: () => State;
  render: (
    queries: RenderQueries,
    state: State,
    slots: ComponentRenderSlots<Mutations>,
  ) => ComponentRenderResult;
}

ComponentDefinitionInput#

Loosely-typed input accepted by component() before inference narrows it.

ts
interface ComponentDefinitionInput {
  /** Force-off escape hatch for inferred server refresh targets (SPEC §4.1). */
  disableServerRefresh?: boolean;
  /** Removed: query-backed components infer refresh targets; use `disableServerRefresh` to opt out. */
  fragmentTarget?: never;
  /** Unexpected render-error fallback for full-page and live-target renders (SPEC §9.2). */
  errorBoundary?: ComponentErrorBoundary;
  mutations?: Record<string, unknown>;
  queries?: unknown;
  state?: () => JsonValue;
  render: (...args: never[]) => ComponentRenderResult;
}

Component#

A component descriptor returned by component(); the compiler injects name after derivation.

ts
interface Component<Definition extends ComponentDefinitionInput> {
  (props?: Record<string, unknown>): any;
  definition: Definition;
  name?: string;
}

QueryArgsBinding#

A typed component query binding with args derived from serializable component props.

ts
interface QueryArgsBinding<Key extends string, Result, Props, Args> {
  args: (props: Props) => Args;
  key: Key;
  result?: Result;
}

Query#

A typed query handle: a key and the result type it resolves to.

ts
interface Query<Key extends string, Result> {
  args<Props extends Record<string, JsonValue>, Args extends Record<string, JsonValue>>(
    mapper: (props: Props) => Args,
  ): QueryArgsBinding<Key, Result, Props, Args>;
  key: Key;
  result?: Result;
}

QueryRegistry#

Augmentable registry mapping query keys to result types (declaration-merged by apps).

ts
interface QueryRegistry {}

MutationRegistry#

Augmentable registry mapping mutation keys to input/failure types.

ts
interface MutationRegistry {}

FragmentTargets#

Augmentable registry mapping fragment-target names to their props.

ts
interface FragmentTargets {}

LiveTargetRegistry#

Augmentable generated registry mapping live targets to component/query reconstruction facts.

ts
interface LiveTargetRegistry {}

ComponentRegistry#

Augmentable registry mapping derived component registry keys to component descriptors.

ts
interface ComponentRegistry {}

RouteRegistry#

Augmentable registry mapping route paths to their Route descriptors.

ts
interface RouteRegistry {}

InvalidationSets#

Augmentable registry mapping mutation keys to the query names they invalidate (drives OptimisticFor).

ts
interface InvalidationSets {}

Route#

A route descriptor: typed path, param/search shapes, and prefetch policy.

ts
interface Route<
  Path extends string,
  Params extends Record<string, string> = PathParams<Path>,
  Search extends Record<string, JsonValue> = Record<string, JsonValue>,
> {
  path: Path;
  params?: Params;
  prefetch?: 'conservative' | 'moderate' | false;
  search?: Search;
}

RouteOptions#

Options accepted by route(): param/search shapes and prefetch policy.

ts
interface RouteOptions<
  Params extends Record<string, string> = Record<string, never>,
  Search extends Record<string, JsonValue> = Record<string, JsonValue>,
> {
  params?: Params;
  prefetch?: 'conservative' | 'moderate' | false;
  search?: Search;
}

LinkDescriptor#

Result of Link(): a resolved href string ready to spread onto an anchor.

ts
interface LinkDescriptor {
  href: string;
}

Redirect#

A 303 redirect outcome returned by redirect().

ts
interface Redirect {
  location: string;
  status: 303;
}

Form#

A typed mutation form handle: its key, input shape, and failure type.

ts
interface Form<
  Key extends string,
  Input extends Record<string, JsonValue> = Record<string, JsonValue>,
  Failure = JsonValue,
> {
  failure?: Failure;
  input?: Input;
  key: Key;
}

GetFormInput#

A typed accessor for one search field of a GET form (form.get(...).input(name)).

ts
interface GetFormInput<Name extends string> {
  name: Name;
}

GetFormDescriptor#

Renderable descriptor for a GET form element: its action and method.

ts
interface GetFormDescriptor {
  action: string;
  method: 'get';
}

GetForm#

A GET-route search form: its action, Form descriptor, and typed input(name) accessors.

ts
interface GetForm<
  Path extends string,
  Search extends Record<string, JsonValue> = Record<string, JsonValue>,
> {
  action: string;
  Form: GetFormDescriptor;
  input<const Name extends Extract<keyof Search, string>>(name: Name): GetFormInput<Name>;
  method: 'get';
  path: Path;
}

FormValidationFailure#

The built-in validation failure shape returned when form input fails parsing.

ts
interface FormValidationFailure {
  code: 'VALIDATION';
  fieldErrors: Record<string, string>;
}

FieldErrorProps#

Props accepted by the compiler-bound <FieldError /> mutation failure helper.

ts
interface FieldErrorProps<Failure = unknown> {
  children?: unknown;
  class?: string;
  code?: string | readonly string[];
  failure?: Failure | null;
  id?: string;
  message?: ComponentRenderResult | ((failure: any) => ComponentRenderResult);
  name: string;
  role?: string;
  [attribute: string]: unknown;
}

FormErrorProps#

Props accepted by the compiler-bound <FormError /> mutation failure helper.

ts
interface FormErrorProps<Failure = unknown> {
  children?: unknown;
  class?: string;
  code?: string | readonly string[];
  failure?: Failure | null;
  id?: string;
  message?: ComponentRenderResult | ((failure: any) => ComponentRenderResult);
  role?: string;
  [attribute: string]: unknown;
}

FormInput#

Extract the input shape of a Form definition.

ts
type FormInput<Definition> =
  Definition extends Form<string, infer Input, unknown> ? Input : never;

FormFailure#

Extract the failure type of a Form, unioned with the built-in validation failure.

ts
type FormFailure<Definition> =
  Definition extends Form<string, any, infer Failure> ? Failure | FormValidationFailure : never;

FormFieldName#

The string-literal union of a form's field names.

ts
type FormFieldName<Definition> = Extract<keyof FormInput<Definition>, string>;

EventDefinition#

A typed event descriptor: its name, payload type, and server-populated payload keys.

ts
interface EventDefinition<Name extends string, Payload extends JsonValue = JsonValue> {
  name: Name;
  payload?: Payload;
  serverFactKeys?: readonly string[];
}

EventPayload#

Extract the payload type of an EventDefinition.

ts
type EventPayload<Definition> =
  Definition extends EventDefinition<string, infer Payload> ? Payload : never;

EventOptions#

Options for event(): which payload keys the server is allowed to supply.

ts
interface EventOptions<Payload extends JsonValue = JsonValue> {
  serverFactKeys?: readonly Extract<keyof Payload, string>[];
}

Constants#

form#

Reference a registered mutation as a typed form, or a GET route as a search form via form.get. form(key) returns a Form whose input and failure types come from the mutation registry; form.get(path) returns a descriptor with typed input(name) accessors for the route's search fields (SPEC §6.3).

ts
const form = Object.assign(createMutationForm, {
  get: getRouteForm,
});

Example

ts
import { form } from '@kovojs/core';

export const addToCart = form('cart/add');
export const search = form.get('/products');