@veloxts/router 0.4.1 → 0.4.3

package/dist/discovery/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Procedure Discovery Errors
+ *
+ * Error classes and factory functions for the discovery system.
+ * Uses E40xx error code range.
+ *
+ * @module discovery/errors
+ */
+import { DiscoveryErrorCode } from './types.js';
+/**
+ * Error thrown during procedure discovery operations
+ */
+export declare class DiscoveryError extends Error {
+    /** Error code identifier */
+    readonly code: DiscoveryErrorCode;
+    /** Optional file path where the error occurred */
+    readonly filePath?: string;
+    /** Suggested fix for the error */
+    readonly fix?: string;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    constructor(code: DiscoveryErrorCode, message: string, options?: {
+        readonly filePath?: string;
+        readonly fix?: string;
+        readonly details?: Record<string, unknown>;
+        readonly cause?: Error;
+    });
+    /**
+     * Format the error for display
+     */
+    format(): string;
+    /**
+     * Convert to JSON for serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Type guard to check if an error is a DiscoveryError
+ */
+export declare function isDiscoveryError(error: unknown): error is DiscoveryError;
+/**
+ * Create error for directory not found
+ */
+export declare function directoryNotFound(path: string): DiscoveryError;
+/**
+ * Create error for no procedures found
+ */
+export declare function noProceduresFound(path: string, scannedCount: number): DiscoveryError;
+/**
+ * Create error for invalid export
+ */
+export declare function invalidExport(filePath: string, exportName: string, reason: string): DiscoveryError;
+/**
+ * Create error for file load failure
+ */
+export declare function fileLoadError(filePath: string, cause: Error): DiscoveryError;
+/**
+ * Create error for permission denied
+ */
+export declare function permissionDenied(path: string): DiscoveryError;
+/**
+ * Create error for invalid file type
+ */
+export declare function invalidFileType(filePath: string, extension: string): DiscoveryError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/discovery/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/discovery/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAMhD;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,4BAA4B;IAC5B,SAAgB,IAAI,EAAE,kBAAkB,CAAC;IAEzC,kDAAkD;IAClD,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElC,kCAAkC;IAClC,SAAgB,GAAG,CAAC,EAAE,MAAM,CAAC;IAE7B,+BAA+B;IAC/B,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGhD,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;KACxB;IAUH;;OAEG;IACH,MAAM,IAAI,MAAM;IAchB;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAS9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,cAAc,CAapF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,cAAc,CAUhB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,cAAc,CAU5E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAS7D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,cAAc,CAUnF"}

package/dist/discovery/errors.js

@@ -0,0 +1,131 @@
+/**
+ * Procedure Discovery Errors
+ *
+ * Error classes and factory functions for the discovery system.
+ * Uses E40xx error code range.
+ *
+ * @module discovery/errors
+ */
+import { DiscoveryErrorCode } from './types.js';
+// ============================================================================
+// Error Class
+// ============================================================================
+/**
+ * Error thrown during procedure discovery operations
+ */
+export class DiscoveryError extends Error {
+    /** Error code identifier */
+    code;
+    /** Optional file path where the error occurred */
+    filePath;
+    /** Suggested fix for the error */
+    fix;
+    /** Additional error details */
+    details;
+    constructor(code, message, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'DiscoveryError';
+        this.code = code;
+        this.filePath = options?.filePath;
+        this.fix = options?.fix;
+        this.details = options?.details;
+    }
+    /**
+     * Format the error for display
+     */
+    format() {
+        let output = `DiscoveryError[${this.code}]: ${this.message}`;
+        if (this.filePath) {
+            output += `\n\n  File: ${this.filePath}`;
+        }
+        if (this.fix) {
+            output += `\n\n  Fix: ${this.fix}`;
+        }
+        return output;
+    }
+    /**
+     * Convert to JSON for serialization
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            filePath: this.filePath,
+            fix: this.fix,
+            details: this.details,
+        };
+    }
+}
+// ============================================================================
+// Type Guard
+// ============================================================================
+/**
+ * Type guard to check if an error is a DiscoveryError
+ */
+export function isDiscoveryError(error) {
+    return error instanceof DiscoveryError;
+}
+// ============================================================================
+// Error Factory Functions
+// ============================================================================
+/**
+ * Create error for directory not found
+ */
+export function directoryNotFound(path) {
+    return new DiscoveryError(DiscoveryErrorCode.DIRECTORY_NOT_FOUND, `Procedures directory not found: ${path}`, {
+        filePath: path,
+        fix: 'Create the procedures directory or check the path. Expected structure: src/procedures/*.ts',
+    });
+}
+/**
+ * Create error for no procedures found
+ */
+export function noProceduresFound(path, scannedCount) {
+    return new DiscoveryError(DiscoveryErrorCode.NO_PROCEDURES_FOUND, `No procedure collections found in ${path}`, {
+        filePath: path,
+        details: { scannedFiles: scannedCount },
+        fix: scannedCount === 0
+            ? 'Create procedure files using: velox generate procedure <name>'
+            : 'Ensure files export ProcedureCollection objects using defineProcedures()',
+    });
+}
+/**
+ * Create error for invalid export
+ */
+export function invalidExport(filePath, exportName, reason) {
+    return new DiscoveryError(DiscoveryErrorCode.INVALID_EXPORT, `Invalid export '${exportName}' in ${filePath}: ${reason}`, {
+        filePath,
+        details: { exportName, reason },
+        fix: 'Export must be a ProcedureCollection created with defineProcedures(namespace, procedures)',
+    });
+}
+/**
+ * Create error for file load failure
+ */
+export function fileLoadError(filePath, cause) {
+    return new DiscoveryError(DiscoveryErrorCode.FILE_LOAD_ERROR, `Failed to load procedure file: ${filePath} - ${cause.message}`, {
+        filePath,
+        cause,
+        fix: 'Check for syntax errors or missing dependencies in the file',
+    });
+}
+/**
+ * Create error for permission denied
+ */
+export function permissionDenied(path) {
+    return new DiscoveryError(DiscoveryErrorCode.PERMISSION_DENIED, `Permission denied accessing: ${path}`, {
+        filePath: path,
+        fix: 'Check file permissions and ensure the process has read access',
+    });
+}
+/**
+ * Create error for invalid file type
+ */
+export function invalidFileType(filePath, extension) {
+    return new DiscoveryError(DiscoveryErrorCode.INVALID_FILE_TYPE, `Unsupported file type: ${extension}`, {
+        filePath,
+        details: { extension },
+        fix: 'Procedure files must be .ts, .js, .mts, or .mjs',
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/discovery/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/discovery/errors.ts"],"names":[],"mappings":"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"}

package/dist/discovery/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Procedure Discovery Module
+ *
+ * Auto-scan and register procedures from the filesystem.
+ *
+ * @module discovery
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { discoverProcedures, rest } from '@veloxts/router';
+ *
+ * const collections = await discoverProcedures('./src/procedures');
+ * await app.register(rest(collections), { prefix: '/api' });
+ * ```
+ *
+ * @example With options
+ * ```typescript
+ * const collections = await discoverProcedures('./src/procedures', {
+ *   recursive: true,
+ *   onInvalidExport: 'warn',
+ * });
+ * ```
+ *
+ * @example Verbose mode for tooling
+ * ```typescript
+ * const result = await discoverProceduresVerbose('./src/procedures');
+ * console.log(`Found ${result.collections.length} collections`);
+ * console.log(`Scanned ${result.scannedFiles.length} files`);
+ * ```
+ */
+export { DiscoveryError, directoryNotFound, fileLoadError, invalidExport, invalidFileType, isDiscoveryError, noProceduresFound, permissionDenied, } from './errors.js';
+export { discoverProcedures, discoverProceduresVerbose } from './loader.js';
+export type { DiscoveryOptions, DiscoveryResult, DiscoveryWarning } from './types.js';
+export { DiscoveryErrorCode } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/discovery/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/discovery/index.js

@@ -0,0 +1,34 @@
+/**
+ * Procedure Discovery Module
+ *
+ * Auto-scan and register procedures from the filesystem.
+ *
+ * @module discovery
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { discoverProcedures, rest } from '@veloxts/router';
+ *
+ * const collections = await discoverProcedures('./src/procedures');
+ * await app.register(rest(collections), { prefix: '/api' });
+ * ```
+ *
+ * @example With options
+ * ```typescript
+ * const collections = await discoverProcedures('./src/procedures', {
+ *   recursive: true,
+ *   onInvalidExport: 'warn',
+ * });
+ * ```
+ *
+ * @example Verbose mode for tooling
+ * ```typescript
+ * const result = await discoverProceduresVerbose('./src/procedures');
+ * console.log(`Found ${result.collections.length} collections`);
+ * console.log(`Scanned ${result.scannedFiles.length} files`);
+ * ```
+ */
+export { DiscoveryError, directoryNotFound, fileLoadError, invalidExport, invalidFileType, isDiscoveryError, noProceduresFound, permissionDenied, } from './errors.js';
+export { discoverProcedures, discoverProceduresVerbose } from './loader.js';
+export { DiscoveryErrorCode } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/discovery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/discovery/loader.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Procedure Discovery Loader
+ *
+ * Core logic for scanning the filesystem and loading procedure collections.
+ * Uses dynamic imports with ESM-compatible file URLs.
+ *
+ * @module discovery/loader
+ */
+import type { ProcedureCollection } from '../types.js';
+import { type DiscoveryOptions, type DiscoveryResult } from './types.js';
+/**
+ * Discover procedure collections from the filesystem
+ *
+ * Scans a directory for files exporting ProcedureCollection objects,
+ * validates them at runtime, and returns type-safe results.
+ *
+ * @param searchPath - Absolute or relative path to procedures directory
+ * @param options - Discovery configuration
+ * @returns Promise resolving to discovered procedure collections
+ *
+ * @example Basic usage
+ * ```typescript
+ * const collections = await discoverProcedures('./src/procedures');
+ * await app.register(rest(collections), { prefix: '/api' });
+ * ```
+ *
+ * @example With options
+ * ```typescript
+ * const collections = await discoverProcedures('./src/procedures', {
+ *   recursive: true,
+ *   cwd: process.cwd(),
+ * });
+ * ```
+ */
+export declare function discoverProcedures(searchPath: string, options?: DiscoveryOptions): Promise<ProcedureCollection[]>;
+/**
+ * Discover procedure collections with detailed results
+ *
+ * Same as discoverProcedures but returns additional metadata about
+ * scanned files, loaded files, and any warnings.
+ *
+ * @param searchPath - Absolute or relative path to procedures directory
+ * @param options - Discovery configuration
+ * @returns Promise resolving to detailed discovery results
+ *
+ * @example
+ * ```typescript
+ * const result = await discoverProceduresVerbose('./src/procedures', {
+ *   onInvalidExport: 'warn',
+ * });
+ *
+ * console.log(`Found ${result.collections.length} collections`);
+ * console.log(`Scanned ${result.scannedFiles.length} files`);
+ * result.warnings.forEach(w => console.warn(w.message));
+ * ```
+ */
+export declare function discoverProceduresVerbose(searchPath: string, options?: DiscoveryOptions): Promise<DiscoveryResult>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/discovery/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/discovery/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AASvD,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAIrB,MAAM,YAAY,CAAC;AAcpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAGhC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAyE1B"}