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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spfn/core",
-  "version": "0.2.0-beta.49",
+  "version": "0.2.0-beta.50",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {
@@ -134,7 +134,7 @@
     "transaction",
     "repository-pattern"
   ],
-  "author": "Ray Im <rayim@inflike.com>",
+  "author": "Ray Im <rayim@fxy.global>",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -203,7 +203,7 @@
     "dev": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --config vitest.unit.config.ts --coverage",
+    "test:coverage": "vitest run --coverage",
     "test:logger": "vitest run src/logger",
     "test:errors": "vitest run src/errors",
     "test:codegen": "vitest run src/codegen",

package/docs/cache.md

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

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

package/docs/database.md

@@ -1,436 +0,0 @@
-# Database
-
-PostgreSQL database layer with Drizzle ORM, automatic transaction management, and read/write separation.
-
-## Setup
-
-### Environment Variables
-
-```bash
-# Single database
-DATABASE_URL=postgresql://localhost:5432/mydb
-
-# Primary + Replica (recommended for production)
-DATABASE_WRITE_URL=postgresql://primary:5432/mydb
-DATABASE_READ_URL=postgresql://replica:5432/mydb
-```
-
-### Initialize
-
-```typescript
-import { initDatabase } from '@spfn/core/db';
-
-// Called automatically by startServer()
-// Manual call only needed for scripts
-await initDatabase();
-```
-
----
-
-## Helper Functions
-
-Standalone functions for simple database operations.
-
-```typescript
-import {
-    findOne,
-    findMany,
-    create,
-    createMany,
-    upsert,
-    updateOne,
-    updateMany,
-    deleteOne,
-    deleteMany,
-    count
-} from '@spfn/core/db';
-```
-
-### findOne
-
-Find a single record.
-
-```typescript
-// Object-based where (simple equality)
-const user = await findOne(users, { id: '1' });
-const user = await findOne(users, { email: 'test@example.com' });
-
-// SQL-based where (complex conditions)
-import { eq, and, gt } from 'drizzle-orm';
-const user = await findOne(users, and(
-    eq(users.email, 'test@example.com'),
-    eq(users.isActive, true)
-));
-```
-
-### findMany
-
-Find multiple records with filtering, ordering, and pagination.
-
-```typescript
-// Simple
-const allUsers = await findMany(users);
-
-// With options
-const activeUsers = await findMany(users, {
-    where: { isActive: true },
-    orderBy: desc(users.createdAt),
-    limit: 10,
-    offset: 0
-});
-
-// Complex where
-const recentAdmins = await findMany(users, {
-    where: and(
-        eq(users.role, 'admin'),
-        gt(users.createdAt, lastWeek)
-    ),
-    orderBy: [desc(users.createdAt), asc(users.name)],
-    limit: 20
-});
-```
-
-### create
-
-Create a single record.
-
-```typescript
-const user = await create(users, {
-    email: 'new@example.com',
-    name: 'New User'
-});
-```
-
-### createMany
-
-Create multiple records.
-
-```typescript
-const newUsers = await createMany(users, [
-    { email: 'user1@example.com', name: 'User 1' },
-    { email: 'user2@example.com', name: 'User 2' }
-]);
-```
-
-### upsert
-
-Insert or update on conflict.
-
-```typescript
-const cache = await upsert(cmsCache, data, {
-    target: [cmsCache.section, cmsCache.locale],
-    set: {
-        content: data.content,
-        updatedAt: new Date()
-    }
-});
-```
-
-### updateOne
-
-Update a single record. Returns updated record or null.
-
-```typescript
-const updated = await updateOne(users, { id: '1' }, { name: 'Updated Name' });
-if (!updated)
-{
-    throw new Error('User not found');
-}
-```
-
-### updateMany
-
-Update multiple records. Returns array of updated records.
-
-```typescript
-const updated = await updateMany(
-    users,
-    { role: 'guest' },
-    { isActive: false }
-);
-```
-
-### deleteOne
-
-Delete a single record. Returns deleted record or null.
-
-```typescript
-const deleted = await deleteOne(users, { id: '1' });
-```
-
-### deleteMany
-
-Delete multiple records. Returns array of deleted records.
-
-```typescript
-const deleted = await deleteMany(users, { isActive: false });
-```
-
-### count
-
-Count records.
-
-```typescript
-const total = await count(users);
-const activeCount = await count(users, { isActive: true });
-const adminCount = await count(users, eq(users.role, 'admin'));
-```
-
----
-
-## Transaction
-
-### Transactional Middleware
-
-Use in routes for automatic commit/rollback.
-
-```typescript
-import { Transactional } from '@spfn/core/db';
-
-route.post('/users')
-    .use([Transactional()])
-    .handler(async (c) => {
-        // Auto commit on success
-        // Auto rollback on error
-        return userRepo.create(body);
-    });
-```
-
-**With options:**
-
-```typescript
-Transactional({
-    timeout: 30000,      // Transaction timeout (ms)
-    logSuccess: false,   // Log successful transactions
-    logErrors: true      // Log failed transactions
-})
-```
-
-### Manual Transaction
-
-For complex multi-operation scenarios.
-
-```typescript
-import { runWithTransaction } from '@spfn/core/db';
-
-await runWithTransaction(async () => {
-    const user = await userRepo.create(userData);
-    await profileRepo.create({ userId: user.id, ...profileData });
-    await emailService.sendWelcome(user.email);
-    // All succeed or all rollback
-});
-```
-
-### After-Commit Hooks
-
-Schedule side effects to run only after the transaction commits.
-
-```typescript
-import { onAfterCommit } from '@spfn/core/db';
-
-async function submitRequest(spaceId: string, chatId: string)
-{
-    const publication = await publicationRepo.create({ spaceId, chatId });
-    await requestRepo.updateStatusAtomically(requestId, 'submitted');
-
-    // Runs after commit, fire-and-forget
-    onAfterCommit(() => generateArticle(spaceId, chatId, publication.id));
-
-    return publication;
-}
-```
-
-- Inside transaction: queued, executed after root commit
-- Outside transaction: executed immediately
-- Nested transactions: callbacks bubble up to root
-- Errors are logged, never thrown
-
-### Get Current Transaction
-
-Access the current transaction context.
-
-```typescript
-import { getTransaction } from '@spfn/core/db';
-
-async function customDbOperation()
-{
-    const tx = getTransaction();
-    if (tx)
-    {
-        // Inside transaction
-        await tx.insert(users).values(data);
-    }
-    else
-    {
-        // Not in transaction
-        const db = getDatabase('write');
-        await db.insert(users).values(data);
-    }
-}
-```
-
----
-
-## Direct Database Access
-
-For complex queries not covered by helpers.
-
-```typescript
-import { getDatabase } from '@spfn/core/db';
-
-// Read operations (uses replica if available)
-const db = getDatabase('read');
-const results = await db
-    .select({
-        user: users,
-        postsCount: sql`count(${posts.id})`
-    })
-    .from(users)
-    .leftJoin(posts, eq(users.id, posts.authorId))
-    .groupBy(users.id);
-
-// Write operations (always uses primary)
-const db = getDatabase('write');
-await db.insert(users).values(data);
-```
-
----
-
-## Connection Info
-
-```typescript
-import { getDatabaseInfo, checkConnection } from '@spfn/core/db';
-
-// Get connection status
-const info = getDatabaseInfo();
-// { hasWriteDb: true, hasReadDb: true, pattern: 'write-read' }
-
-// Health check
-const isHealthy = await checkConnection(getDatabase('write'));
-```
-
----
-
-## Pool Recovery
-
-`@spfn/core` rebuilds the entire `postgres.js` pool (atomic swap) in two situations:
-
-1. **Periodic health check** — every `DB_HEALTH_CHECK_INTERVAL` (default 60s),
-   `SELECT 1` runs on write/read. On failure the pool is destroyed and recreated.
-2. **Query-error fast-path** — real query errors caught by `BaseRepository.withContext`
-   and `@Transactional` middleware are classified; once `DB_RECONNECT_ERROR_THRESHOLD`
-   (default 3) connection-level failures occur within `DB_RECONNECT_ERROR_WINDOW_MS`
-   (default 10s), a rebuild fires without waiting for the periodic tick.
-
-Both paths share the same atomic-swap implementation: the new pool is created and
-validated *before* the global reference is replaced, and the old pool is torn down
-only after the swap completes. Concurrent triggers coalesce to a single rebuild.
-
-### Manual trigger
-
-```typescript
-import { forceReconnectDatabase } from '@spfn/core/db';
-
-// Admin endpoint
-route.post('/admin/db/reconnect')
-    .handler(async (c) => {
-        const ran = await forceReconnectDatabase('admin_request');
-        return c.json({ reconnected: ran });
-    });
-```
-
-Returns `false` if the database is not initialized, is currently closing, or a
-reconnect is already in progress.
-
-### Environment variables
-
-```bash
-# Periodic health check
-DB_HEALTH_CHECK_INTERVAL=60000        # ms between SELECT 1 probes
-DB_HEALTH_CHECK_MAX_RETRIES=3         # retries per rebuild attempt
-DB_HEALTH_CHECK_RETRY_INTERVAL=5000   # delay between retries
-
-# Query-error fast-path
-DB_RECONNECT_ERROR_THRESHOLD=3        # errors needed to trigger rebuild
-DB_RECONNECT_ERROR_WINDOW_MS=10000    # sliding window length (min 1000ms)
-```
-
-### Advanced: custom catch sites
-
-Application code that executes drizzle queries outside `BaseRepository` and
-`@Transactional` can feed the fast-path manually:
-
-```typescript
-import { reportDatabaseError } from '@spfn/core/db';
-
-try {
-    await db.execute(sql`...`);
-}
-catch (error) {
-    reportDatabaseError(error);  // no-op for non-connection errors
-    throw error;
-}
-```
-
-Inside `BaseRepository` / `@Transactional` this is already automatic — no
-manual call needed.
-
----
-
-## Cleanup
-
-```typescript
-import { closeDatabase } from '@spfn/core/db';
-
-// Called automatically on graceful shutdown
-// Manual call for scripts/tests
-await closeDatabase();
-```
-
----
-
-## Best Practices
-
-### Do
-
-```typescript
-// 1. Use Transactional for write routes
-route.post('/users')
-    .use([Transactional()])
-    .handler(...)
-
-// 2. Use repository pattern for data access
-const user = await userRepo.findById(id);
-
-// 3. Use read database for read operations
-async findAll()
-{
-    return this._findMany(users);  // BaseRepository uses readDb
-}
-
-// 4. Close connections in tests
-afterAll(async () => {
-    await closeDatabase();
-});
-```
-
-### Don't
-
-```typescript
-// 1. Don't forget Transactional for writes
-route.post('/users')
-    .handler(async (c) => {  // Missing Transactional!
-        await userRepo.create(body);
-    });
-
-// 2. Don't bypass repository in routes
-route.get('/users')
-    .handler(async (c) => {
-        // Bad - use repository
-        return getDatabase('read').select().from(users);
-    });
-
-// 3. Don't use write database for reads
-const db = getDatabase('write');  // Bad for read queries
-await db.select().from(users);
-```