@velajs/vela 1.9.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## 1.11.0 (2026-07-04)
+
+The module-model release: one blessed authoring path plus public kernel
+extension points, so feature modules (websocket, storage, queue, …) are built
+entirely on the public API. See `MODULE_AUTHORING.md` for the author contract.
+Contains deliberate breaking changes (no deprecation shims); coordinated
+releases of `@velajs/{storage,better-auth,testing,crud,cloudflare}` accompany
+this version.
+
+### Added
+
+- **`defineModule`** — the single module-authoring engine: generates `forRoot`
+  AND `forRootAsync` (typed `inject` inference), derives deterministic
+  `stableHash` keys (`key(options)` override + explicit `key` passthrough),
+  and accepts contributions (providers/controllers/imports/exports) **as
+  functions of the options** plus a standardized `global:` component slot.
+  `ConfigurableModuleBuilder` is now a thin adapter over it (unchanged API).
+- **Authoring primitives**: `lazyProvider` (memoized deferred thunk — replaces
+  the hand-rolled `(...deps)=>()=>fn(...deps)` closures), `provideGlobal`
+  (the one `APP_*` wiring idiom), `sideEffectModule` (first-class
+  contribution-only modules; supported form of the i18n empty-marker trick),
+  `moduleToken`, `moduleKey`.
+- **`DiscoveryService` + `createDiscoverableDecorator`** — public
+  decorator-driven discovery (`providersWithMeta`, `methodsWithMeta`,
+  `getProviders`) backed by a reverse metadata index inside
+  `MetadataRegistry`; honors container diagnostics in one place;
+  request-scoped providers are surfaced but not materialized (opt in with
+  `includeRequestScoped`). The event-emitter, schedule, and websocket
+  bootstrap scans now all run through it.
+- **Open entrypoint registry** — `registerEntrypointKind({ kind, metaKey,
+  level })`, the `ContributesEntrypoints` interface, and per-application
+  `app.entrypoints` (`ofKind`/`kinds`/`all`), built at the end of
+  `callOnApplicationBootstrap()` so slim bootstrap paths (Cloudflare Durable
+  Objects) get it too. Transports query entrypoints instead of module
+  internals; a new kind (queue, cron, CLI) needs **zero core changes**.
+- **`RouteContributor`** — public metadata-claimed route generation
+  (`registerRouteContributor`), consulted after explicit routes and during
+  OpenAPI generation with verb-level merge. Replaces the internal CrudBridge.
+- **`RuntimeAdapter`** — `VelaFactory.create(module, { adapters: [...] })`
+  with `requestMiddleware` (prepended to the global chain), `onBootstrap`
+  (after lifecycle + entrypoints, before routes) and `onRoutesBuilt` hooks.
+- **`PipelineRunner`** — the shared guard → pipe → interceptor execution core
+  used by HTTP and WebSocket dispatch (and any custom dispatcher);
+  configurable args/guards order, transport-specific guard-rejection error.
+- **`Container.replaceProvider(provider, { buckets })`** — supported
+  force-replace across module buckets (what test harnesses need).
+- **`buildEntrypointExecutionContext(kind, class, handler, payload)`** — the
+  entrypoint sibling of the HTTP/WS execution contexts, so guards/
+  interceptors/filters written against `getClass()`/`getHandler()`/`getType()`
+  run unchanged around queue batches, scheduled ticks, and custom kinds
+  (`EntrypointExecutionContext.getPayload()`). `@velajs/cloudflare` dispatches
+  queue/scheduled handlers through `PipelineRunner` with consumer-scoped
+  components (HTTP-global components deliberately do not apply; unclaimed
+  errors rethrow to preserve platform retry semantics).
+- **`runInEntrypointScope(container, fn)`** — the non-HTTP dispatch scope
+  primitive: runs one unit of work (queue batch, scheduled tick, RPC call) in
+  a fresh request-scoped child with LIFO disposal — the per-request-child
+  equivalent for entrypoint dispatchers. `@velajs/cloudflare`'s queue and
+  scheduled handlers run on it (request-scoped consumer deps rebuild per
+  batch/tick instead of capturing boot instances).
+
+### Changed
+
+- **Factory dependency visibility**: `useFactory`/`forRootAsync` `inject`
+  deps now resolve from the declaring module's scope FIRST (imports and
+  exports are honored), with the legacy no-requester lookup kept as fallback.
+- **All in-core configurable modules are on the one engine**: `CorsModule` and
+  `SeederModule` rebuilt on `defineModule` (Cors gains `forRootAsync`; both
+  keep their token/key identities), `ScheduleModule`/`ScheduleNodeModule`
+  normalized to zero-config `@Module` bags with parity `forRoot()` sugar.
+  Builder-based modules (Config/Cache/I18n/Throttler/Http) already run on it
+  through the `ConfigurableModuleBuilder` adapter.
+- **Unhandled handler errors are logged**: an error no exception filter claims
+  still maps to the generic 500 response, but the cause now lands in the logs
+  (`console.error`, gated on container diagnostics ≠ `silent`) — closing the
+  silent-500 gap.
+- **`WebSocketModule`** rebuilt on `defineModule`: registry → driver → server
+  construction moved into chained provider factories (single shared registry
+  preserved; everything materializes at bootstrap), deterministic key
+  `ws#<sync-kind>` — **two identical `forRoot()` calls now dedup**
+  (HMR-idempotent; pass explicit `key` for exotic multi-instance),
+  `forRootAsync` available. `WsDispatcher` contributes `'websocket'`
+  entrypoints; `registerWebSocketGateways` consumes
+  `app.entrypoints.ofKind('websocket')`.
+
+### Breaking
+
+- **`WS_MODULE_OPTIONS`** is now a typed `InjectionToken` (was the raw string
+  `'vela:ws-module-options'`).
+- **`ComponentManager`** is stateless: `init()` and the process-global
+  container are gone; `resolve*` methods require an explicit container;
+  `getComponents` replaced by `getScopedComponents` (controller + handler
+  only — app-wide components have one source: `RouteManager`).
+  `registerGlobal`/`MetadataRegistry.getGlobal` (a dead tier with no readers
+  on the request path) are removed; `MetadataRegistry.clear()` is now a
+  no-op.
+- **CrudBridge removed** (`registerCrudBridge`/`getCrudBridge` and the
+  `/internal` exports): use `registerRouteContributor`. `@velajs/crud`
+  migrates in its coordinated release.
+- `forRootAsync` structural fields (non-async keys passed alongside
+  `useFactory`) now merge under the resolved options.
+
+## 1.10.0 (2026-07-01)
+
+### Added
+
+- **WebSocket support** (`@velajs/vela/websocket` + `@velajs/vela/websocket-node`): `@WebSocketGateway`, `@SubscribeMessage`, gateways run through the same global guard/pipe/interceptor/filter tiers as HTTP (`RouteManager.getGlobalComponents()`).
+
+- **`ConfigurableModuleBuilder`** (NestJS-parity) + the lower-level `defineConfigurableModule` engine. Generates `forRoot`/`forRootAsync` (with `key`, `global`, `useClass`/`useExisting` async options, and the options token) from a tiny spec, so a new module is just its tokens + options type + service + a `@Module({...})` bag — while keeping vela's module encapsulation and multi-instance `key` dedup. `CacheModule`, `ConfigModule`, `ThrottlerModule`, and `HttpModule` are migrated onto it; `@velajs/cloudflare`'s binding modules reuse the engine.
+- **Opt-in ambient request access**: `getCurrentContainer()` / `getCurrentRequestContext()` + `enableAmbientContainer()`, wired via `VelaFactory.create(module, { ambientContainer: true })`. Backed by Hono's `hono/context-storage` (no `node:async_hooks` import in core); OFF by default, explicit child-container path unchanged. On Cloudflare Workers it requires the `nodejs_als` (or `nodejs_compat`) flag — validated on real workerd.
+- **Container + application disposal**: `Container.dispose()` (LIFO; `Symbol.asyncDispose`/`Symbol.dispose`/`.dispose()`, idempotent), `VelaApplication.dispose()` and `Symbol.asyncDispose` (enables `await using`). The root disposes shared singletons; the per-request child container is disposed automatically at the end of each HTTP request — streaming-safe (deferred until the response body drains) and zero-overhead when a request has no request-scoped disposables.
+- **Async cache stores (additive, non-breaking).** New `AsyncCacheStore` interface + `TieredCacheStore` (read-through + backfill + write-through over N sync/async tiers) in core, and `KVCacheStore` in `@velajs/cloudflare`, for a memory→KV cache. The existing synchronous `CacheStore`/`CacheService`/`CacheInterceptor` are **unchanged**; `CacheModuleOptions` gains an optional sync `store`. Use the async stores programmatically (inject under your own token).
+- **i18n** at the `@velajs/vela/i18n` subpath (keeps core lean; `intl-messageformat` is an optional peer dep): `I18nModule.forRoot()` + `registerMessages()` (deep-merged, HMR-safe globalThis registry), ICU formatting, header/query/cookie locale detection. `I18nService` is request-scoped and reads the per-request locale; injecting it into a controller is safe thanks to request-scope bubbling (no `ambientContainer` flag needed).
+- **Storage abstractions** at the `@velajs/vela/storage` subpath (dep-free, Web Crypto only): the `StorageDriver` contract, `expandPathTemplate`/`joinStoragePath`, and HMAC `signUrl`/`verifySignedUrl`. `@velajs/cloudflare` builds on them with a multi-disk `StorageModule` over R2 (`StorageService.put/get/delete/exists/url`, per-disk roots with `{date}`/`{year}`/… templates, bucket-by-name via `EnvService`) plus a signature-gated `StorageController` presign-proxy (R2 has no native presign).
+- **Seeders** at the `@velajs/vela/seeder` subpath: `@Seeder({ order })`, `SeederModule` (`forRoot({ seeders })`), and `SeederRegistry`/`runSeeders(app)` — decorator discovery at bootstrap (mirrors `ScheduleRegistry`), each seeder run in a request-scoped child. Paired with the **new `@velajs/cli` package** (clipanion) providing `vela db seed` driven by a `vela.config.{js,mjs,ts}` app factory (Node-side; kept out of the Worker bundle).
+
+### Changed
+
+- **Request-scope bubbling.** A provider (including controllers, which are singletons) that transitively depends on a request-scoped provider is now automatically treated as request-scoped — rebuilt per request instead of capturing the first request's instance. Matches NestJS; computed once at bootstrap (`Container.computeEffectiveScopes`), governs caching + eager instantiation. Fixes the captive-dependency hazard for request-scoped services injected into controllers.
+- **HMR-safe `MetadataRegistry`**: all backing state is now anchored on `globalThis` via `Symbol.for('vela:registry:v1')`, so a Vite dev re-eval reuses the state classes were decorated against (no split-brain: lost routes / spurious "not @Injectable" warnings / duplicated globals). No API change.
+- **`CacheModule`** now accepts an optional custom sync `store` in its options.
+
 ## 1.8.1 (2026-05-14)
 
 ### Revert

package/dist/__tests__/workers-als/entry-als.d.ts

@@ -0,0 +1,9 @@
+declare const _default: {
+    fetch(request: Request): Promise<Response>;
+};
+export default _default;
+declare global {
+    interface ExportedHandler<Env = unknown> {
+        fetch?(request: Request, env: Env, ctx: unknown): Response | Promise<Response>;
+    }
+}

package/dist/application.d.ts

@@ -1,6 +1,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 { MountOpenApiOptions } from './openapi/types';
 import type { FilterType, GuardType, InterceptorType, PipeType } from './registry/types';
@@ -9,6 +10,8 @@ export declare class VelaApplication {
     private readonly routeManager;
     private instances;
     private honoApp;
+    private entrypointRegistry;
+    private disposed;
     constructor(container: Container, routeManager: RouteManager);
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */
     initRoutes(): Promise<void>;
@@ -43,5 +46,20 @@ export declare class VelaApplication {
     mountOpenApi(options: MountOpenApiOptions): this;
     callOnModuleInit(): Promise<void>;
     callOnApplicationBootstrap(): Promise<void>;
+    /**
+     * Every entrypoint contributed by the module graph, grouped by kind —
+     * what runtime adapters/transports query instead of re-scanning providers:
+     * `app.entrypoints.ofKind('websocket')`.
+     */
+    get entrypoints(): EntrypointRegistry;
     close(signal?: string): Promise<void>;
+    /**
+     * Full teardown: run shutdown lifecycle hooks ({@link close}) then dispose
+     * container-held instances (LIFO) and clear cached singletons. Use for
+     * graceful shutdown and dev HMR so old and new DI graphs never coexist.
+     *
+     * On runtimes/TS supporting explicit resource management this is also exposed
+     * as `Symbol.asyncDispose`, enabling `await using app = await VelaFactory.create(...)`.
+     */
+    dispose(signal?: string): Promise<void>;
 }

package/dist/application.js

@@ -1,3 +1,5 @@
+import { DiscoveryService } from "./discovery/discovery.service.js";
+import { EntrypointRegistry } from "./entrypoint/entrypoint.registry.js";
 import { hasBeforeApplicationShutdown, hasOnApplicationBootstrap, hasOnApplicationShutdown, hasOnModuleDestroy, hasOnModuleInit } from "./lifecycle/index.js";
 import { renderScalarUi } from "./openapi/scalar-ui.js";
 import { renderSwaggerUi } from "./openapi/swagger-ui.js";
@@ -7,6 +9,8 @@ export class VelaApplication {
     routeManager;
     instances = [];
     honoApp = null;
+    entrypointRegistry = null;
+    disposed = false;
     constructor(container, routeManager){
         this.container = container;
         this.routeManager = routeManager;
@@ -136,6 +140,23 @@ export class VelaApplication {
                 await instance.onApplicationBootstrap();
             }
         }
+        // Build the per-app entrypoint registry AFTER the hooks: dispatchers that
+        // implement ContributesEntrypoints (WsDispatcher) finish their own
+        // discovery inside onApplicationBootstrap. Built here — not in
+        // VelaFactory/initRoutes — so slim bootstrap paths that never build HTTP
+        // routes (the Cloudflare Durable Object) still get `app.entrypoints`.
+        const discovery = this.container.has(DiscoveryService) ? this.container.resolve(DiscoveryService) : new DiscoveryService(this.container);
+        this.entrypointRegistry = await EntrypointRegistry.build(discovery, this.instances);
+    }
+    /**
+   * Every entrypoint contributed by the module graph, grouped by kind —
+   * what runtime adapters/transports query instead of re-scanning providers:
+   * `app.entrypoints.ofKind('websocket')`.
+   */ get entrypoints() {
+        if (!this.entrypointRegistry) {
+            throw new Error('Entrypoints are not built yet — they are assembled at the end of ' + 'callOnApplicationBootstrap(). Finish bootstrapping before querying them.');
+        }
+        return this.entrypointRegistry;
     }
     async close(signal) {
         const reversed = [
@@ -157,4 +178,28 @@ export class VelaApplication {
             }
         }
     }
+    /**
+   * Full teardown: run shutdown lifecycle hooks ({@link close}) then dispose
+   * container-held instances (LIFO) and clear cached singletons. Use for
+   * graceful shutdown and dev HMR so old and new DI graphs never coexist.
+   *
+   * On runtimes/TS supporting explicit resource management this is also exposed
+   * as `Symbol.asyncDispose`, enabling `await using app = await VelaFactory.create(...)`.
+   */ async dispose(signal) {
+        // Idempotent: `await using` + an explicit dispose(), or repeated shutdown
+        // signals, must not re-run shutdown lifecycle hooks.
+        if (this.disposed) return;
+        this.disposed = true;
+        await this.close(signal);
+        await this.container.dispose();
+    }
+}
+// Attach the well-known async-dispose symbol at runtime (it is not in the
+// ES2022 lib the project compiles against) so `await using` works where
+// supported, without a type dependency on esnext.disposable.
+const ASYNC_DISPOSE = Symbol.asyncDispose;
+if (ASYNC_DISPOSE) {
+    VelaApplication.prototype[ASYNC_DISPOSE] = function() {
+        return this.dispose();
+    };
 }

package/dist/cache/cache.module.d.ts

@@ -1,9 +1,7 @@
-import type { AsyncModuleOptions, DynamicModule } from '../module/types';
 import type { CacheModuleOptions } from './cache.types';
-export declare class CacheModule {
-    static forRoot(options?: CacheModuleOptions): DynamicModule;
-    static forRootAsync(options: AsyncModuleOptions<CacheModuleOptions> & {
-        isGlobal?: boolean;
-        key?: string;
-    }): DynamicModule;
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<CacheModuleOptions, "forRoot", "create", {
+    isGlobal: boolean;
+}>;
+export declare class CacheModule extends ConfigurableModuleClass {
 }
+export {};

package/dist/cache/cache.module.js

@@ -1,80 +1,58 @@
-import { stableHash } from "../module/stable-hash.js";
+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 { APP_INTERCEPTOR } from "../pipeline/tokens.js";
 import { CacheInterceptor } from "./cache.interceptor.js";
 import { CacheService } from "./cache.service.js";
 import { MemoryCacheStore } from "./cache.store.js";
 import { CACHE_MANAGER, CACHE_MODULE_OPTIONS } from "./cache.tokens.js";
-export class CacheModule {
-    static forRoot(options = {}) {
-        const { ttl = 5, max = 100, isGlobal = false } = options;
-        const store = new MemoryCacheStore(ttl, max);
-        const providers = [
-            {
-                provide: CACHE_MANAGER,
-                useValue: store
-            },
+// Reuse the public CACHE_MODULE_OPTIONS token so its identity (and the
+// index.ts export) is unchanged. `isGlobal` here means "register the interceptor
+// globally as APP_INTERCEPTOR" — NOT `DynamicModule.global` — so the extras
+// transform is customized rather than using the default isGlobal→global.
+const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = new ConfigurableModuleBuilder({
+    moduleName: 'Cache',
+    optionsInjectionToken: CACHE_MODULE_OPTIONS
+}).setExtras({
+    isGlobal: false
+}, (definition, { isGlobal })=>isGlobal ? {
+        ...definition,
+        providers: [
+            ...definition.providers ?? [],
             {
-                provide: CACHE_MODULE_OPTIONS,
-                useValue: options
-            },
-            CacheService,
-            CacheInterceptor
-        ];
-        if (isGlobal) {
-            providers.push({
                 provide: APP_INTERCEPTOR,
                 useExisting: CacheInterceptor
-            });
-        }
-        return {
-            module: CacheModule,
-            key: stableHash(options),
-            providers,
-            exports: [
-                CACHE_MANAGER,
-                CACHE_MODULE_OPTIONS,
-                CacheService,
-                CacheInterceptor
-            ]
-        };
-    }
-    static forRootAsync(options) {
-        const providers = [
-            {
-                provide: CACHE_MODULE_OPTIONS,
-                useFactory: options.useFactory,
-                inject: options.inject ?? []
-            },
+            }
+        ]
+    } : definition).build();
+export class CacheModule extends ConfigurableModuleClass {
+}
+CacheModule = _ts_decorate([
+    Module({
+        providers: [
+            CacheService,
+            CacheInterceptor,
+            // One options-injecting provider serves BOTH forRoot and forRootAsync.
+            // A custom `store` (e.g. TieredCacheStore / KVCacheStore) overrides the
+            // default in-memory store.
             {
                 provide: CACHE_MANAGER,
-                useFactory: (opts)=>new MemoryCacheStore(opts.ttl ?? 5, opts.max ?? 100),
+                useFactory: (options)=>options.store ?? new MemoryCacheStore(options.ttl ?? 5, options.max ?? 100),
                 inject: [
-                    CACHE_MODULE_OPTIONS
+                    MODULE_OPTIONS_TOKEN
                 ]
-            },
+            }
+        ],
+        exports: [
+            CACHE_MANAGER,
+            CACHE_MODULE_OPTIONS,
             CacheService,
             CacheInterceptor
-        ];
-        if (options.isGlobal) {
-            providers.push({
-                provide: APP_INTERCEPTOR,
-                useExisting: CacheInterceptor
-            });
-        }
-        return {
-            module: CacheModule,
-            key: options.key ?? stableHash({
-                inject: options.inject,
-                useFactory: options.useFactory
-            }),
-            imports: options.imports ?? [],
-            providers,
-            exports: [
-                CACHE_MANAGER,
-                CACHE_MODULE_OPTIONS,
-                CacheService,
-                CacheInterceptor
-            ]
-        };
-    }
-}
+        ]
+    })
+], CacheModule);

package/dist/cache/cache.types.d.ts

@@ -1,14 +1,40 @@
+/** A value that may be returned synchronously or as a promise. */
+export type Awaitable<T> = T | Promise<T>;
 export interface CacheModuleOptions {
     ttl?: number;
     max?: number;
     isGlobal?: boolean;
+    /**
+     * Custom SYNC backing store (replaces the default in-memory store). For async
+     * (KV/tiered) caching use {@link AsyncCacheStore} + `TieredCacheStore`
+     * programmatically — the interceptor/CacheService path is synchronous.
+     */
+    store?: CacheStore;
 }
+/**
+ * Synchronous cache backing store. This is the original, stable contract used by
+ * `CacheService` and `CacheInterceptor` — unchanged.
+ */
 export interface CacheStore {
     get<T = unknown>(key: string): T | undefined;
     set<T = unknown>(key: string, value: T, ttl?: number): void;
     del(key: string): void;
     clear(): void;
 }
+/**
+ * Asynchronous cache backing store (additive). Implemented by remote/tiered
+ * stores (`TieredCacheStore`, and `KVCacheStore` in `@velajs/cloudflare`) where
+ * reads/writes are inherently async. Use it programmatically — inject the store
+ * under your own token — rather than as the synchronous `CACHE_MANAGER`.
+ */
+export interface AsyncCacheStore {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** A store that may be sync or async (used to compose tiers). */
+export type AnyCacheStore = CacheStore | AsyncCacheStore;
 export interface CacheEntry<T = unknown> {
     value: T;
     expiresAt: number;

package/dist/cache/cache.types.js

@@ -1 +1 @@
-export { };
+/** A value that may be returned synchronously or as a promise. */ export { };

package/dist/cache/index.d.ts

@@ -2,6 +2,7 @@ export { CacheModule } from './cache.module';
 export { CacheService } from './cache.service';
 export { CacheInterceptor } from './cache.interceptor';
 export { MemoryCacheStore } from './cache.store';
+export { TieredCacheStore } from './tiered-cache.store';
 export { CacheKey, CacheTTL } from './cache.decorators';
 export { CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA } from './cache.tokens';
-export type { CacheModuleOptions, CacheStore, CacheEntry } from './cache.types';
+export type { Awaitable, CacheModuleOptions, CacheStore, AsyncCacheStore, AnyCacheStore, CacheEntry, } from './cache.types';

package/dist/cache/index.js

@@ -2,5 +2,6 @@ export { CacheModule } from "./cache.module.js";
 export { CacheService } from "./cache.service.js";
 export { CacheInterceptor } from "./cache.interceptor.js";
 export { MemoryCacheStore } from "./cache.store.js";
+export { TieredCacheStore } from "./tiered-cache.store.js";
 export { CacheKey, CacheTTL } from "./cache.decorators.js";
 export { CACHE_MANAGER, CACHE_MODULE_OPTIONS, CACHE_KEY_METADATA, CACHE_TTL_METADATA } from "./cache.tokens.js";

package/dist/cache/tiered-cache.store.d.ts

@@ -0,0 +1,19 @@
+import type { AnyCacheStore, AsyncCacheStore } from './cache.types';
+/**
+ * Composes an ordered list of cache tiers (fastest first, e.g. in-memory L1 →
+ * KV L2). Tiers may be sync ({@link CacheStore}) or async ({@link AsyncCacheStore}) —
+ * results are awaited uniformly. Reads are read-through: the first tier with a
+ * hit wins, and nearer tiers that missed are backfilled. Writes/deletes/clears
+ * fan out to all tiers. Always async ({@link AsyncCacheStore}).
+ *
+ * Runtime-agnostic — the concrete tiers (memory here, KV in `@velajs/cloudflare`)
+ * live wherever fits.
+ */
+export declare class TieredCacheStore implements AsyncCacheStore {
+    private readonly tiers;
+    constructor(tiers: AnyCacheStore[]);
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/cache/tiered-cache.store.js

@@ -0,0 +1,40 @@
+/**
+ * Composes an ordered list of cache tiers (fastest first, e.g. in-memory L1 →
+ * KV L2). Tiers may be sync ({@link CacheStore}) or async ({@link AsyncCacheStore}) —
+ * results are awaited uniformly. Reads are read-through: the first tier with a
+ * hit wins, and nearer tiers that missed are backfilled. Writes/deletes/clears
+ * fan out to all tiers. Always async ({@link AsyncCacheStore}).
+ *
+ * Runtime-agnostic — the concrete tiers (memory here, KV in `@velajs/cloudflare`)
+ * live wherever fits.
+ */ export class TieredCacheStore {
+    tiers;
+    constructor(tiers){
+        if (tiers.length === 0) {
+            throw new Error('TieredCacheStore requires at least one tier.');
+        }
+        this.tiers = tiers;
+    }
+    async get(key) {
+        for(let i = 0; i < this.tiers.length; i++){
+            const value = await this.tiers[i].get(key);
+            if (value !== undefined) {
+                // Backfill nearer (faster) tiers that missed.
+                for(let j = 0; j < i; j++){
+                    await this.tiers[j].set(key, value);
+                }
+                return value;
+            }
+        }
+        return undefined;
+    }
+    async set(key, value, ttl) {
+        await Promise.all(this.tiers.map((tier)=>tier.set(key, value, ttl)));
+    }
+    async del(key) {
+        await Promise.all(this.tiers.map((tier)=>tier.del(key)));
+    }
+    async clear() {
+        await Promise.all(this.tiers.map((tier)=>tier.clear()));
+    }
+}

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

@@ -1,11 +1,12 @@
-import type { AsyncModuleOptions, DynamicModule } from '../module/types';
+import type { DynamicModule } from '../module/types';
 import type { ConfigModuleOptions } from './config.types';
-export declare class ConfigModule {
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<ConfigModuleOptions<Record<string, unknown>>, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class ConfigModule extends ConfigurableModuleClass {
     static forRoot<T extends Record<string, unknown>>(options: ConfigModuleOptions<T> & {
-        key?: string;
-    }): DynamicModule;
-    static forRootAsync<T extends Record<string, unknown>>(options: AsyncModuleOptions<ConfigModuleOptions<T>> & {
         isGlobal?: boolean;
         key?: string;
     }): DynamicModule;
 }
+export {};

package/dist/config/config.module.js

@@ -1,54 +1,51 @@
-import { stableHash } from "../module/stable-hash.js";
+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 { ConfigService } from "./config.service.js";
 import { CONFIG_OPTIONS } from "./config.tokens.js";
-export class ConfigModule {
+// 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();
+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 config = options.validate ? options.validate(options.config) : options.config;
-        return {
-            module: ConfigModule,
-            key: options.key ?? stableHash(options.config),
-            providers: [
-                {
-                    provide: CONFIG_OPTIONS,
-                    useValue: config
-                },
-                ConfigService
-            ],
-            exports: [
-                ConfigService,
-                CONFIG_OPTIONS
-            ],
-            ...options.isGlobal ? {
-                global: true
-            } : {}
-        };
-    }
-    static forRootAsync(options) {
-        return {
-            module: ConfigModule,
-            key: options.key ?? stableHash({
-                inject: options.inject,
-                useFactory: options.useFactory
-            }),
-            imports: options.imports ?? [],
-            providers: [
-                {
-                    provide: CONFIG_OPTIONS,
-                    useFactory: async (...args)=>{
-                        const opts = await options.useFactory(...args);
-                        return opts.validate ? opts.validate(opts.config) : opts.config;
-                    },
-                    inject: options.inject ?? []
-                },
-                ConfigService
-            ],
-            exports: [
-                ConfigService,
-                CONFIG_OPTIONS
-            ],
-            ...options.isGlobal ? {
-                global: true
-            } : {}
-        };
+        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.
+        const { validate: _validate, ...rest } = options;
+        return super.forRoot({
+            ...rest,
+            config: validated
+        });
     }
 }
+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);