@velajs/vela 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -2,10 +2,14 @@
 
 ## Unreleased
 
-A sanctioned per-request injectable lands as a framework primitive, and the metadata-store unification finally has its regression tests.
+A sanctioned per-request injectable lands as a framework primitive, the metadata-store unification finally has its regression tests, and dynamic module identity becomes consistent — closing the last open audit item.
 
 ### New
 
+- **Dynamic module identity is now first-class** (audit #2 — last open item, fully closed). `DynamicModule` gains an optional `key?: string`; module authors call `key: stableHash(options)` inside `forRoot()` so two distinct option sets register as distinct module instances. The DI container is bucketed per-module (`Map<moduleId, Map<Token, Registration>>`) so the same logical token can have distinct registrations in different buckets — e.g., `imports: [CacheModule.forRoot({ttl:60}), CacheModule.forRoot({ttl:120})]` now actually produces two reachable cache configs instead of silently dropping one. A consumer module that imports both throws `MultipleProvidersFoundError` with both candidate ids in the message; resolve only one and the ambiguity disappears. `[HttpModule, HttpModule.forRoot({base:X})]` registers both and the loader emits a diagnostic warning. `createModuleRef()` is removed — module authors use `{module: RealClass, key}` directly. New helpers `defineDynamicModule()` and `stableHash()` are exported from the root.
+
+  Pre-fix this swallowed configuration silently in two places: same-class `forRoot` calls collided at `processedModules.has(class)`, and synthetic-class-per-call patterns (the old `HttpModule`) collided at the container's `if (!has(token))` provider guard. Both guards are gone.
+
 - **`REQUEST_CONTEXT` injectable.** A request-scoped primitive carrying a stable `id` (mirrored from inbound `x-request-id` if present, else `crypto.randomUUID()`), `receivedAt`, the raw `Request`, the Hono `Context`, and a typed `set/get/has` bag for cross-cutting metadata. Seeded by `RouteManager` into each per-request child container; resolves through `@Inject(REQUEST_CONTEXT)` from any request-scoped service. No `AsyncLocalStorage` — edge-runtime contract intact (verified live under workerd via `pnpm test:workers`).
 
   ```ts
@@ -21,9 +25,17 @@ A sanctioned per-request injectable lands as a framework primitive, and the meta
   }
   ```
 
+### Breaking
+
+- **`createModuleRef()` removed.** The synthetic-class-per-`forRoot()` workaround is gone; modules use `{ module: RealClass, key }` instead. First-party modules (`HttpModule`, `CacheModule`, `ConfigModule`, `ThrottlerModule`, `CorsModule`) are migrated. Sibling consumers (`@velajs/cloudflare`, `@velajs/crud`) need to switch from `createModuleRef('${name}_${key}')` to `key: ...` on the DynamicModule.
+- **Container provider storage shape changed.** `Container.providers` is now `Map<moduleId, Map<Token, Registration>>` instead of flat. `providerOrigin` is removed (origin is now `declaringModuleId` on each `ProviderRegistration`). `assertVisible` is removed (its role is subsumed by lookup-or-throw in `resolve`). `Container.has(token)` is preserved (any-bucket scan); a new `Container.hasInScope(token, moduleId)` is the strict variant. `resolveAll(token)` is now a real walk across reachable buckets, not a stub. New error: `MultipleProvidersFoundError` when an imports walk yields >1 candidate. New constant: `ROOT_MODULE_ID = '__root__'` (sentinel bucket for bootstrap primitives and sandbox registrations).
+
 ### Internal cleanup
 
 - **Metadata stacking + funnel coverage** (audit #8 follow-up). New `metadata-stacking.test.ts` asserts `appendCustomHandlerMeta` is order-deterministic, `Reflect.defineMetadata` round-trips through `MetadataRegistry`'s typed slots, `MetadataRegistry.reset()` clears `classMeta`/`handlerMeta`, and class+handler `@SetMetadata` on the same key remain independent.
+- **`NestModule.configure()` regression coverage** (audit #4 follow-up). New `configure-resolution.test.ts` asserts configure-time DI works (modules can constructor-inject providers from their own scope), synchronous errors thrown from `configure()` propagate, and unresolvable constructor deps fail loudly rather than silently skipping middleware setup.
+- **Edge-safe contract documented** (audit #7 follow-up). README now states the contract explicitly: the main export is edge-safe and audited in CI by `src/__tests__/edge-runtime-audit.test.ts`; `@velajs/vela/schedule-node` is the one opt-in Node/Bun carve-out.
+- **`RouteManager` split into focused units** (audit #9 follow-up). New files `argument-resolver.ts`, `handler-executor.ts`, `response-mapper.ts`, and `instantiate.ts` carry parameter extraction, the per-request orchestration closure, response/redirect mapping, and the container-aware factory. `RouteManager` is now focused on Hono route registration and path composition. Internal-only refactor — no public API change, no behavior change.
 - **Stale `WeakMap` comment removed** from `MetadataRegistry.reset()` — the WeakMap fallback was retired in 1.1.0; the comment was documentation drift.
 - **`Container.setRequestInstance(token, value)`** — public method to pre-seed the per-request cache. Used by `RouteManager` to populate `REQUEST_CONTEXT` before any handler resolution runs.
 

package/README.md

@@ -73,6 +73,19 @@ Vela runs on any runtime that supports the Web Standards API:
 
 No Node.js-specific APIs (`node:fs`, `Buffer`, `process`) are used.
 
+### Edge-safe contract
+
+The **main export** (`@velajs/vela`) is edge-safe by contract — no `node:*` imports, no `Buffer`, no `process`, no `setInterval`, no `Bun.serve`. This is enforced in CI by [`src/__tests__/edge-runtime-audit.test.ts`](src/__tests__/edge-runtime-audit.test.ts), which fails the build if any file under `src/` references a forbidden API.
+
+One subpath, **`@velajs/vela/schedule-node`**, is an opt-in Node/Bun adapter for `setInterval`-based job execution. It uses runtime-specific APIs by design and is **excluded from the edge-runtime audit**. Edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge) should not import it — use platform cron triggers instead (e.g., `@velajs/cloudflare` ≥ 0.2.0 dispatches `@Cron` jobs via the Workers `scheduled()` handler).
+
+```ts
+// Node / Bun only — opt-in
+import { ScheduleNodeModule } from '@velajs/vela/schedule-node';
+```
+
+The other subpaths (`@velajs/vela/internal`, `@velajs/vela/streaming`) follow the main export's edge-safe contract.
+
 ## Dynamic modules
 
 Configurable modules use `forRoot` (sync) and `forRootAsync` (DI-resolved):
@@ -91,6 +104,45 @@ Configurable modules use `forRoot` (sync) and `forRootAsync` (DI-resolved):
 class AppModule {}
 ```
 
+### Identity model
+
+Each `DynamicModule` has an optional `key?: string` that discriminates one instance from another. First-party modules derive `key: stableHash(options)` automatically inside `forRoot` — so the same options always dedup, and distinct options register as distinct instances:
+
+```ts
+// Same options → dedup (one CacheModule instance, ttl: 60)
+imports: [
+  CacheModule.forRoot({ ttl: 60 }),
+  CacheModule.forRoot({ ttl: 60 }),
+]
+
+// Different options → two distinct instances coexist
+imports: [
+  CacheModule.forRoot({ ttl: 60 }),
+  CacheModule.forRoot({ ttl: 120 }),
+]
+```
+
+When a consumer module imports two instances both exporting the same logical token, the resolver throws `MultipleProvidersFoundError` with both candidate ids — resolve the ambiguity by importing only one, or use a per-instance accessor exposed by the module. Most apps with a single instance never hit this.
+
+Custom modules can use the same pattern via the public helpers:
+
+```ts
+import { defineDynamicModule, stableHash } from '@velajs/vela';
+
+class MyModule {
+  static forRoot(options: MyOptions): DynamicModule {
+    return defineDynamicModule({
+      module: MyModule,
+      key: stableHash(options),    // or pass an explicit key
+      providers: [/* ... */],
+      exports: [/* ... */],
+    });
+  }
+}
+```
+
+`forRootAsync` callers should pass `key` explicitly when the same module needs multiple async instances — factories aren't structurally hashable.
+
 ## Companion packages
 
 | Package | Purpose |

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

@@ -4,5 +4,6 @@ export declare class CacheModule {
     static forRoot(options?: CacheModuleOptions): DynamicModule;
     static forRootAsync(options: AsyncModuleOptions<CacheModuleOptions> & {
         isGlobal?: boolean;
+        key?: string;
     }): DynamicModule;
 }

package/dist/cache/cache.module.js

@@ -1,3 +1,4 @@
+import { stableHash } from "../module/stable-hash.js";
 import { APP_INTERCEPTOR } from "../pipeline/tokens.js";
 import { CacheInterceptor } from "./cache.interceptor.js";
 import { CacheService } from "./cache.service.js";
@@ -27,6 +28,7 @@ export class CacheModule {
         }
         return {
             module: CacheModule,
+            key: stableHash(options),
             providers,
             exports: [
                 CACHE_MANAGER,
@@ -61,6 +63,10 @@ export class CacheModule {
         }
         return {
             module: CacheModule,
+            key: options.key ?? stableHash({
+                inject: options.inject,
+                useFactory: options.useFactory
+            }),
             imports: options.imports ?? [],
             providers,
             exports: [

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

@@ -1,8 +1,11 @@
 import type { AsyncModuleOptions, DynamicModule } from '../module/types';
 import type { ConfigModuleOptions } from './config.types';
 export declare class ConfigModule {
-    static forRoot<T extends Record<string, unknown>>(options: ConfigModuleOptions<T>): DynamicModule;
+    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;
 }

package/dist/config/config.module.js

@@ -1,3 +1,4 @@
+import { stableHash } from "../module/stable-hash.js";
 import { ConfigService } from "./config.service.js";
 import { CONFIG_OPTIONS } from "./config.tokens.js";
 export class ConfigModule {
@@ -5,6 +6,7 @@ export class ConfigModule {
         const config = options.validate ? options.validate(options.config) : options.config;
         return {
             module: ConfigModule,
+            key: options.key ?? stableHash(options.config),
             providers: [
                 {
                     provide: CONFIG_OPTIONS,
@@ -24,6 +26,10 @@ export class ConfigModule {
     static forRootAsync(options) {
         return {
             module: ConfigModule,
+            key: options.key ?? stableHash({
+                inject: options.inject,
+                useFactory: options.useFactory
+            }),
             imports: options.imports ?? [],
             providers: [
                 {

package/dist/container/container.d.ts

@@ -1,25 +1,55 @@
 import { Scope } from '../constants';
 import type { ContainerOptions, Diagnostics, ModuleScope, ProviderOptions, Token, Type } from './types';
+/**
+ * Per-module provider buckets. Each module instance owns its providers under
+ * its `moduleId`; the same logical token can have distinct registrations in
+ * different buckets, supporting multi-instance dynamic modules.
+ *
+ * The `__root__` bucket holds bootstrap-time framework primitives (Container,
+ * ModuleRef, REQUEST_CONTEXT, etc.) and any `register()` call that doesn't
+ * supply a `declaringModuleId`.
+ */
 export declare class Container {
     private providers;
+    private exporterIndex;
     private resolutionStack;
     private requestInstances;
     private scopes;
     private globals;
-    private providerOrigin;
     private diagnostics;
     constructor(options?: ContainerOptions);
     register<T>(provider: Type<T> | ProviderOptions<T>, declaringModuleId?: string): this;
     private registerClass;
     private registerOptions;
-    private recordOrigin;
+    private writeRegistration;
     registerScope(scope: ModuleScope): void;
     markGlobalToken(token: Token): void;
     setRequestInstance(token: Token, value: unknown): void;
     getDiagnostics(): Diagnostics;
     resolve<T>(token: Token<T>, requestingModuleId?: string): T;
     resolveAll<T>(token: Token<T>, requestingModuleId?: string): T[];
+    /**
+     * Find a single reachable registration for a token, applying the visibility
+     * walk: requester's bucket → globals → requester's importedModules
+     * (transitively, following re-exports).
+     *
+     * Returns `undefined` if no candidate exists. Throws
+     * `MultipleProvidersFoundError` if the imports walk yields more than one.
+     */
+    private findRegistration;
+    /** Typed bucket lookup — single seam where the Map<Token, Registration> erases T. */
+    private lookupInBucket;
+    /**
+     * Walk a scope's imports (and their imports' imports, …) collecting every
+     * registration reachable through re-export chains. A child only contributes
+     * if it explicitly exports the token — non-exported providers stay private.
+     */
+    private collectFromImports;
+    private findAllRegistrations;
+    /** True if any bucket has a registration for `token`. Sandbox-friendly. */
     has(token: Token): boolean;
+    /** True if the specified module's bucket has a registration for `token`. */
+    hasInScope(token: Token, moduleId: string): boolean;
     getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
     /**
@@ -35,7 +65,5 @@ export declare class Container {
     private resolveFactory;
     resolveAsync<T>(token: Token<T>, requestingModuleId?: string): Promise<T>;
     private createLazyProxy;
-    private assertVisible;
-    private isExportedFromImports;
     private tokenToString;
 }