@velajs/vela 1.16.0 → 1.17.0

package/dist/index.d.ts

@@ -31,8 +31,8 @@ export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_E
 export type { EventHandler, OnEventMetadata } from './event-emitter/index';
 export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA, } from './schedule/index';
 export type { RegisteredCronJob, RegisteredIntervalJob, CronMetadata, IntervalMetadata, CronMatcher, } from './schedule/index';
-export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsDispatcher, WsException, WS_SERVER, } from './websocket/index';
-export type { WebSocketModuleOptions, WsClient, WsServer, WsMessage, WsResponse, WsExecutionContext, WsArgumentsHost, BroadcastCommand, SyncDriver, RoomRegistry, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket/index';
+export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, ReservedWsEvent, WsDispatcher, WsException, WS_SERVER, RESERVED_WS_EVENT_PREFIX, } from './websocket/index';
+export type { WebSocketModuleOptions, WsClient, WsServer, WsMessage, WsResponse, ReservedWsEventMetadata, ReservedWsEventHandler, WsExecutionContext, WsArgumentsHost, BroadcastCommand, SyncDriver, RoomRegistry, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket/index';
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator, } from './health/index';
 export type { HealthCheckResult, HealthCheckStatus, HealthIndicatorResult, HealthIndicatorFunction, ResponseCheckCallback, HttpPingOptions, } from './health/index';
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA, } from './throttler/index';

package/dist/index.js

@@ -33,7 +33,7 @@ export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_E
 // Schedule
 export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA } from "./schedule/index.js";
 // WebSocket (edge-safe core; transport-facing internals live at @velajs/vela/websocket)
-export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsDispatcher, WsException, WS_SERVER } from "./websocket/index.js";
+export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, ReservedWsEvent, WsDispatcher, WsException, WS_SERVER, RESERVED_WS_EVENT_PREFIX } from "./websocket/index.js";
 // Health
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator } from "./health/index.js";
 // Throttler

package/dist/live/index.d.ts

@@ -0,0 +1,12 @@
+export { LiveModule } from './live.module';
+export { LiveResolver, LiveQuery, getLiveQueries } from './live.decorators';
+export { LiveEngine, LIVE_SUBS_DATA_KEY, readPersistedLiveSubscriptions } from './live.engine';
+export { LiveInvalidation, localLive, stampCommitHeaders } from './live.invalidation';
+export { InMemoryCursorLog } from './live.cursor';
+export { encodeSubscriptionUpdate } from './live.delta';
+export { PresenceService, PresenceResolver, presenceTag, PRESENCE_ROSTER_QUERY } from './presence';
+export type { PresenceMember } from './presence';
+export { LIVE_DRIVER, LIVE_CURSOR_LOG, LIVE_MODULE_OPTIONS, LIVE_RESOLVER_METADATA, LIVE_QUERY_METADATA, } from './live.tokens';
+export type { CommitStamp, CursorLog, InvalidationCommand, LiveDriver, LiveEntrypointMeta, LiveIdentity, LiveInvalidationSink, LiveModuleOptions, LivePresenceOptions, LiveQueryContext, LiveQueryMetadata, LiveQueryOptions, LiveResolverMetadata, ResumeVerdict, SubscriptionRecord, } from './live.types';
+export { LIVE_PROTOCOL, LIVE_EVENT, LIVE_ERROR_CODES, COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, DEFAULT_KEY_FIELD, encodeLiveEnvelope, encodeLiveFrame, readLiveEnvelope, isClientLiveFrame, isServerLiveFrame, encodeListDelta, applyListDelta, } from '@velajs/live-protocol';
+export type { ClientLiveFrame, LiveFrame, RowOp, ServerLiveFrame } from '@velajs/live-protocol';

package/dist/live/index.js

@@ -0,0 +1,16 @@
+// @velajs/vela/live — first-party live-query subsystem (tag-based realtime
+// reactivity), authored entirely on the public API plus the shared wire
+// package @velajs/live-protocol (the live-openness audit test enforces it).
+// Subpath-only, like @velajs/vela/queue: the main barrel stays lean and the
+// name stays free for platform packages.
+export { LiveModule } from "./live.module.js";
+export { LiveResolver, LiveQuery, getLiveQueries } from "./live.decorators.js";
+export { LiveEngine, LIVE_SUBS_DATA_KEY, readPersistedLiveSubscriptions } from "./live.engine.js";
+export { LiveInvalidation, localLive, stampCommitHeaders } from "./live.invalidation.js";
+export { InMemoryCursorLog } from "./live.cursor.js";
+export { encodeSubscriptionUpdate } from "./live.delta.js";
+export { PresenceService, PresenceResolver, presenceTag, PRESENCE_ROSTER_QUERY } from "./presence.js";
+export { LIVE_DRIVER, LIVE_CURSOR_LOG, LIVE_MODULE_OPTIONS, LIVE_RESOLVER_METADATA, LIVE_QUERY_METADATA } from "./live.tokens.js";
+// The wire contract (frames, delta codec, headers) is re-exported so app code
+// and transports need a single import surface.
+export { LIVE_PROTOCOL, LIVE_EVENT, LIVE_ERROR_CODES, COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER, DEFAULT_KEY_FIELD, encodeLiveEnvelope, encodeLiveFrame, readLiveEnvelope, isClientLiveFrame, isServerLiveFrame, encodeListDelta, applyListDelta } from "@velajs/live-protocol";

package/dist/live/live.cursor.d.ts

@@ -0,0 +1,22 @@
+import type { CommitStamp, CursorLog, ResumeVerdict } from './live.types';
+/**
+ * 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.
+ */
+export 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;
+}

package/dist/live/live.cursor.js

@@ -0,0 +1,56 @@
+const intersects = (a, b)=>a.some((tag)=>b.has(tag));
+/**
+ * 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.
+ */ export class InMemoryCursorLog {
+    maxEntries;
+    epoch = crypto.randomUUID();
+    entries = [];
+    seq = 0;
+    constructor(maxEntries = 1024){
+        this.maxEntries = maxEntries;
+    }
+    append(tags) {
+        this.seq += 1;
+        this.entries.push({
+            seq: this.seq,
+            tags
+        });
+        if (this.entries.length > this.maxEntries) {
+            this.entries.splice(0, this.entries.length - this.maxEntries);
+        }
+        return {
+            cursor: this.seq,
+            epoch: this.epoch
+        };
+    }
+    current() {
+        return {
+            cursor: this.seq,
+            epoch: this.epoch
+        };
+    }
+    evaluateResume(sinceCursor, sinceEpoch, subscriptionTags) {
+        // Forked timeline (restart/reset) — the client's cursor means nothing here.
+        if (sinceEpoch !== this.epoch) return 'snapshot';
+        // Rollback guard: a cursor from the future is unexplainable.
+        if (sinceCursor > this.seq) return 'snapshot';
+        if (sinceCursor === this.seq) return 'resume';
+        // Retention: the ring must still cover (sinceCursor, seq].
+        const oldest = this.entries[0];
+        if (oldest === undefined || oldest.seq > sinceCursor + 1) return 'snapshot';
+        const subTags = new Set(subscriptionTags);
+        for (const entry of this.entries){
+            if (entry.seq <= sinceCursor) continue;
+            if (intersects(entry.tags, subTags)) return 'rerun';
+        }
+        return 'resume';
+    }
+}

package/dist/live/live.decorators.d.ts

@@ -0,0 +1,32 @@
+import type { LiveQueryMetadata, LiveQueryOptions } from './live.types';
+/**
+ * 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`.
+ */
+export 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.
+ */
+export declare function LiveQuery<A = unknown>(name: string, options: LiveQueryOptions<A>): MethodDecorator;
+/** `@LiveQuery` entries declared on a resolver class (declaration order). */
+export declare function getLiveQueries(resolverClass: object): LiveQueryMetadata[];

package/dist/live/live.decorators.js

@@ -0,0 +1,46 @@
+import { createDiscoverableDecorator, defineMetadata, getMetadata } from "../index.js";
+import { LIVE_QUERY_METADATA, LIVE_RESOLVER_METADATA } from "./live.tokens.js";
+const LiveResolverMeta = createDiscoverableDecorator(LIVE_RESOLVER_METADATA);
+/**
+ * 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`.
+ */ export function LiveResolver() {
+    return LiveResolverMeta({});
+}
+/**
+ * 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.
+ */ export function LiveQuery(name, options) {
+    return (target, propertyKey)=>{
+        const ctor = target.constructor;
+        const existing = getMetadata(LIVE_QUERY_METADATA, ctor) ?? [];
+        existing.push({
+            name,
+            methodName: propertyKey,
+            options: options
+        });
+        defineMetadata(LIVE_QUERY_METADATA, existing, ctor);
+    };
+}
+/** `@LiveQuery` entries declared on a resolver class (declaration order). */ export function getLiveQueries(resolverClass) {
+    return getMetadata(LIVE_QUERY_METADATA, resolverClass) ?? [];
+}

package/dist/live/live.delta.d.ts

@@ -0,0 +1,15 @@
+import type { ServerLiveFrame } from '@velajs/live-protocol';
+import type { CommitStamp, SubscriptionRecord } from './live.types';
+/**
+ * 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.
+ */
+export declare function encodeSubscriptionUpdate(record: SubscriptionRecord, json: string, result: unknown, stamp: CommitStamp, initial: boolean): ServerLiveFrame;

package/dist/live/live.delta.js

@@ -0,0 +1,51 @@
+import { DEFAULT_KEY_FIELD, encodeListDelta } from "@velajs/live-protocol";
+/**
+ * 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.
+ */ export function encodeSubscriptionUpdate(record, json, result, stamp, initial) {
+    const settled = {
+        t: 'settled',
+        sub: record.sub,
+        cursor: stamp.cursor,
+        epoch: stamp.epoch
+    };
+    if (!initial && record.lastJson !== undefined) {
+        if (record.lastJson === json) return settled;
+        let previous;
+        let parsed = false;
+        try {
+            previous = JSON.parse(record.lastJson);
+            parsed = true;
+        } catch  {
+        // Unparseable baseline — fall through to a snapshot.
+        }
+        if (parsed) {
+            const ops = encodeListDelta(previous, result, record.key ?? DEFAULT_KEY_FIELD);
+            if (ops !== undefined && ops.length > 0) {
+                return {
+                    t: 'delta',
+                    sub: record.sub,
+                    ops,
+                    cursor: stamp.cursor,
+                    epoch: stamp.epoch
+                };
+            }
+            if (ops !== undefined) return settled;
+        }
+    }
+    return {
+        t: 'data',
+        sub: record.sub,
+        snapshot: result,
+        cursor: stamp.cursor,
+        epoch: stamp.epoch
+    };
+}

package/dist/live/live.engine.d.ts

@@ -0,0 +1,81 @@
+import { Container, DiscoveryService } from '../index';
+import type { ContributesEntrypoints, Entrypoint, OnApplicationBootstrap, ReservedWsEventHandler, WsClient, WsMessage } from '../index';
+import type { CommitStamp, CursorLog, InvalidationCommand, LiveDriver, LiveEntrypointMeta, LiveInvalidationSink, LiveModuleOptions, SubscriptionRecord } from './live.types';
+import { PresenceService } from './presence';
+/**
+ * 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.
+ */
+export declare const LIVE_SUBS_DATA_KEY = "__velaLiveSubs";
+/** Read the subscription records a transport persisted for a connection (wake/restore path). */
+export 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.
+ */
+export 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;
+    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;
+}