@velajs/vela 1.19.0 → 1.19.1

package/dist/http/lazy-param.decorator.js

@@ -1,117 +0,0 @@
-import { MetadataRegistry } from "../registry/metadata.registry.js";
-import { buildExecutionContext } from "./execution-context.js";
-const CUSTOM_PARAM_TYPE = 'custom';
-/**
- * Factory for parameter decorators whose value materializes lazily — the
- * factory does not run during argument extraction; it runs the first time
- * the handler reads a property on the resolved value.
- *
- * Why this exists: vela's argument resolver runs *before* guards
- * (handler-executor order: extract args → guards → handler). A custom
- * `createParamDecorator` factory that depends on guard-populated state
- * (e.g. a value a guard places into `REQUEST_CONTEXT`) therefore observes
- * an empty slot. `createLazyParamDecorator` defers factory execution to
- * first property access on the proxied result, by which point guards have
- * run and the slot is populated.
- *
- * The proxy explicitly short-circuits `prop === 'then'` so `await value`
- * does not consider the proxy a thenable, which would otherwise trigger
- * eager resolution. This single invariant is what makes the helper safe to
- * pass through `async` boundaries without surprise.
- *
- * @example
- * ```ts
- * const CurrentUser = createLazyParamDecorator(
- *   (_data: unknown, ctx: ExecutionContext) => {
- *     const reqCtx = ctx.getContext().get('container').resolve(REQUEST_CONTEXT);
- *     return reqCtx.get('user');     // populated by AuthGuard
- *   },
- * );
- *
- * @UseGuards(AuthGuard)
- * @Get('/me')
- * me(@CurrentUser() user: User) {
- *   return { id: user.id };          // factory runs here, after AuthGuard
- * }
- * ```
- */ export function createLazyParamDecorator(factory) {
-    return (data, ...pipes)=>{
-        return (target, propertyKey, parameterIndex)=>{
-            if (propertyKey === undefined) {
-                throw new Error('Parameter decorators can only be used on method parameters');
-            }
-            MetadataRegistry.addParameter(target.constructor, propertyKey, {
-                index: parameterIndex,
-                type: CUSTOM_PARAM_TYPE,
-                name: undefined,
-                factory: (_unused, ctx)=>{
-                    const honoCtx = ctx;
-                    const execCtx = buildExecutionContext(honoCtx, target.constructor, propertyKey);
-                    return createLazyProxy(()=>factory(data, execCtx));
-                },
-                ...pipes.length > 0 ? {
-                    pipes
-                } : {}
-            });
-        };
-    };
-}
-// Single-shot resolution: the factory runs at most once; subsequent reads
-// share the cached real value. The proxy's traps all funnel through
-// `materialize` to keep that invariant in one place.
-function createLazyProxy(produce) {
-    let resolved = false;
-    let value;
-    const materialize = ()=>{
-        if (!resolved) {
-            value = produce();
-            resolved = true;
-        }
-        return value;
-    };
-    // Target is an empty null-prototype object — proxies still need a
-    // backing target for the runtime to forward to, but using a real object
-    // would leak its own properties (`hasOwnProperty`, etc.) into trap
-    // results. `Object.create(null)` keeps the namespace clean.
-    const target = Object.create(null);
-    const handler = {
-        get (_t, prop, receiver) {
-            // Critical: do NOT report the proxy as thenable. If we let the JS
-            // runtime read `then` (during `await proxy`), the engine would
-            // observe a function-shaped value, treat the proxy as a promise,
-            // call `then(resolve, reject)` and trigger eager resolution before
-            // the consumer ever touches a real property. Returning `undefined`
-            // here makes `await proxy` return the proxy itself, untouched.
-            if (prop === 'then') return undefined;
-            const real = materialize();
-            if (real === null || real === undefined) return undefined;
-            const descriptor = Reflect.get(real, prop, receiver);
-            // Bind functions back to the real target so `this` works as the
-            // consumer expects on instance methods.
-            if (typeof descriptor === 'function') {
-                return descriptor.bind(real);
-            }
-            return descriptor;
-        },
-        has (_t, prop) {
-            const real = materialize();
-            return real !== null && real !== undefined && Reflect.has(real, prop);
-        },
-        ownKeys () {
-            const real = materialize();
-            if (real === null || real === undefined) return [];
-            return Reflect.ownKeys(real);
-        },
-        getOwnPropertyDescriptor (_t, prop) {
-            const real = materialize();
-            if (real === null || real === undefined) return undefined;
-            const descriptor = Reflect.getOwnPropertyDescriptor(real, prop);
-            // Proxy invariants require returned descriptors to be configurable
-            // when the underlying target lacks the property, which is always
-            // true for our null-prototype empty target.
-            if (descriptor) descriptor.configurable = true;
-            return descriptor;
-        }
-    };
-    return new Proxy(target, handler);
-}

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

@@ -1,16 +0,0 @@
-import type { Context } from 'hono';
-import type { Container } from '../container/container';
-/**
- * Returns the request-scoped child container for the current request.
- *
- * `@Inject(Container)` resolves the ROOT container (request children share the
- * provider map and never rebind `Container`), so module authors who need
- * request-scoped resolution from inside a handler, param-decorator factory, or
- * scoped middleware must read the child seeded by RouteManager instead. The
- * child is created before guards, pipes, params, and handlers run, so it is
- * always present on the Vela request path.
- *
- * Throws outside a Vela-managed request rather than materializing an orphan
- * child (mirrors the REQUEST_CONTEXT fail-fast).
- */
-export declare function getRequestContainer(c: Context): Container;

package/dist/http/request-container.js

@@ -1,19 +0,0 @@
-/**
- * Returns the request-scoped child container for the current request.
- *
- * `@Inject(Container)` resolves the ROOT container (request children share the
- * provider map and never rebind `Container`), so module authors who need
- * request-scoped resolution from inside a handler, param-decorator factory, or
- * scoped middleware must read the child seeded by RouteManager instead. The
- * child is created before guards, pipes, params, and handlers run, so it is
- * always present on the Vela request path.
- *
- * Throws outside a Vela-managed request rather than materializing an orphan
- * child (mirrors the REQUEST_CONTEXT fail-fast).
- */ export function getRequestContainer(c) {
-    const container = c.get('container');
-    if (!container) {
-        throw new Error('getRequestContainer(c) can only be called inside a Vela-managed request — ' + 'the request child container is seeded by RouteManager when the request enters the pipeline.');
-    }
-    return container;
-}

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

@@ -1,13 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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/response-mapper.d.ts

@@ -1,8 +0,0 @@
-import type { Context } from 'hono';
-export interface ResponseRedirect {
-    url: string;
-    statusCode: number;
-}
-export declare function mapResponse(c: Context, result: unknown, statusCode?: number): Response;
-export declare function mapRedirect(c: Context, result: unknown, redirect: ResponseRedirect): Response;
-export declare function applyResponseHeaders(response: Response, headers: Iterable<readonly [string, string]>): void;

package/dist/http/response-mapper.js

@@ -1,42 +0,0 @@
-// A handler returning `{ url, statusCode? }` may override the @Redirect-decorator
-// destination — kept identical to the previous inline behavior.
-function parseRedirectResult(result) {
-    if (typeof result !== 'object' || result === null) return undefined;
-    if (!('url' in result)) return undefined;
-    const obj = result;
-    if (typeof obj.url !== 'string') return undefined;
-    return {
-        url: obj.url,
-        ...typeof obj.statusCode === 'number' ? {
-            statusCode: obj.statusCode
-        } : {}
-    };
-}
-// Maps a controller return value to a Hono Response. `null`/`undefined` → 204
-// (empty body); strings → text; anything else → JSON. A pre-built Response
-// passes through unchanged.
-export function mapResponse(c, result, statusCode) {
-    if (result instanceof Response) {
-        return result;
-    }
-    if (result === null || result === undefined) {
-        return c.body(null, statusCode ?? 204);
-    }
-    if (typeof result === 'string') {
-        return c.text(result, statusCode ?? 200);
-    }
-    return c.json(result, statusCode ?? 200);
-}
-// Honors @Redirect on the handler. If the handler returned `{ url, statusCode? }`,
-// those override the decorator's defaults; otherwise the decorator wins.
-export function mapRedirect(c, result, redirect) {
-    const overrides = parseRedirectResult(result);
-    const finalUrl = overrides?.url ?? redirect.url;
-    const finalStatus = overrides?.statusCode ?? redirect.statusCode;
-    return c.redirect(finalUrl, finalStatus);
-}
-export function applyResponseHeaders(response, headers) {
-    for (const [name, value] of headers){
-        response.headers.set(name, value);
-    }
-}

package/dist/http/route-contributor.d.ts

@@ -1,68 +0,0 @@
-import type { Hono } from 'hono';
-import type { Container } from '../container/container';
-import type { Type } from '../container/types';
-import type { OpenApiPathItem } from '../openapi/types';
-import type { CanActivate } from '../pipeline/types';
-/**
- * Context passed to {@link RouteContributor.buildRoutes} for each controller
- * the contributor claims. The contributor receives the framework's resolved
- * view of the world so generated routes behave identically to hand-written
- * ones: same global prefix, same global guard instances, same path joining.
- */
-export interface RouteContributorContext {
-    /** The claimed controller class. */
-    controller: Type;
-    /** Controller-level prefix as registered with `@Controller(...)`. */
-    controllerPrefix: string;
-    /** The metadata value (under `claimsMetaKey`) that claimed this controller. */
-    meta: unknown;
-    /** Application-wide path prefix (e.g. `/api`), already normalized. */
-    globalPrefix: string;
-    /** Global guard instances, pre-resolved from the root container. */
-    globalGuards: CanActivate[];
-    /** The app's root container — resolve controller/services from here. */
-    container: Container;
-    /** Path joiner used by the framework — handles slash normalization. */
-    joinPaths: (...parts: string[]) => string;
-}
-/** Context for {@link RouteContributor.buildOpenApiPaths}. */
-export interface RouteContributorOpenApiContext {
-    controller: Type;
-    meta: unknown;
-    /** Application-wide path prefix (e.g. `/api`), already normalized. */
-    globalPrefix: string;
-    /** Controller-level prefix as registered with `@Controller(...)`. */
-    controllerPrefix: string;
-}
-/**
- * A route generator that claims controllers by class-level metadata and
- * mounts routes for them — the public extension point behind `@Crud()` (and
- * any future metadata-driven route generator: storage HTTP surfaces, admin
- * panels, RPC bridges).
- *
- * Register once at import time (`registerRouteContributor`); the framework
- * consults contributors during `RouteManager.build` — AFTER all explicit
- * `@Get`/`@Post` routes, so generated `/:id` catch-alls never shadow custom
- * routes — and during OpenAPI document generation.
- *
- * This contract exists instead of dynamic `import()` because esbuild leaves
- * `await import(variable)` as a runtime import Cloudflare Workers cannot
- * resolve.
- */
-export interface RouteContributor {
-    /** Stable identifier; re-registering the same id overwrites (HMR-friendly). */
-    id: string;
-    /** Class-level metadata key whose presence claims a controller. */
-    claimsMetaKey: string;
-    buildRoutes(app: Hono, ctx: RouteContributorContext): void | Promise<void>;
-    buildOpenApiPaths?(ctx: RouteContributorOpenApiContext): Record<string, OpenApiPathItem>;
-}
-/** Register a contributor. Last registration per `id` wins. */
-export declare function registerRouteContributor(contributor: RouteContributor): void;
-/** All registered contributors (registration order). */
-export declare function getRouteContributors(): RouteContributor[];
-/**
- * Reset all contributor registrations. Test-only.
- * @internal
- */
-export declare function _resetRouteContributors(): void;

package/dist/http/route-contributor.js

@@ -1,22 +0,0 @@
-// Contributors register at import time (package side effect), so the store is
-// anchored on `globalThis` like MetadataRegistry state: a Vite HMR re-eval
-// reuses the same store instead of minting an empty one.
-const STORE_KEY = Symbol.for('vela:route-contributors:v1');
-function store() {
-    const g = globalThis;
-    return g[STORE_KEY] ??= new Map();
-}
-/** Register a contributor. Last registration per `id` wins. */ export function registerRouteContributor(contributor) {
-    store().set(contributor.id, contributor);
-}
-/** All registered contributors (registration order). */ export function getRouteContributors() {
-    return [
-        ...store().values()
-    ];
-}
-/**
- * Reset all contributor registrations. Test-only.
- * @internal
- */ export function _resetRouteContributors() {
-    store().clear();
-}

package/dist/http/route-map.d.ts

@@ -1,30 +0,0 @@
-/**
- * Augmentable map of route name → its path params. Users opt in to type-safe
- * URL generation by augmenting this interface — no build step, no codegen:
- *
- * ```ts
- * declare module '@velajs/vela' {
- *   interface VelaRouteMap {
- *     'users.index': Record<string, never>;
- *     'users.show': { id: string };
- *   }
- * }
- * ```
- *
- * Until augmented it stays empty, so `RouteName` falls back to `string` and
- * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
- * callers keep working unchanged.
- */
-export interface VelaRouteMap {
-}
-/**
- * Every valid route name. Falls back to `string` when `VelaRouteMap` has not
- * been augmented, so `urlFor`/`signedUrl` accept any name in an untyped app.
- */
-export type RouteName = keyof VelaRouteMap extends never ? string : Extract<keyof VelaRouteMap, string>;
-/**
- * The params object required to build a named route's URL. When `VelaRouteMap`
- * is augmented, resolves to the declared params shape for `N`; otherwise a
- * loose `Record<string, string> | undefined`.
- */
-export type RouteParams<N extends RouteName> = N extends keyof VelaRouteMap ? VelaRouteMap[N] : Record<string, string> | undefined;

package/dist/http/route-map.js

@@ -1,27 +0,0 @@
-// Zero-codegen, type-safe route names — mirrors the augmentation pattern from
-// stratal `packages/core/src/router/route-map.ts` (MIT © Temitayo Fadojutimi).
-// Adapted for vela: `VelaRouteMap` maps a route name directly to its params
-// object (stratal wraps params in `{ params: … }`; vela keeps it flat to match
-// the `urlFor(name, params)` call shape).
-/**
- * Augmentable map of route name → its path params. Users opt in to type-safe
- * URL generation by augmenting this interface — no build step, no codegen:
- *
- * ```ts
- * declare module '@velajs/vela' {
- *   interface VelaRouteMap {
- *     'users.index': Record<string, never>;
- *     'users.show': { id: string };
- *   }
- * }
- * ```
- *
- * Until augmented it stays empty, so `RouteName` falls back to `string` and
- * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
- * callers keep working unchanged.
- */ // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentable interface, intentionally empty until a consumer declares routes
-/**
- * The params object required to build a named route's URL. When `VelaRouteMap`
- * is augmented, resolves to the declared params shape for `N`; otherwise a
- * loose `Record<string, string> | undefined`.
- */ export { };

package/dist/http/route.manager.d.ts

@@ -1,92 +0,0 @@
-import { type Context, type MiddlewareHandler, Hono } from 'hono';
-import type { Container } from '../container/container';
-import type { Token, Type } from '../container/types';
-import type { MiddlewareRouteDefinition } from '../module/middleware';
-import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from '../pipeline/types';
-import type { FilterType, GuardType, InterceptorType, MiddlewareType, PipeType } from '../registry/types';
-import type { ControllerRegistration } from './types';
-/**
- * One explicit controller route as the framework registered it — recorded by
- * `build()` with the SAME composed path handed to Hono (global prefix +
- * version segment + controller prefix + route path), so introspection tooling
- * (`vela route list`) never re-derives composition. Contributed routes
- * (`RouteContributor`, e.g. `@velajs/crud`) mount directly on the Hono app
- * and are not described here — diff `app.getHonoApp().routes` for those.
- */
-export interface RouteDescription {
-    /** As declared on the handler — `@Head()` reports HEAD (Hono serves it under GET). */
-    method: string;
-    /** Fully composed path exactly as registered. */
-    path: string;
-    controller: string;
-    handler: string;
-    version?: number;
-    /** Route name (`@Get(path, { name })`) — the URL-generation / `operationId` key. */
-    name?: string;
-}
-export interface RouteManagerOptions {
-    getClientIp?: (c: Context) => string | null;
-    middleware?: MiddlewareHandler[];
-    globalPrefix?: string;
-    /**
-     * Opt into ambient request-container access (`getCurrentContainer()` /
-     * `getCurrentRequestContext()`). Registers Hono's `contextStorage()` as the
-     * first middleware. Off by default — the explicit child container is unchanged.
-     */
-    ambientContainer?: boolean;
-}
-export declare class RouteManager {
-    private container;
-    private static readonly METHOD_REGISTRAR;
-    private controllers;
-    private globalMiddleware;
-    private globalPipes;
-    private globalGuards;
-    private globalInterceptors;
-    private globalFilters;
-    private globalPrefix;
-    private consumerMiddlewareDefinitions;
-    private routeDescriptions;
-    private readonly handlerExecutor;
-    private readonly ambientContainer;
-    constructor(container: Container, options?: RouteManagerOptions);
-    /**
-     * The global-tier components (`APP_*` provider tokens + imperative
-     * `app.useGlobalX()` instances). Exposed so non-HTTP transports (the
-     * WebSocket dispatcher) can apply the same app-wide guards/pipes/interceptors/
-     * filters as HTTP routes, read live so late registrations propagate.
-     */
-    getGlobalComponents(): {
-        guards: Array<GuardType | Token<CanActivate>>;
-        pipes: Array<PipeType | Token<PipeTransform>>;
-        interceptors: Array<InterceptorType | Token<NestInterceptor>>;
-        filters: Array<FilterType | Token<ExceptionFilter>>;
-    };
-    registerConsumerMiddleware(definitions: MiddlewareRouteDefinition[]): this;
-    setGlobalPrefix(prefix: string): this;
-    useGlobalMiddleware(...middleware: MiddlewareType[]): this;
-    useGlobalMiddlewareTokens(...middlewareTokens: Array<Token<NestMiddleware>>): this;
-    useGlobalPipes(...pipes: PipeType[]): this;
-    useGlobalPipeTokens(...pipeTokens: Array<Token<PipeTransform>>): this;
-    useGlobalGuards(...guards: GuardType[]): this;
-    useGlobalGuardTokens(...guardTokens: Array<Token<CanActivate>>): this;
-    useGlobalInterceptors(...interceptors: InterceptorType[]): this;
-    useGlobalInterceptorTokens(...interceptorTokens: Array<Token<NestInterceptor>>): this;
-    useGlobalFilters(...filters: FilterType[]): this;
-    useGlobalFilterTokens(...filterTokens: Array<Token<ExceptionFilter>>): this;
-    private getMiddlewarePriority;
-    private getRequestContainer;
-    private wrapMiddlewareWithFilters;
-    private mapMiddlewareError;
-    registerController(controller: Type): this;
-    /** The explicit controller routes recorded by the last `build()`. */
-    getRouteDescriptions(): RouteDescription[];
-    /** The global prefix in effect (set at bootstrap; '' when none). */
-    getGlobalPrefix(): string;
-    build(): Promise<Hono>;
-    private registerRoute;
-    private buildVersionedPaths;
-    private compilePathMatcher;
-    private compileRouteMatcher;
-    getControllers(): ControllerRegistration[];
-}