@veloxts/core 0.7.7 → 0.7.9

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @veloxts/core
 
+## 0.7.9
+
+### Patch Changes
+
+- feat(router): swagger auto-discovery of module collections
+
+## 0.7.8
+
+### Patch Changes
+
+- New feature: Domain Module. defineModule() implementation
+
 ## 0.7.7
 
 ### Patch Changes

package/dist/app.d.ts

@@ -4,6 +4,7 @@
  * @module app
  */
 import { type FastifyInstance, type FastifyPluginAsync } from 'fastify';
+import type { ServiceDefinitions, VeloxModule } from './module/types.js';
 import type { PluginOptions, VeloxPlugin } from './plugin.js';
 import type { StaticOptions } from './plugins/static.js';
 import type { ShutdownHandler } from './types.js';
@@ -41,6 +42,9 @@ export declare class VeloxApp {
     private readonly _lifecycle;
     private _isRunning;
     private _address;
+    private readonly _bootHooks;
+    private readonly _moduleNames;
+    private readonly _serviceNames;
     /**
      * Creates a new VeloxApp instance
      *
@@ -122,6 +126,20 @@ export declare class VeloxApp {
      * ```
      */
     register<Options extends PluginOptions>(plugin: VeloxPlugin<Options> | FastifyPluginAsync<Options>, options?: Options): Promise<void>;
+    /**
+     * Registers a domain module with the application.
+     *
+     * Modules are self-contained vertical slices that bundle services,
+     * middleware, routes, and lifecycle hooks into a single unit.
+     *
+     * @param mod - VeloxModule created via defineModule()
+     * @returns The app instance for method chaining
+     * @throws {VeloxError} INVALID_MODULE - If module was not created via defineModule()
+     * @throws {VeloxError} DUPLICATE_MODULE - If a module with the same name is already registered
+     * @throws {VeloxError} SERVICE_NAME_COLLISION - If a service name conflicts with another module
+     * @throws {VeloxError} MODULE_REGISTRATION_TOO_LATE - If called after server has started
+     */
+    module<TName extends string, TServices extends ServiceDefinitions>(mod: VeloxModule<TName, TServices>): this;
     /**
      * Registers routes with the application
      *

package/dist/app.js

@@ -7,6 +7,8 @@ import fastify from 'fastify';
 import fp from 'fastify-plugin';
 import { setupContextHook } from './context.js';
 import { ConflictError, isVeloxError, VeloxError } from './errors.js';
+import { isVeloxModule } from './module/define-module.js';
+import { createModulePlugin } from './module/register.js';
 import { isFastifyPlugin, isVeloxPlugin, validatePluginMetadata } from './plugin.js';
 import { requestLogger } from './plugins/request-logger.js';
 import { registerStatic } from './plugins/static.js';
@@ -41,6 +43,9 @@ export class VeloxApp {
     _lifecycle;
     _isRunning = false;
     _address = null;
+    _bootHooks = [];
+    _moduleNames = new Set();
+    _serviceNames = new Map();
     /**
      * Creates a new VeloxApp instance
      *
@@ -232,6 +237,71 @@ export class VeloxApp {
         }
         throw new VeloxError('Invalid plugin: must be a VeloxPlugin object or FastifyPluginAsync function', 500, 'INVALID_PLUGIN_TYPE');
     }
+    /**
+     * Registers a domain module with the application.
+     *
+     * Modules are self-contained vertical slices that bundle services,
+     * middleware, routes, and lifecycle hooks into a single unit.
+     *
+     * @param mod - VeloxModule created via defineModule()
+     * @returns The app instance for method chaining
+     * @throws {VeloxError} INVALID_MODULE - If module was not created via defineModule()
+     * @throws {VeloxError} DUPLICATE_MODULE - If a module with the same name is already registered
+     * @throws {VeloxError} SERVICE_NAME_COLLISION - If a service name conflicts with another module
+     * @throws {VeloxError} MODULE_REGISTRATION_TOO_LATE - If called after server has started
+     */
+    module(mod) {
+        if (this._isRunning) {
+            throw new VeloxError('Cannot register modules after server has started', 500, 'MODULE_REGISTRATION_TOO_LATE');
+        }
+        if (!isVeloxModule(mod)) {
+            throw new VeloxError('Invalid module: must be created via defineModule()', 500, 'INVALID_MODULE');
+        }
+        if (this._moduleNames.has(mod.name)) {
+            throw new VeloxError(`Module "${mod.name}" is already registered`, 500, 'DUPLICATE_MODULE');
+        }
+        // Check for service name collisions (all checks before any mutations)
+        const serviceNames = mod.config.services ? Object.keys(mod.config.services) : [];
+        for (const serviceName of serviceNames) {
+            const existingModule = this._serviceNames.get(serviceName);
+            if (existingModule) {
+                throw new VeloxError(`Service name "${serviceName}" in module "${mod.name}" conflicts with module "${existingModule}"`, 500, 'SERVICE_NAME_COLLISION');
+            }
+        }
+        // All checks passed — commit all mutations
+        this._moduleNames.add(mod.name);
+        for (const serviceName of serviceNames) {
+            this._serviceNames.set(serviceName, mod.name);
+        }
+        // Track resolved services for boot/shutdown callbacks
+        let resolvedServices;
+        const plugin = createModulePlugin(mod, (services) => {
+            resolvedServices = services;
+        });
+        // Register module as encapsulated Fastify plugin
+        this._server.register(plugin);
+        // Register boot hook (runs between ready() and listen())
+        if (mod.config.boot) {
+            const bootFn = mod.config.boot;
+            this._bootHooks.push(async () => {
+                if (resolvedServices) {
+                    await bootFn(resolvedServices);
+                }
+            });
+        }
+        // Register shutdown hook
+        if (mod.config.shutdown) {
+            const shutdownFn = mod.config.shutdown;
+            this.beforeShutdown(async () => {
+                if (!resolvedServices) {
+                    log.warn(`Module "${mod.name}" shutdown skipped: services were never initialized`);
+                    return;
+                }
+                await shutdownFn(resolvedServices);
+            });
+        }
+        return this;
+    }
     /**
      * Registers routes with the application
      *
@@ -318,6 +388,10 @@ export class VeloxApp {
         const startTime = performance.now();
         try {
             await this._server.ready();
+            // Execute module boot hooks (after plugins loaded, before accepting traffic)
+            for (const bootHook of this._bootHooks) {
+                await bootHook();
+            }
             const address = await this._server.listen({
                 port: this._config.port,
                 host: this._config.host,

package/dist/errors.d.ts

@@ -8,7 +8,7 @@ export { ERROR_CATALOG, ERROR_DOMAINS, type ErrorCatalogEntry, type ErrorCode, t
  * Known error codes in the VeloxTS framework core
  * Can be extended via declaration merging by plugins
  */
-export type VeloxCoreErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN' | 'UNAUTHORIZED' | 'SERVICE_UNAVAILABLE' | 'RATE_LIMITED' | 'UNPROCESSABLE' | 'CONFIGURATION_ERROR' | 'PLUGIN_REGISTRATION_ERROR' | 'SERVER_ALREADY_RUNNING' | 'SERVER_NOT_RUNNING' | 'SERVER_START_ERROR' | 'SERVER_STOP_ERROR' | 'INVALID_PLUGIN_METADATA';
+export type VeloxCoreErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN' | 'UNAUTHORIZED' | 'SERVICE_UNAVAILABLE' | 'RATE_LIMITED' | 'UNPROCESSABLE' | 'CONFIGURATION_ERROR' | 'PLUGIN_REGISTRATION_ERROR' | 'SERVER_ALREADY_RUNNING' | 'SERVER_NOT_RUNNING' | 'SERVER_START_ERROR' | 'SERVER_STOP_ERROR' | 'INVALID_PLUGIN_METADATA' | 'INVALID_MODULE' | 'INVALID_MODULE_NAME' | 'DUPLICATE_MODULE' | 'SERVICE_NAME_COLLISION' | 'MODULE_REGISTRATION_TOO_LATE';
 /**
  * Registry for error codes - allows plugins to extend via declaration merging
  *

package/dist/index.d.ts

@@ -39,3 +39,5 @@ export type { FireAndForgetOptions } from './utils/fire-and-forget.js';
 export { fireAndForget } from './utils/fire-and-forget.js';
 export type { RetryOptions } from './utils/retry.js';
 export { withRetry } from './utils/retry.js';
+export type { InferModuleServices, InferServices, ModuleConfig, ModuleMiddleware, ServiceDefinition, ServiceDefinitions, VeloxModule, } from './module/index.js';
+export { defineModule, isVeloxModule, MODULE_BRAND } from './module/index.js';

package/dist/index.js

@@ -36,3 +36,4 @@ export { requestLogger } from './plugins/request-logger.js';
 export { createLogger } from './utils/logger.js';
 export { fireAndForget } from './utils/fire-and-forget.js';
 export { withRetry } from './utils/retry.js';
+export { defineModule, isVeloxModule, MODULE_BRAND } from './module/index.js';

package/dist/module/define-module.d.ts

@@ -0,0 +1,58 @@
+/**
+ * defineModule() factory and isVeloxModule() type guard
+ *
+ * Creates self-contained vertical domain slices with services,
+ * middleware, routes, and lifecycle hooks.
+ *
+ * @module module/define-module
+ */
+import type { ModuleConfig, ServiceDefinitions, VeloxModule } from './types.js';
+/**
+ * Defines a VeloxTS module — a self-contained vertical domain slice.
+ *
+ * Modules encapsulate services, middleware, routes, and lifecycle hooks
+ * for a specific domain (e.g., billing, analytics, notifications).
+ *
+ * @template TName - Literal string name of the module
+ * @template TServices - The service definitions provided by this module
+ * @param name - Unique module name (used as route prefix default)
+ * @param config - Module configuration
+ * @returns A frozen VeloxModule ready for registration
+ *
+ * @throws {VeloxError} If name is empty or whitespace-only
+ *
+ * @example
+ * ```typescript
+ * export const billingModule = defineModule('billing', {
+ *   services: {
+ *     stripe: {
+ *       factory: () => new Stripe(process.env.STRIPE_KEY!),
+ *       close: (s) => s.close(),
+ *     },
+ *   },
+ *   routes: rest([billingProcedures]),
+ *   boot: async ({ stripe }) => {
+ *     await stripe.verifyConnection();
+ *   },
+ * });
+ * ```
+ */
+export declare function defineModule<const TName extends string, TServices extends ServiceDefinitions = ServiceDefinitions>(name: TName, config: ModuleConfig<TServices>): VeloxModule<TName, TServices>;
+/**
+ * Type guard to check if a value is a VeloxModule.
+ *
+ * Uses the MODULE_BRAND symbol for reliable runtime identification,
+ * avoiding false positives from duck-typing.
+ *
+ * @param value - Value to check
+ * @returns true if value is a VeloxModule created by defineModule()
+ *
+ * @example
+ * ```typescript
+ * if (isVeloxModule(someValue)) {
+ *   console.log('Module name:', someValue.name);
+ *   await app.module(someValue);
+ * }
+ * ```
+ */
+export declare function isVeloxModule(value: unknown): value is VeloxModule;

package/dist/module/define-module.js

@@ -0,0 +1,73 @@
+/**
+ * defineModule() factory and isVeloxModule() type guard
+ *
+ * Creates self-contained vertical domain slices with services,
+ * middleware, routes, and lifecycle hooks.
+ *
+ * @module module/define-module
+ */
+import { VeloxError } from '../errors.js';
+import { MODULE_BRAND } from './types.js';
+/**
+ * Defines a VeloxTS module — a self-contained vertical domain slice.
+ *
+ * Modules encapsulate services, middleware, routes, and lifecycle hooks
+ * for a specific domain (e.g., billing, analytics, notifications).
+ *
+ * @template TName - Literal string name of the module
+ * @template TServices - The service definitions provided by this module
+ * @param name - Unique module name (used as route prefix default)
+ * @param config - Module configuration
+ * @returns A frozen VeloxModule ready for registration
+ *
+ * @throws {VeloxError} If name is empty or whitespace-only
+ *
+ * @example
+ * ```typescript
+ * export const billingModule = defineModule('billing', {
+ *   services: {
+ *     stripe: {
+ *       factory: () => new Stripe(process.env.STRIPE_KEY!),
+ *       close: (s) => s.close(),
+ *     },
+ *   },
+ *   routes: rest([billingProcedures]),
+ *   boot: async ({ stripe }) => {
+ *     await stripe.verifyConnection();
+ *   },
+ * });
+ * ```
+ */
+export function defineModule(name, config) {
+    if (name.trim() === '') {
+        throw new VeloxError('Module must have a non-empty name', 500, 'INVALID_MODULE_NAME');
+    }
+    return {
+        [MODULE_BRAND]: true,
+        name,
+        config: Object.freeze({ ...config }),
+    };
+}
+/**
+ * Type guard to check if a value is a VeloxModule.
+ *
+ * Uses the MODULE_BRAND symbol for reliable runtime identification,
+ * avoiding false positives from duck-typing.
+ *
+ * @param value - Value to check
+ * @returns true if value is a VeloxModule created by defineModule()
+ *
+ * @example
+ * ```typescript
+ * if (isVeloxModule(someValue)) {
+ *   console.log('Module name:', someValue.name);
+ *   await app.module(someValue);
+ * }
+ * ```
+ */
+export function isVeloxModule(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    return MODULE_BRAND in value && value[MODULE_BRAND] === true;
+}

package/dist/module/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Module system for VeloxTS framework
+ *
+ * Provides defineModule() for creating self-contained vertical domain slices
+ * with services, middleware, routes, and lifecycle hooks.
+ *
+ * @module module
+ */
+export { defineModule, isVeloxModule } from './define-module.js';
+export type { InferModuleServices, InferServices, ModuleConfig, ModuleMiddleware, ServiceDefinition, ServiceDefinitions, VeloxModule, } from './types.js';
+export { MODULE_BRAND } from './types.js';

package/dist/module/index.js

@@ -0,0 +1,10 @@
+/**
+ * Module system for VeloxTS framework
+ *
+ * Provides defineModule() for creating self-contained vertical domain slices
+ * with services, middleware, routes, and lifecycle hooks.
+ *
+ * @module module
+ */
+export { defineModule, isVeloxModule } from './define-module.js';
+export { MODULE_BRAND } from './types.js';

package/dist/module/register.d.ts

@@ -0,0 +1,26 @@
+/**
+ * createModulePlugin() — creates a Fastify plugin from a VeloxModule definition.
+ *
+ * The plugin creates an encapsulated scope that:
+ * 1. Creates service instances via factories (sync or async)
+ * 2. Injects services into every request via decorateRequest + onRequest hook
+ * 3. Applies module middleware as onRequest hooks
+ * 4. Registers routes with the module prefix (auto from name, custom, or disabled)
+ * 5. Adds onClose hooks for service cleanup
+ *
+ * @module module/register
+ */
+import type { FastifyInstance } from 'fastify';
+import type { InferServices, ServiceDefinitions, VeloxModule } from './types.js';
+/**
+ * Creates a Fastify plugin from a VeloxModule definition.
+ *
+ * @param mod - The module definition
+ * @param onServicesResolved - Optional callback invoked after all services are created,
+ *   during plugin registration (before server.ready()). Used by app.module() to capture
+ *   resolved service references for boot/shutdown hooks.
+ * @returns A Fastify plugin function
+ *
+ * @internal Used by app.module() — not typically called directly.
+ */
+export declare function createModulePlugin<TName extends string, TServices extends ServiceDefinitions>(mod: VeloxModule<TName, TServices>, onServicesResolved?: (services: InferServices<TServices>) => void): (server: FastifyInstance) => Promise<void>;

package/dist/module/register.js

@@ -0,0 +1,92 @@
+/**
+ * createModulePlugin() — creates a Fastify plugin from a VeloxModule definition.
+ *
+ * The plugin creates an encapsulated scope that:
+ * 1. Creates service instances via factories (sync or async)
+ * 2. Injects services into every request via decorateRequest + onRequest hook
+ * 3. Applies module middleware as onRequest hooks
+ * 4. Registers routes with the module prefix (auto from name, custom, or disabled)
+ * 5. Adds onClose hooks for service cleanup
+ *
+ * @module module/register
+ */
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('module');
+/**
+ * Creates a Fastify plugin from a VeloxModule definition.
+ *
+ * @param mod - The module definition
+ * @param onServicesResolved - Optional callback invoked after all services are created,
+ *   during plugin registration (before server.ready()). Used by app.module() to capture
+ *   resolved service references for boot/shutdown hooks.
+ * @returns A Fastify plugin function
+ *
+ * @internal Used by app.module() — not typically called directly.
+ */
+export function createModulePlugin(mod, onServicesResolved) {
+    const { config } = mod;
+    return async (server) => {
+        const services = {};
+        if (config.services) {
+            for (const [key, def] of Object.entries(config.services)) {
+                const service = await def.factory();
+                services[key] = service;
+                server.decorateRequest(key, undefined);
+                server.addHook('onRequest', async (request) => {
+                    request[key] = service;
+                });
+                // Cleanup on close
+                if (def.close) {
+                    addCloseHook(server, service, def.close);
+                }
+            }
+        }
+        // Notify caller of resolved services (for boot/shutdown)
+        if (onServicesResolved) {
+            onServicesResolved(services);
+        }
+        // Apply module middleware
+        if (config.middleware) {
+            for (const mw of config.middleware) {
+                server.addHook('onRequest', mw);
+            }
+        }
+        // Register routes with prefix
+        if (config.routes) {
+            const prefix = resolvePrefix(mod.name, config.prefix);
+            if (prefix) {
+                await server.register(config.routes, { prefix });
+            }
+            else {
+                await server.register(config.routes);
+            }
+        }
+        log.debug(`Module "${mod.name}" registered`);
+    };
+}
+/**
+ * Registers an onClose hook with properly correlated types.
+ * Object.entries() erases per-key generics, so we use a helper
+ * to preserve the relationship between the service and its close function.
+ */
+function addCloseHook(server, service, closeFn) {
+    server.addHook('onClose', async () => {
+        await closeFn(service);
+    });
+}
+/**
+ * Resolve the effective route prefix for a module.
+ *
+ * - undefined -> /${name} (auto from module name)
+ * - false -> no prefix
+ * - string -> custom prefix (ensures leading slash)
+ */
+function resolvePrefix(name, prefix) {
+    if (prefix === false) {
+        return undefined;
+    }
+    if (typeof prefix === 'string') {
+        return prefix.startsWith('/') ? prefix : `/${prefix}`;
+    }
+    return `/${name}`;
+}

package/dist/module/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Module system type definitions for VeloxTS framework
+ *
+ * Defines the shape of a VeloxTS module — a self-contained vertical domain slice
+ * with services, middleware, routes, and lifecycle hooks.
+ *
+ * @module module/types
+ */
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+/**
+ * Service definition within a module.
+ * Each service has a factory and optional cleanup.
+ */
+export interface ServiceDefinition<T = unknown> {
+    /** Factory function to create the service instance */
+    factory: () => T | Promise<T>;
+    /** Optional cleanup called on server close */
+    close?: (service: T) => void | Promise<void>;
+}
+/**
+ * Record of named service definitions
+ */
+export type ServiceDefinitions = Record<string, ServiceDefinition>;
+/**
+ * Infer resolved service instances from their definitions.
+ *
+ * @example
+ * ```typescript
+ * const services = {
+ *   db: { factory: () => new Database() },
+ *   cache: { factory: () => new Cache() },
+ * } satisfies ServiceDefinitions;
+ *
+ * type Resolved = InferServices<typeof services>;
+ * // { db: Database; cache: Cache }
+ * ```
+ */
+export type InferServices<T extends ServiceDefinitions> = {
+    [K in keyof T]: T[K] extends ServiceDefinition<infer S> ? S : never;
+};
+/**
+ * Module middleware — a Fastify onRequest hook applied to all routes in the module scope.
+ */
+export type ModuleMiddleware = (request: FastifyRequest, reply: FastifyReply) => void | Promise<void>;
+/**
+ * Configuration for defineModule().
+ *
+ * @template TServices - The service definitions provided by this module
+ */
+export interface ModuleConfig<TServices extends ServiceDefinitions = ServiceDefinitions> {
+    /** Services this module provides (created once, injected per-request) */
+    services?: TServices;
+    /** Module-wide middleware applied to all routes in the module scope */
+    middleware?: ModuleMiddleware[];
+    /**
+     * Fastify plugin for route registration.
+     * Typically the result of rest([...]) from @veloxts/router.
+     */
+    routes?: FastifyPluginAsync;
+    /**
+     * REST route prefix. Defaults to /${moduleName}.
+     * Set false to disable auto-prefix.
+     * Set a string for a custom prefix.
+     */
+    prefix?: string | false;
+    /** Called after all modules registered, before server starts listening */
+    boot?: (services: InferServices<TServices>) => void | Promise<void>;
+    /** Called during graceful shutdown */
+    shutdown?: (services: InferServices<TServices>) => void | Promise<void>;
+}
+/** Brand symbol for VeloxModule type guard */
+export declare const MODULE_BRAND: unique symbol;
+/**
+ * A VeloxTS module — the return type of defineModule().
+ *
+ * Branded with a unique symbol for reliable runtime type checking
+ * via isVeloxModule().
+ *
+ * @template TName - Literal string name of the module
+ * @template TServices - The service definitions provided by this module
+ */
+export interface VeloxModule<TName extends string = string, TServices extends ServiceDefinitions = ServiceDefinitions> {
+    readonly [MODULE_BRAND]: true;
+    readonly name: TName;
+    readonly config: Readonly<ModuleConfig<TServices>>;
+}
+/**
+ * Infer the services type from a VeloxModule instance.
+ * Useful for extending BaseContext via declaration merging.
+ *
+ * @example
+ * ```typescript
+ * const billing = defineModule('billing', {
+ *   services: {
+ *     stripe: { factory: () => new Stripe(process.env.STRIPE_KEY!) },
+ *   },
+ * });
+ *
+ * type BillingServices = InferModuleServices<typeof billing>;
+ * // { stripe: Stripe }
+ * ```
+ */
+export type InferModuleServices<M> = M extends VeloxModule<string, infer S> ? InferServices<S> : never;

package/dist/module/types.js

@@ -0,0 +1,10 @@
+/**
+ * Module system type definitions for VeloxTS framework
+ *
+ * Defines the shape of a VeloxTS module — a self-contained vertical domain slice
+ * with services, middleware, routes, and lifecycle hooks.
+ *
+ * @module module/types
+ */
+/** Brand symbol for VeloxModule type guard */
+export const MODULE_BRAND = Symbol.for('velox:module');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/core",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Fastify wrapper and plugin system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",