@spfn/core 0.2.0-beta.5 → 0.2.0-beta.8

package/docs/job.md

@@ -0,0 +1,131 @@
+# 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

@@ -0,0 +1,108 @@
+# 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!
+```

package/docs/middleware.md

@@ -0,0 +1,337 @@
+# Middleware
+
+Named middleware system with route-level skip control.
+
+## Define Middleware
+
+### Regular Middleware
+
+```typescript
+import { defineMiddleware } from '@spfn/core/route';
+
+export const authMiddleware = defineMiddleware('auth', async (c, next) => {
+    const token = c.req.header('authorization');
+
+    if (!token)
+    {
+        return c.json({ error: 'Unauthorized' }, 401);
+    }
+
+    const user = await verifyToken(token);
+    c.set('user', user);
+
+    await next();
+});
+```
+
+### Factory Middleware
+
+Middleware with parameters:
+
+```typescript
+export const requireRole = defineMiddleware('role',
+    (...roles: string[]) => async (c, next) => {
+        const user = c.get('user');
+
+        if (!roles.includes(user.role))
+        {
+            return c.json({ error: 'Forbidden' }, 403);
+        }
+
+        await next();
+    }
+);
+
+// Usage
+route.get('/admin')
+    .use([requireRole('admin', 'superadmin')])
+    .handler(...)
+```
+
+### Two-Parameter Factory
+
+For factory with exactly 2 parameters, use `defineMiddlewareFactory`:
+
+```typescript
+import { defineMiddlewareFactory } from '@spfn/core/route';
+
+export const rateLimiter = defineMiddlewareFactory('rateLimit',
+    (limit: number, windowMs: number) => async (c, next) => {
+        // Rate limit logic
+        await next();
+    }
+);
+
+// Usage
+route.get('/api')
+    .use([rateLimiter(100, 60000)])  // 100 requests per minute
+    .handler(...)
+```
+
+---
+
+## Register Global Middleware
+
+```typescript
+// src/server/server.config.ts
+import { defineServerConfig } from '@spfn/core/server';
+import { authMiddleware, loggerMiddleware, corsMiddleware } from './middlewares';
+
+export default defineServerConfig()
+    .middlewares([
+        loggerMiddleware,
+        corsMiddleware,
+        authMiddleware
+    ])
+    .routes(appRouter)
+    .build();
+```
+
+**Execution order:**
+1. Global middlewares (in registration order)
+2. Route-level middlewares (from `.use()`)
+3. Validation middleware (automatic)
+4. Route handler
+
+---
+
+## Use in Routes
+
+### Add Middleware
+
+```typescript
+import { Transactional } from '@spfn/core/db';
+import { authMiddleware, requireRole } from './middlewares';
+
+route.post('/admin/users')
+    .use([authMiddleware, requireRole('admin'), Transactional()])
+    .handler(async (c) => {
+        const user = c.raw.get('user');  // From authMiddleware
+        // ...
+    });
+```
+
+### Skip Global Middleware
+
+```typescript
+// Skip specific middlewares by name
+route.get('/public/health')
+    .skip(['auth', 'rateLimit'])
+    .handler(async (c) => {
+        return { status: 'ok' };
+    });
+
+// Skip all global middlewares
+route.get('/webhooks/stripe')
+    .skip('*')
+    .handler(async (c) => {
+        // No global middleware applied
+    });
+```
+
+**Note:** Route-level middlewares (`.use()`) are never skipped.
+
+---
+
+## Common Middleware Patterns
+
+### Authentication
+
+```typescript
+export const authMiddleware = defineMiddleware('auth', async (c, next) => {
+    const token = c.req.header('authorization')?.replace('Bearer ', '');
+
+    if (!token)
+    {
+        return c.json({ error: 'Missing token' }, 401);
+    }
+
+    try
+    {
+        const payload = await verifyJWT(token);
+        c.set('userId', payload.sub);
+        c.set('user', await userRepo.findById(payload.sub));
+        await next();
+    }
+    catch
+    {
+        return c.json({ error: 'Invalid token' }, 401);
+    }
+});
+```
+
+### Role-based Access
+
+```typescript
+export const requirePermissions = defineMiddleware('permission',
+    (...permissions: string[]) => async (c, next) => {
+        const user = c.get('user');
+
+        const hasPermission = permissions.every(p =>
+            user.permissions.includes(p)
+        );
+
+        if (!hasPermission)
+        {
+            return c.json({ error: 'Insufficient permissions' }, 403);
+        }
+
+        await next();
+    }
+);
+
+// Usage
+route.delete('/posts/:id')
+    .use([requirePermissions('posts:delete')])
+    .handler(...)
+```
+
+### Rate Limiting
+
+```typescript
+const requestCounts = new Map<string, { count: number; resetAt: number }>();
+
+export const rateLimiter = defineMiddlewareFactory('rateLimit',
+    (limit: number, windowMs: number) => async (c, next) => {
+        const key = c.req.header('x-forwarded-for') || 'unknown';
+        const now = Date.now();
+
+        const record = requestCounts.get(key);
+
+        if (!record || now > record.resetAt)
+        {
+            requestCounts.set(key, { count: 1, resetAt: now + windowMs });
+        }
+        else if (record.count >= limit)
+        {
+            return c.json({ error: 'Too many requests' }, 429);
+        }
+        else
+        {
+            record.count++;
+        }
+
+        await next();
+    }
+);
+```
+
+### Request Logging
+
+```typescript
+export const requestLogger = defineMiddleware('requestLogger', async (c, next) => {
+    const start = Date.now();
+    const method = c.req.method;
+    const path = c.req.path;
+
+    await next();
+
+    const duration = Date.now() - start;
+    const status = c.res.status;
+
+    console.log(`${method} ${path} ${status} ${duration}ms`);
+});
+```
+
+### CORS
+
+```typescript
+export const corsMiddleware = defineMiddleware('cors', async (c, next) => {
+    const origin = c.req.header('origin');
+
+    if (origin && allowedOrigins.includes(origin))
+    {
+        c.header('Access-Control-Allow-Origin', origin);
+        c.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
+        c.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    }
+
+    if (c.req.method === 'OPTIONS')
+    {
+        return c.body(null, 204);
+    }
+
+    await next();
+});
+```
+
+---
+
+## Middleware Deduplication
+
+When the same middleware is registered both globally and in a route, it's automatically deduplicated:
+
+```typescript
+// Registered globally
+.middlewares([authMiddleware])
+
+// Also used in route
+route.get('/users')
+    .use([authMiddleware])  // Skipped (already applied globally)
+    .handler(...)
+```
+
+---
+
+## Access Context Data
+
+### Set Data
+
+```typescript
+defineMiddleware('auth', async (c, next) => {
+    c.set('user', user);
+    c.set('sessionId', sessionId);
+    await next();
+});
+```
+
+### Get Data in Handler
+
+```typescript
+route.get('/profile')
+    .handler(async (c) => {
+        const user = c.raw.get('user');
+        const sessionId = c.raw.get('sessionId');
+        // ...
+    });
+```
+
+---
+
+## Best Practices
+
+### Do
+
+```typescript
+// 1. Use meaningful names for skip control
+export const authMiddleware = defineMiddleware('auth', ...);
+export const rateLimiter = defineMiddleware('rateLimit', ...);
+
+// 2. Set context data for downstream use
+c.set('user', user);
+
+// 3. Return early for unauthorized requests
+if (!token) return c.json({ error: 'Unauthorized' }, 401);
+
+// 4. Always call next() for successful middleware
+await next();
+```
+
+### Don't
+
+```typescript
+// 1. Don't forget to call next()
+defineMiddleware('logger', async (c, next) => {
+    console.log(c.req.path);
+    // Missing next() - request hangs!
+});
+
+// 2. Don't use generic names
+defineMiddleware('middleware1', ...);  // Bad
+
+// 3. Don't throw errors - return responses
+defineMiddleware('auth', async (c, next) => {
+    if (!token) throw new Error('No token');  // Bad
+    if (!token) return c.json({ error: 'No token' }, 401);  // Good
+});
+```