@velajs/vela 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+A sanctioned per-request injectable lands as a framework primitive, and the metadata-store unification finally has its regression tests.
+
+### New
+
+- **`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
+  import { Inject, Injectable, Scope, REQUEST_CONTEXT } from '@velajs/vela';
+  import type { RequestContext } from '@velajs/vela';
+
+  @Injectable({ scope: Scope.REQUEST })
+  class TenantResolver {
+    constructor(@Inject(REQUEST_CONTEXT) private readonly ctx: RequestContext) {}
+    resolve() {
+      return this.ctx.hono.req.header('x-tenant') ?? 'default';
+    }
+  }
+  ```
+
+### 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.
+- **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.
+
+## 1.3.0
+
 Module boundaries are enforced. NestJS-shape: a service cannot resolve dependencies from a module it didn't import. Bootstrap is consolidated into a single primitive, discovery failures are diagnostically routed, and a generic plugin composer is included.
 
 ### New

package/dist/container/container.d.ts

@@ -15,6 +15,7 @@ export declare class Container {
     private recordOrigin;
     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[];

package/dist/container/container.js

@@ -86,6 +86,14 @@ export class Container {
     markGlobalToken(token) {
         this.globals.add(token);
     }
+    // Pre-seed the per-request cache. Only meaningful on a child container
+    // produced by createChild() — the root's requestInstances map is unused.
+    // Used by RouteManager to populate framework-provided request-scope
+    // values (REQUEST_CONTEXT) before any handler resolution runs, so the
+    // provider's factory never fires on the request path.
+    setRequestInstance(token, value) {
+        this.requestInstances.set(token, value);
+    }
     getDiagnostics() {
         return this.diagnostics;
     }

package/dist/factory/bootstrap.js

@@ -1,5 +1,7 @@
+import { Scope } from "../constants.js";
 import { Container } from "../container/container.js";
 import { ModuleRef } from "../container/module-ref.js";
+import { REQUEST_CONTEXT } from "../http/request-context.js";
 import { RouteManager } from "../http/route.manager.js";
 import { ModuleLoader } from "../module/module-loader.js";
 import { bindAppProviders } from "../pipeline/app-providers.js";
@@ -39,6 +41,18 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
     ]){
         container.markGlobalToken(t);
     }
+    // REQUEST_CONTEXT is seeded into each request-scoped child by RouteManager
+    // before any handler resolves it (see route.manager.ts:getRequestContainer).
+    // The factory throws so misuse outside the request path surfaces immediately
+    // instead of materializing a phantom context.
+    container.register({
+        provide: REQUEST_CONTEXT,
+        scope: Scope.REQUEST,
+        useFactory: ()=>{
+            throw new Error('REQUEST_CONTEXT can only be resolved inside a request — ' + 'it is seeded by RouteManager when the request enters the pipeline.');
+        }
+    });
+    container.markGlobalToken(REQUEST_CONTEXT);
     const routeManager = new RouteManager(container, options);
     ComponentManager.init(container);
     const loader = new ModuleLoader(container, routeManager);

package/dist/http/request-context.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from 'hono';
+import { InjectionToken } from '../container/types';
+export interface RequestContext {
+    readonly id: string;
+    readonly receivedAt: Date;
+    readonly request: Request;
+    readonly hono: Context;
+    set<T>(key: string | symbol, value: T): void;
+    get<T>(key: string | symbol): T | undefined;
+    has(key: string | symbol): boolean;
+}
+export declare const REQUEST_CONTEXT: InjectionToken<RequestContext>;
+export declare function createRequestContext(c: Context): RequestContext;

package/dist/http/request-context.js

@@ -0,0 +1,22 @@
+import { InjectionToken } from "../container/types.js";
+export const REQUEST_CONTEXT = new InjectionToken('vela.RequestContext');
+export function createRequestContext(c) {
+    const bag = new Map();
+    const inboundId = c.req.raw.headers.get('x-request-id');
+    const id = inboundId && inboundId.length > 0 ? inboundId : crypto.randomUUID();
+    return {
+        id,
+        receivedAt: new Date(),
+        request: c.req.raw,
+        hono: c,
+        set (key, value) {
+            bag.set(key, value);
+        },
+        get (key) {
+            return bag.get(key);
+        },
+        has (key) {
+            return bag.has(key);
+        }
+    };
+}

package/dist/http/route.manager.js

@@ -4,6 +4,7 @@ import { HttpMethod, ParamType } from "../constants.js";
 import { getMetadata } from "../metadata.js";
 import { joinPaths } from "../registry/paths.js";
 import { buildExecutionContext } from "./execution-context.js";
+import { REQUEST_CONTEXT, createRequestContext } from "./request-context.js";
 import { ForbiddenException, HttpException } from "../errors/http-exception.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
 import { shouldFilterCatch } from "../pipeline/decorators.js";
@@ -206,6 +207,7 @@ export class RouteManager {
             return existing;
         }
         const child = this.container.createChild();
+        child.setRequestInstance(REQUEST_CONTEXT, createRequestContext(c));
         c.set('container', child);
         return child;
     }

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 export type { Type, Token, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
 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, applyDecorators, } from './http/index';
+export { REQUEST_CONTEXT } from './http/request-context';
+export type { RequestContext } from './http/request-context';
 export { Logger, LogLevel } from './services/index';
 export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './services/index';
 export { ConfigModule, ConfigService, CONFIG_OPTIONS } from './config/index';

package/dist/index.js

@@ -12,6 +12,8 @@ export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, fo
 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, applyDecorators } from "./http/index.js";
+// Request-scoped context primitive
+export { REQUEST_CONTEXT } from "./http/request-context.js";
 // Services
 export { Logger, LogLevel } from "./services/index.js";
 // Config

package/dist/registry/metadata.registry.js

@@ -265,6 +265,5 @@ export class MetadataRegistry {
             this.handlerComponents[type].clear();
         }
         this.globalComponents = emptyComponentStore();
-    // reflectMeta is a WeakMap — entries die with their targets.
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",