@velajs/vela 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -1,6 +1,51 @@
 # Changelog
 
-## Unreleased
+## 1.14.0 (2026-07-04)
+
+First-party `QueueModule` (roadmap phase 3, "the openness proof"): a whole
+feature module authored on the public API alone — `defineModule` (+ `lazy`),
+`createDiscoverableDecorator`, `registerEntrypointKind`, `app.entrypoints`,
+`runInEntrypointScope`, `buildEntrypointExecutionContext`, `PipelineRunner` —
+machine-verified by an import audit test.
+
+### Added
+
+- **`@velajs/vela/queue`** — platform-agnostic queue subsystem (subpath-only;
+  deliberately NOT re-exported from the main barrel because
+  `@velajs/cloudflare` already exports an unrelated CF-binding `QueueModule`).
+  Producers: `QueueModule.forRoot({ queues: ['email'] })` + per-queue
+  `QueueClient` injected via `queueToken(name)` (`add(jobName, data,
+  { delayMs? })`). Consumers: `@Processor(queue)` classes with
+  `@Process(jobName?)` handlers (named wins over wildcard; duplicates warn,
+  first-wins). Dispatch runs each job in `runInEntrypointScope`
+  (request-scoped deps rebuild per job), re-resolves processors by token
+  through the async seam (lazy consumer modules — async init hooks included —
+  materialize on first job), and applies scoped
+  guards/interceptors/filters through the shared pipeline; unclaimed errors
+  rethrow for platform retry. App-wide `APP_*` components deliberately do NOT
+  run around queue jobs (cloudflare queue/scheduled parity; diverges from the
+  WebSocket dispatcher — revisit framework-wide). The in-core `inline()`
+  driver (edge-pure, no timers) delivers on a microtask (`immediate`) or via
+  `flush()` (`manual`, rejects with `AggregateError` on unclaimed handler
+  errors); platform drivers implement `QueueDriver` out-of-core and call
+  `dispatchQueueJob(container, app.entrypoints, job)`. The module is
+  `lazy: true` (dogfoods 1.13): consumer-only workers defer it entirely;
+  an eager producer's client injection materializes it at bootstrap.
+  `queues` is structural — `forRootAsync({ queues, useFactory })`.
+- **`resolveScopedComponents(type, class, method, container)`** — public
+  pipeline seam surfaced by the openness proof: scoped
+  `@UseGuards`/`@UsePipes`/`@UseInterceptors`/`@UseFilters` resolution for
+  custom dispatchers (declaration order preserved; conventions like
+  closest-first filter reversal stay with the caller).
+- **`EntrypointRegistry` is injectable** — the per-app registry registers
+  into the container (global token) at the end of
+  `callOnApplicationBootstrap()`, so providers that dispatch entrypoints
+  themselves (the queue module's in-process driver binding) resolve it
+  instead of needing a back-reference to the app; `container.has(...)` probes
+  it safely pre-bootstrap (the queue binding falls back to
+  `DiscoveryService` + `deferLazy` for deliveries during bootstrap).
+
+## 1.13.0 (2026-07-04)
 
 Cold-start laziness (roadmap phase 3): modules can defer their entire init to
 first use, and the in-core subsystems an HTTP-only worker doesn't touch now

package/dist/application.js

@@ -220,6 +220,16 @@ export class VelaApplication {
         this.entrypointRegistry = await EntrypointRegistry.build(discovery, this.instances, {
             deferLazy: true
         });
+        // Make the per-app registry injectable (global token): providers that
+        // dispatch entrypoints themselves (the queue module's in-process driver
+        // binding) resolve it instead of needing a back-reference to the app.
+        // Registered AFTER build so anything resolving it sees the final registry;
+        // pre-bootstrap resolution attempts fail the `has()` probe and defer.
+        this.container.register({
+            provide: EntrypointRegistry,
+            useValue: this.entrypointRegistry
+        });
+        this.container.markGlobalToken(EntrypointRegistry);
     }
     /**
    * Materialize every still-pending lazy module (async-safe): construct the

package/dist/index.d.ts

@@ -46,8 +46,8 @@ export type { AdapterContext, RuntimeAdapter } from './factory/adapter';
 export type { VelaCreateOptions } from './factory';
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
 export type { Plugin } from './plugin/plugin';
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
-export type { PipelineRunOptions } from './pipeline/index';
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
+export type { PipelineRunOptions, ResolvedComponentMap } from './pipeline/index';
 export type { HttpArgumentsHost, ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, ReflectableDecorator, CreateDecoratorOptions, } from './pipeline/index';
 export type { Constructor, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, } from './registry/index';
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipeline/index';

package/dist/index.js

@@ -48,7 +48,7 @@ export { registerRouteContributor, getRouteContributors } from "./http/route-con
 // Plugin manifest + composer
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
 // Built-in Pipes
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe } from "./pipeline/index.js";
 // Errors

package/dist/pipeline/index.d.ts

@@ -1,6 +1,8 @@
 export { ComponentManager } from './component.manager';
 export { PipelineRunner } from './pipeline-runner';
 export type { PipelineRunOptions } from './pipeline-runner';
+export { resolveScopedComponents } from './scoped-components';
+export type { ResolvedComponentMap } from './scoped-components';
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch, } from './decorators';
 export { SetMetadata, Reflector } from './reflector';
 export type { ReflectableDecorator, CreateDecoratorOptions } from './reflector';

package/dist/pipeline/index.js

@@ -1,5 +1,6 @@
 export { ComponentManager } from "./component.manager.js";
 export { PipelineRunner } from "./pipeline-runner.js";
+export { resolveScopedComponents } from "./scoped-components.js";
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch } from "./decorators.js";
 export { SetMetadata, Reflector } from "./reflector.js";
 export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./tokens.js";

package/dist/pipeline/scoped-components.d.ts

@@ -0,0 +1,26 @@
+import type { Container } from '../container/container';
+import type { ComponentType, Constructor } from '../registry/types';
+import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from './types';
+export interface ResolvedComponentMap {
+    guard: CanActivate;
+    pipe: PipeTransform;
+    interceptor: NestInterceptor;
+    filter: ExceptionFilter;
+    middleware: NestMiddleware;
+}
+/**
+ * Public seam for custom dispatchers: the `@UseGuards`/`@UsePipes`/
+ * `@UseInterceptors`/`@UseFilters` components scoped to a handler (class-level
+ * then method-level, declaration order), resolved to instances through the
+ * given container (classes constructed with DI; instances passed through).
+ *
+ * Order is preserved exactly as declared — conventions stay with the CALLER:
+ * filters run closest-first, so dispatchers reverse them
+ * (`resolveScopedComponents('filter', ...).reverse()`), and app-wide `APP_*`
+ * components are a separate, transport-specific decision.
+ *
+ * Promoted to the public API by the QueueModule work (the "openness proof"):
+ * it was the one capability custom entrypoint dispatchers needed that only
+ * the internal `ComponentManager` provided.
+ */
+export declare function resolveScopedComponents<T extends ComponentType>(type: T, targetClass: Constructor, methodName: string | symbol, container: Container): ResolvedComponentMap[T][];

package/dist/pipeline/scoped-components.js

@@ -0,0 +1,27 @@
+import { ComponentManager } from "./component.manager.js";
+const RESOLVERS = {
+    guard: ComponentManager.resolveGuards.bind(ComponentManager),
+    pipe: ComponentManager.resolvePipes.bind(ComponentManager),
+    interceptor: ComponentManager.resolveInterceptors.bind(ComponentManager),
+    filter: ComponentManager.resolveFilters.bind(ComponentManager),
+    middleware: ComponentManager.resolveMiddleware.bind(ComponentManager)
+};
+/**
+ * Public seam for custom dispatchers: the `@UseGuards`/`@UsePipes`/
+ * `@UseInterceptors`/`@UseFilters` components scoped to a handler (class-level
+ * then method-level, declaration order), resolved to instances through the
+ * given container (classes constructed with DI; instances passed through).
+ *
+ * Order is preserved exactly as declared — conventions stay with the CALLER:
+ * filters run closest-first, so dispatchers reverse them
+ * (`resolveScopedComponents('filter', ...).reverse()`), and app-wide `APP_*`
+ * components are a separate, transport-specific decision.
+ *
+ * Promoted to the public API by the QueueModule work (the "openness proof"):
+ * it was the one capability custom entrypoint dispatchers needed that only
+ * the internal `ComponentManager` provided.
+ */ export function resolveScopedComponents(type, targetClass, methodName, container) {
+    const scoped = ComponentManager.getScopedComponents(type, targetClass, methodName);
+    const resolve = RESOLVERS[type];
+    return resolve(scoped, container);
+}

package/dist/queue/index.d.ts

@@ -0,0 +1,10 @@
+export { QueueModule, QUEUE_MODULE_OPTIONS } from './queue.module';
+export { Processor, Process, getProcessHandlers } from './queue.decorators';
+export { queueToken, QUEUE_DRIVER, PROCESSOR_METADATA, PROCESS_METADATA } from './queue.tokens';
+export { QueueClient } from './queue.client';
+export { QueueDispatchBinding } from './queue.binding';
+export { dispatchQueueJob } from './queue.dispatch';
+export type { QueueDispatchResult, QueueEntry } from './queue.dispatch';
+export { inline } from './inline.driver';
+export type { InlineQueueDriver, InlineQueueOptions } from './inline.driver';
+export type { AddJobOptions, ProcessMetadata, ProcessorMetadata, QueueDispatchFn, QueueDriver, QueueDriverBindHooks, QueueJob, QueueModuleOptions, } from './queue.types';

package/dist/queue/index.js

@@ -0,0 +1,12 @@
+// @velajs/vela/queue — first-party queue subsystem, authored entirely on the
+// public API (every vela import in src/queue/* comes from '../index'; the
+// openness audit test enforces it). Deliberately NOT re-exported from the
+// main barrel: @velajs/cloudflare already exports an (unrelated) QueueModule
+// for the CF Queues binding, and subpath-only avoids the collision.
+export { QueueModule, QUEUE_MODULE_OPTIONS } from "./queue.module.js";
+export { Processor, Process, getProcessHandlers } from "./queue.decorators.js";
+export { queueToken, QUEUE_DRIVER, PROCESSOR_METADATA, PROCESS_METADATA } from "./queue.tokens.js";
+export { QueueClient } from "./queue.client.js";
+export { QueueDispatchBinding } from "./queue.binding.js";
+export { dispatchQueueJob } from "./queue.dispatch.js";
+export { inline } from "./inline.driver.js";

package/dist/queue/inline.driver.d.ts

@@ -0,0 +1,30 @@
+import type { QueueDriver } from './queue.types';
+export interface InlineQueueOptions {
+    /**
+     * `immediate` (default): deliver on a microtask after `enqueue` resolves —
+     * `add()` resolving does NOT mean the job was handled. Handler errors are
+     * routed to the binding's error hook (container diagnostics), never thrown
+     * into the detached microtask.
+     *
+     * `manual`: buffer until `flush()` — deterministic delivery for tests.
+     */
+    mode?: 'immediate' | 'manual';
+}
+export interface InlineQueueDriver extends QueueDriver {
+    /**
+     * Deliver everything buffered (manual mode; also drains jobs enqueued
+     * before the driver was bound). Resolves with the delivered count; rejects
+     * with an `AggregateError` after attempting ALL buffered jobs if any
+     * handler error went unclaimed — the awaiter exists here, so the
+     * platform-retry rethrow contract is meaningful.
+     */
+    flush(): Promise<number>;
+    /** Jobs currently buffered (unbound immediate + all manual). */
+    readonly size: number;
+}
+/**
+ * In-process driver for dev, tests, and single-isolate apps. Edge-pure: no
+ * timers — `immediate` mode uses `queueMicrotask`. `delayMs` is not
+ * supported (warns once through the bound error hook's diagnostics side).
+ */
+export declare function inline(options?: InlineQueueOptions): InlineQueueDriver;

package/dist/queue/inline.driver.js

@@ -0,0 +1,58 @@
+/**
+ * In-process driver for dev, tests, and single-isolate apps. Edge-pure: no
+ * timers — `immediate` mode uses `queueMicrotask`. `delayMs` is not
+ * supported (warns once through the bound error hook's diagnostics side).
+ */ export function inline(options = {}) {
+    const mode = options.mode ?? 'immediate';
+    const buffer = [];
+    let dispatch;
+    let onError;
+    let warnedDelay = false;
+    const deliverDetached = (job)=>{
+        queueMicrotask(()=>{
+            void dispatch(job).catch((error)=>onError?.(error, job));
+        });
+    };
+    return {
+        kind: 'inline',
+        get size () {
+            return buffer.length;
+        },
+        async enqueue (job, addOptions) {
+            if (addOptions?.delayMs !== undefined && !warnedDelay) {
+                warnedDelay = true;
+                console.warn(`[vela] inline() queue driver does not support delayMs — job '${job.name}' delivers without delay.`);
+            }
+            if (mode === 'manual' || !dispatch) {
+                buffer.push(job);
+                return;
+            }
+            deliverDetached(job);
+        },
+        bind (fn, hooks) {
+            dispatch = fn;
+            onError = hooks?.onError;
+            if (mode === 'immediate' && buffer.length > 0) {
+                for (const job of buffer.splice(0))deliverDetached(job);
+            }
+        },
+        async flush () {
+            if (!dispatch) return 0;
+            const jobs = buffer.splice(0);
+            const errors = [];
+            let delivered = 0;
+            for (const job of jobs){
+                try {
+                    await dispatch(job);
+                    delivered++;
+                } catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0) {
+                throw new AggregateError(errors, `queue flush: ${errors.length} of ${jobs.length} jobs failed (${delivered} delivered)`);
+            }
+            return delivered;
+        }
+    };
+}

package/dist/queue/queue.binding.d.ts

@@ -0,0 +1,23 @@
+import type { Container, DiscoveryService } from '../index';
+import type { QueueDriver } from './queue.types';
+/**
+ * Wires a `QueueModule` instance's driver to the app: binds in-process
+ * delivery to the dispatch core and validates that no other module instance
+ * provides the same queue names.
+ *
+ * Delivery resolves processors from the per-app `EntrypointRegistry` once it
+ * exists (registered into the container at the end of
+ * `callOnApplicationBootstrap`); deliveries that arrive earlier (a producer's
+ * `onModuleInit` calling `add()`) fall back to `DiscoveryService` with
+ * `deferLazy` — identical entries, no buffering, no lost jobs.
+ *
+ * Every `QueueClient` injects this binding, so the driver is always bound
+ * before the first `add()` — including when the module materializes lazily.
+ */
+export declare class QueueDispatchBinding {
+    private readonly container;
+    private readonly discovery;
+    constructor(container: Container, discovery: DiscoveryService, driver: QueueDriver, queues: string[]);
+    private deliver;
+    private routeError;
+}

package/dist/queue/queue.binding.js

@@ -0,0 +1,53 @@
+import { EntrypointRegistry } from "../index.js";
+import { dispatchJobToEntries } from "./queue.dispatch.js";
+import { PROCESSOR_METADATA, queueToken } from "./queue.tokens.js";
+/**
+ * Wires a `QueueModule` instance's driver to the app: binds in-process
+ * delivery to the dispatch core and validates that no other module instance
+ * provides the same queue names.
+ *
+ * Delivery resolves processors from the per-app `EntrypointRegistry` once it
+ * exists (registered into the container at the end of
+ * `callOnApplicationBootstrap`); deliveries that arrive earlier (a producer's
+ * `onModuleInit` calling `add()`) fall back to `DiscoveryService` with
+ * `deferLazy` — identical entries, no buffering, no lost jobs.
+ *
+ * Every `QueueClient` injects this binding, so the driver is always bound
+ * before the first `add()` — including when the module materializes lazily.
+ */ export class QueueDispatchBinding {
+    container;
+    discovery;
+    constructor(container, discovery, driver, queues){
+        this.container = container;
+        this.discovery = discovery;
+        for (const queue of queues){
+            const owners = container.getOwnerModuleIds(queueToken(queue));
+            if (owners.length > 1) {
+                throw new Error(`Queue '${queue}' is provided by multiple QueueModule instances (${owners.join(', ')}). ` + `Queue names must be unique per app — either dedup the forRoot options or rename the queue.`);
+            }
+        }
+        driver.bind?.((job)=>this.deliver(job), {
+            onError: (error, job)=>this.routeError(error, job)
+        });
+    }
+    async deliver(job) {
+        const entries = this.container.has(EntrypointRegistry) ? this.container.resolve(EntrypointRegistry).ofKind('queue').map((ep)=>({
+                token: ep.token,
+                meta: ep.meta
+            })) : this.discovery.providersWithMeta(PROCESSOR_METADATA, {
+            deferLazy: true
+        }).map((found)=>({
+                token: found.token,
+                meta: found.meta
+            }));
+        await dispatchJobToEntries(this.container, entries, job);
+    }
+    routeError(error, job) {
+        const mode = this.container.getDiagnostics();
+        if (mode === 'silent') return;
+        if (mode === 'throw') {
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        console.error(`[vela] unhandled error processing queue job '${job.name}' on '${job.queue}':`, error);
+    }
+}

package/dist/queue/queue.client.d.ts

@@ -0,0 +1,20 @@
+import type { AddJobOptions, QueueDriver, QueueJob } from './queue.types';
+/**
+ * Producer handle for one named queue — inject via `queueToken(name)`:
+ *
+ * ```ts
+ * constructor(@Inject(queueToken('email')) private readonly email: QueueClient) {}
+ * await this.email.add('welcome', { userId });
+ * ```
+ *
+ * `add()` resolves when the DRIVER accepted the job, not when a processor
+ * handled it (the inline driver's `immediate` mode delivers on a following
+ * microtask; platform drivers deliver in another isolate entirely).
+ */
+export declare class QueueClient {
+    private readonly queue;
+    private readonly driver;
+    constructor(queue: string, driver: QueueDriver);
+    get name(): string;
+    add<T>(jobName: string, data: T, options?: AddJobOptions): Promise<QueueJob<T>>;
+}

package/dist/queue/queue.client.js

@@ -0,0 +1,33 @@
+/**
+ * Producer handle for one named queue — inject via `queueToken(name)`:
+ *
+ * ```ts
+ * constructor(@Inject(queueToken('email')) private readonly email: QueueClient) {}
+ * await this.email.add('welcome', { userId });
+ * ```
+ *
+ * `add()` resolves when the DRIVER accepted the job, not when a processor
+ * handled it (the inline driver's `immediate` mode delivers on a following
+ * microtask; platform drivers deliver in another isolate entirely).
+ */ export class QueueClient {
+    queue;
+    driver;
+    constructor(queue, driver){
+        this.queue = queue;
+        this.driver = driver;
+    }
+    get name() {
+        return this.queue;
+    }
+    async add(jobName, data, options = {}) {
+        const job = {
+            id: crypto.randomUUID(),
+            queue: this.queue,
+            name: jobName,
+            data,
+            attempt: 1
+        };
+        await this.driver.enqueue(job, options);
+        return job;
+    }
+}

package/dist/queue/queue.decorators.d.ts

@@ -0,0 +1,23 @@
+import type { ProcessMetadata } from './queue.types';
+/**
+ * Marks a provider class as a processor for one queue:
+ *
+ * ```ts
+ * @Processor('email')
+ * @Injectable()
+ * class EmailProcessor {
+ *   @Process('welcome')
+ *   async sendWelcome(job: QueueJob<{ userId: string }>) { ... }
+ * }
+ * ```
+ */
+export declare function Processor(queueName: string): ClassDecorator;
+/**
+ * Marks a processor method as the handler for a job name. Omit the name for
+ * the wildcard handler (receives every job on the queue that has no named
+ * handler). Named handlers win over the wildcard; a duplicate registration
+ * for the same name is first-wins with a diagnostics warning at dispatch.
+ */
+export declare function Process(jobName?: string): MethodDecorator;
+/** `@Process` entries declared on a processor class (declaration order). */
+export declare function getProcessHandlers(processorClass: object): ProcessMetadata[];

package/dist/queue/queue.decorators.js

@@ -0,0 +1,46 @@
+import { createDiscoverableDecorator, defineMetadata, getMetadata, registerEntrypointKind } from "../index.js";
+import { PROCESS_METADATA, PROCESSOR_METADATA } from "./queue.tokens.js";
+const ProcessorMeta = createDiscoverableDecorator(PROCESSOR_METADATA);
+// The open entrypoint kind: adapters enumerate processors via
+// `app.entrypoints.ofKind<ProcessorMetadata>('queue')`. Declared at import
+// time next to the decorator — zero kernel involvement.
+registerEntrypointKind({
+    kind: 'queue',
+    metaKey: PROCESSOR_METADATA,
+    level: 'class'
+});
+/**
+ * Marks a provider class as a processor for one queue:
+ *
+ * ```ts
+ * @Processor('email')
+ * @Injectable()
+ * class EmailProcessor {
+ *   @Process('welcome')
+ *   async sendWelcome(job: QueueJob<{ userId: string }>) { ... }
+ * }
+ * ```
+ */ export function Processor(queueName) {
+    return ProcessorMeta({
+        queueName
+    });
+}
+/**
+ * Marks a processor method as the handler for a job name. Omit the name for
+ * the wildcard handler (receives every job on the queue that has no named
+ * handler). Named handlers win over the wildcard; a duplicate registration
+ * for the same name is first-wins with a diagnostics warning at dispatch.
+ */ export function Process(jobName) {
+    return (target, propertyKey)=>{
+        const ctor = target.constructor;
+        const existing = getMetadata(PROCESS_METADATA, ctor) ?? [];
+        existing.push({
+            jobName,
+            methodName: propertyKey
+        });
+        defineMetadata(PROCESS_METADATA, existing, ctor);
+    };
+}
+/** `@Process` entries declared on a processor class (declaration order). */ export function getProcessHandlers(processorClass) {
+    return getMetadata(PROCESS_METADATA, processorClass) ?? [];
+}

package/dist/queue/queue.dispatch.d.ts

@@ -0,0 +1,36 @@
+import type { Container, EntrypointRegistry, Token } from '../index';
+import type { ProcessorMetadata, QueueJob } from './queue.types';
+export interface QueueDispatchResult {
+    /** Processors that ran a handler for this job. */
+    handled: number;
+}
+/** One dispatchable processor: its class token + `@Processor` meta. */
+export interface QueueEntry {
+    token: Token;
+    meta: ProcessorMetadata;
+}
+/**
+ * Deliver one job to every `@Processor` of its queue — the primitive both the
+ * in-core `inline()` driver and platform adapters call.
+ *
+ * Each matching processor runs inside `runInEntrypointScope` (request-scoped
+ * dependencies rebuild per job) and is re-resolved BY TOKEN through the async
+ * seam, so processors living in `lazy: true` modules materialize cleanly on
+ * first dispatch — async providers and lifecycle hooks included. Scoped
+ * guards/interceptors/filters run through `PipelineRunner`
+ * (`getType() === 'queue'`, `getPayload()` is the job); app-wide `APP_*`
+ * components deliberately do NOT apply (cloudflare queue/scheduled parity —
+ * documented divergence from the WebSocket dispatcher).
+ *
+ * Errors no scoped filter claims RETHROW so awaiting platforms keep their
+ * retry semantics; fire-and-forget callers (inline `immediate` mode) must
+ * catch — `QueueDispatchBinding` routes those to diagnostics.
+ */
+export declare function dispatchQueueJob(container: Container, entrypoints: EntrypointRegistry, job: QueueJob): Promise<QueueDispatchResult>;
+/**
+ * Entry-list core shared by `dispatchQueueJob` (registry) and the in-process
+ * driver binding (discovery fallback before the registry exists). Entries are
+ * tokens + meta ONLY — every processor is re-resolved by token in its own
+ * scope, so request-scoped and lazy-module processors work on both paths.
+ */
+export declare function dispatchJobToEntries(container: Container, entries: QueueEntry[], job: QueueJob): Promise<QueueDispatchResult>;

package/dist/queue/queue.dispatch.js

@@ -0,0 +1,102 @@
+import { buildEntrypointExecutionContext, PipelineRunner, resolveScopedComponents, runInEntrypointScope, shouldFilterCatch } from "../index.js";
+import { getProcessHandlers } from "./queue.decorators.js";
+const warnedDuplicates = new WeakSet();
+function selectHandler(container, processorClass, handlers, jobName) {
+    const named = handlers.filter((h)=>h.jobName === jobName);
+    const pool = named.length > 0 ? named : handlers.filter((h)=>h.jobName === undefined);
+    if (pool.length > 1 && !warnedDuplicates.has(processorClass)) {
+        warnedDuplicates.add(processorClass);
+        const label = named.length > 0 ? `@Process('${jobName}')` : '@Process() (wildcard)';
+        const message = `[vela] duplicate ${label} handlers on ${processorClass.name}; ` + `keeping the first ('${String(pool[0].methodName)}').`;
+        if (container.getDiagnostics() === 'throw') throw new Error(message);
+        if (container.getDiagnostics() === 'log') console.warn(message);
+    }
+    return pool[0];
+}
+/**
+ * Deliver one job to every `@Processor` of its queue — the primitive both the
+ * in-core `inline()` driver and platform adapters call.
+ *
+ * Each matching processor runs inside `runInEntrypointScope` (request-scoped
+ * dependencies rebuild per job) and is re-resolved BY TOKEN through the async
+ * seam, so processors living in `lazy: true` modules materialize cleanly on
+ * first dispatch — async providers and lifecycle hooks included. Scoped
+ * guards/interceptors/filters run through `PipelineRunner`
+ * (`getType() === 'queue'`, `getPayload()` is the job); app-wide `APP_*`
+ * components deliberately do NOT apply (cloudflare queue/scheduled parity —
+ * documented divergence from the WebSocket dispatcher).
+ *
+ * Errors no scoped filter claims RETHROW so awaiting platforms keep their
+ * retry semantics; fire-and-forget callers (inline `immediate` mode) must
+ * catch — `QueueDispatchBinding` routes those to diagnostics.
+ */ export async function dispatchQueueJob(container, entrypoints, job) {
+    const entries = entrypoints.ofKind('queue').map((ep)=>({
+            token: ep.token,
+            meta: ep.meta
+        }));
+    return dispatchJobToEntries(container, entries, job);
+}
+/**
+ * Entry-list core shared by `dispatchQueueJob` (registry) and the in-process
+ * driver binding (discovery fallback before the registry exists). Entries are
+ * tokens + meta ONLY — every processor is re-resolved by token in its own
+ * scope, so request-scoped and lazy-module processors work on both paths.
+ */ export async function dispatchJobToEntries(container, entries, job) {
+    const processors = entries.filter((entry)=>entry.meta.queueName === job.queue);
+    if (processors.length === 0) {
+        if (container.getDiagnostics() === 'log') {
+            console.warn(`[vela] queue job '${job.name}' on '${job.queue}' has no @Processor('${job.queue}') — dropped.`);
+        }
+        return {
+            handled: 0
+        };
+    }
+    // All matching processors receive the job; the first unclaimed error
+    // rejects the whole dispatch (platform retries the delivery — CF parity).
+    const outcomes = await Promise.all(processors.map((entry)=>dispatchToProcessor(container, entry.token, job)));
+    return {
+        handled: outcomes.filter(Boolean).length
+    };
+}
+async function dispatchToProcessor(container, processorClass, job) {
+    const handler = selectHandler(container, processorClass, getProcessHandlers(processorClass), job.name);
+    if (!handler) {
+        if (container.getDiagnostics() === 'log') {
+            console.warn(`[vela] no @Process('${job.name}') (or wildcard) handler on ` + `${processorClass.name} for queue '${job.queue}' — skipped.`);
+        }
+        return false;
+    }
+    return runInEntrypointScope(container, async (scope)=>{
+        // Async seam: materializes lazy processor modules (drainAsync awaits
+        // their async providers/hooks) and rebuilds request-scoped processors.
+        const instance = await scope.resolveAsync(processorClass);
+        const context = buildEntrypointExecutionContext('queue', processorClass, handler.methodName, job);
+        const guards = resolveScopedComponents('guard', processorClass, handler.methodName, scope);
+        const interceptors = resolveScopedComponents('interceptor', processorClass, handler.methodName, scope);
+        // Closest-first: handler/class filters reversed by the caller (WS/CF convention).
+        const filters = resolveScopedComponents('filter', processorClass, handler.methodName, scope).reverse();
+        try {
+            await PipelineRunner.run({
+                context,
+                guards,
+                interceptors,
+                resolveArgs: async ()=>[
+                        job
+                    ],
+                invoke: async (args)=>{
+                    const method = instance[handler.methodName];
+                    return method.apply(instance, args);
+                }
+            });
+            return true;
+        } catch (error) {
+            for (const filter of filters){
+                if (shouldFilterCatch(filter, error)) {
+                    await filter.catch(error, context);
+                    return true;
+                }
+            }
+            throw error;
+        }
+    });
+}

package/dist/queue/queue.module.d.ts

@@ -0,0 +1,32 @@
+import type { QueueModuleOptions } from './queue.types';
+/**
+ * First-party queue module — authored 100% on vela's public API (the
+ * roadmap's "openness proof"). Producers inject a per-queue `QueueClient`
+ * via `queueToken(name)`; consumers are `@Processor`/`@Process` classes in
+ * ordinary user modules; platforms deliver through `dispatchQueueJob` or the
+ * in-core `inline()` driver.
+ *
+ * ```ts
+ * imports: [QueueModule.forRoot({ queues: ['email'] })]
+ * ```
+ *
+ * `lazy: true` (dogfoods 1.13): the module materializes when an eager
+ * producer injects a client (bootstrap — same structural reality that keeps
+ * WebSocketModule eager) or, in consumer-only workers, at the first
+ * delivered job.
+ *
+ * `queues` is STRUCTURAL: clients are options-derived providers, so
+ * `forRootAsync` callers pass it alongside the factory —
+ * `forRootAsync({ queues: ['email'], useFactory: () => ({ driver }) })`.
+ * Note that async options inherit the 1.13 lazy-module contract: the module
+ * must first materialize through an async seam (an eager producer's injection
+ * during the bootstrap sweep — the common case — or
+ * `app.materializeLazyModules()`); a synchronous first touch throws the
+ * descriptive sync-seam error.
+ */
+declare const ConfigurableModuleClass: import("../module").ConfigurableModuleClassType<QueueModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>, MODULE_OPTIONS_TOKEN: import("../container").InjectionToken<QueueModuleOptions>;
+export declare class QueueModule extends ConfigurableModuleClass {
+}
+export { MODULE_OPTIONS_TOKEN as QUEUE_MODULE_OPTIONS };

package/dist/queue/queue.module.js

@@ -0,0 +1,80 @@
+import { Container, defineModule, DiscoveryService, stableHash } from "../index.js";
+import { inline } from "./inline.driver.js";
+import { QueueClient } from "./queue.client.js";
+import { QueueDispatchBinding } from "./queue.binding.js";
+import { QUEUE_DRIVER, queueToken } from "./queue.tokens.js";
+/**
+ * First-party queue module — authored 100% on vela's public API (the
+ * roadmap's "openness proof"). Producers inject a per-queue `QueueClient`
+ * via `queueToken(name)`; consumers are `@Processor`/`@Process` classes in
+ * ordinary user modules; platforms deliver through `dispatchQueueJob` or the
+ * in-core `inline()` driver.
+ *
+ * ```ts
+ * imports: [QueueModule.forRoot({ queues: ['email'] })]
+ * ```
+ *
+ * `lazy: true` (dogfoods 1.13): the module materializes when an eager
+ * producer injects a client (bootstrap — same structural reality that keeps
+ * WebSocketModule eager) or, in consumer-only workers, at the first
+ * delivered job.
+ *
+ * `queues` is STRUCTURAL: clients are options-derived providers, so
+ * `forRootAsync` callers pass it alongside the factory —
+ * `forRootAsync({ queues: ['email'], useFactory: () => ({ driver }) })`.
+ * Note that async options inherit the 1.13 lazy-module contract: the module
+ * must first materialize through an async seam (an eager producer's injection
+ * during the bootstrap sweep — the common case — or
+ * `app.materializeLazyModules()`); a synchronous first touch throws the
+ * descriptive sync-seam error.
+ */ const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = defineModule({
+    name: 'Queue',
+    lazy: true,
+    key: (o)=>stableHash({
+            queues: o.queues ?? [],
+            driver: o.driver?.kind ?? 'inline'
+        }),
+    setup: ({ OPTIONS, options })=>{
+        const queues = options.queues;
+        if (!queues || queues.length === 0) {
+            throw new Error("QueueModule requires 'queues' as a structural option: " + "QueueModule.forRoot({ queues: ['email'] }) — for forRootAsync, pass it alongside " + 'the factory: forRootAsync({ queues: [...], useFactory }).');
+        }
+        const clientProviders = queues.map((name)=>({
+                provide: queueToken(name),
+                useFactory: (driver, _binding)=>new QueueClient(name, driver),
+                inject: [
+                    QUEUE_DRIVER,
+                    QueueDispatchBinding
+                ]
+            }));
+        return {
+            providers: [
+                {
+                    provide: QUEUE_DRIVER,
+                    useFactory: (o)=>o.driver ?? inline(),
+                    inject: [
+                        OPTIONS
+                    ]
+                },
+                {
+                    provide: QueueDispatchBinding,
+                    useFactory: (container, discovery, driver)=>new QueueDispatchBinding(container, discovery, driver, queues),
+                    inject: [
+                        Container,
+                        DiscoveryService,
+                        QUEUE_DRIVER
+                    ]
+                },
+                ...clientProviders
+            ],
+            exports: [
+                QUEUE_DRIVER,
+                QueueDispatchBinding,
+                ...queues.map((name)=>queueToken(name))
+            ]
+        };
+    }
+});
+export class QueueModule extends ConfigurableModuleClass {
+}
+export { MODULE_OPTIONS_TOKEN as QUEUE_MODULE_OPTIONS };

package/dist/queue/queue.tokens.d.ts

@@ -0,0 +1,21 @@
+import { InjectionToken } from '../index';
+import type { QueueClient } from './queue.client';
+import type { QueueDriver } from './queue.types';
+export declare const PROCESSOR_METADATA = "vela:queue:processor";
+export declare const PROCESS_METADATA = "vela:queue:process";
+/** The driver in effect for a `QueueModule` instance. */
+export declare const QUEUE_DRIVER: InjectionToken<QueueDriver>;
+/**
+ * The injection token for a named queue's `QueueClient`:
+ *
+ * ```ts
+ * constructor(@Inject(queueToken('email')) private readonly email: QueueClient) {}
+ * ```
+ *
+ * Memoized per name (HMR-stable). Deliberately NO `InjectionToken` default
+ * factory: the container resolves default-factory tokens from the root bucket
+ * BEFORE walking module imports, which would break the exported-provider
+ * path — the token description (`vela:queue:client:<name>`) keeps the
+ * no-provider error readable instead.
+ */
+export declare function queueToken(name: string): InjectionToken<QueueClient>;

package/dist/queue/queue.tokens.js

@@ -0,0 +1,34 @@
+import { InjectionToken } from "../index.js";
+export const PROCESSOR_METADATA = 'vela:queue:processor';
+export const PROCESS_METADATA = 'vela:queue:process';
+/** The driver in effect for a `QueueModule` instance. */ export const QUEUE_DRIVER = new InjectionToken('vela:queue:driver');
+// Token identity must survive Vite HMR re-evals (a consumer module that was
+// NOT re-evaluated still holds the token minted by the previous generation),
+// so the name → token map is anchored on globalThis exactly like the
+// entrypoint kind store and MetadataRegistry state.
+const TOKEN_STORE_KEY = Symbol.for('vela:queue:client-tokens:v1');
+function tokenStore() {
+    const g = globalThis;
+    return g[TOKEN_STORE_KEY] ??= new Map();
+}
+/**
+ * The injection token for a named queue's `QueueClient`:
+ *
+ * ```ts
+ * constructor(@Inject(queueToken('email')) private readonly email: QueueClient) {}
+ * ```
+ *
+ * Memoized per name (HMR-stable). Deliberately NO `InjectionToken` default
+ * factory: the container resolves default-factory tokens from the root bucket
+ * BEFORE walking module imports, which would break the exported-provider
+ * path — the token description (`vela:queue:client:<name>`) keeps the
+ * no-provider error readable instead.
+ */ export function queueToken(name) {
+    const store = tokenStore();
+    let token = store.get(name);
+    if (!token) {
+        token = new InjectionToken(`vela:queue:client:${name}`);
+        store.set(name, token);
+    }
+    return token;
+}

package/dist/queue/queue.types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One job as handed to `@Process` handlers and drivers. Ids are minted by the
+ * client via `crypto.randomUUID()` (Web Crypto — edge-safe).
+ */
+export interface QueueJob<T = unknown> {
+    id: string;
+    /** Queue the job was added to (`QueueModule.forRoot({ queues })` name). */
+    queue: string;
+    /** Job name — matched against `@Process(name)`; unnamed handlers catch the rest. */
+    name: string;
+    data: T;
+    /** Delivery attempt, 1-based. Platform drivers increment on retry. */
+    attempt: number;
+}
+export interface AddJobOptions {
+    /**
+     * Requested delivery delay. Honored only by drivers that support it — the
+     * in-core `inline()` driver does not and warns once (log diagnostics).
+     */
+    delayMs?: number;
+}
+/** The function a driver calls to deliver one job into the app's processors. */
+export type QueueDispatchFn = (job: QueueJob) => Promise<void>;
+export interface QueueDriverBindHooks {
+    /**
+     * Where fire-and-forget delivery errors go (the inline driver's
+     * `immediate` mode has no awaiter to rethrow into). Wired to the
+     * container's diagnostics by `QueueDispatchBinding`.
+     */
+    onError?: (error: unknown, job: QueueJob) => void;
+}
+/**
+ * Producer/transport seam. `enqueue` accepts a job for later (or immediate)
+ * delivery; drivers that deliver in-process implement `bind` to receive the
+ * app's dispatch function. Platform packages (Cloudflare Queues, Redis, …)
+ * implement this interface out-of-core.
+ */
+export interface QueueDriver {
+    readonly kind: string;
+    enqueue(job: QueueJob, options?: AddJobOptions): Promise<void>;
+    bind?(dispatch: QueueDispatchFn, hooks?: QueueDriverBindHooks): void;
+}
+export interface QueueModuleOptions {
+    /**
+     * Queue names this instance provides clients for. STRUCTURAL — must be
+     * known at `forRoot`/`forRootAsync` call time (clients are options-derived
+     * providers); `forRootAsync` callers pass it alongside the factory.
+     */
+    queues?: string[];
+    /** Defaults to the in-core `inline()` driver. */
+    driver?: QueueDriver;
+}
+/** Class-level meta written by `@Processor(queueName)` (the 'queue' entrypoint kind). */
+export interface ProcessorMetadata {
+    queueName: string;
+}
+/** Per-handler meta written by `@Process(jobName?)`. */
+export interface ProcessMetadata {
+    jobName?: string;
+    methodName: string | symbol;
+}

package/dist/queue/queue.types.js

@@ -0,0 +1,4 @@
+/**
+ * One job as handed to `@Process` handlers and drivers. Ids are minted by the
+ * client via `crypto.randomUUID()` (Web Crypto — edge-safe).
+ */ /** Per-handler meta written by `@Process(jobName?)`. */ export { };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,6 +34,10 @@
       "types": "./dist/i18n/index.d.ts",
       "import": "./dist/i18n/index.js"
     },
+    "./queue": {
+      "types": "./dist/queue/index.d.ts",
+      "import": "./dist/queue/index.js"
+    },
     "./storage": {
       "types": "./dist/storage/index.d.ts",
       "import": "./dist/storage/index.js"