@spfn/core 0.2.0-beta.9 → 0.3.0-beta.2

package/docs/errors.md

@@ -1,319 +0,0 @@
-# Errors
-
-Error types and handling patterns.
-
-## Error Types
-
-### HttpError
-
-General HTTP error with status code.
-
-```typescript
-import { HttpError } from '@spfn/core/errors';
-
-throw new HttpError(404, 'User not found');
-throw new HttpError(403, 'Access denied');
-throw new HttpError(500, 'Internal server error');
-```
-
-### ValidationError
-
-Input validation error with field details.
-
-```typescript
-import { ValidationError } from '@spfn/core/errors';
-
-throw new ValidationError({
-    message: 'Validation failed',
-    fields: [
-        { path: '/email', message: 'Invalid email format' },
-        { path: '/name', message: 'Name is required' }
-    ]
-});
-```
-
-**Response format:**
-
-```json
-{
-    "error": "Validation failed",
-    "fields": [
-        { "path": "/email", "message": "Invalid email format" },
-        { "path": "/name", "message": "Name is required" }
-    ]
-}
-```
-
-### NotFoundError
-
-Resource not found error.
-
-```typescript
-import { NotFoundError } from '@spfn/core/errors';
-
-throw new NotFoundError('User');
-// → 404: "User not found"
-
-throw new NotFoundError('Post', '123');
-// → 404: "Post with id 123 not found"
-```
-
-### UnauthorizedError
-
-Authentication required error.
-
-```typescript
-import { UnauthorizedError } from '@spfn/core/errors';
-
-throw new UnauthorizedError();
-// → 401: "Unauthorized"
-
-throw new UnauthorizedError('Invalid token');
-// → 401: "Invalid token"
-```
-
-### ForbiddenError
-
-Permission denied error.
-
-```typescript
-import { ForbiddenError } from '@spfn/core/errors';
-
-throw new ForbiddenError();
-// → 403: "Forbidden"
-
-throw new ForbiddenError('Admin access required');
-// → 403: "Admin access required"
-```
-
-### ConflictError
-
-Resource conflict error.
-
-```typescript
-import { ConflictError } from '@spfn/core/errors';
-
-throw new ConflictError('Email already exists');
-// → 409: "Email already exists"
-```
-
-### BadRequestError
-
-Invalid request error.
-
-```typescript
-import { BadRequestError } from '@spfn/core/errors';
-
-throw new BadRequestError('Invalid date format');
-// → 400: "Invalid date format"
-```
-
----
-
-## Database Errors
-
-### RepositoryError
-
-Error from repository operations with context.
-
-```typescript
-import { RepositoryError } from '@spfn/core/db';
-
-// Automatically thrown by BaseRepository.withContext()
-// Contains: repository name, method, table, original error
-```
-
-### PostgreSQL Error Conversion
-
-```typescript
-import { fromPostgresError } from '@spfn/core/db';
-
-try
-{
-    await db.insert(users).values(data);
-}
-catch (error)
-{
-    const customError = fromPostgresError(error);
-    // 23505 → DuplicateEntryError
-    // 23503 → ConstraintViolationError
-    // 40P01 → DeadlockError
-    throw customError;
-}
-```
-
----
-
-## Error Handling in Routes
-
-### Simple Throw
-
-```typescript
-route.get('/users/:id')
-    .handler(async (c) => {
-        const user = await userRepo.findById(id);
-
-        if (!user)
-        {
-            throw new NotFoundError('User');
-        }
-
-        return user;
-    });
-```
-
-### With HttpError
-
-```typescript
-route.post('/login')
-    .handler(async (c) => {
-        const { body } = await c.data();
-        const user = await userRepo.findByEmail(body.email);
-
-        if (!user || !await verifyPassword(body.password, user.password))
-        {
-            throw new UnauthorizedError('Invalid credentials');
-        }
-
-        return { token: generateToken(user) };
-    });
-```
-
-### Validation in Repository
-
-```typescript
-// repository
-async createUser(data: NewUser)
-{
-    const existing = await this._findOne(users, { email: data.email });
-    if (existing)
-    {
-        throw new ConflictError('Email already exists');
-    }
-
-    return this._create(users, data);
-}
-
-// route
-route.post('/users')
-    .handler(async (c) => {
-        const { body } = await c.data();
-        return userRepo.createUser(body);  // Throws ConflictError if exists
-    });
-```
-
----
-
-## Error Response Format
-
-All errors are converted to JSON response:
-
-```json
-{
-    "error": "Error message",
-    "code": "ERROR_CODE",
-    "statusCode": 404
-}
-```
-
-**Validation errors:**
-
-```json
-{
-    "error": "Validation failed",
-    "fields": [
-        { "path": "/email", "message": "Invalid format" }
-    ],
-    "statusCode": 400
-}
-```
-
----
-
-## Global Error Handler
-
-Errors are caught by global error middleware:
-
-```typescript
-// Automatic - no setup needed
-// Standard Error → 500 Internal Server Error
-// HttpError → Custom status code
-// ValidationError → 400 with field details
-```
-
----
-
-## Custom Error Classes
-
-```typescript
-import { HttpError } from '@spfn/core/errors';
-
-export class PaymentRequiredError extends HttpError
-{
-    constructor(message = 'Payment required')
-    {
-        super(402, message);
-        this.name = 'PaymentRequiredError';
-    }
-}
-
-export class TooManyRequestsError extends HttpError
-{
-    constructor(retryAfter?: number)
-    {
-        super(429, 'Too many requests');
-        this.name = 'TooManyRequestsError';
-        if (retryAfter)
-        {
-            this.headers = { 'Retry-After': String(retryAfter) };
-        }
-    }
-}
-```
-
----
-
-## Best Practices
-
-### Do
-
-```typescript
-// 1. Use specific error types
-throw new NotFoundError('User');  // Not: throw new Error('User not found');
-
-// 2. Provide meaningful messages
-throw new ForbiddenError('Only admins can delete users');
-
-// 3. Throw errors from repository for business logic
-async createUser(data) {
-    if (await this.emailExists(data.email)) {
-        throw new ConflictError('Email already exists');
-    }
-}
-
-// 4. Let errors propagate - don't catch and re-throw
-route.handler(async (c) => {
-    return userRepo.create(data);  // Let errors propagate
-});
-```
-
-### Don't
-
-```typescript
-// 1. Don't use generic Error for HTTP errors
-throw new Error('Not found');  // Use NotFoundError
-
-// 2. Don't catch errors just to log
-try {
-    await userRepo.create(data);
-} catch (e) {
-    console.log(e);  // Bad - error handling does this
-    throw e;
-}
-
-// 3. Don't return error objects
-return { error: 'Not found' };  // Throw instead
-
-// 4. Don't expose internal error details
-throw new HttpError(500, error.stack);  // Bad - security risk
-```

package/docs/event.md

@@ -1,116 +0,0 @@
-# Event
-
-In-process event system for decoupled communication.
-
-## 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');
-```
-
-## Emit Events
-
-```typescript
-import { emit } from '@spfn/core/event';
-import { userCreated } from './events';
-
-// In repository or service
-async function createUser(data: NewUser)
-{
-    const user = await this._create(users, data);
-
-    await emit(userCreated, {
-        userId: user.id,
-        email: user.email
-    });
-
-    return user;
-}
-```
-
-## Handle Events
-
-```typescript
-import { on } from '@spfn/core/event';
-import { userCreated, userDeleted } from './events';
-
-// Register handlers
-on(userCreated, async (payload) => {
-    // Send welcome email
-    await emailService.sendWelcome(payload.email);
-});
-
-on(userCreated, async (payload) => {
-    // Create default settings
-    await settingsRepo.createDefaults(payload.userId);
-});
-
-on(userDeleted, async (payload) => {
-    // Cleanup related data
-    await cleanupUserData(payload.userId);
-});
-```
-
-## Handler Registration
-
-```typescript
-// src/server/events/handlers.ts
-import { on } from '@spfn/core/event';
-import { userCreated, userUpdated, userDeleted } from './index';
-
-// Register all handlers
-export function registerEventHandlers()
-{
-    on(userCreated, handleUserCreated);
-    on(userUpdated, handleUserUpdated);
-    on(userDeleted, handleUserDeleted);
-}
-
-// Call in server startup
-import { registerEventHandlers } from './events/handlers';
-registerEventHandlers();
-```
-
-## Best Practices
-
-```typescript
-// 1. Define events in a central location
-// src/server/events/index.ts
-
-// 2. 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
-
-// 4. Handle errors in handlers
-on(userCreated, async (payload) => {
-    try {
-        await sendEmail(payload.email);
-    } catch (error) {
-        logger.error('Failed to send email', { error });
-    }
-});
-
-// 5. Use events for side effects, not core logic
-// Core: await userRepo.create(data);
-// Side effect: emit(userCreated, { ... });
-```

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!
-```