@veloxts/router 0.6.56 → 0.6.58

package/dist/openapi/types.d.ts

@@ -0,0 +1,437 @@
+/**
+ * OpenAPI 3.0.3 Type Definitions
+ *
+ * Type-safe definitions for generating OpenAPI specifications from VeloxTS procedures.
+ *
+ * @module @veloxts/router/openapi/types
+ */
+import type { ProcedureCollection } from '../types.js';
+/**
+ * JSON Schema representation for OpenAPI
+ */
+export type JSONSchema = {
+    type?: string | string[];
+    format?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    const?: unknown;
+    nullable?: boolean;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JSONSchema;
+    patternProperties?: Record<string, JSONSchema>;
+    minProperties?: number;
+    maxProperties?: number;
+    items?: JSONSchema | JSONSchema[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    allOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    oneOf?: JSONSchema[];
+    not?: JSONSchema;
+    $ref?: string;
+    example?: unknown;
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    [key: string]: unknown;
+};
+/**
+ * Contact information for the API
+ */
+export interface OpenAPIContact {
+    name?: string;
+    url?: string;
+    email?: string;
+}
+/**
+ * License information for the API
+ */
+export interface OpenAPILicense {
+    name: string;
+    url?: string;
+}
+/**
+ * API metadata
+ */
+export interface OpenAPIInfo {
+    title: string;
+    version: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: OpenAPIContact;
+    license?: OpenAPILicense;
+}
+/**
+ * Server information
+ */
+export interface OpenAPIServer {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        enum?: string[];
+        description?: string;
+    }>;
+}
+/**
+ * Parameter location
+ */
+export type ParameterIn = 'path' | 'query' | 'header' | 'cookie';
+/**
+ * Parameter definition
+ */
+export interface OpenAPIParameter {
+    name: string;
+    in: ParameterIn;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    schema: JSONSchema;
+    example?: unknown;
+    examples?: Record<string, OpenAPIExample>;
+}
+/**
+ * Example object
+ */
+export interface OpenAPIExample {
+    summary?: string;
+    description?: string;
+    value?: unknown;
+    externalValue?: string;
+}
+/**
+ * Media type object
+ */
+export interface OpenAPIMediaType {
+    schema?: JSONSchema;
+    example?: unknown;
+    examples?: Record<string, OpenAPIExample>;
+    encoding?: Record<string, OpenAPIEncoding>;
+}
+/**
+ * Encoding object for multipart requests
+ */
+export interface OpenAPIEncoding {
+    contentType?: string;
+    headers?: Record<string, OpenAPIHeader>;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+/**
+ * Header object
+ */
+export interface OpenAPIHeader {
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: JSONSchema;
+    example?: unknown;
+}
+/**
+ * Request body definition
+ */
+export interface OpenAPIRequestBody {
+    description?: string;
+    required?: boolean;
+    content: Record<string, OpenAPIMediaType>;
+}
+/**
+ * Response definition
+ */
+export interface OpenAPIResponse {
+    description: string;
+    headers?: Record<string, OpenAPIHeader>;
+    content?: Record<string, OpenAPIMediaType>;
+    links?: Record<string, OpenAPILink>;
+}
+/**
+ * Link object for response linking
+ */
+export interface OpenAPILink {
+    operationRef?: string;
+    operationId?: string;
+    parameters?: Record<string, unknown>;
+    requestBody?: unknown;
+    description?: string;
+    server?: OpenAPIServer;
+}
+/**
+ * Security scheme types
+ */
+export type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+/**
+ * OAuth2 flow object
+ */
+export interface OpenAPIOAuthFlow {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+}
+/**
+ * OAuth2 flows object
+ */
+export interface OpenAPIOAuthFlows {
+    implicit?: OpenAPIOAuthFlow;
+    password?: OpenAPIOAuthFlow;
+    clientCredentials?: OpenAPIOAuthFlow;
+    authorizationCode?: OpenAPIOAuthFlow;
+}
+/**
+ * Security scheme definition
+ */
+export interface OpenAPISecurityScheme {
+    type: SecuritySchemeType;
+    description?: string;
+    name?: string;
+    in?: 'query' | 'header' | 'cookie';
+    scheme?: string;
+    bearerFormat?: string;
+    flows?: OpenAPIOAuthFlows;
+    openIdConnectUrl?: string;
+}
+/**
+ * Security requirement object
+ */
+export type OpenAPISecurityRequirement = Record<string, string[]>;
+/**
+ * External documentation object
+ */
+export interface OpenAPIExternalDocs {
+    url: string;
+    description?: string;
+}
+/**
+ * Operation object (endpoint definition)
+ */
+export interface OpenAPIOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    externalDocs?: OpenAPIExternalDocs;
+    parameters?: OpenAPIParameter[];
+    requestBody?: OpenAPIRequestBody;
+    responses: Record<string, OpenAPIResponse>;
+    callbacks?: Record<string, Record<string, OpenAPIPathItem>>;
+    deprecated?: boolean;
+    security?: OpenAPISecurityRequirement[];
+    servers?: OpenAPIServer[];
+}
+/**
+ * Path item object (all operations for a path)
+ */
+export interface OpenAPIPathItem {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    get?: OpenAPIOperation;
+    put?: OpenAPIOperation;
+    post?: OpenAPIOperation;
+    delete?: OpenAPIOperation;
+    options?: OpenAPIOperation;
+    head?: OpenAPIOperation;
+    patch?: OpenAPIOperation;
+    trace?: OpenAPIOperation;
+    servers?: OpenAPIServer[];
+    parameters?: OpenAPIParameter[];
+}
+/**
+ * Components object for reusable definitions
+ */
+export interface OpenAPIComponents {
+    schemas?: Record<string, JSONSchema>;
+    responses?: Record<string, OpenAPIResponse>;
+    parameters?: Record<string, OpenAPIParameter>;
+    examples?: Record<string, OpenAPIExample>;
+    requestBodies?: Record<string, OpenAPIRequestBody>;
+    headers?: Record<string, OpenAPIHeader>;
+    securitySchemes?: Record<string, OpenAPISecurityScheme>;
+    links?: Record<string, OpenAPILink>;
+    callbacks?: Record<string, Record<string, OpenAPIPathItem>>;
+}
+/**
+ * Tag object for grouping operations
+ */
+export interface OpenAPITag {
+    name: string;
+    description?: string;
+    externalDocs?: OpenAPIExternalDocs;
+}
+/**
+ * Complete OpenAPI 3.0.3 specification
+ */
+export interface OpenAPISpec {
+    openapi: '3.0.3';
+    info: OpenAPIInfo;
+    servers?: OpenAPIServer[];
+    paths: Record<string, OpenAPIPathItem>;
+    components?: OpenAPIComponents;
+    security?: OpenAPISecurityRequirement[];
+    tags?: OpenAPITag[];
+    externalDocs?: OpenAPIExternalDocs;
+}
+/**
+ * Options for OpenAPI specification generation
+ */
+export interface OpenAPIGeneratorOptions {
+    /**
+     * API info metadata (required)
+     */
+    info: OpenAPIInfo;
+    /**
+     * Server URLs for the API
+     */
+    servers?: OpenAPIServer[];
+    /**
+     * API prefix prepended to all paths
+     * @default '/api'
+     */
+    prefix?: string;
+    /**
+     * Security scheme definitions
+     * Merged with default schemes (bearerAuth)
+     */
+    securitySchemes?: Record<string, OpenAPISecurityScheme>;
+    /**
+     * Default security for all endpoints
+     * Applied when no guards are present
+     */
+    defaultSecurity?: OpenAPISecurityRequirement[];
+    /**
+     * Custom guard name to security scheme mapping
+     * @example { 'authenticated': 'bearerAuth', 'apiKey': 'apiKeyAuth' }
+     */
+    guardToSecurityMap?: Record<string, string>;
+    /**
+     * Tag descriptions for namespaces
+     * @example { 'users': 'User management endpoints' }
+     */
+    tagDescriptions?: Record<string, string>;
+    /**
+     * External documentation link
+     */
+    externalDocs?: OpenAPIExternalDocs;
+    /**
+     * Additional OpenAPI extensions (x-* properties)
+     */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Swagger UI configuration options
+ */
+export interface SwaggerUIConfig {
+    /**
+     * Enable deep linking for tags and operations
+     * @default true
+     */
+    deepLinking?: boolean;
+    /**
+     * Display operationId in the UI
+     * @default false
+     */
+    displayOperationId?: boolean;
+    /**
+     * Default expand depth for models section
+     * @default 1
+     */
+    defaultModelsExpandDepth?: number;
+    /**
+     * Default expand depth for model properties
+     * @default 1
+     */
+    defaultModelExpandDepth?: number;
+    /**
+     * Controls expansion of operations and tags
+     * @default 'list'
+     */
+    docExpansion?: 'list' | 'full' | 'none';
+    /**
+     * Enable filter/search box
+     * @default false
+     */
+    filter?: boolean | string;
+    /**
+     * Show extensions (x-* fields)
+     * @default false
+     */
+    showExtensions?: boolean;
+    /**
+     * Enable "Try it out" by default
+     * @default true
+     */
+    tryItOutEnabled?: boolean;
+    /**
+     * Persist authorization data across browser sessions
+     * @default false
+     */
+    persistAuthorization?: boolean;
+}
+/**
+ * Options for the Swagger UI Fastify plugin
+ */
+export interface SwaggerUIPluginOptions {
+    /**
+     * Route prefix for Swagger UI
+     * @default '/docs'
+     */
+    routePrefix?: string;
+    /**
+     * Route for raw OpenAPI JSON
+     * @default '/docs/openapi.json'
+     */
+    specRoute?: string;
+    /**
+     * Swagger UI configuration
+     */
+    uiConfig?: SwaggerUIConfig;
+    /**
+     * OpenAPI generator options
+     */
+    openapi: OpenAPIGeneratorOptions;
+    /**
+     * Procedure collections to document
+     */
+    collections: ProcedureCollection[];
+    /**
+     * Custom page title
+     * @default 'API Documentation'
+     */
+    title?: string;
+    /**
+     * Custom favicon URL
+     */
+    favicon?: string;
+}
+/**
+ * HTTP methods supported by OpenAPI
+ */
+export type OpenAPIHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'options' | 'head';
+/**
+ * Route information for generation
+ */
+export interface RouteInfo {
+    method: OpenAPIHttpMethod;
+    path: string;
+    operationId: string;
+    namespace: string;
+    procedureName: string;
+    inputSchema?: JSONSchema;
+    outputSchema?: JSONSchema;
+    guards: string[];
+    deprecated?: boolean;
+}

package/dist/openapi/types.js

@@ -0,0 +1,8 @@
+/**
+ * OpenAPI 3.0.3 Type Definitions
+ *
+ * Type-safe definitions for generating OpenAPI specifications from VeloxTS procedures.
+ *
+ * @module @veloxts/router/openapi/types
+ */
+export {};

package/dist/providers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * DI Providers for @veloxts/router
+ *
+ * Factory provider functions for registering router services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module router/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerRouterProviders, TRPC_INSTANCE, APP_ROUTER } from '@veloxts/router';
+ *
+ * const container = new Container();
+ * registerRouterProviders(container, {
+ *   procedures: [userProcedures, postProcedures],
+ * });
+ *
+ * const t = container.resolve(TRPC_INSTANCE);
+ * const router = container.resolve(APP_ROUTER);
+ * ```
+ */
+import { type Container, type FactoryProvider } from '@veloxts/core';
+import type { RouterConfig } from './tokens.js';
+import type { AnyRouter, TRPCInstance, TRPCPluginOptions } from './trpc/index.js';
+/**
+ * Creates a factory provider for the tRPC instance
+ *
+ * The tRPC instance is the foundation for building type-safe routers.
+ *
+ * @example
+ * ```typescript
+ * container.register(trpcInstanceProvider());
+ * const t = container.resolve(TRPC_INSTANCE);
+ * ```
+ */
+export declare function trpcInstanceProvider(): FactoryProvider<TRPCInstance>;
+/**
+ * Creates a factory provider for the app router
+ *
+ * Requires TRPC_INSTANCE and PROCEDURE_COLLECTIONS to be registered.
+ *
+ * @example
+ * ```typescript
+ * container.register({ provide: PROCEDURE_COLLECTIONS, useValue: [userProcedures] });
+ * container.register(trpcInstanceProvider());
+ * container.register(appRouterProvider());
+ *
+ * const router = container.resolve(APP_ROUTER);
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export declare function appRouterProvider(): FactoryProvider<AnyRouter>;
+/**
+ * Creates a factory provider for tRPC plugin options
+ *
+ * Requires APP_ROUTER and ROUTER_CONFIG to be registered.
+ *
+ * @example
+ * ```typescript
+ * const options = container.resolve(TRPC_PLUGIN_OPTIONS);
+ * await registerTRPCPlugin(server, options);
+ * ```
+ */
+export declare function trpcPluginOptionsProvider(): FactoryProvider<TRPCPluginOptions>;
+/**
+ * Registers core router providers with a container
+ *
+ * This registers the tRPC instance and app router for DI-enabled routing.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Router configuration with procedure collections
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerRouterProviders, TRPC_INSTANCE, APP_ROUTER } from '@veloxts/router';
+ *
+ * const container = new Container();
+ * registerRouterProviders(container, {
+ *   procedures: [userProcedures, postProcedures],
+ *   apiPrefix: '/api',
+ *   rpcPrefix: '/trpc',
+ * });
+ *
+ * const t = container.resolve(TRPC_INSTANCE);
+ * const router = container.resolve(APP_ROUTER);
+ * ```
+ */
+export declare function registerRouterProviders(container: Container, config?: RouterConfig): void;

package/dist/providers.js

@@ -0,0 +1,145 @@
+/**
+ * DI Providers for @veloxts/router
+ *
+ * Factory provider functions for registering router services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module router/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerRouterProviders, TRPC_INSTANCE, APP_ROUTER } from '@veloxts/router';
+ *
+ * const container = new Container();
+ * registerRouterProviders(container, {
+ *   procedures: [userProcedures, postProcedures],
+ * });
+ *
+ * const t = container.resolve(TRPC_INSTANCE);
+ * const router = container.resolve(APP_ROUTER);
+ * ```
+ */
+import { Scope } from '@veloxts/core';
+import { APP_ROUTER, PROCEDURE_COLLECTIONS, REST_ADAPTER_CONFIG, ROUTER_CONFIG, TRPC_INSTANCE, TRPC_PLUGIN_OPTIONS, } from './tokens.js';
+import { appRouter, trpc } from './trpc/index.js';
+// ============================================================================
+// Core Router Providers
+// ============================================================================
+/**
+ * Creates a factory provider for the tRPC instance
+ *
+ * The tRPC instance is the foundation for building type-safe routers.
+ *
+ * @example
+ * ```typescript
+ * container.register(trpcInstanceProvider());
+ * const t = container.resolve(TRPC_INSTANCE);
+ * ```
+ */
+export function trpcInstanceProvider() {
+    return {
+        provide: TRPC_INSTANCE,
+        useFactory: () => trpc(),
+        inject: [],
+        scope: Scope.SINGLETON,
+    };
+}
+/**
+ * Creates a factory provider for the app router
+ *
+ * Requires TRPC_INSTANCE and PROCEDURE_COLLECTIONS to be registered.
+ *
+ * @example
+ * ```typescript
+ * container.register({ provide: PROCEDURE_COLLECTIONS, useValue: [userProcedures] });
+ * container.register(trpcInstanceProvider());
+ * container.register(appRouterProvider());
+ *
+ * const router = container.resolve(APP_ROUTER);
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export function appRouterProvider() {
+    return {
+        provide: APP_ROUTER,
+        useFactory: (t, collections) => appRouter(t, collections),
+        inject: [TRPC_INSTANCE, PROCEDURE_COLLECTIONS],
+        scope: Scope.SINGLETON,
+    };
+}
+/**
+ * Creates a factory provider for tRPC plugin options
+ *
+ * Requires APP_ROUTER and ROUTER_CONFIG to be registered.
+ *
+ * @example
+ * ```typescript
+ * const options = container.resolve(TRPC_PLUGIN_OPTIONS);
+ * await registerTRPCPlugin(server, options);
+ * ```
+ */
+export function trpcPluginOptionsProvider() {
+    return {
+        provide: TRPC_PLUGIN_OPTIONS,
+        useFactory: (router, config) => ({
+            prefix: config.rpcPrefix ?? '/trpc',
+            router,
+        }),
+        inject: [APP_ROUTER, ROUTER_CONFIG],
+        scope: Scope.SINGLETON,
+    };
+}
+// ============================================================================
+// Bulk Registration Helpers
+// ============================================================================
+/**
+ * Registers core router providers with a container
+ *
+ * This registers the tRPC instance and app router for DI-enabled routing.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Router configuration with procedure collections
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerRouterProviders, TRPC_INSTANCE, APP_ROUTER } from '@veloxts/router';
+ *
+ * const container = new Container();
+ * registerRouterProviders(container, {
+ *   procedures: [userProcedures, postProcedures],
+ *   apiPrefix: '/api',
+ *   rpcPrefix: '/trpc',
+ * });
+ *
+ * const t = container.resolve(TRPC_INSTANCE);
+ * const router = container.resolve(APP_ROUTER);
+ * ```
+ */
+export function registerRouterProviders(container, config = {}) {
+    // Register config
+    container.register({
+        provide: ROUTER_CONFIG,
+        useValue: config,
+    });
+    // Register procedure collections
+    container.register({
+        provide: PROCEDURE_COLLECTIONS,
+        useValue: config.procedures ?? [],
+    });
+    // Register REST adapter config
+    container.register({
+        provide: REST_ADAPTER_CONFIG,
+        useValue: {
+            prefix: config.apiPrefix ?? '/api',
+        },
+    });
+    // Register tRPC instance provider
+    container.register(trpcInstanceProvider());
+    // Only register app router if procedures are provided
+    if (config.procedures && config.procedures.length > 0) {
+        container.register(appRouterProvider());
+        container.register(trpcPluginOptionsProvider());
+    }
+}