@atscript/db-client 0.1.61 → 0.1.63

package/dist/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _uniqu_url_builder = require("@uniqu/url/builder");
+let _atscript_typescript_utils = require("@atscript/typescript/utils");
 //#region src/client-error.ts
 /**
 * Error thrown by `Client` when the server responds with a non-2xx status code.
@@ -92,6 +93,8 @@ var Client = class {
 	_navigate;
 	_metaPromise;
 	_validatorPromise;
+	/** Cached deserialized form schemas keyed by form name. */
+	_formCache = /* @__PURE__ */ new Map();
 	constructor(path, opts) {
 		this._path = path.endsWith("/") ? path.slice(0, -1) : path;
 		this._baseUrl = opts?.baseUrl ?? "";
@@ -218,11 +221,18 @@ var Client = class {
 	* field sets produce HTTP 400; obvious type errors (scalars, `null`) are
 	* caught at compile time when `T` is typed.
 	*
+	* **Form input.** When the action's `inputForm` field is set, the server
+	* expects a structured payload in the envelope's `input` field. Pass it as
+	* the third argument; the schema can be fetched ahead of time via
+	* {@link getActionForm} to drive a UI form. Body shape on the wire is
+	* `{ ids?, input? }` — `ids` carries `id` (object or array per level),
+	* `input` carries the form payload.
+	*
 	* @typeParam R Caller-asserted return shape from the action handler. The
 	*              server returns whatever the handler emits (commonly
 	*              `{ message?: string, ... }`); the client cannot validate.
 	*/
-	async action(name, id) {
+	async action(name, id, input) {
 		const meta = await this.meta();
 		const action = meta.actions.find((a) => a.name === name);
 		if (!action) throw new ActionNotFoundError(name);
@@ -232,10 +242,34 @@ var Client = class {
 			await this._dispatchNavigate(action, url);
 			return;
 		}
-		const body = this._buildActionBody(action, id);
+		const body = this._buildActionBody(action, id, input);
 		return this._postAction(action, body);
 	}
 	/**
+	* Fetches and caches the deserialized form schema for an action's
+	* `@InputForm()` parameter. Returns `null` when the action has no form
+	* declared, or doesn't exist on `/meta`. Callers typically pass the
+	* returned annotated type to a form-renderer (e.g. `@atscript/ui` form
+	* components) and then submit the collected payload through
+	* {@link action}'s `input` argument.
+	*/
+	async getActionForm(actionName) {
+		const action = (await this.meta()).actions.find((a) => a.name === actionName);
+		if (!action?.inputForm) return null;
+		return this._loadActionForm(action.inputForm);
+	}
+	_loadActionForm(formName) {
+		let p = this._formCache.get(formName);
+		if (!p) {
+			p = this._request("GET", `meta/form/${encodeURIComponent(formName)}`).then((schema) => (0, _atscript_typescript_utils.deserializeAnnotatedType)(schema)).catch((err) => {
+				this._formCache.delete(formName);
+				throw err;
+			});
+			this._formCache.set(formName, p);
+		}
+		return p;
+	}
+	/**
 	* Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
 	* Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
 	*/
@@ -252,15 +286,24 @@ var Client = class {
 		});
 		return this._validatorPromise;
 	}
-	_buildActionBody(action, id) {
-		if (action.level === "table") return void 0;
-		if (action.level === "rows") {
-			if (id === void 0) return [];
-			if (!Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): rows-level actions require an array of identifier objects; received ${describeShape(id)}.`);
-			return id;
+	_buildActionBody(action, id, input) {
+		const envelope = {};
+		switch (action.level) {
+			case "rows":
+				if (id === void 0) envelope.ids = [];
+				else if (!Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): rows-level actions require an array of identifier objects; received ${describeShape(id)}.`);
+				else envelope.ids = id;
+				break;
+			case "row":
+				if (id === null || typeof id !== "object" || Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): row-level actions require an identifier object; received ${describeShape(id)}.`);
+				envelope.ids = id;
+				break;
+			case "table":
+				if (input === void 0) return void 0;
+				break;
 		}
-		if (id !== null && typeof id === "object" && !Array.isArray(id)) return id;
-		throw new TypeError(`client.action("${action.name}"): row-level actions require an identifier object; received ${describeShape(id)}.`);
+		if (input !== void 0) envelope.input = input;
+		return envelope;
 	}
 	_interpolateNavigateUrl(action, id, preferredId) {
 		if (action.level !== "row") return action.value;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { C as TDbInsertManyResult, D as Uniquery, E as TypedWithRelation, O as UniqueryControls, S as TDbDeleteResult, T as TDbUpdateResult, _ as OwnOf, b as SearchIndexInfo, c as AtscriptClientShape, d as DataOf, f as FieldMeta, g as NavOf, h as MetaResponse, i as ValidatorMode, l as ClientOptions, m as IdOf, n as ClientValidator, o as AggregateQuery, p as FilterExpr, s as AggregateResult, t as ClientValidationError, u as ClientResponse, v as PageResult, w as TDbInsertResult, x as ServerError, y as RelationInfo } from "./validator-BminFmAf.cjs";
+import { C as TDbInsertManyResult, D as Uniquery, E as TypedWithRelation, O as UniqueryControls, S as TDbDeleteResult, T as TDbUpdateResult, _ as OwnOf, b as SearchIndexInfo, c as AtscriptClientShape, d as DataOf, f as FieldMeta, g as NavOf, h as MetaResponse, i as ValidatorMode, l as ClientOptions, m as IdOf, n as ClientValidator, o as AggregateQuery, p as FilterExpr, s as AggregateResult, t as ClientValidationError, u as ClientResponse, v as PageResult, w as TDbInsertResult, x as ServerError, y as RelationInfo } from "./validator-CiQNksPD.cjs";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
+import { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
 import { TCrudOp, TCrudPermissions, 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
 type Own<T> = OwnOf<T>;
@@ -38,6 +38,8 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
   private readonly _navigate?;
   private _metaPromise?;
   private _validatorPromise?;
+  /** Cached deserialized form schemas keyed by form name. */
+  private _formCache;
   constructor(path: string, opts?: ClientOptions);
   /**
    * `GET /query` — query records with typed filter, sort, select, and relations.
@@ -129,11 +131,28 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * field sets produce HTTP 400; obvious type errors (scalars, `null`) are
    * caught at compile time when `T` is typed.
    *
+   * **Form input.** When the action's `inputForm` field is set, the server
+   * expects a structured payload in the envelope's `input` field. Pass it as
+   * the third argument; the schema can be fetched ahead of time via
+   * {@link getActionForm} to drive a UI form. Body shape on the wire is
+   * `{ ids?, input? }` — `ids` carries `id` (object or array per level),
+   * `input` carries the form payload.
+   *
    * @typeParam R Caller-asserted return shape from the action handler. The
    *              server returns whatever the handler emits (commonly
    *              `{ message?: string, ... }`); the client cannot validate.
    */
-  action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[]): Promise<R>;
+  action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[], input?: unknown): Promise<R>;
+  /**
+   * Fetches and caches the deserialized form schema for an action's
+   * `@InputForm()` parameter. Returns `null` when the action has no form
+   * declared, or doesn't exist on `/meta`. Callers typically pass the
+   * returned annotated type to a form-renderer (e.g. `@atscript/ui` form
+   * components) and then submit the collected payload through
+   * {@link action}'s `input` argument.
+   */
+  getActionForm(actionName: string): Promise<TAtscriptAnnotatedType | null>;
+  private _loadActionForm;
   /**
    * Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { C as TDbInsertManyResult, D as Uniquery, E as TypedWithRelation, O as UniqueryControls, S as TDbDeleteResult, T as TDbUpdateResult, _ as OwnOf, b as SearchIndexInfo, c as AtscriptClientShape, d as DataOf, f as FieldMeta, g as NavOf, h as MetaResponse, i as ValidatorMode, l as ClientOptions, m as IdOf, n as ClientValidator, o as AggregateQuery, p as FilterExpr, s as AggregateResult, t as ClientValidationError, u as ClientResponse, v as PageResult, w as TDbInsertResult, x as ServerError, y as RelationInfo } from "./validator-DkIQ_0Lc.mjs";
-import { TSerializedAnnotatedType } from "@atscript/typescript/utils";
+import { TAtscriptAnnotatedType, 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 { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
 
@@ -38,6 +38,8 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
   private readonly _navigate?;
   private _metaPromise?;
   private _validatorPromise?;
+  /** Cached deserialized form schemas keyed by form name. */
+  private _formCache;
   constructor(path: string, opts?: ClientOptions);
   /**
    * `GET /query` — query records with typed filter, sort, select, and relations.
@@ -129,11 +131,28 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * field sets produce HTTP 400; obvious type errors (scalars, `null`) are
    * caught at compile time when `T` is typed.
    *
+   * **Form input.** When the action's `inputForm` field is set, the server
+   * expects a structured payload in the envelope's `input` field. Pass it as
+   * the third argument; the schema can be fetched ahead of time via
+   * {@link getActionForm} to drive a UI form. Body shape on the wire is
+   * `{ ids?, input? }` — `ids` carries `id` (object or array per level),
+   * `input` carries the form payload.
+   *
    * @typeParam R Caller-asserted return shape from the action handler. The
    *              server returns whatever the handler emits (commonly
    *              `{ message?: string, ... }`); the client cannot validate.
    */
-  action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[]): Promise<R>;
+  action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[], input?: unknown): Promise<R>;
+  /**
+   * Fetches and caches the deserialized form schema for an action's
+   * `@InputForm()` parameter. Returns `null` when the action has no form
+   * declared, or doesn't exist on `/meta`. Callers typically pass the
+   * returned annotated type to a form-renderer (e.g. `@atscript/ui` form
+   * components) and then submit the collected payload through
+   * {@link action}'s `input` argument.
+   */
+  getActionForm(actionName: string): Promise<TAtscriptAnnotatedType | null>;
+  private _loadActionForm;
   /**
    * Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { buildUrl } from "@uniqu/url/builder";
+import { deserializeAnnotatedType } from "@atscript/typescript/utils";
 //#region src/client-error.ts
 /**
 * Error thrown by `Client` when the server responds with a non-2xx status code.
@@ -91,6 +92,8 @@ var Client = class {
 	_navigate;
 	_metaPromise;
 	_validatorPromise;
+	/** Cached deserialized form schemas keyed by form name. */
+	_formCache = /* @__PURE__ */ new Map();
 	constructor(path, opts) {
 		this._path = path.endsWith("/") ? path.slice(0, -1) : path;
 		this._baseUrl = opts?.baseUrl ?? "";
@@ -217,11 +220,18 @@ var Client = class {
 	* field sets produce HTTP 400; obvious type errors (scalars, `null`) are
 	* caught at compile time when `T` is typed.
 	*
+	* **Form input.** When the action's `inputForm` field is set, the server
+	* expects a structured payload in the envelope's `input` field. Pass it as
+	* the third argument; the schema can be fetched ahead of time via
+	* {@link getActionForm} to drive a UI form. Body shape on the wire is
+	* `{ ids?, input? }` — `ids` carries `id` (object or array per level),
+	* `input` carries the form payload.
+	*
 	* @typeParam R Caller-asserted return shape from the action handler. The
 	*              server returns whatever the handler emits (commonly
 	*              `{ message?: string, ... }`); the client cannot validate.
 	*/
-	async action(name, id) {
+	async action(name, id, input) {
 		const meta = await this.meta();
 		const action = meta.actions.find((a) => a.name === name);
 		if (!action) throw new ActionNotFoundError(name);
@@ -231,10 +241,34 @@ var Client = class {
 			await this._dispatchNavigate(action, url);
 			return;
 		}
-		const body = this._buildActionBody(action, id);
+		const body = this._buildActionBody(action, id, input);
 		return this._postAction(action, body);
 	}
 	/**
+	* Fetches and caches the deserialized form schema for an action's
+	* `@InputForm()` parameter. Returns `null` when the action has no form
+	* declared, or doesn't exist on `/meta`. Callers typically pass the
+	* returned annotated type to a form-renderer (e.g. `@atscript/ui` form
+	* components) and then submit the collected payload through
+	* {@link action}'s `input` argument.
+	*/
+	async getActionForm(actionName) {
+		const action = (await this.meta()).actions.find((a) => a.name === actionName);
+		if (!action?.inputForm) return null;
+		return this._loadActionForm(action.inputForm);
+	}
+	_loadActionForm(formName) {
+		let p = this._formCache.get(formName);
+		if (!p) {
+			p = this._request("GET", `meta/form/${encodeURIComponent(formName)}`).then((schema) => deserializeAnnotatedType(schema)).catch((err) => {
+				this._formCache.delete(formName);
+				throw err;
+			});
+			this._formCache.set(formName, p);
+		}
+		return p;
+	}
+	/**
 	* Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
 	* Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
 	*/
@@ -251,15 +285,24 @@ var Client = class {
 		});
 		return this._validatorPromise;
 	}
-	_buildActionBody(action, id) {
-		if (action.level === "table") return void 0;
-		if (action.level === "rows") {
-			if (id === void 0) return [];
-			if (!Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): rows-level actions require an array of identifier objects; received ${describeShape(id)}.`);
-			return id;
+	_buildActionBody(action, id, input) {
+		const envelope = {};
+		switch (action.level) {
+			case "rows":
+				if (id === void 0) envelope.ids = [];
+				else if (!Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): rows-level actions require an array of identifier objects; received ${describeShape(id)}.`);
+				else envelope.ids = id;
+				break;
+			case "row":
+				if (id === null || typeof id !== "object" || Array.isArray(id)) throw new TypeError(`client.action("${action.name}"): row-level actions require an identifier object; received ${describeShape(id)}.`);
+				envelope.ids = id;
+				break;
+			case "table":
+				if (input === void 0) return void 0;
+				break;
 		}
-		if (id !== null && typeof id === "object" && !Array.isArray(id)) return id;
-		throw new TypeError(`client.action("${action.name}"): row-level actions require an identifier object; received ${describeShape(id)}.`);
+		if (input !== void 0) envelope.input = input;
+		return envelope;
 	}
 	_interpolateNavigateUrl(action, id, preferredId) {
 		if (action.level !== "row") return action.value;

package/dist/{validator-BminFmAf.d.cts → validator-CiQNksPD.d.cts}

@@ -1,6 +1,6 @@
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, FilterExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
-import { DbResponse, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescript/utils";
+import { DbResponse, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 import { DbValidationContext, ValidatorMode, ValidatorMode as ValidatorMode$1 } from "@atscript/db/validator";
 
 //#region src/types.d.ts

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-BminFmAf.cjs";
+import { a as createClientValidator, i as ValidatorMode, n as ClientValidator, r as DbValidationContext, t as ClientValidationError } from "./validator-CiQNksPD.cjs";
 export { ClientValidationError, ClientValidator, DbValidationContext, ValidatorMode, createClientValidator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-client",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "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.61"
+    "@atscript/db": "0.1.63"
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.44",