@velajs/cloudflare 1.29.0 → 1.30.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.30.0
+
+### Minor Changes
+
+- 44023fc: `@velajs/cloudflare` exports only the Cloudflare adapter and its platform pieces, so each framework API has one import path. It requires `@velajs/vela` with the tiered entry points and imports its seams from `@velajs/vela/module-kit`, `@velajs/vela/schedule` and the other feature subpaths.
+  
+  The package now publishes one JavaScript module per source file instead of shared chunks, so a bundler drops the features a Worker never imports. A shared chunk kept every decorated class it held, so a Worker that only calls `createCloudflareWorker()` shipped the storage module with the signed-URL crypto its controller uses, the KV and feature-flag drivers and the Durable Object host; it no longer does, which takes 6,975 bytes gzipped off that minimal Worker. Entry points, exports and type declarations are unchanged.
+  
+  **Behavior change:** the WebSocket gateway API is no longer re-exported from `@velajs/cloudflare`. Import it from `@velajs/vela/websocket`:
+  
+  | Old import | New import | Names |
+  |---|---|---|
+  | `@velajs/cloudflare` | `@velajs/vela/websocket` | `ConnectedSocket`, `MessageBody`, `OnGatewayConnection`, `OnGatewayDisconnect`, `OnGatewayInit`, `SubscribeMessage`, `UpgradeAuthenticator`, `WebSocketGateway`, `WebSocketServer`, `WebSocketUpgradeAuthenticationContext`, `WebSocketUpgradeIdentity`, `WsClient`, `WsException`, `WsMessage`, `WsResponse`, `WsServer` |
+
+### Patch Changes
+
+- Updated dependencies [4d0342b]
+- Updated dependencies [4467619]
+- Updated dependencies [7372d90]
+- Updated dependencies [c101033]
+- Updated dependencies [4d0342b]
+  - @velajs/feature-flags@1.30.0
+  - @velajs/vela@1.30.0
+
 ## 1.29.0
 
 ### Minor Changes

package/README.md

@@ -254,7 +254,8 @@ queue, cron and Durable Object code.
 ## Queues and cron
 
 ```ts
-import { Cron, InjectEnv, Injectable, type CronInvocation, type VelaEnv } from '@velajs/vela';
+import { InjectEnv, Injectable, type VelaEnv } from '@velajs/vela';
+import { Cron, type CronInvocation } from '@velajs/vela/schedule';
 import { QueueConsumer } from '@velajs/cloudflare';
 
 @Injectable()

package/dist/_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js

@@ -0,0 +1,9 @@
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+export { __decorate as default };

package/dist/_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorateMetadata.js

@@ -0,0 +1,6 @@
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+export { __decorateMetadata as default };

package/dist/_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorateParam.js

@@ -0,0 +1,8 @@
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+export { __decorateParam as default };

package/dist/cloudflare-application.js

@@ -0,0 +1,309 @@
+import { collectWsGatewayRoutes } from "./websocket/websocket-routing.js";
+import { assertCloudflareEnvironment } from "./environment.js";
+import { CLOUDFLARE_SCHEDULED_EVENT, cloudflareScheduledEvent } from "./scheduled-event.js";
+import { PipelineRunner, buildEntrypointExecutionContext, getEntrypointModuleId, invokeScheduledJob, parseCronMetadata, resolveEntrypoint, resolveErrorReporter, resolveScopedComponentsAsync, runInEntrypointScope, shouldFilterCatch } from "@velajs/vela/module-kit";
+import { readWsEntrypointMeta } from "@velajs/vela/websocket";
+//#region src/cloudflare-application.ts
+function invoke(instance, methodName, args) {
+	const method = Reflect.get(instance, methodName);
+	if (typeof method !== "function") throw new Error(`Method '${String(methodName)}' is not a function on ${instance.constructor.name}`);
+	return Reflect.apply(method, instance, args);
+}
+function entrypointString(meta, property) {
+	if (typeof meta !== "object" || meta === null) throw new Error("Invalid entrypoint metadata.");
+	const value = Reflect.get(meta, property);
+	if (typeof value !== "string") throw new Error(`Invalid entrypoint metadata: ${property} must be a string.`);
+	return value;
+}
+/**
+* `QueueModule`'s native consumer reports each failure of a batch once itself
+* (processor failures where they ran, transport failures on settlement), so
+* its rejection is not reported again here.
+*/
+const SELF_REPORTING_KINDS = /* @__PURE__ */ new Set(["cf:queue:module"]);
+const warnedRawJobs = /* @__PURE__ */ new Set();
+/** The logical queue of a Vela job envelope, without importing the queue subsystem. */
+function envelopeQueue(body) {
+	if (typeof body !== "object" || body === null) return void 0;
+	const queue = Reflect.get(body, "queue");
+	if (typeof queue !== "string" || typeof Reflect.get(body, "id") !== "string" || typeof Reflect.get(body, "name") !== "string" || !("data" in body)) return;
+	return queue;
+}
+/** Wait for every matching handler, even when one fails before its siblings. */
+async function settleEntrypoints(work) {
+	const errors = (await Promise.allSettled(work)).flatMap((outcome) => outcome.status === "rejected" ? [outcome.reason] : []);
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Multiple entrypoint handlers failed.");
+}
+/**
+* Wraps VelaApplication with Cloudflare-specific handlers:
+* - `fetch` — HTTP request handler (from Hono)
+* - `scheduled` — Cron trigger handler (runs the `@Cron()` jobs whose
+*                 expression is the trigger's exact string)
+* - `queue` — Queue consumer handler (`@QueueConsumer()` by physical queue,
+*             then `QueueModule`'s native consumer)
+* - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
+*                    the underlying Hono app
+*
+* @example
+* ```ts
+* const app = await createCloudflareApp(AppModule, { env });
+* export default {
+*   fetch: app.fetch,
+*   scheduled: app.scheduled.bind(app),
+*   queue: app.queue.bind(app),
+* };
+* ```
+*
+* @example
+* ```ts
+* // Serve OpenAPI docs alongside your routes
+* const app = await createCloudflareApp(AppModule, { env });
+* const document = createOpenApiDocument(AppModule);
+* app.mountOpenApi({ document, ui: 'scalar' });
+* // GET /openapi.json -> JSON document
+* // GET /scalar       -> Scalar UI (loads from CDN)
+* ```
+*/
+var CloudflareApplication = class {
+	env;
+	#wsGatewayRoutes = [];
+	#app;
+	/** Scheduled triggers in flight; close() aborts their signals and awaits them. */
+	#scheduled = /* @__PURE__ */ new Map();
+	constructor(app, env) {
+		this.env = env;
+		this.#app = app;
+		this.get = app.get.bind(app);
+	}
+	fetch = async (request, env, ctx) => {
+		assertCloudflareEnvironment(this.env, env);
+		return this.#app.fetch(request, env, ctx);
+	};
+	getHonoApp() {
+		return this.#app.getHonoApp();
+	}
+	/**
+	* Resolve a provider from the application's DI container (delegates to
+	* `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —
+	* to use inside `createCloudflareApp({ middleware: env => [...] })` request middleware,
+	* which runs outside the DI request pipeline.
+	*
+	* @example
+	* ```ts
+	* const app = await createCloudflareApp(AppModule, { env });
+	* const auth = app.get(BetterAuthService);
+	* ```
+	*/
+	get;
+	get entrypoints() {
+		return this.#app.entrypoints;
+	}
+	/**
+	* Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
+	* underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,
+	* so the JSON endpoint defaults to `/openapi.json` and the Scalar UI (when
+	* opted in) defaults to `/scalar`. Edge-safe — the UI HTML loads Scalar from
+	* a CDN at runtime, nothing is bundled server-side.
+	*
+	* @example
+	* ```ts
+	* import { createOpenApiDocument } from '@velajs/vela/openapi';
+	*
+	* const app = await createCloudflareApp(AppModule, { env });
+	* const document = createOpenApiDocument(AppModule, {
+	*   info: { title: 'My API', version: '1.0.0' },
+	* });
+	* app.mountOpenApi({ document, ui: 'scalar' });
+	* // GET /openapi.json -> { openapi: '3.1.0', ... }
+	* // GET /scalar       -> Scalar UI HTML
+	* ```
+	*/
+	mountOpenApi(options) {
+		this.#app.mountOpenApi(options);
+		return this;
+	}
+	/**
+	* @internal Upgrade routes come from validated gateway entrypoints, including
+	* request-scoped gateways without a bootstrap instance. Retain the instance
+	* scan for legacy applications that only declare forwarding metadata.
+	*/
+	scanInstances(instances) {
+		const routes = /* @__PURE__ */ new Map();
+		for (const ep of this.#app.entrypoints.ofKind("websocket")) {
+			if (typeof ep.meta !== "object" || ep.meta === null || !("dispatcher" in ep.meta)) continue;
+			const meta = readWsEntrypointMeta(ep.meta);
+			if (meta.options.binding) routes.set(meta.path, {
+				path: meta.path,
+				binding: meta.options.binding,
+				options: { ...meta.options },
+				moduleId: meta.moduleId
+			});
+		}
+		const container = this.#app.getContainer();
+		for (const instance of instances) {
+			if (!instance || typeof instance !== "object") continue;
+			for (const route of collectWsGatewayRoutes(instance, container)) if (!routes.has(route.path)) routes.set(route.path, route);
+		}
+		this.#wsGatewayRoutes.splice(0, this.#wsGatewayRoutes.length, ...routes.values());
+	}
+	/** @internal — upgrade routes discovered from the application's gateways. */
+	getWsGatewayRoutes() {
+		return [...this.#wsGatewayRoutes];
+	}
+	/**
+	* Handle a Cloudflare cron trigger. Runs every core `@Cron()` job whose
+	* expression is exactly `event.cron` (the trigger string is compared as
+	* delivered, never re-evaluated) through `invokeScheduledJob`, the dispatch
+	* primitive every runtime shares. Each job receives only its
+	* `ScheduleInvocation`, runs in a fresh invocation scope seeded with
+	* {@link CLOUDFLARE_SCHEDULED_EVENT}, and honors signed `ScheduleModule`
+	* dispatch. The trigger settles after every matching job and its managed
+	* work (`EXECUTION_LIFETIME.waitUntil`/`defer`) settle; failures reject it.
+	*/
+	async scheduled(event, env, _ctx) {
+		assertCloudflareEnvironment(this.env, env);
+		const jobs = this.#app.entrypoints.ofKind("schedule:cron", parseCronMetadata).filter((entry) => entry.meta.expression === event.cron);
+		if (jobs.length === 0) return;
+		const controller = new AbortController();
+		const scheduledTime = event.scheduledTime ?? Date.now();
+		const invocation = Object.freeze({
+			kind: "cron",
+			expression: event.cron,
+			scheduledTime,
+			signal: controller.signal
+		});
+		const trigger = cloudflareScheduledEvent(event, scheduledTime);
+		const container = this.#app.getContainer();
+		const running = settleEntrypoints(jobs.map((entry) => invokeScheduledJob(container, entry, invocation, { seed: (scope) => scope.setRequestInstance(CLOUDFLARE_SCHEDULED_EVENT, trigger) })));
+		this.#scheduled.set(running, controller);
+		try {
+			await running;
+		} finally {
+			this.#scheduled.delete(running);
+		}
+	}
+	/**
+	* Run one queue consumer inside a fresh request scope, through the shared
+	* guard → interceptor pipeline (components declared with
+	* `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+	* method). HTTP-global components deliberately do NOT apply — an HTTP auth
+	* guard has no business rejecting a queue batch. Unclaimed errors are
+	* reported once (`QueueModule`'s consumer reports its own) and rethrow so
+	* the platform's retry semantics stay intact.
+	*/
+	async dispatchEntrypoint(ep, payload, env, platformContext) {
+		const targetClass = ep.token;
+		if (typeof targetClass !== "function") throw new Error("Entrypoint token must be a class.");
+		if (ep.methodName === void 0) throw new Error("Entrypoint must declare a handler method.");
+		const methodName = ep.methodName;
+		const reportContext = {
+			edge: "queue",
+			source: `${targetClass.name}.${String(methodName)}`
+		};
+		let reported;
+		let delegated;
+		try {
+			await runInEntrypointScope(this.#app.getContainer(), async (scope, lifetime) => {
+				const moduleId = getEntrypointModuleId(scope, ep);
+				const context = buildEntrypointExecutionContext(ep.kind, targetClass, methodName, payload, moduleId, scope);
+				const invocationContext = { waitUntil(promise) {
+					lifetime.waitUntil(promise);
+					platformContext.waitUntil(promise);
+				} };
+				let filters = [];
+				try {
+					filters = (await resolveScopedComponentsAsync("filter", targetClass, methodName, scope, moduleId)).toReversed();
+					const guards = await resolveScopedComponentsAsync("guard", targetClass, methodName, scope, moduleId);
+					const interceptors = await resolveScopedComponentsAsync("interceptor", targetClass, methodName, scope, moduleId);
+					await PipelineRunner.run({
+						context,
+						guards,
+						interceptors,
+						resolveArgs: async () => [
+							payload,
+							env,
+							invocationContext
+						],
+						invoke: async (args) => {
+							const instance = await resolveEntrypoint(scope, ep);
+							if (typeof instance !== "object" || instance === null) throw new Error("Entrypoint must resolve to an object.");
+							try {
+								return await invoke(instance, methodName, args);
+							} catch (error) {
+								if (SELF_REPORTING_KINDS.has(ep.kind)) delegated = { error };
+								throw error;
+							}
+						}
+					});
+				} catch (error) {
+					if (delegated?.error !== error) resolveErrorReporter(scope).report(error, reportContext);
+					for (const filter of filters) if (shouldFilterCatch(filter, error)) {
+						await filter.catch(error, context);
+						return;
+					}
+					reported = { error };
+					throw error;
+				}
+			});
+		} catch (error) {
+			if (!reported || reported.error !== error) {
+				const completionError = reported && error instanceof AggregateError && error.errors[0] === reported.error ? error.errors[1] : error;
+				resolveErrorReporter(this.#app.getContainer()).report(completionError, reportContext);
+			}
+			throw error;
+		}
+	}
+	/**
+	* Handle Cloudflare Queue consumer events. `@QueueConsumer()` handlers read
+	* from `app.entrypoints` claim a batch by its physical queue name and
+	* receive it whole. A batch no handler claims goes to `QueueModule`'s native
+	* consumer (`cloudflareQueues()` from `@velajs/cloudflare/queues`), which
+	* routes each job by its logical queue. Each dispatch runs inside a fresh
+	* request-scoped child (request-scoped providers rebuild per batch — no
+	* boot-time captives). A batch nothing claims rejects: resolving would let
+	* Cloudflare acknowledge every message implicitly.
+	*/
+	async queue(batch, env, ctx) {
+		assertCloudflareEnvironment(this.env, env);
+		const raw = this.#app.entrypoints.ofKind("cf:queue").filter((ep) => entrypointString(ep.meta, "queueName") === batch.queue);
+		if (raw.length > 0) this.warnRawJobs(batch);
+		const handlers = raw.length > 0 ? raw : this.#app.entrypoints.ofKind("cf:queue:module");
+		if (handlers.length === 0) throw new Error(`No consumer claims queue '${batch.queue}'. Add @QueueConsumer('${batch.queue}') to a provider, or deliver it through QueueModule.forRoot({ driver: cloudflareQueues() }) with a QueueModule.registerQueue() for each queue it carries. The batch is rejected unacknowledged, so Cloudflare retries it and then routes it to the configured dead-letter queue.`);
+		await settleEntrypoints(handlers.map((ep) => this.dispatchEntrypoint(ep, batch, env, ctx)));
+	}
+	/**
+	* A raw `@QueueConsumer` owns its physical queue's batches and must not carry
+	* jobs of a queue registered with `QueueModule`: those reach their
+	* `@Processor` only if the raw handler dispatches them itself, while
+	* `cloudflareQueues()` delivers registered queues. Warn once per physical and
+	* logical queue (unless diagnostics are silent); the raw consumer still
+	* receives and settles the batch.
+	*/
+	warnRawJobs(batch) {
+		if (this.#app.getContainer().getDiagnostics() === "silent") return;
+		const registered = new Set(this.#app.entrypoints.ofKind("queue:registration").map((entry) => typeof entry.meta === "object" && entry.meta !== null ? Reflect.get(entry.meta, "name") : void 0));
+		if (registered.size === 0) return;
+		for (const message of batch.messages) {
+			const queue = envelopeQueue(typeof message === "object" && message !== null ? Reflect.get(message, "body") : void 0);
+			if (queue === void 0 || !registered.has(queue)) continue;
+			const warning = `[vela] @QueueConsumer('${batch.queue}') received jobs of registered queue '${queue}'. The raw consumer owns '${batch.queue}' and must not carry jobs of registered queues: they reach @Processor('${queue}') only if the raw handler dispatches them itself. Deliver '${queue}' through cloudflareQueues() instead: send it to a physical queue that no @QueueConsumer claims.`;
+			if (warnedRawJobs.has(warning)) continue;
+			warnedRawJobs.add(warning);
+			console.warn(warning);
+		}
+	}
+	/**
+	* Abort the signals of scheduled jobs still running, wait for them and their
+	* managed work to settle, then close the application.
+	*/
+	async close(signal) {
+		for (const controller of this.#scheduled.values()) controller.abort();
+		await Promise.allSettled(this.#scheduled.keys());
+		return this.#app.close(signal);
+	}
+};
+//#endregion
+export { CloudflareApplication };
+
+//# sourceMappingURL=cloudflare-application.js.map

package/dist/cloudflare-application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-application.js","names":[],"sources":["../src/cloudflare-application.ts"],"sourcesContent":["import type { ExecutionContext } from 'hono';\nimport type { VelaApplication, ExceptionFilter, VelaEnv } from '@velajs/vela';\nimport {\n  PipelineRunner,\n  buildEntrypointExecutionContext,\n  getEntrypointModuleId,\n  invokeScheduledJob,\n  parseCronMetadata,\n  resolveEntrypoint,\n  resolveScopedComponentsAsync,\n  resolveErrorReporter,\n  runInEntrypointScope,\n  shouldFilterCatch,\n} from '@velajs/vela/module-kit';\nimport type { ScheduleInvocation } from '@velajs/vela/schedule';\nimport type { Entrypoint } from '@velajs/vela/module-kit';\nimport { readWsEntrypointMeta } from '@velajs/vela/websocket';\nimport { collectWsGatewayRoutes, type WsGatewayRoute } from './websocket/websocket-routing';\nimport { assertCloudflareEnvironment } from './environment';\nimport {\n  CLOUDFLARE_SCHEDULED_EVENT,\n  cloudflareScheduledEvent,\n  type ScheduledEvent,\n} from './scheduled-event';\n\n/**\n * Options accepted by {@link CloudflareApplication.mountOpenApi}.\n *\n * Re-exposes vela's `MountOpenApiOptions` type — derived structurally from\n * the underlying `VelaApplication.mountOpenApi` signature so consumers don't\n * have to reach into vela's internal subpaths to type the argument.\n */\nexport type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0];\n\nfunction invoke(instance: object, methodName: string | symbol, args: unknown[]): unknown {\n  // Decorator metadata names an instance method; inspect it before invoking.\n  const method: unknown = Reflect.get(instance, methodName);\n  if (typeof method !== 'function') {\n    throw new Error(\n      `Method '${String(methodName)}' is not a function on ${instance.constructor.name}`,\n    );\n  }\n  return Reflect.apply(method, instance, args);\n}\n\nfunction entrypointString(meta: unknown, property: string): string {\n  if (typeof meta !== 'object' || meta === null) throw new Error('Invalid entrypoint metadata.');\n  const value: unknown = Reflect.get(meta, property);\n  if (typeof value !== 'string')\n    throw new Error(`Invalid entrypoint metadata: ${property} must be a string.`);\n  return value;\n}\n\n/**\n * `QueueModule`'s native consumer reports each failure of a batch once itself\n * (processor failures where they ran, transport failures on settlement), so\n * its rejection is not reported again here.\n */\nconst SELF_REPORTING_KINDS = new Set(['cf:queue:module']);\n\nconst warnedRawJobs = new Set<string>();\n\n/** The logical queue of a Vela job envelope, without importing the queue subsystem. */\nfunction envelopeQueue(body: unknown): string | undefined {\n  if (typeof body !== 'object' || body === null) return undefined;\n  const queue: unknown = Reflect.get(body, 'queue');\n  if (\n    typeof queue !== 'string' ||\n    typeof Reflect.get(body, 'id') !== 'string' ||\n    typeof Reflect.get(body, 'name') !== 'string' ||\n    !('data' in body)\n  ) {\n    return undefined;\n  }\n  return queue;\n}\n\n/** Wait for every matching handler, even when one fails before its siblings. */\nasync function settleEntrypoints(work: readonly Promise<void>[]): Promise<void> {\n  const outcomes = await Promise.allSettled(work);\n  const errors = outcomes.flatMap((outcome) =>\n    outcome.status === 'rejected' ? [outcome.reason] : [],\n  );\n  if (errors.length === 1) throw errors[0];\n  if (errors.length > 1) throw new AggregateError(errors, 'Multiple entrypoint handlers failed.');\n}\n\n/**\n * Wraps VelaApplication with Cloudflare-specific handlers:\n * - `fetch` — HTTP request handler (from Hono)\n * - `scheduled` — Cron trigger handler (runs the `@Cron()` jobs whose\n *                 expression is the trigger's exact string)\n * - `queue` — Queue consumer handler (`@QueueConsumer()` by physical queue,\n *             then `QueueModule`'s native consumer)\n * - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on\n *                    the underlying Hono app\n *\n * @example\n * ```ts\n * const app = await createCloudflareApp(AppModule, { env });\n * export default {\n *   fetch: app.fetch,\n *   scheduled: app.scheduled.bind(app),\n *   queue: app.queue.bind(app),\n * };\n * ```\n *\n * @example\n * ```ts\n * // Serve OpenAPI docs alongside your routes\n * const app = await createCloudflareApp(AppModule, { env });\n * const document = createOpenApiDocument(AppModule);\n * app.mountOpenApi({ document, ui: 'scalar' });\n * // GET /openapi.json -> JSON document\n * // GET /scalar       -> Scalar UI (loads from CDN)\n * ```\n */\nexport class CloudflareApplication {\n  readonly #wsGatewayRoutes: WsGatewayRoute[] = [];\n  readonly #app: VelaApplication;\n  /** Scheduled triggers in flight; close() aborts their signals and awaits them. */\n  readonly #scheduled = new Map<Promise<void>, AbortController>();\n\n  constructor(\n    app: VelaApplication,\n    readonly env: VelaEnv,\n  ) {\n    this.#app = app;\n    this.get = app.get.bind(app);\n  }\n\n  readonly fetch = async (\n    request: Request,\n    env: VelaEnv,\n    ctx?: ExecutionContext,\n  ): Promise<Response> => {\n    assertCloudflareEnvironment(this.env, env);\n    return this.#app.fetch(request, env, ctx);\n  };\n\n  getHonoApp(): ReturnType<VelaApplication['getHonoApp']> {\n    return this.#app.getHonoApp();\n  }\n\n  /**\n   * Resolve a provider from the application's DI container (delegates to\n   * `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —\n   * to use inside `createCloudflareApp({ middleware: env => [...] })` request middleware,\n   * which runs outside the DI request pipeline.\n   *\n   * @example\n   * ```ts\n   * const app = await createCloudflareApp(AppModule, { env });\n   * const auth = app.get(BetterAuthService);\n   * ```\n   */\n  readonly get: VelaApplication['get'];\n\n  get entrypoints(): VelaApplication['entrypoints'] {\n    return this.#app.entrypoints;\n  }\n\n  /**\n   * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the\n   * underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,\n   * so the JSON endpoint defaults to `/openapi.json` and the Scalar UI (when\n   * opted in) defaults to `/scalar`. Edge-safe — the UI HTML loads Scalar from\n   * a CDN at runtime, nothing is bundled server-side.\n   *\n   * @example\n   * ```ts\n   * import { createOpenApiDocument } from '@velajs/vela/openapi';\n   *\n   * const app = await createCloudflareApp(AppModule, { env });\n   * const document = createOpenApiDocument(AppModule, {\n   *   info: { title: 'My API', version: '1.0.0' },\n   * });\n   * app.mountOpenApi({ document, ui: 'scalar' });\n   * // GET /openapi.json -> { openapi: '3.1.0', ... }\n   * // GET /scalar       -> Scalar UI HTML\n   * ```\n   */\n  mountOpenApi(options: MountOpenApiOptions): this {\n    this.#app.mountOpenApi(options);\n    return this;\n  }\n\n  /**\n   * @internal Upgrade routes come from validated gateway entrypoints, including\n   * request-scoped gateways without a bootstrap instance. Retain the instance\n   * scan for legacy applications that only declare forwarding metadata.\n   */\n  scanInstances(instances: unknown[]): void {\n    const routes = new Map<string, WsGatewayRoute>();\n    for (const ep of this.#app.entrypoints.ofKind('websocket')) {\n      if (typeof ep.meta !== 'object' || ep.meta === null || !('dispatcher' in ep.meta)) continue;\n      const meta = readWsEntrypointMeta(ep.meta);\n      if (meta.options.binding) {\n        routes.set(meta.path, {\n          path: meta.path,\n          binding: meta.options.binding,\n          options: { ...meta.options },\n          moduleId: meta.moduleId,\n        });\n      }\n    }\n    const container = this.#app.getContainer();\n    for (const instance of instances) {\n      if (!instance || typeof instance !== 'object') continue;\n      for (const route of collectWsGatewayRoutes(instance, container)) {\n        if (!routes.has(route.path)) routes.set(route.path, route);\n      }\n    }\n    this.#wsGatewayRoutes.splice(0, this.#wsGatewayRoutes.length, ...routes.values());\n  }\n\n  /** @internal — upgrade routes discovered from the application's gateways. */\n  getWsGatewayRoutes(): WsGatewayRoute[] {\n    return [...this.#wsGatewayRoutes];\n  }\n\n  /**\n   * Handle a Cloudflare cron trigger. Runs every core `@Cron()` job whose\n   * expression is exactly `event.cron` (the trigger string is compared as\n   * delivered, never re-evaluated) through `invokeScheduledJob`, the dispatch\n   * primitive every runtime shares. Each job receives only its\n   * `ScheduleInvocation`, runs in a fresh invocation scope seeded with\n   * {@link CLOUDFLARE_SCHEDULED_EVENT}, and honors signed `ScheduleModule`\n   * dispatch. The trigger settles after every matching job and its managed\n   * work (`EXECUTION_LIFETIME.waitUntil`/`defer`) settle; failures reject it.\n   */\n  async scheduled(\n    event: ScheduledEvent,\n    env: VelaEnv,\n    _ctx?: { waitUntil: (promise: Promise<unknown>) => void },\n  ): Promise<void> {\n    assertCloudflareEnvironment(this.env, env);\n    const jobs = this.#app.entrypoints\n      .ofKind('schedule:cron', parseCronMetadata)\n      .filter((entry) => entry.meta.expression === event.cron);\n    if (jobs.length === 0) return;\n\n    const controller = new AbortController();\n    const scheduledTime = event.scheduledTime ?? Date.now();\n    // Shared by every matching job, so none of them can alter what another sees.\n    const invocation: ScheduleInvocation = Object.freeze({\n      kind: 'cron' as const,\n      expression: event.cron,\n      scheduledTime,\n      signal: controller.signal,\n    });\n    const trigger = cloudflareScheduledEvent(event, scheduledTime);\n    const container = this.#app.getContainer();\n    const running = settleEntrypoints(\n      jobs.map((entry) =>\n        invokeScheduledJob(container, entry, invocation, {\n          seed: (scope) => scope.setRequestInstance(CLOUDFLARE_SCHEDULED_EVENT, trigger),\n        }),\n      ),\n    );\n    this.#scheduled.set(running, controller);\n    try {\n      await running;\n    } finally {\n      this.#scheduled.delete(running);\n    }\n  }\n\n  /**\n   * Run one queue consumer inside a fresh request scope, through the shared\n   * guard → interceptor pipeline (components declared with\n   * `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or\n   * method). HTTP-global components deliberately do NOT apply — an HTTP auth\n   * guard has no business rejecting a queue batch. Unclaimed errors are\n   * reported once (`QueueModule`'s consumer reports its own) and rethrow so\n   * the platform's retry semantics stay intact.\n   */\n  private async dispatchEntrypoint(\n    ep: Entrypoint,\n    payload: unknown,\n    env: VelaEnv,\n    platformContext: { waitUntil: (promise: Promise<unknown>) => void },\n  ): Promise<void> {\n    const targetClass = ep.token;\n    if (typeof targetClass !== 'function') throw new Error('Entrypoint token must be a class.');\n    if (ep.methodName === undefined) throw new Error('Entrypoint must declare a handler method.');\n    const methodName = ep.methodName;\n    const reportContext = {\n      edge: 'queue' as const,\n      source: `${targetClass.name}.${String(methodName)}`,\n    };\n    let reported: { error: unknown } | undefined;\n    // A self-reporting handler's own rejection was already reported.\n    let delegated: { error: unknown } | undefined;\n    try {\n      await runInEntrypointScope(this.#app.getContainer(), async (scope, lifetime) => {\n        const moduleId = getEntrypointModuleId(scope, ep);\n        const context = buildEntrypointExecutionContext(\n          ep.kind,\n          targetClass,\n          methodName,\n          payload,\n          moduleId,\n          scope,\n        );\n        const invocationContext = {\n          waitUntil(promise: Promise<unknown>): void {\n            lifetime.waitUntil(promise);\n            platformContext.waitUntil(promise);\n          },\n        };\n        let filters: ExceptionFilter[] = [];\n        try {\n          filters = (\n            await resolveScopedComponentsAsync('filter', targetClass, methodName, scope, moduleId)\n          ).toReversed();\n          const guards = await resolveScopedComponentsAsync(\n            'guard',\n            targetClass,\n            methodName,\n            scope,\n            moduleId,\n          );\n          const interceptors = await resolveScopedComponentsAsync(\n            'interceptor',\n            targetClass,\n            methodName,\n            scope,\n            moduleId,\n          );\n          await PipelineRunner.run({\n            context,\n            guards,\n            interceptors,\n            resolveArgs: async () => [payload, env, invocationContext],\n            invoke: async (args) => {\n              const instance = await resolveEntrypoint(scope, ep);\n              if (typeof instance !== 'object' || instance === null) {\n                throw new Error('Entrypoint must resolve to an object.');\n              }\n              try {\n                return await invoke(instance, methodName, args);\n              } catch (error) {\n                if (SELF_REPORTING_KINDS.has(ep.kind)) delegated = { error };\n                throw error;\n              }\n            },\n          });\n        } catch (error) {\n          if (delegated?.error !== error) {\n            resolveErrorReporter(scope).report(error, reportContext);\n          }\n          for (const filter of filters) {\n            if (shouldFilterCatch(filter, error)) {\n              // Filters run closest-first; this is the framework catch hook.\n              // eslint-disable-next-line no-await-in-loop, promise/valid-params\n              await filter.catch(error, context);\n              return;\n            }\n          }\n          reported = { error };\n          throw error;\n        }\n      });\n    } catch (error) {\n      // Managed completion happens after the handler's filter boundary. Report\n      // a new completion failure without reporting an already-observed handler\n      // failure twice; preserve both errors in the rejected invocation.\n      if (!reported || reported.error !== error) {\n        const completionError =\n          reported && error instanceof AggregateError && error.errors[0] === reported.error\n            ? error.errors[1]\n            : error;\n        resolveErrorReporter(this.#app.getContainer()).report(completionError, reportContext);\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Handle Cloudflare Queue consumer events. `@QueueConsumer()` handlers read\n   * from `app.entrypoints` claim a batch by its physical queue name and\n   * receive it whole. A batch no handler claims goes to `QueueModule`'s native\n   * consumer (`cloudflareQueues()` from `@velajs/cloudflare/queues`), which\n   * routes each job by its logical queue. Each dispatch runs inside a fresh\n   * request-scoped child (request-scoped providers rebuild per batch — no\n   * boot-time captives). A batch nothing claims rejects: resolving would let\n   * Cloudflare acknowledge every message implicitly.\n   */\n  async queue(\n    batch: { queue: string; messages: readonly unknown[] },\n    env: VelaEnv,\n    ctx: { waitUntil: (promise: Promise<unknown>) => void },\n  ): Promise<void> {\n    assertCloudflareEnvironment(this.env, env);\n    const raw = this.#app.entrypoints\n      .ofKind('cf:queue')\n      .filter((ep) => entrypointString(ep.meta, 'queueName') === batch.queue);\n    if (raw.length > 0) this.warnRawJobs(batch);\n    const handlers = raw.length > 0 ? raw : this.#app.entrypoints.ofKind('cf:queue:module');\n\n    if (handlers.length === 0) {\n      throw new Error(\n        `No consumer claims queue '${batch.queue}'. Add @QueueConsumer('${batch.queue}') to a ` +\n          `provider, or deliver it through QueueModule.forRoot({ driver: cloudflareQueues() }) ` +\n          `with a QueueModule.registerQueue() for each queue it carries. The batch is rejected ` +\n          `unacknowledged, so Cloudflare retries it and then routes it to the configured ` +\n          `dead-letter queue.`,\n      );\n    }\n\n    await settleEntrypoints(handlers.map((ep) => this.dispatchEntrypoint(ep, batch, env, ctx)));\n  }\n\n  /**\n   * A raw `@QueueConsumer` owns its physical queue's batches and must not carry\n   * jobs of a queue registered with `QueueModule`: those reach their\n   * `@Processor` only if the raw handler dispatches them itself, while\n   * `cloudflareQueues()` delivers registered queues. Warn once per physical and\n   * logical queue (unless diagnostics are silent); the raw consumer still\n   * receives and settles the batch.\n   */\n  private warnRawJobs(batch: { queue: string; messages: readonly unknown[] }): void {\n    if (this.#app.getContainer().getDiagnostics() === 'silent') return;\n    const registered = new Set(\n      this.#app.entrypoints\n        .ofKind('queue:registration')\n        .map((entry) =>\n          typeof entry.meta === 'object' && entry.meta !== null\n            ? Reflect.get(entry.meta, 'name')\n            : undefined,\n        ),\n    );\n    if (registered.size === 0) return;\n    for (const message of batch.messages) {\n      const body =\n        typeof message === 'object' && message !== null ? Reflect.get(message, 'body') : undefined;\n      const queue = envelopeQueue(body);\n      if (queue === undefined || !registered.has(queue)) continue;\n      const warning =\n        `[vela] @QueueConsumer('${batch.queue}') received jobs of registered queue '${queue}'. ` +\n        `The raw consumer owns '${batch.queue}' and must not carry jobs of registered queues: ` +\n        `they reach @Processor('${queue}') only if the raw handler dispatches them itself. ` +\n        `Deliver '${queue}' through cloudflareQueues() instead: send it to a physical queue ` +\n        `that no @QueueConsumer claims.`;\n      if (warnedRawJobs.has(warning)) continue;\n      warnedRawJobs.add(warning);\n      console.warn(warning);\n    }\n  }\n\n  /**\n   * Abort the signals of scheduled jobs still running, wait for them and their\n   * managed work to settle, then close the application.\n   */\n  async close(signal?: string): Promise<void> {\n    for (const controller of this.#scheduled.values()) controller.abort();\n    await Promise.allSettled(this.#scheduled.keys());\n    return this.#app.close(signal);\n  }\n}\n"],"mappings":"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"}

package/dist/cloudflare-factory.js

@@ -0,0 +1,109 @@
+import { registerWebSocketRoutes } from "./websocket/websocket-routing.js";
+import { assertCloudflareEnvironment, registerCloudflareEnvironment } from "./environment.js";
+import { registerScheduledEventSeed } from "./scheduled-event.js";
+import { CloudflareApplication } from "./cloudflare-application.js";
+import { reportCloudflareScheduleDiagnostics } from "./schedule-diagnostics.js";
+import { warnWorkerLocalLive } from "./websocket/do-live.js";
+import { getConnInfo } from "hono/cloudflare-workers";
+import { VelaFactory } from "@velajs/vela";
+//#region src/cloudflare-factory.ts
+function readStrings(meta, property) {
+	const value = typeof meta === "object" && meta !== null ? Reflect.get(meta, property) : void 0;
+	if (typeof value === "string") return [value];
+	if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value;
+	throw new TypeError(`Invalid queue consumer metadata: ${property}.`);
+}
+/**
+* `@QueueConsumer` handlers own their physical queue. A `QueueModule`
+* registration that pins the same physical queue with `consumer` would never
+* see its batches, so bootstrap rejects the overlap.
+*/
+function assertQueueConsumerOwnership(entrypoints) {
+	const pinned = new Set(entrypoints.ofKind("cf:queue:module").flatMap((entry) => readStrings(entry.meta, "consumers")));
+	for (const entry of entrypoints.ofKind("cf:queue")) {
+		const [queue] = readStrings(entry.meta, "queueName");
+		if (queue !== void 0 && pinned.has(queue)) throw new Error(`Ambiguous consumer ownership for queue '${queue}': @QueueConsumer('${queue}') and a QueueModule.registerQueue({ consumer: '${queue}' }) both claim it. Keep one owner.`);
+	}
+}
+/**
+* Bind an application to one environment: seeded as the global ENV before
+* provider factories and lifecycle hooks, and asserted on every request. The
+* adapter also supplies the `InternalDispatcher` transport, so signed queue and
+* schedule dispatch re-enter this application's routes, and reports schedule
+* declarations a cron trigger cannot honor through the diagnostics policy.
+*/
+function cloudflareAdapter(options) {
+	const { env } = options;
+	return {
+		name: "cloudflare",
+		requestMiddleware: [async (context, next) => {
+			assertCloudflareEnvironment(env, context.env);
+			await next();
+		}],
+		invocationTransport: ({ app }) => (request) => Promise.resolve(app.fetch(request, env)),
+		getClientIp: (c) => getConnInfo(c).remote.address ?? null,
+		configureContainer: (container) => {
+			registerCloudflareEnvironment(container, env);
+			registerScheduledEventSeed(container);
+		},
+		onBootstrap: async ({ app, container }) => {
+			assertQueueConsumerOwnership(app.entrypoints);
+			reportCloudflareScheduleDiagnostics(container, app.entrypoints);
+			await warnWorkerLocalLive(container);
+		}
+	};
+}
+/**
+* Build an application for one native Workers environment. Call inside a platform event.
+* The root is static: a module class or a `DynamicModule` declared at module scope.
+* Read bindings in providers (`@InjectEnv()`) and module factories
+* (`forRootAsync({ inject: [ENV], useFactory })`), which run for each application.
+*/
+async function createCloudflareApp(rootModule, options) {
+	const velaApp = await VelaFactory.create(rootModule, {
+		globalPrefix: options.globalPrefix,
+		security: options.security,
+		middleware: options.middleware?.(options.env),
+		adapters: [cloudflareAdapter(options), ...options.adapters ?? []]
+	});
+	const app = new CloudflareApplication(velaApp, options.env);
+	app.scanInstances(velaApp.getInstances());
+	registerWebSocketRoutes(app.getHonoApp(), app.getWsGatewayRoutes(), velaApp.getContainer());
+	return app;
+}
+/**
+* Worker entrypoint with one bootstrap per environment identity. Concurrent cold
+* events share construction; failed construction is evicted so the next event
+* can retry. Weak keys stop this cache from retaining a replaced environment.
+*/
+function createCloudflareWorker(rootModule, options = {}) {
+	const applications = /* @__PURE__ */ new WeakMap();
+	const application = (env) => {
+		const existing = applications.get(env);
+		if (existing) return existing;
+		const pending = createCloudflareApp(rootModule, {
+			...options,
+			env
+		});
+		applications.set(env, pending);
+		pending.catch(() => {
+			if (applications.get(env) === pending) applications.delete(env);
+		});
+		return pending;
+	};
+	return {
+		async fetch(request, env, ctx) {
+			return (await application(env)).fetch(request, env, ctx);
+		},
+		async scheduled(event, env, ctx) {
+			return (await application(env)).scheduled(event, env, ctx);
+		},
+		async queue(batch, env, ctx) {
+			return (await application(env)).queue(batch, env, ctx);
+		}
+	};
+}
+//#endregion
+export { cloudflareAdapter, createCloudflareApp, createCloudflareWorker };
+
+//# sourceMappingURL=cloudflare-factory.js.map

package/dist/cloudflare-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-factory.js","names":[],"sources":["../src/cloudflare-factory.ts"],"sourcesContent":["import type { ExecutionContext } from 'hono';\nimport { getConnInfo } from 'hono/cloudflare-workers';\nimport { VelaFactory } from '@velajs/vela';\nimport type {\n  VelaApplication,\n  VelaEnv,\n  VelaMiddlewareHandler,\n  VelaSecurityOptions,\n} from '@velajs/vela';\nimport type { RuntimeAdapter } from '@velajs/vela/module-kit';\nimport { CloudflareApplication } from './cloudflare-application';\nimport { assertCloudflareEnvironment, registerCloudflareEnvironment } from './environment';\nimport { reportCloudflareScheduleDiagnostics } from './schedule-diagnostics';\nimport { registerScheduledEventSeed, type ScheduledEvent } from './scheduled-event';\nimport { warnWorkerLocalLive } from './websocket/do-live';\nimport { registerWebSocketRoutes } from './websocket/websocket-routing';\nimport type { CloudflareRoot } from './root-module';\n\nexport interface CloudflareWorkerOptions {\n  globalPrefix?: string;\n  security?: VelaSecurityOptions;\n  /** Build request middleware from the same native environment DI receives as ENV. */\n  middleware?: (env: VelaEnv) => VelaMiddlewareHandler[];\n  /** Further runtime adapters, composed after the Cloudflare adapter for each application. */\n  adapters?: RuntimeAdapter[];\n}\n\nexport interface CreateCloudflareAppOptions extends CloudflareWorkerOptions {\n  /** Supply the platform environment inside fetch/queue/scheduled or a DO constructor. */\n  env: VelaEnv;\n}\n\nfunction readStrings(meta: unknown, property: string): string[] {\n  const value: unknown =\n    typeof meta === 'object' && meta !== null ? Reflect.get(meta, property) : undefined;\n  if (typeof value === 'string') return [value];\n  if (Array.isArray(value) && value.every((item) => typeof item === 'string')) return value;\n  throw new TypeError(`Invalid queue consumer metadata: ${property}.`);\n}\n\n/**\n * `@QueueConsumer` handlers own their physical queue. A `QueueModule`\n * registration that pins the same physical queue with `consumer` would never\n * see its batches, so bootstrap rejects the overlap.\n */\nfunction assertQueueConsumerOwnership(entrypoints: VelaApplication['entrypoints']): void {\n  const pinned = new Set(\n    entrypoints.ofKind('cf:queue:module').flatMap((entry) => readStrings(entry.meta, 'consumers')),\n  );\n  for (const entry of entrypoints.ofKind('cf:queue')) {\n    const [queue] = readStrings(entry.meta, 'queueName');\n    if (queue !== undefined && pinned.has(queue)) {\n      throw new Error(\n        `Ambiguous consumer ownership for queue '${queue}': @QueueConsumer('${queue}') and a ` +\n          `QueueModule.registerQueue({ consumer: '${queue}' }) both claim it. Keep one owner.`,\n      );\n    }\n  }\n}\n\n/**\n * Bind an application to one environment: seeded as the global ENV before\n * provider factories and lifecycle hooks, and asserted on every request. The\n * adapter also supplies the `InternalDispatcher` transport, so signed queue and\n * schedule dispatch re-enter this application's routes, and reports schedule\n * declarations a cron trigger cannot honor through the diagnostics policy.\n */\nexport function cloudflareAdapter(options: { env: VelaEnv }): RuntimeAdapter {\n  const { env } = options;\n  return {\n    name: 'cloudflare',\n    requestMiddleware: [\n      async (context, next) => {\n        assertCloudflareEnvironment(env, context.env);\n        await next();\n      },\n    ],\n    invocationTransport:\n      ({ app }) =>\n      (request) =>\n        Promise.resolve(app.fetch(request, env)),\n    getClientIp: (c) => getConnInfo(c).remote.address ?? null,\n    configureContainer: (container) => {\n      registerCloudflareEnvironment(container, env);\n      registerScheduledEventSeed(container);\n    },\n    onBootstrap: async ({ app, container }) => {\n      assertQueueConsumerOwnership(app.entrypoints);\n      reportCloudflareScheduleDiagnostics(container, app.entrypoints);\n      await warnWorkerLocalLive(container);\n    },\n  };\n}\n\n/**\n * Build an application for one native Workers environment. Call inside a platform event.\n * The root is static: a module class or a `DynamicModule` declared at module scope.\n * Read bindings in providers (`@InjectEnv()`) and module factories\n * (`forRootAsync({ inject: [ENV], useFactory })`), which run for each application.\n */\nexport async function createCloudflareApp(\n  rootModule: CloudflareRoot,\n  options: CreateCloudflareAppOptions,\n): Promise<CloudflareApplication> {\n  const velaApp = await VelaFactory.create(rootModule, {\n    globalPrefix: options.globalPrefix,\n    security: options.security,\n    middleware: options.middleware?.(options.env),\n    adapters: [cloudflareAdapter(options), ...(options.adapters ?? [])],\n  });\n  const app = new CloudflareApplication(velaApp, options.env);\n  app.scanInstances(velaApp.getInstances());\n  registerWebSocketRoutes(app.getHonoApp(), app.getWsGatewayRoutes(), velaApp.getContainer());\n  return app;\n}\n\n/**\n * Worker entrypoint with one bootstrap per environment identity. Concurrent cold\n * events share construction; failed construction is evicted so the next event\n * can retry. Weak keys stop this cache from retaining a replaced environment.\n */\nexport function createCloudflareWorker(\n  rootModule: CloudflareRoot,\n  options: CloudflareWorkerOptions = {},\n) {\n  const applications = new WeakMap<VelaEnv, Promise<CloudflareApplication>>();\n  const application = (env: VelaEnv): Promise<CloudflareApplication> => {\n    const existing = applications.get(env);\n    if (existing) return existing;\n    const pending = createCloudflareApp(rootModule, { ...options, env });\n    applications.set(env, pending);\n    void pending.catch(() => {\n      if (applications.get(env) === pending) applications.delete(env);\n    });\n    return pending;\n  };\n  return {\n    async fetch(request: Request, env: VelaEnv, ctx: ExecutionContext): Promise<Response> {\n      return (await application(env)).fetch(request, env, ctx);\n    },\n    async scheduled(\n      event: ScheduledEvent,\n      env: VelaEnv,\n      ctx?: { waitUntil: (promise: Promise<unknown>) => void },\n    ): Promise<void> {\n      return (await application(env)).scheduled(event, env, ctx);\n    },\n    async queue(\n      batch: { queue: string; messages: readonly unknown[] },\n      env: VelaEnv,\n      ctx: { waitUntil: (promise: Promise<unknown>) => void },\n    ): Promise<void> {\n      return (await application(env)).queue(batch, env, ctx);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAgCA,SAAS,YAAY,MAAe,UAA4B;CAC9D,MAAM,QACJ,OAAO,SAAS,YAAY,SAAS,OAAO,QAAQ,IAAI,MAAM,QAAQ,IAAI,KAAA;CAC5E,IAAI,OAAO,UAAU,UAAU,OAAO,CAAC,KAAK;CAC5C,IAAI,MAAM,QAAQ,KAAK,KAAK,MAAM,OAAO,SAAS,OAAO,SAAS,QAAQ,GAAG,OAAO;CACpF,MAAM,IAAI,UAAU,oCAAoC,SAAS,EAAE;AACrE;;;;;;AAOA,SAAS,6BAA6B,aAAmD;CACvF,MAAM,SAAS,IAAI,IACjB,YAAY,OAAO,iBAAiB,CAAC,CAAC,SAAS,UAAU,YAAY,MAAM,MAAM,WAAW,CAAC,CAC/F;CACA,KAAK,MAAM,SAAS,YAAY,OAAO,UAAU,GAAG;EAClD,MAAM,CAAC,SAAS,YAAY,MAAM,MAAM,WAAW;EACnD,IAAI,UAAU,KAAA,KAAa,OAAO,IAAI,KAAK,GACzC,MAAM,IAAI,MACR,2CAA2C,MAAM,qBAAqB,MAAM,kDAChC,MAAM,oCACpD;CAEJ;AACF;;;;;;;;AASA,SAAgB,kBAAkB,SAA2C;CAC3E,MAAM,EAAE,QAAQ;CAChB,OAAO;EACL,MAAM;EACN,mBAAmB,CACjB,OAAO,SAAS,SAAS;GACvB,4BAA4B,KAAK,QAAQ,GAAG;GAC5C,MAAM,KAAK;EACb,CACF;EACA,sBACG,EAAE,WACF,YACC,QAAQ,QAAQ,IAAI,MAAM,SAAS,GAAG,CAAC;EAC3C,cAAc,MAAM,YAAY,CAAC,CAAC,CAAC,OAAO,WAAW;EACrD,qBAAqB,cAAc;GACjC,8BAA8B,WAAW,GAAG;GAC5C,2BAA2B,SAAS;EACtC;EACA,aAAa,OAAO,EAAE,KAAK,gBAAgB;GACzC,6BAA6B,IAAI,WAAW;GAC5C,oCAAoC,WAAW,IAAI,WAAW;GAC9D,MAAM,oBAAoB,SAAS;EACrC;CACF;AACF;;;;;;;AAQA,eAAsB,oBACpB,YACA,SACgC;CAChC,MAAM,UAAU,MAAM,YAAY,OAAO,YAAY;EACnD,cAAc,QAAQ;EACtB,UAAU,QAAQ;EAClB,YAAY,QAAQ,aAAa,QAAQ,GAAG;EAC5C,UAAU,CAAC,kBAAkB,OAAO,GAAG,GAAI,QAAQ,YAAY,CAAC,CAAE;CACpE,CAAC;CACD,MAAM,MAAM,IAAI,sBAAsB,SAAS,QAAQ,GAAG;CAC1D,IAAI,cAAc,QAAQ,aAAa,CAAC;CACxC,wBAAwB,IAAI,WAAW,GAAG,IAAI,mBAAmB,GAAG,QAAQ,aAAa,CAAC;CAC1F,OAAO;AACT;;;;;;AAOA,SAAgB,uBACd,YACA,UAAmC,CAAC,GACpC;CACA,MAAM,+BAAe,IAAI,QAAiD;CAC1E,MAAM,eAAe,QAAiD;EACpE,MAAM,WAAW,aAAa,IAAI,GAAG;EACrC,IAAI,UAAU,OAAO;EACrB,MAAM,UAAU,oBAAoB,YAAY;GAAE,GAAG;GAAS;EAAI,CAAC;EACnE,aAAa,IAAI,KAAK,OAAO;EAC7B,QAAa,YAAY;GACvB,IAAI,aAAa,IAAI,GAAG,MAAM,SAAS,aAAa,OAAO,GAAG;EAChE,CAAC;EACD,OAAO;CACT;CACA,OAAO;EACL,MAAM,MAAM,SAAkB,KAAc,KAA0C;GACpF,QAAQ,MAAM,YAAY,GAAG,EAAA,CAAG,MAAM,SAAS,KAAK,GAAG;EACzD;EACA,MAAM,UACJ,OACA,KACA,KACe;GACf,QAAQ,MAAM,YAAY,GAAG,EAAA,CAAG,UAAU,OAAO,KAAK,GAAG;EAC3D;EACA,MAAM,MACJ,OACA,KACA,KACe;GACf,QAAQ,MAAM,YAAY,GAAG,EAAA,CAAG,MAAM,OAAO,KAAK,GAAG;EACvD;CACF;AACF"}

package/dist/decorators/queue-consumer.js

@@ -0,0 +1,39 @@
+import { defineMetadata, getMetadata, registerEntrypointKind } from "@velajs/vela/module-kit";
+//#region src/decorators/queue-consumer.ts
+const QUEUE_CONSUMER_METADATA_KEY = "cloudflare:queue-consumer";
+registerEntrypointKind({
+	kind: "cf:queue",
+	metaKey: QUEUE_CONSUMER_METADATA_KEY,
+	level: "method"
+});
+/**
+* Marks a method as a queue consumer handler.
+*
+* @example
+* ```ts
+* @Injectable()
+* class WorkerService {
+*   @QueueConsumer('email-queue')
+*   async processEmails(batch: MessageBatch) {
+*     for (const msg of batch.messages) {
+*       console.log('Processing:', msg.body);
+*       msg.ack();
+*     }
+*   }
+* }
+* ```
+*/
+function QueueConsumer(queueName) {
+	return (target, propertyKey, _descriptor) => {
+		const existing = getMetadata(QUEUE_CONSUMER_METADATA_KEY, target.constructor) ?? [];
+		existing.push({
+			queueName,
+			methodName: String(propertyKey)
+		});
+		defineMetadata(QUEUE_CONSUMER_METADATA_KEY, existing, target.constructor);
+	};
+}
+//#endregion
+export { QueueConsumer };
+
+//# sourceMappingURL=queue-consumer.js.map

package/dist/decorators/queue-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-consumer.js","names":[],"sources":["../../src/decorators/queue-consumer.ts"],"sourcesContent":["import { defineMetadata, getMetadata, registerEntrypointKind } from '@velajs/vela/module-kit';\n\nconst QUEUE_CONSUMER_METADATA_KEY = 'cloudflare:queue-consumer';\n\n// Open entrypoint kind: any adapter can enumerate queue consumers via\n// `app.entrypoints.ofKind('cf:queue')` — declared here, next to the decorator,\n// with zero vela-core involvement.\nregisterEntrypointKind({ kind: 'cf:queue', metaKey: QUEUE_CONSUMER_METADATA_KEY, level: 'method' });\n\nexport interface QueueConsumerMetadata {\n  queueName: string;\n  methodName: string;\n}\n\n/**\n * Marks a method as a queue consumer handler.\n *\n * @example\n * ```ts\n * @Injectable()\n * class WorkerService {\n *   @QueueConsumer('email-queue')\n *   async processEmails(batch: MessageBatch) {\n *     for (const msg of batch.messages) {\n *       console.log('Processing:', msg.body);\n *       msg.ack();\n *     }\n *   }\n * }\n * ```\n */\nexport function QueueConsumer(queueName: string): MethodDecorator {\n  return (target: object, propertyKey: string | symbol, _descriptor: PropertyDescriptor) => {\n    const existing: QueueConsumerMetadata[] =\n      (getMetadata(QUEUE_CONSUMER_METADATA_KEY, target.constructor) as QueueConsumerMetadata[]) ??\n      [];\n    existing.push({ queueName, methodName: String(propertyKey) });\n    defineMetadata(QUEUE_CONSUMER_METADATA_KEY, existing, target.constructor);\n  };\n}\n\nexport function getQueueConsumerMetadata(target: object): QueueConsumerMetadata[] {\n  const ctor = target.constructor ?? target;\n  return (getMetadata(QUEUE_CONSUMER_METADATA_KEY, ctor) as QueueConsumerMetadata[]) ?? [];\n}\n"],"mappings":";;AAEA,MAAM,8BAA8B;AAKpC,uBAAuB;CAAE,MAAM;CAAY,SAAS;CAA6B,OAAO;AAAS,CAAC;;;;;;;;;;;;;;;;;;AAwBlG,SAAgB,cAAc,WAAoC;CAChE,QAAQ,QAAgB,aAA8B,gBAAoC;EACxF,MAAM,WACH,YAAY,6BAA6B,OAAO,WAAW,KAC5D,CAAC;EACH,SAAS,KAAK;GAAE;GAAW,YAAY,OAAO,WAAW;EAAE,CAAC;EAC5D,eAAe,6BAA6B,UAAU,OAAO,WAAW;CAC1E;AACF"}

package/dist/durable-objects.d.ts

@@ -1,9 +1,9 @@
 import "./vela-env-DFvyoNT3.js";
-import { l as VelaDoPitrRpc, p as CloudflareRoot, t as VelaNonceDurableObject } from "./nonce.durable-object-Df4CZi-0.js";
+import { l as VelaDoPitrRpc, p as CloudflareRoot, t as VelaNonceDurableObject } from "./nonce.durable-object-Ci9AGssY.js";
+import { DurableObject } from "cloudflare:workers";
 import { VelaEnv } from "@velajs/vela";
 import { BroadcastCommand } from "@velajs/vela/websocket";
 import { CommitStamp, InvalidationCommand, LiveInspection } from "@velajs/vela/live";
-import { DurableObject } from "cloudflare:workers";
 //#region src/websocket/websocket.durable-object.d.ts
 /**
  * Base class for the WebSocket Durable Object. The user exports a named subclass
@@ -25,5 +25,4 @@ export declare function VelaWebSocketDurableObject(rootModule: CloudflareRoot):
   inspectLive(): Promise<LiveInspection>;
 };
 //#endregion
-export { VelaNonceDurableObject };
-//# sourceMappingURL=durable-objects.d.ts.map
+export { VelaNonceDurableObject };