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

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

@@ -2,6 +2,20 @@ import { TSchema, Static } from '@sinclair/typebox';
 import { ErrorRegistry, ErrorRegistryInput } from '@spfn/core/errors';
 import { RouteDef, RouteInput } from '@spfn/core/route';
 
+/**
+ * Convert File types in schema to actual File for client usage
+ *
+ * TypeBox File schemas become actual File objects on the client side.
+ */
+type ConvertFileTypes<T> = T extends File ? File : T extends File[] ? File[] : T;
+/**
+ * Extract form data input type with File support
+ *
+ * Maps schema types to runtime types, converting FileSchema to File.
+ */
+type FormDataInput<T> = {
+    [K in keyof T]: ConvertFileTypes<T[K]>;
+};
 /**
  * Extract structured input from RouteInput
  *
@@ -11,6 +25,7 @@ type StructuredInput<TInput extends RouteInput> = {
     params: TInput['params'] extends TSchema ? Static<TInput['params']> : {};
     query: TInput['query'] extends TSchema ? Static<TInput['query']> : {};
     body: TInput['body'] extends TSchema ? Static<TInput['body']> : {};
+    formData: TInput['formData'] extends TSchema ? FormDataInput<Static<TInput['formData']>> : {};
     headers: TInput['headers'] extends TSchema ? Static<TInput['headers']> : {};
     cookies: TInput['cookies'] extends TSchema ? Static<TInput['cookies']> : {};
 };

package/docs/cache.md

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

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

@@ -0,0 +1,346 @@
+# 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
+});
+```
+
+### 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'));
+```
+
+---
+
+## 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);
+```