@atscript/moost-db 0.1.56 → 0.1.58

package/dist/index.d.mts

@@ -4,7 +4,8 @@ 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, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import * as _wooksjs_event_core0 from "@wooksjs/event-core";
 
 //#region src/as-readable.controller.d.ts
 /**
@@ -88,11 +89,6 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * to customise.
    */
   protected getSerializeOptions(): TSerializeOptions;
-  /**
-   * Whether this controller is read-only (no write endpoints).
-   * Returns `true` by default; {@link AsDbController} overrides to `false`.
-   */
-  protected _isReadOnly(): boolean;
   private _queryControlsValidator?;
   private _pagesControlsValidator?;
   private _getOneControlsValidator?;
@@ -111,28 +107,39 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
   protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
-   * **GET /meta** — returns the bound interface's metadata envelope.
-   *
-   * Base implementation delegates to {@link buildMetaResponse}, which subclasses
-   * override to add source-specific fields (relations, searchable flags, etc.).
-   * The response is cached on the instance; async overrides must cache any
-   * extra enrichment themselves.
+   * **GET /meta** — returns the bound interface's metadata envelope. The
+   * static envelope is cached; {@link applyMetaOverlay} runs per request so
+   * subclasses can prune the response by principal.
    */
   meta(): Promise<TMetaResponse>;
   /**
    * 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.
+   * fields. Subclasses that fully replace the envelope must call
+   * {@link buildActions} and {@link buildCrud} directly so `@DbAction*`
+   * decorators and CRUD permissions still surface.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): 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[];
+  /**
+   * Declares the built-in CRUD operations this controller exposes. Subclasses
+   * override to add their keys; the bare base only exposes `/meta`. See
+   * `docs/http/permissions.md` for the wire shape and overlay rules.
+   */
+  protected buildCrud(): TCrudPermissions$1;
+  /**
+   * Per-request overlay applied to the cached `/meta` envelope. Default no-op.
+   * Subclasses may shallow-clone and prune `crud` keys, `crud[op]` arrays, or
+   * `actions[]` based on the current request principal (read via Moost
+   * composables). The cached envelope MUST NOT be mutated — see
+   * `docs/http/permissions.md` for the full contract, including the
+   * "discoverability only" caveat.
+   */
+  protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -204,7 +211,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * vector-searchable flags, field-descriptor-derived filter/sort hints, and
    * the configured primary keys.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
+  protected buildCrud(): TCrudPermissions$1;
 }
 //#endregion
 //#region src/as-db.controller.d.ts
@@ -222,7 +230,7 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   /** Reference to the underlying table (typed for write access). */
   protected get table(): AtscriptDbTable<T>;
   constructor(table: AtscriptDbTable<T>, app: Moost);
-  protected _isReadOnly(): boolean;
+  protected buildCrud(): TCrudPermissions$1;
   /**
    * Intercepts write operations. Return `undefined` to abort.
    * May be async (e.g. to enrich payloads from session / permissions).
@@ -344,8 +352,9 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
    * client picker UI (which controls to render); the server does not enforce
    * these flags at request time.
    */
-  protected buildMetaResponse(): Promise<TMetaResponse>;
+  protected buildMetaResponse(): TMetaResponse;
   protected buildActions(): never[];
+  protected buildCrud(): TCrudPermissions$1;
 }
 //#endregion
 //#region src/as-json-value-help.controller.d.ts
@@ -452,15 +461,72 @@ declare const validationErrorTransform: () => moost.TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
 //#endregion
 //#region src/actions/types.d.ts
+/** `'rows'`-level batch policy — controls whether failing rows reject or are filtered out. */
+type TOnDisabledRows = "reject" | "skip";
 /**
  * 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.
+ * {@link TDbActionInfo} so every wire-shape addition propagates here, EXCEPT
+ * `disabled` and `requiredFields` which differ in shape between decorator
+ * opts (function / dev-supplied) and the wire (string / forwarded verbatim).
+ *
+ * Fields owned by the framework (`name`, `level`, `processor`, `value`) are
+ * excluded — `name` comes from the decorator argument, `level` is inferred
+ * from `@DbActionPK*` / `@DbActionRow*` usage, `processor` is fixed to
+ * `'backend'` for method-decorator actions, and `value` is filled from the
+ * `@Post` path.
+ *
+ * Generic over `TRow` so the `disabled` predicate can be type-checked against
+ * the bound table's row shape. Note: TS decorators cannot infer `TRow` from
+ * the enclosing controller's class generic, so the dev MUST annotate the row
+ * arg explicitly (`(row: Order) => …`) to get type-checking.
  */
-type DbActionOpts = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value">>;
+type DbActionOpts<TRow = unknown> = Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled" | "requiredFields">> & {
+  /**
+   * Per-row gate predicate. Truthy → action is disabled for that row.
+   * Server enforces (via the gate interceptor); UI evaluates the same
+   * expression to grey-out / hide the button.
+   *
+   * The dev MUST annotate the row arg explicitly (`(row: Order) => …`) —
+   * TS decorators cannot infer `TRow` from the enclosing class generic.
+   */
+  disabled?: (row: TRow) => boolean;
+  /**
+   * Optional dot-notation field paths the UI should union into `$select`.
+   * Plain `string[]` in v1.
+   *
+   * TODO: upgrade to typed `PathOf<TRow>[]` in a follow-up — the recursive
+   * type pattern is finicky for nested objects/arrays/optionals and isn't
+   * blocking v1.
+   *
+   * When omitted, the UI parses the stringified `disabled` itself to extract
+   * row-property accesses. When present, the UI uses this list verbatim — the
+   * server does NOT auto-derive or merge.
+   */
+  requiredFields?: string[];
+  /**
+   * `'rows'`-level batch policy. Default `'reject'`.
+   *
+   * - `'reject'`: evaluate every row (FULL scan, NOT short-circuit) before
+   *   throwing; if any row fails, the error body lists ALL failing PKs;
+   *   handler not invoked.
+   * - `'skip'`: filter cached rows + cached PKs to passing-only;
+   *   zero survivors → reject. Handler runs against the survivors.
+   *
+   * Ignored for `'row'` and `'table'` level actions.
+   */
+  onDisabledRows?: TOnDisabledRows;
+  /**
+   * Bound table reference. REQUIRED on non-`AsDbReadableController` classes
+   * when `disabled` is set OR a `@DbActionRow*` parameter is declared.
+   *
+   * Silently ignored on `AsDbReadableController` subclasses (which include
+   * `AsDbController`) — the bound table from the controller wins; the
+   * gate / thin interceptor probes `instanceof AsDbReadableController` and
+   * populates the bound-table slot from `controller.readable` before
+   * checking `opts.table`.
+   */
+  table?: AtscriptDbTable<any>;
+};
 interface DbActionsEntryCommon {
   label: string;
   level: TDbActionLevel$1;
@@ -469,7 +535,28 @@ interface DbActionsEntryCommon {
   description?: string;
   order?: number;
   default?: boolean;
-  promptText?: string;
+  /** Mirrors {@link TDbActionInfo.promptText} — singular/plural via tuple. */
+  promptText?: string | [string, string];
+  /** Mirrors {@link TDbActionInfo.shortcut} — single-character UI hint. */
+  shortcut?: string;
+  /**
+   * UI-only gate predicate (class-level dict entries do NOT register a
+   * server-side gate interceptor — the dict entry's `value` may point at an
+   * endpoint in another controller). The wire emits `fn.toString()` so the
+   * UI can grey-out / hide the button. For symmetric server enforcement at
+   * the actual `@Post`-bound handler, declare `@DbAction(name, { disabled })`
+   * on that handler too.
+   *
+   * Not generic over `TRow` — devs type the row arg explicitly.
+   */
+  disabled?: (row: any) => boolean;
+  /** Same as method-decorator `requiredFields`. UI hint, not server-derived. */
+  requiredFields?: string[];
+  /**
+   * Reserved for future API symmetry with method-decorator opts. Currently a
+   * no-op for class-level dict entries (no gate interceptor registers).
+   */
+  onDisabledRows?: TOnDisabledRows;
 }
 /**
  * Class-level dict entry. `value` semantics by processor:
@@ -500,21 +587,13 @@ 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) { ... }
- * ```
+ * Mark a controller method as a database action surfaced via `/meta`. Writes
+ * `MOOST_DB_ACTION` metadata and registers a Moost interceptor when needed
+ * (gate when `disabled` is set, thin bound-table injector when only
+ * `@DbActionRow*` is present). Stacking two `@DbAction` on the same method
+ * is undefined and emits a warning.
  */
-declare function DbAction(name: string, opts?: DbActionOpts): MethodDecorator;
+declare function DbAction<TRow = unknown>(name: string, opts?: DbActionOpts<TRow>): MethodDecorator;
 //#endregion
 //#region src/actions/db-action-default.decorator.d.ts
 /**
@@ -537,6 +616,10 @@ declare function DbActionDefault(): MethodDecorator;
  *
  * Marks the param so {@link discoverActions} can infer the action's `level`
  * as `'row'`.
+ *
+ * Implementation note: the resolver is a thin reader of the cached PK wook
+ * — validation logic lives in the wook factory, which runs once per request
+ * regardless of how many readers consume the value.
  */
 declare function DbActionPK(): ParameterDecorator;
 //#endregion
@@ -550,9 +633,37 @@ declare function DbActionPK(): ParameterDecorator;
  *
  * Validation is strict — no type coercion. Marks the param so
  * {@link discoverActions} can infer the action's `level` as `'rows'`.
+ *
+ * In `'rows'` skip mode the resolved value reflects the gate interceptor's
+ * filtered subset (the cached PK slot is overwritten in place); see
+ * {@link dbActionPksSlot} for precedence details.
  */
 declare function DbActionPKs(): ParameterDecorator;
 //#endregion
+//#region src/actions/db-action-row.decorator.d.ts
+/**
+ * Parameter decorator that injects the row whose PK was supplied in the
+ * request body. Reads from the cached row wook (fetched once per request,
+ * shared with the gate interceptor when `disabled` is set).
+ *
+ * Marks the param so {@link discoverActions} infers the action's `level` as
+ * `'row'`. Co-occurrence with `@DbActionRows()` (or any multi-cardinality
+ * decorator) drops the action with a warning.
+ *
+ * In `'skip'` mode this returns the gate's filtered row; the original
+ * request-body row is not retrievable.
+ */
+declare function DbActionRow(): ParameterDecorator;
+/**
+ * Parameter decorator that injects the rows-array fetched by primary keys
+ * from the request body. Reads from the cached row-array wook.
+ *
+ * Marks the param so {@link discoverActions} infers the action's `level` as
+ * `'rows'`. In `'rows'` + `'skip'` mode the resolved value contains only the
+ * gate's surviving rows.
+ */
+declare function DbActionRows(): ParameterDecorator;
+//#endregion
 //#region src/actions/db-actions.decorator.d.ts
 /**
  * Declare class-level actions on a controller. Entries are flat dicts with
@@ -599,4 +710,65 @@ interface PkValidationSource {
   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 };
+//#region src/actions/pk-cache.d.ts
+declare const useDbActionPk: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+declare const useDbActionPks: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown[]>;
+}>;
+//#endregion
+//#region src/actions/row-cache.d.ts
+declare const useDbActionRow: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown>;
+}>;
+declare const useDbActionRows: _wooksjs_event_core0.WookComposable<{
+  load: () => Promise<unknown[]>;
+}>;
+//#endregion
+//#region src/actions/action-disabled-error.d.ts
+/**
+ * Wire-body shape for server-side gate rejections. The `name` discriminator
+ * lets `@atscript/db-client` recognise the response and construct the typed
+ * `ActionDisabledError` subclass. The shape extends Moost's standard
+ * `ServerError` envelope (`{ message, statusCode, errors? }`) with three
+ * additional fields:
+ *
+ * - `name: 'ActionDisabledError'` — discriminator the client matches.
+ * - `action` — the `@DbAction` name that rejected the request.
+ * - `pk?` — present only for `'row'`-level rejections.
+ * - `pks?` — present only for `'rows'`-level rejections.
+ *
+ * `message` is populated with a human-readable string so generic
+ * `ClientError` consumers (which read `body.message`) still get something
+ * useful without typed-catch dispatch.
+ */
+interface ActionDisabledErrorBody {
+  name: "ActionDisabledError";
+  message: string;
+  statusCode: 409;
+  action: string;
+  pk?: unknown;
+  pks?: unknown[];
+}
+/**
+ * Thrown by the gate interceptor when `disabled` returns truthy. Composes
+ * with Moost's existing error mapper to produce HTTP 409 with the wire body
+ * defined by {@link ActionDisabledErrorBody}.
+ *
+ * - `'row'`-level rejection: pass `(action, pk)` — the body emits `pk`.
+ * - `'rows'`-level rejection: pass `(action, undefined, pks)` — the body
+ *   emits `pks` (the FULL list of failing PKs in reject mode; the FULL list
+ *   of request PKs in skip mode with zero survivors).
+ */
+declare class ActionDisabledError extends HttpError<ActionDisabledErrorBody> {
+  name: string;
+  constructor(action: string, pk?: unknown, pks?: unknown[]);
+}
+//#endregion
+//#region src/permissions/crud-controls.d.ts
+declare const QUERY_CONTROLS: readonly string[];
+declare const PAGES_CONTROLS: readonly string[];
+declare const ONE_CONTROLS: readonly string[];
+//#endregion
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, DbAction, DbActionDefault, type DbActionOpts, DbActionPK, DbActionPKs, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, ONE_CONTROLS, PAGES_CONTROLS, type PkValidationSource, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, discoverActions, useDbActionPk, useDbActionPks, useDbActionRow, useDbActionRows, validationErrorTransform };