@velajs/cloudflare 1.28.0 → 1.30.0

package/dist/index.d.ts

@@ -1,10 +1,15 @@
-import { a as DoPitrId, c as DoPitrUnavailableError, d as isDoPitrUnavailable, f as readDoPitrBookmark, i as DoPitrBookmarkRead, l as VelaDoPitrRpc, n as DoPitrArmOptions, o as DoPitrNamespace, p as CloudflareRoot, r as DoPitrArmResult, s as DoPitrStorage, t as VelaNonceDurableObject, u as armDoPitr } from "./nonce.durable-object-DffHMRnU.js";
-import { AsyncCacheStore, CacheEntry, CacheEntryReader, CacheEntryWriter, CacheInvalidationStore, DynamicModule, InjectionToken, NonceStore, RuntimeAdapter, ThrottlerStore, Type, VelaApplication, VelaMiddlewareHandler, VelaSecurityOptions } from "@velajs/vela";
-import { BroadcastCommand, ConnectedSocket, MessageBody, OnGatewayConnection, OnGatewayDisconnect, OnGatewayInit, SubscribeMessage, WebSocketGateway, WebSocketGatewayOptions, WebSocketSendGate, WebSocketServer, WsClient, WsDispatcher, WsException, WsMessage, WsResponse, WsServer } from "@velajs/vela/websocket";
-import { DownloadResult, PresignMethod, PresignedUrlResult, StorageBody, StorageDriver, UploadOptions, UploadResult } from "@velajs/vela/storage";
-import { CommitStamp, CursorLog, InvalidationCommand, LiveDriver, LiveEngine, LiveInvalidationSink, ResumeVerdict } from "@velajs/vela/live";
+import "./vela-env-DFvyoNT3.js";
+import { a as DoPitrId, c as DoPitrUnavailableError, d as isDoPitrUnavailable, f as readDoPitrBookmark, i as DoPitrBookmarkRead, l as VelaDoPitrRpc, n as DoPitrArmOptions, o as DoPitrNamespace, p as CloudflareRoot, r as DoPitrArmResult, s as DoPitrStorage, t as VelaNonceDurableObject, u as armDoPitr } from "./nonce.durable-object-Ci9AGssY.js";
+import { DynamicModule, InjectionToken, Type, VelaApplication, VelaEnv, VelaMiddlewareHandler, VelaSecurityOptions } from "@velajs/vela";
+import { BroadcastCommand, WebSocketGatewayOptions } from "@velajs/vela/websocket";
+import { CommitStamp, CursorLog, InvalidationCommand, LiveDriver, LiveInvalidationSink, ResumeVerdict } from "@velajs/vela/live";
 import { Context, ExecutionContext } from "hono";
+import { RuntimeAdapter } from "@velajs/vela/module-kit";
+import { DownloadResult, PresignMethod, PresignedUrlResult, StorageBody, StorageDriver, UploadOptions, UploadResult } from "@velajs/vela/storage";
+import { AsyncCacheStore, CacheEntry, CacheEntryReader, CacheEntryWriter, CacheInvalidationStore } from "@velajs/vela/cache";
 import { FeatureFlagDriver, FlagContext } from "@velajs/feature-flags";
+import { ThrottlerStore } from "@velajs/vela/throttler";
+import { NonceStore } from "@velajs/vela/security";
 //#region src/websocket/room-id.d.ts
 /** Stable, collision-free Durable Object name for one gateway's room. */
 export declare function durableObjectRoomName(gatewayPath: string, roomId: string): string;
@@ -14,8 +19,63 @@ interface WsGatewayRoute {
   path: string;
   binding: string;
   options: WebSocketGatewayOptions;
+  /** Container module that declares the gateway; its authenticator resolves from here. */
+  moduleId?: string;
 }
 //#endregion
+//#region src/scheduled-event.d.ts
+/**
+ * The event a Worker's `scheduled()` export receives. The native
+ * `ScheduledController` satisfies it; direct calls (tests, scripts) may omit
+ * `scheduledTime`, which then defaults to the current time, and `noRetry`.
+ */
+interface ScheduledEvent {
+  readonly cron: string;
+  readonly scheduledTime?: number;
+  noRetry?(): void;
+}
+/** The Cloudflare trigger behind the current scheduled invocation. */
+interface CloudflareScheduledEvent {
+  /** The trigger's exact cron string; it equals the invocation's `expression`. */
+  readonly cron: string;
+  /** The platform's scheduled time in Unix milliseconds. */
+  readonly scheduledTime: number;
+  /**
+   * Ask Cloudflare not to retry this trigger if the invocation fails. Already
+   * bound to the native controller, so it can be passed around or destructured.
+   * A no-op for direct calls that supplied no controller.
+   */
+  readonly noRetry: () => void;
+}
+/**
+ * Request-scoped Cloudflare view of the scheduled trigger, seeded into each
+ * `@Cron` job's invocation scope by the Cloudflare adapter. Inject it where a
+ * job needs platform controls such as `noRetry()`; the job's argument stays
+ * the portable `ScheduleInvocation`. It resolves only inside a scheduled
+ * invocation; resolving it anywhere else throws. A cron job fired on demand
+ * (Studio's run-now) receives a synthetic event: `cron` is the job's
+ * expression and `noRetry()` does nothing.
+ *
+ * The token provides itself as request-scoped in every container, so a class
+ * that injects it is request-scoped wherever the graph boots (a Worker, a
+ * Durable Object, the CLI or a testing module) and is built only for an
+ * invocation, never at bootstrap.
+ *
+ * @example
+ * ```ts
+ * @Injectable({ scope: Scope.REQUEST })
+ * class Reports {
+ *   constructor(@Inject(CLOUDFLARE_SCHEDULED_EVENT) private readonly trigger: CloudflareScheduledEvent) {}
+ *
+ *   @Cron('0 3 * * *', { dialect: 'cloudflare' })
+ *   async nightly(tick: CronInvocation) {
+ *     if (!(await this.upstreamAvailable(tick.signal))) this.trigger.noRetry();
+ *   }
+ * }
+ * ```
+ */
+export declare const CLOUDFLARE_SCHEDULED_EVENT: InjectionToken<CloudflareScheduledEvent>;
+//#endregion
 //#region src/cloudflare-application.d.ts
 /**
  * Options accepted by {@link CloudflareApplication.mountOpenApi}.
@@ -28,15 +88,16 @@ type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0];
 /**
  * Wraps VelaApplication with Cloudflare-specific handlers:
  * - `fetch` — HTTP request handler (from Hono)
- * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
- *                 AND vela's own `@Cron()` jobs)
- * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+ * - `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, envToken: ENV });
+ * const app = await createCloudflareApp(AppModule, { env });
  * export default {
  *   fetch: app.fetch,
  *   scheduled: app.scheduled.bind(app),
@@ -47,18 +108,18 @@ type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0];
  * @example
  * ```ts
  * // Serve OpenAPI docs alongside your routes
- * const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+ * 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)
  * ```
  */
-export declare class CloudflareApplication<T extends object = object> {
+export declare class CloudflareApplication {
   #private;
-  readonly env: T;
-  constructor(app: VelaApplication, env: T);
-  readonly fetch: (request: Request, env: T, ctx?: ExecutionContext) => Promise<Response>;
+  readonly env: VelaEnv;
+  constructor(app: VelaApplication, env: VelaEnv);
+  readonly fetch: (request: Request, env: VelaEnv, ctx?: ExecutionContext) => Promise<Response>;
   getHonoApp(): ReturnType<VelaApplication['getHonoApp']>;
   /**
    * Resolve a provider from the application's DI container (delegates to
@@ -68,7 +129,7 @@ export declare class CloudflareApplication<T extends object = object> {
    *
    * @example
    * ```ts
-   * const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+   * const app = await createCloudflareApp(AppModule, { env });
    * const auth = app.get(BetterAuthService);
    * ```
    */
@@ -83,9 +144,9 @@ export declare class CloudflareApplication<T extends object = object> {
    *
    * @example
    * ```ts
-   * import { createOpenApiDocument } from '@velajs/vela';
+   * import { createOpenApiDocument } from '@velajs/vela/openapi';
    *
-   * const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+   * const app = await createCloudflareApp(AppModule, { env });
    * const document = createOpenApiDocument(AppModule, {
    *   info: { title: 'My API', version: '1.0.0' },
    * });
@@ -104,75 +165,104 @@ export declare class CloudflareApplication<T extends object = object> {
   /** @internal — upgrade routes discovered from the application's gateways. */
   getWsGatewayRoutes(): WsGatewayRoute[];
   /**
-   * Handle Cloudflare scheduled (cron) events.
-   * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
-   * handlers read from `app.entrypoints`; each handler runs inside a fresh
-   * request-scoped child (request-scoped providers rebuild per tick).
+   * 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.
    */
-  scheduled(event: {
-    cron: string;
-    scheduledTime?: number;
-  }, env: T, ctx: {
+  scheduled(event: ScheduledEvent, env: VelaEnv, _ctx?: {
     waitUntil: (promise: Promise<unknown>) => void;
   }): Promise<void>;
   /**
-   * Run one entrypoint handler inside a fresh request scope, through the
-   * shared guard → interceptor pipeline (components declared with
+   * 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 rethrow
-   * so the platform's retry semantics stay intact.
+   * 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.
    */
   private dispatchEntrypoint;
   /**
-   * Handle Cloudflare Queue consumer events.
-   * Matches the batch queue name to `@QueueConsumer()` handlers read from
-   * `app.entrypoints`; each batch is processed inside a fresh request-scoped
-   * child (request-scoped providers rebuild per batch — no boot-time captives).
+   * 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.
    */
   queue(batch: {
     queue: string;
     messages: readonly unknown[];
-  }, env: T, ctx: {
+  }, env: VelaEnv, ctx: {
     waitUntil: (promise: Promise<unknown>) => void;
   }): Promise<void>;
+  /**
+   * 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.
+   */
+  private warnRawJobs;
+  /**
+   * Abort the signals of scheduled jobs still running, wait for them and their
+   * managed work to settle, then close the application.
+   */
   close(signal?: string): Promise<void>;
 }
 //#endregion
 //#region src/cloudflare-factory.d.ts
-interface CloudflareWorkerOptions<T extends object> {
-  /** Global typed DI token for the platform's native environment. */
-  envToken: InjectionToken<T>;
+interface CloudflareWorkerOptions {
   globalPrefix?: string;
   security?: VelaSecurityOptions;
-  /** Build request middleware from the same typed native environment as DI. */
-  middleware?: (env: NoInfer<T>) => VelaMiddlewareHandler[];
+  /** Build request middleware from the same native environment DI receives as ENV. */
+  middleware?: (env: VelaEnv) => VelaMiddlewareHandler[];
+  /** Further runtime adapters, composed after the Cloudflare adapter for each application. */
+  adapters?: RuntimeAdapter[];
 }
-interface CreateCloudflareAppOptions<T extends object> extends CloudflareWorkerOptions<T> {
+interface CreateCloudflareAppOptions extends CloudflareWorkerOptions {
   /** Supply the platform environment inside fetch/queue/scheduled or a DO constructor. */
-  env: NoInfer<T>;
+  env: VelaEnv;
 }
-/** Bind an application to one environment before provider factories and lifecycle hooks. */
-export declare function cloudflareAdapter<T extends object>(options: CreateCloudflareAppOptions<T>): RuntimeAdapter;
-/** Build an application for one native Workers environment. Call inside a platform event. */
-export declare function createCloudflareApp<T extends object>(rootModule: CloudflareRoot<NoInfer<T>>, options: CreateCloudflareAppOptions<T>): Promise<CloudflareApplication<T>>;
 /**
- * Worker entrypoint with one bootstrap per environment identity. Weak keys let
- * obsolete environments and secrets be collected. Concurrent cold events share
- * construction; failed construction is evicted so the next event can retry.
+ * 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.
  */
-export declare function createCloudflareWorker<T extends object>(rootModule: CloudflareRoot<NoInfer<T>>, options: CloudflareWorkerOptions<T>): {
-  fetch(request: Request, env: T, ctx: ExecutionContext): Promise<Response>;
-  scheduled(event: {
-    cron: string;
-    scheduledTime?: number;
-  }, env: T, ctx: {
+export declare function cloudflareAdapter(options: {
+  env: VelaEnv;
+}): RuntimeAdapter;
+/**
+ * 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.
+ */
+export declare function createCloudflareApp(rootModule: CloudflareRoot, options: CreateCloudflareAppOptions): Promise<CloudflareApplication>;
+/**
+ * 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.
+ */
+export declare function createCloudflareWorker(rootModule: CloudflareRoot, options?: CloudflareWorkerOptions): {
+  fetch(request: Request, env: VelaEnv, ctx: ExecutionContext): Promise<Response>;
+  scheduled(event: ScheduledEvent, env: VelaEnv, ctx?: {
     waitUntil: (promise: Promise<unknown>) => void;
   }): Promise<void>;
   queue(batch: {
     queue: string;
     messages: readonly unknown[];
-  }, env: T, ctx: {
+  }, env: VelaEnv, ctx: {
     waitUntil: (promise: Promise<unknown>) => void;
   }): Promise<void>;
 };
@@ -403,60 +493,6 @@ export declare class KvFlagDriver implements FeatureFlagDriver {
 /** Convenience factory for {@link KvFlagDriver}. */
 export declare function kvFlagDriver(kv: KVNamespace, options?: KvFlagDriverOptions): KvFlagDriver;
 //#endregion
-//#region src/decorators/env.d.ts
-/**
- * Parameter decorator to inject Cloudflare environment bindings.
- *
- * Without arguments, returns the entire `env` object.
- * With a binding name, returns that specific binding.
- *
- * @example
- * ```ts
- * @Get()
- * handle(@Env() env: WorkerEnv) { ... }
- *
- * @Get()
- * handle(@Env('MY_KV') kv: KVNamespace) { ... }
- * ```
- */
-export declare const Env: (data?: string | undefined, ...pipes: import("@velajs/vela").PipeType[]) => ParameterDecorator;
-//#endregion
-//#region src/decorators/scheduled.d.ts
-interface ScheduledMetadata {
-  cron: string;
-  methodName: string;
-}
-/** Compatible with the existing programmatic scheduled() entrypoint. */
-interface ScheduledEvent {
-  readonly cron: string;
-  readonly scheduledTime?: number;
-}
-/** Native controller passed unchanged to a Worker handler. Call noRetry on its receiver. */
-interface ScheduledController extends ScheduledEvent {
-  readonly scheduledTime: number;
-  noRetry(): void;
-}
-interface ScheduledContext {
-  waitUntil(promise: Promise<unknown>): void;
-}
-type ScheduledHandler<Env extends object = object> = (controller: ScheduledController, env: Env, context: ScheduledContext) => void | Promise<void>;
-export declare function parseScheduledMetadata(value: unknown): ScheduledMetadata;
-/**
- * Marks a method as a scheduled (cron) handler.
- *
- * @example
- * ```ts
- * @Injectable()
- * class WorkerService {
- *   @Scheduled('0 * * * *')
- *   async hourlyCron() {
- *     console.log('Running hourly');
- *   }
- * }
- * ```
- */
-export declare function Scheduled(cron: string): MethodDecorator;
-//#endregion
 //#region src/decorators/queue-consumer.d.ts
 interface QueueConsumerMetadata {
   queueName: string;
@@ -645,5 +681,4 @@ interface DurableObjectNonceStoreOptions {
  */
 export declare function durableObjectNonceStore(options: DurableObjectNonceStoreOptions): NonceStore;
 //#endregion
-export { type BroadcastNamespace, type CfLiveDriver, type CloudflareRateLimitBinding, type CloudflareRateLimitStoreOptions, type CloudflareRoot, type CloudflareWorkerOptions, ConnectedSocket, type CreateCloudflareAppOptions, type DiskConfig, type DoPitrArmOptions, type DoPitrArmResult, type DoPitrBookmarkRead, type DoPitrId, type DoPitrNamespace, type DoPitrStorage, DoPitrUnavailableError, type DurableObjectLiveOptions, type DurableObjectNonceNamespace, type DurableObjectNonceStoreOptions, type FlagshipBinding, type FlagshipFlagDriverOptions, type KvFlagDriverOptions, type LiveNamespace, MessageBody, type MountOpenApiOptions, type OnGatewayConnection, type OnGatewayDisconnect, type OnGatewayInit, type PresignedUrlConfig, type QueueConsumerMetadata, type ScheduledContext, type ScheduledController, type ScheduledEvent, type ScheduledHandler, type ScheduledMetadata, type StorageModuleOptions, SubscribeMessage, type VelaDoPitrRpc, WebSocketGateway, WebSocketServer, type WsClient, WsException, type WsGatewayRoute, type WsMessage, type WsResponse, type WsServer, armDoPitr, isDoPitrUnavailable, readDoPitrBookmark };
-//# sourceMappingURL=index.d.ts.map
+export { type BroadcastNamespace, type CfLiveDriver, type CloudflareRateLimitBinding, type CloudflareRateLimitStoreOptions, type CloudflareRoot, type CloudflareScheduledEvent, type CloudflareWorkerOptions, type CreateCloudflareAppOptions, type DiskConfig, type DoPitrArmOptions, type DoPitrArmResult, type DoPitrBookmarkRead, type DoPitrId, type DoPitrNamespace, type DoPitrStorage, DoPitrUnavailableError, type DurableObjectLiveOptions, type DurableObjectNonceNamespace, type DurableObjectNonceStoreOptions, type FlagshipBinding, type FlagshipFlagDriverOptions, type KvFlagDriverOptions, type LiveNamespace, type MountOpenApiOptions, type PresignedUrlConfig, type QueueConsumerMetadata, type ScheduledEvent, type StorageModuleOptions, type VelaDoPitrRpc, type WsGatewayRoute, armDoPitr, isDoPitrUnavailable, readDoPitrBookmark };