@velajs/vela 1.15.0 → 1.16.0

package/dist/config/config.module.d.ts

@@ -4,7 +4,14 @@ declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<
     isGlobal?: boolean;
 }>;
 export declare class ConfigModule extends ConfigurableModuleClass {
-    static forRoot<T extends Record<string, unknown>>(options: ConfigModuleOptions<T> & {
+    /**
+     * Preserve (a) per-call generic inference over the flat config record and
+     * (b) the eager-validation contract: `validate` runs at call time so bad
+     * config fails fast, then is stripped so the derived `CONFIG_OPTIONS`
+     * provider is a passthrough (no double validation). `validateSchema` (the
+     * merged-config schema) is deferred to first read — its input needs env.
+     */
+    static forRoot<T extends Record<string, unknown>>(options?: ConfigModuleOptions<T> & {
         isGlobal?: boolean;
         key?: string;
     }): DynamicModule;

package/dist/config/config.module.js

@@ -1,51 +1,98 @@
-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 { Container } from "../container/container.js";
+import { defineModule } from "../module/define-module.js";
 import { ConfigService } from "./config.service.js";
+import { ConfigStore } from "./config.store.js";
 import { CONFIG_OPTIONS } from "./config.tokens.js";
-// MODULE_OPTIONS_TOKEN carries the RAW options; CONFIG_OPTIONS stays the
-// distinct validated-record token, derived in @Module. The derived provider
-// validates the forRootAsync path lazily (its factory is deferred); forRoot
-// validates eagerly at call time (see the override below), matching the
-// long-standing contract, and passes an already-validated config through.
-const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = new ConfigurableModuleBuilder({
-    moduleName: 'Config'
-}).build();
+/**
+ * Carrier for the namespace `asProvider()` KEY providers ONLY. Split out of
+ * ConfigModule and marked `lazy: true` so those factories — which inject
+ * `CONFIG_ENV`, live per-request on edge runtimes — never run at bootstrap.
+ * ConfigModule itself stays EAGER (see below).
+ */ let ConfigNamespacesModule = class ConfigNamespacesModule {
+};
+/**
+ * Build the lazy sub-module holding one KEY provider per namespace. Its `key`
+ * is derived from the owning ConfigModule instance key so multiple ConfigModule
+ * instances get distinct sub-module instances (no import-dedup collision).
+ */ function namespacesSubModule(load, key) {
+    return {
+        module: ConfigNamespacesModule,
+        key: `config-ns:${key}`,
+        lazy: true,
+        providers: load.map((namespace)=>namespace.asProvider()),
+        exports: load.map((namespace)=>namespace.KEY)
+    };
+}
+// Rebuilt on `defineModule` (the blessed engine — CLAUDE.md: changed modules
+// use it). ConfigModule is EAGER: `ConfigService`, `ConfigStore`, and
+// `CONFIG_OPTIONS` construct at bootstrap, so a `forRootAsync` async
+// `useFactory` resolves in the awaited bootstrap pass and a *synchronous*
+// `app.get(ConfigService)` afterwards returns the cached singleton (no drain).
+//
+// ONLY the namespace `asProvider()` KEY providers are deferred — they move into
+// a LAZY sub-module (`ConfigNamespacesModule`) that ConfigModule imports and
+// re-exports. Their factories inject `CONFIG_ENV` (live per-request on edge
+// runtimes), so construction must not happen at bootstrap. `ConfigStore`
+// resolves each KEY through the container on first `get()`; that first
+// resolution claims + sync-drains the sub-module (namespace factories are
+// synchronous, so the sync seam is safe). `resolveAllInstances` treats the KEY
+// tokens as lazy-only (they belong solely to the lazy sub-module) and skips
+// them at bootstrap.
+const { ConfigurableModuleClass } = defineModule({
+    name: 'Config',
+    setup: ({ OPTIONS, options, key })=>{
+        const load = options.load ?? [];
+        const { validateSchema } = options;
+        return {
+            // Lazy sub-module carries the KEY providers; re-exported below so direct
+            // `@Inject(ns.KEY)` and `ConfigStore`'s container lookup both reach them.
+            imports: load.length > 0 ? [
+                namespacesSubModule(load, key)
+            ] : [],
+            providers: [
+                {
+                    // Flat config record. `validate` is applied here for the async path;
+                    // `forRoot` pre-validates eagerly and strips it (see the override).
+                    provide: CONFIG_OPTIONS,
+                    useFactory: (opts)=>opts.validate ? opts.validate(opts.config ?? {}) : opts.config ?? {},
+                    inject: [
+                        OPTIONS
+                    ]
+                },
+                {
+                    // Factory-provided so the store closes over the namespace list +
+                    // schema; it resolves each namespace's KEY lazily via the container.
+                    provide: ConfigStore,
+                    useFactory: (container, config)=>new ConfigStore(container, config, load, validateSchema),
+                    inject: [
+                        Container,
+                        CONFIG_OPTIONS
+                    ]
+                },
+                ConfigService
+            ],
+            exports: [
+                ConfigService,
+                ConfigStore,
+                CONFIG_OPTIONS,
+                ...load.map((n)=>n.KEY)
+            ]
+        };
+    }
+});
 export class ConfigModule extends ConfigurableModuleClass {
-    // Preserve (a) per-call generic inference over the config record and (b) the
-    // eager-validation contract: forRoot validates at call time so bad config
-    // fails fast. `super.forRoot` runs the generated static with `this === ConfigModule`.
-    static forRoot(options) {
-        const validated = options.validate ? options.validate(options.config) : options.config;
-        // Strip `validate` so the derived CONFIG_OPTIONS provider is a passthrough
-        // (no double validation) for the already-validated config.
+    /**
+   * Preserve (a) per-call generic inference over the flat config record and
+   * (b) the eager-validation contract: `validate` runs at call time so bad
+   * config fails fast, then is stripped so the derived `CONFIG_OPTIONS`
+   * provider is a passthrough (no double validation). `validateSchema` (the
+   * merged-config schema) is deferred to first read — its input needs env.
+   */ static forRoot(options = {}) {
+        const validatedConfig = options.validate ? options.validate(options.config ?? {}) : options.config;
         const { validate: _validate, ...rest } = options;
         return super.forRoot({
             ...rest,
-            config: validated
+            config: validatedConfig
         });
     }
 }
-ConfigModule = _ts_decorate([
-    Module({
-        providers: [
-            ConfigService,
-            {
-                provide: CONFIG_OPTIONS,
-                useFactory: (options)=>options.validate ? options.validate(options.config) : options.config,
-                inject: [
-                    MODULE_OPTIONS_TOKEN
-                ]
-            }
-        ],
-        exports: [
-            ConfigService,
-            CONFIG_OPTIONS
-        ]
-    })
-], ConfigModule);

package/dist/config/config.service.d.ts

@@ -1,7 +1,20 @@
+import { ConfigStore } from './config.store';
+import type { ConfigPath, ConfigPathValue } from './config.types';
+/**
+ * Typed, dot-notation reads over the merged config. Stays a singleton (NestJS
+ * parity); delegates to the {@link ConfigStore}. Pass `ConfigType<[...]>` as the
+ * generic to type namespaced paths (`cfg.get('database.url')` → `string`).
+ */
 export declare class ConfigService<T extends Record<string, unknown> = Record<string, unknown>> {
-    private readonly config;
-    constructor(config: T);
-    get<V>(key: string): V | undefined;
-    get<V>(key: string, defaultValue: V): V;
+    private readonly store;
+    constructor(store: ConfigStore);
+    /** Read a config value; `undefined` when absent, or the supplied default. */
+    get<P extends ConfigPath<T>>(path: P): ConfigPathValue<T, P> | undefined;
+    get<P extends ConfigPath<T>>(path: P, defaultValue: ConfigPathValue<T, P>): ConfigPathValue<T, P>;
+    /** Read a config value; throws when the path is absent. */
+    getOrThrow<P extends ConfigPath<T>>(path: P): ConfigPathValue<T, P>;
+    /** Whether a config path resolves to a defined value. */
+    has<P extends ConfigPath<T>>(path: P): boolean;
+    /** The full merged config object (flat record + resolved namespaces). */
     getAll(): T;
 }

package/dist/config/config.service.js

@@ -12,34 +12,32 @@ function _ts_param(paramIndex, decorator) {
         decorator(target, key, paramIndex);
     };
 }
-import { Injectable } from "../container/decorators.js";
-import { Inject } from "../container/decorators.js";
-import { CONFIG_OPTIONS } from "./config.tokens.js";
+import { Injectable, Inject } from "../container/decorators.js";
+import { ConfigStore } from "./config.store.js";
 export class ConfigService {
-    config;
-    constructor(config){
-        this.config = config;
+    store;
+    constructor(store){
+        this.store = store;
     }
-    get(key, defaultValue) {
-        const parts = key.split('.');
-        let current = this.config;
-        for (const part of parts){
-            if (current === null || current === undefined || typeof current !== 'object') {
-                return defaultValue;
-            }
-            current = current[part];
-        }
-        return current ?? defaultValue;
+    get(path, defaultValue) {
+        const value = this.store.get(path);
+        return value === undefined ? defaultValue : value;
     }
-    getAll() {
-        return this.config;
+    /** Read a config value; throws when the path is absent. */ getOrThrow(path) {
+        return this.store.getOrThrow(path);
+    }
+    /** Whether a config path resolves to a defined value. */ has(path) {
+        return this.store.has(path);
+    }
+    /** The full merged config object (flat record + resolved namespaces). */ getAll() {
+        return this.store.all();
     }
 }
 ConfigService = _ts_decorate([
     Injectable(),
-    _ts_param(0, Inject(CONFIG_OPTIONS)),
+    _ts_param(0, Inject(ConfigStore)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof T === "undefined" ? Object : T
+        typeof ConfigStore === "undefined" ? Object : ConfigStore
     ])
 ], ConfigService);

package/dist/config/config.store.d.ts

@@ -0,0 +1,46 @@
+import type { Container } from '../container/container';
+import type { ConfigSchema } from './config.types';
+import type { AnyConfigNamespace } from './register-as';
+/**
+ * Singleton source of truth for merged configuration.
+ *
+ * Holds the flat `config` record plus a `namespace → KEY` map. Namespaces are
+ * resolved LAZILY — the KEY is pulled from the container on the first read of
+ * that namespace and cached — so the store never forces namespace factories to
+ * materialize at construction. Resolution uses the synchronous container seam
+ * (`resolve`), which stays compatible with lazy modules.
+ *
+ * The merged shape is `{ ...config, [ns]: value }` — a namespace shadows a flat
+ * key of the same name.
+ *
+ * Constructed via a factory provider in {@link ConfigModule} so it can close
+ * over the `load` list and `validateSchema` without extra tokens.
+ */
+export declare class ConfigStore {
+    private readonly container;
+    private readonly config;
+    private readonly validateSchema?;
+    private readonly namespaceKeys;
+    private readonly cache;
+    private validated;
+    private validationError;
+    constructor(container: Pick<Container, 'resolve'>, config?: Record<string, unknown>, namespaces?: ReadonlyArray<AnyConfigNamespace>, validateSchema?: ConfigSchema | undefined);
+    /** Read a value by dot-notation path; `undefined` if absent. */
+    get(path: string): unknown;
+    /** Read a value by dot-notation path; throws if absent. */
+    getOrThrow(path: string): unknown;
+    /** Whether a dot-notation path resolves to a defined value. */
+    has(path: string): boolean;
+    /** The full merged config object (flat record + resolved namespaces). */
+    all(): Record<string, unknown>;
+    private read;
+    /** Resolve a namespace's KEY through the container on first use, then cache. */
+    private resolveNamespace;
+    private merged;
+    /**
+     * Validate the merged config once, on first read. Deferred (not at bootstrap)
+     * because the merged shape needs namespace factories — and their env — which
+     * are only available after bootstrap on edge runtimes.
+     */
+    private ensureValidated;
+}

package/dist/config/config.store.js

@@ -0,0 +1,119 @@
+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);
+}
+import { Injectable } from "../container/decorators.js";
+/** Prototype-pollution guard for dot-notation segments. */ const DANGEROUS_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype'
+]);
+function runSchema(schema, config) {
+    if (typeof schema === 'function') {
+        schema(config);
+        return;
+    }
+    if (schema && typeof schema.parse === 'function') {
+        schema.parse(config);
+        return;
+    }
+    throw new Error('ConfigModule `validateSchema` must be a function or expose a `parse()` method');
+}
+export class ConfigStore {
+    container;
+    config;
+    validateSchema;
+    namespaceKeys = new Map();
+    cache = new Map();
+    validated = false;
+    validationError;
+    constructor(container, config = {}, namespaces = [], validateSchema){
+        this.container = container;
+        this.config = config;
+        this.validateSchema = validateSchema;
+        for (const ns of namespaces){
+            this.namespaceKeys.set(ns.namespace, ns.KEY);
+        }
+    }
+    /** Read a value by dot-notation path; `undefined` if absent. */ get(path) {
+        this.ensureValidated();
+        return this.read(path);
+    }
+    /** Read a value by dot-notation path; throws if absent. */ getOrThrow(path) {
+        const value = this.get(path);
+        if (value === undefined) {
+            throw new Error(`Configuration key "${path}" was not found`);
+        }
+        return value;
+    }
+    /** Whether a dot-notation path resolves to a defined value. */ has(path) {
+        this.ensureValidated();
+        return this.read(path) !== undefined;
+    }
+    /** The full merged config object (flat record + resolved namespaces). */ all() {
+        this.ensureValidated();
+        return this.merged();
+    }
+    read(path) {
+        const [head, ...rest] = path.split('.');
+        if (head === undefined || DANGEROUS_KEYS.has(head)) return undefined;
+        let current = this.namespaceKeys.has(head) ? this.resolveNamespace(head) : this.config[head];
+        for (const key of rest){
+            if (DANGEROUS_KEYS.has(key)) return undefined;
+            if (current === null || current === undefined || typeof current !== 'object') {
+                return undefined;
+            }
+            current = current[key];
+        }
+        return current;
+    }
+    /** Resolve a namespace's KEY through the container on first use, then cache. */ resolveNamespace(namespace) {
+        if (this.cache.has(namespace)) return this.cache.get(namespace);
+        const key = this.namespaceKeys.get(namespace);
+        const value = key === undefined ? undefined : this.container.resolve(key);
+        this.cache.set(namespace, value);
+        return value;
+    }
+    merged() {
+        const out = {
+            ...this.config
+        };
+        for (const namespace of this.namespaceKeys.keys()){
+            out[namespace] = this.resolveNamespace(namespace);
+        }
+        return out;
+    }
+    /**
+   * Validate the merged config once, on first read. Deferred (not at bootstrap)
+   * because the merged shape needs namespace factories — and their env — which
+   * are only available after bootstrap on edge runtimes.
+   */ ensureValidated() {
+        if (this.validated) {
+            if (this.validationError) throw this.validationError; // fail-closed on every read
+            return;
+        }
+        this.validated = true; // run the schema exactly once
+        if (!this.validateSchema) return;
+        try {
+            runSchema(this.validateSchema, this.merged());
+        } catch (err) {
+            this.validationError = err;
+            throw err;
+        }
+    }
+}
+ConfigStore = _ts_decorate([
+    Injectable(),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Pick === "undefined" ? Object : Pick,
+        typeof Record === "undefined" ? Object : Record,
+        typeof ReadonlyArray === "undefined" ? Object : ReadonlyArray,
+        typeof ConfigSchema === "undefined" ? Object : ConfigSchema
+    ])
+], ConfigStore);

package/dist/config/config.tokens.d.ts

@@ -1,2 +1,13 @@
 import { InjectionToken } from '../container/types';
 export declare const CONFIG_OPTIONS: InjectionToken<Record<string, unknown>>;
+/**
+ * Ambient environment record consumed by config-namespace factories
+ * (`registerAs`). It is the multi-runtime substitute for stratal's
+ * Cloudflare-specific `env` token: core never touches `process.env`.
+ *
+ * The token self-provides `{}` by default (so factories resolve even with no
+ * platform binding), and stays OVERRIDABLE — a platform adapter
+ * (`@velajs/cloudflare`) or a future `./config-node` subpath provides a global
+ * `CONFIG_ENV` and that registration wins over the default.
+ */
+export declare const CONFIG_ENV: InjectionToken<Record<string, unknown>>;

package/dist/config/config.tokens.js

@@ -1,2 +1,14 @@
 import { InjectionToken } from "../container/types.js";
 export const CONFIG_OPTIONS = new InjectionToken('CONFIG_OPTIONS');
+/**
+ * Ambient environment record consumed by config-namespace factories
+ * (`registerAs`). It is the multi-runtime substitute for stratal's
+ * Cloudflare-specific `env` token: core never touches `process.env`.
+ *
+ * The token self-provides `{}` by default (so factories resolve even with no
+ * platform binding), and stays OVERRIDABLE — a platform adapter
+ * (`@velajs/cloudflare`) or a future `./config-node` subpath provides a global
+ * `CONFIG_ENV` and that registration wins over the default.
+ */ export const CONFIG_ENV = new InjectionToken('CONFIG_ENV', {
+    factory: ()=>({})
+});

package/dist/config/config.types.d.ts

@@ -1,5 +1,41 @@
+import type { AnyConfigNamespace } from './register-as';
+/**
+ * A schema for validating the fully-merged config. Kept structural so zod stays
+ * an OPTIONAL peer — a zod schema (has `.parse`) or a plain function both work;
+ * core never imports zod. Throwing rejects the config.
+ */
+export type ConfigSchema = ((config: Record<string, unknown>) => unknown) | {
+    parse: (config: unknown) => unknown;
+};
+/**
+ * Options for {@link ConfigModule}.
+ *
+ * NOTE: `load` and `validateSchema` are **`forRoot`-only** — they are read
+ * structurally from the call-time options bag. On the `forRootAsync` path the
+ * options come from a DI-resolved factory, so only the flat `config` record is
+ * supported there (async namespaces are out of scope; declare them via
+ * `forRoot`).
+ */
 export interface ConfigModuleOptions<T extends Record<string, unknown> = Record<string, unknown>> {
-    config: T;
+    /** Flat config record — the pre-namespace `config` path (still supported). */
+    config?: T;
+    /** Config namespaces created via `registerAs()`, merged under their namespace name. `forRoot`-only. */
+    load?: AnyConfigNamespace[];
+    /** Eager validator for the flat `config` record; runs at `forRoot()` call time. */
     validate?: (config: T) => T;
+    /** Schema validating the MERGED config (flat + namespaces); runs lazily on first read. `forRoot`-only. */
+    validateSchema?: ConfigSchema;
     isGlobal?: boolean;
 }
+/**
+ * All valid dot-notation paths of a config object type.
+ * @example `ConfigPath<{ database: { url: string } }>` → `'database' | 'database.url'`
+ */
+export type ConfigPath<T> = {
+    [K in keyof T & string]: T[K] extends Record<string, unknown> ? K | `${K}.${ConfigPath<T[K]>}` : K;
+}[keyof T & string];
+/**
+ * The value type at a dot-notation path.
+ * @example `ConfigPathValue<{ database: { url: string } }, 'database.url'>` → `string`
+ */
+export type ConfigPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? T[K] extends Record<string, unknown> ? ConfigPathValue<T[K], Rest> : never : never : P extends keyof T ? T[P] : never;

package/dist/config/config.types.js

@@ -1 +1,4 @@
-export { };
+/**
+ * The value type at a dot-notation path.
+ * @example `ConfigPathValue<{ database: { url: string } }, 'database.url'>` → `string`
+ */ export { };

package/dist/config/index.d.ts

@@ -1,4 +1,7 @@
 export { ConfigModule } from './config.module';
 export { ConfigService } from './config.service';
-export { CONFIG_OPTIONS } from './config.tokens';
-export type { ConfigModuleOptions } from './config.types';
+export { ConfigStore } from './config.store';
+export { CONFIG_OPTIONS, CONFIG_ENV } from './config.tokens';
+export { registerAs } from './register-as';
+export type { ConfigNamespace, AnyConfigNamespace, InferConfigType, ConfigType } from './register-as';
+export type { ConfigModuleOptions, ConfigSchema, ConfigPath, ConfigPathValue } from './config.types';

package/dist/config/index.js

@@ -1,3 +1,5 @@
 export { ConfigModule } from "./config.module.js";
 export { ConfigService } from "./config.service.js";
-export { CONFIG_OPTIONS } from "./config.tokens.js";
+export { ConfigStore } from "./config.store.js";
+export { CONFIG_OPTIONS, CONFIG_ENV } from "./config.tokens.js";
+export { registerAs } from "./register-as.js";

package/dist/config/register-as.d.ts

@@ -0,0 +1,52 @@
+import type { InjectionToken, ProviderOptions } from '../container/types';
+/**
+ * The result of {@link registerAs}: a namespaced config factory plus the DI
+ * token it is provided under.
+ */
+export interface ConfigNamespace<TKey extends string = string, TEnv = Record<string, unknown>, TConfig extends object = object> {
+    /** Injection token for this namespace's resolved config (`Symbol.for('vela:config:<ns>')`). */
+    readonly KEY: InjectionToken<TConfig>;
+    /** The namespace name (e.g. `'database'`). */
+    readonly namespace: TKey;
+    /** Factory receiving the ambient env and returning the namespace config. */
+    readonly factory: (env: TEnv) => TConfig;
+    /** Provider registration injecting {@link CONFIG_ENV} — spread into a module's providers. */
+    asProvider(): ProviderOptions<TConfig>;
+}
+/** Any config namespace — structural typing for the module `load` list. */
+export type AnyConfigNamespace = ConfigNamespace<string, any, object>;
+/**
+ * Create a namespaced configuration factory (NestJS `registerAs` parity).
+ *
+ * The `KEY` is minted with `Symbol.for` so it keeps a stable identity across
+ * module re-evaluation (HMR / repeated imports) — a fresh `InjectionToken`
+ * would mint a new identity each eval and break dedup. It is typed as
+ * `InjectionToken<TConfig>` purely for injection-site DX.
+ *
+ * @example
+ * ```ts
+ * export const dbConfig = registerAs('database', (env: Env) => ({
+ *   url: env.DATABASE_URL,
+ *   pool: 10,
+ * }));
+ * // ConfigModule.forRoot({ load: [dbConfig] });
+ * // cfg.get('database.url');                              // via ConfigService
+ * // constructor(@Inject(dbConfig.KEY) db: InferConfigType<typeof dbConfig>) {}
+ * ```
+ */
+export declare function registerAs<TKey extends string, TEnv, TConfig extends object>(namespace: TKey, factory: (env: TEnv) => TConfig): ConfigNamespace<TKey, TEnv, TConfig>;
+/**
+ * Extract a namespace's config shape from a {@link registerAs} result.
+ *
+ * @example `type Db = InferConfigType<typeof dbConfig>` → `{ url: string; pool: number }`
+ */
+export type InferConfigType<T> = T extends ConfigNamespace<string, any, infer C> ? C : never;
+/**
+ * Zero-codegen typed config shape from a tuple of namespaces — pass as the
+ * `ConfigService` generic to type dot-notation reads.
+ *
+ * @example `ConfigService<ConfigType<[typeof dbConfig, typeof mailConfig]>>`
+ */
+export type ConfigType<L extends readonly AnyConfigNamespace[]> = {
+    [N in L[number] as N['namespace']]: InferConfigType<N>;
+};

package/dist/config/register-as.js

@@ -0,0 +1,39 @@
+// Config-namespace registration. Design ported from stratal's `registerAs`
+// (MIT, © Temitayo Fadojutimi) and reworked for vela's multi-runtime DI: env
+// enters through the `CONFIG_ENV` token instead of a Cloudflare-specific one.
+import { CONFIG_ENV } from "./config.tokens.js";
+/**
+ * Create a namespaced configuration factory (NestJS `registerAs` parity).
+ *
+ * The `KEY` is minted with `Symbol.for` so it keeps a stable identity across
+ * module re-evaluation (HMR / repeated imports) — a fresh `InjectionToken`
+ * would mint a new identity each eval and break dedup. It is typed as
+ * `InjectionToken<TConfig>` purely for injection-site DX.
+ *
+ * @example
+ * ```ts
+ * export const dbConfig = registerAs('database', (env: Env) => ({
+ *   url: env.DATABASE_URL,
+ *   pool: 10,
+ * }));
+ * // ConfigModule.forRoot({ load: [dbConfig] });
+ * // cfg.get('database.url');                              // via ConfigService
+ * // constructor(@Inject(dbConfig.KEY) db: InferConfigType<typeof dbConfig>) {}
+ * ```
+ */ export function registerAs(namespace, factory) {
+    const KEY = Symbol.for(`vela:config:${namespace}`);
+    return {
+        KEY,
+        namespace,
+        factory,
+        asProvider () {
+            return {
+                provide: KEY,
+                useFactory: factory,
+                inject: [
+                    CONFIG_ENV
+                ]
+            };
+        }
+    };
+}

package/dist/{storage → crypto}/signed-url.js

@@ -1,6 +1,11 @@
 // Signed-URL utilities using HMAC-SHA256 via the Web Crypto API (edge-safe;
 // no node:crypto). Verification uses crypto.subtle.verify for timing-safety.
 // Pattern: https://developers.cloudflare.com/workers/examples/signing-requests/
+//
+// This is the canonical home for the util. `@velajs/vela/storage` re-exports it
+// (see src/storage/index.ts) so the storage subpath API is unchanged, while
+// core (the URL generator + signed-URL guard) imports it here directly — core
+// never reaches into a published subpath.
 async function importKey(secret) {
     return crypto.subtle.importKey('raw', new TextEncoder().encode(secret), {
         name: 'HMAC',

package/dist/factory/bootstrap.js

@@ -4,6 +4,8 @@ import { ModuleRef } from "../container/module-ref.js";
 import { DiscoveryService } from "../discovery/discovery.service.js";
 import { REQUEST_CONTEXT } from "../http/request-context.js";
 import { RouteManager } from "../http/route.manager.js";
+import { UrlGeneratorService } from "../http/url/url-generator.service.js";
+import { SignedUrlGuard } from "../http/url/signed-url.guard.js";
 import { ModuleLoader } from "../module/module-loader.js";
 import { bindAppProviders } from "../pipeline/app-providers.js";
 import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
@@ -70,6 +72,14 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
         useValue: routeManager
     });
     container.markGlobalToken(RouteManager);
+    // Named-route URL generation + signed-URL verification are app-level
+    // singletons: injectable from any module, and (for the guard) instantiable by
+    // the pipeline when a route opts in via `@SignedUrl()`. Both read their secret
+    // lazily and never force controllers/lazy modules to materialize.
+    container.register(UrlGeneratorService);
+    container.markGlobalToken(UrlGeneratorService);
+    container.register(SignedUrlGuard);
+    container.markGlobalToken(SignedUrlGuard);
     const loader = new ModuleLoader(container, routeManager);
     // loader.load() also arms the deferred-init seam (LazyModuleManager) — kept
     // inside the loader so hand-rolled bootstrap paths that never call this

package/dist/http/decorators.d.ts

@@ -31,15 +31,24 @@ export declare function Controller(pathOrOptions?: string | ControllerOptions):
  */
 export declare function Version(version: number | number[]): MethodDecorator;
 export declare function getRouteVersion(target: Constructor, propertyKey: string | symbol): number | number[] | undefined;
-export declare const Get: (path?: string) => MethodDecorator;
-export declare const Post: (path?: string) => MethodDecorator;
-export declare const Put: (path?: string) => MethodDecorator;
-export declare const Patch: (path?: string) => MethodDecorator;
-export declare const Delete: (path?: string) => MethodDecorator;
-export declare const Options: (path?: string) => MethodDecorator;
-export declare const Head: (path?: string) => MethodDecorator;
-export declare const All: (path?: string) => MethodDecorator;
-export declare const Sse: (path?: string) => MethodDecorator;
+/** Per-route options for the HTTP method decorators (`@Get`, `@Post`, …). */
+export interface RouteOptions {
+    /**
+     * A stable, human-readable name for this route. Enables URL generation
+     * (`UrlGeneratorService.urlFor(name, …)`), surfaces on `app.describeRoutes()`,
+     * and — when set — becomes the OpenAPI `operationId`.
+     */
+    name?: string;
+}
+export declare const Get: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Post: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Put: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Patch: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Delete: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Options: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Head: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const All: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Sse: (path?: string, options?: RouteOptions) => MethodDecorator;
 export declare const Param: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;
 export declare const Query: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;
 export declare const Body: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;

package/dist/http/decorators.js

@@ -57,7 +57,7 @@ export function getRouteVersion(target, propertyKey) {
     return MetadataRegistry.getRouteVersion(target, propertyKey);
 }
 function createMethodDecorator(method) {
-    return (path = '')=>{
+    return (path = '', options)=>{
         return (target, propertyKey, _descriptor)=>{
             const ctor = target.constructor;
             const normalizedPath = normalizePath(path);
@@ -68,6 +68,9 @@ function createMethodDecorator(method) {
                 handlerName: propertyKey,
                 ...version !== undefined ? {
                     version
+                } : {},
+                ...options?.name !== undefined ? {
+                    name: options.name
                 } : {}
             });
         };

package/dist/http/index.d.ts

@@ -3,6 +3,10 @@ export type { RouteManagerOptions } from './route.manager';
 export { MiddlewareBuilder } from '../module/middleware';
 export type { MiddlewareConsumer, MiddlewareConfigProxy, RouteInfo, NestModule, MiddlewareRouteDefinition } from '../module/middleware';
 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, applyDecorators, isController, } from './decorators';
+export type { RouteOptions } from './decorators';
 export { createLazyParamDecorator } from './lazy-param.decorator';
+export { UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET, } from './url/index';
+export type { UrlForOptions, SignedUrlGenerateOptions } from './url/index';
+export type { VelaRouteMap, RouteName, RouteParams } from './route-map';
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext, } from './ambient';
 export type { RouteMetadata, ControllerMetadata, ControllerOptions, ParamMetadata, ControllerRegistration, } from './types';

package/dist/http/index.js

@@ -2,4 +2,6 @@ export { RouteManager } from "./route.manager.js";
 export { MiddlewareBuilder } from "../module/middleware.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, applyDecorators, isController } from "./decorators.js";
 export { createLazyParamDecorator } from "./lazy-param.decorator.js";
+// Named-route URL generation + signed URLs
+export { UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET } from "./url/index.js";
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext } from "./ambient.js";

package/dist/http/route-map.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Augmentable map of route name → its path params. Users opt in to type-safe
+ * URL generation by augmenting this interface — no build step, no codegen:
+ *
+ * ```ts
+ * declare module '@velajs/vela' {
+ *   interface VelaRouteMap {
+ *     'users.index': Record<string, never>;
+ *     'users.show': { id: string };
+ *   }
+ * }
+ * ```
+ *
+ * Until augmented it stays empty, so `RouteName` falls back to `string` and
+ * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
+ * callers keep working unchanged.
+ */
+export interface VelaRouteMap {
+}
+/**
+ * Every valid route name. Falls back to `string` when `VelaRouteMap` has not
+ * been augmented, so `urlFor`/`signedUrl` accept any name in an untyped app.
+ */
+export type RouteName = keyof VelaRouteMap extends never ? string : Extract<keyof VelaRouteMap, string>;
+/**
+ * The params object required to build a named route's URL. When `VelaRouteMap`
+ * is augmented, resolves to the declared params shape for `N`; otherwise a
+ * loose `Record<string, string> | undefined`.
+ */
+export type RouteParams<N extends RouteName> = N extends keyof VelaRouteMap ? VelaRouteMap[N] : Record<string, string> | undefined;

package/dist/http/route-map.js

@@ -0,0 +1,27 @@
+// Zero-codegen, type-safe route names — mirrors the augmentation pattern from
+// stratal `packages/core/src/router/route-map.ts` (MIT © Temitayo Fadojutimi).
+// Adapted for vela: `VelaRouteMap` maps a route name directly to its params
+// object (stratal wraps params in `{ params: … }`; vela keeps it flat to match
+// the `urlFor(name, params)` call shape).
+/**
+ * Augmentable map of route name → its path params. Users opt in to type-safe
+ * URL generation by augmenting this interface — no build step, no codegen:
+ *
+ * ```ts
+ * declare module '@velajs/vela' {
+ *   interface VelaRouteMap {
+ *     'users.index': Record<string, never>;
+ *     'users.show': { id: string };
+ *   }
+ * }
+ * ```
+ *
+ * Until augmented it stays empty, so `RouteName` falls back to `string` and
+ * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
+ * callers keep working unchanged.
+ */ // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentable interface, intentionally empty until a consumer declares routes
+/**
+ * The params object required to build a named route's URL. When `VelaRouteMap`
+ * is augmented, resolves to the declared params shape for `N`; otherwise a
+ * loose `Record<string, string> | undefined`.
+ */ export { };

package/dist/http/route.manager.d.ts

@@ -21,6 +21,8 @@ export interface RouteDescription {
     controller: string;
     handler: string;
     version?: number;
+    /** Route name (`@Get(path, { name })`) — the URL-generation / `operationId` key. */
+    name?: string;
 }
 export interface RouteManagerOptions {
     getClientIp?: (c: Context) => string | null;

package/dist/http/route.manager.js

@@ -388,7 +388,10 @@ export class RouteManager {
                             path: fullPath || '/',
                             controller: controller.name,
                             handler: String(route.handlerName),
-                            version: versionsForPaths[pathIndex]
+                            version: versionsForPaths[pathIndex],
+                            ...route.name !== undefined ? {
+                                name: route.name
+                            } : {}
                         });
                     }
                 }

package/dist/http/types.d.ts

@@ -6,6 +6,8 @@ export interface RouteMetadata {
     path: string;
     handlerName: string | symbol;
     version?: number | number[];
+    /** Route name for URL generation / OpenAPI operationId (`@Get(path, { name })`). */
+    name?: string;
 }
 export interface ControllerOptions {
     path?: string;

package/dist/http/url/index.d.ts

@@ -0,0 +1,4 @@
+export { UrlGeneratorService } from './url-generator.service';
+export type { UrlForOptions, SignedUrlGenerateOptions } from './url-generator.service';
+export { SignedUrlGuard, SignedUrl } from './signed-url.guard';
+export { URL_SIGNING_SECRET } from './signing-secret';

package/dist/http/url/index.js

@@ -0,0 +1,3 @@
+export { UrlGeneratorService } from "./url-generator.service.js";
+export { SignedUrlGuard, SignedUrl } from "./signed-url.guard.js";
+export { URL_SIGNING_SECRET } from "./signing-secret.js";

package/dist/http/url/signed-url.guard.d.ts

@@ -0,0 +1,27 @@
+import { applyDecorators } from '../decorators';
+import type { CanActivate, ExecutionContext } from '../../pipeline/types';
+/**
+ * Verifies the HMAC signature (and `expires`) of the incoming request URL,
+ * using the same secret source as {@link UrlGeneratorService.signedUrl}: the
+ * {@link URL_SIGNING_SECRET} token, else `CONFIG_ENV`. Throws
+ * `ForbiddenException` (403) when the signature is missing, tampered, or
+ * expired. Registered app-wide by `bootstrap`; apply it per-route with
+ * {@link SignedUrl}.
+ */
+export declare class SignedUrlGuard implements CanActivate {
+    private readonly secretToken?;
+    private readonly env;
+    constructor(secretToken?: string | undefined, env?: Record<string, unknown>);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+/**
+ * Guards a route with {@link SignedUrlGuard} — the request must carry a valid,
+ * unexpired HMAC signature (produced by `UrlGeneratorService.signedUrl`).
+ *
+ * ```ts
+ * @Get('download', { name: 'file.download' })
+ * @SignedUrl()
+ * download() { ... }
+ * ```
+ */
+export declare function SignedUrl(): ReturnType<typeof applyDecorators>;

package/dist/http/url/signed-url.guard.js

@@ -0,0 +1,62 @@
+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 { Injectable, Inject, Optional } from "../../container/decorators.js";
+import { CONFIG_ENV } from "../../config/config.tokens.js";
+import { verifySignedUrl } from "../../crypto/signed-url.js";
+import { ForbiddenException } from "../../errors/http-exception.js";
+import { applyDecorators } from "../decorators.js";
+import { UseGuards } from "../../pipeline/decorators.js";
+import { URL_SIGNING_SECRET, resolveSigningSecret } from "./signing-secret.js";
+export class SignedUrlGuard {
+    secretToken;
+    env;
+    constructor(secretToken, env = {}){
+        this.secretToken = secretToken;
+        this.env = env;
+    }
+    async canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        const secret = resolveSigningSecret(undefined, this.secretToken, this.env);
+        const valid = await verifySignedUrl(request.url, secret);
+        if (!valid) {
+            throw new ForbiddenException('Invalid or expired signed URL');
+        }
+        return true;
+    }
+}
+SignedUrlGuard = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Optional()),
+    _ts_param(0, Inject(URL_SIGNING_SECRET)),
+    _ts_param(1, Optional()),
+    _ts_param(1, Inject(CONFIG_ENV)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        String,
+        typeof Record === "undefined" ? Object : Record
+    ])
+], SignedUrlGuard);
+/**
+ * Guards a route with {@link SignedUrlGuard} — the request must carry a valid,
+ * unexpired HMAC signature (produced by `UrlGeneratorService.signedUrl`).
+ *
+ * ```ts
+ * @Get('download', { name: 'file.download' })
+ * @SignedUrl()
+ * download() { ... }
+ * ```
+ */ export function SignedUrl() {
+    return applyDecorators(UseGuards(SignedUrlGuard));
+}

package/dist/http/url/signing-secret.d.ts

@@ -0,0 +1,20 @@
+import { InjectionToken } from '../../container/types';
+/**
+ * Optional DI token holding the HMAC secret used to sign / verify URLs. Provide
+ * it globally (e.g. from a platform adapter or a `@Global` module) so both
+ * {@link UrlGeneratorService} and the signed-URL guard can read it:
+ *
+ * ```ts
+ * { provide: URL_SIGNING_SECRET, useValue: env.URL_SIGNING_SECRET }
+ * ```
+ */
+export declare const URL_SIGNING_SECRET: InjectionToken<string>;
+/** Key read from `CONFIG_ENV` when no explicit secret / token is available. */
+export declare const URL_SIGNING_SECRET_ENV_KEY = "URL_SIGNING_SECRET";
+/**
+ * Resolve the signing secret from, in order: an explicit argument, the
+ * {@link URL_SIGNING_SECRET} token, then `CONFIG_ENV[URL_SIGNING_SECRET]`.
+ * Throws a descriptive error when none is available — signing must never fall
+ * back to an empty/implicit key.
+ */
+export declare function resolveSigningSecret(explicit: string | undefined, token: string | undefined, env: Record<string, unknown> | undefined): string;

package/dist/http/url/signing-secret.js

@@ -0,0 +1,24 @@
+import { InjectionToken } from "../../container/types.js";
+/**
+ * Optional DI token holding the HMAC secret used to sign / verify URLs. Provide
+ * it globally (e.g. from a platform adapter or a `@Global` module) so both
+ * {@link UrlGeneratorService} and the signed-URL guard can read it:
+ *
+ * ```ts
+ * { provide: URL_SIGNING_SECRET, useValue: env.URL_SIGNING_SECRET }
+ * ```
+ */ export const URL_SIGNING_SECRET = new InjectionToken('URL_SIGNING_SECRET');
+/** Key read from `CONFIG_ENV` when no explicit secret / token is available. */ export const URL_SIGNING_SECRET_ENV_KEY = 'URL_SIGNING_SECRET';
+/**
+ * Resolve the signing secret from, in order: an explicit argument, the
+ * {@link URL_SIGNING_SECRET} token, then `CONFIG_ENV[URL_SIGNING_SECRET]`.
+ * Throws a descriptive error when none is available — signing must never fall
+ * back to an empty/implicit key.
+ */ export function resolveSigningSecret(explicit, token, env) {
+    const fromEnv = env?.[URL_SIGNING_SECRET_ENV_KEY];
+    const secret = explicit ?? token ?? (typeof fromEnv === 'string' ? fromEnv : undefined);
+    if (!secret) {
+        throw new Error('No URL signing secret is available. Pass one explicitly, register a ' + '`URL_SIGNING_SECRET` provider, or set `URL_SIGNING_SECRET` in `CONFIG_ENV`.');
+    }
+    return secret;
+}

package/dist/http/url/url-generator.service.d.ts

@@ -0,0 +1,52 @@
+import { RouteManager } from '../route.manager';
+import type { RouteName, RouteParams } from '../route-map';
+/** Value accepted for a path param or query entry. */
+type UrlParamValue = string | number | boolean;
+/** Extra options for {@link UrlGeneratorService.urlFor}. */
+export interface UrlForOptions {
+    /** Additional query-string entries merged after any leftover params. */
+    query?: Record<string, UrlParamValue>;
+}
+/** Options for {@link UrlGeneratorService.signedUrl}. */
+export interface SignedUrlGenerateOptions {
+    /** Time-to-live in seconds; enforced on verification via the `expires` param. */
+    expiresIn?: number;
+    /** Override the signing secret (else the `URL_SIGNING_SECRET` token / `CONFIG_ENV`). */
+    secret?: string;
+}
+/**
+ * Builds URLs for named routes (Laravel-flavoured `route()` ergonomics).
+ *
+ * Route descriptions are read LAZILY from the {@link RouteManager} on first use
+ * — post-build, so composition (global prefix + version + controller prefix) is
+ * already baked into each path — and it never instantiates controllers, so it
+ * plays nicely with lazy modules. Registered as an app-level singleton by
+ * `bootstrap`, so it is injectable anywhere.
+ */
+export declare class UrlGeneratorService {
+    private readonly routeManager;
+    private readonly secretToken?;
+    private readonly env;
+    private routeMap;
+    constructor(routeManager: RouteManager, secretToken?: string | undefined, env?: Record<string, unknown>);
+    /**
+     * Build the path for a named route, filling `:param` placeholders from
+     * `params`. Params that don't match a placeholder become query-string
+     * entries; `opts.query` is merged after them.
+     *
+     * @throws if no route carries `name`, or a required `:param` is missing.
+     */
+    urlFor<N extends RouteName>(name: N, params?: RouteParams<N>, opts?: UrlForOptions): string;
+    /**
+     * Build a named-route URL and HMAC-sign it (path + query). The secret comes
+     * from `options.secret`, else the {@link URL_SIGNING_SECRET} token, else
+     * `CONFIG_ENV`; a descriptive error is thrown when none is available.
+     */
+    signedUrl<N extends RouteName>(name: N, params?: RouteParams<N>, options?: SignedUrlGenerateOptions): Promise<string>;
+    /**
+     * Lazily index named route descriptions. Rebuilt while empty (routes may not
+     * be built yet), cached once populated.
+     */
+    private routes;
+}
+export {};

package/dist/http/url/url-generator.service.js

@@ -0,0 +1,104 @@
+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 { Injectable, Inject, Optional } from "../../container/decorators.js";
+import { CONFIG_ENV } from "../../config/config.tokens.js";
+import { signUrl } from "../../crypto/signed-url.js";
+import { RouteManager } from "../route.manager.js";
+import { URL_SIGNING_SECRET, resolveSigningSecret } from "./signing-secret.js";
+export class UrlGeneratorService {
+    routeManager;
+    secretToken;
+    env;
+    routeMap = null;
+    constructor(routeManager, secretToken, env = {}){
+        this.routeManager = routeManager;
+        this.secretToken = secretToken;
+        this.env = env;
+    }
+    /**
+   * Build the path for a named route, filling `:param` placeholders from
+   * `params`. Params that don't match a placeholder become query-string
+   * entries; `opts.query` is merged after them.
+   *
+   * @throws if no route carries `name`, or a required `:param` is missing.
+   */ urlFor(name, params, opts) {
+        const description = this.routes().get(name);
+        if (!description) {
+            throw new Error(`No route named "${String(name)}" was found. Give the route a name ` + `via \`@Get(path, { name: '${String(name)}' })\`.`);
+        }
+        const provided = {
+            ...params ?? {}
+        };
+        const consumed = new Set();
+        const path = description.path.replace(/:([A-Za-z0-9_]+)/g, (_match, key)=>{
+            const value = provided[key];
+            if (value === undefined || value === null) {
+                throw new Error(`Missing route param "${key}" for route "${String(name)}".`);
+            }
+            consumed.add(key);
+            return encodeURIComponent(String(value));
+        });
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(provided)){
+            if (consumed.has(key) || value === undefined || value === null) continue;
+            query.set(key, String(value));
+        }
+        for (const [key, value] of Object.entries(opts?.query ?? {})){
+            if (value === undefined || value === null) continue;
+            query.set(key, String(value));
+        }
+        const qs = query.toString();
+        return qs ? `${path}?${qs}` : path;
+    }
+    /**
+   * Build a named-route URL and HMAC-sign it (path + query). The secret comes
+   * from `options.secret`, else the {@link URL_SIGNING_SECRET} token, else
+   * `CONFIG_ENV`; a descriptive error is thrown when none is available.
+   */ async signedUrl(name, params, options = {}) {
+        const url = this.urlFor(name, params);
+        const secret = resolveSigningSecret(options.secret, this.secretToken, this.env);
+        return signUrl(url, secret, options.expiresIn !== undefined ? {
+            expiresIn: options.expiresIn
+        } : undefined);
+    }
+    /**
+   * Lazily index named route descriptions. Rebuilt while empty (routes may not
+   * be built yet), cached once populated.
+   */ routes() {
+        if (this.routeMap && this.routeMap.size > 0) return this.routeMap;
+        const map = new Map();
+        for (const description of this.routeManager.getRouteDescriptions()){
+            if (description.name && !map.has(description.name)) {
+                map.set(description.name, description);
+            }
+        }
+        this.routeMap = map;
+        return map;
+    }
+}
+UrlGeneratorService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(RouteManager)),
+    _ts_param(1, Optional()),
+    _ts_param(1, Inject(URL_SIGNING_SECRET)),
+    _ts_param(2, Optional()),
+    _ts_param(2, Inject(CONFIG_ENV)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof RouteManager === "undefined" ? Object : RouteManager,
+        String,
+        typeof Record === "undefined" ? Object : Record
+    ])
+], UrlGeneratorService);

package/dist/index.d.ts

@@ -10,14 +10,17 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './container/index';
 export type { RouteDescription } from './http/route.manager';
 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 { 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, UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET, } from './http/index';
+export type { RouteOptions, UrlForOptions, SignedUrlGenerateOptions, VelaRouteMap, RouteName, RouteParams, } from './http/index';
+export { signUrl, verifySignedUrl } from './crypto/signed-url';
+export type { SignedUrlOptions } from './crypto/signed-url';
 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';
-export type { ConfigModuleOptions } from './config/index';
+export { ConfigModule, ConfigService, ConfigStore, CONFIG_OPTIONS, CONFIG_ENV, registerAs, } from './config/index';
+export type { ConfigModuleOptions, ConfigSchema, ConfigNamespace, AnyConfigNamespace, InferConfigType, ConfigType, ConfigPath, ConfigPathValue, } from './config/index';
 export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } from './fetch/index';
 export type { HttpModuleOptions, HttpResponse, HttpRequestConfig } from './fetch/index';
 export { CorsModule, CORS_OPTIONS } from './cors/index';

package/dist/index.js

@@ -11,7 +11,9 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
-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";
+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, UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET } from "./http/index.js";
+// Edge-safe HMAC signed-URL primitives (also re-exported from `@velajs/vela/storage`)
+export { signUrl, verifySignedUrl } from "./crypto/signed-url.js";
 // Request-scoped context primitive
 export { REQUEST_CONTEXT } from "./http/request-context.js";
 // Opt-in ambient container access (ALS via hono/context-storage)
@@ -19,7 +21,7 @@ export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext }
 // Services
 export { Logger, LogLevel } from "./services/index.js";
 // Config
-export { ConfigModule, ConfigService, CONFIG_OPTIONS } from "./config/index.js";
+export { ConfigModule, ConfigService, ConfigStore, CONFIG_OPTIONS, CONFIG_ENV, registerAs } from "./config/index.js";
 // HTTP Client
 export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } from "./fetch/index.js";
 // CORS

package/dist/openapi/document.js

@@ -182,7 +182,8 @@ function buildOperation(controller, route, pathString, registry) {
     if (requestBody) operation.requestBody = requestBody;
     if (docMeta?.summary) operation.summary = docMeta.summary;
     if (docMeta?.description) operation.description = docMeta.description;
-    if (docMeta?.operationId) operation.operationId = docMeta.operationId;
+    const operationId = docMeta?.operationId ?? route.name;
+    if (operationId) operation.operationId = operationId;
     if (docMeta?.deprecated) operation.deprecated = docMeta.deprecated;
     if (mergedTags.length > 0) operation.tags = mergedTags;
     return operation;

package/dist/registry/types.d.ts

@@ -21,6 +21,8 @@ export interface RouteDefinition {
     path: string;
     handlerName: string | symbol;
     version?: number | number[];
+    /** Route name for URL generation / OpenAPI operationId (`@Get(path, { name })`). */
+    name?: string;
 }
 export interface ParameterMetadata {
     index: number;

package/dist/storage/index.d.ts

@@ -1,4 +1,4 @@
-export { signUrl, verifySignedUrl } from './signed-url';
-export type { SignedUrlOptions } from './signed-url';
+export { signUrl, verifySignedUrl } from '../crypto/signed-url';
+export type { SignedUrlOptions } from '../crypto/signed-url';
 export { expandPathTemplate, joinStoragePath } from './path-template';
 export type { StorageBody, StorageDriver, PresignMethod, UploadOptions, UploadResult, DownloadResult, PresignedUrlResult, } from './storage.types';

package/dist/storage/index.js

@@ -1,2 +1,5 @@
-export { signUrl, verifySignedUrl } from "./signed-url.js";
+// The HMAC signed-URL util now lives in `src/crypto/` (core consumes it there
+// for the URL generator + guard). Re-exported here so `@velajs/vela/storage`'s
+// public API is unchanged for existing consumers.
+export { signUrl, verifySignedUrl } from "../crypto/signed-url.js";
 export { expandPathTemplate, joinStoragePath } from "./path-template.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -102,6 +102,7 @@
     "@vitest/runner": "^4.1.9",
     "@vitest/snapshot": "^4.1.9",
     "intl-messageformat": "^11.2.9",
+    "typedoc": "~0.28.19",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.9",
@@ -112,6 +113,9 @@
     "test": "vitest run",
     "test:workers": "vitest run --config vitest.config.workers.ts",
     "test:workers:als": "vitest run --config vitest.config.workers-als.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.type-tests.json",
+    "check:skill": "node scripts/check-skill.mjs",
+    "docs": "typedoc",
+    "docs:check": "typedoc --emit none"
   }
 }