@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.10

package/docs/server.md

@@ -0,0 +1,307 @@
+# Server
+
+HTTP server configuration with three-level progressive customization.
+
+## Quick Start
+
+```typescript
+// src/server/index.ts
+import { startServer } from '@spfn/core/server';
+
+await startServer();
+```
+
+---
+
+## Configuration Levels
+
+### Level 1: Zero Config
+
+No configuration needed. Uses sensible defaults:
+
+```typescript
+import { startServer } from '@spfn/core/server';
+
+await startServer();
+// Port: 4000 (or process.env.PORT)
+// Host: localhost (or process.env.HOST)
+// Middleware: Logger + CORS + ErrorHandler
+// Infrastructure: Auto-init from env vars
+```
+
+### Level 2: Partial Customization
+
+Create `src/server/server.config.ts`:
+
+```typescript
+import { defineServerConfig, defineRouter } from '@spfn/core/server';
+import * as userRoutes from './routes/users';
+import * as postRoutes from './routes/posts';
+import { authMiddleware, rateLimiter } from './middlewares';
+
+const appRouter = defineRouter({
+    ...userRoutes,
+    ...postRoutes
+});
+
+export default defineServerConfig()
+    .port(8790)
+    .host('0.0.0.0')
+    .routes(appRouter)
+    .middlewares([authMiddleware, rateLimiter])
+    .build();
+
+export type AppRouter = typeof appRouter;
+```
+
+### Level 3: Full Control
+
+Create `src/server/app.ts` for custom Hono setup:
+
+```typescript
+import { Hono } from 'hono';
+import { timing } from 'hono/timing';
+import { compress } from 'hono/compress';
+import type { AppFactory } from '@spfn/core/server';
+
+export default (async () => {
+    const app = new Hono();
+
+    // Custom middleware
+    app.use('*', timing());
+    app.use('*', compress());
+
+    // Custom routes
+    app.get('/custom', (c) => c.json({ custom: true }));
+
+    return app;
+}) satisfies AppFactory;
+```
+
+Then in `server.config.ts`:
+
+```typescript
+export default defineServerConfig()
+    .routes(appRouter)  // Routes registered to your custom app
+    .build();
+```
+
+---
+
+## Configuration Builder
+
+### Basic Options
+
+```typescript
+defineServerConfig()
+    .port(8790)                    // Server port
+    .host('0.0.0.0')               // Server host
+    .routes(appRouter)             // Router
+    .middlewares([...])            // Global middlewares
+    .build();
+```
+
+### Infrastructure Options
+
+```typescript
+defineServerConfig()
+    .database(true)                // Enable database (default: auto from env)
+    .redis(true)                   // Enable Redis (default: auto from env)
+    .build();
+```
+
+### CORS Options
+
+```typescript
+defineServerConfig()
+    .cors({
+        origin: ['https://example.com'],
+        methods: ['GET', 'POST', 'PUT', 'DELETE'],
+        credentials: true
+    })
+    .build();
+```
+
+### Lifecycle Hooks
+
+```typescript
+defineServerConfig()
+    .beforeStart(async () => {
+        // Before server starts
+        console.log('Initializing...');
+    })
+    .afterStart(async (server) => {
+        // After server is running
+        console.log(`Server running on port ${server.port}`);
+    })
+    .beforeShutdown(async () => {
+        // Before graceful shutdown
+        console.log('Shutting down...');
+    })
+    .build();
+```
+
+---
+
+## Router
+
+### Define Router
+
+```typescript
+import { defineRouter } from '@spfn/core/route';
+
+export const appRouter = defineRouter({
+    getUser,
+    createUser,
+    updateUser,
+    deleteUser
+});
+```
+
+### Nested Routers
+
+```typescript
+export const appRouter = defineRouter({
+    users: defineRouter({
+        get: getUser,
+        create: createUser,
+        list: getUsers
+    }),
+    posts: defineRouter({
+        get: getPost,
+        create: createPost
+    })
+});
+```
+
+### Type Export
+
+```typescript
+// server.config.ts
+export type AppRouter = typeof appRouter;
+
+// Use in Next.js client
+import type { AppRouter } from '@/server/server.config';
+import { createApi } from '@spfn/core/nextjs';
+
+const api = createApi<AppRouter>();
+```
+
+---
+
+## Graceful Shutdown
+
+Automatic graceful shutdown handling:
+
+1. Stop accepting new connections
+2. Wait for in-flight requests
+3. Close database connections
+4. Close Redis connections
+5. Exit process
+
+**Signals handled:** `SIGTERM`, `SIGINT`
+
+---
+
+## Health Check
+
+Built-in health endpoint at `/health`:
+
+```bash
+curl http://localhost:8790/health
+# { "status": "ok", "timestamp": "2024-..." }
+```
+
+---
+
+## Environment Variables
+
+```bash
+# Server
+PORT=8790
+HOST=localhost
+NODE_ENV=development
+
+# Database
+DATABASE_URL=postgresql://localhost:5432/mydb
+DATABASE_WRITE_URL=postgresql://primary:5432/mydb
+DATABASE_READ_URL=postgresql://replica:5432/mydb
+
+# Redis
+REDIS_URL=redis://localhost:6379
+```
+
+---
+
+## File Structure
+
+```
+src/server/
+├── server.config.ts    # Configuration (Level 2)
+├── app.ts              # Custom Hono app (Level 3, optional)
+├── index.ts            # Entry point
+├── entities/           # Database schema
+├── repositories/       # Data access
+├── routes/             # API routes
+└── middlewares/        # Custom middleware
+```
+
+---
+
+## Startup Banner
+
+On startup, server displays:
+
+```
+╭──────────────────────────────────────╮
+│                                      │
+│     SPFN Server v1.0.0               │
+│                                      │
+│     http://localhost:8790            │
+│                                      │
+│     Press Ctrl+C to stop             │
+│                                      │
+╰──────────────────────────────────────╯
+
+  ✓ Database connected
+  ✓ Redis connected
+  ✓ 12 routes registered
+```
+
+---
+
+## Best Practices
+
+### Do
+
+```typescript
+// 1. Export router type for client usage
+export type AppRouter = typeof appRouter;
+
+// 2. Use lifecycle hooks for initialization
+.beforeStart(async () => {
+    await warmupCache();
+})
+
+// 3. Register global middlewares
+.middlewares([authMiddleware, rateLimiter])
+
+// 4. Use Level 2 for most projects
+defineServerConfig()
+    .port(8790)
+    .routes(appRouter)
+    .build();
+```
+
+### Don't
+
+```typescript
+// 1. Don't hardcode port in production
+.port(8790)  // Use process.env.PORT instead
+
+// 2. Don't skip database auto-init unless needed
+.database(false)  // Usually let it auto-detect
+
+// 3. Don't use Level 3 unless necessary
+// Level 2 covers most use cases
+```

package/package.json

@@ -1,31 +1,34 @@
 {
   "name": "@spfn/core",
-  "version": "0.1.0-alpha.88",
+  "version": "0.2.0-beta.10",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
-    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
       "require": "./dist/client/index.js"
     },
-    "./client/nextjs": {
-      "types": "./dist/client/nextjs/index.d.ts",
-      "import": "./dist/client/nextjs/index.js",
-      "require": "./dist/client/nextjs/index.js"
+    "./nextjs": {
+      "types": "./dist/nextjs/index.d.ts",
+      "import": "./dist/nextjs/index.js",
+      "require": "./dist/nextjs/index.js"
+    },
+    "./nextjs/server": {
+      "types": "./dist/nextjs/server.d.ts",
+      "import": "./dist/nextjs/server.js",
+      "require": "./dist/nextjs/server.js"
     },
     "./route": {
       "types": "./dist/route/index.d.ts",
       "import": "./dist/route/index.js",
       "require": "./dist/route/index.js"
     },
+    "./route/types": {
+      "types": "./dist/route/types.d.ts",
+      "import": "./dist/route/types.js",
+      "require": "./dist/route/types.js"
+    },
     "./db": {
       "types": "./dist/db/index.d.ts",
       "import": "./dist/db/index.js",
@@ -46,11 +49,6 @@
       "import": "./dist/middleware/index.js",
       "require": "./dist/middleware/index.js"
     },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js",
-      "require": "./dist/types/index.js"
-    },
     "./cache": {
       "types": "./dist/cache/index.d.ts",
       "import": "./dist/cache/index.js",
@@ -66,25 +64,40 @@
       "import": "./dist/env/index.js",
       "require": "./dist/env/index.js"
     },
+    "./env/loader": {
+      "types": "./dist/env/loader.d.ts",
+      "import": "./dist/env/loader.js",
+      "require": "./dist/env/loader.js"
+    },
     "./logger": {
       "types": "./dist/logger/index.d.ts",
       "import": "./dist/logger/index.js",
       "require": "./dist/logger/index.js"
     },
-    "./events": {
-      "types": "./dist/events/index.d.ts",
-      "import": "./dist/events/index.js",
-      "require": "./dist/events/index.js"
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "require": "./dist/config/index.js"
     },
-    "./generators": {
-      "types": "./dist/codegen/generators/index.d.ts",
-      "import": "./dist/codegen/generators/index.js",
-      "require": "./dist/codegen/generators/index.js"
+    "./job": {
+      "types": "./dist/job/index.d.ts",
+      "import": "./dist/job/index.js",
+      "require": "./dist/job/index.js"
     },
-    "./codegen/generators": {
-      "types": "./dist/codegen/generators/index.d.ts",
-      "import": "./dist/codegen/generators/index.js",
-      "require": "./dist/codegen/generators/index.js"
+    "./event": {
+      "types": "./dist/event/index.d.ts",
+      "import": "./dist/event/index.js",
+      "require": "./dist/event/index.js"
+    },
+    "./event/sse": {
+      "types": "./dist/event/sse/index.d.ts",
+      "import": "./dist/event/sse/index.js",
+      "require": "./dist/event/sse/index.js"
+    },
+    "./event/sse/client": {
+      "types": "./dist/event/sse/client.d.ts",
+      "import": "./dist/event/sse/client.js",
+      "require": "./dist/event/sse/client.js"
     }
   },
   "keywords": [
@@ -131,11 +144,12 @@
     "chalk": "^5.6.2",
     "chokidar": "^4.0.3",
     "dotenv": "^17.2.3",
-    "drizzle-orm": "^0.44.7",
+    "drizzle-orm": "^0.45.0",
     "drizzle-typebox": "^0.1.0",
-    "hono": "^4.9.0",
+    "hono": "^4.10.6",
     "jiti": "^2.6.1",
     "micromatch": "^4.0.8",
+    "pg-boss": "^11.1.2",
     "postgres": "^3.4.0",
     "typescript": "^5.3.3",
     "zod": "^4.1.11"
@@ -148,12 +162,18 @@
     "@types/node": "^20.11.0",
     "@vitest/coverage-v8": "^4.0.6",
     "drizzle-kit": "^0.31.6",
-    "next": "^16.0.1",
+    "madge": "^8.0.0",
+    "next": "^16.0.0",
     "tsup": "^8.5.0",
     "vitest": "^4.0.6"
   },
   "peerDependencies": {
-    "next": "^16.0.1"
+    "next": "^15.0.0 || ^16.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
   },
   "files": [
     "dist",
@@ -163,28 +183,28 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "alpha"
+    "tag": "beta"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "pnpm check:circular && tsup",
     "dev": "tsup",
-    "test": "vitest",
-    "test:unit": "vitest --config vitest.unit.config.ts",
-    "test:integration": "vitest --config vitest.integration.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "test:coverage": "vitest run --config vitest.unit.config.ts --coverage",
-    "test:logger": "vitest src/logger",
-    "test:errors": "vitest src/errors",
-    "test:codegen": "vitest src/codegen",
-    "test:route": "vitest src/route",
-    "test:client": "vitest src/client",
-    "test:middleware": "vitest src/middleware",
-    "test:env": "vitest src/env",
-    "test:cache": "vitest src/cache --config vitest.integration.config.ts",
-    "test:db": "vitest src/db --config vitest.integration.config.ts",
-    "test:server": "vitest src/server --config vitest.integration.config.ts",
+    "test:logger": "vitest run src/logger",
+    "test:errors": "vitest run src/errors",
+    "test:codegen": "vitest run src/codegen",
+    "test:route": "vitest run src/route",
+    "test:client": "vitest run src/client",
+    "test:middleware": "vitest run src/middleware",
+    "test:env": "vitest run src/env",
+    "test:cache": "vitest run src/cache --config vitest.integration.config.ts",
+    "test:db": "vitest run src/db --config vitest.integration.config.ts",
+    "test:server": "vitest run src/server --config vitest.integration.config.ts",
     "docker:test:up": "docker compose -f docker-compose.test.yml up -d",
     "docker:test:down": "docker compose -f docker-compose.test.yml down",
     "docker:test:logs": "docker compose -f docker-compose.test.yml logs -f",
+    "check:circular": "madge --circular --extensions ts src/",
     "type-check": "tsc --noEmit"
   }
 }

package/dist/auto-loader-JFaZ9gON.d.ts

@@ -1,80 +0,0 @@
-import { MiddlewareHandler, Hono } from 'hono';
-
-declare module 'hono' {
-    interface ContextVariableMap {
-        _skipMiddlewares?: string[];
-    }
-}
-/**
- * AutoRouteLoader: Simplified File-based Routing System
- *
- * Features:
- * - Auto-discovery: Scans routes directory and auto-registers
- * - Dynamic routes: [id] → :id, [...slug] → *
- * - Statistics: Route registration stats for dashboard
- * - Grouping: Natural grouping by directory structure
- */
-type RouteInfo = {
-    path: string;
-    file: string;
-    meta?: {
-        description?: string;
-        tags?: string[];
-        auth?: boolean;
-        [key: string]: unknown;
-    };
-    priority: number;
-};
-type RouteStats = {
-    total: number;
-    byPriority: {
-        static: number;
-        dynamic: number;
-        catchAll: number;
-    };
-    byTag: Record<string, number>;
-    routes: RouteInfo[];
-};
-declare class AutoRouteLoader {
-    private routesDir;
-    private routes;
-    private readonly debug;
-    private readonly middlewares;
-    constructor(routesDir: string, debug?: boolean, middlewares?: Array<{
-        name: string;
-        handler: MiddlewareHandler;
-    }>);
-    load(app: Hono): Promise<RouteStats>;
-    /**
-     * Load routes from an external directory (e.g., from SPFN function packages)
-     * Reads package.json spfn.prefix and mounts routes under that prefix
-     *
-     * @param app - Hono app instance
-     * @param routesDir - Directory containing route handlers
-     * @param packageName - Name of the package (for logging)
-     * @param prefix - Optional prefix to mount routes under (from package.json spfn.prefix)
-     * @returns Route statistics
-     */
-    loadExternalRoutes(app: Hono, routesDir: string, packageName: string, prefix?: string): Promise<RouteStats>;
-    getStats(): RouteStats;
-    private scanFiles;
-    private isValidRouteFile;
-    private loadRoute;
-    private extractContractPaths;
-    private calculateContractPriority;
-    private validateModule;
-    private registerContractBasedMiddlewares;
-    private categorizeAndLogError;
-    private logStats;
-}
-declare function loadRoutes(app: Hono, options?: {
-    routesDir?: string;
-    debug?: boolean;
-    middlewares?: Array<{
-        name: string;
-        handler: MiddlewareHandler;
-    }>;
-    includeFunctionRoutes?: boolean;
-}): Promise<RouteStats>;
-
-export { AutoRouteLoader as A, type RouteInfo as R, type RouteStats as a, loadRoutes as l };