@velajs/vela 1.10.0 → 1.13.0

package/dist/discovery/discovery.service.js

@@ -0,0 +1,177 @@
+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;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Scope } from "../constants.js";
+import { Container } from "../container/container.js";
+import { Inject, Injectable } from "../container/decorators.js";
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+function isMethodMetaItem(x) {
+    return typeof x === 'object' && x !== null && (typeof x.methodName === 'string' || typeof x.methodName === 'symbol');
+}
+function resolveKey(key) {
+    return typeof key === 'string' ? key : key.KEY;
+}
+export class DiscoveryService {
+    container;
+    constructor(container){
+        this.container = container;
+    }
+    /** Every class-token provider registered in the container. */ getProviders(filter) {
+        const out = [];
+        for (const token of this.container.getTokens()){
+            if (typeof token !== 'function') continue;
+            const entry = this.buildEntry(token, filter, 'provider discovery');
+            if (entry) out.push(entry);
+        }
+        return out;
+    }
+    /**
+   * Providers whose class carries class-level metadata under `key` — both
+   * class decorators (single value) and method decorators that append
+   * class-level lists (`@Cron`, `@OnEvent`, `@SubscribeMessage`).
+   */ providersWithMeta(key, filter) {
+        const metaKey = resolveKey(key);
+        const out = [];
+        for (const target of this.candidatesWithClassMeta(metaKey)){
+            const entry = this.buildEntry(target, filter, `discovery of '${metaKey}'`);
+            if (!entry) continue;
+            const meta = MetadataRegistry.getCustomClassMeta(target, metaKey);
+            out.push({
+                ...entry,
+                meta
+            });
+        }
+        return out;
+    }
+    /**
+   * Handler methods carrying metadata under `key`. Merges the two storage
+   * conventions:
+   *  - class-level appended lists whose items carry `methodName`
+   *    (`@Cron`/`@OnEvent`-style method decorators), and
+   *  - true handler-level metadata (`@SetMetadata`/`createDiscoverableDecorator`
+   *    applied to a method).
+   */ methodsWithMeta(key, filter) {
+        const metaKey = resolveKey(key);
+        const out = [];
+        for (const target of this.candidatesWithClassMeta(metaKey)){
+            const classMeta = MetadataRegistry.getCustomClassMeta(target, metaKey);
+            if (!Array.isArray(classMeta) || !classMeta.some(isMethodMetaItem)) continue;
+            const entry = this.buildEntry(target, filter, `discovery of '${metaKey}'`);
+            if (!entry) continue;
+            for (const item of classMeta){
+                if (!isMethodMetaItem(item)) continue;
+                out.push({
+                    class: entry,
+                    methodName: item.methodName,
+                    meta: item
+                });
+            }
+        }
+        for (const target of MetadataRegistry.getClassesWithHandlerMeta(metaKey)){
+            if (!this.container.has(target)) continue;
+            const entry = this.buildEntry(target, filter, `discovery of '${metaKey}'`);
+            if (!entry) continue;
+            for (const { handler, value } of MetadataRegistry.getHandlersWithMeta(target, metaKey)){
+                out.push({
+                    class: entry,
+                    methodName: handler,
+                    meta: value
+                });
+            }
+        }
+        return out;
+    }
+    /**
+   * Index-first candidate walk with a legacy full-scan fallback: when the
+   * reverse index knows nothing about a key, an older copy of the registry
+   * module may have taken the writes (mixed dist/src or package versions in
+   * one process) — fall back to scanning container tokens the way the
+   * pre-DiscoveryService loops did.
+   */ candidatesWithClassMeta(metaKey) {
+        const indexed = MetadataRegistry.getClassesWithClassMeta(metaKey);
+        if (indexed.size > 0) {
+            return [
+                ...indexed
+            ].filter((t)=>this.container.has(t));
+        }
+        const out = [];
+        for (const token of this.container.getTokens()){
+            if (typeof token !== 'function') continue;
+            if (MetadataRegistry.getCustomClassMeta(token, metaKey) !== undefined) {
+                out.push(token);
+            }
+        }
+        return out;
+    }
+    buildEntry(metatype, filter, label) {
+        const moduleIds = this.container.getOwnerModuleIds(metatype);
+        if (moduleIds.length === 0) return undefined;
+        if (filter?.moduleId !== undefined) {
+            const wanted = Array.isArray(filter.moduleId) ? filter.moduleId : [
+                filter.moduleId
+            ];
+            if (!moduleIds.some((id)=>wanted.includes(id))) return undefined;
+        }
+        const scope = this.container.getProviderScope(metatype) ?? Scope.SINGLETON;
+        if (filter?.deferLazy && this.container.isLazyPending(metatype)) {
+            // Deliberate deferral — no diagnostics warning: the entry is complete
+            // metadata-wise and consumers re-resolve by token at dispatch time.
+            return {
+                token: metatype,
+                metatype,
+                moduleIds,
+                scope,
+                instance: undefined
+            };
+        }
+        if (scope === Scope.REQUEST && !filter?.includeRequestScoped) {
+            if (this.container.getDiagnostics() === 'log') {
+                console.warn(`[vela] ${label}: ${metatype.name} is request-scoped and cannot be ` + `materialized at bootstrap — skipped. Pass { includeRequestScoped: true } to override.`);
+            }
+            return {
+                token: metatype,
+                metatype,
+                moduleIds,
+                scope,
+                instance: undefined
+            };
+        }
+        let instance;
+        try {
+            instance = this.container.resolve(metatype);
+        } catch (err) {
+            const mode = this.container.getDiagnostics();
+            if (mode === 'throw') throw err;
+            if (mode === 'log') {
+                console.warn(`[vela] ${label}: cannot resolve ${metatype.name}:`, err);
+            }
+            return undefined;
+        }
+        return {
+            token: metatype,
+            metatype,
+            moduleIds,
+            scope,
+            instance
+        };
+    }
+}
+DiscoveryService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(Container)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Container === "undefined" ? Object : Container
+    ])
+], DiscoveryService);

package/dist/discovery/index.d.ts

@@ -0,0 +1,2 @@
+export { DiscoveryService, type DiscoveredClass, type DiscoveredMethodMeta, type DiscoveryFilter, } from './discovery.service';
+export { createDiscoverableDecorator, type CreateDiscoverableDecoratorOptions, type DiscoverableDecorator, } from './discoverable.decorator';

package/dist/discovery/index.js

@@ -0,0 +1,2 @@
+export { DiscoveryService } from "./discovery.service.js";
+export { createDiscoverableDecorator } from "./discoverable.decorator.js";

package/dist/entrypoint/entrypoint.registry.d.ts

@@ -0,0 +1,42 @@
+import type { DiscoveryService } from '../discovery/discovery.service';
+import { type Entrypoint, type EntrypointKind } from './entrypoint.types';
+/**
+ * Declare an entrypoint kind. Idempotent per `kind` (last declaration wins so
+ * an HMR-re-evaluated module can re-declare); typically called at module
+ * import time next to the decorator definition:
+ *
+ * ```ts
+ * export const WS_GATEWAY_METADATA = 'vela:ws:gateway';
+ * registerEntrypointKind({ kind: 'websocket', metaKey: WS_GATEWAY_METADATA, level: 'class' });
+ * ```
+ */
+export declare function registerEntrypointKind(k: EntrypointKind): void;
+/** All declared kinds (registration order). */
+export declare function getEntrypointKinds(): EntrypointKind[];
+/**
+ * Reset all kind declarations. Test-only.
+ * @internal
+ */
+export declare function _resetEntrypointKinds(): void;
+/**
+ * The per-application view of every entrypoint: built once after
+ * `onApplicationBootstrap` hooks have run (so `ContributesEntrypoints`
+ * providers have finished their own discovery), queried by runtime adapters:
+ *
+ * ```ts
+ * for (const ep of app.entrypoints.ofKind('websocket')) { ... }
+ * ```
+ *
+ * Per-app (never global): two applications in one process each build their
+ * own registry from their own container.
+ */
+export declare class EntrypointRegistry {
+    private readonly byKind;
+    static build(discovery: DiscoveryService, eagerInstances: readonly unknown[], options?: {
+        deferLazy?: boolean;
+    }): Promise<EntrypointRegistry>;
+    private add;
+    ofKind<M = unknown>(kind: string): Entrypoint<M>[];
+    kinds(): string[];
+    all(): Entrypoint[];
+}

package/dist/entrypoint/entrypoint.registry.js

@@ -0,0 +1,112 @@
+import { contributesEntrypoints } from "./entrypoint.types.js";
+// Kind declarations are process-global and import-time (a module declares its
+// kind next to its decorator, before any app exists), so they are anchored on
+// `globalThis` exactly like MetadataRegistry state: a Vite HMR re-eval must
+// reuse the same store, not mint an empty one.
+const KIND_STORE_KEY = Symbol.for('vela:entrypoints:v1');
+function kindStore() {
+    const g = globalThis;
+    return g[KIND_STORE_KEY] ??= new Map();
+}
+/**
+ * Declare an entrypoint kind. Idempotent per `kind` (last declaration wins so
+ * an HMR-re-evaluated module can re-declare); typically called at module
+ * import time next to the decorator definition:
+ *
+ * ```ts
+ * export const WS_GATEWAY_METADATA = 'vela:ws:gateway';
+ * registerEntrypointKind({ kind: 'websocket', metaKey: WS_GATEWAY_METADATA, level: 'class' });
+ * ```
+ */ export function registerEntrypointKind(k) {
+    kindStore().set(k.kind, k);
+}
+/** All declared kinds (registration order). */ export function getEntrypointKinds() {
+    return [
+        ...kindStore().values()
+    ];
+}
+/**
+ * Reset all kind declarations. Test-only.
+ * @internal
+ */ export function _resetEntrypointKinds() {
+    kindStore().clear();
+}
+/**
+ * The per-application view of every entrypoint: built once after
+ * `onApplicationBootstrap` hooks have run (so `ContributesEntrypoints`
+ * providers have finished their own discovery), queried by runtime adapters:
+ *
+ * ```ts
+ * for (const ep of app.entrypoints.ofKind('websocket')) { ... }
+ * ```
+ *
+ * Per-app (never global): two applications in one process each build their
+ * own registry from their own container.
+ */ export class EntrypointRegistry {
+    byKind = new Map();
+    static async build(discovery, eagerInstances, options = {}) {
+        const registry = new EntrypointRegistry();
+        // With deferLazy, providers of unmaterialized lazy modules yield
+        // metadata-only entries (instance: undefined). Dispatchers re-resolve by
+        // token per event, so the owning module materializes at dispatch time.
+        const filter = options.deferLazy ? {
+            deferLazy: true
+        } : undefined;
+        for (const kind of getEntrypointKinds()){
+            if (kind.level === 'class') {
+                for (const found of discovery.providersWithMeta(kind.metaKey, filter)){
+                    registry.add({
+                        kind: kind.kind,
+                        token: found.token,
+                        instance: found.instance,
+                        meta: found.meta
+                    });
+                }
+            } else {
+                for (const found of discovery.methodsWithMeta(kind.metaKey, filter)){
+                    registry.add({
+                        kind: kind.kind,
+                        token: found.class.token,
+                        instance: found.class.instance,
+                        methodName: found.methodName,
+                        meta: found.meta
+                    });
+                }
+            }
+        }
+        // Computed contributions. A contributor is AUTHORITATIVE for every kind it
+        // reports: its entries replace any metaKey-derived ones of the same kind,
+        // so a dispatcher that both carries decorator metadata and computes richer
+        // entries (path routing, aggregated handlers) never double-reports.
+        const contributed = [];
+        for (const instance of new Set(eagerInstances)){
+            if (!contributesEntrypoints(instance)) continue;
+            contributed.push(...await instance.collectEntrypoints(discovery));
+        }
+        for (const kind of new Set(contributed.map((ep)=>ep.kind))){
+            registry.byKind.delete(kind);
+        }
+        for (const ep of contributed)registry.add(ep);
+        return registry;
+    }
+    add(ep) {
+        const list = this.byKind.get(ep.kind);
+        if (list) list.push(ep);
+        else this.byKind.set(ep.kind, [
+            ep
+        ]);
+    }
+    ofKind(kind) {
+        return this.byKind.get(kind) ?? [];
+    }
+    kinds() {
+        return [
+            ...this.byKind.keys()
+        ];
+    }
+    all() {
+        return [
+            ...this.byKind.values()
+        ].flat();
+    }
+}

package/dist/entrypoint/entrypoint.types.d.ts

@@ -0,0 +1,41 @@
+import type { Token } from '../container/types';
+import type { DiscoveryService } from '../discovery/discovery.service';
+/**
+ * A declared entrypoint kind: a named category of non-HTTP (or non-standard)
+ * entry surface that some module knows how to dispatch — WebSocket gateways,
+ * queue consumers, scheduled jobs, CLI commands. Core ships NO fixed set;
+ * any module registers its own kind and any runtime adapter can query it.
+ *
+ * `metaKey` binds the kind to a decorator's metadata key: every provider
+ * carrying that metadata becomes an entrypoint of this kind at bootstrap.
+ */
+export interface EntrypointKind {
+    kind: string;
+    metaKey: string;
+    /**
+     * 'class': one entrypoint per decorated provider (`@WebSocketGateway`).
+     * 'method': one entrypoint per decorated method (`@Cron`, `@QueueConsumer`
+     * handler methods) — flattened from the class-level list convention.
+     */
+    level: 'class' | 'method';
+}
+/** One concrete entrypoint discovered at bootstrap. */
+export interface Entrypoint<M = unknown> {
+    kind: string;
+    token: Token;
+    /** The resolved provider backing the entrypoint (undefined if request-scoped). */
+    instance: unknown;
+    /** Present for method-level kinds. */
+    methodName?: string | symbol;
+    meta: M;
+}
+/**
+ * Escape hatch for providers whose entrypoints are computed rather than purely
+ * decorator-declared (e.g. `WsDispatcher` aggregates per-gateway routing state
+ * before contributing). Implementers are detected among the app's eagerly
+ * instantiated providers after `onApplicationBootstrap` hooks have run.
+ */
+export interface ContributesEntrypoints {
+    collectEntrypoints(discovery: DiscoveryService): Entrypoint[] | Promise<Entrypoint[]>;
+}
+export declare function contributesEntrypoints(x: unknown): x is ContributesEntrypoints;

package/dist/entrypoint/entrypoint.types.js

@@ -0,0 +1,3 @@
+export function contributesEntrypoints(x) {
+    return typeof x === 'object' && x !== null && typeof x.collectEntrypoints === 'function';
+}

package/dist/entrypoint/execution-context.d.ts

@@ -0,0 +1,15 @@
+import type { Type } from '../container/types';
+import type { ExecutionContext } from '../pipeline/types';
+/** ExecutionContext flavor handed to components around entrypoint dispatch. */
+export interface EntrypointExecutionContext extends ExecutionContext {
+    /** The dispatch payload (queue batch, scheduled event, …). */
+    getPayload<T = unknown>(): T;
+}
+/**
+ * Entrypoint sibling of `buildExecutionContext` (HTTP) and
+ * `buildWsExecutionContext`: lets guards/interceptors/filters written against
+ * `getClass()`/`getHandler()`/`getType()` run unchanged around queue batches,
+ * scheduled ticks, and any custom entrypoint kind. Transport-specific
+ * accessors throw rather than fabricate fakes.
+ */
+export declare function buildEntrypointExecutionContext(kind: string, targetClass: Type, handlerName: string | symbol, payload: unknown): EntrypointExecutionContext;

package/dist/entrypoint/execution-context.js

@@ -0,0 +1,21 @@
+const WRONG_TRANSPORT = (accessor, kind)=>()=>{
+        throw new Error(`${accessor} called on a '${kind}' entrypoint ExecutionContext — this ` + `handler runs over an entrypoint dispatch, not that transport. Use ` + `getType()/getPayload() to branch.`);
+    };
+/**
+ * Entrypoint sibling of `buildExecutionContext` (HTTP) and
+ * `buildWsExecutionContext`: lets guards/interceptors/filters written against
+ * `getClass()`/`getHandler()`/`getType()` run unchanged around queue batches,
+ * scheduled ticks, and any custom entrypoint kind. Transport-specific
+ * accessors throw rather than fabricate fakes.
+ */ export function buildEntrypointExecutionContext(kind, targetClass, handlerName, payload) {
+    return {
+        getType: ()=>kind,
+        getClass: ()=>targetClass,
+        getHandler: ()=>handlerName,
+        getPayload: ()=>payload,
+        getContext: WRONG_TRANSPORT('getContext()', kind),
+        getRequest: WRONG_TRANSPORT('getRequest()', kind),
+        switchToHttp: WRONG_TRANSPORT('switchToHttp()', kind),
+        switchToWs: WRONG_TRANSPORT('switchToWs()', kind)
+    };
+}

package/dist/entrypoint/execution-scope.d.ts

@@ -0,0 +1,21 @@
+import type { Container } from '../container/container';
+/**
+ * Run one unit of non-HTTP work (a queue batch, a scheduled tick, an RPC
+ * call) inside a fresh request-scoped child container — the non-HTTP
+ * equivalent of the per-request child the HTTP pipeline creates:
+ *
+ * ```ts
+ * await runInEntrypointScope(app.getContainer(), async (scope) => {
+ *   const consumer = scope.resolve(ep.token);
+ *   await consumer.process(batch);
+ * });
+ * ```
+ *
+ * Request-scoped providers (and singletons bubbled to request scope) resolve
+ * per invocation instead of leaking one boot-time instance across every
+ * dispatch; the child's request-scoped disposables are disposed (LIFO) when
+ * `fn` settles — success or failure. `REQUEST_CONTEXT` is deliberately NOT
+ * seeded: it is an HTTP primitive, and resolving it here keeps throwing its
+ * explicit misuse error.
+ */
+export declare function runInEntrypointScope<T>(container: Container, fn: (scope: Container) => T | Promise<T>): Promise<T>;

package/dist/entrypoint/execution-scope.js

@@ -0,0 +1,28 @@
+/**
+ * Run one unit of non-HTTP work (a queue batch, a scheduled tick, an RPC
+ * call) inside a fresh request-scoped child container — the non-HTTP
+ * equivalent of the per-request child the HTTP pipeline creates:
+ *
+ * ```ts
+ * await runInEntrypointScope(app.getContainer(), async (scope) => {
+ *   const consumer = scope.resolve(ep.token);
+ *   await consumer.process(batch);
+ * });
+ * ```
+ *
+ * Request-scoped providers (and singletons bubbled to request scope) resolve
+ * per invocation instead of leaking one boot-time instance across every
+ * dispatch; the child's request-scoped disposables are disposed (LIFO) when
+ * `fn` settles — success or failure. `REQUEST_CONTEXT` is deliberately NOT
+ * seeded: it is an HTTP primitive, and resolving it here keeps throwing its
+ * explicit misuse error.
+ */ export async function runInEntrypointScope(container, fn) {
+    const scope = container.createChild();
+    try {
+        return await fn(scope);
+    } finally{
+        if (scope.hasDisposables()) {
+            await scope.dispose();
+        }
+    }
+}

package/dist/entrypoint/index.d.ts

@@ -0,0 +1,4 @@
+export { EntrypointRegistry, getEntrypointKinds, registerEntrypointKind, } from './entrypoint.registry';
+export { runInEntrypointScope } from './execution-scope';
+export { buildEntrypointExecutionContext, type EntrypointExecutionContext, } from './execution-context';
+export { contributesEntrypoints, type ContributesEntrypoints, type Entrypoint, type EntrypointKind, } from './entrypoint.types';

package/dist/entrypoint/index.js

@@ -0,0 +1,4 @@
+export { EntrypointRegistry, getEntrypointKinds, registerEntrypointKind } from "./entrypoint.registry.js";
+export { runInEntrypointScope } from "./execution-scope.js";
+export { buildEntrypointExecutionContext } from "./execution-context.js";
+export { contributesEntrypoints } from "./entrypoint.types.js";

package/dist/event-emitter/event-emitter.module.js

@@ -11,6 +11,7 @@ export class EventEmitterModule {
 }
 EventEmitterModule = _ts_decorate([
     Module({
+        lazy: true,
         providers: [
             EventEmitter,
             EventEmitterSubscriber

package/dist/event-emitter/event-emitter.subscriber.d.ts

@@ -1,9 +1,9 @@
-import { Container } from '../container/container';
+import { DiscoveryService } from '../discovery/discovery.service';
 import type { OnApplicationBootstrap } from '../lifecycle/index';
 import { EventEmitter } from './event-emitter.service';
 export declare class EventEmitterSubscriber implements OnApplicationBootstrap {
-    private container;
+    private readonly discovery;
     private emitter;
-    constructor(container: Container, emitter: EventEmitter);
+    constructor(discovery: DiscoveryService, emitter: EventEmitter);
     onApplicationBootstrap(): void;
 }

package/dist/event-emitter/event-emitter.subscriber.js

@@ -13,50 +13,33 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 import { Injectable, Inject } from "../container/index.js";
-import { Container } from "../container/container.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { DiscoveryService } from "../discovery/discovery.service.js";
 import { EventEmitter } from "./event-emitter.service.js";
 import { ON_EVENT_METADATA } from "./event-emitter.tokens.js";
 export class EventEmitterSubscriber {
-    container;
+    discovery;
     emitter;
-    constructor(container, emitter){
-        this.container = container;
+    constructor(discovery, emitter){
+        this.discovery = discovery;
         this.emitter = emitter;
     }
     onApplicationBootstrap() {
-        const tokens = this.container.getTokens();
-        for (const token of tokens){
-            // Skip non-class tokens
-            if (typeof token !== 'function') continue;
-            const metadata = MetadataRegistry.getCustomClassMeta(token, ON_EVENT_METADATA);
-            if (!metadata || metadata.length === 0) continue;
-            let instance;
-            try {
-                instance = this.container.resolve(token);
-            } catch (err) {
-                const mode = this.container.getDiagnostics();
-                if (mode === 'throw') throw err;
-                if (mode === 'log') {
-                    console.warn(`[vela] event subscriber discovery: cannot resolve ${token.name || String(token)}:`, err);
-                }
-                continue;
-            }
-            for (const { event, methodName } of metadata){
-                const method = instance[methodName];
-                if (typeof method === 'function') {
-                    this.emitter.on(event, (...args)=>method.apply(instance, args));
-                }
+        for (const found of this.discovery.methodsWithMeta(ON_EVENT_METADATA)){
+            const instance = found.class.instance;
+            if (!instance) continue;
+            const method = instance[found.methodName];
+            if (typeof method === 'function') {
+                this.emitter.on(found.meta.event, (...args)=>method.apply(instance, args));
             }
         }
     }
 }
 EventEmitterSubscriber = _ts_decorate([
     Injectable(),
-    _ts_param(0, Inject(Container)),
+    _ts_param(0, Inject(DiscoveryService)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof Container === "undefined" ? Object : Container,
+        typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
         typeof EventEmitter === "undefined" ? Object : EventEmitter
     ])
 ], EventEmitterSubscriber);

package/dist/factory/adapter.d.ts

@@ -0,0 +1,36 @@
+import type { MiddlewareHandler } from 'hono';
+import type { VelaApplication } from '../application';
+import type { Container } from '../container/container';
+import type { DiscoveryService } from '../discovery/discovery.service';
+import type { RouteManager } from '../http/route.manager';
+/** The framework's resolved world, handed to adapter hooks. */
+export interface AdapterContext {
+    app: VelaApplication;
+    container: Container;
+    routeManager: RouteManager;
+    discovery: DiscoveryService;
+}
+/**
+ * The contract a runtime binding implements to plug a platform into a Vela
+ * app — what `@velajs/cloudflare` (bindings + Durable Object WebSocket) and
+ * the Node/Bun WebSocket transport do, made first-class:
+ *
+ * ```ts
+ * const app = await VelaFactory.create(AppModule, {
+ *   adapters: [cloudflareAdapter({ bindings })],
+ * });
+ * ```
+ *
+ * - `requestMiddleware` is prepended to the global middleware chain (runs
+ *   before consumer middleware — e.g. capture `c.env` for binding services).
+ * - `onBootstrap` runs after DI + lifecycle hooks, with `app.entrypoints`
+ *   available, BEFORE routes are built — register platform services here.
+ * - `onRoutesBuilt` runs after the Hono app exists — mount platform routes
+ *   (WebSocket upgrades, health endpoints) here via `ctx.app.getHonoApp()`.
+ */
+export interface RuntimeAdapter {
+    name: string;
+    requestMiddleware?: MiddlewareHandler[];
+    onBootstrap?(ctx: AdapterContext): void | Promise<void>;
+    onRoutesBuilt?(ctx: AdapterContext): void | Promise<void>;
+}

package/dist/factory/adapter.js

@@ -0,0 +1,18 @@
+/**
+ * The contract a runtime binding implements to plug a platform into a Vela
+ * app — what `@velajs/cloudflare` (bindings + Durable Object WebSocket) and
+ * the Node/Bun WebSocket transport do, made first-class:
+ *
+ * ```ts
+ * const app = await VelaFactory.create(AppModule, {
+ *   adapters: [cloudflareAdapter({ bindings })],
+ * });
+ * ```
+ *
+ * - `requestMiddleware` is prepended to the global middleware chain (runs
+ *   before consumer middleware — e.g. capture `c.env` for binding services).
+ * - `onBootstrap` runs after DI + lifecycle hooks, with `app.entrypoints`
+ *   available, BEFORE routes are built — register platform services here.
+ * - `onRoutesBuilt` runs after the Hono app exists — mount platform routes
+ *   (WebSocket upgrades, health endpoints) here via `ctx.app.getHonoApp()`.
+ */ export { };