@atscript/moost-db 0.1.55 → 0.1.56

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as _atscript_typescript_utils0 from "@atscript/typescript/utils";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, Validator } from "@atscript/typescript/utils";
 import * as _uniqu_url0 from "@uniqu/url";
-import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
 import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
@@ -123,8 +123,16 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * Builds the `/meta` payload. Override in subclasses to populate source-specific
    * fields. Defaults return a minimal envelope with the serialized type and the
    * read-only flag; value-help dicts populate their capability hints here.
+   * Subclasses that fully replace the envelope must call {@link buildActions}
+   * directly so `@DbAction*` decorators still surface.
    */
   protected buildMetaResponse(): Promise<TMetaResponse>;
+  /**
+   * Discovers `@DbAction*` and `@DbActions`-style class metadata on this
+   * controller and produces the `actions` array. Returns `[]` for value-help
+   * controllers — see {@link AsValueHelpController#buildMetaResponse}.
+   */
+  protected buildActions(): TDbActionInfo$1[];
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -280,6 +288,12 @@ interface ValueHelpQuery<T> {
  * requests against them. Subclasses that need a backend gate should compose
  * one of their own (see {@link AsDbReadableController} for the
  * `@db.column.filterable` / `@db.column.sortable` pattern).
+ *
+ * **Actions are intentionally NOT supported on value-help controllers.** The
+ * `/meta` payload still includes `actions: []` for shape uniformity, and any
+ * `@DbAction*` / `@DbActions*` decorators applied here are silently ignored.
+ * Value-help is for FK pickers and dictionary surfaces — adding row/table
+ * actions there would muddy the contract.
  */
 declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
   /** Per-prop metadata map of the bound interface; eagerly built once. */
@@ -331,6 +345,7 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
    * these flags at request time.
    */
   protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildActions(): never[];
 }
 //#endregion
 //#region src/as-json-value-help.controller.d.ts
@@ -436,4 +451,152 @@ declare const ViewController: (readable: AtscriptDbReadable, prefix?: string) =>
 declare const validationErrorTransform: () => moost.TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, validationErrorTransform };
+//#region src/actions/types.d.ts
+/**
+ * Options accepted by `@DbAction(name, opts?)`. Structurally derived from
+ * {@link TDbActionInfo} so every addition to the wire shape automatically
+ * propagates here. Fields owned by the framework (`name`, `level`, `processor`,
+ * `value`) are excluded — `name` comes from the decorator argument, `level` is
+ * inferred from `@DbActionPK*` usage, `processor` is fixed to `'backend'` for
+ * method-decorator actions, and `value` is filled from the `@Post` path.
+ */
+type DbActionOpts = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value">>;
+interface DbActionsEntryCommon {
+  label: string;
+  level: TDbActionLevel$1;
+  icon?: string;
+  intent?: TDbActionIntent$1;
+  description?: string;
+  order?: number;
+  default?: boolean;
+  promptText?: string;
+}
+/**
+ * Class-level dict entry. `value` semantics by processor:
+ *
+ * - `'navigate'` — REQUIRED, non-empty. The URL template (with `$1` substituted client-side).
+ * - `'backend'`  — REQUIRED, non-empty. The full HTTP POST path the UI client should invoke.
+ *   For row/rows entries the dev-supplied path MUST point to a `@Post`-bound
+ *   handler accepting the PK-shaped JSON body (single PK scalar / composite
+ *   object / array thereof) — typically a method using `@DbActionPK()` or
+ *   `@DbActionPKs()`. The meta builder does NOT validate this.
+ * - `'custom'`   — `value` is forbidden in the entry; the meta builder fills it
+ *   with the dict key.
+ */
+type TDbActionsEntry = (DbActionsEntryCommon & {
+  processor: "navigate";
+  value: string;
+}) | (DbActionsEntryCommon & {
+  processor: "custom";
+  value?: never;
+}) | (DbActionsEntryCommon & {
+  processor: "backend";
+  value: string;
+});
+/** Distributes `Omit` across the discriminated union members. */
+type DistributiveOmit<T, K extends keyof T> = T extends T ? Omit<T, K> : never;
+/** Same as {@link TDbActionsEntry} but without the `level` field — used by the level-pinned shortcuts. */
+type TDbActionsEntryUnpinned = DistributiveOmit<TDbActionsEntry, "level">;
+//#endregion
+//#region src/actions/db-action.decorator.d.ts
+/**
+ * Mark a controller method as a database action surfaced via `/meta`.
+ *
+ * Metadata-only — pair with `@Post(...)` for Moost to bind the route. The
+ * meta builder reads this metadata plus the bound POST path lazily and
+ * emits the action with `processor: 'backend'`. Order vs.
+ * `@DbActionDefault()` does not matter — both merge into the same slot.
+ *
+ * @example
+ * ```ts
+ * @Post('actions/block')
+ * @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
+ * async blockUser(@DbActionPK() id: string) { ... }
+ * ```
+ */
+declare function DbAction(name: string, opts?: DbActionOpts): MethodDecorator;
+//#endregion
+//#region src/actions/db-action-default.decorator.d.ts
+/**
+ * Sugar that flips `default: true` on the same method's `@DbAction` metadata.
+ * Equivalent to passing `opts.default = true`. Decorator order does not matter.
+ */
+declare function DbActionDefault(): MethodDecorator;
+//#endregion
+//#region src/actions/db-action-pk.decorator.d.ts
+/**
+ * Parameter resolver that reads the primary key from the JSON request body
+ * and validates it against the bound table's PK schema.
+ *
+ * - Single-field PK → JSON-encoded scalar (`"abc"`, `42`, `true`).
+ * - Composite PK → JSON object with all PK fields.
+ *
+ * Validation is strict — no type coercion. Mismatches throw a
+ * `ValidatorError` which the existing validation interceptor surfaces as
+ * HTTP 400 with the same envelope as DTO failures.
+ *
+ * Marks the param so {@link discoverActions} can infer the action's `level`
+ * as `'row'`.
+ */
+declare function DbActionPK(): ParameterDecorator;
+//#endregion
+//#region src/actions/db-action-pks.decorator.d.ts
+/**
+ * Parameter resolver that reads a JSON array of primary keys from the request
+ * body and validates each entry against the bound table's PK schema.
+ *
+ * - Scalar PK → JSON array of scalars (`["a","b","c"]`).
+ * - Composite PK → JSON array of objects.
+ *
+ * Validation is strict — no type coercion. Marks the param so
+ * {@link discoverActions} can infer the action's `level` as `'rows'`.
+ */
+declare function DbActionPKs(): ParameterDecorator;
+//#endregion
+//#region src/actions/db-actions.decorator.d.ts
+/**
+ * Declare class-level actions on a controller. Entries are flat dicts with
+ * `processor: 'navigate' | 'custom' | 'backend'` matching the `/meta` wire
+ * shape (see {@link TDbActionsEntry}). Each entry MUST specify `level`. Use
+ * the level-pinned shortcuts (`@DbTableActions`, `@DbRowActions`,
+ * `@DbRowsActions`) to avoid repeating `level`.
+ *
+ * The dictionary key serves as the action `name`. Entries do NOT bind any
+ * HTTP route — the meta builder surfaces them in `/meta` only. For
+ * `processor: 'backend'`, the dev-supplied `value` MUST point to a real
+ * `@Post`-bound endpoint accepting the level-determined body shape.
+ *
+ * Multiple `@DbActions` (and shortcut) decorators on the same class
+ * accumulate.
+ */
+declare function DbActions(dict: Record<string, TDbActionsEntry>): ClassDecorator;
+/** Sugar for `@DbActions` with `level: 'table'` injected into each entry. */
+declare function DbTableActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+/** Sugar for `@DbActions` with `level: 'row'` injected into each entry. */
+declare function DbRowActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+/** Sugar for `@DbActions` with `level: 'rows'` injected into each entry. */
+declare function DbRowsActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+//#endregion
+//#region src/actions/discover.d.ts
+/**
+ * Discover all actions declared on a controller and produce the `/meta` array.
+ * Reads class + method metadata via `getMoostMate()` and resolves bound POST
+ * paths through the Moost controller overview.
+ *
+ * Result is memoized per controller constructor — discovery walks every
+ * handler entry and reads decorator metadata, which is wasted work to repeat
+ * across instances.
+ */
+declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionInfo$1[];
+//#endregion
+//#region src/actions/pk-validation.d.ts
+/**
+ * Minimal shape required to validate PKs against a table — supplied by the
+ * controller's underlying `AtscriptDbReadable`/`AtscriptDbTable`.
+ */
+interface PkValidationSource {
+  primaryKeys: readonly string[];
+  fieldDescriptors: readonly TDbFieldMeta[];
+}
+//#endregion
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, PkValidationSource, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, TDbActionsEntry, TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, validationErrorTransform };

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
 import * as _uniqu_url0 from "@uniqu/url";
-import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
 
 //#region src/as-readable.controller.d.ts
 /**
@@ -123,8 +123,16 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * Builds the `/meta` payload. Override in subclasses to populate source-specific
    * fields. Defaults return a minimal envelope with the serialized type and the
    * read-only flag; value-help dicts populate their capability hints here.
+   * Subclasses that fully replace the envelope must call {@link buildActions}
+   * directly so `@DbAction*` decorators still surface.
    */
   protected buildMetaResponse(): Promise<TMetaResponse>;
+  /**
+   * Discovers `@DbAction*` and `@DbActions`-style class metadata on this
+   * controller and produces the `actions` array. Returns `[]` for value-help
+   * controllers — see {@link AsValueHelpController#buildMetaResponse}.
+   */
+  protected buildActions(): TDbActionInfo$1[];
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -280,6 +288,12 @@ interface ValueHelpQuery<T> {
  * requests against them. Subclasses that need a backend gate should compose
  * one of their own (see {@link AsDbReadableController} for the
  * `@db.column.filterable` / `@db.column.sortable` pattern).
+ *
+ * **Actions are intentionally NOT supported on value-help controllers.** The
+ * `/meta` payload still includes `actions: []` for shape uniformity, and any
+ * `@DbAction*` / `@DbActions*` decorators applied here are silently ignored.
+ * Value-help is for FK pickers and dictionary surfaces — adding row/table
+ * actions there would muddy the contract.
  */
 declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
   /** Per-prop metadata map of the bound interface; eagerly built once. */
@@ -331,6 +345,7 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
    * these flags at request time.
    */
   protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildActions(): never[];
 }
 //#endregion
 //#region src/as-json-value-help.controller.d.ts
@@ -436,4 +451,152 @@ declare const ViewController: (readable: AtscriptDbReadable, prefix?: string) =>
 declare const validationErrorTransform: () => moost.TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
 //#endregion
-export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, validationErrorTransform };
+//#region src/actions/types.d.ts
+/**
+ * Options accepted by `@DbAction(name, opts?)`. Structurally derived from
+ * {@link TDbActionInfo} so every addition to the wire shape automatically
+ * propagates here. Fields owned by the framework (`name`, `level`, `processor`,
+ * `value`) are excluded — `name` comes from the decorator argument, `level` is
+ * inferred from `@DbActionPK*` usage, `processor` is fixed to `'backend'` for
+ * method-decorator actions, and `value` is filled from the `@Post` path.
+ */
+type DbActionOpts = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value">>;
+interface DbActionsEntryCommon {
+  label: string;
+  level: TDbActionLevel$1;
+  icon?: string;
+  intent?: TDbActionIntent$1;
+  description?: string;
+  order?: number;
+  default?: boolean;
+  promptText?: string;
+}
+/**
+ * Class-level dict entry. `value` semantics by processor:
+ *
+ * - `'navigate'` — REQUIRED, non-empty. The URL template (with `$1` substituted client-side).
+ * - `'backend'`  — REQUIRED, non-empty. The full HTTP POST path the UI client should invoke.
+ *   For row/rows entries the dev-supplied path MUST point to a `@Post`-bound
+ *   handler accepting the PK-shaped JSON body (single PK scalar / composite
+ *   object / array thereof) — typically a method using `@DbActionPK()` or
+ *   `@DbActionPKs()`. The meta builder does NOT validate this.
+ * - `'custom'`   — `value` is forbidden in the entry; the meta builder fills it
+ *   with the dict key.
+ */
+type TDbActionsEntry = (DbActionsEntryCommon & {
+  processor: "navigate";
+  value: string;
+}) | (DbActionsEntryCommon & {
+  processor: "custom";
+  value?: never;
+}) | (DbActionsEntryCommon & {
+  processor: "backend";
+  value: string;
+});
+/** Distributes `Omit` across the discriminated union members. */
+type DistributiveOmit<T, K extends keyof T> = T extends T ? Omit<T, K> : never;
+/** Same as {@link TDbActionsEntry} but without the `level` field — used by the level-pinned shortcuts. */
+type TDbActionsEntryUnpinned = DistributiveOmit<TDbActionsEntry, "level">;
+//#endregion
+//#region src/actions/db-action.decorator.d.ts
+/**
+ * Mark a controller method as a database action surfaced via `/meta`.
+ *
+ * Metadata-only — pair with `@Post(...)` for Moost to bind the route. The
+ * meta builder reads this metadata plus the bound POST path lazily and
+ * emits the action with `processor: 'backend'`. Order vs.
+ * `@DbActionDefault()` does not matter — both merge into the same slot.
+ *
+ * @example
+ * ```ts
+ * @Post('actions/block')
+ * @DbAction('block', { label: 'Block', icon: 'i-as-block', intent: 'negative' })
+ * async blockUser(@DbActionPK() id: string) { ... }
+ * ```
+ */
+declare function DbAction(name: string, opts?: DbActionOpts): MethodDecorator;
+//#endregion
+//#region src/actions/db-action-default.decorator.d.ts
+/**
+ * Sugar that flips `default: true` on the same method's `@DbAction` metadata.
+ * Equivalent to passing `opts.default = true`. Decorator order does not matter.
+ */
+declare function DbActionDefault(): MethodDecorator;
+//#endregion
+//#region src/actions/db-action-pk.decorator.d.ts
+/**
+ * Parameter resolver that reads the primary key from the JSON request body
+ * and validates it against the bound table's PK schema.
+ *
+ * - Single-field PK → JSON-encoded scalar (`"abc"`, `42`, `true`).
+ * - Composite PK → JSON object with all PK fields.
+ *
+ * Validation is strict — no type coercion. Mismatches throw a
+ * `ValidatorError` which the existing validation interceptor surfaces as
+ * HTTP 400 with the same envelope as DTO failures.
+ *
+ * Marks the param so {@link discoverActions} can infer the action's `level`
+ * as `'row'`.
+ */
+declare function DbActionPK(): ParameterDecorator;
+//#endregion
+//#region src/actions/db-action-pks.decorator.d.ts
+/**
+ * Parameter resolver that reads a JSON array of primary keys from the request
+ * body and validates each entry against the bound table's PK schema.
+ *
+ * - Scalar PK → JSON array of scalars (`["a","b","c"]`).
+ * - Composite PK → JSON array of objects.
+ *
+ * Validation is strict — no type coercion. Marks the param so
+ * {@link discoverActions} can infer the action's `level` as `'rows'`.
+ */
+declare function DbActionPKs(): ParameterDecorator;
+//#endregion
+//#region src/actions/db-actions.decorator.d.ts
+/**
+ * Declare class-level actions on a controller. Entries are flat dicts with
+ * `processor: 'navigate' | 'custom' | 'backend'` matching the `/meta` wire
+ * shape (see {@link TDbActionsEntry}). Each entry MUST specify `level`. Use
+ * the level-pinned shortcuts (`@DbTableActions`, `@DbRowActions`,
+ * `@DbRowsActions`) to avoid repeating `level`.
+ *
+ * The dictionary key serves as the action `name`. Entries do NOT bind any
+ * HTTP route — the meta builder surfaces them in `/meta` only. For
+ * `processor: 'backend'`, the dev-supplied `value` MUST point to a real
+ * `@Post`-bound endpoint accepting the level-determined body shape.
+ *
+ * Multiple `@DbActions` (and shortcut) decorators on the same class
+ * accumulate.
+ */
+declare function DbActions(dict: Record<string, TDbActionsEntry>): ClassDecorator;
+/** Sugar for `@DbActions` with `level: 'table'` injected into each entry. */
+declare function DbTableActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+/** Sugar for `@DbActions` with `level: 'row'` injected into each entry. */
+declare function DbRowActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+/** Sugar for `@DbActions` with `level: 'rows'` injected into each entry. */
+declare function DbRowsActions(dict: Record<string, TDbActionsEntryUnpinned>): ClassDecorator;
+//#endregion
+//#region src/actions/discover.d.ts
+/**
+ * Discover all actions declared on a controller and produce the `/meta` array.
+ * Reads class + method metadata via `getMoostMate()` and resolves bound POST
+ * paths through the Moost controller overview.
+ *
+ * Result is memoized per controller constructor — discovery walks every
+ * handler entry and reads decorator metadata, which is wasted work to repeat
+ * across instances.
+ */
+declare function discoverActions(controllerCtor: Function, app: Moost, logger: TConsoleBase): TDbActionInfo$1[];
+//#endregion
+//#region src/actions/pk-validation.d.ts
+/**
+ * Minimal shape required to validate PKs against a table — supplied by the
+ * controller's underlying `AtscriptDbReadable`/`AtscriptDbTable`.
+ */
+interface PkValidationSource {
+  primaryKeys: readonly string[];
+  fieldDescriptors: readonly TDbFieldMeta[];
+}
+//#endregion
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionOpts, DbActionPK, DbActionPKs, DbActions, DbRowActions, DbRowsActions, DbTableActions, type PkValidationSource, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, validationErrorTransform };