@velajs/vela 1.19.0 → 1.19.1

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

@@ -1,36 +0,0 @@
-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

@@ -1,109 +0,0 @@
-import { buildEntrypointExecutionContext, PipelineRunner, resolveErrorReporter, 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) {
-            // Report BEFORE the filter loop and BEFORE any rethrow — every dispatch
-            // error reaches the exception handler, whether a scoped filter claims it
-            // or it rethrows to preserve platform retry semantics.
-            resolveErrorReporter(scope).report(error, {
-                edge: 'queue',
-                source: `${processorClass.name}.${String(handler.methodName)}`
-            });
-            for (const filter of filters){
-                if (shouldFilterCatch(filter, error)) {
-                    await filter.catch(error, context);
-                    return true;
-                }
-            }
-            throw error; // unclaimed → platform retry semantics stay intact
-        }
-    });
-}

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

@@ -1,32 +0,0 @@
-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

@@ -1,80 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

@@ -1,61 +0,0 @@
-/**
- * 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

@@ -1,4 +0,0 @@
-/**
- * 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/dist/registry/index.d.ts

@@ -1,2 +0,0 @@
-export { MetadataRegistry } from './metadata.registry';
-export type { Type, Constructor, ComponentType, ComponentTypeMap, ComponentInstance, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, RouteDefinition, ParameterMetadata, ModuleOptions, ProviderOptions, InjectionToken, } from './types';

package/dist/registry/index.js

@@ -1 +0,0 @@
-export { MetadataRegistry } from "./metadata.registry.js";

package/dist/registry/metadata.registry.d.ts

@@ -1,73 +0,0 @@
-import type { Scope } from '../constants';
-import type { InjectMetadata } from '../container/types';
-import type { ComponentType, ComponentTypeMap, Constructor, HttpHandlerMeta, ModuleOptions, ParameterMetadata, RouteDefinition, Type } from './types';
-export interface ControllerOptions {
-    version?: number | number[];
-}
-export declare class MetadataRegistry {
-    private static get routes();
-    private static get controllers();
-    private static get controllerOptions();
-    private static get modules();
-    private static get parameters();
-    private static get injectables();
-    private static get scopes();
-    private static get injectTokens();
-    private static get handlerHttpMeta();
-    private static get catchTypes();
-    private static get routeVersions();
-    private static get classMeta();
-    private static get handlerMeta();
-    private static get classMetaIndex();
-    private static get handlerMetaIndex();
-    private static get controllerComponents();
-    private static get handlerComponents();
-    static getRoutes(controller: Constructor): RouteDefinition[];
-    static addRoute(controller: Constructor, route: RouteDefinition): void;
-    static getControllerPath(controller: Constructor): string;
-    static setControllerPath(controller: Constructor, path: string): void;
-    static getControllerOptions(controller: Constructor): ControllerOptions;
-    static setControllerOptions(controller: Constructor, options: ControllerOptions): void;
-    static getModuleOptions(module: Constructor): ModuleOptions | undefined;
-    static setModuleOptions(module: Constructor, options: ModuleOptions): void;
-    static getParameters(controller: Constructor): Map<string | symbol, ParameterMetadata[]>;
-    static addParameter(controller: Constructor, methodName: string | symbol, param: ParameterMetadata): void;
-    static registerController<T extends ComponentType>(type: T, controller: Constructor, component: ComponentTypeMap[T]): void;
-    static getController<T extends ComponentType>(type: T, controller: Constructor): ComponentTypeMap[T][];
-    static registerHandler<T extends ComponentType>(type: T, controller: Constructor, methodName: string | symbol, component: ComponentTypeMap[T]): void;
-    static getHandler<T extends ComponentType>(type: T, controller: Constructor, methodName: string | symbol): ComponentTypeMap[T][];
-    static markInjectable(target: object): void;
-    static hasInjectable(target: object): boolean;
-    static setScope(target: object, scope: Scope): void;
-    static getScope(target: object): Scope | undefined;
-    static setInjectTokens(target: object, tokens: InjectMetadata[]): void;
-    static getInjectTokens(target: object): InjectMetadata[] | undefined;
-    static setHandlerHttpMeta(controller: Constructor, method: string | symbol, meta: HttpHandlerMeta): void;
-    static getHandlerHttpMeta(controller: Constructor, method: string | symbol): HttpHandlerMeta | undefined;
-    static setCatchTypes(filter: Constructor, types: Type<Error>[]): void;
-    static getCatchTypes(filter: Constructor): Type<Error>[] | undefined;
-    static hasCatchTypes(filter: Constructor): boolean;
-    static setRouteVersion(controller: Constructor, method: string | symbol, version: number | number[]): void;
-    static getRouteVersion(controller: Constructor, method: string | symbol): number | number[] | undefined;
-    static setCustomClassMeta(target: object, key: string, value: unknown): void;
-    static getCustomClassMeta(target: object, key: string): unknown;
-    static getCustomClassMetaAll(target: object): Map<string, unknown> | undefined;
-    static setCustomHandlerMeta(target: object, handler: string | symbol, key: string, value: unknown): void;
-    static getCustomHandlerMeta(target: object, handler: string | symbol, key: string): unknown;
-    static getCustomHandlerMetaAll(target: object, handler: string | symbol): Map<string, unknown> | undefined;
-    static appendCustomClassMeta<T>(target: object, key: string, item: T): void;
-    static appendCustomHandlerMeta<T>(target: object, handler: string | symbol, key: string, item: T): void;
-    static getClassesWithClassMeta(key: string): ReadonlySet<object>;
-    static getClassesWithHandlerMeta(key: string): ReadonlySet<object>;
-    /** Every (handler, value) pair on `target` carrying metadata under `key`. */
-    static getHandlersWithMeta(target: object, key: string): Array<{
-        handler: string | symbol;
-        value: unknown;
-    }>;
-    static setReflectMetadata(target: object, key: string, value: unknown, propertyKey?: string | symbol): void;
-    static getReflectMetadata<T = unknown>(target: object, key: string, propertyKey?: string | symbol): T | undefined;
-    static getParamTypes(target: object, propertyKey?: string | symbol): unknown[] | undefined;
-    static propagateControllerComponents(from: Constructor, to: Constructor): void;
-    static clear(): void;
-    static reset(): void;
-}