@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.10

package/dist/types-B-e_f2dQ.d.ts

@@ -0,0 +1,121 @@
+import { E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './router-Di7ENoah.js';
+
+/**
+ * SSE Types
+ *
+ * Type definitions for Server-Sent Events
+ */
+
+/**
+ * SSE message sent from server
+ */
+interface SSEMessage<TEvent extends string = string, TPayload = unknown> {
+    /** Event name */
+    event: TEvent;
+    /** Event payload */
+    data: TPayload;
+    /** Optional message ID for reconnection */
+    id?: string;
+}
+/**
+ * SSE Handler configuration
+ */
+interface SSEHandlerConfig {
+    /**
+     * Keep-alive ping interval in milliseconds
+     * @default 30000
+     */
+    pingInterval?: number;
+    /**
+     * Custom headers for SSE response
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * SSE Client configuration
+ */
+interface SSEClientConfig {
+    /**
+     * Backend API host URL
+     * @default NEXT_PUBLIC_SPFN_API_URL || 'http://localhost:8790'
+     * @example 'http://localhost:8790'
+     * @example 'https://api.example.com'
+     */
+    host?: string;
+    /**
+     * SSE endpoint pathname
+     * @default '/events/stream'
+     */
+    pathname?: string;
+    /**
+     * Full URL (overrides host + pathname)
+     * @deprecated Use host and pathname instead
+     * @example 'http://localhost:8790/events/stream'
+     */
+    url?: string;
+    /**
+     * Auto reconnect on disconnect
+     * @default true
+     */
+    reconnect?: boolean;
+    /**
+     * Reconnect delay in milliseconds
+     * @default 3000
+     */
+    reconnectDelay?: number;
+    /**
+     * Maximum reconnect attempts (0 = infinite)
+     * @default 0
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Include credentials (cookies) in request
+     * @default false
+     */
+    withCredentials?: boolean;
+}
+/**
+ * Event handler function
+ */
+type SSEEventHandler<TPayload> = (payload: TPayload) => void;
+/**
+ * Event handlers map for EventRouter
+ */
+type SSEEventHandlers<TRouter extends EventRouterDef<any>> = {
+    [K in InferEventNames<TRouter>]?: SSEEventHandler<InferEventPayload<TRouter, K>>;
+};
+/**
+ * Subscription options
+ */
+interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
+    /**
+     * Events to subscribe
+     */
+    events: InferEventNames<TRouter>[];
+    /**
+     * Event handlers
+     */
+    handlers: SSEEventHandlers<TRouter>;
+    /**
+     * Called when connection opens
+     */
+    onOpen?: () => void;
+    /**
+     * Called on connection error
+     */
+    onError?: (error: Event) => void;
+    /**
+     * Called when reconnecting
+     */
+    onReconnect?: (attempt: number) => void;
+}
+/**
+ * SSE connection state
+ */
+type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
+/**
+ * Unsubscribe function
+ */
+type SSEUnsubscribe = () => void;
+
+export type { SSEHandlerConfig as S, SSEMessage as a, SSEClientConfig as b, SSEEventHandler as c, SSEEventHandlers as d, SSESubscribeOptions as e, SSEConnectionState as f, SSEUnsubscribe as g };

package/dist/types-BGl4QL1w.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Logger Type Definitions
+ *
+ * 로깅 시스템 타입 정의
+ *
+ * ✅ 구현 완료:
+ * - LogLevel 타입 정의
+ * - LogMetadata 인터페이스
+ * - Transport 인터페이스
+ * - 환경별 설정 타입
+ *
+ * 🔗 관련 파일:
+ * - src/logger/logger.ts (Logger 클래스)
+ * - src/logger/transports/ (Transport 구현체)
+ * - src/logger/config.ts (설정)
+ */
+/**
+ * 로그 레벨
+ * debug < info < warn < error < fatal
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * 로그 메타데이터
+ */
+interface LogMetadata {
+    timestamp: Date;
+    level: LogLevel;
+    message: string;
+    module?: string;
+    error?: Error;
+    context?: Record<string, unknown>;
+}
+/**
+ * Transport 인터페이스
+ * 모든 Transport는 이 인터페이스를 구현해야 함
+ */
+interface Transport {
+    /**
+     * Transport 이름
+     */
+    name: string;
+    /**
+     * 최소 로그 레벨 (이 레벨 이상만 처리)
+     */
+    level: LogLevel;
+    /**
+     * 활성화 여부
+     */
+    enabled: boolean;
+    /**
+     * 로그 처리 함수
+     */
+    log(metadata: LogMetadata): Promise<void>;
+    /**
+     * Transport 종료 (리소스 정리)
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Logger 설정
+ */
+interface LoggerConfig {
+    /**
+     * 기본 로그 레벨
+     */
+    level: LogLevel;
+    /**
+     * 모듈명 (context)
+     */
+    module?: string;
+    /**
+     * Transport 리스트
+     */
+    transports: Transport[];
+}
+
+export type { LogLevel as L, Transport as T, LoggerConfig as a };

package/dist/types-BOPTApC2.d.ts

@@ -0,0 +1,245 @@
+import { TSchema, Static } from '@sinclair/typebox';
+import { ErrorRegistry, ErrorRegistryInput } from '@spfn/core/errors';
+import { RouteDef, RouteInput } from '@spfn/core/route';
+
+/**
+ * Convert File types in schema to actual File for client usage
+ *
+ * TypeBox File schemas become actual File objects on the client side.
+ */
+type ConvertFileTypes<T> = T extends File ? File : T extends File[] ? File[] : T;
+/**
+ * Extract form data input type with File support
+ *
+ * Maps schema types to runtime types, converting FileSchema to File.
+ */
+type FormDataInput<T> = {
+    [K in keyof T]: ConvertFileTypes<T[K]>;
+};
+/**
+ * Extract structured input from RouteInput
+ *
+ * Converts TypeBox schemas to their static types for each input field.
+ */
+type StructuredInput<TInput extends RouteInput> = {
+    params: TInput['params'] extends TSchema ? Static<TInput['params']> : {};
+    query: TInput['query'] extends TSchema ? Static<TInput['query']> : {};
+    body: TInput['body'] extends TSchema ? Static<TInput['body']> : {};
+    formData: TInput['formData'] extends TSchema ? FormDataInput<Static<TInput['formData']>> : {};
+    headers: TInput['headers'] extends TSchema ? Static<TInput['headers']> : {};
+    cookies: TInput['cookies'] extends TSchema ? Static<TInput['cookies']> : {};
+};
+/**
+ * Infer route input type from RouteDef
+ *
+ * @example
+ * ```typescript
+ * // Server route definition
+ * const getUser = route.get('/users/:id')
+ *   .input({ params: Type.Object({ id: Type.String() }) })
+ *   .handler(...);
+ *
+ * // Client: extract input type
+ * type Input = InferRouteInput<typeof getUser>;
+ * // { params: { id: string }, query: {}, body: {}, ... }
+ * ```
+ */
+type InferRouteInput<TRoute> = TRoute extends RouteDef<infer TInput, any, any> ? StructuredInput<TInput> : never;
+/**
+ * Infer route output type from RouteDef
+ *
+ * @example
+ * ```typescript
+ * // Server route definition
+ * const getUser = route.get('/users/:id')
+ *   .handler(async (c) => {
+ *     return { id: '1', name: 'John' };
+ *   });
+ *
+ * // Client: extract output type
+ * type Output = InferRouteOutput<typeof getUser>;
+ * // { id: string, name: string }
+ * ```
+ */
+type InferRouteOutput<TRoute> = TRoute extends RouteDef<any, any, infer TResponse> ? TResponse : never;
+/**
+ * Extract routes from Router type
+ * Router<TRoutes> has routes in `_routes` property
+ */
+type ExtractRoutes<TRouter> = TRouter extends {
+    _routes: infer TRoutes;
+} ? TRoutes : TRouter;
+/**
+ * Extract output type for a specific route from router
+ *
+ * @example
+ * ```typescript
+ * import type { RouterOutput } from '@spfn/core/nextjs';
+ * import type { AppRouter } from '@/server/router';
+ *
+ * // Get output type for a specific route
+ * type ListData = RouterOutput<AppRouter, 'listExamples'>;
+ *
+ * // Use in props
+ * interface Props {
+ *     data: RouterOutput<AppRouter, 'listExamples'>;
+ * }
+ *
+ * // Extract item type from paginated response
+ * type Example = RouterOutput<AppRouter, 'listExamples'>['items'][number];
+ * ```
+ */
+type RouterOutput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteOutput<ExtractRoutes<TRouter>[K]>;
+/**
+ * Extract input type for a specific route from router
+ *
+ * @example
+ * ```typescript
+ * import type { RouterInput } from '@spfn/core/nextjs';
+ * import type { AppRouter } from '@/server/router';
+ *
+ * // Get input type for a specific route
+ * type CreateInput = RouterInput<AppRouter, 'createExample'>;
+ *
+ * // Use in function parameter
+ * function submitForm(data: RouterInput<AppRouter, 'createExample'>['body']) {
+ *     // ...
+ * }
+ * ```
+ */
+type RouterInput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteInput<ExtractRoutes<TRouter>[K]>;
+/**
+ * Cookie options for setCookie
+ */
+interface CookieOptions {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+}
+/**
+ * Cookie to set in response
+ */
+interface SetCookie {
+    name: string;
+    value: string;
+    options?: CookieOptions;
+}
+/**
+ * Request interceptor - called before fetch
+ */
+type RequestInterceptor = (url: string, init: RequestInit) => Promise<RequestInit> | RequestInit;
+/**
+ * Response interceptor - called after fetch
+ */
+type ResponseInterceptor = (response: Response, body: any) => Promise<{
+    response: Response;
+    body: any;
+}> | {
+    response: Response;
+    body: any;
+};
+/**
+ * Client configuration
+ */
+interface ApiConfig {
+    /**
+     * Base URL for RPC endpoint
+     *
+     * @default '/api/rpc'
+     * @example '/api/rpc', 'http://localhost:3000/api/rpc'
+     */
+    baseUrl?: string;
+    /**
+     * Default headers for all requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds
+     *
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom fetch implementation
+     */
+    fetch?: typeof fetch;
+    /**
+     * Global request interceptor
+     */
+    onRequest?: RequestInterceptor;
+    /**
+     * Global response interceptor
+     */
+    onResponse?: ResponseInterceptor;
+    /**
+     * Custom error registry for deserialization
+     *
+     * Core HTTP errors are automatically registered. Use this to add your custom application errors.
+     *
+     * @example
+     * ```typescript
+     * import { errorRegistry } from '@spfn/core/errors';
+     * import { authErrorRegistry } from '@myapp/auth/errors';
+     * import { PaymentFailedError } from '@/server/errors';
+     *
+     * const api = createApi<AppRouter>({
+     *   errorRegistry: [errorRegistry, authErrorRegistry, PaymentFailedError]
+     * });
+     * ```
+     */
+    errorRegistry?: ErrorRegistry | ErrorRegistryInput[];
+    /**
+     * Enable debug logging
+     *
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Per-call options
+ */
+interface CallOptions {
+    /**
+     * Additional headers for this request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Override cookies for this request
+     *
+     * Note: Cookies are automatically forwarded by the proxy.
+     * Use this only when you need to override them.
+     */
+    cookies?: Record<string, string>;
+    /**
+     * Request-specific interceptor
+     */
+    onRequest?: RequestInterceptor;
+    /**
+     * Response-specific interceptor
+     */
+    onResponse?: ResponseInterceptor;
+    /**
+     * Next.js-specific fetch options
+     *
+     * @example
+     * // Time-based revalidation
+     * { next: { revalidate: 60 } }
+     *
+     * // Disable cache
+     * { cache: 'no-store' }
+     *
+     * // Tag-based revalidation
+     * { next: { tags: ['users'] } }
+     */
+    fetchOptions?: RequestInit & {
+        next?: {
+            revalidate?: number | false;
+            tags?: string[];
+        };
+    };
+}
+
+export type { ApiConfig as A, CallOptions as C, InferRouteInput as I, RequestInterceptor as R, StructuredInput as S, ResponseInterceptor as a, InferRouteOutput as b, RouterInput as c, RouterOutput as d, CookieOptions as e, SetCookie as f };

package/docs/cache.md

@@ -0,0 +1,133 @@
+# Cache
+
+Redis caching with type-safe operations.
+
+## Setup
+
+```bash
+REDIS_URL=redis://localhost:6379
+```
+
+## Basic Usage
+
+```typescript
+import { cache } from '@spfn/core/cache';
+
+// Set
+await cache.set('user:123', { id: '123', name: 'John' });
+await cache.set('session:abc', data, { ttl: 3600 });  // 1 hour
+
+// Get
+const user = await cache.get<User>('user:123');
+
+// Delete
+await cache.del('user:123');
+
+// Check existence
+const exists = await cache.exists('user:123');
+```
+
+## TTL Options
+
+```typescript
+// Set with TTL (seconds)
+await cache.set('key', value, { ttl: 60 });      // 1 minute
+await cache.set('key', value, { ttl: 3600 });    // 1 hour
+await cache.set('key', value, { ttl: 86400 });   // 1 day
+
+// No expiration
+await cache.set('key', value);  // Permanent until deleted
+```
+
+## Patterns
+
+### Cache-Aside
+
+```typescript
+async function getUser(id: string): Promise<User>
+{
+    const cached = await cache.get<User>(`user:${id}`);
+    if (cached)
+    {
+        return cached;
+    }
+
+    const user = await userRepo.findById(id);
+    if (user)
+    {
+        await cache.set(`user:${id}`, user, { ttl: 3600 });
+    }
+
+    return user;
+}
+```
+
+### Cache Invalidation
+
+```typescript
+async function updateUser(id: string, data: Partial<User>)
+{
+    const user = await userRepo.update(id, data);
+    await cache.del(`user:${id}`);  // Invalidate cache
+    return user;
+}
+```
+
+### Cache with Prefix
+
+```typescript
+const userCache = cache.prefix('user');
+
+await userCache.set('123', user);     // Key: user:123
+await userCache.get('123');
+await userCache.del('123');
+```
+
+## Hash Operations
+
+```typescript
+// Set hash field
+await cache.hset('user:123', 'name', 'John');
+
+// Get hash field
+const name = await cache.hget('user:123', 'name');
+
+// Get all hash fields
+const user = await cache.hgetall('user:123');
+
+// Delete hash field
+await cache.hdel('user:123', 'name');
+```
+
+## List Operations
+
+```typescript
+// Push to list
+await cache.lpush('queue', item);
+await cache.rpush('queue', item);
+
+// Pop from list
+const item = await cache.lpop('queue');
+const item = await cache.rpop('queue');
+
+// Get list range
+const items = await cache.lrange('queue', 0, -1);  // All items
+```
+
+## Best Practices
+
+```typescript
+// 1. Use consistent key naming
+`user:${id}`
+`session:${token}`
+`cache:posts:${page}`
+
+// 2. Set appropriate TTL
+{ ttl: 300 }    // 5 min for frequently changing data
+{ ttl: 3600 }   // 1 hour for stable data
+{ ttl: 86400 }  // 1 day for rarely changing data
+
+// 3. Invalidate on write
+await userRepo.update(id, data);
+await cache.del(`user:${id}`);
+```

package/docs/codegen.md

@@ -0,0 +1,74 @@
+# Codegen
+
+Automatic API client generation from route definitions.
+
+## Setup
+
+### Configure Generator
+
+```typescript
+// codegen.config.ts
+import { defineCodegenConfig } from '@spfn/core/codegen';
+
+export default defineCodegenConfig({
+    generators: [
+        {
+            name: 'api-client',
+            output: './src/client/api.ts',
+            router: './src/server/server.config.ts'
+        }
+    ]
+});
+```
+
+## Generate Client
+
+```bash
+# Generate once
+pnpm spfn codegen run
+
+# Watch mode (dev server includes this)
+pnpm spfn:dev
+```
+
+## Generated Client
+
+```typescript
+// src/client/api.ts (generated)
+import { createApi } from '@spfn/core/nextjs';
+import type { AppRouter } from '@/server/server.config';
+
+export const api = createApi<AppRouter>();
+```
+
+## Usage
+
+```typescript
+import { api } from '@/client/api';
+
+// Type-safe API calls
+const user = await api.getUser.call({
+    params: { id: '123' }
+});
+
+const users = await api.getUsers.call({
+    query: { page: 1, limit: 20 }
+});
+
+const created = await api.createUser.call({
+    body: { email: 'user@example.com', name: 'User' }
+});
+```
+
+## CLI Commands
+
+```bash
+# Generate API client
+pnpm spfn codegen run
+
+# List registered generators
+pnpm spfn codegen list
+
+# Run specific generator
+pnpm spfn codegen run --name api-client
+```