@spfn/core 0.1.0-alpha.4 → 0.1.0-alpha.40

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 INFLIKE Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -485,6 +485,30 @@ Server configuration and lifecycle management.
 
 **[→ Read Server Documentation](./src/server/README.md)**
 
+### 📝 Logger
+High-performance logging with multiple transports, sensitive data masking, and automatic validation.
+
+**[→ Read Logger Documentation](./src/logger/README.md)**
+
+**Key Features:**
+- Adapter pattern (Pino for production, custom for full control)
+- Sensitive data masking (passwords, tokens, API keys)
+- File rotation (date and size-based) with automatic cleanup
+- Configuration validation with clear error messages
+- Multiple transports (Console, File, Slack, Email)
+
+### ⚙️ Code Generation
+Automatic code generation with pluggable generators and centralized file watching.
+
+**[→ Read Codegen Documentation](./src/codegen/README.md)**
+
+**Key Features:**
+- Orchestrator pattern for managing multiple generators
+- Built-in contract generator for type-safe API clients
+- Configuration-based setup (`.spfnrc.json` or `package.json`)
+- Watch mode integrated into `spfn dev`
+- Extensible with custom generators
+
 ## Module Exports
 
 ### Main Export
@@ -522,6 +546,11 @@ import {
 import { initRedis, getRedis, getRedisRead } from '@spfn/core';
 ```
 
+### Logger
+```typescript
+import { logger } from '@spfn/core';
+```
+
 ### Client (for frontend)
 ```typescript
 import { ContractClient, createClient } from '@spfn/core/client';
@@ -545,6 +574,17 @@ REDIS_READ_URL=redis://replica:6379
 PORT=8790
 HOST=localhost
 NODE_ENV=development
+
+# Server Timeouts (optional, in milliseconds)
+SERVER_TIMEOUT=120000              # Request timeout (default: 120000)
+SERVER_KEEPALIVE_TIMEOUT=65000     # Keep-alive timeout (default: 65000)
+SERVER_HEADERS_TIMEOUT=60000       # Headers timeout (default: 60000)
+SHUTDOWN_TIMEOUT=30000             # Graceful shutdown timeout (default: 30000)
+
+# Logger (optional)
+LOGGER_ADAPTER=pino               # pino | custom (default: pino)
+LOGGER_FILE_ENABLED=true          # Enable file logging (production only)
+LOG_DIR=/var/log/myapp           # Log directory (required when file logging enabled)
 ```
 
 ## Requirements
@@ -574,6 +614,8 @@ npm test -- --coverage      # With coverage
 - [Error Handling](./src/errors/README.md)
 - [Middleware](./src/middleware/README.md)
 - [Server Configuration](./src/server/README.md)
+- [Logger](./src/logger/README.md)
+- [Code Generation](./src/codegen/README.md)
 
 ### API Reference
 - See module-specific README files linked above

package/dist/auto-loader-JZT4AGYX.d.ts

@@ -0,0 +1,73 @@
+import { MiddlewareHandler, Hono } from 'hono';
+
+declare module 'hono' {
+    interface ContextVariableMap {
+        _skipMiddlewares?: string[];
+    }
+}
+/**
+ * AutoRouteLoader: Simplified File-based Routing System
+ *
+ * Features:
+ * - Auto-discovery: Scans routes directory and auto-registers
+ * - Dynamic routes: [id] → :id, [...slug] → *
+ * - Statistics: Route registration stats for dashboard
+ * - Grouping: Natural grouping by directory structure
+ */
+type RouteInfo = {
+    path: string;
+    file: string;
+    meta?: {
+        description?: string;
+        tags?: string[];
+        auth?: boolean;
+        [key: string]: unknown;
+    };
+    priority: number;
+};
+type RouteStats = {
+    total: number;
+    byPriority: {
+        static: number;
+        dynamic: number;
+        catchAll: number;
+    };
+    byTag: Record<string, number>;
+    routes: RouteInfo[];
+};
+declare class AutoRouteLoader {
+    private routesDir;
+    private routes;
+    private registeredRoutes;
+    private debug;
+    private readonly middlewares;
+    constructor(routesDir: string, debug?: boolean, middlewares?: Array<{
+        name: string;
+        handler: MiddlewareHandler;
+    }>);
+    load(app: Hono): Promise<RouteStats>;
+    getStats(): RouteStats;
+    private scanFiles;
+    private isValidRouteFile;
+    private loadRoute;
+    private validateModule;
+    private checkRouteConflict;
+    private registerContractBasedMiddlewares;
+    private registerFileBasedMiddlewares;
+    private categorizeAndLogError;
+    private fileToPath;
+    private calculatePriority;
+    private normalizePath;
+    private logRegistrationOrder;
+    private logStats;
+}
+declare function loadRoutes(app: Hono, options?: {
+    routesDir?: string;
+    debug?: boolean;
+    middlewares?: Array<{
+        name: string;
+        handler: MiddlewareHandler;
+    }>;
+}): Promise<RouteStats>;
+
+export { AutoRouteLoader as A, type RouteInfo as R, type RouteStats as a, loadRoutes as l };

package/dist/bind-zSx7Joxv.d.ts

@@ -0,0 +1,17 @@
+import { Context } from 'hono';
+import { R as RouteContract, c as RouteContext } from './types-C0u_SdUv.js';
+
+/**
+ * Contract-based Route Handler Wrapper
+ *
+ * Binds a contract to a route handler, providing automatic validation
+ * and type-safe context creation.
+ *
+ * Features:
+ * - Automatic params/query/body validation using TypeBox
+ * - Type-safe RouteContext with contract-based inference
+ * - Clean separation: bind() for validation, Hono for middleware
+ */
+declare function bind<TContract extends RouteContract>(contract: TContract, handler: (c: RouteContext<TContract>) => Response | Promise<Response>): (rawContext: Context) => Promise<Response>;
+
+export { bind as b };

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
-import '../auto-loader-C44TcLmM.js';
-import { R as RouteContract, I as InferContract } from '../types-SlzTr8ZO.js';
+import '../auto-loader-JZT4AGYX.js';
+import { R as RouteContract, I as InferContract } from '../types-C0u_SdUv.js';
 import 'hono';
 import 'hono/utils/http-status';
 import '@sinclair/typebox';
@@ -8,31 +8,12 @@ import '@sinclair/typebox';
  * Contract-Based API Client
  *
  * Type-safe HTTP client that works with RouteContract for full end-to-end type safety
- *
- * @example
- * ```ts
- * import { createClient } from '@spfn/core/client';
- * import { getUserContract } from './contracts';
- *
- * const client = createClient({ baseUrl: 'http://localhost:4000' });
- * const user = await client.call(getUserContract, { params: { id: '123' } });
- * // ✅ user is fully typed based on contract.response
- * ```
  */
 
-/**
- * Request interceptor function
- *
- * Allows modifying request before it's sent
- */
 type RequestInterceptor = (url: string, init: RequestInit) => Promise<RequestInit> | RequestInit;
-/**
- * Client configuration
- */
 interface ClientConfig {
     /**
      * API base URL (e.g., http://localhost:4000)
-     * Can be overridden per request
      */
     baseUrl?: string;
     /**
@@ -44,33 +25,15 @@ interface ClientConfig {
      */
     timeout?: number;
     /**
-     * Custom fetch implementation (for testing or custom behavior)
+     * Custom fetch implementation
      */
     fetch?: typeof fetch;
 }
-/**
- * Request options for API calls
- */
 interface CallOptions<TContract extends RouteContract> {
-    /**
-     * Path parameters (for dynamic routes like /users/:id)
-     */
     params?: InferContract<TContract>['params'];
-    /**
-     * Query parameters (for URL query strings)
-     */
     query?: InferContract<TContract>['query'];
-    /**
-     * Request body (for POST, PUT, PATCH)
-     */
     body?: InferContract<TContract>['body'];
-    /**
-     * Additional headers for this specific request
-     */
     headers?: Record<string, string>;
-    /**
-     * Override base URL for this request
-     */
     baseUrl?: string;
 }
 /**
@@ -80,7 +43,8 @@ declare class ApiClientError extends Error {
     readonly status: number;
     readonly url: string;
     readonly response?: unknown | undefined;
-    constructor(message: string, status: number, url: string, response?: unknown | undefined);
+    readonly errorType?: "timeout" | "network" | "http" | undefined;
+    constructor(message: string, status: number, url: string, response?: unknown | undefined, errorType?: "timeout" | "network" | "http" | undefined);
 }
 /**
  * Contract-based API Client
@@ -91,83 +55,115 @@ declare class ContractClient {
     constructor(config?: ClientConfig);
     /**
      * Add request interceptor
-     *
-     * Interceptors are executed in the order they are added
-     *
-     * @example
-     * ```ts
-     * client.use(async (url, init) => {
-     *   // Add auth header
-     *   return {
-     *     ...init,
-     *     headers: {
-     *       ...init.headers,
-     *       Authorization: `Bearer ${token}`
-     *     }
-     *   };
-     * });
-     * ```
      */
     use(interceptor: RequestInterceptor): void;
     /**
      * Make a type-safe API call using a contract
-     *
-     * @example
-     * ```ts
-     * const getUserContract = {
-     *   params: Type.Object({ id: Type.String() }),
-     *   response: Type.Object({ id: Type.Number(), name: Type.String() })
-     * } as const satisfies RouteContract;
-     *
-     * const user = await client.call('/users/:id', getUserContract, {
-     *   params: { id: '123' }
-     * });
-     * // ✅ user.name is typed as string
-     * ```
      */
-    call<TContract extends RouteContract>(path: string, contract: TContract, options?: CallOptions<TContract>): Promise<InferContract<TContract>['response']>;
+    call<TContract extends RouteContract>(contract: TContract, options?: CallOptions<TContract>): Promise<InferContract<TContract>['response']>;
     /**
      * Create a new client with merged configuration
-     *
-     * Useful for creating clients with specific auth tokens or custom headers
-     *
-     * @example
-     * ```ts
-     * const authClient = client.withConfig({
-     *   headers: { Authorization: `Bearer ${token}` }
-     * });
-     * ```
      */
     withConfig(config: Partial<ClientConfig>): ContractClient;
+    private static buildUrl;
+    private static buildQuery;
+    private static getHttpMethod;
+    private static isFormData;
 }
 /**
  * Create a new contract-based API client
+ */
+declare function createClient(config?: ClientConfig): ContractClient;
+/**
+ * Configure the global client instance
+ *
+ * Call this in your app initialization to set default configuration
+ * for all auto-generated API calls.
  *
  * @example
  * ```ts
- * const client = createClient({
- *   baseUrl: 'http://localhost:4000',
- *   headers: { 'X-Custom': 'header' }
+ * // In app initialization (layout.tsx, _app.tsx, etc)
+ * import { configureClient } from '@spfn/core/client';
+ *
+ * configureClient({
+ *   baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:4000',
+ *   timeout: 60000,
+ *   headers: {
+ *     'X-App-Version': '1.0.0'
+ *   }
  * });
  *
- * const user = await client.call('/users/:id', getUserContract, {
- *   params: { id: '123' }
+ * // Add interceptors
+ * import { client } from '@spfn/core/client';
+ * client.use(async (url, init) => {
+ *   // Add auth header
+ *   return {
+ *     ...init,
+ *     headers: {
+ *       ...init.headers,
+ *       Authorization: `Bearer ${getToken()}`
+ *     }
+ *   };
  * });
  * ```
  */
-declare function createClient(config?: ClientConfig): ContractClient;
+declare function configureClient(config: ClientConfig): void;
+/**
+ * Global client singleton with Proxy
+ *
+ * This client can be configured using configureClient() before use.
+ * Used by auto-generated API client code.
+ */
+declare const client: ContractClient;
 /**
- * Default client instance
+ * Type guard for timeout errors
  *
  * @example
  * ```ts
- * import { client } from '@spfn/core/client';
+ * try {
+ *   await api.users.getById({ params: { id: '123' } });
+ * } catch (error) {
+ *   if (isTimeoutError(error)) {
+ *     console.error('Request timed out, retrying...');
+ *     // Implement retry logic
+ *   }
+ * }
+ * ```
+ */
+declare function isTimeoutError(error: unknown): error is ApiClientError;
+/**
+ * Type guard for network errors
  *
- * const user = await client.call('/users/:id', getUserContract, {
- *   params: { id: '123' }
- * });
+ * @example
+ * ```ts
+ * try {
+ *   await api.users.list();
+ * } catch (error) {
+ *   if (isNetworkError(error)) {
+ *     showOfflineMessage();
+ *   }
+ * }
  * ```
  */
-declare const client: ContractClient;
+declare function isNetworkError(error: unknown): error is ApiClientError;
+/**
+ * Type guard for HTTP errors (4xx, 5xx)
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.users.create({ body: userData });
+ * } catch (error) {
+ *   if (isHttpError(error)) {
+ *     if (error.status === 401) {
+ *       redirectToLogin();
+ *     } else if (error.status === 404) {
+ *       showNotFoundMessage();
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function isHttpError(error: unknown): error is ApiClientError;
 
-export { ApiClientError, type CallOptions, type ClientConfig, ContractClient, type RequestInterceptor, client, createClient };
+export { ApiClientError, type CallOptions, type ClientConfig, ContractClient, type RequestInterceptor, client, configureClient, createClient, isHttpError, isNetworkError, isTimeoutError };

package/dist/client/index.js

@@ -1,43 +1,14 @@
 // src/client/contract-client.ts
 var ApiClientError = class extends Error {
-  constructor(message, status, url, response) {
+  constructor(message, status, url, response, errorType) {
     super(message);
     this.status = status;
     this.url = url;
     this.response = response;
+    this.errorType = errorType;
     this.name = "ApiClientError";
   }
 };
-function buildUrl(path, params) {
-  if (!params) return path;
-  let url = path;
-  for (const [key, value] of Object.entries(params)) {
-    url = url.replace(`:${key}`, String(value));
-  }
-  return url;
-}
-function buildQuery(query) {
-  if (!query || Object.keys(query).length === 0) return "";
-  const params = new URLSearchParams();
-  for (const [key, value] of Object.entries(query)) {
-    if (Array.isArray(value)) {
-      value.forEach((v) => params.append(key, String(v)));
-    } else if (value !== void 0 && value !== null) {
-      params.append(key, String(value));
-    }
-  }
-  const queryString = params.toString();
-  return queryString ? `?${queryString}` : "";
-}
-function getHttpMethod(contract, options) {
-  if ("method" in contract && typeof contract.method === "string") {
-    return contract.method.toUpperCase();
-  }
-  if (options?.body !== void 0) {
-    return "POST";
-  }
-  return "GET";
-}
 var ContractClient = class _ContractClient {
   config;
   interceptors = [];
@@ -46,58 +17,35 @@ var ContractClient = class _ContractClient {
       baseUrl: config.baseUrl || process.env.NEXT_PUBLIC_API_URL || "http://localhost:4000",
       headers: config.headers || {},
       timeout: config.timeout || 3e4,
-      fetch: config.fetch || globalThis.fetch
+      fetch: config.fetch || globalThis.fetch.bind(globalThis)
     };
   }
   /**
    * Add request interceptor
-   *
-   * Interceptors are executed in the order they are added
-   *
-   * @example
-   * ```ts
-   * client.use(async (url, init) => {
-   *   // Add auth header
-   *   return {
-   *     ...init,
-   *     headers: {
-   *       ...init.headers,
-   *       Authorization: `Bearer ${token}`
-   *     }
-   *   };
-   * });
-   * ```
    */
   use(interceptor) {
     this.interceptors.push(interceptor);
   }
   /**
    * Make a type-safe API call using a contract
-   *
-   * @example
-   * ```ts
-   * const getUserContract = {
-   *   params: Type.Object({ id: Type.String() }),
-   *   response: Type.Object({ id: Type.Number(), name: Type.String() })
-   * } as const satisfies RouteContract;
-   *
-   * const user = await client.call('/users/:id', getUserContract, {
-   *   params: { id: '123' }
-   * });
-   * // ✅ user.name is typed as string
-   * ```
    */
-  async call(path, contract, options) {
+  async call(contract, options) {
     const baseUrl = options?.baseUrl || this.config.baseUrl;
-    const urlPath = buildUrl(path, options?.params);
-    const queryString = buildQuery(options?.query);
+    const urlPath = _ContractClient.buildUrl(
+      contract.path,
+      options?.params
+    );
+    const queryString = _ContractClient.buildQuery(
+      options?.query
+    );
     const url = `${baseUrl}${urlPath}${queryString}`;
-    const method = getHttpMethod(contract, options);
+    const method = _ContractClient.getHttpMethod(contract, options);
     const headers = {
       ...this.config.headers,
       ...options?.headers
     };
-    if (options?.body !== void 0 && !headers["Content-Type"]) {
+    const isFormData = _ContractClient.isFormData(options?.body);
+    if (options?.body !== void 0 && !isFormData && !headers["Content-Type"]) {
       headers["Content-Type"] = "application/json";
     }
     let init = {
@@ -105,7 +53,7 @@ var ContractClient = class _ContractClient {
       headers
     };
     if (options?.body !== void 0) {
-      init.body = JSON.stringify(options.body);
+      init.body = isFormData ? options.body : JSON.stringify(options.body);
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
@@ -117,18 +65,20 @@ var ContractClient = class _ContractClient {
       clearTimeout(timeoutId);
       if (error instanceof Error && error.name === "AbortError") {
         throw new ApiClientError(
-          `${method} ${urlPath} timed out after ${this.config.timeout}ms`,
+          `Request timed out after ${this.config.timeout}ms`,
           0,
-          "Timeout",
-          url
+          url,
+          void 0,
+          "timeout"
         );
       }
       if (error instanceof Error) {
         throw new ApiClientError(
-          `${method} ${urlPath} network error: ${error.message}`,
+          `Network error: ${error.message}`,
           0,
-          "Network Error",
-          url
+          url,
+          void 0,
+          "network"
         );
       }
       throw error;
@@ -140,7 +90,8 @@ var ContractClient = class _ContractClient {
         `${method} ${urlPath} failed: ${response.status} ${response.statusText}`,
         response.status,
         url,
-        errorBody
+        errorBody,
+        "http"
       );
     }
     const data = await response.json();
@@ -148,15 +99,6 @@ var ContractClient = class _ContractClient {
   }
   /**
    * Create a new client with merged configuration
-   *
-   * Useful for creating clients with specific auth tokens or custom headers
-   *
-   * @example
-   * ```ts
-   * const authClient = client.withConfig({
-   *   headers: { Authorization: `Bearer ${token}` }
-   * });
-   * ```
    */
   withConfig(config) {
     return new _ContractClient({
@@ -166,12 +108,62 @@ var ContractClient = class _ContractClient {
       fetch: config.fetch || this.config.fetch
     });
   }
+  static buildUrl(path, params) {
+    if (!params) return path;
+    let url = path;
+    for (const [key, value] of Object.entries(params)) {
+      url = url.replace(`:${key}`, String(value));
+    }
+    return url;
+  }
+  static buildQuery(query) {
+    if (!query || Object.keys(query).length === 0) return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (Array.isArray(value)) {
+        value.forEach((v) => params.append(key, String(v)));
+      } else if (value !== void 0 && value !== null) {
+        params.append(key, String(value));
+      }
+    }
+    const queryString = params.toString();
+    return queryString ? `?${queryString}` : "";
+  }
+  static getHttpMethod(contract, options) {
+    if ("method" in contract && typeof contract.method === "string") {
+      return contract.method.toUpperCase();
+    }
+    if (options?.body !== void 0) {
+      return "POST";
+    }
+    return "GET";
+  }
+  static isFormData(body) {
+    return body instanceof FormData;
+  }
 };
 function createClient(config) {
   return new ContractClient(config);
 }
-var client = createClient();
+var _clientInstance = new ContractClient();
+function configureClient(config) {
+  _clientInstance = new ContractClient(config);
+}
+var client = new Proxy({}, {
+  get(_target, prop) {
+    return _clientInstance[prop];
+  }
+});
+function isTimeoutError(error) {
+  return error instanceof ApiClientError && error.errorType === "timeout";
+}
+function isNetworkError(error) {
+  return error instanceof ApiClientError && error.errorType === "network";
+}
+function isHttpError(error) {
+  return error instanceof ApiClientError && error.errorType === "http";
+}
 
-export { ApiClientError, ContractClient, client, createClient };
+export { ApiClientError, ContractClient, client, configureClient, createClient, isHttpError, isNetworkError, isTimeoutError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map