@velajs/vela 1.10.0 → 1.13.0

package/dist/module/decorators.js

@@ -16,7 +16,8 @@ export function Module(options = {}) {
             providers: options.providers,
             controllers: options.controllers,
             exports: options.exports,
-            isGlobal: options.isGlobal
+            isGlobal: options.isGlobal,
+            lazy: options.lazy
         });
     };
 }
@@ -40,6 +41,7 @@ export function getModuleMetadata(target) {
         controllers: options.controllers ?? [],
         imports: options.imports ?? [],
         exports: options.exports ?? [],
-        isGlobal: options.isGlobal === true
+        isGlobal: options.isGlobal === true,
+        lazy: options.lazy === true
     };
 }

package/dist/module/define-module.d.ts

@@ -0,0 +1,112 @@
+import { InjectionToken, type ProviderOptions, type Token, type Type } from '../container/types';
+import type { ComponentInstance, ModuleImport } from '../registry/types';
+import type { ConfigurableModuleAsyncOptions, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost } from './configurable-module.types';
+/** The `global:` slot's component groups, lowered to `APP_*` registrations. */
+export interface GlobalComponentSlot {
+    guards?: Array<Type | ComponentInstance>;
+    pipes?: Array<Type | ComponentInstance>;
+    interceptors?: Array<Type | ComponentInstance>;
+    filters?: Array<Type | ComponentInstance>;
+    middleware?: Array<Type | ComponentInstance>;
+}
+/** What a module instance contributes, computed from its call-time options. */
+export interface ModuleContributions {
+    providers?: Array<Type | ProviderOptions>;
+    controllers?: Type[];
+    imports?: ModuleImport[];
+    exports?: Array<Type | InjectionToken>;
+    /**
+     * Standardized global-component registration — the one idiom replacing both
+     * the `@Module({ providers: [{ provide: APP_GUARD, useExisting: X }] })`
+     * pattern and the conditional-push-into-forRoot pattern. Class entries are
+     * registered as providers and wired via `useExisting`; instances via `useValue`.
+     */
+    global?: GlobalComponentSlot;
+}
+export interface ModuleSetupContext<Opts> {
+    /** The options token — derived providers do `inject: [OPTIONS]`. */
+    readonly OPTIONS: InjectionToken<Opts>;
+    /**
+     * Structural options known at call time. For `forRoot` this is the full
+     * bag; for `forRootAsync` it is only the structural fields passed alongside
+     * the factory (the DI-resolved options exist only at resolution time —
+     * read them through `OPTIONS`, never here).
+     */
+    readonly options: Partial<Opts>;
+    /** The instance key in effect (for deriving per-instance token names). */
+    readonly key: string;
+}
+export interface DefineModuleSpec<Opts, Extras extends ConfigurableModuleExtras = {
+    isGlobal?: boolean;
+}, MethodKey extends string = 'forRoot', FactoryMethodKey extends string = 'create'> {
+    /** Names the generated base class, the minted options token, and diagnostics. */
+    name: string;
+    /**
+     * Reuse an existing options token instead of minting one — critical for
+     * migrations so the module's public token keeps its identity.
+     */
+    optionsToken?: InjectionToken<Opts>;
+    /**
+     * Structural contributions as a function of the call-time options. Runs at
+     * `forRoot`/`forRootAsync` call time, once per module instance.
+     */
+    setup?: (ctx: ModuleSetupContext<Opts>) => ModuleContributions;
+    /**
+     * Dedup key from the structural options. Defaults to `stableHash(options)`.
+     * Modules whose options carry stateful instances (drivers, registries)
+     * should derive from the stable identifying subset — or document that
+     * callers pass an explicit `key` for multi-instance setups.
+     */
+    key?: (options: Partial<Opts>) => string;
+    /** Call-site extras defaults (default `{ isGlobal: false }`). */
+    extras?: Extras;
+    /** Reshape the definition from resolved extras (default: `isGlobal` → `global: true`). */
+    transform?: ConfigurableModuleExtrasTransform<Extras>;
+    /** Rename the sync static (default `forRoot`); the async static becomes `<name>Async`. */
+    methodName?: MethodKey;
+    /** Method a `useClass`/`useExisting` options factory must implement (default `create`). */
+    factoryMethodName?: FactoryMethodKey;
+    /**
+     * Default every generated module instance to deferred (first-use)
+     * materialization. Call sites can also opt in per instance by passing
+     * `lazy: true` alongside the options (recognized like `isGlobal`).
+     * See MODULE_AUTHORING.md "Lazy modules".
+     */
+    lazy?: boolean;
+}
+/**
+ * The one blessed module-authoring engine. Generates `forRoot` AND
+ * `forRootAsync` statics with: `stableHash` key derivation (multi-instance
+ * dedup that survives HMR), typed `inject` tuple inference on the async
+ * factory, an `isGlobal` extra, and — the piece `ConfigurableModuleBuilder`
+ * could not express — providers/controllers/imports/exports/global components
+ * computed **as functions of the options**.
+ *
+ * ```ts
+ * const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = defineModule<CorsOptions>({
+ *   name: 'Cors',
+ *   setup: ({ OPTIONS }) => ({
+ *     providers: [{
+ *       provide: APP_MIDDLEWARE,
+ *       useFactory: (o: CorsOptions) => buildCorsMiddleware(o),
+ *       inject: [OPTIONS],
+ *     }],
+ *     exports: [OPTIONS],
+ *   }),
+ * });
+ * export class CorsModule extends ConfigurableModuleClass {}
+ * ```
+ *
+ * `ConfigurableModuleBuilder` remains supported (NestJS parity) and is a thin
+ * adapter over this engine.
+ */
+export declare function defineModule<Opts, Extras extends ConfigurableModuleExtras = {
+    isGlobal?: boolean;
+}, MethodKey extends string = 'forRoot', FactoryMethodKey extends string = 'create'>(spec: DefineModuleSpec<Opts, Extras, MethodKey, FactoryMethodKey>): ConfigurableModuleHost<Opts, MethodKey, FactoryMethodKey, Extras>;
+/**
+ * Lower `useFactory`/`useClass`/`useExisting` async options into provider
+ * registrations. Structural fields from the call site merge UNDER the resolved
+ * options (`{ ...structural, ...resolved }`) so sync-declared fields act as
+ * defaults and the factory stays authoritative.
+ */
+export declare function buildAsyncOptionsProviders<Opts>(optionsToken: Token, factoryMethodName: string, async: Pick<ConfigurableModuleAsyncOptions<Opts>, 'inject' | 'useFactory' | 'useClass' | 'useExisting'>, structural?: Record<string, unknown>): Array<ProviderOptions>;

package/dist/module/define-module.js

@@ -0,0 +1,232 @@
+import { InjectionToken } from "../container/types.js";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
+import { stableHash } from "./stable-hash.js";
+const DEFAULT_EXTRAS = {
+    isGlobal: false
+};
+const DEFAULT_TRANSFORM = (def, extras)=>extras.isGlobal ? {
+        ...def,
+        global: true
+    } : def;
+const GLOBAL_SLOT_TOKENS = {
+    guards: APP_GUARD,
+    pipes: APP_PIPE,
+    interceptors: APP_INTERCEPTOR,
+    filters: APP_FILTER,
+    middleware: APP_MIDDLEWARE
+};
+/** Lower a `global:` slot to `APP_*` provider registrations. */ function lowerGlobalSlot(slot) {
+    const out = [];
+    for (const kind of Object.keys(GLOBAL_SLOT_TOKENS)){
+        for (const component of slot[kind] ?? []){
+            const token = GLOBAL_SLOT_TOKENS[kind];
+            if (typeof component === 'function') {
+                out.push(component, {
+                    provide: token,
+                    useExisting: component
+                });
+            } else {
+                out.push({
+                    provide: token,
+                    useValue: component
+                });
+            }
+        }
+    }
+    return out;
+}
+const ASYNC_OPTION_KEYS = new Set([
+    'key',
+    'imports',
+    'inject',
+    'useFactory',
+    'useClass',
+    'useExisting'
+]);
+/**
+ * The one blessed module-authoring engine. Generates `forRoot` AND
+ * `forRootAsync` statics with: `stableHash` key derivation (multi-instance
+ * dedup that survives HMR), typed `inject` tuple inference on the async
+ * factory, an `isGlobal` extra, and — the piece `ConfigurableModuleBuilder`
+ * could not express — providers/controllers/imports/exports/global components
+ * computed **as functions of the options**.
+ *
+ * ```ts
+ * const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = defineModule<CorsOptions>({
+ *   name: 'Cors',
+ *   setup: ({ OPTIONS }) => ({
+ *     providers: [{
+ *       provide: APP_MIDDLEWARE,
+ *       useFactory: (o: CorsOptions) => buildCorsMiddleware(o),
+ *       inject: [OPTIONS],
+ *     }],
+ *     exports: [OPTIONS],
+ *   }),
+ * });
+ * export class CorsModule extends ConfigurableModuleClass {}
+ * ```
+ *
+ * `ConfigurableModuleBuilder` remains supported (NestJS parity) and is a thin
+ * adapter over this engine.
+ */ export function defineModule(spec) {
+    const optionsToken = spec.optionsToken ?? new InjectionToken(`${spec.name}_MODULE_OPTIONS`);
+    const syncName = spec.methodName ?? 'forRoot';
+    const asyncName = `${syncName}Async`;
+    const factoryMethodName = spec.factoryMethodName ?? 'create';
+    const extrasDefaults = spec.extras ?? DEFAULT_EXTRAS;
+    const transform = spec.transform ?? DEFAULT_TRANSFORM;
+    const deriveKey = (explicit, structural)=>explicit ?? spec.key?.(structural) ?? stableHash(structural);
+    // Laziness is OR-composed: the spec defaults it, a call site can add it.
+    const applyLazy = (definition, callSiteLazy)=>spec.lazy === true || callSiteLazy === true ? {
+            ...definition,
+            lazy: true
+        } : definition;
+    const applyContributions = (definition, structural, key)=>{
+        if (!spec.setup) return definition;
+        const contributions = spec.setup({
+            OPTIONS: optionsToken,
+            options: structural,
+            key
+        });
+        const providers = [
+            ...definition.providers ?? [],
+            ...contributions.providers ?? [],
+            ...contributions.global ? lowerGlobalSlot(contributions.global) : []
+        ];
+        return {
+            ...definition,
+            providers,
+            controllers: [
+                ...definition.controllers ?? [],
+                ...contributions.controllers ?? []
+            ],
+            imports: [
+                ...definition.imports ?? [],
+                ...contributions.imports ?? []
+            ],
+            exports: [
+                ...definition.exports ?? [],
+                ...contributions.exports ?? []
+            ]
+        };
+    };
+    let GeneratedModuleClass = class GeneratedModuleClass {
+    };
+    Object.defineProperty(GeneratedModuleClass, 'name', {
+        value: `${spec.name}ModuleHost`
+    });
+    Object.defineProperty(GeneratedModuleClass, syncName, {
+        configurable: true,
+        writable: true,
+        enumerable: false,
+        value (options = {}) {
+            const { key: explicitKey, ...rest } = options;
+            const key = deriveKey(explicitKey, rest);
+            const definition = {
+                module: this,
+                key,
+                providers: [
+                    {
+                        provide: optionsToken,
+                        useValue: rest
+                    }
+                ]
+            };
+            return applyLazy(transform(applyContributions(definition, rest, key), {
+                ...extrasDefaults,
+                ...rest
+            }), rest.lazy);
+        }
+    });
+    Object.defineProperty(GeneratedModuleClass, asyncName, {
+        configurable: true,
+        writable: true,
+        enumerable: false,
+        value (options = {}) {
+            const bag = options;
+            const structural = {};
+            for (const [k, v] of Object.entries(bag)){
+                if (!ASYNC_OPTION_KEYS.has(k)) structural[k] = v;
+            }
+            const key = deriveKey(bag.key, // Async factories aren't structurally hashable in a useful way, so the
+            // default key hashes the async wiring + structural fields — same
+            // instance-identity semantics ConfigurableModuleBuilder always had.
+            spec.key ? structural : {
+                inject: bag.inject,
+                useFactory: bag.useFactory,
+                useClass: bag.useClass,
+                useExisting: bag.useExisting,
+                ...structural
+            });
+            const definition = {
+                module: this,
+                key,
+                imports: bag.imports ?? [],
+                providers: buildAsyncOptionsProviders(optionsToken, factoryMethodName, bag, structural)
+            };
+            return applyLazy(transform(applyContributions(definition, structural, key), {
+                ...extrasDefaults,
+                ...structural
+            }), structural.lazy);
+        }
+    });
+    return {
+        ConfigurableModuleClass: GeneratedModuleClass,
+        MODULE_OPTIONS_TOKEN: optionsToken,
+        // Type-only sentinels — never read at runtime.
+        OPTIONS_TYPE: undefined,
+        ASYNC_OPTIONS_TYPE: undefined
+    };
+}
+/**
+ * Lower `useFactory`/`useClass`/`useExisting` async options into provider
+ * registrations. Structural fields from the call site merge UNDER the resolved
+ * options (`{ ...structural, ...resolved }`) so sync-declared fields act as
+ * defaults and the factory stays authoritative.
+ */ export function buildAsyncOptionsProviders(optionsToken, factoryMethodName, async, structural = {}) {
+    const hasStructural = Object.keys(structural).length > 0;
+    const merge = (resolved)=>resolved instanceof Promise ? resolved.then((o)=>({
+                ...structural,
+                ...o
+            })) : {
+            ...structural,
+            ...resolved
+        };
+    if (async.useFactory) {
+        const factory = async.useFactory;
+        return [
+            {
+                provide: optionsToken,
+                // No structural fields → pass the caller's factory through untouched
+                // (function identity preserved; nothing to merge).
+                useFactory: hasStructural ? (...deps)=>merge(factory(...deps)) : factory,
+                inject: async.inject ?? []
+            }
+        ];
+    }
+    if (async.useClass) {
+        const factoryClass = async.useClass;
+        return [
+            factoryClass,
+            {
+                provide: optionsToken,
+                useFactory: (instance)=>merge(instance[factoryMethodName]()),
+                inject: [
+                    factoryClass
+                ]
+            }
+        ];
+    }
+    if (async.useExisting) {
+        return [
+            {
+                provide: optionsToken,
+                useFactory: (instance)=>merge(instance[factoryMethodName]()),
+                inject: [
+                    async.useExisting
+                ]
+            }
+        ];
+    }
+    throw new Error('Async module options require one of `useFactory`, `useClass`, or `useExisting`.');
+}

package/dist/module/index.d.ts

@@ -1,6 +1,8 @@
 export { Global, Module, isModule, getModuleMetadata, defineDynamicModule, } from './decorators';
 export { stableHash } from './stable-hash';
-export { ConfigurableModuleBuilder, defineConfigurableModule, } from './configurable-module.builder';
+export { ConfigurableModuleBuilder, defineConfigurableModule, moduleKey, } from './configurable-module.builder';
+export { defineModule, buildAsyncOptionsProviders, type DefineModuleSpec, type GlobalComponentSlot, type ModuleContributions, type ModuleSetupContext, } from './define-module';
+export { lazyProvider, moduleToken, provideGlobal, sideEffectModule, type LazyProviderSpec, } from './lazy-provider';
 export type { ConfigurableModuleAsyncOptions, ConfigurableModuleBuilderOptions, ConfigurableModuleClassType, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, ConfigurableModuleOptionsFactory, DefineConfigurableModuleSpec, } from './configurable-module.types';
 export { ModuleLoader } from './module-loader';
 export { MiddlewareBuilder } from './middleware';

package/dist/module/index.js

@@ -1,5 +1,7 @@
 export { Global, Module, isModule, getModuleMetadata, defineDynamicModule } from "./decorators.js";
 export { stableHash } from "./stable-hash.js";
-export { ConfigurableModuleBuilder, defineConfigurableModule } from "./configurable-module.builder.js";
+export { ConfigurableModuleBuilder, defineConfigurableModule, moduleKey } from "./configurable-module.builder.js";
+export { defineModule, buildAsyncOptionsProviders } from "./define-module.js";
+export { lazyProvider, moduleToken, provideGlobal, sideEffectModule } from "./lazy-provider.js";
 export { ModuleLoader } from "./module-loader.js";
 export { MiddlewareBuilder } from "./middleware.js";

package/dist/module/lazy-modules.d.ts

@@ -0,0 +1,82 @@
+import type { Container } from '../container/container';
+import type { LazyResolutionHook, Token } from '../container/types';
+/** One lazy module instance's deferral unit: its own tokens, in registration order. */
+export interface LazyModuleGroup {
+    moduleId: string;
+    tokens: Token[];
+    /**
+     * A class provider's prototype declares `collectEntrypoints` — the module
+     * must be materialized before the entrypoint registry snapshot or its
+     * computed contributions would be silently absent.
+     */
+    hasEntrypointContributor: boolean;
+}
+/**
+ * Owns deferred-module state for one application: which module instances are
+ * still pending, which have been claimed by a container trigger, and how
+ * claimed groups get completed (construction + lifecycle-hook replay).
+ *
+ * Phases:
+ * - `'bootstrap'` (until the end of `callOnApplicationBootstrap`): completed
+ *   groups are *absorbed* — their instances queue up for the application's
+ *   normal hook phases, so a lazy module dragged in by an eager consumer gets
+ *   today-identical semantics.
+ * - `'live'`: hooks replay at drain time (memoized, exactly once), then the
+ *   instances are handed to the application for shutdown-hook symmetry.
+ *
+ * Sync/async duality: sync drains throw a descriptive error when a member
+ * factory or hook yields a thenable — lazy modules with async providers or
+ * hooks must be reached through an async seam (`materializeLazyModules()`,
+ * `resolveAsync`) or stay eager.
+ */
+export declare class LazyModuleManager implements LazyResolutionHook {
+    private readonly container;
+    private readonly pending;
+    private readonly claimed;
+    private readonly absorbed;
+    private phase;
+    private draining;
+    private drainPromise?;
+    private onMaterialized?;
+    constructor(container: Container);
+    registerGroup(group: LazyModuleGroup): void;
+    /** Application sink for live-phase materializations (shutdown symmetry). */
+    setOnMaterialized(sink: (instances: unknown[]) => void): void;
+    setPhaseLive(): void;
+    isPending(moduleId: string): boolean;
+    /** Tokens whose owning modules are ALL still pending are deferred. */
+    hasPendingModules(): boolean;
+    claim(moduleId: string): void;
+    hasClaimed(): boolean;
+    /**
+     * A drain loop is running. The container consults this before its
+     * post-resolution drain: `constructGroupAsync` resolves members through
+     * `resolveAsync`, whose end-of-cascade check would otherwise re-enter and
+     * AWAIT the very drain promise it is executing inside — a self-referential
+     * await that never settles (with ≥2 claimed groups). Claims made while
+     * draining are picked up by the running loop instead.
+     */
+    isDraining(): boolean;
+    /** Instances constructed during the bootstrap phase, owed their hooks. */
+    takeAbsorbed(): unknown[];
+    drainSync(): void;
+    drainAsync(): Promise<void>;
+    /**
+     * Materialize every still-pending group whose providers compute entrypoints
+     * (`collectEntrypoints` on a class prototype). Called by the application
+     * right before the entrypoint-registry snapshot so computed contributions
+     * are never silently absent. The cost — those modules are effectively
+     * eager — is the documented price of contributing computed entrypoints.
+     */
+    materializeContributors(): Promise<void>;
+    /** Materialize everything still pending (warmup / tests / node runtimes). */
+    materializeAll(): Promise<void>;
+    private groupTokensToConstruct;
+    private constructGroupSync;
+    private constructGroupAsync;
+    /** Reversed batch = dependency-before-consumer (see drainSync comment). */
+    private orderBatch;
+    private finishBatchSync;
+    private finishBatchAsync;
+    private describeSyncFailure;
+}