@velajs/vela 1.10.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,162 @@
 # Changelog
 
+## Unreleased
+
+Cold-start laziness (roadmap phase 3): modules can defer their entire init to
+first use, and the in-core subsystems an HTTP-only worker doesn't touch now
+cost it nothing at bootstrap.
+
+### Added
+
+- **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:
+  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
+  resolution stack unwinds, the group materializes and its
+  `onModuleInit`/`onApplicationBootstrap` hooks replay in registration order,
+  exactly once (memoized). Materialized instances join the instance flow so
+  shutdown hooks stay symmetric; untouched modules get neither init nor
+  shutdown hooks. Triggers during bootstrap absorb the group into the normal
+  hook phases, ordered dependency-before-consumer. `useValue` reads (options
+  tokens) do not trigger. Sync seams (`app.get`, the request pipeline) throw
+  a descriptive error for lazy modules with async providers/hooks — reach
+  those through `app.materializeLazyModules()` (the new warmup escape hatch)
+  or keep them sync. Authoring contract: MODULE_AUTHORING.md "Lazy modules".
+- **`app.materializeLazyModules()`** — materialize every still-pending lazy
+  module (async-safe); warmup/eager-everything escape hatch.
+- **`Container.isLazyPending(token)` / `Container.isInstantiated(token)`** —
+  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
+  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)
+  materialize the owning module at dispatch time. `ContributesEntrypoints`
+  providers in lazy modules are materialized right before the snapshot —
+  computed contributions can't defer (documented cost).
+
+### Changed
+
+- **`EventEmitterModule`, `ScheduleModule`, `SeederModule`, `I18nModule` are
+  now lazy.** An HTTP-only worker that imports them but never emits an event,
+  reads the schedule registry, runs seeders, or translates pays zero
+  cold-start cost for them — no subscriber wiring pass, no `@Cron` discovery
+  walk, no merged-message snapshot. Every consumer path is a trigger, so
+  observable behavior is unchanged (`app.get(EventEmitter).emit(...)` wires
+  subscribers first; `runSeeders()` populates the registry via hook replay).
+  `WebSocketModule` and `ScheduleNodeModule` deliberately stay eager (gateway
+  injection drags the WS chain in anyway; the node executor is self-driving).
+- `ModuleLoader.resolveAllInstances()` skips tokens owned exclusively by lazy
+  module instances; a token also registered by a non-lazy module stays on the
+  eager pass. Route building no longer instantiate-probes middleware tokens
+  that are lazy-pending (default priority 0) — the probe would have defeated
+  i18n's deferral at route build.
+
+## 1.12.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

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,8 +10,12 @@ export declare class VelaApplication {
     private readonly routeManager;
     private instances;
     private honoApp;
+    private entrypointRegistry;
     private disposed;
+    private readonly lazyManager;
+    private readonly knownInstances;
     constructor(container: Container, routeManager: RouteManager);
+    private trackNew;
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */
     initRoutes(): Promise<void>;
     private getApp;
@@ -42,8 +47,28 @@ export declare class VelaApplication {
      * ```
      */
     mountOpenApi(options: MountOpenApiOptions): this;
+    /**
+     * Pull instances materialized during the bootstrap phase (lazy modules
+     * dragged in by eager consumers) into the front of the instance list —
+     * dependency-before-consumer: a group absorbed because an eager provider
+     * injected it must be initialized before that consumer's hooks read it.
+     */
+    private absorbLazyInstances;
     callOnModuleInit(): Promise<void>;
     callOnApplicationBootstrap(): Promise<void>;
+    /**
+     * Materialize every still-pending lazy module (async-safe): construct the
+     * groups, replay their lifecycle hooks, and add their instances to the
+     * shutdown flow. Warmup escape hatch for tests and node runtimes that want
+     * eager-everything semantics back after bootstrap.
+     */
+    materializeLazyModules(): 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

package/dist/application.js

@@ -1,3 +1,6 @@
+import { DiscoveryService } from "./discovery/discovery.service.js";
+import { EntrypointRegistry } from "./entrypoint/entrypoint.registry.js";
+import { LazyModuleManager } from "./module/lazy-modules.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,10 +10,29 @@ export class VelaApplication {
     routeManager;
     instances = [];
     honoApp = null;
+    entrypointRegistry = null;
     disposed = false;
+    lazyManager;
+    // Identity guard for the instance flow: a token registered by BOTH a lazy
+    // and an eager module reaches us through the eager pass AND the absorbed
+    // batch — without dedup its hooks would run twice.
+    knownInstances = new Set();
     constructor(container, routeManager){
         this.container = container;
         this.routeManager = routeManager;
+        // bootstrap() registers the manager; a hand-built container may not have
+        // one (container unit tests) — lazy semantics simply don't engage then.
+        this.lazyManager = container.has(LazyModuleManager) ? container.resolve(LazyModuleManager) : undefined;
+        // Live-phase materializations join the instance flow so close()/dispose()
+        // run shutdown hooks over them (LIFO — appended last, destroyed first).
+        this.lazyManager?.setOnMaterialized((instances)=>{
+            this.instances.push(...this.trackNew(instances));
+        });
+    }
+    trackNew(batch) {
+        const fresh = batch.filter((i)=>!this.knownInstances.has(i));
+        for (const i of fresh)this.knownInstances.add(i);
+        return fresh;
     }
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */ async initRoutes() {
         this.honoApp = await this.routeManager.build();
@@ -32,6 +54,8 @@ export class VelaApplication {
     }
     setInstances(instances) {
         this.instances = instances;
+        this.knownInstances.clear();
+        for (const i of instances)this.knownInstances.add(i);
     }
     get(token) {
         return this.container.resolve(token);
@@ -124,19 +148,96 @@ export class VelaApplication {
         return this;
     }
     // Lifecycle hooks
+    /**
+   * Pull instances materialized during the bootstrap phase (lazy modules
+   * dragged in by eager consumers) into the front of the instance list —
+   * dependency-before-consumer: a group absorbed because an eager provider
+   * injected it must be initialized before that consumer's hooks read it.
+   */ absorbLazyInstances(prepend) {
+        const batch = this.trackNew(this.lazyManager?.takeAbsorbed() ?? []);
+        if (batch.length === 0) return batch;
+        if (prepend) {
+            this.instances = [
+                ...batch,
+                ...this.instances
+            ];
+        } else {
+            this.instances.push(...batch);
+        }
+        return batch;
+    }
     async callOnModuleInit() {
-        for (const instance of this.instances){
+        this.absorbLazyInstances(true);
+        // Index loop: hooks can trigger further absorptions, which append —
+        // the loop naturally covers them.
+        for(let i = 0; i < this.instances.length; i++){
+            const instance = this.instances[i];
             if (hasOnModuleInit(instance)) {
                 await instance.onModuleInit();
             }
+            this.absorbLazyInstances(false);
         }
     }
     async callOnApplicationBootstrap() {
-        for (const instance of this.instances){
+        for(let i = 0; i < this.instances.length; i++){
+            const instance = this.instances[i];
             if (hasOnApplicationBootstrap(instance)) {
                 await instance.onApplicationBootstrap();
             }
+            // Instances absorbed mid-phase already missed the init pass — run
+            // onModuleInit now; the loop then reaches them for the bootstrap hook.
+            for (const late of this.absorbLazyInstances(false)){
+                if (hasOnModuleInit(late)) await late.onModuleInit();
+            }
+        }
+        // Computed-entrypoint contributors (ContributesEntrypoints) in lazy
+        // modules must exist before the snapshot below — materialize them now
+        // (the documented cost of contributing computed entrypoints), then run
+        // their hooks through the same absorb loop.
+        if (this.lazyManager) {
+            await this.lazyManager.materializeContributors();
+            let batch;
+            while((batch = this.absorbLazyInstances(false)).length > 0){
+                for (const late of batch){
+                    if (hasOnModuleInit(late)) await late.onModuleInit();
+                }
+                for (const late of batch){
+                    if (hasOnApplicationBootstrap(late)) await late.onApplicationBootstrap();
+                }
+            }
+            // From here on, materializations replay their hooks at the trigger.
+            this.lazyManager.setPhaseLive();
+        }
+        // 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`.
+        // Lazy-pending providers of declared kinds yield metadata-only entries
+        // (instance: undefined) — dispatchers re-resolve by token per event,
+        // which materializes the owning module at dispatch time.
+        const discovery = this.container.has(DiscoveryService) ? this.container.resolve(DiscoveryService) : new DiscoveryService(this.container);
+        this.entrypointRegistry = await EntrypointRegistry.build(discovery, this.instances, {
+            deferLazy: true
+        });
+    }
+    /**
+   * Materialize every still-pending lazy module (async-safe): construct the
+   * groups, replay their lifecycle hooks, and add their instances to the
+   * shutdown flow. Warmup escape hatch for tests and node runtimes that want
+   * eager-everything semantics back after bootstrap.
+   */ async materializeLazyModules() {
+        await this.lazyManager?.materializeAll();
+    }
+    /**
+   * 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 = [

package/dist/container/container.d.ts

@@ -1,5 +1,5 @@
 import { Scope } from '../constants';
-import type { ContainerOptions, Diagnostics, ModuleScope, ProviderOptions, Token, Type } from './types';
+import type { ContainerOptions, Diagnostics, LazyResolutionHook, 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
@@ -19,7 +19,13 @@ export declare class Container {
     private diagnostics;
     private root;
     private disposables;
+    private lazyHook?;
+    private asyncDepth;
     constructor(options?: ContainerOptions);
+    /** Install the lazy-module seam (bootstrap-time; root container only). */
+    setLazyHook(hook: LazyResolutionHook): void;
+    private claimLazyModule;
+    private maybeDrainSync;
     register<T>(provider: Type<T> | ProviderOptions<T>, declaringModuleId?: string): this;
     private registerClass;
     private registerOptions;
@@ -52,6 +58,34 @@ export declare class Container {
     has(token: Token): boolean;
     /** True if the specified module's bucket has a registration for `token`. */
     hasInScope(token: Token, moduleId: string): boolean;
+    /** Module buckets that hold a registration for `token` (registration order). */
+    getOwnerModuleIds(token: Token): string[];
+    /**
+     * Force-replace a provider across module scopes — the supported form of the
+     * override loop test harnesses need (module-scoped resolution consults the
+     * module's own bucket first, so a root-only override would never win there).
+     *
+     * - `'all-existing'` (default): every non-root bucket that already holds the
+     *   token, plus `__root__` (so framework-internal lookups see it too).
+     * - `'root'`: only the `__root__` bucket.
+     * - `string[]`: exactly these bucket ids.
+     */
+    replaceProvider<T>(provider: Type<T> | ProviderOptions<T>, options?: {
+        buckets?: 'all-existing' | 'root' | string[];
+    }): this;
+    /**
+     * True when the token belongs exclusively to lazy modules that have not
+     * been materialized yet — resolving it would trigger materialization.
+     * Build-time probes (route-manager middleware priority, entrypoint
+     * snapshots) use this to defer instead of forcing the group.
+     */
+    isLazyPending(token: Token): boolean;
+    /**
+     * True when any registration of the token holds a constructed instance.
+     * Diagnostic helper (cold-start tests): checks WITHOUT resolving, so it
+     * never triggers lazy materialization.
+     */
+    isInstantiated(token: Token): boolean;
     getProviderScope(token: Token): Scope | undefined;
     getTokens(): Token[];
     /**
@@ -95,8 +129,19 @@ export declare class Container {
     dispose(): Promise<void>;
     private resolveRegistration;
     private resolveClass;
+    /**
+     * Resolve one factory `inject` dependency. Since 1.11 the declaring module's
+     * scope is consulted FIRST (proper visibility semantics — a `forRootAsync`
+     * factory can inject providers reachable through its module's imports); on
+     * any failure the legacy no-requester lookup (root bucket, then first
+     * exporter) is kept as fallback, so every previously-resolving graph still
+     * resolves.
+     */
+    private resolveFactoryDependency;
+    private resolveFactoryDependencyAsync;
     private resolveFactory;
     resolveAsync<T>(token: Token<T>, requestingModuleId?: string): Promise<T>;
+    private resolveAsyncInner;
     private createLazyProxy;
     private tokenToString;
 }