@velajs/cloudflare 1.10.0 → 1.10.1

package/dist/storage/storage.tokens.d.ts

@@ -1,3 +0,0 @@
-import { InjectionToken } from '@velajs/vela';
-import type { StorageModuleOptions } from './storage.types';
-export declare const STORAGE_OPTIONS: InjectionToken<StorageModuleOptions>;

package/dist/storage/storage.tokens.js

@@ -1,2 +0,0 @@
-import { InjectionToken } from "@velajs/vela";
-export const STORAGE_OPTIONS = new InjectionToken('STORAGE_OPTIONS');

package/dist/storage/storage.types.d.ts

@@ -1,17 +0,0 @@
-/** A named storage disk backed by an R2 bucket binding. */
-export interface DiskConfig {
-    disk: string;
-    /** R2Bucket binding name from wrangler.toml. */
-    binding: string;
-    /** Optional root prefix; supports path-template tokens ({date}/{year}/…). */
-    root?: string;
-}
-export interface PresignedUrlConfig {
-    defaultExpiry: number;
-    maxExpiry: number;
-}
-export interface StorageModuleOptions {
-    disks: DiskConfig[];
-    defaultDisk: string;
-    presignedUrl?: PresignedUrlConfig;
-}

package/dist/storage/storage.types.js

@@ -1 +0,0 @@
-/** A named storage disk backed by an R2 bucket binding. */ export { };

package/dist/tokens.d.ts

@@ -1,12 +0,0 @@
-import { InjectionToken } from '@velajs/vela';
-import type { BindingRef } from './binding-ref';
-import type { EnvRef } from './env-ref';
-export declare const KV_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const D1_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const R2_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const QUEUE_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const DO_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const AI_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const VECTORIZE_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const HYPERDRIVE_BINDING_REF: InjectionToken<BindingRef<unknown>>;
-export declare const ENV_REF: InjectionToken<EnvRef>;

package/dist/tokens.js

@@ -1,12 +0,0 @@
-import { InjectionToken } from "@velajs/vela";
-// Tokens for binding refs — used by services to receive the binding value.
-export const KV_BINDING_REF = new InjectionToken('CF_KV_BINDING_REF');
-export const D1_BINDING_REF = new InjectionToken('CF_D1_BINDING_REF');
-export const R2_BINDING_REF = new InjectionToken('CF_R2_BINDING_REF');
-export const QUEUE_BINDING_REF = new InjectionToken('CF_QUEUE_BINDING_REF');
-export const DO_BINDING_REF = new InjectionToken('CF_DO_BINDING_REF');
-export const AI_BINDING_REF = new InjectionToken('CF_AI_BINDING_REF');
-export const VECTORIZE_BINDING_REF = new InjectionToken('CF_VECTORIZE_BINDING_REF');
-export const HYPERDRIVE_BINDING_REF = new InjectionToken('CF_HYPERDRIVE_BINDING_REF');
-// Token for the whole-env holder (full c.env), backing EnvService.
-export const ENV_REF = new InjectionToken('CF_ENV_REF');

package/dist/types.d.ts

@@ -1,13 +0,0 @@
-export interface CloudflareEnv {
-    [key: string]: unknown;
-}
-export interface ScheduledRegistration {
-    instance: unknown;
-    methodName: string;
-    cron: string;
-}
-export interface QueueRegistration {
-    instance: unknown;
-    methodName: string;
-    queueName: string;
-}

package/dist/types.js

@@ -1 +0,0 @@
-export { };

package/dist/websocket/broadcast.d.ts

@@ -1,15 +0,0 @@
-/**
- * Push to a room from a Worker HTTP handler / cron / queue consumer (server-
- * initiated emit). Resolves the room's Durable Object and calls its `broadcast`
- * RPC method — the same canonical room→DO mapping the upgrade route uses, so it
- * always reaches the DO holding those sockets.
- *
- * @example
- * ```ts
- * // In a controller — ns from DurableObjectService.namespace
- * await broadcastToRoom(ns, `org:${id}`, 'order.created', order);
- * ```
- */
-export declare function broadcastToRoom(ns: DurableObjectNamespace, room: string, event: string, data?: unknown, options?: {
-    exceptIds?: string[];
-}): Promise<void>;

package/dist/websocket/broadcast.js

@@ -1,26 +0,0 @@
-import { roomToDurableId } from "./room-id.js";
-/**
- * Push to a room from a Worker HTTP handler / cron / queue consumer (server-
- * initiated emit). Resolves the room's Durable Object and calls its `broadcast`
- * RPC method — the same canonical room→DO mapping the upgrade route uses, so it
- * always reaches the DO holding those sockets.
- *
- * @example
- * ```ts
- * // In a controller — ns from DurableObjectService.namespace
- * await broadcastToRoom(ns, `org:${id}`, 'order.created', order);
- * ```
- */ export async function broadcastToRoom(ns, room, event, data, options) {
-    const cmd = {
-        rooms: [
-            room
-        ],
-        exceptIds: options?.exceptIds,
-        frame: JSON.stringify({
-            event,
-            data
-        })
-    };
-    const stub = ns.get(roomToDurableId(ns, room));
-    await stub.broadcast(cmd);
-}

package/dist/websocket/cf-room-registry.d.ts

@@ -1,23 +0,0 @@
-import type { BroadcastCommand, RoomRegistry, WsClient } from '@velajs/vela/websocket';
-import type { DoStateLike, WsLike } from './do-state';
-/**
- * Core `RoomRegistry` backed by a Durable Object's hibernatable sockets. Room
- * membership lives in tags (hub room, set at accept) + the attachment (dynamic
- * `join()`), never in DO instance fields — so it survives hibernation with zero
- * rehydration.
- */
-export declare class CfRoomRegistry implements RoomRegistry {
-    private readonly ctx;
-    constructor(ctx: DoStateLike);
-    register(_client: WsClient): void;
-    leaveAll(_client: WsClient): void;
-    join(client: WsClient, room: string): void | Promise<void>;
-    leave(client: WsClient, room: string): void | Promise<void>;
-    localIdsInRoom(room: string): string[];
-    deliverLocal(cmd: BroadcastCommand): void;
-    private collectRooms;
-    private socketsForRoom;
-    private attachmentOf;
-    /** Reconstruct a `WsClient` for a raw socket (e.g. inside gateway lifecycle scans). */
-    clientFor(ws: WsLike): WsClient;
-}

package/dist/websocket/cf-room-registry.js

@@ -1,65 +0,0 @@
-import { CfWsClient } from "./cf-ws-client.js";
-/**
- * Core `RoomRegistry` backed by a Durable Object's hibernatable sockets. Room
- * membership lives in tags (hub room, set at accept) + the attachment (dynamic
- * `join()`), never in DO instance fields — so it survives hibernation with zero
- * rehydration.
- */ export class CfRoomRegistry {
-    ctx;
-    constructor(ctx){
-        this.ctx = ctx;
-    }
-    // CF sockets are registered with the DO by `acceptWebSocket`; nothing to track.
-    register(_client) {}
-    leaveAll(_client) {}
-    join(client, room) {
-        return client.join(room);
-    }
-    leave(client, room) {
-        return client.leave(room);
-    }
-    localIdsInRoom(room) {
-        return this.socketsForRoom(room).map((ws)=>this.attachmentOf(ws).connId);
-    }
-    deliverLocal(cmd) {
-        const excludeIds = new Set(cmd.exceptIds ?? []);
-        const excludeRooms = cmd.exceptRooms ?? [];
-        // Empty `rooms` => GLOBAL (every socket in this DO). Otherwise the union of
-        // targeted rooms, deduped per connection.
-        const targets = cmd.rooms.length === 0 ? this.ctx.getWebSockets() : this.collectRooms(cmd.rooms);
-        const seen = new Set();
-        for (const ws of targets){
-            const att = this.attachmentOf(ws);
-            if (seen.has(att.connId)) continue;
-            seen.add(att.connId);
-            if (excludeIds.has(att.connId)) continue;
-            if (excludeRooms.some((r)=>att.rooms.includes(r))) continue;
-            ws.send(cmd.frame);
-        }
-    }
-    collectRooms(rooms) {
-        const set = new Set();
-        for (const room of rooms)for (const ws of this.socketsForRoom(room))set.add(ws);
-        return [
-            ...set
-        ];
-    }
-    socketsForRoom(room) {
-        // Membership is the attachment's `rooms`, NOT the hibernation tag: tags are
-        // immutable after acceptWebSocket, so a socket that left its hub room still
-        // carries the tag. Since one DO ≈ one room, scanning all sockets in the DO
-        // and filtering by attachment is both correct and cheap.
-        return this.ctx.getWebSockets().filter((ws)=>this.attachmentOf(ws).rooms.includes(room));
-    }
-    attachmentOf(ws) {
-        return ws.deserializeAttachment() ?? {
-            connId: '',
-            path: '',
-            rooms: [],
-            data: {}
-        };
-    }
-    /** Reconstruct a `WsClient` for a raw socket (e.g. inside gateway lifecycle scans). */ clientFor(ws) {
-        return new CfWsClient(this.ctx, ws);
-    }
-}

package/dist/websocket/cf-ws-client.d.ts

@@ -1,28 +0,0 @@
-import type { WsClient } from '@velajs/vela/websocket';
-import type { DoStateLike, WsLike } from './do-state';
-/**
- * Core `WsClient` over a native Cloudflare `WebSocket` inside a Durable Object.
- * Per-connection state lives in the hibernation attachment (survives eviction),
- * so a fresh `CfWsClient` is reconstructed per message with no in-memory state.
- */
-export declare class CfWsClient<TData extends Record<string, unknown> = Record<string, unknown>> implements WsClient<TData> {
-    private readonly ctx;
-    private readonly ws;
-    private readonly attachment;
-    constructor(ctx: DoStateLike, ws: WsLike);
-    get id(): string;
-    /** The gateway route path this socket connected on (used to route messages). */
-    get path(): string;
-    get rooms(): ReadonlySet<string>;
-    get data(): TData;
-    set data(value: TData);
-    get raw(): unknown;
-    send(event: string, data?: unknown, id?: string): void;
-    sendRaw(payload: string): void;
-    join(room: string): void;
-    leave(room: string): void;
-    /** Persist `data`/room mutations to the hibernation attachment. */
-    commit(): void;
-    close(code?: number, reason?: string): void;
-    private persist;
-}

package/dist/websocket/cf-ws-client.js

@@ -1,83 +0,0 @@
-const MAX_ATTACHMENT_BYTES = 16_384; // Cloudflare hibernation attachment limit (16 KiB).
-const encoder = new TextEncoder();
-const EMPTY = {
-    connId: '',
-    path: '',
-    rooms: [],
-    data: {}
-};
-/**
- * Core `WsClient` over a native Cloudflare `WebSocket` inside a Durable Object.
- * Per-connection state lives in the hibernation attachment (survives eviction),
- * so a fresh `CfWsClient` is reconstructed per message with no in-memory state.
- */ export class CfWsClient {
-    ctx;
-    ws;
-    attachment;
-    constructor(ctx, ws){
-        this.ctx = ctx;
-        this.ws = ws;
-        const raw = ws.deserializeAttachment();
-        this.attachment = raw ?? {
-            ...EMPTY,
-            data: {}
-        };
-    }
-    get id() {
-        return this.attachment.connId;
-    }
-    /** The gateway route path this socket connected on (used to route messages). */ get path() {
-        return this.attachment.path;
-    }
-    get rooms() {
-        return new Set(this.attachment.rooms);
-    }
-    get data() {
-        return this.attachment.data;
-    }
-    set data(value) {
-        this.attachment.data = value;
-    }
-    get raw() {
-        return this.ws;
-    }
-    send(event, data, id) {
-        this.ws.send(JSON.stringify(id !== undefined ? {
-            id,
-            event,
-            data
-        } : {
-            event,
-            data
-        }));
-    }
-    sendRaw(payload) {
-        this.ws.send(payload);
-    }
-    join(room) {
-        if (!this.attachment.rooms.includes(room)) {
-            this.attachment.rooms.push(room);
-            this.persist();
-        }
-    }
-    leave(room) {
-        const next = this.attachment.rooms.filter((r)=>r !== room);
-        if (next.length !== this.attachment.rooms.length) {
-            this.attachment.rooms = next;
-            this.persist();
-        }
-    }
-    /** Persist `data`/room mutations to the hibernation attachment. */ commit() {
-        this.persist();
-    }
-    close(code, reason) {
-        this.ws.close(code, reason);
-    }
-    persist() {
-        const serialized = JSON.stringify(this.attachment);
-        if (encoder.encode(serialized).length > MAX_ATTACHMENT_BYTES) {
-            throw new Error(`WebSocket attachment exceeds the 16 KiB Cloudflare limit. Store large ` + `per-connection state in Durable Object storage keyed by connId instead.`);
-        }
-        this.ws.serializeAttachment(this.attachment);
-    }
-}

package/dist/websocket/cloudflare-websocket.module.d.ts

@@ -1,11 +0,0 @@
-import type { DynamicModule } from '@velajs/vela';
-/**
- * Cloudflare counterpart to the core `WebSocketModule.forRoot()`. Import this in
- * your `AppModule` instead: it provides the gateway dispatcher plus a late-bound
- * `WS_SERVER` (`WsServerHolder`) that the WebSocket Durable Object wires to a
- * ctx-backed server per instance. `useClass` ensures a fresh holder per DI
- * container so colocated DO instances never share a server.
- */
-export declare class CloudflareWebSocketModule {
-    static forRoot(): DynamicModule;
-}

package/dist/websocket/cloudflare-websocket.module.js

@@ -1,27 +0,0 @@
-import { WsDispatcher, WS_SERVER } from "@velajs/vela/websocket";
-import { WsServerHolder } from "./ws-server-holder.js";
-/**
- * Cloudflare counterpart to the core `WebSocketModule.forRoot()`. Import this in
- * your `AppModule` instead: it provides the gateway dispatcher plus a late-bound
- * `WS_SERVER` (`WsServerHolder`) that the WebSocket Durable Object wires to a
- * ctx-backed server per instance. `useClass` ensures a fresh holder per DI
- * container so colocated DO instances never share a server.
- */ export class CloudflareWebSocketModule {
-    static forRoot() {
-        const providers = [
-            {
-                provide: WS_SERVER,
-                useClass: WsServerHolder
-            },
-            WsDispatcher
-        ];
-        return {
-            module: CloudflareWebSocketModule,
-            providers,
-            exports: [
-                WS_SERVER,
-                WsDispatcher
-            ]
-        };
-    }
-}

package/dist/websocket/do-bootstrap.d.ts

@@ -1,24 +0,0 @@
-import type { Type } from '@velajs/vela';
-import { WsDispatcher } from '@velajs/vela/websocket';
-import type { WsServer } from '@velajs/vela/websocket';
-import type { LiveEngine } from '@velajs/vela/live';
-import { CfRoomRegistry } from './cf-room-registry';
-import type { DoStateLike } from './do-state';
-export interface DoRuntime {
-    dispatcher: WsDispatcher;
-    registry: CfRoomRegistry;
-    server: WsServer;
-    /** Gateway paths from `app.entrypoints.ofKind('websocket')` (discovery order). */
-    gatewayPaths: string[];
-    /** The live-query engine (undefined when the app doesn't import LiveModule). */
-    live?: LiveEngine;
-    close(signal?: string): Promise<void>;
-}
-/**
- * Slim DI bootstrap for the Durable Object isolate: wires the container and runs
- * `OnModuleInit`/`OnApplicationBootstrap` (so `WsDispatcher` discovers gateways)
- * WITHOUT building the Hono app/routes the DO never serves. Cloudflare binding
- * refs are initialized straight from the DO's `env`, and the ctx-backed server
- * is bound before bootstrap lifecycle so gateway `afterInit`/handlers see it.
- */
-export declare function buildDoRuntime(rootModule: Type, ctx: DoStateLike, env: Record<string, unknown>): Promise<DoRuntime>;

package/dist/websocket/do-bootstrap.js

@@ -1,55 +0,0 @@
-import { bootstrap, VelaApplication } from "@velajs/vela";
-import { local, WsDispatcher, WsServerImpl, WS_SERVER } from "@velajs/vela/websocket";
-import { BindingRef } from "../binding-ref.js";
-import { EnvRef } from "../env-ref.js";
-import { CfRoomRegistry } from "./cf-room-registry.js";
-import { initDoLive } from "./do-live.js";
-import { WsServerHolder } from "./ws-server-holder.js";
-/**
- * Slim DI bootstrap for the Durable Object isolate: wires the container and runs
- * `OnModuleInit`/`OnApplicationBootstrap` (so `WsDispatcher` discovers gateways)
- * WITHOUT building the Hono app/routes the DO never serves. Cloudflare binding
- * refs are initialized straight from the DO's `env`, and the ctx-backed server
- * is bound before bootstrap lifecycle so gateway `afterInit`/handlers see it.
- */ export async function buildDoRuntime(rootModule, ctx, env) {
-    const { container, routeManager, loader } = await bootstrap(rootModule);
-    // Init binding refs from env directly (no request middleware inside a DO).
-    // Enumerate per-instance useValue providers across ALL module buckets — two
-    // same-type binding modules share one token but live in distinct buckets, so
-    // resolving the token would return only the first and leave the rest uninitialized.
-    for (const value of container.getUseValues()){
-        if (value instanceof EnvRef) value._initialize(env);
-        else if (value instanceof BindingRef) value._initialize(env[value.bindingName]);
-    }
-    const registry = new CfRoomRegistry(ctx);
-    const driver = local();
-    driver.bind(registry);
-    const server = new WsServerImpl(driver);
-    try {
-        const holder = container.resolve(WS_SERVER);
-        if (holder instanceof WsServerHolder) holder.setTarget(server);
-    } catch  {
-    // CloudflareWebSocketModule not imported — gateways won't have a server.
-    }
-    const app = new VelaApplication(container, routeManager);
-    app.setInstances(await loader.resolveAllInstances());
-    await app.callOnModuleInit();
-    await app.callOnApplicationBootstrap();
-    // The entrypoint registry is the transport contract: one 'websocket' entry
-    // per discovered gateway ({ meta: { path, dispatcher } }). Built by
-    // callOnApplicationBootstrap(), so this slim no-routes path has it too.
-    const wsEntrypoints = app.entrypoints.ofKind('websocket');
-    // Live queries: wire the SQLite cursor log + local driver mode and replay
-    // hibernation-persisted subscriptions into the fresh engine.
-    const live = initDoLive(app, container, ctx);
-    return {
-        // Zero gateways still yields a live dispatcher (module imported, nothing
-        // decorated) — fall back to resolving it directly.
-        dispatcher: wsEntrypoints[0]?.meta.dispatcher ?? app.get(WsDispatcher),
-        registry,
-        server,
-        gatewayPaths: wsEntrypoints.map((ep)=>ep.meta.path),
-        live,
-        close: (signal)=>app.close(signal)
-    };
-}

package/dist/websocket/do-live.d.ts

@@ -1,81 +0,0 @@
-import type { Container } from '@velajs/vela';
-import type { CommitStamp, CursorLog, LiveDriver, LiveEngine, ResumeVerdict } from '@velajs/vela/live';
-import type { DoStateLike, SqlStorageLike } from './do-state';
-/**
- * The durable `CursorLog`: an append-only tag-invalidation log in the DO's
- * SQLite (`__vela_live_log`, AUTOINCREMENT seq = cursor) plus an epoch UUID in
- * `__vela_live_meta`. Because the cursor survives hibernation AND trims (it is
- * read from `sqlite_sequence`, lunora's `ctx-db-cdc.ts` trick), a reconnecting
- * client whose gap the log still covers gets a tiny `resume` instead of a
- * re-run — the real-resume half of the live protocol.
- *
- * Constructed un-initialized at module-composition time (the same app module
- * bootstraps in the Worker AND in each DO); `initDoLive` wires the SQLite
- * handle inside the DO. In the Worker isolate it stays un-initialized — and is
- * never consulted there, because `durableObjectLive()` routes every
- * invalidation to the room DO's log (one log scope per room, exactly the
- * protocol's model).
- */
-export declare class DoCursorLog implements CursorLog {
-    private readonly maxRows;
-    private sql?;
-    private epoch?;
-    constructor(maxRows?: number);
-    /** @internal — called by `initDoLive` with the DO's `ctx.storage.sql`. */
-    _initialize(sql: SqlStorageLike): void;
-    append(tags: string[]): CommitStamp;
-    current(): CommitStamp;
-    evaluateResume(sinceCursor: number, sinceEpoch: string, subscriptionTags: string[]): ResumeVerdict;
-    private assertReady;
-}
-export interface DurableObjectLiveOptions {
-    /** The wrangler binding name of the WebSocket DO namespace (e.g. `'CHAT_ROOM'`). */
-    binding: string;
-    /** Room used when an invalidation names none. Matches the client default. */
-    defaultRoom?: string;
-}
-export interface CfLiveDriver extends LiveDriver {
-    /** @internal — Worker isolate: capture `env` so the namespace binding resolves per dispatch. */
-    _initializeEnv(env: Record<string, unknown>): void;
-    /** @internal — DO isolate: deliver invalidations straight to this DO's engine. */
-    _setLocalMode(): void;
-}
-/**
- * The Cloudflare `LiveDriver`. Dual-mode, because the SAME app module
- * bootstraps in both isolates:
- *
- * - **Worker** (HTTP mutations, queue consumers, crons): route the command to
- *   the room's Durable Object over the `invalidate` RPC — the same canonical
- *   `roomToDurableId` mapping the upgrade route and `broadcastToRoom` use —
- *   and return THAT log scope's commit stamp (what `Vela-Commit-Cursor`
- *   must carry).
- * - **DO** (writes issued from inside the object): apply to the local engine.
- */
-export declare function durableObjectLive(options: DurableObjectLiveOptions): CfLiveDriver;
-/** Worker-side wiring, called from `cloudflareAdapter`'s first-request middleware. */
-export declare function initializeWorkerLive(container: Container, env: Record<string, unknown>): void;
-/** The app-facing surface of the engine reached through `app.entrypoints.ofKind('live')`. */
-interface EntrypointsApp {
-    entrypoints: {
-        ofKind<M>(kind: string): Array<{
-            meta: M;
-        }>;
-    };
-}
-/**
- * DO-side wiring, called from `buildDoRuntime`: initialize the SQLite cursor
- * log, flip the driver to local mode, and replay every hibernation-persisted
- * subscription into the (fresh) engine so an eviction is invisible to
- * subscribers. Returns the engine for the `invalidate` RPC, or undefined when
- * the app doesn't use LiveModule.
- */
-export declare function initDoLive(app: EntrypointsApp, container: Container, ctx: DoStateLike): LiveEngine | undefined;
-/** Ergonomic alias: the log option for `LiveModule.forRoot` on Cloudflare. */
-export declare function durableObjectCursorLog(maxRows?: number): DoCursorLog;
-/**
- * Invalidate live tags in a room from a Worker (controller / cron / queue
- * consumer) — the live sibling of `broadcastToRoom`. Returns the room log
- * scope's commit stamp for `Vela-Commit-Cursor` stamping.
- */
-export declare function liveInvalidateToRoom(ns: DurableObjectNamespace, room: string, tags: string[]): Promise<CommitStamp | undefined>;
-export {};