@velajs/vela 1.19.0 → 1.19.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.19.1
+
+### Patch Changes
+
+- 50854e2: Modernize the package build, validation, and release toolchain.
+
 ## 1.19.0 (2026-07-11)
 
 Exception-handler layer (roadmap phase 3): a single branded error concept, one
@@ -96,7 +102,7 @@ machine-verified by an import audit test.
   `@velajs/cloudflare` already exports an unrelated CF-binding `QueueModule`).
   Producers: `QueueModule.forRoot({ queues: ['email'] })` + per-queue
   `QueueClient` injected via `queueToken(name)` (`add(jobName, data,
-  { delayMs? })`). Consumers: `@Processor(queue)` classes with
+{ delayMs? })`). Consumers: `@Processor(queue)` classes with
   `@Process(jobName?)` handlers (named wins over wildcard; duplicates warn,
   first-wins). Dispatch runs each job in `runInEntrypointScope`
   (request-scoped deps rebuild per job), re-resolves processors by token
@@ -136,7 +142,7 @@ cost it nothing at bootstrap.
 
 - **Lazy modules** — `@Module({ lazy: true })`, `DynamicModule.lazy`, and
   `defineModule({ lazy: true })` (also recognized per call site like
-  `isGlobal`) defer a module *instance*'s entire provider/controller group:
+  `isGlobal`) defer a module _instance_'s entire provider/controller group:
   nothing constructs during `VelaFactory.create`. The first resolution of any
   of its tokens (injection, `app.get()`, a request hitting its controller, a
   dispatcher re-resolving an entrypoint token) claims the module; when the
@@ -156,7 +162,7 @@ cost it nothing at bootstrap.
   non-triggering diagnostics (build-time probes, cold-start regression tests).
 - **`DiscoveryFilter.deferLazy`** — discovery returns providers of
   unmaterialized lazy modules as metadata-only entries (`instance:
-  undefined`, mirroring the request-scoped convention) instead of forcing the
+undefined`, mirroring the request-scoped convention) instead of forcing the
   group. `EntrypointRegistry.build` uses it: declared-kind entrypoints of
   lazy modules are metadata-only in `app.entrypoints`; dispatchers that
   re-resolve by token (cloudflare cron/queue/scheduled already do)
@@ -211,7 +217,7 @@ this version.
   `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
+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
@@ -320,7 +326,7 @@ The exception-filter chain now reaches into attached middlewares for full NestJS
 
 ### Added
 
-- **`createLazyParamDecorator((data, ctx) => T)`.** Custom parameter decorators whose factory runs the *first time the handler reads a property on the resolved value* — not during argument extraction. Vela's argument resolver runs before guards by design (`extract args → guards → handler`), which means a `createParamDecorator` factory that depends on guard-populated state observes an empty slot. The lazy variant returns a `Proxy` whose traps invoke the factory on demand; the `get` trap short-circuits `prop === 'then'` so `await value` does not consider the proxy a thenable and therefore does not trigger eager resolution. Method results are auto-bound to the resolved real target so detached calls keep `this`; `ownKeys` + `getOwnPropertyDescriptor` are implemented so `JSON.stringify(value)` works after one access. Exported from the root barrel and from `@velajs/vela/internal` via the same surface as `createParamDecorator`. Documented in README under *Custom parameter decorators with deferred resolution*.
+- **`createLazyParamDecorator((data, ctx) => T)`.** Custom parameter decorators whose factory runs the _first time the handler reads a property on the resolved value_ — not during argument extraction. Vela's argument resolver runs before guards by design (`extract args → guards → handler`), which means a `createParamDecorator` factory that depends on guard-populated state observes an empty slot. The lazy variant returns a `Proxy` whose traps invoke the factory on demand; the `get` trap short-circuits `prop === 'then'` so `await value` does not consider the proxy a thenable and therefore does not trigger eager resolution. Method results are auto-bound to the resolved real target so detached calls keep `this`; `ownKeys` + `getOwnPropertyDescriptor` are implemented so `JSON.stringify(value)` works after one access. Exported from the root barrel and from `@velajs/vela/internal` via the same surface as `createParamDecorator`. Documented in README under _Custom parameter decorators with deferred resolution_.
 
 ### Changed
 
@@ -339,14 +345,16 @@ A sanctioned per-request injectable lands as a framework primitive, the metadata
 - **`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';
+  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) {}
+    constructor(
+      @Inject(REQUEST_CONTEXT) private readonly ctx: RequestContext
+    ) {}
     resolve() {
-      return this.ctx.hono.req.header('x-tenant') ?? 'default';
+      return this.ctx.hono.req.header("x-tenant") ?? "default";
     }
   }
   ```
@@ -393,7 +401,7 @@ Module boundaries are enforced. NestJS-shape: a service cannot resolve dependenc
 
 ### Internal cleanup
 
-- **`Container` constructor accepts `ContainerOptions`** (`{ diagnostics? }`). Threads `requestingModuleId` through `resolve` / `resolveAsync` / `resolveAll`. Per-module scopes are tracked via `registerScope`; framework-internal globals via `markGlobalToken`. `providerOrigin: Map<Token, string>` records each provider's declaring module so constructor injections resolve from the *class's* module, not the caller's. Visibility enforcement runs whenever a `requestingModuleId` is supplied — there is no on/off switch.
+- **`Container` constructor accepts `ContainerOptions`** (`{ diagnostics? }`). Threads `requestingModuleId` through `resolve` / `resolveAsync` / `resolveAll`. Per-module scopes are tracked via `registerScope`; framework-internal globals via `markGlobalToken`. `providerOrigin: Map<Token, string>` records each provider's declaring module so constructor injections resolve from the _class's_ module, not the caller's. Visibility enforcement runs whenever a `requestingModuleId` is supplied — there is no on/off switch.
 
 - **`ModuleLoader` registers a `ModuleScope` per module** before recursing into imports — `localProviders` includes the module class itself (so `NestModule.configure()` resolution stays inside its own scope), controllers, and every provider token. Synthetic `APP_*` tokens are marked global at mint time so RouteManager's request-time resolutions (no requester) keep working.
 
@@ -403,7 +411,7 @@ Module boundaries are enforced. NestJS-shape: a service cannot resolve dependenc
 
 - **Dropped unused `Container.parent` field** (audit #10). Was assigned in `createChild()` but never read.
 
-- **Bootstrap consolidated into `src/factory/bootstrap.ts`** — `VelaFactory.create` no longer hand-rolls the APP_* / consumer-middleware / global-prefix wiring sequence. Net code reduction in `factory.ts`.
+- **Bootstrap consolidated into `src/factory/bootstrap.ts`** — `VelaFactory.create` no longer hand-rolls the APP\_\* / consumer-middleware / global-prefix wiring sequence. Net code reduction in `factory.ts`.
 
 ## 1.1.0 (2026-04-30)
 
@@ -480,7 +488,7 @@ Architectural remodel: one metadata model, one storage, public surface trimmed,
 - **`module-loader` `new moduleClass()` footgun fixed.** `NestModule.configure()` modules are now resolved through the container, so they can have constructor-injected deps.
 - **One path util** (`registry/paths.ts`: `normalizePath`, `joinPaths`, `toOpenApiPath`). Replaces 2× duplicated implementations in `http/decorators.ts`, `openapi/document.ts`, and `route.manager.ts`.
 - **One `ExecutionContext` factory** (`http/execution-context.ts`: `buildExecutionContext`). Replaces 2× duplicated literal construction.
-- **One `bindAppProviders` helper** (`pipeline/app-providers.ts`). Implements the NestJS APP_* provider convention in one place; replaces 5× duplicated APP_* wiring blocks across `factory.ts` and `testing.builder.ts`.
+- **One `bindAppProviders` helper** (`pipeline/app-providers.ts`). Implements the NestJS APP*\* provider convention in one place; replaces 5× duplicated APP*\* wiring blocks across `factory.ts` and `testing.builder.ts`.
 - **One module-graph walk** (`module/graph.ts`: `collectControllers`). Replaces the duplicate implementation in `openapi/document.ts`.
 - **schedule/event-emitter/openapi decorators** now use `MetadataRegistry.appendCustomClassMeta`/`appendCustomHandlerMeta` instead of direct `Reflect.defineMetadata` calls.
 - **Stub `pnpm-workspace.yaml` and `bunfig.toml` deleted** — they only set `onlyBuiltDependencies`, which lives in `package.json#pnpm`. `bun.lock` deleted; pnpm is the source of truth.
@@ -494,7 +502,7 @@ Edge-runtime audit and AI-drift cleanup.
 - **Schedule module split.** `ScheduleExecutor`, `SCHEDULE_MODULE_OPTIONS`, and `ScheduleModuleOptions` are no longer exported from `@velajs/vela`. The `setInterval`-based timer executor moved to a new opt-in sub-export at `@velajs/vela/schedule-node`. Consumers on Node or Bun should now do:
 
   ```ts
-  import { ScheduleNodeModule } from '@velajs/vela/schedule-node';
+  import { ScheduleNodeModule } from "@velajs/vela/schedule-node";
 
   @Module({ imports: [ScheduleNodeModule.forRoot()], providers: [JobsService] })
   class AppModule {}
@@ -504,7 +512,7 @@ Edge-runtime audit and AI-drift cleanup.
 
   Edge runtimes without `setInterval` (Cloudflare Workers, etc.) should continue to use platform cron triggers — `@velajs/cloudflare` ≥ 0.2.0 dispatches core `@Cron` jobs via its `scheduled()` handler.
 
-- **TypeScript enums replaced with `as const` objects** for `HttpMethod`, `ParamType`, `Scope`, `RequestMethod`, and `LogLevel`. Value access (`HttpMethod.GET`) keeps working; type-position usages (`: HttpMethod`) keep working via same-name type aliases. Code that imported the enum *type* with structural assumptions about enum runtime shape may need adjustment.
+- **TypeScript enums replaced with `as const` objects** for `HttpMethod`, `ParamType`, `Scope`, `RequestMethod`, and `LogLevel`. Value access (`HttpMethod.GET`) keeps working; type-position usages (`: HttpMethod`) keep working via same-name type aliases. Code that imported the enum _type_ with structural assumptions about enum runtime shape may need adjustment.
 
 ### Fixes
 

package/dist/configurable-module.builder-5FGMaXG6.js

@@ -0,0 +1,91 @@
+import { n as defineModule, r as stableHash } from "./define-module-NOyOZNXD.js";
+//#region src/module/configurable-module.builder.ts
+/**
+* Blessed key-derivation helper for hand-written `forRoot` statics: the one
+* documented way to derive a `DynamicModule.key` from an options bag so
+* identical configurations dedup (HMR-idempotent) and distinct ones coexist.
+* Alias of {@link stableHash} with a module-authoring name.
+*/
+const moduleKey = stableHash;
+/**
+* NestJS-parity builder that generates `forRoot`/`forRootAsync` (and `key`,
+* `global`, factory-param inference) from a tiny spec — so a module is just its
+* tokens + options type + service + a `@Module({...})` bag, while vela keeps its
+* encapsulation (`exports`/visibility) and multi-instance `key` dedup.
+*
+* Since 1.11 this is a thin adapter over {@link defineModule} — the single
+* authoring engine. Prefer `defineModule` for new modules: it additionally
+* supports contributions (providers/controllers/imports/exports/global
+* components) computed as functions of the options.
+*
+* @example
+* ```ts
+* const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
+*   new ConfigurableModuleBuilder<FooOptions>({ moduleName: 'Foo' }).build();
+*
+* @Module({
+*   providers: [FooService], // derived providers inject MODULE_OPTIONS_TOKEN
+*   exports: [FooService],
+* })
+* export class FooModule extends ConfigurableModuleClass {}
+* ```
+*/
+var ConfigurableModuleBuilder = class {
+	options;
+	classMethodName = "forRoot";
+	factoryMethodName = "create";
+	extrasDefaults;
+	extrasTransform;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/** Declare extra call-site keys (e.g. `isGlobal`) + how they reshape the definition. */
+	setExtras(defaults, transform) {
+		this.extrasDefaults = defaults;
+		this.extrasTransform = transform;
+		return this;
+	}
+	/** Rename the sync static (default `forRoot`); the async static becomes `<name>Async`. */
+	setClassMethodName(name) {
+		this.classMethodName = name;
+		return this;
+	}
+	/** Rename the method a `useClass`/`useExisting` options factory must implement (default `create`). */
+	setFactoryMethodName(name) {
+		this.factoryMethodName = name;
+		return this;
+	}
+	build() {
+		return defineModule({
+			name: this.options.moduleName ?? "ConfigurableModule",
+			optionsToken: this.options.optionsInjectionToken,
+			extras: this.extrasDefaults,
+			transform: this.extrasTransform,
+			methodName: this.classMethodName,
+			factoryMethodName: this.factoryMethodName
+		});
+	}
+};
+/**
+* Lower-level engine for cases a class-mixin can't express — chiefly a
+* runtime-generated module class whose providers depend on a call-time arg
+* (Cloudflare binding modules). Returns an object with a single static named by
+* `spec.methodName` (default `forRoot`).
+*/
+function defineConfigurableModule(spec) {
+	return { [spec.methodName ?? "forRoot"](args) {
+		const definition = {
+			module: spec.module,
+			key: spec.keyFrom(args),
+			providers: spec.providers(args)
+		};
+		if (spec.imports) definition.imports = spec.imports(args);
+		if (spec.exports) definition.exports = spec.exports;
+		if (spec.global) definition.global = true;
+		return definition;
+	} };
+}
+//#endregion
+export { defineConfigurableModule as n, moduleKey as r, ConfigurableModuleBuilder as t };
+
+//# sourceMappingURL=configurable-module.builder-5FGMaXG6.js.map

package/dist/configurable-module.builder-5FGMaXG6.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurable-module.builder-5FGMaXG6.js","names":[],"sources":["../src/module/configurable-module.builder.ts"],"sourcesContent":["import { InjectionToken } from '../container/types';\nimport type { DynamicModule } from '../registry/types';\nimport type {\n  ConfigurableModuleBuilderOptions,\n  ConfigurableModuleExtras,\n  ConfigurableModuleExtrasTransform,\n  ConfigurableModuleHost,\n  DefineConfigurableModuleSpec,\n} from './configurable-module.types';\nimport { defineModule } from './define-module';\nimport { stableHash } from './stable-hash';\n\n/**\n * Blessed key-derivation helper for hand-written `forRoot` statics: the one\n * documented way to derive a `DynamicModule.key` from an options bag so\n * identical configurations dedup (HMR-idempotent) and distinct ones coexist.\n * Alias of {@link stableHash} with a module-authoring name.\n */\nexport const moduleKey: (options: unknown) => string = stableHash;\n\n/**\n * NestJS-parity builder that generates `forRoot`/`forRootAsync` (and `key`,\n * `global`, factory-param inference) from a tiny spec — so a module is just its\n * tokens + options type + service + a `@Module({...})` bag, while vela keeps its\n * encapsulation (`exports`/visibility) and multi-instance `key` dedup.\n *\n * Since 1.11 this is a thin adapter over {@link defineModule} — the single\n * authoring engine. Prefer `defineModule` for new modules: it additionally\n * supports contributions (providers/controllers/imports/exports/global\n * components) computed as functions of the options.\n *\n * @example\n * ```ts\n * const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =\n *   new ConfigurableModuleBuilder<FooOptions>({ moduleName: 'Foo' }).build();\n *\n * @Module({\n *   providers: [FooService], // derived providers inject MODULE_OPTIONS_TOKEN\n *   exports: [FooService],\n * })\n * export class FooModule extends ConfigurableModuleClass {}\n * ```\n */\nexport class ConfigurableModuleBuilder<\n  Opts,\n  MethodKey extends string = 'forRoot',\n  FactoryMethodKey extends string = 'create',\n  Extras extends ConfigurableModuleExtras = { isGlobal?: boolean },\n> {\n  private classMethodName = 'forRoot';\n  private factoryMethodName = 'create';\n  private extrasDefaults: ConfigurableModuleExtras | undefined;\n  private extrasTransform: ConfigurableModuleExtrasTransform<ConfigurableModuleExtras> | undefined;\n\n  constructor(private readonly options: ConfigurableModuleBuilderOptions = {}) {}\n\n  /** Declare extra call-site keys (e.g. `isGlobal`) + how they reshape the definition. */\n  setExtras<NewExtras extends ConfigurableModuleExtras>(\n    defaults: NewExtras,\n    transform: ConfigurableModuleExtrasTransform<NewExtras>,\n  ): ConfigurableModuleBuilder<Opts, MethodKey, FactoryMethodKey, NewExtras> {\n    this.extrasDefaults = defaults;\n    this.extrasTransform = transform as ConfigurableModuleExtrasTransform<ConfigurableModuleExtras>;\n    return this as unknown as ConfigurableModuleBuilder<\n      Opts,\n      MethodKey,\n      FactoryMethodKey,\n      NewExtras\n    >;\n  }\n\n  /** Rename the sync static (default `forRoot`); the async static becomes `<name>Async`. */\n  setClassMethodName<NewMethodKey extends string>(\n    name: NewMethodKey,\n  ): ConfigurableModuleBuilder<Opts, NewMethodKey, FactoryMethodKey, Extras> {\n    this.classMethodName = name;\n    return this as unknown as ConfigurableModuleBuilder<\n      Opts,\n      NewMethodKey,\n      FactoryMethodKey,\n      Extras\n    >;\n  }\n\n  /** Rename the method a `useClass`/`useExisting` options factory must implement (default `create`). */\n  setFactoryMethodName<NewFactoryMethodKey extends string>(\n    name: NewFactoryMethodKey,\n  ): ConfigurableModuleBuilder<Opts, MethodKey, NewFactoryMethodKey, Extras> {\n    this.factoryMethodName = name;\n    return this as unknown as ConfigurableModuleBuilder<\n      Opts,\n      MethodKey,\n      NewFactoryMethodKey,\n      Extras\n    >;\n  }\n\n  build(): ConfigurableModuleHost<Opts, MethodKey, FactoryMethodKey, Extras> {\n    return defineModule<Opts, Extras, MethodKey, FactoryMethodKey>({\n      name: this.options.moduleName ?? 'ConfigurableModule',\n      optionsToken: this.options.optionsInjectionToken as InjectionToken<Opts> | undefined,\n      extras: this.extrasDefaults as Extras | undefined,\n      transform: this.extrasTransform as ConfigurableModuleExtrasTransform<Extras> | undefined,\n      methodName: this.classMethodName as MethodKey,\n      factoryMethodName: this.factoryMethodName as FactoryMethodKey,\n    });\n  }\n}\n\n/**\n * Lower-level engine for cases a class-mixin can't express — chiefly a\n * runtime-generated module class whose providers depend on a call-time arg\n * (Cloudflare binding modules). Returns an object with a single static named by\n * `spec.methodName` (default `forRoot`).\n */\nexport function defineConfigurableModule<Args>(\n  spec: DefineConfigurableModuleSpec<Args>,\n): Record<string, (args: Args) => DynamicModule> {\n  const methodName = spec.methodName ?? 'forRoot';\n  return {\n    [methodName](args: Args): DynamicModule {\n      const definition: DynamicModule = {\n        module: spec.module,\n        key: spec.keyFrom(args),\n        providers: spec.providers(args),\n      };\n      if (spec.imports) definition.imports = spec.imports(args);\n      if (spec.exports) definition.exports = spec.exports;\n      if (spec.global) definition.global = true;\n      return definition;\n    },\n  };\n}\n"],"mappings":";;;;;;;;AAkBA,MAAa,YAA0C;;;;;;;;;;;;;;;;;;;;;;;;AAyBvD,IAAa,4BAAb,MAKE;CAM6B;CAL7B,kBAA0B;CAC1B,oBAA4B;CAC5B;CACA;CAEA,YAAY,UAA6D,CAAC,GAAG;EAAhD,KAAA,UAAA;CAAiD;;CAG9E,UACE,UACA,WACyE;EACzE,KAAK,iBAAiB;EACtB,KAAK,kBAAkB;EACvB,OAAO;CAMT;;CAGA,mBACE,MACyE;EACzE,KAAK,kBAAkB;EACvB,OAAO;CAMT;;CAGA,qBACE,MACyE;EACzE,KAAK,oBAAoB;EACzB,OAAO;CAMT;CAEA,QAA2E;EACzE,OAAO,aAAwD;GAC7D,MAAM,KAAK,QAAQ,cAAc;GACjC,cAAc,KAAK,QAAQ;GAC3B,QAAQ,KAAK;GACb,WAAW,KAAK;GAChB,YAAY,KAAK;GACjB,mBAAmB,KAAK;EAC1B,CAAC;CACH;AACF;;;;;;;AAQA,SAAgB,yBACd,MAC+C;CAE/C,OAAO,EACL,CAFiB,KAAK,cAAc,WAEvB,MAA2B;EACtC,MAAM,aAA4B;GAChC,QAAQ,KAAK;GACb,KAAK,KAAK,QAAQ,IAAI;GACtB,WAAW,KAAK,UAAU,IAAI;EAChC;EACA,IAAI,KAAK,SAAS,WAAW,UAAU,KAAK,QAAQ,IAAI;EACxD,IAAI,KAAK,SAAS,WAAW,UAAU,KAAK;EAC5C,IAAI,KAAK,QAAQ,WAAW,SAAS;EACrC,OAAO;CACT,EACF;AACF"}