@spfn/core 0.1.0-alpha.64 → 0.1.0-alpha.68

package/dist/error-handler-wjLL3v-a.d.ts

@@ -0,0 +1,44 @@
+import { Context } from 'hono';
+
+/**
+ * Error Handler Middleware
+ *
+ * Generic middleware that converts errors with statusCode to HTTP responses
+ */
+
+interface ErrorHandlerOptions {
+    /**
+     * Include stack trace in response
+     * @default process.env.NODE_ENV !== 'production'
+     */
+    includeStack?: boolean;
+    /**
+     * Enable error logging
+     * @default true
+     */
+    enableLogging?: boolean;
+}
+/**
+ * Standard error response format
+ *
+ * Used by ErrorHandler middleware for all error responses.
+ * Compatible with ApiResponse pattern for consistent API responses.
+ */
+interface ErrorResponse {
+    success: false;
+    error: {
+        message: string;
+        type: string;
+        statusCode: number;
+        stack?: string;
+        details?: any;
+    };
+}
+/**
+ * Error handler middleware
+ *
+ * Used in Hono's onError hook
+ */
+declare function ErrorHandler(options?: ErrorHandlerOptions): (err: Error, c: Context) => Response | Promise<Response>;
+
+export { ErrorHandler as E, type ErrorHandlerOptions as a, type ErrorResponse as b };

package/dist/errors/index.d.ts

@@ -0,0 +1,119 @@
+import { D as DatabaseError } from '../database-errors-CoPrcOpq.js';
+export { C as ConnectionError, a as ConstraintViolationError, b as DeadlockError, c as DuplicateEntryError, N as NotFoundError, Q as QueryError, T as TransactionError } from '../database-errors-CoPrcOpq.js';
+
+/**
+ * HTTP Error Classes
+ *
+ * Standard HTTP error classes for API responses
+ * Covers common HTTP status codes beyond database errors
+ */
+/**
+ * Base HTTP Error
+ *
+ * Base class for all HTTP-related errors
+ */
+declare class HttpError<TDetails extends Record<string, unknown> = Record<string, unknown>> extends Error {
+    readonly statusCode: number;
+    readonly details?: TDetails;
+    readonly timestamp: Date;
+    constructor(message: string, statusCode: number, details?: TDetails);
+    /**
+     * Serialize error for API response
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        statusCode: number;
+        details: TDetails | undefined;
+        timestamp: string;
+    };
+}
+/**
+ * Bad Request Error (400)
+ *
+ * Generic bad request - malformed syntax, invalid parameters, etc.
+ */
+declare class BadRequestError extends HttpError {
+    constructor(message?: string, details?: Record<string, any>);
+}
+/**
+ * Validation Error (400)
+ *
+ * Input validation failure (request params, query, body)
+ * Used by contract-based routing for automatic validation
+ */
+declare class ValidationError extends HttpError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Unauthorized Error (401)
+ *
+ * Authentication required or authentication failed
+ */
+declare class UnauthorizedError extends HttpError {
+    constructor(message?: string, details?: Record<string, any>);
+}
+/**
+ * Forbidden Error (403)
+ *
+ * Authenticated but lacks permission to access resource
+ */
+declare class ForbiddenError extends HttpError {
+    constructor(message?: string, details?: Record<string, any>);
+}
+/**
+ * Conflict Error (409)
+ *
+ * Generic conflict - resource state conflict, concurrent modification, etc.
+ * More general than DuplicateEntryError
+ */
+declare class ConflictError extends HttpError {
+    constructor(message?: string, details?: Record<string, any>);
+}
+/**
+ * Too Many Requests Error (429)
+ *
+ * Rate limit exceeded
+ */
+declare class TooManyRequestsError extends HttpError {
+    constructor(message?: string, retryAfter?: number, details?: Record<string, any>);
+}
+/**
+ * Internal Server Error (500)
+ *
+ * Generic server error when no specific error type applies
+ */
+declare class InternalServerError extends HttpError {
+    constructor(message?: string, details?: Record<string, any>);
+}
+/**
+ * Service Unavailable Error (503)
+ *
+ * Service temporarily unavailable (maintenance, overload, etc.)
+ */
+declare class ServiceUnavailableError extends HttpError {
+    constructor(message?: string, retryAfter?: number, details?: Record<string, any>);
+}
+
+/**
+ * Error Utility Functions
+ *
+ * Generic error type checking utilities
+ */
+
+/**
+ * Check if error is a DatabaseError
+ */
+declare function isDatabaseError(error: unknown): error is DatabaseError;
+/**
+ * Check if error is an HttpError
+ */
+declare function isHttpError(error: unknown): error is HttpError;
+/**
+ * Check if error has a statusCode property
+ */
+declare function hasStatusCode(error: unknown): error is {
+    statusCode: number;
+};
+
+export { BadRequestError, ConflictError, DatabaseError, ForbiddenError, HttpError, InternalServerError, ServiceUnavailableError, TooManyRequestsError, UnauthorizedError, ValidationError, hasStatusCode, isDatabaseError, isHttpError };

package/dist/errors/index.js

@@ -0,0 +1,160 @@
+// src/errors/database-errors.ts
+var DatabaseError = class extends Error {
+  statusCode;
+  details;
+  timestamp;
+  constructor(message, statusCode = 500, details) {
+    super(message);
+    this.name = "DatabaseError";
+    this.statusCode = statusCode;
+    this.details = details;
+    this.timestamp = /* @__PURE__ */ new Date();
+    Error.captureStackTrace(this, this.constructor);
+  }
+  /**
+   * Serialize error for API response
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details,
+      timestamp: this.timestamp.toISOString()
+    };
+  }
+};
+var ConnectionError = class extends DatabaseError {
+  constructor(message, details) {
+    super(message, 503, details);
+    this.name = "ConnectionError";
+  }
+};
+var QueryError = class extends DatabaseError {
+  constructor(message, statusCode = 500, details) {
+    super(message, statusCode, details);
+    this.name = "QueryError";
+  }
+};
+var NotFoundError = class extends QueryError {
+  constructor(resource, id) {
+    super(`${resource} with id ${id} not found`, 404, { resource, id });
+    this.name = "NotFoundError";
+  }
+};
+var ConstraintViolationError = class extends QueryError {
+  constructor(message, details) {
+    super(message, 400, details);
+    this.name = "ConstraintViolationError";
+  }
+};
+var TransactionError = class extends DatabaseError {
+  constructor(message, statusCode = 500, details) {
+    super(message, statusCode, details);
+    this.name = "TransactionError";
+  }
+};
+var DeadlockError = class extends TransactionError {
+  constructor(message, details) {
+    super(message, 409, details);
+    this.name = "DeadlockError";
+  }
+};
+var DuplicateEntryError = class extends QueryError {
+  constructor(field, value) {
+    super(`${field} '${value}' already exists`, 409, { field, value });
+    this.name = "DuplicateEntryError";
+  }
+};
+
+// src/errors/http-errors.ts
+var HttpError = class extends Error {
+  statusCode;
+  details;
+  timestamp;
+  constructor(message, statusCode, details) {
+    super(message);
+    this.name = "HttpError";
+    this.statusCode = statusCode;
+    this.details = details;
+    this.timestamp = /* @__PURE__ */ new Date();
+    Error.captureStackTrace(this, this.constructor);
+  }
+  /**
+   * Serialize error for API response
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details,
+      timestamp: this.timestamp.toISOString()
+    };
+  }
+};
+var BadRequestError = class extends HttpError {
+  constructor(message = "Bad request", details) {
+    super(message, 400, details);
+    this.name = "BadRequestError";
+  }
+};
+var ValidationError = class extends HttpError {
+  constructor(message, details) {
+    super(message, 400, details);
+    this.name = "ValidationError";
+  }
+};
+var UnauthorizedError = class extends HttpError {
+  constructor(message = "Authentication required", details) {
+    super(message, 401, details);
+    this.name = "UnauthorizedError";
+  }
+};
+var ForbiddenError = class extends HttpError {
+  constructor(message = "Access forbidden", details) {
+    super(message, 403, details);
+    this.name = "ForbiddenError";
+  }
+};
+var ConflictError = class extends HttpError {
+  constructor(message = "Resource conflict", details) {
+    super(message, 409, details);
+    this.name = "ConflictError";
+  }
+};
+var TooManyRequestsError = class extends HttpError {
+  constructor(message = "Too many requests", retryAfter, details) {
+    const fullDetails = retryAfter ? { ...details, retryAfter } : details;
+    super(message, 429, fullDetails);
+    this.name = "TooManyRequestsError";
+  }
+};
+var InternalServerError = class extends HttpError {
+  constructor(message = "Internal server error", details) {
+    super(message, 500, details);
+    this.name = "InternalServerError";
+  }
+};
+var ServiceUnavailableError = class extends HttpError {
+  constructor(message = "Service unavailable", retryAfter, details) {
+    const fullDetails = retryAfter ? { ...details, retryAfter } : details;
+    super(message, 503, fullDetails);
+    this.name = "ServiceUnavailableError";
+  }
+};
+
+// src/errors/error-utils.ts
+function isDatabaseError(error) {
+  return error instanceof DatabaseError;
+}
+function isHttpError(error) {
+  return error instanceof HttpError;
+}
+function hasStatusCode(error) {
+  return typeof error === "object" && error !== null && "statusCode" in error && typeof error.statusCode === "number";
+}
+
+export { BadRequestError, ConflictError, ConnectionError, ConstraintViolationError, DatabaseError, DeadlockError, DuplicateEntryError, ForbiddenError, HttpError, InternalServerError, NotFoundError, QueryError, ServiceUnavailableError, TooManyRequestsError, TransactionError, UnauthorizedError, ValidationError, hasStatusCode, isDatabaseError, isHttpError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors/database-errors.ts","../../src/errors/http-errors.ts","../../src/errors/error-utils.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Database Error Classes\n *\n * Type-safe error handling with custom error class hierarchy\n * Mapped to HTTP status codes for API responses\n */\n\n/**\n * Base Database Error\n *\n * Base class for all database-related errors\n */\nexport class DatabaseError<TDetails extends Record<string, unknown> = Record<string, unknown>> extends Error\n{\n    public readonly statusCode: number;\n    public readonly details?: TDetails;\n    public readonly timestamp: Date;\n\n    constructor(\n        message: string,\n        statusCode: number = 500,\n        details?: TDetails\n    )\n    {\n        super(message);\n        this.name = 'DatabaseError';\n        this.statusCode = statusCode;\n        this.details = details;\n        this.timestamp = new Date();\n        Error.captureStackTrace(this, this.constructor);\n    }\n\n    /**\n     * Serialize error for API response\n     */\n    toJSON()\n    {\n        return {\n            name: this.name,\n            message: this.message,\n            statusCode: this.statusCode,\n            details: this.details,\n            timestamp: this.timestamp.toISOString()\n        };\n    }\n}\n\n/**\n * Connection Error (503 Service Unavailable)\n *\n * Database connection failure, connection pool exhaustion, etc.\n */\nexport class ConnectionError extends DatabaseError\n{\n    constructor(message: string, details?: Record<string, any>)\n    {\n        super(message, 503, details);\n        this.name = 'ConnectionError';\n    }\n}\n\n/**\n * Query Error (500 Internal Server Error)\n *\n * SQL query execution failure, syntax errors, etc.\n */\nexport class QueryError extends DatabaseError\n{\n    constructor(message: string, statusCode: number = 500, details?: Record<string, any>)\n    {\n        super(message, statusCode, details);\n        this.name = 'QueryError';\n    }\n}\n\n/**\n * Not Found Error (404 Not Found)\n *\n * Requested resource does not exist\n */\nexport class NotFoundError extends QueryError\n{\n    constructor(resource: string, id: string | number)\n    {\n        super(`${resource} with id ${id} not found`, 404, { resource, id });\n        this.name = 'NotFoundError';\n    }\n}\n\n/**\n * Constraint Violation Error (400 Bad Request)\n *\n * Database constraint violation (NOT NULL, CHECK, FOREIGN KEY, etc.)\n * This is different from HTTP ValidationError which validates request input\n */\nexport class ConstraintViolationError extends QueryError\n{\n    constructor(message: string, details?: Record<string, any>)\n    {\n        super(message, 400, details);\n        this.name = 'ConstraintViolationError';\n    }\n}\n\n/**\n * Transaction Error (500 Internal Server Error)\n *\n * Transaction start/commit/rollback failure\n */\nexport class TransactionError extends DatabaseError\n{\n    constructor(message: string, statusCode: number = 500, details?: Record<string, any>)\n    {\n        super(message, statusCode, details);\n        this.name = 'TransactionError';\n    }\n}\n\n/**\n * Deadlock Error (409 Conflict)\n *\n * Database deadlock detected\n */\nexport class DeadlockError extends TransactionError\n{\n    constructor(message: string, details?: Record<string, any>)\n    {\n        super(message, 409, details);\n        this.name = 'DeadlockError';\n    }\n}\n\n/**\n * Duplicate Entry Error (409 Conflict)\n *\n * Unique constraint violation (e.g., duplicate email)\n */\nexport class DuplicateEntryError extends QueryError\n{\n    constructor(field: string, value: string | number)\n    {\n        super(`${field} '${value}' already exists`, 409, { field, value });\n        this.name = 'DuplicateEntryError';\n    }\n}","/**\n * HTTP Error Classes\n *\n * Standard HTTP error classes for API responses\n * Covers common HTTP status codes beyond database errors\n */\n\n/**\n * Base HTTP Error\n *\n * Base class for all HTTP-related errors\n */\nexport class HttpError<TDetails extends Record<string, unknown> = Record<string, unknown>> extends Error\n{\n    public readonly statusCode: number;\n    public readonly details?: TDetails;\n    public readonly timestamp: Date;\n\n    constructor(\n        message: string,\n        statusCode: number,\n        details?: TDetails\n    )\n    {\n        super(message);\n        this.name = 'HttpError';\n        this.statusCode = statusCode;\n        this.details = details;\n        this.timestamp = new Date();\n        Error.captureStackTrace(this, this.constructor);\n    }\n\n    /**\n     * Serialize error for API response\n     */\n    toJSON()\n    {\n        return {\n            name: this.name,\n            message: this.message,\n            statusCode: this.statusCode,\n            details: this.details,\n            timestamp: this.timestamp.toISOString()\n        };\n    }\n}\n\n/**\n * Bad Request Error (400)\n *\n * Generic bad request - malformed syntax, invalid parameters, etc.\n */\nexport class BadRequestError extends HttpError\n{\n    constructor(message: string = 'Bad request', details?: Record<string, any>)\n    {\n        super(message, 400, details);\n        this.name = 'BadRequestError';\n    }\n}\n\n/**\n * Validation Error (400)\n *\n * Input validation failure (request params, query, body)\n * Used by contract-based routing for automatic validation\n */\nexport class ValidationError extends HttpError\n{\n    constructor(message: string, details?: Record<string, any>)\n    {\n        super(message, 400, details);\n        this.name = 'ValidationError';\n    }\n}\n\n/**\n * Unauthorized Error (401)\n *\n * Authentication required or authentication failed\n */\nexport class UnauthorizedError extends HttpError\n{\n    constructor(message: string = 'Authentication required', details?: Record<string, any>)\n    {\n        super(message, 401, details);\n        this.name = 'UnauthorizedError';\n    }\n}\n\n/**\n * Forbidden Error (403)\n *\n * Authenticated but lacks permission to access resource\n */\nexport class ForbiddenError extends HttpError\n{\n    constructor(message: string = 'Access forbidden', details?: Record<string, any>)\n    {\n        super(message, 403, details);\n        this.name = 'ForbiddenError';\n    }\n}\n\n/**\n * Conflict Error (409)\n *\n * Generic conflict - resource state conflict, concurrent modification, etc.\n * More general than DuplicateEntryError\n */\nexport class ConflictError extends HttpError\n{\n    constructor(message: string = 'Resource conflict', details?: Record<string, any>)\n    {\n        super(message, 409, details);\n        this.name = 'ConflictError';\n    }\n}\n\n/**\n * Too Many Requests Error (429)\n *\n * Rate limit exceeded\n */\nexport class TooManyRequestsError extends HttpError\n{\n    constructor(\n        message: string = 'Too many requests',\n        retryAfter?: number,\n        details?: Record<string, any>\n    )\n    {\n        const fullDetails = retryAfter\n            ? { ...details, retryAfter }\n            : details;\n\n        super(message, 429, fullDetails);\n        this.name = 'TooManyRequestsError';\n    }\n}\n\n/**\n * Internal Server Error (500)\n *\n * Generic server error when no specific error type applies\n */\nexport class InternalServerError extends HttpError\n{\n    constructor(message: string = 'Internal server error', details?: Record<string, any>)\n    {\n        super(message, 500, details);\n        this.name = 'InternalServerError';\n    }\n}\n\n/**\n * Service Unavailable Error (503)\n *\n * Service temporarily unavailable (maintenance, overload, etc.)\n */\nexport class ServiceUnavailableError extends HttpError\n{\n    constructor(\n        message: string = 'Service unavailable',\n        retryAfter?: number,\n        details?: Record<string, any>\n    )\n    {\n        const fullDetails = retryAfter\n            ? { ...details, retryAfter }\n            : details;\n\n        super(message, 503, fullDetails);\n        this.name = 'ServiceUnavailableError';\n    }\n}","/**\n * Error Utility Functions\n *\n * Generic error type checking utilities\n */\n\nimport { DatabaseError } from './database-errors.js';\nimport { HttpError } from './http-errors.js';\n\n/**\n * Check if error is a DatabaseError\n */\nexport function isDatabaseError(error: unknown): error is DatabaseError\n{\n    return error instanceof DatabaseError;\n}\n\n/**\n * Check if error is an HttpError\n */\nexport function isHttpError(error: unknown): error is HttpError\n{\n    return error instanceof HttpError;\n}\n\n/**\n * Check if error has a statusCode property\n */\nexport function hasStatusCode(error: unknown): error is { statusCode: number }\n{\n    return (\n        typeof error === 'object' &&\n        error !== null &&\n        'statusCode' in error &&\n        typeof (error as any).statusCode === 'number'\n    );\n}\n"]}

package/dist/index-DHiAqhKv.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Generator Interface
+ *
+ * Defines the contract for code generators that can be orchestrated by the codegen system.
+ */
+/**
+ * Generator execution trigger types
+ */
+type GeneratorTrigger = 'watch' | 'manual' | 'build' | 'start';
+interface GeneratorOptions {
+    /** Project root directory */
+    cwd: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Execution trigger information */
+    trigger?: {
+        /** How the generator was triggered */
+        type: GeneratorTrigger;
+        /** Changed file information (only for 'watch' trigger) */
+        changedFile?: {
+            path: string;
+            event: 'add' | 'change' | 'unlink';
+        };
+    };
+    /** Custom configuration options */
+    [key: string]: any;
+}
+interface Generator {
+    /** Unique generator name */
+    name: string;
+    /** File patterns to watch (glob patterns) */
+    watchPatterns: string[];
+    /**
+     * When this generator should run
+     *
+     * @default ['watch', 'manual', 'build']
+     *
+     * Examples:
+     * - ['watch', 'build']: Run during development and build (e.g., admin-nav-generator)
+     * - ['build', 'start']: Run during build and server start (e.g., db-migration)
+     * - ['watch', 'manual']: Run during development and manual CLI (e.g., contract-generator)
+     * - ['start']: Run only on server start (e.g., runtime config generator)
+     */
+    runOn?: GeneratorTrigger[];
+    /**
+     * Generate code
+     *
+     * Generator can implement incremental updates by checking `options.trigger.changedFile`.
+     * If incremental update is not possible, do full regeneration.
+     *
+     * @param options - Generator options with trigger context
+     *
+     * @example
+     * ```typescript
+     * async generate(options: GeneratorOptions): Promise<void>
+     * {
+     *     // Check if incremental update is possible
+     *     if (options.trigger?.changedFile)
+     *     {
+     *         const { path, event } = options.trigger.changedFile;
+     *
+     *         if (canDoIncrementalUpdate(path, event))
+     *         {
+     *             await updateSingleFile(path);
+     *             return;
+     *         }
+     *     }
+     *
+     *     // Fallback: full regeneration
+     *     await fullRegenerate();
+     * }
+     * ```
+     */
+    generate(options: GeneratorOptions): Promise<void>;
+}
+
+/**
+ * Contract Generator
+ *
+ * Generates type-safe API client from contract definitions
+ *
+ * Features:
+ * - Automatic scanning of contract files
+ * - Type-safe client generation with InferContract
+ * - Split output by resource for better code organization
+ * - Incremental updates when single files change (smart regeneration)
+ */
+
+interface ContractGeneratorConfig {
+    /** Contracts directory (default: src/lib/contracts) */
+    contractsDir?: string;
+    /** Output directory (default: src/lib/api) */
+    outputPath?: string;
+    /** Base URL for API client */
+    baseUrl?: string;
+    /** When to run this generator (default: ['watch', 'manual', 'build']) */
+    runOn?: GeneratorTrigger[];
+}
+declare function createContractGenerator(config?: ContractGeneratorConfig): Generator;
+
+export { type ContractGeneratorConfig as C, type Generator as G, type GeneratorTrigger as a, type GeneratorOptions as b, createContractGenerator as c };

package/dist/index.d.ts

@@ -1,233 +1,7 @@
 export { AppFactory, ServerConfig, createServer, startServer } from './server/index.js';
-export { A as AutoRouteLoader, R as RouteInfo, a as RouteStats, l as loadRoutes } from './auto-loader-CdsxOceW.js';
-export { b as bind } from './bind-CSzshBtm.js';
-export { d as HttpMethod, I as InferContract, c as RouteContext, R as RouteContract, a as RouteHandler, i as isHttpMethod } from './types-Bd8YsFSU.js';
-import { D as DatabaseError } from './postgres-errors-lw1aRUFe.js';
-export { C as ConnectionError, l as DeadlockError, c as DrizzleConfigOptions, m as DuplicateEntryError, N as NotFoundError, Q as QueryError, h as TransactionContext, k as TransactionError, T as Transactional, j as TransactionalOptions, V as ValidationError, d as detectDialect, f as foreignKey, b as fromPostgresError, a as generateDrizzleConfigFile, g as getDrizzleConfig, e as getTransaction, i as id, o as optionalForeignKey, r as runWithTransaction, t as timestamps } from './postgres-errors-lw1aRUFe.js';
-import { Redis, Cluster } from 'ioredis';
-export { LogLevel, LoggerAdapter, logger } from './logger/index.js';
-import { Context, Next } from 'hono';
+export { H as HttpMethod, I as InferContract, R as RouteContext, a as RouteContract, b as RouteHandler, i as isHttpMethod } from './types-CAON3Mmg.js';
+import 'hono';
 import 'hono/cors';
 import '@hono/node-server';
 import 'hono/utils/http-status';
 import '@sinclair/typebox';
-import 'drizzle-orm';
-import 'drizzle-orm/pg-core';
-import 'drizzle-orm/postgres-js';
-
-/**
- * Error Utility Functions
- *
- * Generic error type checking utilities
- */
-
-/**
- * Check if error is a DatabaseError
- */
-declare function isDatabaseError(error: unknown): error is DatabaseError;
-
-/**
- * Redis factory with automatic environment variable detection
- * Supports: Single, Master-Replica, Sentinel, Cluster
- */
-
-interface RedisClients {
-    /** Primary Redis for writes (or both read/write if no replica) */
-    write?: Redis | Cluster;
-    /** Replica Redis for reads (optional, falls back to write) */
-    read?: Redis | Cluster;
-}
-/**
- * Create Redis client(s) from environment variables
- *
- * Supported patterns (priority order):
- * 1. Single instance: REDIS_URL
- * 2. Master-Replica: REDIS_WRITE_URL + REDIS_READ_URL
- * 3. Sentinel: REDIS_SENTINEL_HOSTS + REDIS_MASTER_NAME
- * 4. Cluster: REDIS_CLUSTER_NODES
- *
- * @returns Redis client(s) or undefined if no configuration found
- *
- * @example
- * ```bash
- * # Single (most common)
- * REDIS_URL=redis://localhost:6379
- * REDIS_URL=rediss://secure.redis.com:6380  # TLS
- *
- * # Master-Replica
- * REDIS_WRITE_URL=redis://master:6379
- * REDIS_READ_URL=redis://replica:6379
- *
- * # Sentinel
- * REDIS_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379
- * REDIS_MASTER_NAME=mymaster
- * REDIS_PASSWORD=secret
- *
- * # Cluster
- * REDIS_CLUSTER_NODES=node1:6379,node2:6379,node3:6379
- * REDIS_PASSWORD=secret
- * ```
- */
-declare function createRedisFromEnv(): Promise<RedisClients>;
-/**
- * Create single Redis client (backward compatibility)
- * Only returns write instance
- */
-declare function createSingleRedisFromEnv(): Promise<Redis | Cluster | undefined>;
-
-/**
- * Global Redis instance manager
- * Provides singleton access to Redis across all modules
- * Supports Master-Replica pattern with separate read/write instances
- */
-
-/**
- * Get global Redis write instance
- *
- * @returns Redis write instance or undefined if not initialized
- *
- * @example
- * ```typescript
- * import { getRedis } from '@spfn/core/cache';
- *
- * const redis = getRedis();
- * if (redis) {
- *   await redis.set('key', 'value');
- * }
- * ```
- */
-declare function getRedis(): Redis | Cluster | undefined;
-/**
- * Get global Redis read instance (falls back to write if no replica)
- *
- * @returns Redis read instance or write instance as fallback
- *
- * @example
- * ```typescript
- * import { getRedisRead } from '@spfn/core/cache';
- *
- * const redis = getRedisRead();
- * if (redis) {
- *   const value = await redis.get('key');
- * }
- * ```
- */
-declare function getRedisRead(): Redis | Cluster | undefined;
-/**
- * Set global Redis instances (for testing or manual configuration)
- *
- * @param write - Redis write instance
- * @param read - Redis read instance (optional, defaults to write)
- *
- * @example
- * ```typescript
- * import { setRedis } from '@spfn/core/cache';
- * import Redis from 'ioredis';
- *
- * const write = new Redis('redis://master:6379');
- * const read = new Redis('redis://replica:6379');
- * setRedis(write, read);
- * ```
- */
-declare function setRedis(write: Redis | Cluster | undefined, read?: Redis | Cluster | undefined): void;
-/**
- * Initialize Redis from environment variables
- * Automatically called by startServer()
- *
- * Supported environment variables:
- * - REDIS_URL (single instance)
- * - REDIS_WRITE_URL + REDIS_READ_URL (master-replica)
- * - REDIS_SENTINEL_HOSTS + REDIS_MASTER_NAME (sentinel)
- * - REDIS_CLUSTER_NODES (cluster)
- * - REDIS_TLS_REJECT_UNAUTHORIZED (TLS config)
- *
- * @returns Object with write and read instances
- *
- * @example
- * ```typescript
- * import { initRedis } from '@spfn/core/cache';
- *
- * // Manual initialization (not needed if using startServer)
- * const { write, read } = await initRedis();
- * ```
- */
-declare function initRedis(): Promise<{
-    write?: Redis | Cluster;
-    read?: Redis | Cluster;
-}>;
-/**
- * Close all Redis connections and cleanup
- *
- * @example
- * ```typescript
- * import { closeRedis } from '@spfn/core/cache';
- *
- * // During graceful shutdown
- * await closeRedis();
- * ```
- */
-declare function closeRedis(): Promise<void>;
-/**
- * Get Redis connection info (for debugging)
- */
-declare function getRedisInfo(): {
-    hasWrite: boolean;
-    hasRead: boolean;
-    isReplica: boolean;
-};
-
-/**
- * Request Logger Middleware
- *
- * Automatic API request/response logging with performance monitoring
- */
-
-interface RequestLoggerConfig {
-    /**
-     * Paths to exclude from logging (health checks, etc.)
-     */
-    excludePaths?: string[];
-    /**
-     * Field names to mask for sensitive data
-     */
-    sensitiveFields?: string[];
-    /**
-     * Slow request threshold (ms)
-     */
-    slowRequestThreshold?: number;
-}
-/**
- * Mask sensitive data with circular reference handling
- */
-declare function maskSensitiveData(obj: any, sensitiveFields: string[], seen?: WeakSet<object>): any;
-/**
- * Request Logger middleware
- */
-declare function RequestLogger(config?: RequestLoggerConfig): (c: Context, next: Next) => Promise<void>;
-
-/**
- * Error Handler Middleware
- *
- * Generic middleware that converts errors with statusCode to HTTP responses
- */
-
-interface ErrorHandlerOptions {
-    /**
-     * Include stack trace in response
-     * @default process.env.NODE_ENV !== 'production'
-     */
-    includeStack?: boolean;
-    /**
-     * Enable error logging
-     * @default true
-     */
-    enableLogging?: boolean;
-}
-/**
- * Error handler middleware
- *
- * Used in Hono's onError hook
- */
-declare function ErrorHandler(options?: ErrorHandlerOptions): (err: Error, c: Context) => Response | Promise<Response>;
-
-export { DatabaseError, ErrorHandler, type ErrorHandlerOptions, type RedisClients, RequestLogger, type RequestLoggerConfig, closeRedis, createRedisFromEnv, createSingleRedisFromEnv, getRedis, getRedisInfo, getRedisRead, initRedis, isDatabaseError, maskSensitiveData, setRedis };