@atscript/db-client 0.1.55 → 0.1.56

package/dist/index.cjs

@@ -17,6 +17,28 @@ var ClientError = class extends Error {
 		return this.body.errors ?? [];
 	}
 };
+/** Thrown by `Client.action()` when the action name is not present in `/meta`. */
+var ActionNotFoundError = class extends Error {
+	name = "ActionNotFoundError";
+	constructor(action) {
+		super(`Action "${action}" is not declared on this controller`);
+		this.action = action;
+	}
+};
+/**
+* Thrown by `Client.action()` for actions that cannot be invoked through
+* the client — currently `processor: 'custom'` (UI-dispatched events,
+* which the application is responsible for handling) and `processor: 'navigate'`
+* when no browser environment and no `navigate` option are configured.
+*/
+var ActionUnsupportedError = class extends Error {
+	name = "ActionUnsupportedError";
+	constructor(action, processor, message) {
+		super(message);
+		this.action = action;
+		this.processor = processor;
+	}
+};
 //#endregion
 //#region src/client.ts
 /**
@@ -45,6 +67,7 @@ var Client = class {
 	_baseUrl;
 	_fetch;
 	_headers;
+	_navigate;
 	_metaPromise;
 	_validatorPromise;
 	constructor(path, opts) {
@@ -52,6 +75,7 @@ var Client = class {
 		this._baseUrl = opts?.baseUrl ?? "";
 		this._fetch = opts?.fetch ?? globalThis.fetch.bind(globalThis);
 		this._headers = opts?.headers;
+		this._navigate = opts?.navigate;
 	}
 	/**
 	* `GET /query` — query records with typed filter, sort, select, and relations.
@@ -138,6 +162,39 @@ var Client = class {
 		return this._metaPromise;
 	}
 	/**
+	* Invoke a declared action by name. Resolves the action descriptor from the
+	* cached `/meta` response, then dispatches based on `processor`:
+	*
+	* - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+	*   and return the parsed server response. The HTTP method is always POST.
+	* - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
+	*   PK (URL-encoded; composite PKs are URL-encoded per field and joined
+	*   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
+	*   verbatim. The default navigator (browser only) calls
+	*   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
+	*   integrate with a SPA router.
+	* - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
+	*   are the application's responsibility, not the client's.
+	*
+	* Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
+	*
+	* For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
+	* for a `'rows'` action it is wrapped into a single-element array — the
+	* server-side `@DbActionPKs()` resolver requires an array body.
+	*/
+	async action(name, pk) {
+		const action = (await this.meta()).actions.find((a) => a.name === name);
+		if (!action) throw new ActionNotFoundError(name);
+		if (action.processor === "custom") throw new ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
+		if (action.processor === "navigate") {
+			const url = this._interpolateNavigateUrl(action, pk);
+			await this._dispatchNavigate(action, url);
+			return;
+		}
+		const body = this._buildActionBody(action, pk);
+		return this._postAction(action, body);
+	}
+	/**
 	* Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
 	* Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
 	*/
@@ -154,6 +211,34 @@ var Client = class {
 		});
 		return this._validatorPromise;
 	}
+	_buildActionBody(action, pk) {
+		if (action.level === "table") return void 0;
+		if (action.level !== "rows") return pk;
+		if (Array.isArray(pk)) return pk;
+		return pk === void 0 ? [] : [pk];
+	}
+	_interpolateNavigateUrl(action, pk) {
+		if (action.level !== "row") return action.value;
+		if (pk === void 0) return action.value;
+		return action.value.replace(/\$1/g, encodeNavigatePk(pk));
+	}
+	async _dispatchNavigate(action, url) {
+		if (this._navigate) {
+			await this._navigate(url);
+			return;
+		}
+		const loc = globalThis.location;
+		if (loc?.assign) {
+			loc.assign(url);
+			return;
+		}
+		throw new ActionUnsupportedError(action.name, "navigate", `Action "${action.name}" is processor: 'navigate' but no browser is available and no \`navigate\` option was provided to Client.`);
+	}
+	async _postAction(action, body) {
+		const url = `${this._baseUrl}${action.value}`;
+		const init = await this._buildInit("POST", body);
+		return this._send(url, init, true);
+	}
 	_idToParams(id) {
 		const params = new URLSearchParams();
 		for (const [k, v] of Object.entries(id)) params.set(k, String(v));
@@ -179,6 +264,10 @@ var Client = class {
 	async _request(method, endpoint, body) {
 		const sep = endpoint && !endpoint.startsWith("?") ? "/" : "";
 		const url = `${this._baseUrl}${this._path}${sep}${endpoint}`;
+		const init = await this._buildInit(method, body);
+		return this._send(url, init, false);
+	}
+	async _buildInit(method, body) {
 		const headers = { ...await this._resolveHeaders() };
 		const init = {
 			method,
@@ -188,6 +277,9 @@ var Client = class {
 			headers["Content-Type"] = "application/json";
 			init.body = JSON.stringify(body);
 		}
+		return init;
+	}
+	async _send(url, init, allowEmpty) {
 		const res = await this._fetch(url, init);
 		if (!res.ok) {
 			let errorBody;
@@ -201,9 +293,27 @@ var Client = class {
 			}
 			throw new ClientError(res.status, errorBody);
 		}
-		return res.json();
+		if (!allowEmpty) return res.json();
+		if (res.status === 204 || res.headers.get("content-length") === "0") return void 0;
+		try {
+			return await res.json();
+		} catch {
+			return;
+		}
 	}
 };
+/**
+* Encode a row PK for substitution into a `processor: 'navigate'` URL template.
+* Scalars are URL-encoded directly; composite PK objects have each value
+* URL-encoded and joined with `/` in object-key order (which mirrors
+* `primaryKeys` for the table).
+*/
+function encodeNavigatePk(pk) {
+	if (pk === null || pk === void 0) return "";
+	return (typeof pk === "object" ? Object.values(pk) : [pk]).map((v) => encodeURIComponent(String(v))).join("/");
+}
 //#endregion
+exports.ActionNotFoundError = ActionNotFoundError;
+exports.ActionUnsupportedError = ActionUnsupportedError;
 exports.Client = Client;
 exports.ClientError = ClientError;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { C as TDbUpdateResult, E as UniqueryControls, S as TDbInsertResult, T as Uniquery, _ as RelationInfo, b as TDbDeleteResult, c as ClientOptions, d as FilterExpr, f as IdOf, g as PageResult, h as OwnOf, i as ValidatorMode, l as DataOf, m as NavOf, n as ClientValidator, o as AggregateQuery, p as MetaResponse, s as AggregateResult, t as ClientValidationError, u as FieldMeta, v as SearchIndexInfo, w as TypedWithRelation, x as TDbInsertManyResult, y as ServerError } from "./validator-DfU6oJir.cjs";
+import { C as TDbUpdateResult, E as UniqueryControls, S as TDbInsertResult, T as Uniquery, _ as RelationInfo, b as TDbDeleteResult, c as ClientOptions, d as FilterExpr, f as IdOf, g as PageResult, h as OwnOf, i as ValidatorMode, l as DataOf, m as NavOf, n as ClientValidator, o as AggregateQuery, p as MetaResponse, s as AggregateResult, t as ClientValidationError, u as FieldMeta, v as SearchIndexInfo, w as TypedWithRelation, x as TDbInsertManyResult, y as ServerError } from "./validator-DNm9kCoq.cjs";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
-import { TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
+import { TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
 import { TSerializedAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/client.d.ts
@@ -34,6 +34,7 @@ declare class Client<T = Record<string, unknown>> {
   private readonly _baseUrl;
   private readonly _fetch;
   private readonly _headers?;
+  private readonly _navigate?;
   private _metaPromise?;
   private _validatorPromise?;
   constructor(path: string, opts?: ClientOptions);
@@ -90,6 +91,28 @@ declare class Client<T = Record<string, unknown>> {
    * `GET /meta` — table/view metadata (cached after first call).
    */
   meta(): Promise<MetaResponse>;
+  /**
+   * Invoke a declared action by name. Resolves the action descriptor from the
+   * cached `/meta` response, then dispatches based on `processor`:
+   *
+   * - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+   *   and return the parsed server response. The HTTP method is always POST.
+   * - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
+   *   PK (URL-encoded; composite PKs are URL-encoded per field and joined
+   *   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
+   *   verbatim. The default navigator (browser only) calls
+   *   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
+   *   integrate with a SPA router.
+   * - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
+   *   are the application's responsibility, not the client's.
+   *
+   * Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
+   *
+   * For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
+   * for a `'rows'` action it is wrapped into a single-element array — the
+   * server-side `@DbActionPKs()` resolver requires an array body.
+   */
+  action(name: string, pk?: unknown): Promise<unknown>;
   /**
    * Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
@@ -97,11 +120,17 @@ declare class Client<T = Record<string, unknown>> {
   getValidator(): Promise<ClientValidator>;
   private _validateData;
   private _getValidator;
+  private _buildActionBody;
+  private _interpolateNavigateUrl;
+  private _dispatchNavigate;
+  private _postAction;
   private _idToParams;
   private _getOrNull;
   private _get;
   private _resolveHeaders;
   private _request;
+  private _buildInit;
+  private _send;
 }
 //#endregion
 //#region src/client-error.d.ts
@@ -127,5 +156,23 @@ declare class ClientError extends Error {
     details?: unknown[];
   }[];
 }
+/** Thrown by `Client.action()` when the action name is not present in `/meta`. */
+declare class ActionNotFoundError extends Error {
+  readonly action: string;
+  name: string;
+  constructor(action: string);
+}
+/**
+ * Thrown by `Client.action()` for actions that cannot be invoked through
+ * the client — currently `processor: 'custom'` (UI-dispatched events,
+ * which the application is responsible for handling) and `processor: 'navigate'`
+ * when no browser environment and no `navigate` option are configured.
+ */
+declare class ActionUnsupportedError extends Error {
+  readonly action: string;
+  readonly processor: string;
+  name: string;
+  constructor(action: string, processor: string, message: string);
+}
 //#endregion
-export { type AggregateQuery, type AggregateResult, Client, ClientError, type ClientOptions, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode };
+export { ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, Client, ClientError, type ClientOptions, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { C as TDbUpdateResult, E as UniqueryControls, S as TDbInsertResult, T as Uniquery, _ as RelationInfo, b as TDbDeleteResult, c as ClientOptions, d as FilterExpr, f as IdOf, g as PageResult, h as OwnOf, i as ValidatorMode, l as DataOf, m as NavOf, n as ClientValidator, o as AggregateQuery, p as MetaResponse, s as AggregateResult, t as ClientValidationError, u as FieldMeta, v as SearchIndexInfo, w as TypedWithRelation, x as TDbInsertManyResult, y as ServerError } from "./validator-wyKVvc-q.mjs";
+import { C as TDbUpdateResult, E as UniqueryControls, S as TDbInsertResult, T as Uniquery, _ as RelationInfo, b as TDbDeleteResult, c as ClientOptions, d as FilterExpr, f as IdOf, g as PageResult, h as OwnOf, i as ValidatorMode, l as DataOf, m as NavOf, n as ClientValidator, o as AggregateQuery, p as MetaResponse, s as AggregateResult, t as ClientValidationError, u as FieldMeta, v as SearchIndexInfo, w as TypedWithRelation, x as TDbInsertManyResult, y as ServerError } from "./validator-DfNMCEKa.mjs";
 import { TSerializedAnnotatedType } from "@atscript/typescript/utils";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
-import { TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
+import { TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
 
 //#region src/client.d.ts
 type Own<T> = OwnOf<T>;
@@ -34,6 +34,7 @@ declare class Client<T = Record<string, unknown>> {
   private readonly _baseUrl;
   private readonly _fetch;
   private readonly _headers?;
+  private readonly _navigate?;
   private _metaPromise?;
   private _validatorPromise?;
   constructor(path: string, opts?: ClientOptions);
@@ -90,6 +91,28 @@ declare class Client<T = Record<string, unknown>> {
    * `GET /meta` — table/view metadata (cached after first call).
    */
   meta(): Promise<MetaResponse>;
+  /**
+   * Invoke a declared action by name. Resolves the action descriptor from the
+   * cached `/meta` response, then dispatches based on `processor`:
+   *
+   * - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+   *   and return the parsed server response. The HTTP method is always POST.
+   * - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
+   *   PK (URL-encoded; composite PKs are URL-encoded per field and joined
+   *   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
+   *   verbatim. The default navigator (browser only) calls
+   *   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
+   *   integrate with a SPA router.
+   * - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
+   *   are the application's responsibility, not the client's.
+   *
+   * Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
+   *
+   * For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
+   * for a `'rows'` action it is wrapped into a single-element array — the
+   * server-side `@DbActionPKs()` resolver requires an array body.
+   */
+  action(name: string, pk?: unknown): Promise<unknown>;
   /**
    * Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
@@ -97,11 +120,17 @@ declare class Client<T = Record<string, unknown>> {
   getValidator(): Promise<ClientValidator>;
   private _validateData;
   private _getValidator;
+  private _buildActionBody;
+  private _interpolateNavigateUrl;
+  private _dispatchNavigate;
+  private _postAction;
   private _idToParams;
   private _getOrNull;
   private _get;
   private _resolveHeaders;
   private _request;
+  private _buildInit;
+  private _send;
 }
 //#endregion
 //#region src/client-error.d.ts
@@ -127,5 +156,23 @@ declare class ClientError extends Error {
     details?: unknown[];
   }[];
 }
+/** Thrown by `Client.action()` when the action name is not present in `/meta`. */
+declare class ActionNotFoundError extends Error {
+  readonly action: string;
+  name: string;
+  constructor(action: string);
+}
+/**
+ * Thrown by `Client.action()` for actions that cannot be invoked through
+ * the client — currently `processor: 'custom'` (UI-dispatched events,
+ * which the application is responsible for handling) and `processor: 'navigate'`
+ * when no browser environment and no `navigate` option are configured.
+ */
+declare class ActionUnsupportedError extends Error {
+  readonly action: string;
+  readonly processor: string;
+  name: string;
+  constructor(action: string, processor: string, message: string);
+}
 //#endregion
-export { type AggregateQuery, type AggregateResult, Client, ClientError, type ClientOptions, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode };
+export { ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, Client, ClientError, type ClientOptions, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode };

package/dist/index.mjs

@@ -16,6 +16,28 @@ var ClientError = class extends Error {
 		return this.body.errors ?? [];
 	}
 };
+/** Thrown by `Client.action()` when the action name is not present in `/meta`. */
+var ActionNotFoundError = class extends Error {
+	name = "ActionNotFoundError";
+	constructor(action) {
+		super(`Action "${action}" is not declared on this controller`);
+		this.action = action;
+	}
+};
+/**
+* Thrown by `Client.action()` for actions that cannot be invoked through
+* the client — currently `processor: 'custom'` (UI-dispatched events,
+* which the application is responsible for handling) and `processor: 'navigate'`
+* when no browser environment and no `navigate` option are configured.
+*/
+var ActionUnsupportedError = class extends Error {
+	name = "ActionUnsupportedError";
+	constructor(action, processor, message) {
+		super(message);
+		this.action = action;
+		this.processor = processor;
+	}
+};
 //#endregion
 //#region src/client.ts
 /**
@@ -44,6 +66,7 @@ var Client = class {
 	_baseUrl;
 	_fetch;
 	_headers;
+	_navigate;
 	_metaPromise;
 	_validatorPromise;
 	constructor(path, opts) {
@@ -51,6 +74,7 @@ var Client = class {
 		this._baseUrl = opts?.baseUrl ?? "";
 		this._fetch = opts?.fetch ?? globalThis.fetch.bind(globalThis);
 		this._headers = opts?.headers;
+		this._navigate = opts?.navigate;
 	}
 	/**
 	* `GET /query` — query records with typed filter, sort, select, and relations.
@@ -137,6 +161,39 @@ var Client = class {
 		return this._metaPromise;
 	}
 	/**
+	* Invoke a declared action by name. Resolves the action descriptor from the
+	* cached `/meta` response, then dispatches based on `processor`:
+	*
+	* - `'backend'` → POST `pk` (or `pks`) as a JSON body to the action's path
+	*   and return the parsed server response. The HTTP method is always POST.
+	* - `'navigate'` → for `level: 'row'`, substitute `$1` in `value` with the
+	*   PK (URL-encoded; composite PKs are URL-encoded per field and joined
+	*   with `/`); for `level: 'rows'` or `'table'`, navigate to `value`
+	*   verbatim. The default navigator (browser only) calls
+	*   `window.location.assign(url)`. Provide `ClientOptions.navigate` to
+	*   integrate with a SPA router.
+	* - `'custom'` → throw {@link ActionUnsupportedError}; UI-dispatched events
+	*   are the application's responsibility, not the client's.
+	*
+	* Throws {@link ActionNotFoundError} when the action is not present in `/meta`.
+	*
+	* For `level: 'rows'`, `pk` must be an array. If a non-array is supplied
+	* for a `'rows'` action it is wrapped into a single-element array — the
+	* server-side `@DbActionPKs()` resolver requires an array body.
+	*/
+	async action(name, pk) {
+		const action = (await this.meta()).actions.find((a) => a.name === name);
+		if (!action) throw new ActionNotFoundError(name);
+		if (action.processor === "custom") throw new ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
+		if (action.processor === "navigate") {
+			const url = this._interpolateNavigateUrl(action, pk);
+			await this._dispatchNavigate(action, url);
+			return;
+		}
+		const body = this._buildActionBody(action, pk);
+		return this._postAction(action, body);
+	}
+	/**
 	* Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
 	* Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
 	*/
@@ -153,6 +210,34 @@ var Client = class {
 		});
 		return this._validatorPromise;
 	}
+	_buildActionBody(action, pk) {
+		if (action.level === "table") return void 0;
+		if (action.level !== "rows") return pk;
+		if (Array.isArray(pk)) return pk;
+		return pk === void 0 ? [] : [pk];
+	}
+	_interpolateNavigateUrl(action, pk) {
+		if (action.level !== "row") return action.value;
+		if (pk === void 0) return action.value;
+		return action.value.replace(/\$1/g, encodeNavigatePk(pk));
+	}
+	async _dispatchNavigate(action, url) {
+		if (this._navigate) {
+			await this._navigate(url);
+			return;
+		}
+		const loc = globalThis.location;
+		if (loc?.assign) {
+			loc.assign(url);
+			return;
+		}
+		throw new ActionUnsupportedError(action.name, "navigate", `Action "${action.name}" is processor: 'navigate' but no browser is available and no \`navigate\` option was provided to Client.`);
+	}
+	async _postAction(action, body) {
+		const url = `${this._baseUrl}${action.value}`;
+		const init = await this._buildInit("POST", body);
+		return this._send(url, init, true);
+	}
 	_idToParams(id) {
 		const params = new URLSearchParams();
 		for (const [k, v] of Object.entries(id)) params.set(k, String(v));
@@ -178,6 +263,10 @@ var Client = class {
 	async _request(method, endpoint, body) {
 		const sep = endpoint && !endpoint.startsWith("?") ? "/" : "";
 		const url = `${this._baseUrl}${this._path}${sep}${endpoint}`;
+		const init = await this._buildInit(method, body);
+		return this._send(url, init, false);
+	}
+	async _buildInit(method, body) {
 		const headers = { ...await this._resolveHeaders() };
 		const init = {
 			method,
@@ -187,6 +276,9 @@ var Client = class {
 			headers["Content-Type"] = "application/json";
 			init.body = JSON.stringify(body);
 		}
+		return init;
+	}
+	async _send(url, init, allowEmpty) {
 		const res = await this._fetch(url, init);
 		if (!res.ok) {
 			let errorBody;
@@ -200,8 +292,24 @@ var Client = class {
 			}
 			throw new ClientError(res.status, errorBody);
 		}
-		return res.json();
+		if (!allowEmpty) return res.json();
+		if (res.status === 204 || res.headers.get("content-length") === "0") return void 0;
+		try {
+			return await res.json();
+		} catch {
+			return;
+		}
 	}
 };
+/**
+* Encode a row PK for substitution into a `processor: 'navigate'` URL template.
+* Scalars are URL-encoded directly; composite PK objects have each value
+* URL-encoded and joined with `/` in object-key order (which mirrors
+* `primaryKeys` for the table).
+*/
+function encodeNavigatePk(pk) {
+	if (pk === null || pk === void 0) return "";
+	return (typeof pk === "object" ? Object.values(pk) : [pk]).map((v) => encodeURIComponent(String(v))).join("/");
+}
 //#endregion
-export { Client, ClientError };
+export { ActionNotFoundError, ActionUnsupportedError, Client, ClientError };

package/dist/{validator-DfU6oJir.d.cts → validator-DNm9kCoq.d.cts}

@@ -21,6 +21,17 @@ interface ClientOptions {
    * @example "https://api.example.com"
    */
   baseUrl?: string;
+  /**
+   * Override for `processor: 'navigate'` action dispatch. When `Client.action()`
+   * resolves a navigate action, this hook is invoked with the interpolated
+   * URL. Default behaviour (browser only) calls `window.location.assign(url)`.
+   *
+   * Provide a custom navigator to integrate with a SPA router:
+   * ```typescript
+   * new Client('/api/users', { navigate: (url) => router.push(url) })
+   * ```
+   */
+  navigate?: (url: string) => void | Promise<void>;
 }
 /** Search index metadata from the server. */
 type SearchIndexInfo = TSearchIndexInfo;

package/dist/{validator-wyKVvc-q.d.mts → validator-DfNMCEKa.d.mts}

@@ -21,6 +21,17 @@ interface ClientOptions {
    * @example "https://api.example.com"
    */
   baseUrl?: string;
+  /**
+   * Override for `processor: 'navigate'` action dispatch. When `Client.action()`
+   * resolves a navigate action, this hook is invoked with the interpolated
+   * URL. Default behaviour (browser only) calls `window.location.assign(url)`.
+   *
+   * Provide a custom navigator to integrate with a SPA router:
+   * ```typescript
+   * new Client('/api/users', { navigate: (url) => router.push(url) })
+   * ```
+   */
+  navigate?: (url: string) => void | Promise<void>;
 }
 /** Search index metadata from the server. */
 type SearchIndexInfo = TSearchIndexInfo;

package/dist/validator.d.cts

@@ -1,2 +1,2 @@
-import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-DfU6oJir.cjs";
+import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-DNm9kCoq.cjs";
 export { ClientValidationError, ClientValidator, DbValidationContext, ValidatorMode, createClientValidator };

package/dist/validator.d.mts

@@ -1,2 +1,2 @@
-import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-wyKVvc-q.mjs";
+import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-DfNMCEKa.mjs";
 export { ClientValidationError, ClientValidator, DbValidationContext, ValidatorMode, createClientValidator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-client",
-  "version": "0.1.55",
+  "version": "0.1.56",
   "description": "Browser-compatible HTTP client for @atscript/moost-db REST endpoints.",
   "keywords": [
     "atscript",
@@ -50,7 +50,7 @@
     "@atscript/typescript": "^0.1.50",
     "@uniqu/core": "^0.1.5",
     "unplugin-atscript": "^0.1.50",
-    "@atscript/db": "0.1.55"
+    "@atscript/db": "0.1.56"
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.44",