@velajs/vela 1.18.0 → 1.19.1

package/dist/index-D72EQfcC.d.ts

@@ -0,0 +1,430 @@
+import { a as OnApplicationBootstrap } from "./schedule.registry-DVm7Jp5w.js";
+import { P as Container, U as InjectionToken, i as DiscoveryService } from "./discovery.service-Cpf1QcZ5.js";
+import { X as ContributesEntrypoints, Z as Entrypoint } from "./metadata.registry-D1od8ZBt.js";
+import { Xn as ReservedWsEventHandler, er as WsClient, nr as WsMessage, zt as ConfigurableModuleClassType } from "./index-DhShDLCM.js";
+import { COMMIT_CURSOR_HEADER as COMMIT_CURSOR_HEADER$1, COMMIT_EPOCH_HEADER as COMMIT_EPOCH_HEADER$1, ClientLiveFrame, DEFAULT_KEY_FIELD as DEFAULT_KEY_FIELD$1, LIVE_ERROR_CODES as LIVE_ERROR_CODES$1, LIVE_EVENT, LIVE_PROTOCOL as LIVE_PROTOCOL$1, LiveFrame, RowOp, ServerLiveFrame, ServerLiveFrame as ServerLiveFrame$1, applyListDelta, encodeListDelta as encodeListDelta$1, encodeLiveEnvelope as encodeLiveEnvelope$1, encodeLiveFrame, isClientLiveFrame as isClientLiveFrame$1, isServerLiveFrame, readLiveEnvelope } from "@velajs/live-protocol";
+//#region src/live/live.types.d.ts
+/**
+ * Identity captured at subscribe time and replayed into every re-run of the
+ * subscription's query — never re-read from the client afterwards. Free-form;
+ * `expiresAt` (epoch ms) is the one recognized field: a lapsed identity drops
+ * the socket before it receives another scoped push (outbound enforcement —
+ * a passive subscriber never trips inbound checks).
+ */
+interface LiveIdentity {
+  [key: string]: unknown;
+  expiresAt?: number;
+}
+/** Second positional argument every `@LiveQuery` handler receives. */
+interface LiveQueryContext {
+  identity?: LiveIdentity;
+  /** The subscribed connection's id. */
+  clientId: string;
+  /** Rooms the connection was in when it subscribed. */
+  rooms: string[];
+}
+interface LiveQueryOptions<A = unknown> {
+  /**
+   * Dependency tags this query's result is built from — the invalidation
+   * contract. Static for the common case; the function form derives
+   * per-entity tags from the (parsed) subscribe args. Writes invalidate tags
+   * via `LiveInvalidation.invalidate()` (the CRUD bridge does it
+   * automatically with `crud:<table>` tags).
+   */
+  tags: string[] | ((args: A) => string[]);
+  /** Key field for incremental list deltas (default `'id'`). */
+  key?: string;
+  /**
+   * Args validator, run ONCE at subscribe (a zod schema's `.parse` slots in
+   * directly). A throw rejects the subscription with a `bad_args` error frame.
+   */
+  parse?: (args: unknown) => A;
+}
+/** One `@LiveQuery` declaration on a `@LiveResolver` class. */
+interface LiveQueryMetadata {
+  name: string;
+  methodName: string | symbol;
+  options: LiveQueryOptions;
+}
+/** Class-level marker meta written by `@LiveResolver()`. */
+interface LiveResolverMetadata {}
+/** A position in this log scope's ordered invalidation log. */
+interface CommitStamp {
+  cursor: number;
+  epoch: string;
+}
+/**
+ * Resume verdict for a reconnecting subscription:
+ * - `'resume'` — nothing the subscription depends on changed while away; keep
+ *   the client's cached value and just advance its cursor.
+ * - `'rerun'` — a relevant tag was invalidated in the gap; re-run and snapshot.
+ * - `'snapshot'` — the gap cannot be reasoned about (epoch fork, trimmed log,
+ *   rollback); re-run and snapshot.
+ */
+type ResumeVerdict = 'resume' | 'rerun' | 'snapshot';
+/**
+ * The ordered tag-invalidation log for ONE log scope (this process on
+ * node/bun/deno; one Durable Object on Cloudflare). Cursor = monotonic
+ * sequence; epoch = timeline token rolled whenever monotonicity can no longer
+ * be guaranteed (process restart, DO reset).
+ */
+interface CursorLog {
+  append(tags: string[]): CommitStamp | Promise<CommitStamp>;
+  current(): CommitStamp | Promise<CommitStamp>;
+  evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict | Promise<ResumeVerdict>;
+}
+/** A tag invalidation crossing the driver seam. `room` addresses the log scope holding the subscribers (advisory for local delivery). */
+interface InvalidationCommand {
+  room?: string;
+  tags: string[];
+  /** Origin instance id — lets pub/sub drivers drop their own echo. */
+  origin?: string;
+}
+/** What a driver delivers invalidations INTO — the live engine of one log scope. */
+interface LiveInvalidationSink {
+  applyInvalidation(cmd: InvalidationCommand): CommitStamp | Promise<CommitStamp>;
+}
+/**
+ * Cross-boundary invalidation transport — the live sibling of the WebSocket
+ * `SyncDriver`, carrying TAGS (re-run instructions) instead of pre-serialized
+ * frames. `localLive()` is the in-core single-scope default; platform packages
+ * (`durableObjectLive()` in @velajs/cloudflare, `redisLive()` in
+ * websocket-node) implement it out-of-core. `dispatch` returns the commit
+ * stamp of the targeted log scope when the driver can observe it.
+ */
+interface LiveDriver {
+  readonly kind: string;
+  bind(sink: LiveInvalidationSink): void;
+  dispatch(cmd: InvalidationCommand): CommitStamp | undefined | Promise<CommitStamp | undefined>;
+  start?(): void | Promise<void>;
+  stop?(): void | Promise<void>;
+}
+/** One live subscription as tracked by the engine (and persisted by transports that survive eviction). */
+interface SubscriptionRecord {
+  sub: string;
+  query: string;
+  args: unknown;
+  /** Frozen at subscribe from the (parsed) args. */
+  tags: string[];
+  /** Delta key field (subscribe-frame override wins over the handler option). */
+  key?: string;
+  identity?: LiveIdentity;
+  /**
+   * The last result this subscription confirmed on the wire (the delta diff
+   * baseline). `undefined` after a cursor-resume: the server never re-ran the
+   * query, so the next relevant change sends a full snapshot.
+   */
+  lastJson?: string;
+  lastCursor?: number;
+}
+interface LivePresenceOptions {
+  /** Roster entries older than this are filtered at read time (default 30_000 ms). */
+  ttlMs?: number;
+}
+interface LiveModuleOptions {
+  /** Cross-boundary invalidation driver. Defaults to `localLive()`. */
+  driver?: LiveDriver;
+  /** Ordered invalidation log. Defaults to the in-memory per-process log. */
+  log?: CursorLog;
+  /**
+   * Identity capture at subscribe. Default: a shallow copy of `client.data`
+   * (whatever the app's upgrade/`handleConnection` auth stamped there), or
+   * `undefined` when empty.
+   */
+  identity?: (client: WsClient) => LiveIdentity | undefined;
+  /** Presence preset configuration; `false` disables the built-in resolver. */
+  presence?: LivePresenceOptions | false;
+}
+/** Meta carried by the `'live'` entrypoint (transports reach the engine through it). */
+interface LiveEntrypointMeta {
+  /** The engine — typed loosely to avoid a circular type edge; cast to `LiveEngine`. */
+  engine: unknown;
+}
+//#endregion
+//#region src/live/live.module.d.ts
+/**
+ * First-party live-query module (tag-based realtime reactivity) — authored,
+ * like the queue module, entirely on vela's public API (`live-openness.test.ts`
+ * machine-verifies it; the only extra dependency is the shared wire package
+ * `@velajs/live-protocol`).
+ *
+ * ```ts
+ * imports: [WebSocketModule.forRoot({}), LiveModule.forRoot({})]
+ * ```
+ *
+ * App code declares `@LiveResolver` classes with `@LiveQuery(name, { tags })`
+ * methods; clients subscribe over the `$live` reserved WebSocket event; writes
+ * invalidate tags via `LiveInvalidation` (the `@velajs/crud` bridge does it
+ * automatically per table). See `LIVE.md` for the wire protocol, delivery
+ * guarantees, and the resume story.
+ *
+ * Deliberately EAGER (like WebSocketModule): the engine self-drives — it
+ * claims the `$live` event at bootstrap and receives invalidations from
+ * writes that never touch a live token — so the lazy-module contract
+ * ("nothing self-drives") rules laziness out.
+ */
+declare const ConfigurableModuleClass: ConfigurableModuleClassType<LiveModuleOptions, "forRoot", "create", {
+  isGlobal?: boolean;
+}>;
+declare class LiveModule extends ConfigurableModuleClass {}
+//#endregion
+//#region src/live/live.decorators.d.ts
+/**
+ * Marks a provider class as a live-query resolver:
+ *
+ * ```ts
+ * @LiveResolver()
+ * @Injectable()
+ * class TodoLive {
+ *   constructor(private readonly todos: TodoService) {}
+ *
+ *   @LiveQuery('todos.list', { tags: (a: { listId: string }) => [`todos:${a.listId}`] })
+ *   list(args: { listId: string }, ctx: LiveQueryContext) {
+ *     return this.todos.byList(args.listId, ctx.identity?.userId);
+ *   }
+ * }
+ * ```
+ *
+ * Clients subscribe by query name over the `$live` reserved event; the engine
+ * re-runs a handler whenever one of its tags is invalidated and pushes the
+ * result (as a keyed delta when possible). Stack with `@Injectable()`, exactly
+ * like `@Processor`.
+ */
+declare function LiveResolver(): ClassDecorator;
+/**
+ * Declares a live query on a resolver method. The handler receives
+ * `(args, ctx: LiveQueryContext)` positionally — args are validated once at
+ * subscribe (via `options.parse`), then replayed verbatim into every re-run
+ * under the subscriber's captured identity.
+ */
+declare function LiveQuery<A = unknown>(name: string, options: LiveQueryOptions<A>): MethodDecorator;
+/** `@LiveQuery` entries declared on a resolver class (declaration order). */
+declare function getLiveQueries(resolverClass: object): LiveQueryMetadata[];
+//#endregion
+//#region src/live/presence.d.ts
+/** The invalidation tag for one room's roster. `$`-prefixed: never collides with app tags. */
+declare const presenceTag: (room: string) => string;
+/** The built-in roster query name (`useLiveQuery`-able like any app query). */
+declare const PRESENCE_ROSTER_QUERY = "$presence.roster";
+/** One present connection as returned by the roster query. Keyed by `id` so list deltas apply. */
+interface PresenceMember {
+  /** The connection id that heartbeats this membership. */
+  id: string;
+  meta?: unknown;
+  lastSeen: number;
+}
+/**
+ * The presence preset's server half. Heartbeats arrive as `{ t: 'presence' }`
+ * frames on the live socket (routed here by the engine); the roster is a
+ * built-in live query invalidated per room. Departure is immediate: the WS
+ * close hook reaps the member without waiting out the TTL. Staleness (an
+ * ungraceful drop the transport never noticed) is filtered AT READ TIME —
+ * no timers, per the edge rules (`setInterval` is forbidden).
+ *
+ * Scope note: the roster lives in this log scope (one process on node, one
+ * room-DO on Cloudflare — where it is exactly the room's roster).
+ */
+declare class PresenceService {
+  private readonly ttlMs;
+  readonly enabled: boolean;
+  private readonly rooms;
+  private readonly roomsByClient;
+  private invalidator?;
+  constructor(ttlMs?: number, enabled?: boolean);
+  /** Wired by the engine so beats/reaps invalidate through the live driver. */
+  bindInvalidator(invalidator: (tags: string[]) => void): void;
+  beat(room: string, clientId: string, meta?: unknown): void;
+  /** Immediate departure on socket close — peers see it without a TTL wait. */
+  reap(clientId: string): void;
+  roster(room: string): PresenceMember[];
+}
+/** The built-in resolver backing `$presence.roster`. Registered by `LiveModule` unless presence is disabled. */
+declare class PresenceResolver {
+  private readonly presence;
+  constructor(presence: PresenceService);
+  roster(args: {
+    room: string;
+  }): PresenceMember[];
+}
+//#endregion
+//#region src/live/live.engine.d.ts
+/**
+ * Where the engine persists a connection's subscription records inside
+ * `client.data` (committed through `WsClient.commit()`). On Cloudflare that
+ * lands in the hibernation attachment, so subscriptions survive DO eviction;
+ * the transport replays them via `restoreSubscription` on wake. On node,
+ * `commit()` is a no-op and this is just in-memory bookkeeping.
+ */
+declare const LIVE_SUBS_DATA_KEY = "__velaLiveSubs";
+/** Read the subscription records a transport persisted for a connection (wake/restore path). */
+declare function readPersistedLiveSubscriptions(client: WsClient): SubscriptionRecord[];
+/**
+ * The live-query engine of ONE log scope: routes `$live` frames (subscribe /
+ * unsubscribe / presence), owns the subscription registry, and turns tag
+ * invalidations into re-run → diff → push cycles.
+ *
+ * Delivery semantics (ported from lunora's `shard-do.ts` refresh loop):
+ * - **Coalescing**: a burst of invalidations collapses into one flush; every
+ *   committed invalidation is observed by a flush that STARTS after it
+ *   committed (`applyInvalidation` appends to the log before arming the
+ *   drain, and the drain re-loops while tags are pending).
+ * - **At-least-once**: a subscription's diff baseline (`lastJson`) advances
+ *   only when the frame left the socket; keyed deltas are idempotent on
+ *   replay.
+ * - **Frame suppression**: a byte-identical re-run sends `settled` — no
+ *   payload, but the cursor still advances so client optimistic layers drop.
+ * - **Outbound expiry**: a subscription whose captured identity lapsed is
+ *   dropped (socket closed) before it receives another scoped push.
+ * - **Cursor-before-run**: the stamp a frame carries is read BEFORE the
+ *   re-run, so a result can only be NEWER than its cursor claims — an
+ *   invalidation racing the run is re-observed by the next flush, never lost.
+ *
+ * Transports reach the engine via `app.entrypoints.ofKind('live')` (it
+ * contributes itself) — the same contract the WebSocket triad uses.
+ */
+declare class LiveEngine implements OnApplicationBootstrap, ContributesEntrypoints, ReservedWsEventHandler, LiveInvalidationSink {
+  private readonly container;
+  private readonly discovery;
+  private readonly log;
+  private readonly options;
+  private readonly presence?;
+  private readonly queries;
+  private readonly connections;
+  private readonly pendingTags;
+  private drainChain;
+  private draining;
+  constructor(container: Container, discovery: DiscoveryService, log: CursorLog, driver: LiveDriver, options: LiveModuleOptions, presence?: PresenceService | undefined);
+  onApplicationBootstrap(): Promise<void>;
+  /** The `'live'` entrypoint — how transports (node registrar, CF DO bootstrap) find the engine. */
+  collectEntrypoints(): Entrypoint<LiveEntrypointMeta>[];
+  handleReservedEvent(path: string, client: WsClient, message: WsMessage): Promise<void>;
+  handleSocketClose(_path: string, client: WsClient): Promise<void>;
+  applyInvalidation(cmd: InvalidationCommand): Promise<CommitStamp>;
+  /** Settles when every pending invalidation has been flushed (tests, graceful transports). */
+  whenIdle(): Promise<void>;
+  /**
+   * Re-attach a persisted subscription without the subscribe handshake — the
+   * Cloudflare transport replays hibernation-attachment records through this
+   * on wake. No frames are sent; the next relevant invalidation pushes.
+   */
+  restoreSubscription(path: string, client: WsClient, record: SubscriptionRecord): void;
+  private onSubscribe;
+  private runSubscribeGuards;
+  private scheduleDrain;
+  private drainLoop;
+  /**
+   * Map a resolver failure to its live error-frame code. A branded
+   * {@link VelaError} carries an HTTP-ish status that projects onto the live
+   * vocabulary (403 → forbidden, 400/422 → bad_args); everything else — and
+   * every unbranded error — is `internal` (the client sees a redacted message).
+   */
+  private static liveFrameCode;
+  private push;
+  private runQuery;
+  /**
+   * Mirror the connection's records into `client.data` + `commit()` so
+   * hibernating transports can replay them on wake. The volatile diff
+   * baseline (`lastJson`/`lastCursor`) is deliberately stripped: it can be
+   * large (the whole last result vs the 16 KiB attachment cap) and a lost
+   * baseline just means the next relevant change sends a full snapshot.
+   */
+  private persistSubscriptions;
+  private ensureConnection;
+  private sendFrame;
+}
+//#endregion
+//#region src/live/live.invalidation.d.ts
+/** Single-scope default driver: deliver straight to this process's engine. */
+declare function localLive(): LiveDriver;
+/**
+ * Per-app wrapper around a (possibly SHARED) driver instance.
+ *
+ * A driver passed to `LiveModule.forRoot({ driver })` is a plain config object
+ * — and on Cloudflare the SAME app module (thus the same driver object)
+ * bootstraps in the Worker isolate AND inside each Durable Object, often
+ * within one isolate. Mutable per-app state must therefore never live on the
+ * driver itself: the DO flipping a shared `durableObjectLive()` into local
+ * mode would otherwise poison the Worker's engine, which then executes the
+ * DO's storage handle in the wrong request context ("Cannot perform I/O on
+ * behalf of a different request").
+ *
+ * The wrapper owns the per-app sink and the per-app local-mode flag; isolate-
+ * wide concerns (env capture) forward to the underlying driver. Platform init
+ * hooks (`_setLocalMode`, `_initializeEnv`) are exposed pass-through so
+ * platform packages can keep type-guarding on their presence.
+ */
+declare function perAppLiveDriver(underlying: LiveDriver): LiveDriver;
+/**
+ * The injectable invalidation surface for custom (non-CRUD) write paths:
+ *
+ * ```ts
+ * await this.live.invalidate({ tags: ['todos:' + listId] });
+ * ```
+ *
+ * Every affected live query re-runs and pushes. Returns the commit stamp of
+ * the targeted log scope so mutation endpoints can expose it to the client
+ * (`Vela-Commit-Cursor` / `Vela-Commit-Epoch`) — the cursor optimistic
+ * updates gate on. When ambient request access is enabled
+ * (`VelaFactory.create(m, { ambientContainer: true })`) the headers are
+ * stamped onto the current HTTP response automatically; otherwise stamp them
+ * yourself via {@link stampCommitHeaders}.
+ */
+declare class LiveInvalidation {
+  private readonly driver;
+  constructor(driver: LiveDriver);
+  invalidate(cmd: InvalidationCommand): Promise<CommitStamp | undefined>;
+}
+/** Write the commit headers onto a Hono context (a mutation route's response). */
+declare function stampCommitHeaders(c: {
+  header: (name: string, value: string) => unknown;
+}, stamp: CommitStamp): void;
+//#endregion
+//#region src/live/live.cursor.d.ts
+/**
+ * The in-core `CursorLog`: a bounded in-memory ring, epoch minted per process
+ * (Web Crypto). A restart rolls the epoch, so every reconnecting client falls
+ * back to snapshot — exactly the documented node/dev semantics. Within one
+ * process lifetime resume works for gaps the ring still covers; a trimmed gap
+ * degrades to snapshot (mirrors lunora's CDC retention rule,
+ * `ctx-db-cdc.ts` — retention gap → snapshot).
+ *
+ * The Cloudflare transport replaces this with a Durable-Object SQLite log so
+ * resume survives hibernation and eviction.
+ */
+declare class InMemoryCursorLog implements CursorLog {
+  private readonly maxEntries;
+  private readonly epoch;
+  private readonly entries;
+  private seq;
+  constructor(maxEntries?: number);
+  append(tags: string[]): CommitStamp;
+  current(): CommitStamp;
+  evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict;
+}
+//#endregion
+//#region src/live/live.delta.d.ts
+/**
+ * Decide what one re-run puts on the wire — pure, so the contract is
+ * unit-testable without sockets:
+ *
+ * - byte-identical to the baseline → `settled` (cursor still advances; this
+ *   is what drops client optimistic layers for writes that didn't change the
+ *   result);
+ * - baseline exists and the shared codec can diff → `delta` (batched keyed
+ *   row ops);
+ * - otherwise (first send after subscribe/resume, codec bailed, unparseable
+ *   baseline) → full `data` snapshot.
+ */
+declare function encodeSubscriptionUpdate(record: SubscriptionRecord, json: string, result: unknown, stamp: CommitStamp, initial: boolean): ServerLiveFrame;
+//#endregion
+//#region src/live/live.tokens.d.ts
+declare const LIVE_RESOLVER_METADATA = "vela:live:resolver";
+declare const LIVE_QUERY_METADATA = "vela:live:query";
+/** The invalidation driver in effect for a `LiveModule` instance (`localLive()` by default). */
+declare const LIVE_DRIVER: InjectionToken<LiveDriver>;
+/** The ordered tag-invalidation log backing cursors/epochs for this log scope. */
+declare const LIVE_CURSOR_LOG: InjectionToken<CursorLog>;
+declare const LIVE_MODULE_OPTIONS: InjectionToken<LiveModuleOptions>;
+//#endregion
+export { LiveResolverMetadata as $, LiveEngine as A, LiveModule as B, encodeSubscriptionUpdate as C, perAppLiveDriver as D, localLive as E, PresenceService as F, LiveEntrypointMeta as G, CursorLog as H, presenceTag as I, LiveModuleOptions as J, LiveIdentity as K, LiveQuery as L, PRESENCE_ROSTER_QUERY as M, PresenceMember as N, stampCommitHeaders as O, PresenceResolver as P, LiveQueryOptions as Q, LiveResolver as R, LIVE_RESOLVER_METADATA as S, LiveInvalidation as T, InvalidationCommand as U, CommitStamp as V, LiveDriver as W, LiveQueryContext as X, LivePresenceOptions as Y, LiveQueryMetadata as Z, readLiveEnvelope as _, LIVE_ERROR_CODES$1 as a, LIVE_MODULE_OPTIONS as b, LiveFrame as c, applyListDelta as d, ResumeVerdict as et, encodeListDelta$1 as f, isServerLiveFrame as g, isClientLiveFrame$1 as h, DEFAULT_KEY_FIELD$1 as i, readPersistedLiveSubscriptions as j, LIVE_SUBS_DATA_KEY as k, RowOp as l, encodeLiveFrame as m, COMMIT_EPOCH_HEADER$1 as n, LIVE_EVENT as o, encodeLiveEnvelope$1 as p, LiveInvalidationSink as q, ClientLiveFrame as r, LIVE_PROTOCOL$1 as s, COMMIT_CURSOR_HEADER$1 as t, SubscriptionRecord as tt, ServerLiveFrame$1 as u, LIVE_CURSOR_LOG as v, InMemoryCursorLog as w, LIVE_QUERY_METADATA as x, LIVE_DRIVER as y, getLiveQueries as z };
+//# sourceMappingURL=index-D72EQfcC.d.ts.map