exisjs 0.6.1 → 0.7.0

package/dist/docs/content/database.mdx

@@ -1,278 +0,0 @@
----
-title: "Database Layer"
-description: "ExisJS includes a built-in, efficient database layer with native support for PostgreSQL, MySQL, SQLite, and MongoDB, plus a powerful SQL-First auto-sync engine."
----
-
-# Database Layer
-
-Unlike other Node.js frameworks that rely entirely on third-party ORMs like Prisma or TypeORM, **ExisJS ships with a fully integrated, efficient Database Layer.** 
-
-This provides a massive advantage in developer experience and reliability, as connections, query generation, schema synchronization, and migrations are orchestrated directly by the framework.
-
-<Info title="Functional vs OOP">
-ExisJS natively supports both a **Functional Paradigm** and a **Class-Based OOP Paradigm** (for dependency injection and decorators). The database layer is seamlessly accessible through both approaches.
-</Info>
-
-## Setup and Connection
-
-#### Functional Paradigm
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { createDatabase } from 'exisjs/database'
-import { userTable, leadCustomerTable } from '../database/schema'
-
-export default exis({
-  async onStart(app) {
-    const database = createDatabase({
-      dialect: 'postgres',
-      url: process.env.DATABASE_URL,
-      autoSync: true // Enables automatic schema synchronization!
-    })
-    
-    // Register schemas for Auto-Sync
-    database.registerSchema([userTable, leadCustomerTable])
-
-    // Connect on boot
-    await database.connect()
-  }
-})
-```
-
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/server.ts"
-import { Server } from 'exisjs/decorators'
-import { createDatabase } from 'exisjs/database'
-import { userTable, leadCustomerTable } from '../database/schema'
-
-@Server()
-export default class RootServer {
-  async onStart(app: App) {
-    const database = createDatabase({
-      dialect: 'postgres',
-      url: process.env.DATABASE_URL,
-      autoSync: true
-    })
-    
-    database.registerSchema([userTable, leadCustomerTable])
-    await database.connect()
-  }
-}
-```
-
-## SQL-First Schema Definition
-
-ExisJS provides a strictly-typed, modern **SQL-First Schema API**. Instead of writing raw SQL migration files, you define your tables in TypeScript. When `autoSync` is enabled, ExisJS will read these definitions, diff them against your live PostgreSQL database, and automatically run `CREATE TABLE` and `ALTER TABLE` for you!
-
-```typescript filename="src/database/schema.ts"
-import { table, uuid, text, jsonb, timestamptz, boolean } from 'exisjs/database/sql'
-
-export const userTable = table('user', {
-  user_id: uuid('user_id').primaryKey().default('gen_random_uuid()'),
-  name: text('name').notNull(),
-  phone: text('phone').unique().notNull(),
-  email: text('email').unique().notNull(),
-  address: jsonb('address'),
-  date_of_birth: timestamptz('date_of_birth'),
-  role: text('role').notNull(),
-  password_hash: text('password_hash').notNull(),
-  created_at: timestamptz('created_at').default('NOW()')
-})
-
-export const leadCustomerTable = table('leadCustomer', {
-  record_id: uuid('record_id').primaryKey().default('gen_random_uuid()'),
-  name: text('name').notNull(),
-  email: text('email'),
-  is_customer: boolean('is_customer').default('false'),
-  // Perfect, strict SQL Foreign Key References!
-  assigned_to: uuid('assigned_to').references(() => userTable.user_id),
-})
-```
-
-## Querying
-
-ExisJS supports **two ways** to query your database. You can use the traditional string-based builder, or the new fully-typed SQL-First builder.
-
-### Method A: Typed SQL-First Querying (Recommended)
-This method gives you 100% type safety and auto-complete for your columns.
-
-#### Functional Paradigm
-```typescript filename="src/http/users/route.ts"
-import { controller, route } from 'exisjs/router'
-import { db } from 'exisjs/database'
-import { eq } from 'exisjs/database/sql'
-import { userTable } from '@/database/schema'
-
-export default controller({
-  list: route.get('/', {
-    async handle() {
-      // Fully typed! Auto-complete knows userTable has name, email, etc.
-      const users = await db
-        .select(userTable.user_id.name, userTable.name.name, userTable.email.name)
-        .from(userTable)
-        .where(eq(userTable.role, 'admin'))
-        .limit(10)
-        .rows()
-        
-      return users
-    }
-  }),
-
-  create: route.post('/', {
-    async handle({ req }) {
-      const { name, email, phone, password_hash } = req.body
-      
-      const result = await db
-        .insert(userTable)
-        .values({ name, email, phone, role: 'user', password_hash })
-        .returning(userTable.user_id.name)
-        .execute()
-        
-      return { id: result.rows[0].user_id }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-```typescript filename="src/http/users/service.ts"
-import { Injectable } from 'exisjs/decorators'
-import { db } from 'exisjs/database'
-import { eq } from 'exisjs/database/sql'
-import { userTable } from '@/database/schema'
-
-@Injectable()
-export class UsersService {
-  async getAdmins() {
-    return await db
-      .select(userTable.user_id.name, userTable.name.name, userTable.email.name)
-      .from(userTable)
-      .where(eq(userTable.role, 'admin'))
-      .limit(10)
-      .rows()
-  }
-
-  async createUser(data: any) {
-    const result = await db
-      .insert(userTable)
-      .values({ ...data, role: 'user' })
-      .returning(userTable.user_id.name)
-      .execute()
-      
-    return { id: result.rows[0].user_id }
-  }
-}
-```
-
-### Method B: String-Based Query Builder
-If you don't want to define schema files, you can still use the raw string builder.
-
-```typescript
-// Query multiple rows
-const users = await db.table('users')
-  .select('id', 'name', 'email')
-  .where('role', '=', 'admin')
-  .orderBy('created_at', 'desc')
-  .limit(10)
-  .rows()
-```
-
-## Transactions
-
-ExisJS makes it trivial to perform safe database transactions. If the callback throws an error, the transaction is automatically rolled back.
-
-```typescript
-import { db } from 'exisjs/database'
-
-await db.transaction(async (tx) => {
-  // Deduct from inventory
-  await tx.execute(
-    'UPDATE inventory SET stock = stock - $1 WHERE id = $2', 
-    [1, itemId]
-  )
-  
-  // Create order record
-  await tx.execute(
-    'INSERT INTO orders (user_id, item_id) VALUES ($1, $2)', 
-    [userId, itemId]
-  )
-})
-```
-
-## Manual Migrations (Optional)
-
-If you prefer to write raw SQL instead of using the Auto-Sync engine, ExisJS still includes a built-in migration tracker.
-
-```typescript
-import { db } from 'exisjs/database'
-
-const migrator = db.getMigrator({ directory: './migrations' })
-
-// Apply all pending migrations
-await migrator.up()
-```
-
-A migration file simply exports `up` and `down` methods. You write raw SQL inside them for ultimate control.
-
-```typescript filename="migrations/001_create_users.ts"
-module.exports = {
-  name: '001_create_users',
-  async up(db) {
-    await db.execute(`
-      CREATE TABLE users (
-        id SERIAL PRIMARY KEY,
-        name VARCHAR(255) NOT NULL,
-        email VARCHAR(255) UNIQUE NOT NULL
-      )
-    `)
-  },
-  async down(db) {
-    await db.execute('DROP TABLE users')
-  },
-}
-```
-
-## API Reference
-
-To maintain a clean namespace, ExisJS separates the core database manager from the SQL schema utilities.
-
-### Core Database (`exisjs/database`)
-Imports related to connection management, raw queries, and migrations.
-
-- `db` - The global singleton database manager.
-- `createDatabase` - Factory to instantiate a new database connection.
-- `DatabaseManager` - The underlying class for `db`.
-- `Migrator` - The migration engine class.
-- `QueryBuilder` - The base query builder class.
-
-### SQL-First Schema & Queries (`exisjs/database/sql`)
-Imports related to defining tables, column types, and writing fluent queries.
-
-**Table Builder:**
-- `table` - Define a new SQL-first table.
-
-**Column Types:**
-- `uuid`
-- `text`
-- `varchar`
-- `integer`
-- `serial`
-- `bigint`
-- `numeric`
-- `real`
-- `boolean`
-- `json`
-- `jsonb`
-- `timestamp`
-- `timestamptz`
-- `date`
-
-**Condition Operators (for `.where()`):**
-- `eq` (Equal: `=`)
-- `ne` (Not Equal: `!=`)
-- `gt` (Greater Than: `>`)
-- `gte` (Greater Than or Equal: `>=`)
-- `lt` (Less Than: `<`)
-- `lte` (Less Than or Equal: `<=`)
-- `isNull` (IS NULL)
-- `isNotNull` (IS NOT NULL)
-- `inArray` (IN)

package/dist/docs/content/gateways.mdx

@@ -1,376 +0,0 @@
----
-nextUrl: "/docs/validation"
-nextTitle: "Validation"
----
-
-# Gateways (Middleware & Modules)
-
-Gateways act as a configuration entry point for specific folders in your file-system routing architecture.
-
-Instead of writing programmatic middleware declarations like `app.use('/admin', requireAuth)`, you can place a `gateway.ts` file inside a folder to scope **Middleware**, **CORS**, and **Dependency Injection** to that specific domain.
-
-## Cascading Middleware
-
-The most common use-case for a gateway is applying middleware arrays to a group of routes.
-
-### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/admin/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-import { requireAuth } from '../../middleware/auth'
-import { cors, helmet } from 'exisjs/middleware'
-
-export default defineGateway({
-  // This middleware array runs before ANY route in /admin/*
-  middleware: [
-    helmet(),
-    compress(),
-    cache({ ttlMs: 60000 }),
-    requireAuth
-  ],
-  
-  // Enforce strict CORS for this folder
-  cors: {
-    origin: 'https://admin.yourdomain.com',
-    methods: ['GET', 'POST', 'DELETE']
-  },
-
-  // Append custom default headers to all responses
-  headers: {
-    'X-Admin-Api-Version': '2.0'
-  }
-})
-```
-
-### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/admin/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-import { requireAuth } from '../../middleware/auth'
-import { helmet } from 'exisjs/middleware'
-
-@Gateway({
-  // This middleware array runs before ANY route in /admin/*
-  middleware: [
-    helmet(),
-    compress(),
-    cache({ ttlMs: 60000 }),
-    requireAuth
-  ],
-  
-  // Enforce strict CORS for this folder
-  cors: {
-    origin: 'https://admin.yourdomain.com',
-    methods: ['GET', 'POST', 'DELETE']
-  },
-
-  // Append custom default headers to all responses
-  headers: {
-    'X-Admin-Api-Version': '2.0'
-  }
-})
-export default class AdminGateway {}
-```
-
-When a request comes in for `/admin/users`, ExisJS processes the Gateway's middleware sequentially before it ever reaches your `route.ts` file.
-
-## Folder-Scoped CORS
-
-Handling CORS across an API can require granular control. For instance, you might want your `/public` folder to accept requests from anywhere, while restricting your `/billing` folder to a strict frontend domain. ExisJS allows you to define the `cors` property in your Gateway, overriding the global configuration for that specific folder.
-
-## File-Based Modules (Domain-Driven Design)
-
-In addition to serving as an interceptor for middleware, `gateway.ts` acts as a module boundary, enabling **Domain-Driven Design (DDD)** via the file system.
-
-### Providers (Dependency Injection)
-
-If you have a database service unique to your `/users` domain, encapsulate it strictly inside the users gateway:
-
-```typescript className="language-typescript" filename="src/http/users/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-import { UsersRepository } from './repository'
-
-export default defineGateway({
-  // Provide the UsersRepository directly to this folder's DI container!
-  providers: [
-    ['UsersRepository', { useClass: UsersRepository }]
-  ]
-})
-```
-
-When ExisJS boots, it automatically discovers `gateway.ts`, parses the `providers`, and hydrates them into the internal Dependency Injection container before executing the routes. Inside your route handler, you can inject them:
-
-#### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/users/route.ts"
-import { controller, route } from 'exisjs/router'
-import { inject } from 'exisjs/di'
-import type { UsersRepository } from './repository'
-
-export default controller({
-  list: route.get('/', {
-    async handle() {
-      // Access the scoped dependency
-      const usersRepo = inject<UsersRepository>('UsersRepository')
-      return await usersRepo.findAll()
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/users/route.ts"
-import { Controller, Get } from 'exisjs/decorators'
-import { inject } from 'exisjs/di'
-import type { UsersRepository } from './repository'
-
-@Controller()
-export default class UsersController {
-  @Get('/')
-  async list() {
-    const usersRepo = inject<UsersRepository>('UsersRepository')
-    return await usersRepo.findAll()
-  }
-}
-```
-
-### Imports & Plugins
-
-Gateways allow you to bundle other modules and plugins into a domain.
-
-### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/orders/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-import AuthModule from '../auth/module'
-import { stripePlugin } from '../../plugins/stripe'
-
-export default defineGateway({
-  // Pull in the Auth feature set
-  imports: [AuthModule],
-  
-  // Isolate Stripe setup for the orders domain
-  plugins: [stripePlugin({ apiKey: process.env.STRIPE_KEY })]
-})
-```
-
-### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/orders/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-import AuthModule from '../auth/module'
-import { stripePlugin } from '../../plugins/stripe'
-
-@Gateway({
-  // Pull in the Auth feature set
-  imports: [AuthModule],
-  
-  // Isolate Stripe setup for the orders domain
-  plugins: [stripePlugin({ apiKey: process.env.STRIPE_KEY })]
-})
-export default class OrdersGateway {}
-```
-
-<Hint>
-- **Imports**: Automatically deduplicated. If multiple gateways import `AuthModule`, its internal singletons are only initialized once.
-- **Plugins**: Setup logic runs specifically for the scoped folder.
-</Hint>
-
-## Gateway Inheritance (Cascading)
-
-Gateways inherently **cascade**. If you define a Gateway at the absolute root (`src/http/gateway.ts`), it applies globally.
-
-If you define another Gateway at `src/http/admin/gateway.ts`, requests to `/admin/dashboard` will sequentially pass through the Root Gateway, and *then* pass through the Admin Gateway!
-
-```text className="language-text"
-src/
-└── http/
-    ├── gateway.ts            <-- Runs first (Global Rate Limits)
-    └── admin/
-        ├── gateway.ts        <-- Runs second (JWT Validation)
-        └── users/
-            └── route.ts      <-- Runs last (Only if both gateways succeed!)
-```
-
-## Extended Features
-
-Gateways provide features to manage cross-cutting concerns like Exception Filters or Guards for an entire folder.
-
-### 1. Folder-Scoped Guards
-
-Apply Authorization Guards directly to a folder. If the guard returns `false`, the entire folder is protected.
-
-#### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-import { RequireAdminRoleGuard } from '../../guards'
-
-export default defineGateway({
-  // Protects the entire /api folder
-  guards: [RequireAdminRoleGuard]
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-import { RequireAdminRoleGuard } from '../../guards'
-
-@Gateway({
-  // Protects the entire /api folder
-  guards: [RequireAdminRoleGuard]
-})
-export default class ApiGateway {}
-```
-
-### 2. Folder-Scoped Exception Filters
-
-Catch exceptions for a specific domain. For example, you can return HTML error pages for `/views`, but standardized JSON errors for `/api`.
-
-#### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-import { ApiVersion2ErrorFilter } from '../../filters'
-
-export default defineGateway({
-  // Catches all exceptions thrown inside /api/*
-  filters: [ApiVersion2ErrorFilter]
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-import { ApiVersion2ErrorFilter } from '../../filters'
-
-@Gateway({
-  // Catches all exceptions thrown inside /api/*
-  filters: [ApiVersion2ErrorFilter]
-})
-export default class ApiGateway {}
-```
-
-### 3. Folder-Scoped Interceptors
-
-Transform or wrap all responses exiting a specific folder.
-
-#### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-import { StandardResponseInterceptor } from '../../interceptors'
-
-export default defineGateway({
-  // Wraps all responses from /api/* in a standard format
-  interceptors: [StandardResponseInterceptor]
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-import { StandardResponseInterceptor } from '../../interceptors'
-
-@Gateway({
-  // Wraps all responses from /api/* in a standard format
-  interceptors: [StandardResponseInterceptor]
-})
-export default class ApiGateway {}
-```
-
-### 4. Bypassing Gateways (Exclude)
-
-Bypass the Gateway's middleware, guards, and filters for specific sub-paths or methods without breaking your folder structure.
-
-#### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-
-export default defineGateway({
-  exclude: [
-    '/api/public/status', // Exact Match
-    '/api/webhooks/*',    // Wildcard Match
-    { path: '/api/users', methods: ['GET'] } // Method-specific bypass
-  ]
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/api/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-
-@Gateway({
-  exclude: [
-    '/api/public/status', // Exact Match
-    '/api/webhooks/*',    // Wildcard Match
-    { path: '/api/users', methods: ['GET'] } // Method-specific bypass
-  ]
-})
-export default class ApiGateway {}
-```
-
-### 5. Dynamic Request Timeouts
-
-Define dynamic, folder-scoped request timeouts. For example, give your `/reports` folder 60 seconds, but restrict `/api` to 5 seconds. You can evaluate the timeout dynamically per-request.
-
-#### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/reports/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-
-export default defineGateway({
-  // Dynamic request timeouts evaluated per-request
-  timeout: (req) => req.headers['x-premium'] ? 30000 : 5000
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/reports/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-
-@Gateway({
-  // Dynamic request timeouts evaluated per-request
-  timeout: (req) => req.headers['x-premium'] ? 30000 : 5000
-})
-export default class ReportsGateway {}
-```
-
-### 6. Cascading Metadata
-
-Define tags (like OpenAPI/Swagger tags or Role definitions) at the folder level that automatically cascade down to every route inside.
-
-#### Functional Paradigm
-
-```typescript className="language-typescript" filename="src/http/admin/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-
-export default defineGateway({
-  // Automatically cascades OpenAPI tags to every route in the folder
-  metadata: {
-    openapi: { tags: ['Admin API'], security: ['bearerAuth'] }
-  }
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript className="language-typescript" filename="src/http/admin/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-
-@Gateway({
-  // Automatically cascades OpenAPI tags to every route in the folder
-  metadata: {
-    openapi: { tags: ['Admin API'], security: ['bearerAuth'] }
-  }
-})
-export default class AdminGateway {}
-```