@velajs/vela 1.12.0 → 1.14.0

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>;