@velajs/vela 1.8.8 → 1.10.0

package/dist/i18n/i18n.middleware.d.ts

@@ -0,0 +1,15 @@
+import type { Context, Next } from 'hono';
+import type { NestMiddleware } from '../pipeline/types';
+import { type I18nModuleOptions } from './i18n.options';
+/**
+ * Detects the request locale and stashes it on the per-request RequestContext
+ * bag under {@link I18N_LOCALE_KEY}, where {@link I18nService} reads it.
+ * Registered globally via APP_MIDDLEWARE by {@link I18nModule}. Holds no
+ * per-request state (reads the RequestContext off the request container each
+ * call), so a singleton instance is safe.
+ */
+export declare class I18nLocaleMiddleware implements NestMiddleware {
+    private readonly resolved;
+    constructor(options: I18nModuleOptions);
+    use(c: Context, next: Next): Promise<Response | void>;
+}

package/dist/i18n/i18n.middleware.js

@@ -0,0 +1,94 @@
+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 { Inject, Injectable } from "../container/decorators.js";
+import { REQUEST_CONTEXT } from "../http/request-context.js";
+import { resolveI18nOptions } from "./i18n.options.js";
+import { I18N_LOCALE_KEY, I18N_OPTIONS } from "./i18n.tokens.js";
+export class I18nLocaleMiddleware {
+    resolved;
+    constructor(options){
+        this.resolved = resolveI18nOptions(options);
+    }
+    async use(c, next) {
+        const container = c.get('container');
+        if (container) {
+            const ctx = container.resolve(REQUEST_CONTEXT);
+            ctx.set(I18N_LOCALE_KEY, detectLocale(c, this.resolved));
+        }
+        return next();
+    }
+}
+I18nLocaleMiddleware = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(I18N_OPTIONS)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof I18nModuleOptions === "undefined" ? Object : I18nModuleOptions
+    ])
+], I18nLocaleMiddleware);
+function detectLocale(c, resolved) {
+    if (!resolved.detection.enabled) return resolved.defaultLocale;
+    const { strategy, lookupKey } = resolved.detection;
+    // Candidate tags in preference order.
+    const candidates = strategy === 'query' ? [
+        new URL(c.req.url).searchParams.get(lookupKey) ?? ''
+    ] : strategy === 'cookie' ? [
+        readCookie(c.req.raw.headers.get('cookie'), lookupKey) ?? ''
+    ] : parseAcceptLanguage(c.req.raw.headers.get('accept-language'));
+    for (const candidate of candidates){
+        const match = matchLocale(candidate, resolved.locales);
+        if (match) return match;
+    }
+    return resolved.defaultLocale;
+}
+/** Case-insensitive locale match with region fallback (en-US -> en); returns the configured casing. */ function matchLocale(candidate, locales) {
+    if (!candidate) return undefined;
+    const lc = candidate.toLowerCase();
+    const exact = locales.find((l)=>l.toLowerCase() === lc);
+    if (exact) return exact;
+    const base = lc.split('-')[0];
+    return locales.find((l)=>l.toLowerCase().split('-')[0] === base);
+}
+/** Parse Accept-Language into tags ordered by descending q-value (RFC 7231). */ function parseAcceptLanguage(header) {
+    if (!header) return [];
+    return header.split(',').map((part)=>{
+        const [tag, ...params] = part.trim().split(';');
+        let q = 1;
+        for (const p of params){
+            const m = p.trim().match(/^q=([\d.]+)$/);
+            if (m) q = Number.parseFloat(m[1]);
+        }
+        return {
+            tag: (tag ?? '').trim(),
+            q: Number.isNaN(q) ? 0 : q
+        };
+    }).filter((e)=>e.tag && e.tag !== '*').sort((a, b)=>b.q - a.q).map((e)=>e.tag);
+}
+function readCookie(header, name) {
+    if (!header) return undefined;
+    for (const part of header.split(';')){
+        const [rawKey, ...rest] = part.split('=');
+        if (rawKey?.trim() === name) {
+            const raw = rest.join('=').trim();
+            try {
+                return decodeURIComponent(raw);
+            } catch  {
+                // Malformed percent-encoding must not crash locale detection.
+                return raw;
+            }
+        }
+    }
+    return undefined;
+}

package/dist/i18n/i18n.module.d.ts

@@ -0,0 +1,13 @@
+import type { DynamicModule } from '../module/types';
+import type { I18nModuleOptions } from './i18n.options';
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<I18nModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class I18nModule extends ConfigurableModuleClass {
+    /**
+     * forFeature-style: contribute a message tree (`{ [locale]: { ...messages } }`).
+     * Contributions are collected statically at module-load and deep-merged.
+     */
+    static registerMessages(messages: Record<string, Record<string, unknown>>): DynamicModule;
+}
+export {};

package/dist/i18n/i18n.module.js

@@ -0,0 +1,61 @@
+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 { ConfigurableModuleBuilder } from "../module/configurable-module.builder.js";
+import { stableHash } from "../module/stable-hash.js";
+import { APP_MIDDLEWARE } from "../pipeline/tokens.js";
+import { I18nLocaleMiddleware } from "./i18n.middleware.js";
+import { I18nService } from "./i18n.service.js";
+import { I18N_OPTIONS } from "./i18n.tokens.js";
+import { MessageLoaderService } from "./message-loader.service.js";
+import { MessageRegistry } from "./message-registry.js";
+const { ConfigurableModuleClass } = new ConfigurableModuleBuilder({
+    moduleName: 'I18n',
+    optionsInjectionToken: I18N_OPTIONS
+}).build();
+// Empty marker module for `registerMessages`. The contribution is a side-effect
+// on the global MessageRegistry; this carries NO providers so it never
+// duplicates I18nModule's providers (which would trip vela's multi-instance
+// encapsulation → MultipleProvidersFoundError).
+let I18nMessagesModule = class I18nMessagesModule {
+};
+I18nMessagesModule = _ts_decorate([
+    Module({})
+], I18nMessagesModule);
+export class I18nModule extends ConfigurableModuleClass {
+    /**
+   * forFeature-style: contribute a message tree (`{ [locale]: { ...messages } }`).
+   * Contributions are collected statically at module-load and deep-merged.
+   */ static registerMessages(messages) {
+        MessageRegistry.addMessages(messages);
+        return {
+            module: I18nMessagesModule,
+            key: `messages:${stableHash(messages)}`,
+            providers: []
+        };
+    }
+}
+I18nModule = _ts_decorate([
+    Module({
+        providers: [
+            MessageRegistry,
+            MessageLoaderService,
+            I18nService,
+            I18nLocaleMiddleware,
+            // Register the locale middleware globally (NestJS APP_MIDDLEWARE convention).
+            {
+                provide: APP_MIDDLEWARE,
+                useExisting: I18nLocaleMiddleware
+            }
+        ],
+        exports: [
+            I18nService,
+            MessageLoaderService,
+            I18N_OPTIONS
+        ]
+    })
+], I18nModule);

package/dist/i18n/i18n.options.d.ts

@@ -0,0 +1,30 @@
+/** How the request locale is detected. */
+export type DetectionStrategy = 'header' | 'query' | 'cookie';
+export interface I18nModuleOptions {
+    /** Default locale. @default 'en' */
+    defaultLocale?: string;
+    /** Fallback when a translation is missing. @default defaultLocale */
+    fallbackLocale?: string;
+    /** Supported locales; request locales outside this list fall back to default. @default ['en'] */
+    locales?: string[];
+    /** Locale detection config. */
+    detection?: {
+        /** Set false to disable detection (always use defaultLocale). @default true */
+        enabled?: boolean;
+        /** @default 'header' (Accept-Language) */
+        strategy?: DetectionStrategy;
+        /** Cookie/query parameter name. @default 'locale' */
+        lookupKey?: string;
+    };
+}
+export interface ResolvedI18nOptions {
+    defaultLocale: string;
+    fallbackLocale: string;
+    locales: string[];
+    detection: {
+        enabled: boolean;
+        strategy: DetectionStrategy;
+        lookupKey: string;
+    };
+}
+export declare function resolveI18nOptions(options?: I18nModuleOptions): ResolvedI18nOptions;

package/dist/i18n/i18n.options.js

@@ -0,0 +1,16 @@
+/** How the request locale is detected. */ export function resolveI18nOptions(options) {
+    const detection = options?.detection;
+    const defaultLocale = options?.defaultLocale ?? 'en';
+    return {
+        defaultLocale,
+        fallbackLocale: options?.fallbackLocale ?? defaultLocale,
+        locales: options?.locales ?? [
+            'en'
+        ],
+        detection: {
+            enabled: detection?.enabled !== false,
+            strategy: detection?.strategy ?? 'header',
+            lookupKey: detection?.lookupKey ?? 'locale'
+        }
+    };
+}

package/dist/i18n/i18n.service.d.ts

@@ -0,0 +1,20 @@
+import { type RequestContext } from '../http/request-context';
+import type { I18nModuleOptions } from './i18n.options';
+import type { II18nService } from './i18n.types';
+import { MessageLoaderService } from './message-loader.service';
+/**
+ * Request-scoped translation facade. Reads the locale resolved by
+ * {@link I18nLocaleMiddleware} from the per-request RequestContext.
+ *
+ * Injecting it into a controller/service is safe: vela's request-scope bubbling
+ * promotes the consumer to request scope automatically, so no captive-dependency
+ * hazard and no `ambientContainer` flag required.
+ */
+export declare class I18nService implements II18nService {
+    private readonly loader;
+    private readonly ctx;
+    private readonly options;
+    constructor(loader: MessageLoaderService, ctx: RequestContext, options: I18nModuleOptions);
+    t(key: string, params?: Record<string, unknown>): string;
+    getLocale(): string;
+}

package/dist/i18n/i18n.service.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;
+}
+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 { Scope } from "../constants.js";
+import { Inject, Injectable } from "../container/decorators.js";
+import { REQUEST_CONTEXT } from "../http/request-context.js";
+import { I18N_LOCALE_KEY, I18N_OPTIONS } from "./i18n.tokens.js";
+import { MessageLoaderService } from "./message-loader.service.js";
+export class I18nService {
+    loader;
+    ctx;
+    options;
+    constructor(loader, ctx, options){
+        this.loader = loader;
+        this.ctx = ctx;
+        this.options = options;
+    }
+    t(key, params) {
+        return this.loader.translate(this.getLocale(), key, params);
+    }
+    getLocale() {
+        return this.ctx.get(I18N_LOCALE_KEY) ?? this.options.defaultLocale ?? 'en';
+    }
+}
+I18nService = _ts_decorate([
+    Injectable({
+        scope: Scope.REQUEST
+    }),
+    _ts_param(0, Inject(MessageLoaderService)),
+    _ts_param(1, Inject(REQUEST_CONTEXT)),
+    _ts_param(2, Inject(I18N_OPTIONS)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof MessageLoaderService === "undefined" ? Object : MessageLoaderService,
+        typeof RequestContext === "undefined" ? Object : RequestContext,
+        typeof I18nModuleOptions === "undefined" ? Object : I18nModuleOptions
+    ])
+], I18nService);

package/dist/i18n/i18n.tokens.d.ts

@@ -0,0 +1,6 @@
+import { InjectionToken } from '../container/types';
+import type { I18nModuleOptions } from './i18n.options';
+/** Options bag from `I18nModule.forRoot()` (the ConfigurableModuleBuilder options token). */
+export declare const I18N_OPTIONS: InjectionToken<I18nModuleOptions>;
+/** Key under which the resolved locale is stashed on the per-request RequestContext bag. */
+export declare const I18N_LOCALE_KEY: unique symbol;

package/dist/i18n/i18n.tokens.js

@@ -0,0 +1,3 @@
+import { InjectionToken } from "../container/types.js";
+/** Options bag from `I18nModule.forRoot()` (the ConfigurableModuleBuilder options token). */ export const I18N_OPTIONS = new InjectionToken('I18N_OPTIONS');
+/** Key under which the resolved locale is stashed on the per-request RequestContext bag. */ export const I18N_LOCALE_KEY = Symbol.for('vela:i18n:locale');

package/dist/i18n/i18n.types.d.ts

@@ -0,0 +1,6 @@
+export interface II18nService {
+    /** Translate `key` (dot-path into the message tree) with optional ICU params. */
+    t(key: string, params?: Record<string, unknown>): string;
+    /** The resolved locale for the current request. */
+    getLocale(): string;
+}

package/dist/i18n/i18n.types.js

@@ -0,0 +1 @@
+export { };

package/dist/i18n/index.d.ts

@@ -0,0 +1,10 @@
+export { I18nModule } from './i18n.module';
+export { I18nService } from './i18n.service';
+export { MessageLoaderService } from './message-loader.service';
+export { MessageRegistry } from './message-registry';
+export { I18nLocaleMiddleware } from './i18n.middleware';
+export { I18N_OPTIONS, I18N_LOCALE_KEY } from './i18n.tokens';
+export { resolveI18nOptions } from './i18n.options';
+export { deepMerge } from './deep-merge';
+export type { I18nModuleOptions, ResolvedI18nOptions, DetectionStrategy } from './i18n.options';
+export type { II18nService } from './i18n.types';

package/dist/i18n/index.js

@@ -0,0 +1,8 @@
+export { I18nModule } from "./i18n.module.js";
+export { I18nService } from "./i18n.service.js";
+export { MessageLoaderService } from "./message-loader.service.js";
+export { MessageRegistry } from "./message-registry.js";
+export { I18nLocaleMiddleware } from "./i18n.middleware.js";
+export { I18N_OPTIONS, I18N_LOCALE_KEY } from "./i18n.tokens.js";
+export { resolveI18nOptions } from "./i18n.options.js";
+export { deepMerge } from "./deep-merge.js";

package/dist/i18n/message-loader.service.d.ts

@@ -0,0 +1,21 @@
+import type { I18nModuleOptions } from './i18n.options';
+import { MessageRegistry } from './message-registry';
+/**
+ * Compiles and caches ICU messages (via `intl-messageformat`). Singleton: reads
+ * the merged registry once at construction (all `registerMessages` calls run at
+ * module-load, before providers are instantiated), flattens each locale to
+ * dot-paths, and compiles lazily per locale.
+ */
+export declare class MessageLoaderService {
+    private readonly cache;
+    private readonly compiledCache;
+    private readonly defaultLocale;
+    private readonly fallbackLocale;
+    constructor(registry: MessageRegistry, options: I18nModuleOptions);
+    translate(locale: string, key: string, params?: Record<string, unknown>): string;
+    getAvailableLocales(): string[];
+    isLocaleSupported(locale: string): boolean;
+    getDefaultLocale(): string;
+    private getCompiledMessages;
+    private flattenMessages;
+}

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,18 +21,20 @@ 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, ConfigurableModuleBuilder, defineConfigurableModule, } from './module/index';
+export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport, ConfigurableModuleAsyncOptions, ConfigurableModuleBuilderOptions, ConfigurableModuleClassType, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, ConfigurableModuleOptionsFactory, DefineConfigurableModuleSpec, } from './module/index';
 export type { MiddlewareConsumer, NestModule, RouteInfo } from './http/index';
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
 export type { Plugin } from './plugin/plugin';

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,17 +25,19 @@ 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, ConfigurableModuleBuilder, defineConfigurableModule } from "./module/index.js";
 // Plugin manifest + composer
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators

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

@@ -0,0 +1,44 @@
+import type { DynamicModule } from '../registry/types';
+import type { ConfigurableModuleBuilderOptions, ConfigurableModuleExtras, ConfigurableModuleExtrasTransform, ConfigurableModuleHost, DefineConfigurableModuleSpec } from './configurable-module.types';
+/**
+ * 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 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>;