@velajs/vela 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -1,6 +1,76 @@
 # Changelog
 
-## Unreleased
+## 1.15.0 (2026-07-04)
+
+Introspection seams for `@velajs/cli` (roadmap phase 3, CLI introspection):
+serializable, zero-instantiation views of the app the CLI renders instead of
+re-deriving framework internals.
+
+### Added
+
+- **`app.describeRoutes(): RouteDescription[]`** — every explicit controller
+  route exactly as `build()` registered it: method AS DECLARED (`@Head()`
+  reports HEAD even though Hono serves it under GET), fully composed path
+  (global prefix + version segment + controller prefix + route path),
+  controller name, handler name, version. Contributed routes
+  (`RouteContributor`/CRUD) mount directly on Hono and are observable via
+  `getHonoApp().routes`.
+- **`app.getGlobalPrefix()`** — the prefix in effect ('' when none); also
+  what `openapi` tooling threads into `createOpenApiDocument`.
+- **`Container.getModuleDescriptions(): ModuleDescription[]`** — the loaded
+  module graph (moduleId, imports, isGlobal, lazy, provider/export token
+  labels), load order plus the `__root__` bucket; reads registration state
+  only — safe pre/post bootstrap, never constructs, never claims lazy
+  modules.
+- **`describeToken(token)`** — the token-label helper vela's own errors use,
+  exported for tooling.
+
+## 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.d.ts

@@ -2,7 +2,7 @@ import type { Hono } from 'hono';
 import type { Container } from './container/container';
 import type { Token } from './container/types';
 import { EntrypointRegistry } from './entrypoint/entrypoint.registry';
-import type { RouteManager } from './http/route.manager';
+import type { RouteDescription, RouteManager } from './http/route.manager';
 import type { MountOpenApiOptions } from './openapi/types';
 import type { FilterType, GuardType, InterceptorType, PipeType } from './registry/types';
 export declare class VelaApplication {
@@ -25,6 +25,15 @@ export declare class VelaApplication {
     setInstances(instances: unknown[]): void;
     get<T>(token: Token<T>): T;
     getHonoApp(): Hono;
+    /**
+     * Every explicit controller route as the framework registered it (fully
+     * composed paths — the `vela route list` seam). Requires built routes;
+     * contributed routes (`@velajs/crud`) mount directly on Hono and are
+     * observable via `getHonoApp().routes` instead.
+     */
+    describeRoutes(): RouteDescription[];
+    /** The global route prefix in effect ('' when none). */
+    getGlobalPrefix(): string;
     useGlobalPipes(...pipes: PipeType[]): this;
     useGlobalGuards(...guards: GuardType[]): this;
     useGlobalInterceptors(...interceptors: InterceptorType[]): this;

package/dist/application.js

@@ -63,6 +63,18 @@ export class VelaApplication {
     getHonoApp() {
         return this.getApp();
     }
+    /**
+   * Every explicit controller route as the framework registered it (fully
+   * composed paths — the `vela route list` seam). Requires built routes;
+   * contributed routes (`@velajs/crud`) mount directly on Hono and are
+   * observable via `getHonoApp().routes` instead.
+   */ describeRoutes() {
+        this.getApp(); // same routes-not-built guard as every HTTP accessor
+        return this.routeManager.getRouteDescriptions();
+    }
+    /** The global route prefix in effect ('' when none). */ getGlobalPrefix() {
+        return this.routeManager.getGlobalPrefix();
+    }
     // Pipeline components — applied at request time, no rebuild needed
     useGlobalPipes(...pipes) {
         this.routeManager.useGlobalPipes(...pipes);
@@ -220,6 +232,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/container/container.d.ts

@@ -1,5 +1,5 @@
 import { Scope } from '../constants';
-import type { ContainerOptions, Diagnostics, LazyResolutionHook, ModuleScope, ProviderOptions, Token, Type } from './types';
+import type { ContainerOptions, Diagnostics, LazyResolutionHook, ModuleDescription, ModuleScope, ProviderOptions, Token, Type } from './types';
 /**
  * Per-module provider buckets. Each module instance owns its providers under
  * its `moduleId`; the same logical token can have distinct registrations in
@@ -95,6 +95,13 @@ export declare class Container {
      * binding module — so framework adapters can initialize all of them.
      */
     getUseValues(): unknown[];
+    /**
+     * Serializable description of every loaded module instance (load order),
+     * plus the `__root__` bucket (bootstrap primitives) when non-empty —
+     * the `vela module graph` seam. Reads registration state only: safe pre-
+     * and post-bootstrap, never constructs, never claims lazy modules.
+     */
+    getModuleDescriptions(): ModuleDescription[];
     /**
      * Compute request-scope bubbling for every registration (call once at
      * bootstrap, after all providers are registered). A provider whose declared

package/dist/container/container.js

@@ -1,7 +1,7 @@
 import { Scope } from "../constants.js";
 import { disposeInstance, isDisposable } from "./disposable.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
-import { ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
+import { describeToken, ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
 const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips type-only imports at ' + 'runtime and `design:paramtypes` emits `Object`/`undefined` for their ' + 'positions. Use a runtime `import { X }` for DI tokens.';
 /**
  * Sentinel comparing a token to the bare `Object` class — `design:paramtypes`
@@ -415,6 +415,44 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         return out;
     }
     /**
+   * Serializable description of every loaded module instance (load order),
+   * plus the `__root__` bucket (bootstrap primitives) when non-empty —
+   * the `vela module graph` seam. Reads registration state only: safe pre-
+   * and post-bootstrap, never constructs, never claims lazy modules.
+   */ getModuleDescriptions() {
+        const out = [];
+        for (const scope of this.scopes.values()){
+            out.push({
+                moduleId: scope.moduleId,
+                imports: [
+                    ...scope.importedModules
+                ],
+                isGlobal: scope.isGlobal,
+                lazy: scope.lazy === true,
+                providers: [
+                    ...this.providers.get(scope.moduleId)?.keys() ?? []
+                ].map(describeToken),
+                exports: [
+                    ...scope.exportedTokens
+                ].map(describeToken)
+            });
+        }
+        const rootBucket = this.providers.get(ROOT_MODULE_ID);
+        if (rootBucket && rootBucket.size > 0) {
+            out.push({
+                moduleId: ROOT_MODULE_ID,
+                imports: [],
+                isGlobal: false,
+                lazy: false,
+                providers: [
+                    ...rootBucket.keys()
+                ].map(describeToken),
+                exports: []
+            });
+        }
+        return out;
+    }
+    /**
    * Compute request-scope bubbling for every registration (call once at
    * bootstrap, after all providers are registered). A provider whose declared
    * scope is not REQUEST but which (transitively) depends on a request-scoped

package/dist/container/index.d.ts

@@ -1,6 +1,6 @@
 export { Container } from './container';
 export { Injectable, Inject, Optional, isInjectable, getScope } from './decorators';
-export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, } from './types';
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, describeToken, } from './types';
 export { ModuleRef } from './module-ref';
 export { mixin } from './mixin';
-export type { Type, Token, InferToken, InferTokens, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ContainerOptions, Diagnostics, } from './types';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './types';

package/dist/container/index.js

@@ -1,5 +1,5 @@
 export { Container } from "./container.js";
 export { Injectable, Inject, Optional, isInjectable, getScope } from "./decorators.js";
-export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, describeToken } from "./types.js";
 export { ModuleRef } from "./module-ref.js";
 export { mixin } from "./mixin.js";

package/dist/container/types.d.ts

@@ -117,6 +117,29 @@ export type Diagnostics = 'silent' | 'log' | 'throw';
 export interface ContainerOptions {
     diagnostics?: Diagnostics;
 }
+/**
+ * Human-readable token label — class name, `InjectionToken(desc)`, symbol
+ * string, or String() fallback. Public so introspection tooling (module
+ * graphs, entrypoint listings) renders tokens the same way vela's own errors
+ * do.
+ */
+export declare function describeToken(token: Token): string;
+/**
+ * One module instance in the loaded graph, serializable (strings only) —
+ * what `Container.getModuleDescriptions()` returns for introspection tooling
+ * (`vela module graph`). Reads registration state only; never constructs.
+ */
+export interface ModuleDescription {
+    moduleId: string;
+    /** moduleIds this instance imports. */
+    imports: string[];
+    isGlobal: boolean;
+    lazy: boolean;
+    /** Token labels registered in this instance's bucket (registration order). */
+    providers: string[];
+    /** Token labels this instance exports. */
+    exports: string[];
+}
 export declare class ModuleVisibilityError extends Error {
     readonly moduleId: string;
     readonly token: Token;

package/dist/container/types.js

@@ -18,7 +18,12 @@ export class ForwardRef {
 export function forwardRef(factory) {
     return new ForwardRef(factory);
 }
-function describeToken(token) {
+/**
+ * Human-readable token label — class name, `InjectionToken(desc)`, symbol
+ * string, or String() fallback. Public so introspection tooling (module
+ * graphs, entrypoint listings) renders tokens the same way vela's own errors
+ * do.
+ */ export function describeToken(token) {
     if (token instanceof InjectionToken) return token.toString();
     if (typeof token === 'function') return token.name;
     if (typeof token === 'symbol') return token.toString();

package/dist/http/route.manager.d.ts

@@ -5,6 +5,23 @@ import type { MiddlewareRouteDefinition } from '../module/middleware';
 import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from '../pipeline/types';
 import type { FilterType, GuardType, InterceptorType, MiddlewareType, PipeType } from '../registry/types';
 import type { ControllerRegistration } from './types';
+/**
+ * One explicit controller route as the framework registered it — recorded by
+ * `build()` with the SAME composed path handed to Hono (global prefix +
+ * version segment + controller prefix + route path), so introspection tooling
+ * (`vela route list`) never re-derives composition. Contributed routes
+ * (`RouteContributor`, e.g. `@velajs/crud`) mount directly on the Hono app
+ * and are not described here — diff `app.getHonoApp().routes` for those.
+ */
+export interface RouteDescription {
+    /** As declared on the handler — `@Head()` reports HEAD (Hono serves it under GET). */
+    method: string;
+    /** Fully composed path exactly as registered. */
+    path: string;
+    controller: string;
+    handler: string;
+    version?: number;
+}
 export interface RouteManagerOptions {
     getClientIp?: (c: Context) => string | null;
     middleware?: MiddlewareHandler[];
@@ -27,6 +44,7 @@ export declare class RouteManager {
     private globalFilters;
     private globalPrefix;
     private consumerMiddlewareDefinitions;
+    private routeDescriptions;
     private readonly handlerExecutor;
     private readonly ambientContainer;
     constructor(container: Container, options?: RouteManagerOptions);
@@ -59,6 +77,10 @@ export declare class RouteManager {
     private wrapMiddlewareWithFilters;
     private mapMiddlewareError;
     registerController(controller: Type): this;
+    /** The explicit controller routes recorded by the last `build()`. */
+    getRouteDescriptions(): RouteDescription[];
+    /** The global prefix in effect (set at bootstrap; '' when none). */
+    getGlobalPrefix(): string;
     build(): Promise<Hono>;
     private registerRoute;
     private buildVersionedPaths;

package/dist/http/route.manager.js

@@ -92,6 +92,7 @@ export class RouteManager {
     globalFilters = [];
     globalPrefix = '';
     consumerMiddlewareDefinitions = [];
+    routeDescriptions = [];
     handlerExecutor;
     ambientContainer;
     constructor(container, options = {}){
@@ -273,8 +274,17 @@ export class RouteManager {
         });
         return this;
     }
+    /** The explicit controller routes recorded by the last `build()`. */ getRouteDescriptions() {
+        return [
+            ...this.routeDescriptions
+        ];
+    }
+    /** The global prefix in effect (set at bootstrap; '' when none). */ getGlobalPrefix() {
+        return this.globalPrefix;
+    }
     async build() {
         const app = new Hono();
+        this.routeDescriptions = [];
         // Outermost: dispose the per-request child container once the request is
         // fully done. Fast-paths out when the child has no request-scoped
         // disposables (the common case → zero overhead / no behavior change).
@@ -353,11 +363,18 @@ export class RouteManager {
                 for (const route of routes){
                     const effectiveVersion = route.version ?? metadata.version;
                     const versionedPaths = this.buildVersionedPaths(this.globalPrefix, metadata.prefix, route.path, effectiveVersion);
+                    // Parallel to versionedPaths: buildVersionedPaths maps versions to
+                    // paths 1:1 in order, so index i of both arrays belongs together.
+                    const versionsForPaths = effectiveVersion === undefined ? [
+                        undefined
+                    ] : Array.isArray(effectiveVersion) ? effectiveVersion : [
+                        effectiveVersion
+                    ];
                     // Scoped (controller/handler) middleware only — global middleware is
                     // applied once by this manager's own global pass, never re-read here.
                     const middlewareItems = ComponentManager.getScopedComponents('middleware', controller, route.handlerName);
                     const handler = this.handlerExecutor.create(route, controller, allParamMetadata);
-                    for (const fullPath of versionedPaths){
+                    for (const [pathIndex, fullPath] of versionedPaths.entries()){
                         for (const middlewareItem of middlewareItems){
                             app.use(fullPath, this.wrapMiddlewareWithFilters((c, next)=>{
                                 const requestContainer = this.getRequestContainer(c);
@@ -366,6 +383,13 @@ export class RouteManager {
                             }));
                         }
                         this.registerRoute(app, route.method, fullPath, handler);
+                        this.routeDescriptions.push({
+                            method: String(route.method),
+                            path: fullPath || '/',
+                            controller: controller.name,
+                            handler: String(route.handlerName),
+                            version: versionsForPaths[pathIndex]
+                        });
                     }
                 }
             }

package/dist/index.d.ts

@@ -6,8 +6,9 @@ export { bootstrap } from './factory/bootstrap';
 export type { BootstrapOptions, BootstrapResult } from './factory/bootstrap';
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema, } from './openapi/index';
 export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, } from './openapi/index';
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, } from './container/index';
-export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, describeToken, } from './container/index';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './container/index';
+export type { RouteDescription } from './http/route.manager';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, } from './http/index';
 export { REQUEST_CONTEXT } from './http/request-context';
@@ -46,8 +47,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

@@ -7,7 +7,7 @@ export { bootstrap } from "./factory/bootstrap.js";
 // OpenAPI
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema } from "./openapi/index.js";
 // DI Container
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin } from "./container/index.js";
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, describeToken } from "./container/index.js";
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
@@ -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.15.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"