@velajs/vela 1.12.0 → 1.14.0

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/dist/registry/types.d.ts

@@ -81,6 +81,13 @@ export interface DynamicModule {
     controllers?: Type[];
     exports?: Array<Type | InjectionToken>;
     global?: boolean;
+    /**
+     * Defer this module instance's providers/controllers to first use: nothing
+     * constructs at bootstrap; the first resolution of any of its tokens
+     * materializes the whole group and replays its lifecycle hooks (memoized).
+     * See MODULE_AUTHORING.md "Lazy modules" for the contract.
+     */
+    lazy?: boolean;
 }
 export interface ModuleOptions {
     providers?: Array<Type | ProviderOptions>;
@@ -88,6 +95,8 @@ export interface ModuleOptions {
     imports?: ModuleImport[];
     exports?: Array<Type | InjectionToken>;
     isGlobal?: boolean;
+    /** Defer to first use (see {@link DynamicModule.lazy}). */
+    lazy?: boolean;
 }
 export interface ModuleMetadata {
     providers: Array<Type | ProviderOptions>;
@@ -95,4 +104,5 @@ export interface ModuleMetadata {
     imports: ModuleImport[];
     exports: Array<Type | InjectionToken>;
     isGlobal: boolean;
+    lazy: boolean;
 }

package/dist/schedule/schedule.module.js

@@ -15,6 +15,9 @@ export class ScheduleModule {
 }
 ScheduleModule = _ts_decorate([
     Module({
+        // Lazy: the @Cron/@Interval discovery pass runs when ScheduleRegistry is
+        // first resolved (executor bootstrap, introspection, first dispatch).
+        lazy: true,
         providers: [
             ScheduleRegistry
         ],

package/dist/seeder/seeder.module.js

@@ -28,6 +28,9 @@ export class SeederModule extends ConfigurableModuleClass {
 }
 SeederModule = _ts_decorate([
     Module({
+        // Lazy: the @Seeder metadata scan runs when SeederRegistry is first
+        // resolved (runSeeders) — hook replay repopulates it correctly.
+        lazy: true,
         providers: [
             SeederRegistry
         ],

package/package.json

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