@decaf-ts/ui-decorators 0.18.0 → 0.19.0

package/lib/types/user-requests/UserRequestHandler.d.mts

@@ -0,0 +1,117 @@
+/**
+ * @module ui-decorators/user-requests/UserRequestHandler
+ * @summary Service-based base class for user request handlers.
+ * @description No Angular or DOM imports — safe for pure-Node (backend) bundles.
+ *
+ * Handlers extend `Service`, receive a rendering-engine facade as a
+ * `protected readonly` property and implement `handle`, either returning the
+ * resolved value or throwing (a `CancelledError` when the user cancels
+ * mid-request). Lookup and dispatch are static: `@userRequest(reference)`
+ * records the class as metadata and `UserRequestHandler.getHandler(reference)`
+ * / `UserRequestHandler.handle(request, renderingEngine)` resolve and run it,
+ * so no process-wide registry instance is needed.
+ */
+import { Context, ContextFlags, ContextualArgs, FlagsOf, LoggerOf, MaybeContextualArg, MethodOrOperation, Service } from "@decaf-ts/core";
+import { Constructor } from "@decaf-ts/decoration";
+import type { RenderingFacade, UserRequest, UserRequestHandlerMetadata } from "./types.d.mts";
+/**
+ * @description Result of `UserRequestHandler.logCtx(...)`. Extends the
+ * standard `{ log, ctx, ctxArgs }` surface with the exact `RenderingEngine`
+ * methods a handler needs (`modal`/`toast`/`spinner`/`router`) wrapping the
+ * rendering engine handed to the handler constructor. The keys mirror the
+ * underlying engine methods without a `get` prefix, and no duplicated
+ * `UserRequest*` rendering types are introduced.
+ * @summary Contextual surface returned by `UserRequestHandler.logCtx(*, *, true)`.
+ * @template C The decaf context the handler service runs under.
+ * @template ARGS The contextual argument tuple passed to the call.
+ */
+export interface UserRequestLogContext<C extends Context<ContextFlags<any>> = Context<ContextFlags<any>>, ARGS extends any[] = any[]> {
+    log: LoggerOf<C>;
+    ctx: C;
+    ctxArgs: ContextualArgs<C, ARGS>;
+    readonly modal: RenderingFacade["getModal"];
+    readonly toast: RenderingFacade["getToast"];
+    readonly spinner: RenderingFacade["getSpinner"];
+    readonly router: RenderingFacade["router"];
+}
+/**
+ * @description Abstract base class for user request handlers.
+ *
+ * Handler methods follow the core `Service` golden rules: `handle` (and the
+ * lifecycle helpers `getInput`/`cancel`) accept rest contextual args
+ * (`...args: ContextualArgs<C>`) and obtain their `{ log, ctx, ctxArgs }` via
+ * `this.logCtx([request, ...args], this.handle, true)` — entry and resolution
+ * via `log.info`, transitions via `log.verbose`, payload details via
+ * `log.debug` and failures/cancellations via `log.error`. A `CancelledError`
+ * is thrown when the user cancels mid-request. `handle` is the one async
+ * method handlers override, returning the resolved value or throwing.
+ * @summary Service-based base class implementing the user request lifecycle.
+ * @template T The resolved payload type the handler returns.
+ * @template C The decaf context the service runs under.
+ */
+export declare abstract class UserRequestHandler<T = unknown, C extends Context<ContextFlags<any>> = Context<ContextFlags<any>>> extends Service<C> {
+    protected readonly renderingEngine: RenderingFacade;
+    private currentModal?;
+    private cancelled;
+    private submitted?;
+    private dismissed?;
+    /**
+     * @description Creates a handler bound to the given rendering-engine facade.
+     * The facade is the only external dependency: no context/resolver
+     * indirection.
+     * @param {RenderingFacade} renderingEngine The rendering-engine surface the
+     * handler drives (modal, toast, spinner and router).
+     */
+    protected constructor(renderingEngine: RenderingFacade);
+    /**
+     * @description Resolves the handler class registered for the given request
+     * reference via `Metadata`. Handlers are recorded by the `@userRequest`
+     * decorator under `USER_REQUEST_KEY`.
+     * @param {string} reference The request id/type the handler is registered
+     * for.
+     * @return {.Constructor<UserRequestHandler> | undefined}
+     * The registered handler constructor, or `undefined` when unknown.
+     */
+    static getHandler(reference: string): Constructor<UserRequestHandler> | undefined;
+    /**
+     * @description Reads the `@userRequest` metadata recorded on a handler class
+     * via `Metadata`.
+     * @param {object} target The handler class to inspect.
+     * @return {UserRequestHandlerMetadata | undefined} The recorded metadata
+     * `{ reference }`, or `undefined` when the class is not decorated.
+     */
+    static getMetadata(target: object): UserRequestHandlerMetadata | undefined;
+    static handle<T = unknown>(request: UserRequest<T>, renderingEngine: RenderingFacade): Promise<T>;
+    protected getInput(request: UserRequest<T>, ...args: ContextualArgs<C>): Promise<T>;
+    private awaitDismissal;
+    cancel(...args: ContextualArgs<C> | []): Promise<void>;
+    abstract handle(request: UserRequest<T>, ...args: ContextualArgs<C>): Promise<T>;
+    /**
+     * @description Logging + rendering-engine methods for a call. Mirrors the
+     * `Service` `logCtx` contract and exposes `modal`/`toast`/`spinner`/`router`
+     * getters wrapping the rendering engine.
+     * @param {MaybeContextualArg<C, ARGS>} args Contextual args (context at the
+     * end, or pre-args plus context).
+     * @param {METHOD} operation The operation the context is created for.
+     * @param {boolean} allowCreate Whether a context is created when none is
+     * provided.
+     * @param {Partial<FlagsOf<CONTEXT>>} overrides Optional flag overrides.
+     * @return {UserRequestLogContext<C, ARGS> | Promise<UserRequestLogContext<C, ARGS>>}
+     * The contextual surface (or a promise of it when `allowCreate` is true).
+     * @template C The decaf context the service runs under.
+     * @template ARGS The contextual argument tuple passed to the call.
+     * @template CONTEXT The context type to promote to when creating one.
+     * @template METHOD The operation the context is created for.
+     */
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<C, ARGS>, operation: METHOD): UserRequestLogContext<C, ARGS>;
+    protected logCtx<CONTEXT extends Context<any> = C, ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<CONTEXT, ARGS>, operation: METHOD, allowCreate: false, overrides?: Partial<FlagsOf<CONTEXT>>): UserRequestLogContext<C, ARGS>;
+    protected logCtx<CONTEXT extends Context<any> = C, ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<CONTEXT, ARGS>, operation: METHOD, allowCreate: true, overrides?: Partial<FlagsOf<CONTEXT>>): Promise<UserRequestLogContext<C, ARGS>>;
+    /**
+     * @description Decorates the base contextual surface with the rendering
+     * engine methods exposed as `modal`/`toast`/`spinner`/`router` bound getters.
+     * @return {UserRequestLogContext<C, ARGS>} The decorated contextual surface.
+     * @template C The decaf context the service runs under.
+     * @template ARGS The contextual argument tuple passed to the call.
+     */
+    private wrapLogContext;
+}

package/lib/types/user-requests/constants.d.cts

@@ -0,0 +1,17 @@
+/**
+ * @module ui-decorators/user-requests/constants
+ * @summary Metadata keys for the User Request Resolution Engine.
+ */
+/**
+ * @description Metadata key under which user request handlers are registered
+ * and resolved.
+ * @summary The `@userRequest(reference)` decorator stores both the handler
+ * reference and the decorating metadata under this key, and
+ * `UserRequestHandler.getHandler` / `UserRequestHandler.getMetadata` read it
+ * back. The key is scoped to the User Request Resolution Engine to avoid
+ * colliding with other reflection metadata.
+ * @const USER_REQUEST_KEY
+ * @type {string}
+ * @readonly
+ */
+export declare const USER_REQUEST_KEY = "user-requests.handler";

package/lib/types/user-requests/constants.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @module ui-decorators/user-requests/constants
+ * @summary Metadata keys for the User Request Resolution Engine.
+ */
+/**
+ * @description Metadata key under which user request handlers are registered
+ * and resolved.
+ * @summary The `@userRequest(reference)` decorator stores both the handler
+ * reference and the decorating metadata under this key, and
+ * `UserRequestHandler.getHandler` / `UserRequestHandler.getMetadata` read it
+ * back. The key is scoped to the User Request Resolution Engine to avoid
+ * colliding with other reflection metadata.
+ * @const USER_REQUEST_KEY
+ * @type {string}
+ * @readonly
+ */
+export declare const USER_REQUEST_KEY = "user-requests.handler";

package/lib/types/user-requests/decorators.d.cts

@@ -0,0 +1,22 @@
+/**
+ * @module ui-decorators/user-requests/decorators
+ * @summary `@userRequest(reference)` class decorator.
+ * @description No Angular or DOM imports — safe for pure-Node (backend)
+ * bundles. Registration is metadata-based: the decorator records the handler
+ * class under `USER_REQUEST_KEY` and the static `UserRequestHandler` methods
+ * resolve and dispatch it, so no process-wide registry is involved.
+ */
+/**
+ * @description Registers a handler class for the given request id/type.
+ *
+ * Mirrors `core/src/migrations/decorators.ts`:
+ * `Decoration.for(KEY).define({ decorator, args }).apply()` plus
+ * `Metadata.set(USER_REQUEST_KEY, reference, original)` so the class is
+ * retrievable by id via metadata — `UserRequestHandler.getHandler(reference)`
+ * reads it back and `UserRequestHandler.handle(request, renderingEngine)`
+ * dispatches it — and a class-level `metadata(...)` payload for
+ * introspection (`UserRequestHandler.getMetadata(target)`).
+ * @param {string} reference The request id/type the handler is registered for.
+ * @return {ClassDecorator} The class decorator to apply.
+ */
+export declare function userRequest(reference: string): ClassDecorator;

package/lib/types/user-requests/decorators.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @module ui-decorators/user-requests/decorators
+ * @summary `@userRequest(reference)` class decorator.
+ * @description No Angular or DOM imports — safe for pure-Node (backend)
+ * bundles. Registration is metadata-based: the decorator records the handler
+ * class under `USER_REQUEST_KEY` and the static `UserRequestHandler` methods
+ * resolve and dispatch it, so no process-wide registry is involved.
+ */
+/**
+ * @description Registers a handler class for the given request id/type.
+ *
+ * Mirrors `core/src/migrations/decorators.ts`:
+ * `Decoration.for(KEY).define({ decorator, args }).apply()` plus
+ * `Metadata.set(USER_REQUEST_KEY, reference, original)` so the class is
+ * retrievable by id via metadata — `UserRequestHandler.getHandler(reference)`
+ * reads it back and `UserRequestHandler.handle(request, renderingEngine)`
+ * dispatches it — and a class-level `metadata(...)` payload for
+ * introspection (`UserRequestHandler.getMetadata(target)`).
+ * @param {string} reference The request id/type the handler is registered for.
+ * @return {ClassDecorator} The class decorator to apply.
+ */
+export declare function userRequest(reference: string): ClassDecorator;

package/lib/types/user-requests/errors.d.cts

@@ -0,0 +1,18 @@
+/**
+ * @module ui-decorators/user-requests/errors
+ * @summary Decaf error hierarchy for the User Request Resolution Engine.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * @description Error thrown when the user cancels a user request mid-resolution.
+ * Follows the decaf error hierarchy: never a raw `Error`. Compatible with the
+ * validation error signaling used by `@devcerts/decaf` UI facades.
+ * @summary Error thrown when a user request is cancelled.
+ */
+export declare class CancelledError extends InternalError {
+    /**
+     * @param {string | Error | unknown} msg The cancellation message.
+     * @return {CancelledError} A new `CancelledError`.
+     */
+    constructor(msg?: string | Error | unknown);
+}

package/lib/types/user-requests/errors.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @module ui-decorators/user-requests/errors
+ * @summary Decaf error hierarchy for the User Request Resolution Engine.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * @description Error thrown when the user cancels a user request mid-resolution.
+ * Follows the decaf error hierarchy: never a raw `Error`. Compatible with the
+ * validation error signaling used by `@devcerts/decaf` UI facades.
+ * @summary Error thrown when a user request is cancelled.
+ */
+export declare class CancelledError extends InternalError {
+    /**
+     * @param {string | Error | unknown} msg The cancellation message.
+     * @return {CancelledError} A new `CancelledError`.
+     */
+    constructor(msg?: string | Error | unknown);
+}

package/lib/types/user-requests/index.d.cts

@@ -0,0 +1,15 @@
+/**
+ * @module ui-decorators/user-requests
+ * @summary Backend binding surface for the User Request Resolution Engine.
+ * @description Framework-agnostic core of the engine: no Angular or DOM
+ * imports, safe for pure-Node (backend) bundles. Handlers are registered via
+ * `@userRequest(reference)` (metadata) and resolved/dispatched through the
+ * static `UserRequestHandler` methods; example handlers and rendering-engine
+ * mocks live only in the test tree, never under `src`. Frontend bindings live
+ * in `for-angular`.
+ */
+export * from "./constants.d.cts";
+export * from "./errors.d.cts";
+export * from "./types.d.cts";
+export * from "./UserRequestHandler.d.cts";
+export * from "./decorators.d.cts";

package/lib/types/user-requests/index.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @module ui-decorators/user-requests
+ * @summary Backend binding surface for the User Request Resolution Engine.
+ * @description Framework-agnostic core of the engine: no Angular or DOM
+ * imports, safe for pure-Node (backend) bundles. Handlers are registered via
+ * `@userRequest(reference)` (metadata) and resolved/dispatched through the
+ * static `UserRequestHandler` methods; example handlers and rendering-engine
+ * mocks live only in the test tree, never under `src`. Frontend bindings live
+ * in `for-angular`.
+ */
+export * from "./constants.d.mts";
+export * from "./errors.d.mts";
+export * from "./types.d.mts";
+export * from "./UserRequestHandler.d.mts";
+export * from "./decorators.d.mts";

package/lib/types/user-requests/types.d.cts

@@ -0,0 +1,36 @@
+/**
+ * @module ui-decorators/user-requests/types
+ * @summary Framework-agnostic contracts for the User Request Resolution Engine.
+ * @description No Angular or DOM imports are allowed here so the `user-requests`
+ * entry point stays consumable from pure-Node (backend) bundles.
+ */
+import type { RenderingEngine } from "../ui/Rendering.d.cts";
+/**
+ * @description A user request payload. `id` identifies the request instance,
+ * `type` is the keyed handler reference used for resolution — handlers are
+ * dispatched via `UserRequestHandler.handle(request, renderingEngine)`, which
+ * resolves the registered handler class by `request.type || request.id` — and
+ * `payload` carries optional request data.
+ * @template T The shape of the optional request data.
+ */
+export interface UserRequest<T = unknown> {
+    id: string;
+    type: string;
+    payload?: T;
+}
+/**
+ * @description The rendering-engine surface a user request handler needs.
+ * Exposes exactly the four real `RenderingEngine` methods a handler drives
+ * (modal, toast, spinner and router); no duplicated rendering types.
+ * @summary The four real `RenderingEngine` methods handed to handlers.
+ */
+export type RenderingFacade = Pick<RenderingEngine, "getModal" | "getToast" | "getSpinner" | "router">;
+/**
+ * @description Metadata recorded by `@userRequest(reference)` on a handler
+ * class and read back via `UserRequestHandler.getMetadata(target)`. `reference`
+ * is the request id/type the handler is registered for.
+ * @summary Metadata recorded on a `@userRequest`-decorated handler class.
+ */
+export interface UserRequestHandlerMetadata {
+    reference: string;
+}

package/lib/types/user-requests/types.d.mts

@@ -0,0 +1,36 @@
+/**
+ * @module ui-decorators/user-requests/types
+ * @summary Framework-agnostic contracts for the User Request Resolution Engine.
+ * @description No Angular or DOM imports are allowed here so the `user-requests`
+ * entry point stays consumable from pure-Node (backend) bundles.
+ */
+import type { RenderingEngine } from "../ui/Rendering.d.mts";
+/**
+ * @description A user request payload. `id` identifies the request instance,
+ * `type` is the keyed handler reference used for resolution — handlers are
+ * dispatched via `UserRequestHandler.handle(request, renderingEngine)`, which
+ * resolves the registered handler class by `request.type || request.id` — and
+ * `payload` carries optional request data.
+ * @template T The shape of the optional request data.
+ */
+export interface UserRequest<T = unknown> {
+    id: string;
+    type: string;
+    payload?: T;
+}
+/**
+ * @description The rendering-engine surface a user request handler needs.
+ * Exposes exactly the four real `RenderingEngine` methods a handler drives
+ * (modal, toast, spinner and router); no duplicated rendering types.
+ * @summary The four real `RenderingEngine` methods handed to handlers.
+ */
+export type RenderingFacade = Pick<RenderingEngine, "getModal" | "getToast" | "getSpinner" | "router">;
+/**
+ * @description Metadata recorded by `@userRequest(reference)` on a handler
+ * class and read back via `UserRequestHandler.getMetadata(target)`. `reference`
+ * is the request id/type the handler is registered for.
+ * @summary Metadata recorded on a `@userRequest`-decorated handler class.
+ */
+export interface UserRequestHandlerMetadata {
+    reference: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/ui-decorators",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Extension of decorator validation to ui elements to allow for web integration",
   "type": "module",
   "exports": {
@@ -25,6 +25,17 @@
         "default": "./lib/cjs/graph/index.cjs"
       },
       "default": "./lib/esm/graph/index.js"
+    },
+    "./user-requests": {
+      "import": {
+        "types": "./lib/types/user-requests/index.d.mts",
+        "default": "./lib/esm/user-requests/index.js"
+      },
+      "require": {
+        "types": "./lib/types/user-requests/index.d.cts",
+        "default": "./lib/cjs/user-requests/index.cjs"
+      },
+      "default": "./lib/esm/user-requests/index.js"
     }
   },
   "types": "./lib/types/index.d.mts",
@@ -47,7 +58,7 @@
     "lint": "eslint .",
     "lint-fix": "eslint --fix .",
     "prepare-pr": "npm run lint-fix && npm run build:prod && npm run coverage && npm run docs",
-    "prepare-release": "npm run lint-fix && npm run build:prod && npm run coverage && npm run docs",
+    "prepare-release": "npm run lint-fix && npm run build:prod && npm run coverage",
     "release": "./bin/tag-release.sh",
     "clean-publish": "npx clean-publish",
     "drawings": "for FILE in workdocs/drawings/*.drawio; do echo \"converting $FILE to image...\" && docker run --rm -v $(pwd):/data rlespinasse/drawio-export --format png $FILE; done && cp -rf workdocs/drawings/export/* workdocs/resources/",
@@ -108,9 +119,12 @@
     "@types/jest": "^30.0.0"
   },
   "dependencies": {
+    "@decaf-ts/core": "latest",
     "@decaf-ts/db-decorators": "latest",
     "@decaf-ts/decoration": "latest",
-    "@decaf-ts/decorator-validation": "latest"
+    "@decaf-ts/decorator-validation": "latest",
+    "better-docs": "^2.7.3",
+    "taffydb": "^2.7.3"
   },
   "main": "./lib/cjs/index.cjs",
   "module": "./lib/esm/index.js",
@@ -123,5 +137,9 @@
     "./lib/cjs/graph/overrides/index.cjs",
     "./lib/cjs/graph/overrides/overrides.cjs",
     "./lib/cjs/model/overrides.cjs"
-  ]
+  ],
+  "overrides": {
+    "test-exclude": "^7.0.2",
+    "brace-expansion": "^5.0.8"
+  }
 }