@spfn/core 0.1.0-alpha.7 → 0.1.0-alpha.74

package/README.md

@@ -58,7 +58,7 @@ export const getUsersContract = {
 // src/server/routes/users/index.ts
 import { createApp } from '@spfn/core/route';
 import { getUsersContract } from './contract.js';
-import { getRepository } from '@spfn/core/db';
+import { findMany } from '@spfn/core/db';
 import { users } from '../../entities/users.js';
 
 const app = createApp();
@@ -66,14 +66,11 @@ const app = createApp();
 app.bind(getUsersContract, async (c) => {
   const { page = 1, limit = 10 } = c.query;
 
-  // Get repository singleton - automatically cached
-  const repo = getRepository(users);
+  // Use helper function directly - no Repository needed
+  const offset = (page - 1) * limit;
+  const result = await findMany(users, { limit, offset });
 
-  const result = await repo.findPage({
-    pagination: { page, limit }
-  });
-
-  return c.json(result);
+  return c.json({ users: result, total: result.length });
 });
 
 export default app;
@@ -88,7 +85,7 @@ npm run spfn:dev
 
 ## Architecture Pattern
 
-SPFN follows a **layered architecture** that separates concerns and keeps code maintainable:
+Superfunction follows a **layered architecture** that separates concerns and keeps code maintainable:
 
 ```
 ┌─────────────────────────────────────────┐
@@ -102,14 +99,14 @@ SPFN follows a **layered architecture** that separates concerns and keeps code m
 │           Service Layer                  │  Business logic
 │  - Orchestrate operations               │
 │  - Implement business rules             │
-│  - Use repositories                     │
+│  - Use helper functions or custom logic │
 └──────────────┬──────────────────────────┘
                │
 ┌──────────────▼──────────────────────────┐
-│         Repository Layer                 │  Data access
-│  - CRUD operations                      │
-│  - Custom queries                       │
-│  - Extend base Repository               │
+│         Data Access Layer                │  Database operations
+│  - Use helper functions (findOne, etc)  │
+│  - Custom queries with Drizzle          │
+│  - Domain-specific wrappers             │
 └──────────────┬──────────────────────────┘
                │
 ┌──────────────▼──────────────────────────┐
@@ -144,134 +141,35 @@ export type Post = typeof posts.$inferSelect;
 export type NewPost = typeof posts.$inferInsert;
 ```
 
-**2. Repository Layer** - Data access with custom methods
+**2. Data Access Layer** - Helper functions with domain-specific wrappers
 
 ```typescript
 // src/server/repositories/posts.repository.ts
-import { eq } from 'drizzle-orm';
-import { Repository } from '@spfn/core/db';
-import { posts } from '../entities';
-import type { Post } from '../entities';
-
-export class PostRepository extends Repository<typeof posts>
-{
-  async findBySlug(slug: string): Promise<Post | null>
-  {
-    return this.findOne(eq(this.table.slug, slug));
-  }
-
-  async findPublished(): Promise<Post[]>
-  {
-    const results = await this.db
-      .select()
-      .from(this.table)
-      .where(eq(this.table.status, 'published'))
-      .orderBy(this.table.createdAt);
-
-    return results;
-  }
-}
-```
-
-**3. Service Layer** - Business logic (Function-based pattern)
+import { findOne, findMany, create as createHelper } from '@spfn/core/db';
+import { eq, desc } from 'drizzle-orm';
+import { posts, type Post, type NewPost } from '../entities/posts';
 
-```typescript
-// src/server/services/posts.ts
-import { getRepository } from '@spfn/core/db';
-import { ValidationError, DatabaseError, NotFoundError } from '@spfn/core';
-import { posts } from '../entities';
-import { PostRepository } from '../repositories/posts.repository';
-import type { NewPost, Post } from '../entities';
-
-/**
- * Create a new post
- */
-export async function createPost(data: {
-  title: string;
-  content: string;
-}): Promise<Post> {
-  try {
-    // Get repository singleton
-    const repo = getRepository(posts, PostRepository);
-
-    // Business logic: Generate slug from title
-    const slug = generateSlug(data.title);
-
-    // Validation: Check if slug already exists
-    const existing = await repo.findBySlug(slug);
-    if (existing) {
-      throw new ValidationError('Post with this title already exists', {
-        fields: [{
-          path: '/title',
-          message: 'A post with this title already exists',
-          value: data.title
-        }]
-      });
-    }
-
-    // Create post
-    return await repo.save({
-      ...data,
-      slug,
-      status: 'draft',
-    });
-  } catch (error) {
-    // Re-throw ValidationError as-is
-    if (error instanceof ValidationError) {
-      throw error;
-    }
-
-    // Wrap unexpected errors
-    throw new DatabaseError('Failed to create post', 500, {
-      originalError: error instanceof Error ? error.message : String(error)
-    });
-  }
+// Domain-specific wrappers using helper functions
+export async function findPostBySlug(slug: string): Promise<Post | null> {
+  return findOne(posts, { slug });
 }
 
-/**
- * Publish a post
- */
-export async function publishPost(id: string): Promise<Post> {
-  try {
-    const repo = getRepository(posts, PostRepository);
-    const post = await repo.update(id, { status: 'published' });
-
-    if (!post) {
-      throw new NotFoundError('Post not found');
-    }
-
-    return post;
-  } catch (error) {
-    if (error instanceof NotFoundError) {
-      throw error;
-    }
-
-    throw new DatabaseError('Failed to publish post', 500, {
-      originalError: error instanceof Error ? error.message : String(error)
-    });
-  }
+export async function findPublishedPosts(): Promise<Post[]> {
+  return findMany(posts, {
+    where: { status: 'published' },
+    orderBy: desc(posts.createdAt)
+  });
 }
 
-/**
- * Get all published posts
- */
-export async function getPublishedPosts(): Promise<Post[]> {
-  const repo = getRepository(posts, PostRepository);
-  return repo.findPublished();
+export async function createPost(data: NewPost): Promise<Post> {
+  return createHelper(posts, data);
 }
 
-/**
- * Helper: Generate URL-friendly slug from title
- */
-function generateSlug(title: string): string {
-  return title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/(^-|-$)/g, '');
-}
+// Or use helper functions directly in routes for simple cases
+// const post = await findOne(posts, { id: 1 });
 ```
 
-**4. Routes Layer** - HTTP API
+**3. Routes Layer** - HTTP API
 
 ```typescript
 // src/server/routes/posts/contracts.ts
@@ -306,22 +204,40 @@ export const listPostsContract = {
 // src/server/routes/posts/index.ts
 import { createApp } from '@spfn/core/route';
 import { Transactional } from '@spfn/core/db';
-import { createPost, getPublishedPosts } from '../../services/posts';
+import { findPostBySlug, createPost, findPublishedPosts } from '../../repositories/posts.repository';
 import { createPostContract, listPostsContract } from './contracts';
 
 const app = createApp();
 
 // POST /posts - Create new post (with transaction)
-app.bind(createPostContract, Transactional(), async (c) => {
+app.bind(createPostContract, [Transactional()], async (c) => {
   const body = await c.data();
-  const post = await createPost(body);
+
+  // Generate slug from title
+  const slug = body.title.toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '');
+
+  // Check if slug exists
+  const existing = await findPostBySlug(slug);
+  if (existing) {
+    return c.json({ error: 'Post with this title already exists' }, 409);
+  }
+
+  // Create post
+  const post = await createPost({
+    ...body,
+    slug,
+    status: 'draft'
+  });
+
   // ✅ Auto-commit on success, auto-rollback on error
   return c.json(post, 201);
 });
 
 // GET /posts - List published posts (no transaction needed)
 app.bind(listPostsContract, async (c) => {
-  const posts = await getPublishedPosts();
+  const posts = await findPublishedPosts();
   return c.json(posts);
 });
 
@@ -340,10 +256,10 @@ export default app;
 
 **✅ Reusability**
 - Services can be used by multiple routes
-- Repositories can be shared across services
+- Data access functions can be shared across services
 
 **✅ Type Safety**
-- Types flow from Entity → Repository → Service → Route
+- Types flow from Entity → Data Access → Service → Route
 - Full IDE autocomplete and error checking
 
 **✅ Maintainability**
@@ -355,7 +271,7 @@ export default app;
 | Layer | Responsibility | Examples |
 |-------|---------------|----------|
 | **Entity** | Define data structure | Schema, types, constraints |
-| **Repository** | Data access | CRUD, custom queries, joins |
+| **Data Access** | Database operations | Helper functions, custom queries, joins |
 | **Service** | Business logic | Validation, orchestration, rules |
 | **Routes** | HTTP interface | Contracts, request handling |
 
@@ -366,21 +282,16 @@ export default app;
 - ✅ Export inferred types: `Post`, `NewPost`
 - ✅ Use TEXT with enum for status fields
 
-**Repository Layer:**
-- ✅ Extend `Repository<typeof table>` for custom methods
-- ✅ Use `getRepository(table)` or `getRepository(table, CustomRepo)`
-- ✅ Add domain-specific query methods
-- ✅ Return typed results
-
-**Service Layer:**
-- ✅ Use function-based pattern (export async functions)
-- ✅ Get repositories via `getRepository()` (singleton)
-- ✅ Implement business logic and validation
-- ✅ Throw descriptive errors
-- ✅ Keep functions focused and small
+**Data Access Layer:**
+- ✅ Use helper functions for simple CRUD: `findOne()`, `create()`, etc.
+- ✅ Create domain-specific wrappers in `src/server/repositories/*.repository.ts`
+- ✅ Export functions (not classes): `export async function findPostBySlug()`
+- ✅ Use object-based where for simple queries: `{ id: 1 }`
+- ✅ Use SQL-based where for complex queries: `and(eq(...), gt(...))`
+- ✅ Full TypeScript type inference from table schemas
 
 **Routes Layer:**
-- ✅ Keep handlers thin (delegate to services)
+- ✅ Keep handlers thin (delegate to services/data access)
 - ✅ Define contracts with TypeBox
 - ✅ Use `Transactional()` middleware for write operations
 - ✅ Use `c.data()` for validated input
@@ -399,61 +310,75 @@ File-based routing with contract validation and type safety.
 - Type-safe request/response handling
 - Method-level middleware control (skip auth per HTTP method)
 
-### 🗄️ Database & Repository
-Drizzle ORM integration with repository pattern and pagination.
+### 🗄️ Database
+Drizzle ORM integration with type-safe helper functions and automatic transaction handling.
 
 **[→ Read Database Documentation](./src/db/README.md)**
 
-**Guides:**
-- [Repository Pattern](./src/db/docs/repository.md)
-- [Schema Helpers](./src/db/docs/schema-helpers.md)
-- [Database Manager](./src/db/docs/database-manager.md)
+**Key Features:**
+- Helper functions for type-safe CRUD operations
+- Automatic transaction handling and read/write separation
+- Schema helpers: `id()`, `timestamps()`, `foreignKey()`
+- Hybrid where clause support (objects or SQL)
+- **Function schema auto-discovery** (see below)
+
+### 📦 Function Schema Discovery
+Automatic discovery of database schemas from Superfunction ecosystem functions.
 
-#### Choosing a Repository Pattern
+**[→ Read Database Manager Documentation](./src/db/manager/README.md)**
 
-SPFN offers two repository patterns. Choose based on your needs:
+**Key Features:**
+- Zero-config schema discovery from `@spfn/*` functions
+- Functions declare schemas via `package.json`
+- No hard dependencies between functions
+- Efficient scanning (direct dependencies only)
+- Function-specific migration support
 
-**Global Singleton (`getRepository`)**
-```typescript
-import { getRepository } from '@spfn/core/db';
+**How it works:**
 
-const repo = getRepository(users);
+Functions declare their schemas in `package.json`:
+```json
+{
+  "name": "@spfn/cms",
+  "spfn": {
+    "schemas": ["./dist/entities/*.js"],
+    "setupMessage": "📚 Setup guide..."
+  }
+}
 ```
 
-- ✅ Simple API, minimal setup
-- ✅ Maximum memory efficiency
-- ⚠️ Requires manual `clearRepositoryCache()` in tests
-- ⚠️ Global state across all requests
-- 📝 **Use for:** Simple projects, prototypes, single-instance services
-
-**Request-Scoped (`getScopedRepository` + `RepositoryScope()`)** ⭐ Recommended
+Superfunction automatically discovers and merges these schemas during migration generation:
 ```typescript
-import { getScopedRepository, RepositoryScope } from '@spfn/core/db';
+import { getDrizzleConfig } from '@spfn/core'
 
-// Add middleware once (in server setup)
-app.use(RepositoryScope());
-
-// Use in routes/services
-const repo = getScopedRepository(users);
+// Auto-discovers all function schemas
+const config = getDrizzleConfig()
 ```
 
-- ✅ Automatic per-request isolation
-- ✅ No manual cache clearing needed
-- ✅ Test-friendly (each test gets fresh instances)
-- ✅ Production-ready with graceful degradation
-- 📝 **Use for:** Production apps, complex testing, team projects
+**Install functions with automatic DB setup:**
+```bash
+pnpm spfn add @spfn/cms
+# ✅ Installs function
+# ✅ Generates migrations
+# ✅ Applies migrations
+# ✅ Shows setup guide
+```
 
-**Comparison:**
+**Create your own Superfunction packages:**
+```typescript
+// 1. Define entities
+export const myTable = pgTable('my_table', { ... })
 
-| Feature | `getRepository` | `getScopedRepository` |
-|---------|----------------|----------------------|
-| Setup | Zero config | Add middleware |
-| Test isolation | Manual | Automatic |
-| Memory | Shared cache | Per-request cache |
-| State | Global | Request-scoped |
-| Best for | Prototypes | Production |
+// 2. Add to package.json
+{
+  "spfn": {
+    "schemas": ["./dist/entities/*.js"]
+  }
+}
 
-[→ See full request-scoped documentation](./src/db/repository/request-scope.ts)
+// 3. Users install with one command
+// pnpm spfn add @yourcompany/spfn-plugin
+```
 
 ### 🔄 Transactions
 Automatic transaction management with async context propagation.
@@ -485,6 +410,30 @@ Server configuration and lifecycle management.
 
 **[→ Read Server Documentation](./src/server/README.md)**
 
+### 📝 Logger
+High-performance logging with multiple transports, sensitive data masking, and automatic validation.
+
+**[→ Read Logger Documentation](./src/logger/README.md)**
+
+**Key Features:**
+- Adapter pattern (Pino for production, custom for full control)
+- Sensitive data masking (passwords, tokens, API keys)
+- File rotation (date and size-based) with automatic cleanup
+- Configuration validation with clear error messages
+- Multiple transports (Console, File, Slack, Email)
+
+### ⚙️ Code Generation
+Automatic code generation with pluggable generators and centralized file watching.
+
+**[→ Read Codegen Documentation](./src/codegen/README.md)**
+
+**Key Features:**
+- Orchestrator pattern for managing multiple generators
+- Built-in contract generator for type-safe API clients
+- Configuration-based setup (`.spfnrc.json` or `package.json`)
+- Watch mode integrated into `spfn dev`
+- Extensible with custom generators
+
 ## Module Exports
 
 ### Main Export
@@ -501,11 +450,17 @@ import type { RouteContext, RouteContract } from '@spfn/core/route';
 ### Database
 ```typescript
 import {
-  getDb,
-  Repository,
-  getRepository
+  getDatabase,
+  findOne,
+  findMany,
+  create,
+  createMany,
+  updateOne,
+  updateMany,
+  deleteOne,
+  deleteMany,
+  count
 } from '@spfn/core/db';
-import type { Pageable, Page } from '@spfn/core/db';
 ```
 
 ### Transactions
@@ -522,6 +477,11 @@ import {
 import { initRedis, getRedis, getRedisRead } from '@spfn/core';
 ```
 
+### Logger
+```typescript
+import { logger } from '@spfn/core';
+```
+
 ### Client (for frontend)
 ```typescript
 import { ContractClient, createClient } from '@spfn/core/client';
@@ -545,6 +505,17 @@ REDIS_READ_URL=redis://replica:6379
 PORT=8790
 HOST=localhost
 NODE_ENV=development
+
+# Server Timeouts (optional, in milliseconds)
+SERVER_TIMEOUT=120000              # Request timeout (default: 120000)
+SERVER_KEEPALIVE_TIMEOUT=65000     # Keep-alive timeout (default: 65000)
+SERVER_HEADERS_TIMEOUT=60000       # Headers timeout (default: 60000)
+SHUTDOWN_TIMEOUT=30000             # Graceful shutdown timeout (default: 30000)
+
+# Logger (optional)
+LOGGER_ADAPTER=pino               # pino | custom (default: pino)
+LOGGER_FILE_ENABLED=true          # Enable file logging (production only)
+LOG_DIR=/var/log/myapp           # Log directory (required when file logging enabled)
 ```
 
 ## Requirements
@@ -568,12 +539,14 @@ npm test -- --coverage      # With coverage
 
 ### Guides
 - [File-based Routing](./src/route/README.md)
-- [Database & Repository](./src/db/README.md)
+- [Database & Helper Functions](./src/db/README.md)
 - [Transaction Management](./src/db/docs/transactions.md)
 - [Redis Cache](./src/cache/README.md)
 - [Error Handling](./src/errors/README.md)
 - [Middleware](./src/middleware/README.md)
 - [Server Configuration](./src/server/README.md)
+- [Logger](./src/logger/README.md)
+- [Code Generation](./src/codegen/README.md)
 
 ### API Reference
 - See module-specific README files linked above
@@ -584,4 +557,4 @@ MIT
 
 ---
 
-Part of the [SPFN Framework](https://github.com/spfn/spfn)
+Part of the [Superfunction Framework](https://github.com/spfn/spfn)

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

@@ -0,0 +1,80 @@
+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 };