@velajs/vela 1.9.0 → 1.12.0

package/dist/i18n/message-loader.service.js

@@ -0,0 +1,90 @@
+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;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import IntlMessageFormat from "intl-messageformat";
+import { Inject, Injectable } from "../container/decorators.js";
+import { I18N_OPTIONS } from "./i18n.tokens.js";
+import { MessageRegistry } from "./message-registry.js";
+export class MessageLoaderService {
+    cache = new Map();
+    compiledCache = new Map();
+    defaultLocale;
+    fallbackLocale;
+    constructor(registry, options){
+        this.defaultLocale = options?.defaultLocale ?? 'en';
+        this.fallbackLocale = options?.fallbackLocale ?? this.defaultLocale;
+        const merged = registry.getMergedMessages();
+        for (const locale of Object.keys(merged)){
+            this.cache.set(locale, merged[locale]);
+        }
+    }
+    translate(locale, key, params) {
+        const primary = this.getCompiledMessages(locale)[key];
+        if (primary) return primary(params);
+        // Per-key fallback: a supported locale missing an individual key falls back
+        // to fallbackLocale before giving up (returning the raw key).
+        if (this.fallbackLocale !== locale) {
+            const fallback = this.getCompiledMessages(this.fallbackLocale)[key];
+            if (fallback) return fallback(params);
+        }
+        return key; // missing everywhere → return the key (dev-friendly)
+    }
+    getAvailableLocales() {
+        return [
+            ...this.cache.keys()
+        ];
+    }
+    isLocaleSupported(locale) {
+        return this.cache.has(locale);
+    }
+    getDefaultLocale() {
+        return this.defaultLocale;
+    }
+    getCompiledMessages(locale) {
+        const effectiveLocale = this.cache.has(locale) ? locale : this.defaultLocale;
+        const cached = this.compiledCache.get(effectiveLocale);
+        if (cached) return cached;
+        const flattened = this.flattenMessages(this.cache.get(effectiveLocale) ?? {});
+        const compiled = {};
+        for (const [key, value] of Object.entries(flattened)){
+            const msg = new IntlMessageFormat(value, effectiveLocale);
+            compiled[key] = (params)=>String(msg.format(params));
+        }
+        this.compiledCache.set(effectiveLocale, compiled);
+        return compiled;
+    }
+    flattenMessages(messages, prefix = '') {
+        const result = {};
+        for (const key of Object.keys(messages)){
+            const value = messages[key];
+            const newKey = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                Object.assign(result, this.flattenMessages(value, newKey));
+            } else {
+                result[newKey] = String(value);
+            }
+        }
+        return result;
+    }
+}
+MessageLoaderService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(MessageRegistry)),
+    _ts_param(1, Inject(I18N_OPTIONS)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof MessageRegistry === "undefined" ? Object : MessageRegistry,
+        typeof I18nModuleOptions === "undefined" ? Object : I18nModuleOptions
+    ])
+], MessageLoaderService);

package/dist/i18n/message-registry.d.ts

@@ -0,0 +1,16 @@
+type Contribution = Record<string, Record<string, unknown>>;
+/**
+ * Accumulates i18n messages from multiple `I18nModule.registerMessages()` calls
+ * (statically, at module import time), deep-merged on read by
+ * {@link MessageLoaderService}. Later registrations override earlier ones at the
+ * leaf level.
+ */
+export declare class MessageRegistry {
+    /** Called by `I18nModule.registerMessages()`. */
+    static addMessages(messages: Contribution): void;
+    /** All contributions deep-merged, per locale, in registration order. */
+    getMergedMessages(): Record<string, Record<string, unknown>>;
+    /** @internal — testing */
+    static reset(): void;
+}
+export {};

package/dist/i18n/message-registry.js

@@ -0,0 +1,49 @@
+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 { Injectable } from "../container/decorators.js";
+import { deepMerge } from "./deep-merge.js";
+// Shared contributions store anchored on globalThis so bundler-inlined copies
+// (portal/symlink) and Vite HMR re-eval share ONE store. Content-keyed so
+// re-registering identical messages (HMR) dedups instead of accumulating.
+const CONTRIBUTIONS_KEY = Symbol.for('vela:i18n:message-registry:contributions');
+function getContributions() {
+    const g = globalThis;
+    return g[CONTRIBUTIONS_KEY] ??= new Map();
+}
+function contentKey(value) {
+    if (Array.isArray(value)) return `[${value.map(contentKey).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.keys(value).sort().map((key)=>`${JSON.stringify(key)}:${contentKey(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'undefined';
+}
+export class MessageRegistry {
+    /** Called by `I18nModule.registerMessages()`. */ static addMessages(messages) {
+        if (messages && typeof messages === 'object' && Object.keys(messages).length > 0) {
+            // set() dedups by content-key AND preserves insertion order for an existing
+            // key. (A prior delete+set moved re-registered content to the end, flipping
+            // deep-merge precedence under HMR re-eval.)
+            getContributions().set(contentKey(messages), messages);
+        }
+    }
+    /** All contributions deep-merged, per locale, in registration order. */ getMergedMessages() {
+        const merged = {};
+        for (const contribution of getContributions().values()){
+            for (const locale of Object.keys(contribution)){
+                merged[locale] = deepMerge(merged[locale] ?? {}, contribution[locale]);
+            }
+        }
+        return merged;
+    }
+    /** @internal — testing */ static reset() {
+        globalThis[CONTRIBUTIONS_KEY] = new Map();
+    }
+}
+MessageRegistry = _ts_decorate([
+    Injectable()
+], MessageRegistry);

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, } from './http/index';
 export { REQUEST_CONTEXT } from './http/request-context';
 export type { RequestContext } from './http/request-context';
+export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext, } from './http/ambient';
 export { Logger, LogLevel } from './services/index';
 export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './services/index';
 export { ConfigModule, ConfigService, CONFIG_OPTIONS } from './config/index';
@@ -20,22 +21,33 @@ export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } fr
 export type { HttpModuleOptions, HttpResponse, HttpRequestConfig } from './fetch/index';
 export { CorsModule, CORS_OPTIONS } from './cors/index';
 export type { CorsOptions } from './cors/index';
-export { CacheModule, CacheService, CacheInterceptor, MemoryCacheStore, CacheKey, CacheTTL, CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA, } from './cache/index';
-export type { CacheModuleOptions, CacheStore, CacheEntry } from './cache/index';
+export { CacheModule, CacheService, CacheInterceptor, MemoryCacheStore, TieredCacheStore, CacheKey, CacheTTL, CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA, } from './cache/index';
+export type { Awaitable, CacheModuleOptions, CacheStore, AsyncCacheStore, AnyCacheStore, CacheEntry, } from './cache/index';
 export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_EVENT_METADATA, } from './event-emitter/index';
 export type { EventHandler, OnEventMetadata } from './event-emitter/index';
 export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA, } from './schedule/index';
 export type { RegisteredCronJob, RegisteredIntervalJob, CronMetadata, IntervalMetadata, CronMatcher, } from './schedule/index';
+export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsDispatcher, WsException, WS_SERVER, } from './websocket/index';
+export type { WebSocketModuleOptions, WsClient, WsServer, WsMessage, WsResponse, WsExecutionContext, WsArgumentsHost, BroadcastCommand, SyncDriver, RoomRegistry, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket/index';
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator, } from './health/index';
 export type { HealthCheckResult, HealthCheckStatus, HealthIndicatorResult, HealthIndicatorFunction, ResponseCheckCallback, HttpPingOptions, } from './health/index';
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA, } from './throttler/index';
 export type { ThrottlerModuleOptions, ThrottleConfig, ThrottlerStore, ThrottlerStorageRecord, RateLimitInfo, } from './throttler/index';
-export { Global, Module, defineDynamicModule, stableHash, } from './module/index';
-export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport } from './module/index';
+export { Global, Module, defineDynamicModule, stableHash, moduleKey, ConfigurableModuleBuilder, defineConfigurableModule, defineModule, buildAsyncOptionsProviders, lazyProvider, moduleToken, provideGlobal, sideEffectModule, } from './module/index';
+export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport, ConfigurableModuleAsyncOptions, ConfigurableModuleBuilderOptions, ConfigurableModuleClassType, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, ConfigurableModuleOptionsFactory, DefineConfigurableModuleSpec, DefineModuleSpec, GlobalComponentSlot, ModuleContributions, ModuleSetupContext, LazyProviderSpec, } from './module/index';
 export type { MiddlewareConsumer, NestModule, RouteInfo } from './http/index';
+export { DiscoveryService, createDiscoverableDecorator, } from './discovery/index';
+export type { DiscoveredClass, DiscoveredMethodMeta, DiscoveryFilter, DiscoverableDecorator, CreateDiscoverableDecoratorOptions, } from './discovery/index';
+export { EntrypointRegistry, registerEntrypointKind, getEntrypointKinds, contributesEntrypoints, runInEntrypointScope, buildEntrypointExecutionContext, } from './entrypoint/index';
+export type { ContributesEntrypoints, Entrypoint, EntrypointKind, EntrypointExecutionContext, } from './entrypoint/index';
+export { registerRouteContributor, getRouteContributors, } from './http/route-contributor';
+export type { RouteContributor, RouteContributorContext, RouteContributorOpenApiContext, } from './http/route-contributor';
+export type { AdapterContext, RuntimeAdapter } from './factory/adapter';
+export type { VelaCreateOptions } from './factory';
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
 export type { Plugin } from './plugin/plugin';
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
+export type { PipelineRunOptions } from './pipeline/index';
 export type { HttpArgumentsHost, ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, ReflectableDecorator, CreateDecoratorOptions, } from './pipeline/index';
 export type { Constructor, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, } from './registry/index';
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipeline/index';

package/dist/index.js

@@ -14,6 +14,8 @@ export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators } from "./http/index.js";
 // Request-scoped context primitive
 export { REQUEST_CONTEXT } from "./http/request-context.js";
+// Opt-in ambient container access (ALS via hono/context-storage)
+export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext } from "./http/ambient.js";
 // Services
 export { Logger, LogLevel } from "./services/index.js";
 // Config
@@ -23,21 +25,30 @@ export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } fr
 // CORS
 export { CorsModule, CORS_OPTIONS } from "./cors/index.js";
 // Cache
-export { CacheModule, CacheService, CacheInterceptor, MemoryCacheStore, CacheKey, CacheTTL, CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA } from "./cache/index.js";
+export { CacheModule, CacheService, CacheInterceptor, MemoryCacheStore, TieredCacheStore, CacheKey, CacheTTL, CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA } from "./cache/index.js";
 // Event Emitter
 export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_EVENT_METADATA } from "./event-emitter/index.js";
 // Schedule
 export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA } from "./schedule/index.js";
+// WebSocket (edge-safe core; transport-facing internals live at @velajs/vela/websocket)
+export { WebSocketModule, WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsDispatcher, WsException, WS_SERVER } from "./websocket/index.js";
 // Health
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator } from "./health/index.js";
 // Throttler
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA } from "./throttler/index.js";
 // Module
-export { Global, Module, defineDynamicModule, stableHash } from "./module/index.js";
+export { Global, Module, defineDynamicModule, stableHash, moduleKey, ConfigurableModuleBuilder, defineConfigurableModule, defineModule, buildAsyncOptionsProviders, lazyProvider, moduleToken, provideGlobal, sideEffectModule } from "./module/index.js";
+// Discovery — decorator-driven provider discovery (the public replacement for
+// hand-rolled bootstrap scans)
+export { DiscoveryService, createDiscoverableDecorator } from "./discovery/index.js";
+// Entrypoints — the open non-HTTP entry surface (websocket, queue, cron, …)
+export { EntrypointRegistry, registerEntrypointKind, getEntrypointKinds, contributesEntrypoints, runInEntrypointScope, buildEntrypointExecutionContext } from "./entrypoint/index.js";
+// Route contribution — metadata-claimed route generators (@Crud-style)
+export { registerRouteContributor, getRouteContributors } from "./http/route-contributor.js";
 // Plugin manifest + composer
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
 // Built-in Pipes
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe } from "./pipeline/index.js";
 // Errors

package/dist/internal.d.ts

@@ -5,8 +5,6 @@ export type { ModuleScope, ContainerOptions, Diagnostics, } from './container/ty
 export { bindAppProviders } from './pipeline/app-providers';
 export { RouteManager } from './http/route.manager';
 export type { RouteManagerOptions } from './http/route.manager';
-export { registerCrudBridge, getCrudBridge, } from './http/crud-bridge';
-export type { CrudBridge, CrudBridgeRouteContext, CrudBridgeOpenApiContext, } from './http/crud-bridge';
 export { ModuleLoader } from './module/module-loader';
 export { ComponentManager } from './pipeline/component.manager';
 export { VelaApplication } from './application';

package/dist/internal.js

@@ -6,13 +6,6 @@ export { ModuleRef } from "./container/module-ref.js";
 export { ModuleVisibilityError } from "./container/types.js";
 export { bindAppProviders } from "./pipeline/app-providers.js";
 export { RouteManager } from "./http/route.manager.js";
-// CRUD bridge registry — the integration seam for `@velajs/crud` (and any
-// future CRUD route generator). `@velajs/crud` calls `registerCrudBridge`
-// once at import time; the framework consults `getCrudBridge` whenever it
-// encounters a controller carrying `vela:crud` metadata, both at route
-// build time and at OpenAPI document generation. The types are exposed so
-// integrators can write their own bridges or strongly-typed mocks in tests.
-export { registerCrudBridge, getCrudBridge } from "./http/crud-bridge.js";
 export { ModuleLoader } from "./module/module-loader.js";
 export { ComponentManager } from "./pipeline/component.manager.js";
 export { VelaApplication } from "./application.js";

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

@@ -0,0 +1,56 @@
+import type { DynamicModule } from '../registry/types';
+import type { ConfigurableModuleBuilderOptions, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, DefineConfigurableModuleSpec } from './configurable-module.types';
+/**
+ * Blessed key-derivation helper for hand-written `forRoot` statics: the one
+ * documented way to derive a `DynamicModule.key` from an options bag so
+ * identical configurations dedup (HMR-idempotent) and distinct ones coexist.
+ * Alias of {@link stableHash} with a module-authoring name.
+ */
+export declare const moduleKey: (options: unknown) => string;
+/**
+ * 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.
+ *
+ * Since 1.11 this is a thin adapter over {@link defineModule} — the single
+ * authoring engine. Prefer `defineModule` for new modules: it additionally
+ * supports contributions (providers/controllers/imports/exports/global
+ * components) computed as functions of the options.
+ *
+ * @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 declare class ConfigurableModuleBuilder<Opts, MethodKey extends string = 'forRoot', FactoryMethodKey extends string = 'create', Extras extends ConfigurableModuleExtras = {
+    isGlobal?: boolean;
+}> {
+    private readonly options;
+    private classMethodName;
+    private factoryMethodName;
+    private extrasDefaults;
+    private extrasTransform;
+    constructor(options?: ConfigurableModuleBuilderOptions);
+    /** Declare extra call-site keys (e.g. `isGlobal`) + how they reshape the definition. */
+    setExtras<NewExtras extends ConfigurableModuleExtras>(defaults: NewExtras, transform: ConfigurableModuleExtrasTransform<NewExtras>): ConfigurableModuleBuilder<Opts, MethodKey, FactoryMethodKey, NewExtras>;
+    /** Rename the sync static (default `forRoot`); the async static becomes `<name>Async`. */
+    setClassMethodName<NewMethodKey extends string>(name: NewMethodKey): ConfigurableModuleBuilder<Opts, NewMethodKey, FactoryMethodKey, Extras>;
+    /** Rename the method a `useClass`/`useExisting` options factory must implement (default `create`). */
+    setFactoryMethodName<NewFactoryMethodKey extends string>(name: NewFactoryMethodKey): ConfigurableModuleBuilder<Opts, MethodKey, NewFactoryMethodKey, Extras>;
+    build(): ConfigurableModuleHost<Opts, MethodKey, FactoryMethodKey, Extras>;
+}
+/**
+ * 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 declare function defineConfigurableModule<Args>(spec: DefineConfigurableModuleSpec<Args>): Record<string, (args: Args) => DynamicModule>;

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

@@ -0,0 +1,84 @@
+import { defineModule } from "./define-module.js";
+import { stableHash } from "./stable-hash.js";
+/**
+ * Blessed key-derivation helper for hand-written `forRoot` statics: the one
+ * documented way to derive a `DynamicModule.key` from an options bag so
+ * identical configurations dedup (HMR-idempotent) and distinct ones coexist.
+ * Alias of {@link stableHash} with a module-authoring name.
+ */ export const moduleKey = stableHash;
+/**
+ * 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.
+ *
+ * Since 1.11 this is a thin adapter over {@link defineModule} — the single
+ * authoring engine. Prefer `defineModule` for new modules: it additionally
+ * supports contributions (providers/controllers/imports/exports/global
+ * components) computed as functions of the options.
+ *
+ * @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;
+    extrasTransform;
+    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() {
+        return defineModule({
+            name: this.options.moduleName ?? 'ConfigurableModule',
+            optionsToken: this.options.optionsInjectionToken,
+            extras: this.extrasDefaults,
+            transform: this.extrasTransform,
+            methodName: this.classMethodName,
+            factoryMethodName: this.factoryMethodName
+        });
+    }
+}
+/**
+ * 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/define-module.d.ts

@@ -0,0 +1,105 @@
+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;
+}
+/**
+ * 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>;