@spfn/core 0.3.0-beta.23 → 0.3.0-beta.25

package/dist/state/index.d.ts

@@ -0,0 +1,380 @@
+import { TObject, TSchema, Static } from '@sinclair/typebox';
+import { MiddlewareHandler, Context } from 'hono';
+import { EventDef } from '@spfn/core/event';
+import { NamedMiddleware, RouteAuthProfile, Router, RouteDef } from '@spfn/core/route';
+
+/**
+ * State Types
+ *
+ * A state's shape is tracked as one phantom record, `StateShape`, which each
+ * builder call rewrites. Every derived type — the read context, the result,
+ * the change signal's payload, the frame, the routes — is computed from it.
+ */
+
+/**
+ * What a builder has declared so far, at the type level only.
+ */
+interface StateShape {
+    key: TObject | undefined;
+    shared: boolean;
+    value: TSchema | undefined;
+    data: TSchema | undefined;
+    input: TSchema | undefined;
+    read: boolean;
+}
+/** The shape of `defineState(id)` before any call. */
+interface EmptyStateShape extends StateShape {
+    key: undefined;
+    shared: false;
+    value: undefined;
+    data: undefined;
+    input: undefined;
+    read: false;
+}
+/** `T` with the fields of `U` replaced. */
+type WithShape<T extends StateShape, U extends Partial<StateShape>> = {
+    [K in keyof StateShape]: K extends keyof U ? U[K] : T[K];
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The key object of a keyed state, `undefined` for a keyless one. */
+type StateKey<T extends StateShape> = T['key'] extends TObject ? Static<T['key']> : undefined;
+/** The value type, `unknown` until `.value()` is declared. */
+type StateValue<T extends StateShape> = T['value'] extends TSchema ? Static<T['value']> : unknown;
+/**
+ * What `read()` returns: always an object, so a value can never be mistaken
+ * for `{ value, data }`. With `.data()` declared, `data` is part of every
+ * result — the router checks each one against the declaration.
+ */
+type StateResult<T extends StateShape> = T['data'] extends TSchema ? {
+    value: StateValue<T>;
+    data: Static<T['data']>;
+} : {
+    value: StateValue<T>;
+};
+/** What the read and write routes answer: the result and the time its read started. */
+type StateSnapshot<T extends StateShape> = Simplify<{
+    at: string;
+} & StateResult<T>>;
+/** What `.canRead()` / `.canWrite()` decide on. */
+type PermissionContext<T extends StateShape> = T['key'] extends TObject ? {
+    subject: string;
+    principal: unknown;
+    key: Static<T['key']>;
+} : {
+    subject: string;
+    principal: unknown;
+};
+/** What `read()` receives. A shared state's value does not depend on the subject, so it gets none. */
+type ReadContext<T extends StateShape> = T['key'] extends TObject ? T['shared'] extends true ? {
+    principal: unknown;
+    key: Static<T['key']>;
+} : PermissionContext<T> : PermissionContext<T>;
+/** What `write()` receives: the read context plus the validated input. */
+type WriteContext<T extends StateShape, I extends TSchema> = Simplify<ReadContext<T> & {
+    input: Static<I>;
+}>;
+/** The payload of `state.changed.emit()`: exactly what names the value to re-read. */
+type ChangedPayload<T extends StateShape> = T['key'] extends TObject ? T['shared'] extends true ? Simplify<Static<T['key']>> : Simplify<Static<T['key']> & {
+    subject: string;
+}> : {
+    subject: string;
+};
+/** The payload of the derived SSE event `state.<id>.changed`. */
+type StateFrame<T extends StateShape> = Simplify<StateSnapshot<T> & (T['key'] extends TObject ? {
+    key: Static<T['key']>;
+} : {}) & (T['key'] extends TObject ? (T['shared'] extends true ? {} : {
+    subject: string;
+}) : {
+    subject: string;
+})>;
+/** Whom `grant()` reaches, and for a keyed state the one key it opens and sends the current value of. */
+type GrantTarget<T extends StateShape> = T['key'] extends TObject ? {
+    subject: string;
+    key: Static<T['key']>;
+} : {
+    subject: string;
+};
+/** Whom `revoke()` reaches: for a keyed state, the connections on `key`, or every one without it. */
+type RevokeTarget<T extends StateShape> = T['key'] extends TObject ? {
+    subject: string;
+    key?: Static<T['key']>;
+} : {
+    subject: string;
+};
+/**
+ * The contract one `.contract()` declares for the read route, the write route
+ * and the derived event. The response schema is derived, never declared.
+ */
+interface StateContract {
+    since: string;
+    auth?: RouteAuthProfile;
+    requiresSession?: boolean;
+    deprecatedIn?: string;
+    removedIn?: string;
+}
+/** Version markers of a write added, deprecated or removed apart from its read. */
+interface StateWriteOptions {
+    since?: string;
+    deprecatedIn?: string;
+    removedIn?: string;
+}
+/** Any read / permission / write context, as the runtime handles it. */
+interface StateCallContext {
+    subject?: string;
+    principal: unknown;
+    key?: Record<string, string>;
+    input?: unknown;
+}
+type StatePredicate = (ctx: StateCallContext) => boolean | Promise<boolean>;
+type StateReader = (ctx: StateCallContext) => unknown;
+type StateWriter = (ctx: StateCallContext) => void | Promise<void>;
+/**
+ * Everything one builder declared, as the router reads it.
+ */
+interface StateDefinition {
+    id: string;
+    key?: TObject;
+    shared: boolean;
+    value?: TSchema;
+    data?: TSchema;
+    middlewares: (MiddlewareHandler | NamedMiddleware<string>)[];
+    skipMiddlewares?: string[] | '*';
+    contract?: StateContract;
+    canRead?: StatePredicate;
+    canWrite?: StatePredicate;
+    read?: StateReader;
+    write?: {
+        input: TSchema;
+        fn: StateWriter;
+        options: StateWriteOptions;
+    };
+    changedBy?: EventDef<any>[];
+}
+/**
+ * What `defineStateRouter` accepts: a builder with `.value()` and `.read()`
+ * declared. A builder without either is not assignable here.
+ */
+interface RoutableState {
+    readonly id: string;
+    readonly _types: StateShape & {
+        value: TSchema;
+        read: true;
+    };
+    readonly _definition: Readonly<StateDefinition>;
+    readonly _event: EventDef<any>;
+    readonly changed: EventDef<any>;
+}
+
+/**
+ * State Builder
+ *
+ * `defineState(id)` starts an immutable builder: every call returns a new one,
+ * order is free and there is no terminal method. `defineStateRouter` reads
+ * what a builder declared and derives its routes and SSE event from it.
+ */
+
+/**
+ * A server-owned value declared once. See the module README.
+ */
+declare class StateBuilder<TId extends string, T extends StateShape> {
+    readonly id: TId;
+    readonly _definition: Readonly<StateDefinition>;
+    /** Type inference helper: what this builder declared. Never set at runtime. */
+    readonly _types: T;
+    private changedSignal?;
+    private stateEvent?;
+    constructor(id: TId, _definition: Readonly<StateDefinition>);
+    /**
+     * Declare the key: one value per key (and per subject, unless `shared`).
+     * Fields are required strings: they travel as query parameters.
+     */
+    key<K extends TObject, S extends boolean = false>(schema: K, options?: {
+        shared?: S;
+    }): StateBuilder<TId, WithShape<T, {
+        key: K;
+        shared: S;
+    }>>;
+    /** Declare the value schema. Required. */
+    value<V extends TSchema>(schema: V): StateBuilder<TId, WithShape<T, {
+        value: V;
+    }>>;
+    /** Declare data attached to the value. Optional. */
+    data<D extends TSchema>(schema: D): StateBuilder<TId, WithShape<T, {
+        data: D;
+    }>>;
+    /**
+     * Middleware for the two per-state routes, `get<Id>State` / `put<Id>State`.
+     * Not authorization: the snapshot and the SSE stream cannot run it, so a
+     * state with `.use()` must declare `.canRead()`. Calls add up.
+     */
+    use(middlewares: (MiddlewareHandler | NamedMiddleware<string>)[]): StateBuilder<TId, T>;
+    /** Server-level named middlewares the two per-state routes skip. Calls add up; `'*'` wins. Needs `.canRead()`, as `.use()`. */
+    skip(middlewareNames: string[] | '*'): StateBuilder<TId, T>;
+    /** Publish the read route, the write route and the event in the contract. */
+    contract(contract: StateContract): StateBuilder<TId, T>;
+    /** Who may read. Required on a keyed state; checked on HTTP and at SSE connect. */
+    canRead(predicate: (ctx: PermissionContext<T>) => boolean | Promise<boolean>): StateBuilder<TId, T>;
+    /** Who may write. Absent → `canRead` decides. */
+    canWrite(predicate: (ctx: PermissionContext<T>) => boolean | Promise<boolean>): StateBuilder<TId, T>;
+    /** The only source of a value. Required. */
+    read(fn: (ctx: ReadContext<T>) => StateResult<T> | Promise<StateResult<T>>): StateBuilder<TId, WithShape<T, {
+        read: true;
+    }>>;
+    /**
+     * Derive `PUT <path>/<id>`. `fn` runs the command; the value the route
+     * answers and broadcasts is re-read afterwards, never taken from `input`.
+     */
+    write<I extends TSchema>(input: I, fn: (ctx: WriteContext<T, I>) => void | Promise<void>, options?: StateWriteOptions): StateBuilder<TId, WithShape<T, {
+        input: I;
+    }>>;
+    /**
+     * Domain events whose payload names a changed value of this state, treated
+     * like `changed.emit` with that payload: keyless `subject`, keyed the key
+     * fields and `subject`, shared the key fields. The router subscribes them
+     * and refuses one whose payload schema lacks a field.
+     */
+    changedBy(events: EventDef<any>[]): StateBuilder<TId, T>;
+    /**
+     * The change signal. Emit it after the change is committed; the module
+     * re-reads the value and sends the frame. Refused on a builder no router
+     * grouped — export the instance you passed to `defineStateRouter`.
+     */
+    get changed(): EventDef<ChangedPayload<T>>;
+    /** Internal: the SSE event `state.<id>.changed` (`defineStateRouter(...).events`). */
+    get _event(): EventDef<StateFrame<T>>;
+    /**
+     * Activate the state's event on `subject`'s open connections and send it
+     * the current value at once. On a keyed state only the connections that
+     * declared `key` are opened. Does not consult `canRead`.
+     */
+    grant(target: GrantTarget<T>): Promise<void>;
+    /**
+     * Deactivate the state's event on `subject`'s open connections: on a keyed
+     * state those that declared `key`, or every one when no key is given.
+     */
+    revoke(target: RevokeTarget<T>): Promise<void>;
+    /** A keyed grant opens one key: without it there is no key to open and no value to send. */
+    private assertGrantKey;
+    /**
+     * The declared key fields of `key`, checked against `.key()`: an empty or
+     * partial key would match every connection of the subject. A field the
+     * declaration does not name is dropped, never matched on — so the check
+     * runs on a fresh object of the declared fields, never `.key()` itself: a
+     * key declared `additionalProperties: false` would otherwise refuse it.
+     * The fresh object keeps `.key()`'s `required`, and a key that still picks
+     * to nothing is refused: `undefined` here would mean every connection.
+     */
+    private declaredKey;
+    private refuseKey;
+    private with;
+    private assertOnce;
+}
+/**
+ * Declare a server-owned state.
+ *
+ * @example
+ * ```typescript
+ * export const consent = defineState('consent')
+ *     .value(Type.Union([Type.Literal('pending'), Type.Literal('agreed')]))
+ *     .read(({ subject }) => consents.current(subject));
+ * ```
+ */
+declare function defineState<TId extends string>(id: TId): StateBuilder<TId, EmptyStateShape>;
+
+/**
+ * State Routes
+ *
+ * The read, write and snapshot routes a state router derives. They are
+ * ordinary `RouteDef`s registered through `registerRoutes`, so a state's
+ * `.use()` middleware runs inside the route's own chain after the app's
+ * global middleware.
+ */
+
+/** Who a request is for. `null` answers 401. */
+type SubjectResolver = (c: Context) => string | null;
+
+/**
+ * State Router
+ *
+ * Groups states, derives their routes into one `Router` the app mounts with
+ * `.packages()`, collects their SSE events for the app's event router, and
+ * subscribes each state's change signal — once, here.
+ */
+
+interface StateRouterOptions {
+    /**
+     * Where the routes are mounted: `GET <path>`, `GET|PUT <path>/<id>`.
+     * @default '/state'
+     */
+    path?: string;
+    /**
+     * Who an HTTP request is for. `null` answers 401.
+     * @default (c) => c.get('auth')?.userId ?? null
+     */
+    subject?: SubjectResolver;
+}
+type Shape<S extends RoutableState> = S['_types'];
+type KeyQuery<S extends RoutableState> = Shape<S>['key'] extends TObject ? {
+    query: Shape<S>['key'];
+} : {};
+type ReadRoutes<S extends Record<string, RoutableState>> = {
+    [K in keyof S as `get${Capitalize<S[K]['id']>}State`]: RouteDef<KeyQuery<S[K]>, {}, StateSnapshot<Shape<S[K]>>>;
+};
+type WriteInput<S extends RoutableState> = KeyQuery<S> & {
+    body: Shape<S>['input'];
+};
+type WriteRoutes<S extends Record<string, RoutableState>> = {
+    [K in keyof S as Shape<S[K]>['input'] extends TSchema ? `put${Capitalize<S[K]['id']>}State` : never]: RouteDef<WriteInput<S[K]>, {}, StateSnapshot<Shape<S[K]>>>;
+};
+/** What `GET <path>` answers: every state the subject may read and whose key the query carries. */
+type StatesSnapshot<S extends Record<string, RoutableState>> = {
+    at: string;
+    states: {
+        [K in keyof S as S[K]['id']]?: StateResult<Shape<S[K]>>;
+    };
+};
+/** The routes one state router derives, typed for `createApi` and the route map. */
+type StateRoutes<S extends Record<string, RoutableState>> = ReadRoutes<S> & WriteRoutes<S> & {
+    getStates: RouteDef<{
+        query: TObject;
+    }, {}, StatesSnapshot<S>>;
+};
+/** The SSE events, keyed by their wire names, for the app's `defineEventRouter`. */
+type StateEvents<S extends Record<string, RoutableState>> = {
+    [K in keyof S as `state.${S[K]['id']}.changed`]: EventDef<StateFrame<Shape<S[K]>>>;
+};
+interface StateRouter<S extends Record<string, RoutableState>> {
+    /** The derived routes. Mount with `appRouter.packages([states.router])`. */
+    router: Router<StateRoutes<S>>;
+    /** The derived SSE events. Spread into `defineEventRouter({ ...appEvents, ...states.events })`. */
+    events: StateEvents<S>;
+    /** The declarations, as given. */
+    states: S;
+}
+type StateById<R extends StateRouter<any>, TId extends string> = Extract<R['states'][keyof R['states']], {
+    id: TId;
+}>;
+/** The value type of state `TId` of a state router. */
+type InferStateValue<R extends StateRouter<any>, TId extends string> = StateValue<Shape<StateById<R, TId>>>;
+/** The key type of state `TId`, `undefined` when it is keyless. */
+type InferStateKey<R extends StateRouter<any>, TId extends string> = StateKey<Shape<StateById<R, TId>>>;
+/** The write input of state `TId`, `never` when it declares no `.write()`. */
+type InferStateInput<R extends StateRouter<any>, TId extends string> = Shape<StateById<R, TId>>['input'] extends TSchema ? Static<Shape<StateById<R, TId>>['input']> : never;
+/**
+ * Group states, derive their routes and SSE events, and subscribe their change
+ * signals.
+ *
+ * @example
+ * ```typescript
+ * export const states = defineStateRouter({ consent, runtime, member });
+ *
+ * // server.config.ts
+ * //   .routes(appRouter.packages([states.router]))
+ * //   .events(defineEventRouter({ ...appEvents, ...states.events }), { auth: { enabled: true } })
+ * ```
+ */
+declare function defineStateRouter<S extends Record<string, RoutableState>>(states: S, options?: StateRouterOptions): StateRouter<S>;
+
+export { type ChangedPayload, type GrantTarget, type InferStateInput, type InferStateKey, type InferStateValue, type PermissionContext, type ReadContext, type RevokeTarget, type RoutableState, StateBuilder, type StateContract, type StateEvents, type StateFrame, type StateKey, type StateResult, type StateRouter, type StateRouterOptions, type StateRoutes, type StateShape, type StateSnapshot, type StateValue, type StateWriteOptions, type StatesSnapshot, type SubjectResolver, type WriteContext, defineState, defineStateRouter };