@spfn/core 0.2.0-beta.10 → 0.2.0-beta.12

package/dist/{types-BOPTApC2.d.ts → types-DP8nzQcY.d.ts}

@@ -202,6 +202,11 @@ interface ApiConfig {
  * Per-call options
  */
 interface CallOptions {
+    /**
+     * Request timeout in milliseconds
+     * Overrides the global timeout set in ApiConfig
+     */
+    timeout?: number;
     /**
      * Additional headers for this request
      */

package/docs/event.md

@@ -1,116 +1,335 @@
 # Event
 
-In-process event system for decoupled communication.
+Decoupled pub/sub event system with SSE support for real-time frontend updates.
 
 ## Define Events
 
 ```typescript
 // src/server/events/index.ts
-import { defineEvent, defineEventHandler } from '@spfn/core/event';
-
-// Define event types
-export const userCreated = defineEvent<{
-    userId: string;
-    email: string;
-}>('user.created');
-
-export const userUpdated = defineEvent<{
-    userId: string;
-    changes: Record<string, any>;
-}>('user.updated');
-
-export const userDeleted = defineEvent<{
-    userId: string;
-}>('user.deleted');
+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');
 ```
 
-## Emit Events
+## Subscribe & Emit
 
 ```typescript
-import { emit } from '@spfn/core/event';
-import { userCreated } from './events';
+import { userCreated, serverStarted } from './events';
 
-// In repository or service
-async function createUser(data: NewUser)
-{
-    const user = await this._create(users, data);
+// Subscribe to event
+const unsubscribe = userCreated.subscribe((payload) => {
+    console.log('User created:', payload.userId);
+});
 
-    await emit(userCreated, {
-        userId: user.id,
-        email: user.email
-    });
+// Emit event
+await userCreated.emit({ userId: '123', email: 'user@example.com' });
 
-    return user;
-}
+// Emit event without payload
+await serverStarted.emit();
+
+// Unsubscribe when done
+unsubscribe();
 ```
 
-## Handle Events
+## Multiple Subscribers
 
 ```typescript
-import { on } from '@spfn/core/event';
-import { userCreated, userDeleted } from './events';
+// Multiple independent handlers
+userCreated.subscribe(async (payload) => {
+    await sendWelcomeEmail(payload.email);
+});
+
+userCreated.subscribe(async (payload) => {
+    await createDefaultSettings(payload.userId);
+});
 
-// Register handlers
-on(userCreated, async (payload) => {
-    // Send welcome email
-    await emailService.sendWelcome(payload.email);
+userCreated.subscribe(async (payload) => {
+    await notifyAdmins(payload.userId);
 });
 
-on(userCreated, async (payload) => {
-    // Create default settings
-    await settingsRepo.createDefaults(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)
+})
+```
+
+## 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,
 });
 
-on(userDeleted, async (payload) => {
-    // Cleanup related data
-    await cleanupUserData(payload.userId);
+// 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();
 ```
 
-## Handler Registration
+## Simple Subscribe Helper
 
 ```typescript
-// src/server/events/handlers.ts
-import { on } from '@spfn/core/event';
-import { userCreated, userUpdated, userDeleted } from './index';
+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 all handlers
-export function registerEventHandlers()
+// 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)
 {
-    on(userCreated, handleUserCreated);
-    on(userUpdated, handleUserUpdated);
-    on(userDeleted, handleUserDeleted);
+    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));
+                }
+            });
+        },
+    });
 }
 
-// Call in server startup
-import { registerEventHandlers } from './events/handlers';
-registerEventHandlers();
+// Events now broadcast to all instances
+await userCreated.emit({ userId: '123' });
 ```
 
-## Best Practices
+## API Reference
+
+### defineEvent(name)
+
+Define an event without payload.
 
 ```typescript
-// 1. Define events in a central location
-// src/server/events/index.ts
+export const serverStarted = defineEvent('server.started');
+
+serverStarted.subscribe(() => { ... });
+await serverStarted.emit();
+```
 
-// 2. Use descriptive event names
+### 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 |
+
+## 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')
 
-// 3. Keep payloads minimal
-defineEvent<{ userId: string }>('user.deleted')  // Just ID, not full user
+// 2. Keep payloads minimal - just IDs, not full objects
+defineEvent('user.deleted', Type.Object({
+    userId: Type.String(),
+}));
 
-// 4. Handle errors in handlers
-on(userCreated, async (payload) => {
-    try {
-        await sendEmail(payload.email);
-    } catch (error) {
-        logger.error('Failed to send email', { error });
-    }
+// 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');
 });
 
-// 5. Use events for side effects, not core logic
+// 4. Use events for side effects, not core logic
 // Core: await userRepo.create(data);
-// Side effect: emit(userCreated, { ... });
+// 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spfn/core",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.12",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {