@velajs/vela 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.15.0 (2026-07-04)
+
+Introspection seams for `@velajs/cli` (roadmap phase 3, CLI introspection):
+serializable, zero-instantiation views of the app the CLI renders instead of
+re-deriving framework internals.
+
+### Added
+
+- **`app.describeRoutes(): RouteDescription[]`** — every explicit controller
+  route exactly as `build()` registered it: method AS DECLARED (`@Head()`
+  reports HEAD even though Hono serves it under GET), fully composed path
+  (global prefix + version segment + controller prefix + route path),
+  controller name, handler name, version. Contributed routes
+  (`RouteContributor`/CRUD) mount directly on Hono and are observable via
+  `getHonoApp().routes`.
+- **`app.getGlobalPrefix()`** — the prefix in effect ('' when none); also
+  what `openapi` tooling threads into `createOpenApiDocument`.
+- **`Container.getModuleDescriptions(): ModuleDescription[]`** — the loaded
+  module graph (moduleId, imports, isGlobal, lazy, provider/export token
+  labels), load order plus the `__root__` bucket; reads registration state
+  only — safe pre/post bootstrap, never constructs, never claims lazy
+  modules.
+- **`describeToken(token)`** — the token-label helper vela's own errors use,
+  exported for tooling.
+
 ## 1.14.0 (2026-07-04)
 
 First-party `QueueModule` (roadmap phase 3, "the openness proof"): a whole

package/dist/application.d.ts

@@ -2,7 +2,7 @@ import type { Hono } from 'hono';
 import type { Container } from './container/container';
 import type { Token } from './container/types';
 import { EntrypointRegistry } from './entrypoint/entrypoint.registry';
-import type { RouteManager } from './http/route.manager';
+import type { RouteDescription, RouteManager } from './http/route.manager';
 import type { MountOpenApiOptions } from './openapi/types';
 import type { FilterType, GuardType, InterceptorType, PipeType } from './registry/types';
 export declare class VelaApplication {
@@ -25,6 +25,15 @@ export declare class VelaApplication {
     setInstances(instances: unknown[]): void;
     get<T>(token: Token<T>): T;
     getHonoApp(): Hono;
+    /**
+     * Every explicit controller route as the framework registered it (fully
+     * composed paths — the `vela route list` seam). Requires built routes;
+     * contributed routes (`@velajs/crud`) mount directly on Hono and are
+     * observable via `getHonoApp().routes` instead.
+     */
+    describeRoutes(): RouteDescription[];
+    /** The global route prefix in effect ('' when none). */
+    getGlobalPrefix(): string;
     useGlobalPipes(...pipes: PipeType[]): this;
     useGlobalGuards(...guards: GuardType[]): this;
     useGlobalInterceptors(...interceptors: InterceptorType[]): this;

package/dist/application.js

@@ -63,6 +63,18 @@ export class VelaApplication {
     getHonoApp() {
         return this.getApp();
     }
+    /**
+   * Every explicit controller route as the framework registered it (fully
+   * composed paths — the `vela route list` seam). Requires built routes;
+   * contributed routes (`@velajs/crud`) mount directly on Hono and are
+   * observable via `getHonoApp().routes` instead.
+   */ describeRoutes() {
+        this.getApp(); // same routes-not-built guard as every HTTP accessor
+        return this.routeManager.getRouteDescriptions();
+    }
+    /** The global route prefix in effect ('' when none). */ getGlobalPrefix() {
+        return this.routeManager.getGlobalPrefix();
+    }
     // Pipeline components — applied at request time, no rebuild needed
     useGlobalPipes(...pipes) {
         this.routeManager.useGlobalPipes(...pipes);

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>;
+};