@velajs/vela 1.18.0 → 1.19.1

package/dist/module/lazy-modules.js

@@ -1,231 +0,0 @@
-import { Scope } from "../constants.js";
-import { hasOnApplicationBootstrap, hasOnModuleInit } from "../lifecycle/index.js";
-function isThenable(x) {
-    return x !== null && (typeof x === 'object' || typeof x === 'function') && typeof x.then === 'function';
-}
-/**
- * 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 class LazyModuleManager {
-    container;
-    pending = new Map();
-    claimed = [];
-    absorbed = [];
-    phase = 'bootstrap';
-    draining = false;
-    // In-flight async drain: concurrent drainAsync callers must await the SAME
-    // completion (the running loop picks their claims up), never resolve early
-    // with a group's hooks still pending.
-    drainPromise;
-    onMaterialized;
-    constructor(container){
-        this.container = container;
-    }
-    registerGroup(group) {
-        this.pending.set(group.moduleId, group);
-    }
-    /** Application sink for live-phase materializations (shutdown symmetry). */ setOnMaterialized(sink) {
-        this.onMaterialized = sink;
-    }
-    setPhaseLive() {
-        this.phase = 'live';
-    }
-    isPending(moduleId) {
-        return this.pending.has(moduleId);
-    }
-    /** Tokens whose owning modules are ALL still pending are deferred. */ hasPendingModules() {
-        return this.pending.size > 0;
-    }
-    claim(moduleId) {
-        const group = this.pending.get(moduleId);
-        if (!group) return;
-        this.pending.delete(moduleId);
-        this.claimed.push(group);
-    }
-    hasClaimed() {
-        return this.claimed.length > 0;
-    }
-    /**
-   * 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() {
-        return this.draining;
-    }
-    /** Instances constructed during the bootstrap phase, owed their hooks. */ takeAbsorbed() {
-        if (this.absorbed.length === 0) return [];
-        return this.absorbed.splice(0, this.absorbed.length);
-    }
-    drainSync() {
-        if (this.draining) return;
-        this.draining = true;
-        try {
-            // Construct-all-then-hook, batch by batch: a cascade's groups arrive in
-            // consumer-before-dependency claim order (the consumer's token resolves
-            // first; constructing it claims its deps), so hook phases run over the
-            // REVERSED batch — dependency-before-consumer, matching what the eager
-            // bootstrap would have produced. Hooks can claim further groups
-            // (discovery cascades) → outer loop.
-            while(this.claimed.length > 0){
-                const batch = [];
-                while(this.claimed.length > 0){
-                    const group = this.claimed.shift();
-                    batch.push({
-                        group,
-                        instances: this.constructGroupSync(group)
-                    });
-                }
-                this.finishBatchSync(batch);
-            }
-        } finally{
-            this.draining = false;
-        }
-    }
-    drainAsync() {
-        if (this.draining) {
-            // External concurrent callers await the in-flight completion (its loop
-            // picks their claims up). Callers INSIDE the drain's own await chain
-            // never reach here — the container skips its post-resolution drain
-            // while isDraining() (self-await would deadlock).
-            return this.drainPromise ?? Promise.resolve();
-        }
-        this.draining = true;
-        const run = (async ()=>{
-            try {
-                while(this.claimed.length > 0){
-                    const batch = [];
-                    while(this.claimed.length > 0){
-                        const group = this.claimed.shift();
-                        batch.push({
-                            group,
-                            instances: await this.constructGroupAsync(group)
-                        });
-                    }
-                    await this.finishBatchAsync(batch);
-                }
-            } finally{
-                this.draining = false;
-                this.drainPromise = undefined;
-            }
-        })();
-        this.drainPromise = run;
-        return run;
-    }
-    /**
-   * 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.
-   */ async materializeContributors() {
-        for (const group of [
-            ...this.pending.values()
-        ]){
-            if (group.hasEntrypointContributor) this.claim(group.moduleId);
-        }
-        await this.drainAsync();
-    }
-    /** Materialize everything still pending (warmup / tests / node runtimes). */ async materializeAll() {
-        for (const moduleId of [
-            ...this.pending.keys()
-        ])this.claim(moduleId);
-        await this.drainAsync();
-    }
-    groupTokensToConstruct(group) {
-        return group.tokens.filter((token)=>this.container.getProviderScope(token) !== Scope.REQUEST);
-    }
-    constructGroupSync(group) {
-        const out = new Set();
-        for (const token of this.groupTokensToConstruct(group)){
-            try {
-                out.add(this.container.resolve(token, group.moduleId));
-            } catch (error) {
-                // Only the sync-resolution-of-async-factory error is a seam problem;
-                // genuine provider failures must surface untouched.
-                if (error instanceof Error && error.message.includes('returned a Promise')) {
-                    throw this.describeSyncFailure(group.moduleId, error);
-                }
-                throw error;
-            }
-        }
-        return [
-            ...out
-        ];
-    }
-    async constructGroupAsync(group) {
-        const out = new Set();
-        for (const token of this.groupTokensToConstruct(group)){
-            out.add(await this.container.resolveAsync(token, group.moduleId));
-        }
-        return [
-            ...out
-        ];
-    }
-    /** Reversed batch = dependency-before-consumer (see drainSync comment). */ orderBatch(batch) {
-        return [
-            ...batch
-        ].reverse();
-    }
-    finishBatchSync(batch) {
-        const ordered = this.orderBatch(batch);
-        if (this.phase === 'bootstrap') {
-            for (const { instances } of ordered)this.absorbed.push(...instances);
-            return;
-        }
-        for (const { group, instances } of ordered){
-            for (const instance of instances){
-                if (hasOnModuleInit(instance) && isThenable(instance.onModuleInit())) {
-                    throw this.describeSyncFailure(group.moduleId);
-                }
-            }
-        }
-        for (const { group, instances } of ordered){
-            for (const instance of instances){
-                if (hasOnApplicationBootstrap(instance) && isThenable(instance.onApplicationBootstrap())) {
-                    throw this.describeSyncFailure(group.moduleId);
-                }
-            }
-        }
-        this.onMaterialized?.(ordered.flatMap((b)=>b.instances));
-    }
-    async finishBatchAsync(batch) {
-        const ordered = this.orderBatch(batch);
-        if (this.phase === 'bootstrap') {
-            for (const { instances } of ordered)this.absorbed.push(...instances);
-            return;
-        }
-        for (const { instances } of ordered){
-            for (const instance of instances){
-                if (hasOnModuleInit(instance)) await instance.onModuleInit();
-            }
-        }
-        for (const { instances } of ordered){
-            for (const instance of instances){
-                if (hasOnApplicationBootstrap(instance)) await instance.onApplicationBootstrap();
-            }
-        }
-        this.onMaterialized?.(ordered.flatMap((b)=>b.instances));
-    }
-    describeSyncFailure(moduleId, cause) {
-        return new Error(`[vela] lazy module '${moduleId}' has async providers or lifecycle hooks and was ` + `triggered through a synchronous resolution path. Reach it through an async seam ` + `first (app.materializeLazyModules(), an async provider) or remove lazy: true.`, cause !== undefined ? {
-            cause
-        } : undefined);
-    }
-}

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

@@ -1,65 +0,0 @@
-import { InjectionToken, type InferTokens, type ProviderOptions, type Token, type Type } from '../container/types';
-import type { ComponentType, DynamicModule } from '../registry/types';
-import type { ModuleContributions } from './define-module';
-export interface LazyProviderSpec<T, Inject extends readonly Token<unknown>[]> {
-    /** Token under which the memoized thunk `() => T` is provided. */
-    provide: Token<() => T>;
-    inject?: Inject;
-    useFactory: (...deps: InferTokens<Inject>) => T;
-    /** Memoize the first call's result (default true). */
-    memoize?: boolean;
-}
-/**
- * Provide a zero-arg thunk `() => T` whose factory runs on FIRST CALL, not at
- * provider construction — for values that don't exist yet when the module
- * graph is built (Cloudflare bindings are only live at request time).
- *
- * The shared primitive replacing the hand-rolled
- * `useFactory: (...deps) => () => build(...deps)` closure that auth and
- * storage each copy-pasted.
- *
- * ```ts
- * lazyProvider({
- *   provide: STORAGE_DRIVER_BUILDER,
- *   inject: [MODULE_OPTIONS_TOKEN],
- *   useFactory: (options) => options.driver(),
- * })
- * ```
- */
-export declare function lazyProvider<T, const Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]>(spec: LazyProviderSpec<T, Inject>): ProviderOptions;
-/**
- * The one idiom for registering an app-wide component from a module's
- * providers. Returns registrations to spread:
- *
- * ```ts
- * providers: [MyService, ...provideGlobal('guard', AuthGuard)]
- * ```
- *
- * Class components are registered as providers and wired via `useExisting`
- * (so DI constructs them with their dependencies); instances via `useValue`.
- * Inside `defineModule`, prefer the equivalent `global:` contribution slot.
- */
-export declare function provideGlobal(kind: ComponentType, component: Type | object): Array<Type | ProviderOptions>;
-/**
- * A first-class side-effect-only module: contributes providers/exports without
- * being a configurable module — the supported form of the "empty marker
- * module" trick (i18n's `registerMessages`). Content-derived `key` makes
- * identical contributions dedup (HMR-idempotent) while distinct ones coexist.
- *
- * ```ts
- * export function registerMessages(messages: Messages): DynamicModule {
- *   return sideEffectModule('I18nMessages', {
- *     providers: [{ provide: I18N_MESSAGES, useValue: messages }],
- *     exports: [I18N_MESSAGES],
- *   });
- * }
- * ```
- */
-export declare function sideEffectModule(name: string, contributions?: Omit<ModuleContributions, 'global'> & {
-    key?: string;
-}): DynamicModule;
-/**
- * Blessed token-minting convention: always an `InjectionToken` (never a raw
- * string), named for diagnostics. Namespace it `'<pkg>:<area>:<thing>'`.
- */
-export declare function moduleToken<T>(name: string): InjectionToken<T>;

package/dist/module/lazy-provider.js

@@ -1,111 +0,0 @@
-import { InjectionToken } from "../container/types.js";
-import { Module } from "./decorators.js";
-import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
-import { stableHash } from "./stable-hash.js";
-/**
- * Provide a zero-arg thunk `() => T` whose factory runs on FIRST CALL, not at
- * provider construction — for values that don't exist yet when the module
- * graph is built (Cloudflare bindings are only live at request time).
- *
- * The shared primitive replacing the hand-rolled
- * `useFactory: (...deps) => () => build(...deps)` closure that auth and
- * storage each copy-pasted.
- *
- * ```ts
- * lazyProvider({
- *   provide: STORAGE_DRIVER_BUILDER,
- *   inject: [MODULE_OPTIONS_TOKEN],
- *   useFactory: (options) => options.driver(),
- * })
- * ```
- */ export function lazyProvider(spec) {
-    const memoize = spec.memoize ?? true;
-    return {
-        provide: spec.provide,
-        inject: [
-            ...spec.inject ?? []
-        ],
-        useFactory: (...deps)=>{
-            const build = ()=>spec.useFactory(...deps);
-            if (!memoize) return build;
-            let cached;
-            return ()=>(cached ??= {
-                    value: build()
-                }).value;
-        }
-    };
-}
-const GLOBAL_COMPONENT_TOKENS = {
-    guard: APP_GUARD,
-    pipe: APP_PIPE,
-    interceptor: APP_INTERCEPTOR,
-    filter: APP_FILTER,
-    middleware: APP_MIDDLEWARE
-};
-/**
- * The one idiom for registering an app-wide component from a module's
- * providers. Returns registrations to spread:
- *
- * ```ts
- * providers: [MyService, ...provideGlobal('guard', AuthGuard)]
- * ```
- *
- * Class components are registered as providers and wired via `useExisting`
- * (so DI constructs them with their dependencies); instances via `useValue`.
- * Inside `defineModule`, prefer the equivalent `global:` contribution slot.
- */ export function provideGlobal(kind, component) {
-    const token = GLOBAL_COMPONENT_TOKENS[kind];
-    if (typeof component === 'function') {
-        return [
-            component,
-            {
-                provide: token,
-                useExisting: component
-            }
-        ];
-    }
-    return [
-        {
-            provide: token,
-            useValue: component
-        }
-    ];
-}
-/**
- * A first-class side-effect-only module: contributes providers/exports without
- * being a configurable module — the supported form of the "empty marker
- * module" trick (i18n's `registerMessages`). Content-derived `key` makes
- * identical contributions dedup (HMR-idempotent) while distinct ones coexist.
- *
- * ```ts
- * export function registerMessages(messages: Messages): DynamicModule {
- *   return sideEffectModule('I18nMessages', {
- *     providers: [{ provide: I18N_MESSAGES, useValue: messages }],
- *     exports: [I18N_MESSAGES],
- *   });
- * }
- * ```
- */ export function sideEffectModule(name, contributions = {}) {
-    const { key, ...rest } = contributions;
-    // Computed-property-name idiom: mints a class whose .name is `name` without
-    // dynamic code evaluation (edge-safe; no `new Function`).
-    const moduleClass = {
-        [name]: class {
-        }
-    }[name];
-    Module({})(moduleClass);
-    return {
-        module: moduleClass,
-        key: key ?? stableHash(rest),
-        providers: rest.providers ?? [],
-        controllers: rest.controllers ?? [],
-        imports: rest.imports ?? [],
-        exports: rest.exports ?? []
-    };
-}
-/**
- * Blessed token-minting convention: always an `InjectionToken` (never a raw
- * string), named for diagnostics. Namespace it `'<pkg>:<area>:<thing>'`.
- */ export function moduleToken(name) {
-    return new InjectionToken(name);
-}

package/dist/module/middleware.d.ts

@@ -1,30 +0,0 @@
-import { HttpMethod } from '../constants';
-import type { NestMiddleware } from '../pipeline/types';
-import type { Constructor, Type } from '../registry/types';
-export interface RouteInfo {
-    path: string;
-    method?: HttpMethod;
-}
-export interface MiddlewareRouteDefinition {
-    middleware: Array<Type<NestMiddleware> | NestMiddleware>;
-    routes: RouteInfo[];
-    excludes: RouteInfo[];
-    /** Stable-sort key; lower runs first. Default 0. */
-    priority?: number;
-}
-export interface MiddlewareConfigProxy {
-    exclude(...routes: Array<string | RouteInfo>): MiddlewareConfigProxy;
-    withPriority(priority: number): MiddlewareConfigProxy;
-    forRoutes(...routes: Array<string | Constructor | RouteInfo>): MiddlewareConsumer;
-}
-export interface MiddlewareConsumer {
-    apply(...middleware: Array<Type<NestMiddleware> | NestMiddleware>): MiddlewareConfigProxy;
-}
-export interface NestModule {
-    configure(consumer: MiddlewareConsumer): void;
-}
-export declare class MiddlewareBuilder implements MiddlewareConsumer {
-    private definitions;
-    apply(...middleware: Array<Type<NestMiddleware> | NestMiddleware>): MiddlewareConfigProxy;
-    getDefinitions(): MiddlewareRouteDefinition[];
-}

package/dist/module/middleware.js

@@ -1,67 +0,0 @@
-import { MetadataRegistry } from "../registry/metadata.registry.js";
-export class MiddlewareBuilder {
-    definitions = [];
-    apply(...middleware) {
-        const currentMiddleware = [
-            ...middleware
-        ];
-        let currentExcludes = [];
-        let currentPriority;
-        const proxy = {
-            exclude: (...routes)=>{
-                currentExcludes = routes.map(normalizeRouteArg);
-                return proxy;
-            },
-            withPriority: (priority)=>{
-                currentPriority = priority;
-                return proxy;
-            },
-            forRoutes: (...routes)=>{
-                this.definitions.push({
-                    middleware: currentMiddleware,
-                    routes: routes.flatMap(resolveRouteArg),
-                    excludes: [
-                        ...currentExcludes
-                    ],
-                    ...currentPriority !== undefined ? {
-                        priority: currentPriority
-                    } : {}
-                });
-                currentExcludes = [];
-                currentPriority = undefined;
-                return this;
-            }
-        };
-        return proxy;
-    }
-    getDefinitions() {
-        return [
-            ...this.definitions
-        ];
-    }
-}
-function normalizeRouteArg(route) {
-    return typeof route === 'string' ? {
-        path: route
-    } : route;
-}
-function resolveRouteArg(route) {
-    if (typeof route === 'string') {
-        return [
-            {
-                path: route
-            }
-        ];
-    }
-    if (typeof route === 'function') {
-        const prefix = MetadataRegistry.getControllerPath(route);
-        return [
-            {
-                path: prefix || '/'
-            }
-        ];
-    }
-    return [
-        route
-    ];
-}

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

@@ -1,58 +0,0 @@
-import type { Container } from "../container/container";
-import type { Token, Type } from "../container/types";
-import type { RouteManager } from "../http/route.manager";
-import type { MiddlewareRouteDefinition } from "./middleware";
-/** What the loader records per lazy module instance (see LazyModuleManager). */
-export interface LazyModuleGroupSpec {
-    moduleId: string;
-    tokens: Token[];
-    hasEntrypointContributor: boolean;
-}
-export declare class ModuleLoader {
-    private container;
-    private router;
-    private processedModules;
-    private processingStack;
-    private collectedControllers;
-    private registeredProviders;
-    private moduleExportsCache;
-    private globalExports;
-    private consumerMiddlewareDefinitions;
-    private appProviderCounter;
-    private appProviderTokens;
-    private moduleIdByClassKey;
-    private seenModuleIds;
-    private lazyModuleIds;
-    private lazyGroups;
-    constructor(container: Container, router: RouteManager);
-    load(rootModule: Type): void;
-    private getModuleId;
-    private isProcessed;
-    private markProcessed;
-    private getCachedExports;
-    private cacheExports;
-    private processModule;
-    private warnOnMixedDefaultAndKeyed;
-    /** Registers the provider and returns the token it was registered under. */
-    private registerProvider;
-    private isAppToken;
-    private buildExportSet;
-    getControllers(): Type[];
-    getRegisteredProviders(): Token[];
-    getAppProviderTokens(token: Token): Token[];
-    getConsumerMiddlewareDefinitions(): MiddlewareRouteDefinition[];
-    /**
-     * Every lazy module instance recorded during load. Handed to the
-     * LazyModuleManager at bootstrap; empty when no module opted in.
-     */
-    getLazyGroups(): LazyModuleGroupSpec[];
-    /**
-     * A token is deferred iff EVERY module bucket holding it belongs to a lazy
-     * module instance — a token also registered by a non-lazy module stays on
-     * the eager pass (and resolving it there claims the lazy sibling, which is
-     * the "any use = init" semantic, not a bug).
-     */
-    private isLazyOnlyToken;
-    resolveAllInstances(): Promise<unknown[]>;
-    private routeError;
-}