@velajs/vela 1.9.0 → 1.10.0

package/dist/module/configurable-module.builder.js

@@ -0,0 +1,177 @@
+import { InjectionToken } from "../container/types.js";
+import { stableHash } from "./stable-hash.js";
+/** Default extra: `isGlobal` toggles `DynamicModule.global`, hiding the naming split. */ const DEFAULT_EXTRAS = {
+    isGlobal: false
+};
+const DEFAULT_TRANSFORM = (def, extras)=>extras.isGlobal ? {
+        ...def,
+        global: true
+    } : def;
+/**
+ * NestJS-parity builder that generates `forRoot`/`forRootAsync` (and `key`,
+ * `global`, factory-param inference) from a tiny spec — so a module is just its
+ * tokens + options type + service + a `@Module({...})` bag, while vela keeps its
+ * encapsulation (`exports`/visibility) and multi-instance `key` dedup.
+ *
+ * @example
+ * ```ts
+ * const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
+ *   new ConfigurableModuleBuilder<FooOptions>({ moduleName: 'Foo' }).build();
+ *
+ * @Module({
+ *   providers: [FooService], // derived providers inject MODULE_OPTIONS_TOKEN
+ *   exports: [FooService],
+ * })
+ * export class FooModule extends ConfigurableModuleClass {}
+ * ```
+ */ export class ConfigurableModuleBuilder {
+    options;
+    classMethodName = 'forRoot';
+    factoryMethodName = 'create';
+    extrasDefaults = DEFAULT_EXTRAS;
+    extrasTransform = DEFAULT_TRANSFORM;
+    constructor(options = {}){
+        this.options = options;
+    }
+    /** Declare extra call-site keys (e.g. `isGlobal`) + how they reshape the definition. */ setExtras(defaults, transform) {
+        this.extrasDefaults = defaults;
+        this.extrasTransform = transform;
+        return this;
+    }
+    /** Rename the sync static (default `forRoot`); the async static becomes `<name>Async`. */ setClassMethodName(name) {
+        this.classMethodName = name;
+        return this;
+    }
+    /** Rename the method a `useClass`/`useExisting` options factory must implement (default `create`). */ setFactoryMethodName(name) {
+        this.factoryMethodName = name;
+        return this;
+    }
+    build() {
+        const moduleName = this.options.moduleName ?? 'ConfigurableModule';
+        const optionsToken = this.options.optionsInjectionToken ?? new InjectionToken(`${moduleName}_MODULE_OPTIONS`);
+        const syncName = this.classMethodName;
+        const asyncName = `${this.classMethodName}Async`;
+        const factoryMethodName = this.factoryMethodName;
+        const extrasDefaults = this.extrasDefaults;
+        const transform = this.extrasTransform;
+        let ConfigurableModuleClass = class ConfigurableModuleClass {
+        };
+        Object.defineProperty(ConfigurableModuleClass, syncName, {
+            configurable: true,
+            writable: true,
+            enumerable: false,
+            value (options = {}) {
+                const { key, ...rest } = options;
+                const definition = {
+                    module: this,
+                    key: key ?? stableHash(rest),
+                    providers: [
+                        {
+                            provide: optionsToken,
+                            useValue: rest
+                        }
+                    ]
+                };
+                return transform(definition, {
+                    ...extrasDefaults,
+                    ...rest
+                });
+            }
+        });
+        Object.defineProperty(ConfigurableModuleClass, asyncName, {
+            configurable: true,
+            writable: true,
+            enumerable: false,
+            value (options = {}) {
+                const { key, imports, inject, useFactory, useClass, useExisting, ...restExtras } = options;
+                const definition = {
+                    module: this,
+                    // Include extras (e.g. isGlobal) in the key — like forRoot — so two
+                    // async instances differing only in an extra don't wrongly dedup.
+                    key: key ?? stableHash({
+                        inject,
+                        useFactory,
+                        useClass,
+                        useExisting,
+                        ...restExtras
+                    }),
+                    imports: imports ?? [],
+                    providers: buildAsyncOptionsProviders(optionsToken, factoryMethodName, {
+                        inject,
+                        useFactory,
+                        useClass,
+                        useExisting
+                    })
+                };
+                return transform(definition, {
+                    ...extrasDefaults,
+                    ...restExtras
+                });
+            }
+        });
+        return {
+            ConfigurableModuleClass: ConfigurableModuleClass,
+            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. */ function buildAsyncOptionsProviders(optionsToken, factoryMethodName, async) {
+    if (async.useFactory) {
+        return [
+            {
+                provide: optionsToken,
+                useFactory: async.useFactory,
+                inject: async.inject ?? []
+            }
+        ];
+    }
+    if (async.useClass) {
+        const factoryClass = async.useClass;
+        return [
+            factoryClass,
+            {
+                provide: optionsToken,
+                useFactory: (instance)=>instance[factoryMethodName](),
+                inject: [
+                    factoryClass
+                ]
+            }
+        ];
+    }
+    if (async.useExisting) {
+        return [
+            {
+                provide: optionsToken,
+                useFactory: (instance)=>instance[factoryMethodName](),
+                inject: [
+                    async.useExisting
+                ]
+            }
+        ];
+    }
+    throw new Error('Async module options require one of `useFactory`, `useClass`, or `useExisting`.');
+}
+/**
+ * Lower-level engine for cases a class-mixin can't express — chiefly a
+ * runtime-generated module class whose providers depend on a call-time arg
+ * (Cloudflare binding modules). Returns an object with a single static named by
+ * `spec.methodName` (default `forRoot`).
+ */ export function defineConfigurableModule(spec) {
+    const methodName = spec.methodName ?? 'forRoot';
+    return {
+        [methodName] (args) {
+            const definition = {
+                module: spec.module,
+                key: spec.keyFrom(args),
+                providers: spec.providers(args)
+            };
+            if (spec.imports) definition.imports = spec.imports(args);
+            if (spec.exports) definition.exports = spec.exports;
+            if (spec.global) definition.global = true;
+            return definition;
+        }
+    };
+}

package/dist/module/configurable-module.types.d.ts

@@ -0,0 +1,93 @@
+import type { InferTokens, InjectionToken, Token, Type } from '../container/types';
+import type { DynamicModule, ModuleImport } from '../registry/types';
+/**
+ * Arbitrary extra keys a module accepts alongside its options bag (e.g.
+ * `isGlobal`). Kept separate from the options type so the extras-transform can
+ * reshape the generated {@link DynamicModule} without polluting `Opts`.
+ */
+export type ConfigurableModuleExtras = Record<string, unknown>;
+/**
+ * Reshape the generated definition based on the resolved extras. Runs after the
+ * options provider + `key` are computed; the return value is the final
+ * `DynamicModule`. Mirrors NestJS's `extras` transform.
+ */
+export type ConfigurableModuleExtrasTransform<E extends ConfigurableModuleExtras> = (definition: DynamicModule, extras: E) => DynamicModule;
+/**
+ * The contract a `useClass`/`useExisting` async-options factory must satisfy:
+ * a single method (default name `create`) returning the module options.
+ */
+export type ConfigurableModuleOptionsFactory<Opts, MethodName extends string> = {
+    [K in MethodName]: () => Opts | Promise<Opts>;
+};
+/**
+ * Async configuration accepted by the generated `<method>Async` static.
+ *
+ * Superset of `AsyncModuleOptions` (`registry/types.ts`): adds NestJS's
+ * `useClass`/`useExisting` while preserving the headline `const Inject` tuple
+ * inference for `useFactory` params (no `as const` needed at the call site).
+ */
+export interface ConfigurableModuleAsyncOptions<Opts, MethodName extends string = 'create', Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]> {
+    imports?: ModuleImport[];
+    inject?: Inject;
+    useFactory?: (...args: InferTokens<Inject>) => Opts | Promise<Opts>;
+    useClass?: Type<ConfigurableModuleOptionsFactory<Opts, MethodName>>;
+    useExisting?: Token<ConfigurableModuleOptionsFactory<Opts, MethodName>>;
+    /** Explicit instance discriminator (see {@link DynamicModule.key}). */
+    key?: string;
+}
+export interface ConfigurableModuleBuilderOptions {
+    /** Names the generated base class + the auto-minted options token, and feeds diagnostics. */
+    moduleName?: string;
+    /**
+     * Reuse an existing options token instead of minting one. **Critical for
+     * migrations** so the module's public token keeps its identity.
+     */
+    optionsInjectionToken?: InjectionToken<unknown>;
+}
+/**
+ * The generated base class type, carrying dynamically-named `<method>` and
+ * `<method>Async` statics. A module does `class Foo extends ConfigurableModuleClass {}`
+ * and gets `Foo.forRoot(...)` / `Foo.forRootAsync(...)` for free.
+ */
+export type ConfigurableModuleClassType<Opts, MethodKey extends string, FactoryMethodKey extends string, Extras extends ConfigurableModuleExtras> = (new () => object) & Record<MethodKey, (options: Opts & Partial<Extras> & {
+    key?: string;
+}) => DynamicModule> & Record<`${MethodKey}Async`, <const Inject extends readonly Token<unknown>[]>(options: ConfigurableModuleAsyncOptions<Opts, FactoryMethodKey, Inject> & Partial<Extras> & {
+    key?: string;
+}) => DynamicModule>;
+export interface ConfigurableModuleHost<Opts, MethodKey extends string = 'forRoot', FactoryMethodKey extends string = 'create', Extras extends ConfigurableModuleExtras = {
+    isGlobal?: boolean;
+}> {
+    /** Base class to `extends`. */
+    ConfigurableModuleClass: ConfigurableModuleClassType<Opts, MethodKey, FactoryMethodKey, Extras>;
+    /** The options token — inject it into derived providers (`inject: [MODULE_OPTIONS_TOKEN]`). */
+    MODULE_OPTIONS_TOKEN: InjectionToken<Opts>;
+    /** Type-only helper: the shape accepted by the sync `<method>` static. */
+    OPTIONS_TYPE: Opts & Partial<Extras> & {
+        key?: string;
+    };
+    /** Type-only helper: the shape accepted by the `<method>Async` static. */
+    ASYNC_OPTIONS_TYPE: ConfigurableModuleAsyncOptions<Opts, FactoryMethodKey> & Partial<Extras> & {
+        key?: string;
+    };
+}
+/**
+ * Low-level engine spec (see `defineConfigurableModule`). Used for the cases a
+ * class-mixin can't express — notably runtime-generated module classes whose
+ * providers depend on a call-time argument (e.g. Cloudflare binding modules).
+ */
+export interface DefineConfigurableModuleSpec<Args> {
+    /** The module class to reference in `{ module }`. */
+    module: Type;
+    /** Static method name to generate (e.g. `forRoot`). */
+    methodName?: string;
+    /** Derive the instance `key` from the call args. */
+    keyFrom: (args: Args) => string;
+    /** Build the provider list from the call args. */
+    providers: (args: Args) => DynamicModule['providers'];
+    /** Optional exports (usually prefer declaring these on `@Module`). */
+    exports?: DynamicModule['exports'];
+    /** Optional imports. */
+    imports?: (args: Args) => DynamicModule['imports'];
+    /** Mark the produced module global. */
+    global?: boolean;
+}

package/dist/module/configurable-module.types.js

@@ -0,0 +1,5 @@
+/**
+ * Low-level engine spec (see `defineConfigurableModule`). Used for the cases a
+ * class-mixin can't express — notably runtime-generated module classes whose
+ * providers depend on a call-time argument (e.g. Cloudflare binding modules).
+ */ export { };

package/dist/module/index.d.ts

@@ -1,5 +1,7 @@
 export { Global, Module, isModule, getModuleMetadata, defineDynamicModule, } from './decorators';
 export { stableHash } from './stable-hash';
+export { ConfigurableModuleBuilder, defineConfigurableModule, } from './configurable-module.builder';
+export type { ConfigurableModuleAsyncOptions, ConfigurableModuleBuilderOptions, ConfigurableModuleClassType, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, ConfigurableModuleOptionsFactory, DefineConfigurableModuleSpec, } from './configurable-module.types';
 export { ModuleLoader } from './module-loader';
 export { MiddlewareBuilder } from './middleware';
 export type { MiddlewareConsumer, MiddlewareConfigProxy, MiddlewareRouteDefinition, NestModule, RouteInfo, } from './middleware';

package/dist/module/index.js

@@ -1,4 +1,5 @@
 export { Global, Module, isModule, getModuleMetadata, defineDynamicModule } from "./decorators.js";
 export { stableHash } from "./stable-hash.js";
+export { ConfigurableModuleBuilder, defineConfigurableModule } from "./configurable-module.builder.js";
 export { ModuleLoader } from "./module-loader.js";
 export { MiddlewareBuilder } from "./middleware.js";

package/dist/pipeline/types.d.ts

@@ -11,16 +11,33 @@ export interface HttpArgumentsHost {
     getRequest<T = Request>(): T;
     getResponse<T = Context>(): T;
 }
+/**
+ * WebSocket-specific arguments host returned by `ExecutionContext.switchToWs()`.
+ * Populated by `@velajs/vela/websocket` when a gateway message is dispatched.
+ *
+ * - `getClient()` — the connected socket (`WsClient`)
+ * - `getData()` — the inbound message payload (the envelope's `data`)
+ * - `getPattern()` — the subscribed event name that matched
+ */
+export interface WsArgumentsHost {
+    getClient<T = unknown>(): T;
+    getData<T = unknown>(): T;
+    getPattern<T = string>(): T;
+}
+/** The transport a component is executing under. `'http'` for routes, `'ws'` for gateway messages. */
+export type ContextType = 'http' | 'ws';
 export interface ExecutionContext {
-    getType<T extends string = 'http'>(): T;
+    getType<T extends string = ContextType>(): T;
     getClass(): Type;
     getHandler(): string | symbol;
-    /** Returns the Hono `Context` directly. */
+    /** Returns the Hono `Context` directly. Throws on a WebSocket context. */
     getContext<T = Context>(): T;
-    /** Shorthand for `switchToHttp().getRequest()` — returns the Web `Request`. */
+    /** Shorthand for `switchToHttp().getRequest()` — returns the Web `Request`. Throws on a WebSocket context. */
     getRequest(): Request;
-    /** Switch to the HTTP arguments host for NestJS-style `getRequest()` / `getResponse()` access. */
+    /** Switch to the HTTP arguments host. Throws on a WebSocket context. */
     switchToHttp(): HttpArgumentsHost;
+    /** Switch to the WebSocket arguments host. Throws on an HTTP context. */
+    switchToWs(): WsArgumentsHost;
 }
 export interface CanActivate {
     canActivate(context: ExecutionContext): boolean | Promise<boolean>;

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

@@ -5,22 +5,22 @@ export interface ControllerOptions {
     version?: number | number[];
 }
 export declare class MetadataRegistry {
-    private static readonly routes;
-    private static readonly controllers;
-    private static readonly controllerOptions;
-    private static readonly modules;
-    private static readonly parameters;
-    private static readonly injectables;
-    private static readonly scopes;
-    private static readonly injectTokens;
-    private static readonly handlerHttpMeta;
-    private static readonly catchTypes;
-    private static readonly routeVersions;
-    private static readonly classMeta;
-    private static readonly handlerMeta;
-    private static readonly controllerComponents;
-    private static readonly handlerComponents;
-    private static globalComponents;
+    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 controllerComponents();
+    private static get handlerComponents();
+    private static get globalComponents();
     static getRoutes(controller: Constructor): RouteDefinition[];
     static addRoute(controller: Constructor, route: RouteDefinition): void;
     static getControllerPath(controller: Constructor): string;

package/dist/registry/metadata.registry.js

@@ -17,37 +17,95 @@ function emptyComponentByOwner() {
         filter: new Map()
     };
 }
-export class MetadataRegistry {
-    // Decoration metadata (set at import time, persists across clear()).
-    static routes = new Map();
-    static controllers = new Map();
-    static controllerOptions = new Map();
-    static modules = new Map();
-    static parameters = new Map();
-    static injectables = new Set();
-    static scopes = new Map();
-    static injectTokens = new Map();
-    static handlerHttpMeta = new Map();
-    static catchTypes = new Map();
-    static routeVersions = new Map();
-    // Free-form key→value class & handler meta. Backs:
-    //   - @SetMetadata (custom user keys)
-    //   - feature decorators (@Cron, @OnEvent, @ApiDoc, …)
-    //   - the SWC shim (Reflect.metadata's design:* keys)
-    //   - external Reflect.defineMetadata / Reflect.getMetadata calls.
-    static classMeta = new Map();
-    static handlerMeta = new Map();
-    // Component decoration (set by @UseGuards/@UsePipes/etc. at decoration time).
-    static controllerComponents = emptyComponentByOwner();
-    static handlerComponents = {
-        middleware: new Map(),
-        guard: new Map(),
-        pipe: new Map(),
-        interceptor: new Map(),
-        filter: new Map()
+function createRegistryState() {
+    return {
+        routes: new Map(),
+        controllers: new Map(),
+        controllerOptions: new Map(),
+        modules: new Map(),
+        parameters: new Map(),
+        injectables: new Set(),
+        scopes: new Map(),
+        injectTokens: new Map(),
+        handlerHttpMeta: new Map(),
+        catchTypes: new Map(),
+        routeVersions: new Map(),
+        classMeta: new Map(),
+        handlerMeta: new Map(),
+        controllerComponents: emptyComponentByOwner(),
+        handlerComponents: {
+            middleware: new Map(),
+            guard: new Map(),
+            pipe: new Map(),
+            interceptor: new Map(),
+            filter: new Map()
+        },
+        globalComponents: emptyComponentStore()
     };
-    // Global components — app-time state (cleared by clear()).
-    static globalComponents = emptyComponentStore();
+}
+// HMR-safe: anchor ALL backing state on `globalThis` so a Vite dev re-eval of
+// this module reuses the SAME maps that classes were already decorated against.
+// Without this, re-eval creates fresh empty statics → split-brain (lost routes,
+// spurious "not @Injectable" warnings, duplicated global components). The
+// versioned symbol avoids collisions across framework major versions in one
+// process. `globalThis` + `Symbol.for` exist on every target runtime; no node:*.
+const REGISTRY_STATE_KEY = Symbol.for('vela:registry:v1');
+function registryState() {
+    const g = globalThis;
+    return g[REGISTRY_STATE_KEY] ??= createRegistryState();
+}
+export class MetadataRegistry {
+    // Every field is a getter over the globalThis-anchored state (registryState).
+    // Method bodies keep using `this.<field>`; the getter returns the live map so
+    // `.set`/`.get`/`.clear` mutate the shared state.
+    static get routes() {
+        return registryState().routes;
+    }
+    static get controllers() {
+        return registryState().controllers;
+    }
+    static get controllerOptions() {
+        return registryState().controllerOptions;
+    }
+    static get modules() {
+        return registryState().modules;
+    }
+    static get parameters() {
+        return registryState().parameters;
+    }
+    static get injectables() {
+        return registryState().injectables;
+    }
+    static get scopes() {
+        return registryState().scopes;
+    }
+    static get injectTokens() {
+        return registryState().injectTokens;
+    }
+    static get handlerHttpMeta() {
+        return registryState().handlerHttpMeta;
+    }
+    static get catchTypes() {
+        return registryState().catchTypes;
+    }
+    static get routeVersions() {
+        return registryState().routeVersions;
+    }
+    static get classMeta() {
+        return registryState().classMeta;
+    }
+    static get handlerMeta() {
+        return registryState().handlerMeta;
+    }
+    static get controllerComponents() {
+        return registryState().controllerComponents;
+    }
+    static get handlerComponents() {
+        return registryState().handlerComponents;
+    }
+    static get globalComponents() {
+        return registryState().globalComponents;
+    }
     // Routes
     static getRoutes(controller) {
         return this.routes.get(controller) ?? [];
@@ -237,7 +295,7 @@ export class MetadataRegistry {
     // Clear app-time state. Decoration metadata persists — once a class is
     // decorated, that fact is permanent for the lifetime of the process.
     static clear() {
-        this.globalComponents = emptyComponentStore();
+        registryState().globalComponents = emptyComponentStore();
     }
     // Full reset, including decoration metadata. Used in framework-internal scenarios.
     static reset() {
@@ -264,6 +322,6 @@ export class MetadataRegistry {
             this.controllerComponents[type].clear();
             this.handlerComponents[type].clear();
         }
-        this.globalComponents = emptyComponentStore();
+        registryState().globalComponents = emptyComponentStore();
     }
 }

package/dist/seeder/index.d.ts

@@ -0,0 +1,5 @@
+export { Seeder } from './seeder.decorator';
+export { SeederRegistry } from './seeder.registry';
+export { SeederModule, runSeeders } from './seeder.module';
+export { SEEDER_METADATA } from './seeder.tokens';
+export type { Seeder as ISeeder, SeederMetadata, RegisteredSeeder, SeederResult, } from './seeder.types';

package/dist/seeder/index.js

@@ -0,0 +1,4 @@
+export { Seeder } from "./seeder.decorator.js";
+export { SeederRegistry } from "./seeder.registry.js";
+export { SeederModule, runSeeders } from "./seeder.module.js";
+export { SEEDER_METADATA } from "./seeder.tokens.js";

package/dist/seeder/seeder.decorator.d.ts

@@ -0,0 +1,7 @@
+import type { SeederMetadata } from './seeder.types';
+/**
+ * Mark a class as a seeder. Also marks it `@Injectable()` (singleton) so it only
+ * needs to be listed in a module's providers (or `SeederModule.forRoot({ seeders })`)
+ * to be discovered by {@link SeederRegistry} at bootstrap.
+ */
+export declare function Seeder(options?: SeederMetadata): ClassDecorator;

package/dist/seeder/seeder.decorator.js

@@ -0,0 +1,15 @@
+import { Scope } from "../constants.js";
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { SEEDER_METADATA } from "./seeder.tokens.js";
+/**
+ * Mark a class as a seeder. Also marks it `@Injectable()` (singleton) so it only
+ * needs to be listed in a module's providers (or `SeederModule.forRoot({ seeders })`)
+ * to be discovered by {@link SeederRegistry} at bootstrap.
+ */ export function Seeder(options = {}) {
+    return (target)=>{
+        const ctor = target;
+        MetadataRegistry.markInjectable(ctor);
+        MetadataRegistry.setScope(ctor, Scope.SINGLETON);
+        MetadataRegistry.setCustomClassMeta(target, SEEDER_METADATA, options);
+    };
+}

package/dist/seeder/seeder.module.d.ts

@@ -0,0 +1,18 @@
+import type { VelaApplication } from '../application';
+import type { DynamicModule } from '../module/types';
+import type { Type } from '../container/types';
+import type { SeederResult } from './seeder.types';
+export declare class SeederModule {
+    /**
+     * Register seeder classes as providers so they're discovered at bootstrap.
+     * (Seeders declared in other modules' providers are also discovered — this is
+     * just a convenience to co-locate them.)
+     */
+    static forRoot(options?: {
+        seeders?: Type[];
+    }): DynamicModule;
+}
+/** Convenience runner: resolve the registry from a built app and run all seeders. */
+export declare function runSeeders(app: VelaApplication, options?: {
+    stopOnError?: boolean;
+}): Promise<SeederResult[]>;

package/dist/seeder/seeder.module.js

@@ -0,0 +1,40 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { Module } from "../module/decorators.js";
+import { stableHash } from "../module/stable-hash.js";
+import { SeederRegistry } from "./seeder.registry.js";
+export class SeederModule {
+    /**
+   * Register seeder classes as providers so they're discovered at bootstrap.
+   * (Seeders declared in other modules' providers are also discovered — this is
+   * just a convenience to co-locate them.)
+   */ static forRoot(options = {}) {
+        const seeders = options.seeders ?? [];
+        return {
+            module: SeederModule,
+            key: stableHash({
+                seeders: seeders.map((s)=>s.name)
+            }),
+            providers: [
+                ...seeders
+            ]
+        };
+    }
+}
+SeederModule = _ts_decorate([
+    Module({
+        providers: [
+            SeederRegistry
+        ],
+        exports: [
+            SeederRegistry
+        ]
+    })
+], SeederModule);
+/** Convenience runner: resolve the registry from a built app and run all seeders. */ export function runSeeders(app, options) {
+    return app.get(SeederRegistry).runAll(options);
+}

package/dist/seeder/seeder.registry.d.ts

@@ -0,0 +1,23 @@
+import { Container } from '../container/container';
+import type { OnApplicationBootstrap } from '../lifecycle/index';
+import type { RegisteredSeeder, SeederResult } from './seeder.types';
+/**
+ * Discovers `@Seeder()` providers at bootstrap and runs them on demand.
+ * Mirrors `ScheduleRegistry`'s discovery (scan container tokens → read metadata).
+ */
+export declare class SeederRegistry implements OnApplicationBootstrap {
+    private readonly container;
+    private seeders;
+    constructor(container: Container);
+    onApplicationBootstrap(): void;
+    /** Registered seeders in run order. */
+    list(): RegisteredSeeder[];
+    /**
+     * Run every seeder in order, each in its own request-scoped child container so
+     * request-scoped dependencies resolve. Returns a per-seeder result; when
+     * `stopOnError` is true (default) the run aborts on the first failure.
+     */
+    runAll(options?: {
+        stopOnError?: boolean;
+    }): Promise<SeederResult[]>;
+}