@spfn/core 0.2.0-beta.49 → 0.2.0-beta.50

package/docs/event.md

@@ -1,443 +0,0 @@
-# Event
-
-Decoupled pub/sub event system with SSE support for real-time frontend updates.
-
-## Define Events
-
-```typescript
-// src/server/events/index.ts
-import { defineEvent } from '@spfn/core/event';
-import { Type } from '@sinclair/typebox';
-
-// Event with typed payload
-export const userCreated = defineEvent('user.created', Type.Object({
-    userId: Type.String(),
-    email: Type.String(),
-}));
-
-export const orderPlaced = defineEvent('order.placed', Type.Object({
-    orderId: Type.String(),
-    amount: Type.Number(),
-}));
-
-// Event without payload
-export const serverStarted = defineEvent('server.started');
-```
-
-## Subscribe & Emit
-
-```typescript
-import { userCreated, serverStarted } from './events';
-
-// Subscribe to event
-const unsubscribe = userCreated.subscribe((payload) => {
-    console.log('User created:', payload.userId);
-});
-
-// Emit event
-await userCreated.emit({ userId: '123', email: 'user@example.com' });
-
-// Emit event without payload
-await serverStarted.emit();
-
-// Unsubscribe when done
-unsubscribe();
-```
-
-## Multiple Subscribers
-
-```typescript
-// Multiple independent handlers
-userCreated.subscribe(async (payload) => {
-    await sendWelcomeEmail(payload.email);
-});
-
-userCreated.subscribe(async (payload) => {
-    await createDefaultSettings(payload.userId);
-});
-
-userCreated.subscribe(async (payload) => {
-    await notifyAdmins(payload.userId);
-});
-
-// All handlers execute when event is emitted
-await userCreated.emit({ userId: '123', email: 'user@example.com' });
-```
-
-## Event Router for SSE
-
-```typescript
-// src/server/events/router.ts
-import { defineEventRouter } from '@spfn/core/event';
-import { userCreated, orderPlaced } from './index';
-
-export const eventRouter = defineEventRouter({
-    userCreated,
-    orderPlaced,
-});
-
-export type EventRouter = typeof eventRouter;
-```
-
-## Server Setup
-
-```typescript
-// server.config.ts
-import { defineServerConfig } from '@spfn/core/server';
-import { eventRouter } from './events/router';
-
-export default defineServerConfig()
-    .routes(appRouter)
-    .jobs(jobRouter)
-    .events(eventRouter)  // → GET /events/stream
-    .build();
-
-// Custom path and options
-.events(eventRouter, {
-    path: '/sse',           // Custom endpoint path
-    pingInterval: 30000,    // Keep-alive interval (default: 30s)
-})
-```
-
-## SSE Authentication
-
-Browser `EventSource` API does not support custom headers. SPFN uses a **Token Exchange** pattern:
-
-1. Client sends `POST /events/token` with Bearer JWT
-2. Server returns a one-time token (30s TTL)
-3. Client connects to `GET /events/stream?token=...&events=...`
-
-```typescript
-// server.config.ts
-import { defineServerConfig } from '@spfn/core/server';
-import { authenticate } from '@spfn/auth/server';
-
-export default defineServerConfig()
-    .middlewares([authenticate])
-    .routes(appRouter)
-    .events(eventRouter, {
-        auth: { enabled: true },  // This is all you need
-    })
-    .build();
-// → POST /events/token (protected by authenticate middleware)
-// → GET /events/stream?token=...&events=... (token verified)
-```
-
-### Authorization Hooks
-
-#### `authorize` — Subscription Authorization (once on connect)
-
-```typescript
-.events(eventRouter, {
-    auth: {
-        enabled: true,
-        authorize: async (subject, events) =>
-        {
-            // events: ('userCreated' | 'orderPlaced')[] — type inferred
-            const user = await usersRepository.findById(subject);
-            if (user.role === 'admin') return events;
-            return events.filter(e => !e.startsWith('admin.'));
-        },
-    },
-})
-```
-
-#### `filter` — Payload Filtering (on every event emission)
-
-```typescript
-.events(eventRouter, {
-    auth: {
-        enabled: true,
-        filter: {
-            // payload type inferred per-event — no casting needed
-            orderPlaced: (subject, payload) => payload.userId === subject,
-            // userCreated: no filter → sent to all authenticated users
-        },
-    },
-})
-```
-
-## Browser Client
-
-```typescript
-import { createSSEClient } from '@spfn/core/event/sse/client';
-import type { EventRouter } from '@/server/events/router';
-
-// Create client (uses defaults: NEXT_PUBLIC_SPFN_API_URL + /events/stream)
-const client = createSSEClient<EventRouter>();
-
-// Or with custom configuration
-const client = createSSEClient<EventRouter>({
-    host: 'https://api.example.com',
-    pathname: '/sse',
-    reconnect: true,
-    reconnectDelay: 3000,
-});
-
-// Subscribe to events
-const unsubscribe = client.subscribe({
-    events: ['userCreated', 'orderPlaced'],
-    handlers: {
-        userCreated: (payload) => {
-            console.log('New user:', payload.userId);
-        },
-        orderPlaced: (payload) => {
-            console.log('New order:', payload.orderId);
-        },
-    },
-    onOpen: () => console.log('SSE connected'),
-    onError: (err) => console.error('SSE error:', err),
-});
-
-// Cleanup
-unsubscribe();
-```
-
-### With Authentication
-
-Use `createAuthSSEClient` which handles token acquisition automatically via the RPC proxy:
-
-```typescript
-import { createAuthSSEClient } from '@spfn/core/event/sse/client';
-import type { EventRouter } from '@/server/events/router';
-
-const client = createAuthSSEClient<EventRouter>();
-```
-
-This requires `eventRouteMap` to be merged into your RPC proxy (one-time setup):
-
-```typescript
-// app/api/rpc/[routeName]/route.ts
-import '@spfn/auth/nextjs/api';
-import { createRpcProxy } from '@spfn/core/nextjs/server';
-import { eventRouteMap } from '@spfn/core/event';
-import { routeMap } from '@/generated/route-map';
-
-export const { GET, POST } = createRpcProxy({
-    routeMap: { ...routeMap, ...eventRouteMap },
-});
-```
-
-Tokens are acquired on every (re)connect — one-time tokens are handled automatically.
-
-## Simple Subscribe Helper
-
-```typescript
-import { subscribeToEvents } from '@spfn/core/event/sse/client';
-import type { EventRouter } from '@/server/events/router';
-
-// One-liner subscription
-const unsubscribe = subscribeToEvents<EventRouter>(
-    ['userCreated'],
-    {
-        userCreated: (payload) => console.log('User:', payload),
-    }
-);
-```
-
-## Job Integration
-
-```typescript
-import { defineEvent } from '@spfn/core/event';
-import { job, defineJobRouter } from '@spfn/core/job';
-
-// Define event
-export const orderPlaced = defineEvent('order.placed', Type.Object({
-    orderId: Type.String(),
-    userId: Type.String(),
-}));
-
-// Jobs subscribe to event
-export const sendOrderConfirmation = job('send-order-confirmation')
-    .on(orderPlaced)
-    .handler(async (payload) => {
-        await emailService.sendOrderConfirmation(payload.orderId);
-    });
-
-export const updateInventory = job('update-inventory')
-    .on(orderPlaced)
-    .handler(async (payload) => {
-        await inventoryService.reserve(payload.orderId);
-    });
-
-// Register jobs
-export const jobRouter = defineJobRouter({
-    sendOrderConfirmation,
-    updateInventory,
-});
-
-// Emit event - all subscribed jobs execute
-await orderPlaced.emit({ orderId: 'ord-123', userId: 'user-456' });
-```
-
-## Multi-Instance Support
-
-For applications running multiple instances, use cache-based pub/sub.
-
-```typescript
-import { defineEvent } from '@spfn/core/event';
-import { getCache } from '@spfn/core/cache';
-
-const userCreated = defineEvent('user.created', Type.Object({
-    userId: Type.String(),
-}));
-
-// Enable cache-based pub/sub
-const cache = getCache();
-if (cache)
-{
-    await userCreated.useCache({
-        publish: async (channel, message) => {
-            await cache.publish(channel, JSON.stringify(message));
-        },
-        subscribe: async (channel, handler) => {
-            const subscriber = cache.duplicate();
-            await subscriber.subscribe(channel);
-            subscriber.on('message', (ch, msg) => {
-                if (ch === channel)
-                {
-                    handler(JSON.parse(msg));
-                }
-            });
-        },
-    });
-}
-
-// Events now broadcast to all instances
-await userCreated.emit({ userId: '123' });
-```
-
-### SSE Token Store
-
-SSE 토큰 저장소도 멀티 인스턴스에서 공유되어야 합니다.
-캐시가 연결되면 `CacheTokenStore`가 **자동 사용**됩니다.
-
-| 환경 | 토큰 저장소 | 설정 |
-|------|------------|------|
-| `CACHE_URL` 없음 | `InMemoryTokenStore` | 자동 |
-| `CACHE_URL` 설정됨 | `CacheTokenStore` | 자동 감지 |
-| 커스텀 | `SSETokenStore` 구현 | `auth.store` 옵션 |
-
-## API Reference
-
-### defineEvent(name)
-
-Define an event without payload.
-
-```typescript
-export const serverStarted = defineEvent('server.started');
-
-serverStarted.subscribe(() => { ... });
-await serverStarted.emit();
-```
-
-### defineEvent(name, schema)
-
-Define an event with typed payload.
-
-```typescript
-export const userCreated = defineEvent('user.created', Type.Object({
-    userId: Type.String(),
-}));
-
-userCreated.subscribe((payload) => { ... });
-await userCreated.emit({ userId: '123' });
-```
-
-### EventDef Methods
-
-| Method | Description |
-|--------|-------------|
-| `subscribe(handler)` | Subscribe to event. Returns unsubscribe function |
-| `unsubscribeAll()` | Remove all subscribers |
-| `emit(payload?)` | Emit event to all subscribers |
-| `useCache(cache)` | Enable cache-based pub/sub for multi-instance |
-
-### SSE Client Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `host` | string | `NEXT_PUBLIC_SPFN_API_URL` | Backend API host URL |
-| `pathname` | string | `/events/stream` | SSE endpoint pathname |
-| `reconnect` | boolean | `true` | Auto reconnect on disconnect |
-| `reconnectDelay` | number | `3000` | Reconnect delay (ms) |
-| `maxReconnectAttempts` | number | `0` | Max attempts (0 = infinite) |
-| `withCredentials` | boolean | `false` | Include cookies |
-| `acquireToken` | () => Promise\<string\> | - | Acquire one-time SSE token before connecting |
-
-### SSE Auth Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | boolean | `false` | Enable token authentication |
-| `tokenTtl` | number | `30000` | Token TTL in milliseconds |
-| `store` | SSETokenStore | InMemory | Custom token store (e.g., Redis) |
-| `getSubject` | (c) => string \| null | `c.get('auth')?.userId` | Extract subject from context |
-| `authorize` | (subject, events) => events[] | - | Subscription authorization hook |
-| `filter` | { [event]: (subject, payload) => boolean } | - | Per-event payload filter |
-
-## Event Flow Architecture
-
-```
-                    userCreated.emit({ ... })
-                              │
-          ┌───────────────────┼───────────────────┐
-          ▼                   ▼                   ▼
-    ┌──────────┐       ┌──────────┐       ┌──────────┐
-    │ Backend  │       │   Job    │       │   SSE    │
-    │ Handler  │       │  Queue   │       │  Stream  │
-    └──────────┘       └──────────┘       └──────────┘
-    .subscribe()       .on(event)              ↓
-          │                 │           ┌──────────┐
-          ▼                 ▼           │ Browser  │
-    [Logging,         [Background       │  Client  │
-     Analytics]        Processing]      └──────────┘
-```
-
-## Best Practices
-
-```typescript
-// 1. Use descriptive event names
-defineEvent('user.created')
-defineEvent('order.completed')
-defineEvent('payment.failed')
-
-// 2. Keep payloads minimal - just IDs, not full objects
-defineEvent('user.deleted', Type.Object({
-    userId: Type.String(),
-}));
-
-// 3. Handler errors are isolated - one failing handler doesn't affect others
-userCreated.subscribe(async (payload) => {
-    throw new Error('This fails');
-});
-
-userCreated.subscribe(async (payload) => {
-    // This still executes
-    console.log('Handler 2 runs');
-});
-
-// 4. Use events for side effects, not core logic
-// Core: await userRepo.create(data);
-// Side effect: await userCreated.emit({ ... });
-
-// 5. Await useCache() before emitting for multi-instance
-await userCreated.useCache(cache);
-await userCreated.emit({ userId: '123' });
-```
-
-## Event vs Direct Job
-
-| Aspect | Event + Job | Direct Job |
-|--------|-------------|------------|
-| Coupling | Loose (producer doesn't know consumers) | Tight (producer calls specific job) |
-| Multiple consumers | Easy (multiple jobs subscribe) | Manual (call each job) |
-| Extensibility | Add consumers without modifying producer | Modify producer for each consumer |
-
-**Use Event when:**
-- Multiple systems need to react to the same occurrence
-- You want to decouple producers from consumers
-
-**Use Direct Job when:**
-- Single, known consumer
-- Simpler mental model preferred

package/docs/job.md

@@ -1,131 +0,0 @@
-# Job
-
-Background job processing.
-
-## Define Jobs
-
-```typescript
-// src/server/jobs/send-email.job.ts
-import { defineJob } from '@spfn/core/job';
-
-export const sendEmailJob = defineJob<{
-    to: string;
-    subject: string;
-    body: string;
-}>({
-    name: 'send-email',
-    handler: async (payload) => {
-        await emailService.send({
-            to: payload.to,
-            subject: payload.subject,
-            body: payload.body
-        });
-    }
-});
-```
-
-## Enqueue Jobs
-
-```typescript
-import { enqueue } from '@spfn/core/job';
-import { sendEmailJob } from './jobs/send-email.job';
-
-// Enqueue for immediate processing
-await enqueue(sendEmailJob, {
-    to: 'user@example.com',
-    subject: 'Welcome',
-    body: 'Welcome to our app!'
-});
-
-// Enqueue with delay
-await enqueue(sendEmailJob, payload, {
-    delay: 60000  // 1 minute
-});
-
-// Enqueue with options
-await enqueue(sendEmailJob, payload, {
-    priority: 'high',
-    attempts: 3,
-    backoff: 'exponential'
-});
-```
-
-## Job Options
-
-```typescript
-defineJob({
-    name: 'process-image',
-    concurrency: 5,           // Max concurrent jobs
-    attempts: 3,              // Retry attempts
-    backoff: 'exponential',   // Backoff strategy
-    timeout: 30000,           // Job timeout (ms)
-    handler: async (payload) => {
-        // ...
-    }
-});
-```
-
-## Scheduled Jobs
-
-```typescript
-import { schedule } from '@spfn/core/job';
-
-// Run every hour
-schedule('cleanup', '0 * * * *', async () => {
-    await cleanupExpiredSessions();
-});
-
-// Run daily at midnight
-schedule('daily-report', '0 0 * * *', async () => {
-    await generateDailyReport();
-});
-
-// Run every 5 minutes
-schedule('health-check', '*/5 * * * *', async () => {
-    await checkExternalServices();
-});
-```
-
-## Job Registration
-
-```typescript
-// src/server/jobs/index.ts
-import { registerJobs } from '@spfn/core/job';
-import { sendEmailJob } from './send-email.job';
-import { processImageJob } from './process-image.job';
-
-export function initializeJobs()
-{
-    registerJobs([
-        sendEmailJob,
-        processImageJob
-    ]);
-}
-```
-
-## Best Practices
-
-```typescript
-// 1. Keep jobs idempotent
-handler: async (payload) => {
-    // Check if already processed
-    const existing = await db.findProcessed(payload.id);
-    if (existing) return;
-
-    await processItem(payload);
-}
-
-// 2. Use appropriate timeout
-timeout: 30000  // Don't set too high
-
-// 3. Handle failures gracefully
-attempts: 3,
-backoff: 'exponential'
-
-// 4. Log job progress
-handler: async (payload) => {
-    logger.info('Processing job', { jobId: payload.id });
-    // ...
-    logger.info('Job completed', { jobId: payload.id });
-}
-```

package/docs/logger.md

@@ -1,108 +0,0 @@
-# Logger
-
-Structured logging with context support.
-
-## Basic Usage
-
-```typescript
-import { logger } from '@spfn/core/logger';
-
-logger.info('User created', { userId: '123' });
-logger.warn('Rate limit approaching', { remaining: 10 });
-logger.error('Failed to process', { error: err.message });
-logger.debug('Processing request', { path: '/api/users' });
-```
-
-## Log Levels
-
-| Level | Usage |
-|-------|-------|
-| `debug` | Development debugging |
-| `info` | General information |
-| `warn` | Warning conditions |
-| `error` | Error conditions |
-
-## Structured Logging
-
-```typescript
-// Good - structured data
-logger.info('User login', {
-    userId: user.id,
-    email: user.email,
-    ip: request.ip
-});
-
-// Bad - string concatenation
-logger.info(`User ${user.id} logged in from ${request.ip}`);
-```
-
-## Create Scoped Logger
-
-```typescript
-import { createLogger } from '@spfn/core/logger';
-
-const userLogger = createLogger('user-service');
-
-userLogger.info('Created user');
-// Output: [user-service] Created user
-
-const paymentLogger = createLogger('payment');
-paymentLogger.error('Payment failed', { orderId: '123' });
-// Output: [payment] Payment failed { orderId: '123' }
-```
-
-## Context Logging
-
-```typescript
-import { withLogContext } from '@spfn/core/logger';
-
-// Add context to all logs in scope
-await withLogContext({ requestId: '123', userId: 'abc' }, async () => {
-    logger.info('Processing request');
-    // Output includes: { requestId: '123', userId: 'abc' }
-
-    await doSomething();
-    logger.info('Request complete');
-    // Also includes context
-});
-```
-
-## Log Format
-
-Development (pretty):
-```
-2024-01-15 10:30:45 INFO  User created { userId: '123', email: 'user@example.com' }
-```
-
-Production (JSON):
-```json
-{"timestamp":"2024-01-15T10:30:45.123Z","level":"info","message":"User created","userId":"123","email":"user@example.com"}
-```
-
-## Best Practices
-
-```typescript
-// 1. Use structured data
-logger.info('Operation complete', { duration: 150, result: 'success' });
-
-// 2. Include error details
-logger.error('Request failed', {
-    error: err.message,
-    stack: err.stack,
-    path: req.path
-});
-
-// 3. Use appropriate levels
-logger.debug(...)  // Development only
-logger.info(...)   // Normal operations
-logger.warn(...)   // Potential issues
-logger.error(...)  // Errors requiring attention
-
-// 4. Create scoped loggers for modules
-const dbLogger = createLogger('database');
-const authLogger = createLogger('auth');
-
-// 5. Don't log sensitive data
-logger.info('User login', { userId: '123' });  // Good
-logger.info('User login', { password: '...' }); // Bad!
-```