@velajs/vela 1.14.0 → 1.16.0

package/dist/http/url/url-generator.service.d.ts

@@ -0,0 +1,52 @@
+import { RouteManager } from '../route.manager';
+import type { RouteName, RouteParams } from '../route-map';
+/** Value accepted for a path param or query entry. */
+type UrlParamValue = string | number | boolean;
+/** Extra options for {@link UrlGeneratorService.urlFor}. */
+export interface UrlForOptions {
+    /** Additional query-string entries merged after any leftover params. */
+    query?: Record<string, UrlParamValue>;
+}
+/** Options for {@link UrlGeneratorService.signedUrl}. */
+export interface SignedUrlGenerateOptions {
+    /** Time-to-live in seconds; enforced on verification via the `expires` param. */
+    expiresIn?: number;
+    /** Override the signing secret (else the `URL_SIGNING_SECRET` token / `CONFIG_ENV`). */
+    secret?: string;
+}
+/**
+ * Builds URLs for named routes (Laravel-flavoured `route()` ergonomics).
+ *
+ * Route descriptions are read LAZILY from the {@link RouteManager} on first use
+ * — post-build, so composition (global prefix + version + controller prefix) is
+ * already baked into each path — and it never instantiates controllers, so it
+ * plays nicely with lazy modules. Registered as an app-level singleton by
+ * `bootstrap`, so it is injectable anywhere.
+ */
+export declare class UrlGeneratorService {
+    private readonly routeManager;
+    private readonly secretToken?;
+    private readonly env;
+    private routeMap;
+    constructor(routeManager: RouteManager, secretToken?: string | undefined, env?: Record<string, unknown>);
+    /**
+     * Build the path for a named route, filling `:param` placeholders from
+     * `params`. Params that don't match a placeholder become query-string
+     * entries; `opts.query` is merged after them.
+     *
+     * @throws if no route carries `name`, or a required `:param` is missing.
+     */
+    urlFor<N extends RouteName>(name: N, params?: RouteParams<N>, opts?: UrlForOptions): string;
+    /**
+     * Build a named-route URL and HMAC-sign it (path + query). The secret comes
+     * from `options.secret`, else the {@link URL_SIGNING_SECRET} token, else
+     * `CONFIG_ENV`; a descriptive error is thrown when none is available.
+     */
+    signedUrl<N extends RouteName>(name: N, params?: RouteParams<N>, options?: SignedUrlGenerateOptions): Promise<string>;
+    /**
+     * Lazily index named route descriptions. Rebuilt while empty (routes may not
+     * be built yet), cached once populated.
+     */
+    private routes;
+}
+export {};

package/dist/http/url/url-generator.service.js

@@ -0,0 +1,104 @@
+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 { Injectable, Inject, Optional } from "../../container/decorators.js";
+import { CONFIG_ENV } from "../../config/config.tokens.js";
+import { signUrl } from "../../crypto/signed-url.js";
+import { RouteManager } from "../route.manager.js";
+import { URL_SIGNING_SECRET, resolveSigningSecret } from "./signing-secret.js";
+export class UrlGeneratorService {
+    routeManager;
+    secretToken;
+    env;
+    routeMap = null;
+    constructor(routeManager, secretToken, env = {}){
+        this.routeManager = routeManager;
+        this.secretToken = secretToken;
+        this.env = env;
+    }
+    /**
+   * Build the path for a named route, filling `:param` placeholders from
+   * `params`. Params that don't match a placeholder become query-string
+   * entries; `opts.query` is merged after them.
+   *
+   * @throws if no route carries `name`, or a required `:param` is missing.
+   */ urlFor(name, params, opts) {
+        const description = this.routes().get(name);
+        if (!description) {
+            throw new Error(`No route named "${String(name)}" was found. Give the route a name ` + `via \`@Get(path, { name: '${String(name)}' })\`.`);
+        }
+        const provided = {
+            ...params ?? {}
+        };
+        const consumed = new Set();
+        const path = description.path.replace(/:([A-Za-z0-9_]+)/g, (_match, key)=>{
+            const value = provided[key];
+            if (value === undefined || value === null) {
+                throw new Error(`Missing route param "${key}" for route "${String(name)}".`);
+            }
+            consumed.add(key);
+            return encodeURIComponent(String(value));
+        });
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(provided)){
+            if (consumed.has(key) || value === undefined || value === null) continue;
+            query.set(key, String(value));
+        }
+        for (const [key, value] of Object.entries(opts?.query ?? {})){
+            if (value === undefined || value === null) continue;
+            query.set(key, String(value));
+        }
+        const qs = query.toString();
+        return qs ? `${path}?${qs}` : path;
+    }
+    /**
+   * Build a named-route URL and HMAC-sign it (path + query). The secret comes
+   * from `options.secret`, else the {@link URL_SIGNING_SECRET} token, else
+   * `CONFIG_ENV`; a descriptive error is thrown when none is available.
+   */ async signedUrl(name, params, options = {}) {
+        const url = this.urlFor(name, params);
+        const secret = resolveSigningSecret(options.secret, this.secretToken, this.env);
+        return signUrl(url, secret, options.expiresIn !== undefined ? {
+            expiresIn: options.expiresIn
+        } : undefined);
+    }
+    /**
+   * Lazily index named route descriptions. Rebuilt while empty (routes may not
+   * be built yet), cached once populated.
+   */ routes() {
+        if (this.routeMap && this.routeMap.size > 0) return this.routeMap;
+        const map = new Map();
+        for (const description of this.routeManager.getRouteDescriptions()){
+            if (description.name && !map.has(description.name)) {
+                map.set(description.name, description);
+            }
+        }
+        this.routeMap = map;
+        return map;
+    }
+}
+UrlGeneratorService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(RouteManager)),
+    _ts_param(1, Optional()),
+    _ts_param(1, Inject(URL_SIGNING_SECRET)),
+    _ts_param(2, Optional()),
+    _ts_param(2, Inject(CONFIG_ENV)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof RouteManager === "undefined" ? Object : RouteManager,
+        String,
+        typeof Record === "undefined" ? Object : Record
+    ])
+], UrlGeneratorService);

package/dist/index.d.ts

@@ -6,17 +6,21 @@ export { bootstrap } from './factory/bootstrap';
 export type { BootstrapOptions, BootstrapResult } from './factory/bootstrap';
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema, } from './openapi/index';
 export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, } from './openapi/index';
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, } from './container/index';
-export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, describeToken, } from './container/index';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './container/index';
+export type { RouteDescription } from './http/route.manager';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
-export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, } from './http/index';
+export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET, } from './http/index';
+export type { RouteOptions, UrlForOptions, SignedUrlGenerateOptions, VelaRouteMap, RouteName, RouteParams, } from './http/index';
+export { signUrl, verifySignedUrl } from './crypto/signed-url';
+export type { SignedUrlOptions } from './crypto/signed-url';
 export { REQUEST_CONTEXT } from './http/request-context';
 export type { RequestContext } from './http/request-context';
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext, } from './http/ambient';
 export { Logger, LogLevel } from './services/index';
 export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './services/index';
-export { ConfigModule, ConfigService, CONFIG_OPTIONS } from './config/index';
-export type { ConfigModuleOptions } from './config/index';
+export { ConfigModule, ConfigService, ConfigStore, CONFIG_OPTIONS, CONFIG_ENV, registerAs, } from './config/index';
+export type { ConfigModuleOptions, ConfigSchema, ConfigNamespace, AnyConfigNamespace, InferConfigType, ConfigType, ConfigPath, ConfigPathValue, } from './config/index';
 export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } from './fetch/index';
 export type { HttpModuleOptions, HttpResponse, HttpRequestConfig } from './fetch/index';
 export { CorsModule, CORS_OPTIONS } from './cors/index';

package/dist/index.js

@@ -7,11 +7,13 @@ export { bootstrap } from "./factory/bootstrap.js";
 // OpenAPI
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema } from "./openapi/index.js";
 // DI Container
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin } from "./container/index.js";
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, describeToken } from "./container/index.js";
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
-export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators } from "./http/index.js";
+export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, createLazyParamDecorator, applyDecorators, UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET } from "./http/index.js";
+// Edge-safe HMAC signed-URL primitives (also re-exported from `@velajs/vela/storage`)
+export { signUrl, verifySignedUrl } from "./crypto/signed-url.js";
 // Request-scoped context primitive
 export { REQUEST_CONTEXT } from "./http/request-context.js";
 // Opt-in ambient container access (ALS via hono/context-storage)
@@ -19,7 +21,7 @@ export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext }
 // Services
 export { Logger, LogLevel } from "./services/index.js";
 // Config
-export { ConfigModule, ConfigService, CONFIG_OPTIONS } from "./config/index.js";
+export { ConfigModule, ConfigService, ConfigStore, CONFIG_OPTIONS, CONFIG_ENV, registerAs } from "./config/index.js";
 // HTTP Client
 export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } from "./fetch/index.js";
 // CORS

package/dist/openapi/document.js

@@ -182,7 +182,8 @@ function buildOperation(controller, route, pathString, registry) {
     if (requestBody) operation.requestBody = requestBody;
     if (docMeta?.summary) operation.summary = docMeta.summary;
     if (docMeta?.description) operation.description = docMeta.description;
-    if (docMeta?.operationId) operation.operationId = docMeta.operationId;
+    const operationId = docMeta?.operationId ?? route.name;
+    if (operationId) operation.operationId = operationId;
     if (docMeta?.deprecated) operation.deprecated = docMeta.deprecated;
     if (mergedTags.length > 0) operation.tags = mergedTags;
     return operation;

package/dist/registry/types.d.ts

@@ -21,6 +21,8 @@ export interface RouteDefinition {
     path: string;
     handlerName: string | symbol;
     version?: number | number[];
+    /** Route name for URL generation / OpenAPI operationId (`@Get(path, { name })`). */
+    name?: string;
 }
 export interface ParameterMetadata {
     index: number;

package/dist/storage/index.d.ts

@@ -1,4 +1,4 @@
-export { signUrl, verifySignedUrl } from './signed-url';
-export type { SignedUrlOptions } from './signed-url';
+export { signUrl, verifySignedUrl } from '../crypto/signed-url';
+export type { SignedUrlOptions } from '../crypto/signed-url';
 export { expandPathTemplate, joinStoragePath } from './path-template';
 export type { StorageBody, StorageDriver, PresignMethod, UploadOptions, UploadResult, DownloadResult, PresignedUrlResult, } from './storage.types';

package/dist/storage/index.js

@@ -1,2 +1,5 @@
-export { signUrl, verifySignedUrl } from "./signed-url.js";
+// The HMAC signed-URL util now lives in `src/crypto/` (core consumes it there
+// for the URL generator + guard). Re-exported here so `@velajs/vela/storage`'s
+// public API is unchanged for existing consumers.
+export { signUrl, verifySignedUrl } from "../crypto/signed-url.js";
 export { expandPathTemplate, joinStoragePath } from "./path-template.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -102,6 +102,7 @@
     "@vitest/runner": "^4.1.9",
     "@vitest/snapshot": "^4.1.9",
     "intl-messageformat": "^11.2.9",
+    "typedoc": "~0.28.19",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.9",
@@ -112,6 +113,9 @@
     "test": "vitest run",
     "test:workers": "vitest run --config vitest.config.workers.ts",
     "test:workers:als": "vitest run --config vitest.config.workers-als.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.type-tests.json",
+    "check:skill": "node scripts/check-skill.mjs",
+    "docs": "typedoc",
+    "docs:check": "typedoc --emit none"
   }
 }