exisjs 0.5.9 → 0.5.11

package/dist/docs/content/routing.mdx

@@ -0,0 +1,541 @@
+---
+nextUrl: "/docs/controllers"
+nextTitle: "Controllers"
+---
+
+# Routing
+
+Routes are responsible for handling incoming requests and sending responses back to the client. The routing mechanism determines which handler will process each request.
+
+<Info title="Functional vs OOP">
+ExisJS natively supports both a **Functional Paradigm** and a **Class-Based OOP Paradigm** (for dependency injection and decorators). You can mix and match them throughout your application.
+</Info>
+
+## Folder-Based Routing
+
+ExisJS uses **folder-based file-system routing** instead of programmatic route declaration in a single entry file.
+
+For a folder to become an accessible API endpoint, it must contain a `route.ts` file that exports a route definition. 
+
+In addition to `route.ts`, the ExisJS router utilizes two other special gatekeeper files:
+- **`server.ts`**: Placed at the root of your `http` directory, it is the entry point that boots your application, registers global plugins, and connects to databases.
+- **`gateway.ts`**: Can be placed in any folder. It acts as a gatekeeper, automatically applying middleware, CORS, headers, and dependencies to *all* routes within its directory and subdirectories.
+
+### Routing Conventions
+
+The ExisJS file-system router natively supports advanced folder naming conventions to handle dynamic segments and logical grouping:
+
+- **Dynamic Parameters (`[param]`)**: A folder named `[id]` creates a dynamic route segment (e.g., `/:id`). The value is accessible in your handler via `ctx.params.id`.
+- **Catch-all Routes (`[...param]`)**: A folder named `[...slug]` catches all subsequent URL segments, matching anything that follows (e.g., `/*slug`).
+- **Route Groups (`(group)`)**: A folder wrapped in parentheses (e.g., `(admin)`) is ignored in the final URL path. This is useful for grouping related routes or applying shared controller-level middleware without adding `/admin` to the URL.
+
+### The Application Entry Point (`server.ts`)
+
+The `server.ts` file acts as the root configuration for your application. It provides lifecycle hooks to boot databases, register global plugins, and provide root-level dependencies.
+
+#### Functional Paradigm
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+
+export default exis({
+  async onStart(app) {
+    // Boot your database here!
+  }
+})
+```
+
+#### Class-Based (OOP) Paradigm
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import type { App } from 'exisjs'
+
+@Server({
+  providers: [['LoggerService', { useValue: console }]]
+})
+export default class RootServer {
+  async onStart(app: App) {
+    // Boot your database here!
+  }
+}
+```
+
+### Folder Gateways (`gateway.ts`)
+
+Gateways apply configurations to all routes in their directory and subdirectories.
+
+#### Functional Paradigm
+```typescript filename="src/http/admin/gateway.ts"
+import { defineGateway } from 'exisjs/router'
+
+export default defineGateway({
+  headers: { 'X-Admin-Area': 'true' }
+})
+```
+
+#### Class-Based (OOP) Paradigm
+```typescript filename="src/http/admin/gateway.ts"
+import { Gateway } from 'exisjs/decorators'
+
+@Gateway({
+  headers: { 'X-Admin-Area': 'true' }
+})
+export default class AdminGateway {}
+```
+
+### Route Definitions (`route.ts`)
+
+For example, to create a simple `/health` endpoint, you create the folder `src/http/health/` and place a `route.ts` file inside it:
+
+#### Functional Paradigm
+
+
+```typescript filename="src/http/health/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  check: route.get('/', {
+    handle() {
+      return { status: 'ok', timestamp: new Date().toISOString() }
+    }
+  })
+})
+```
+
+  
+#### Class-Based (OOP) Paradigm
+
+
+```typescript filename="src/http/health/route.ts"
+import { Controller, Get } from 'exisjs/decorators'
+
+@Controller()
+export default class HealthController {
+  @Get('/')
+  check() {
+    return { status: 'ok', timestamp: new Date().toISOString() }
+  }
+}
+```
+
+  
+
+## Supported Methods
+
+ExisJS natively exposes standard HTTP methods alongside advanced routing paradigms like WebSockets and Server-Sent Events. Choose your paradigm below to see the available methods.
+
+#### Functional Paradigm
+
+    <div className="overflow-x-auto mb-6">
+      <table className="w-full text-sm text-left border border-border/50 rounded-lg overflow-hidden">
+        <thead className="bg-muted/50 text-foreground">
+          <tr>
+            <th className="px-4 py-3 border-b border-border/50 font-semibold w-1/3">Method</th>
+            <th className="px-4 py-3 border-b border-border/50 font-semibold">Description</th>
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border/50">
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>get() / post() / put()</td>
+            <td className="px-4 py-3 text-muted-foreground">Standard HTTP methods. Also includes patch, delete, options, head, connect, and trace.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>all()</td>
+            <td className="px-4 py-3 text-muted-foreground">Matches any HTTP request method for the given path.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>query()</td>
+            <td className="px-4 py-3 text-muted-foreground">The new experimental HTTP QUERY method, solving complex idempotent fetches.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>ws()</td>
+            <td className="px-4 py-3 text-muted-foreground">Exposes a native WebSocket endpoint with automatic pub/sub support.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">route.</span>sse()</td>
+            <td className="px-4 py-3 text-muted-foreground">Exposes a Server-Sent Events stream for one-way realtime data.</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  list: route.get('/', {
+    handle() {
+      // Fetch all users from database
+      return [
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' }
+      ]
+    }
+  }),
+  create: route.post('/', {
+    handle({ req }) {
+      // Create a new user with parsed payload
+      const payload = req.body
+      return { id: 3, ...payload }
+    }
+  }),
+  preflight: route.options('/', {
+    handle({ res }) {
+      // Handle custom preflight logic if `preflightContinue: true` is configured in CORS
+      res.header('X-Custom-Options', 'true')
+      return { allowed: true }
+    }
+  })
+})
+```
+  
+#### Class-Based (OOP) Paradigm
+
+    <div className="overflow-x-auto mb-6">
+      <table className="w-full text-sm text-left border border-border/50 rounded-lg overflow-hidden">
+        <thead className="bg-muted/50 text-foreground">
+          <tr>
+            <th className="px-4 py-3 border-b border-border/50 font-semibold w-1/3">Decorator</th>
+            <th className="px-4 py-3 border-b border-border/50 font-semibold">Description</th>
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border/50">
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Get() / <span className="text-primary">@</span>Post() / <span className="text-primary">@</span>Put()</td>
+            <td className="px-4 py-3 text-muted-foreground">Standard HTTP methods. Also includes @Patch, @Delete, @Options, @Head, @Connect, and @Trace.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>All()</td>
+            <td className="px-4 py-3 text-muted-foreground">Matches any HTTP request method for the given path.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Query()</td>
+            <td className="px-4 py-3 text-muted-foreground">The new experimental HTTP QUERY method, solving complex idempotent fetches.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Ws()</td>
+            <td className="px-4 py-3 text-muted-foreground">Exposes a native WebSocket endpoint with automatic pub/sub support.</td>
+          </tr>
+          <tr className="bg-background hover:bg-muted/30 transition-colors">
+            <td className="px-4 py-3 font-mono text-xs"><span className="text-primary">@</span>Sse()</td>
+            <td className="px-4 py-3 text-muted-foreground">Exposes a Server-Sent Events stream for one-way realtime data.</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Post, Body } from 'exisjs/decorators'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  list() {
+    // Fetch all users from database
+    return [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' }
+    ]
+  }
+
+  @Post('/')
+  create(@Body() data: any) {
+    // Create a new user with parsed payload
+    return { id: 3, ...data }
+  }
+}
+```
+  
+
+## Sub-Paths in a Single File
+
+While folder-based routing is standard, you can also define multiple sub-paths in a single `route.ts` file to group related endpoints.
+
+#### Functional Paradigm
+
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  list: route.get('/', {
+    handle() {
+      return { message: 'Fetching all users' }
+    }
+  }),
+  getSingle: route.get('/:id', {
+    handle({ params }) {
+      const { id } = params
+      return { message: \`Fetching user \${id}\` }
+    }
+  })
+})
+```
+
+  
+#### Class-Based (OOP) Paradigm
+
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Param } from 'exisjs/decorators'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  list() {
+    return { message: 'Fetching all users' }
+  }
+
+  @Get('/:id')
+  getSingle(@Param('id') id: string) {
+    return { message: \`Fetching user \${id}\` }
+  }
+}
+```
+
+  
+
+## Route Parameters (Dynamic Routing)
+
+Routes with static paths won’t work when you need to accept dynamic data as part of the request (e.g., `GET /users/123`). To create dynamic routes using folders, enclose the folder name in brackets `[]`.
+
+#### Functional Paradigm
+
+
+```typescript filename="src/http/users/[id]/route.ts"
+// Location: src/http/users/[id]/route.ts
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  getSingle: route.get('/', {
+    handle({ params }) {
+      const { id } = params
+      return { message: \`Fetching user \${id}\` }
+    }
+  })
+})
+```
+
+  
+#### Class-Based (OOP) Paradigm
+
+
+```typescript filename="src/http/users/[id]/route.ts"
+// Location: src/http/users/[id]/route.ts
+import { Controller, Get, Param } from 'exisjs/decorators'
+
+@Controller()
+export default class SingleUserController {
+  @Get('/')
+  getSingle(@Param('id') id: string) {
+    return { message: \`Fetching user \${id}\` }
+  }
+}
+```
+
+  
+
+## Request & Response Objects
+
+Handlers often need access to the client’s request details, or fine-grained control over the response headers and status codes. Every route handler natively receives powerful `req` and `res` objects.
+
+#### Functional Paradigm
+
+
+```typescript filename="src/http/profile/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  profile: route.get('/profile', {
+    handle({ req, res }) {
+      // Read Request details
+      const ip = req.ip
+      const headers = req.headers
+
+      // Chain Response methods
+      res
+        .status(202)
+        .cookie('session', 'xyz123', { httpOnly: true, secure: true })
+        .header('X-Custom-Header', 'Exis')
+        .json({ message: 'Accepted' })
+    }
+  })
+})
+```
+
+  
+#### Class-Based (OOP) Paradigm
+
+
+```typescript filename="src/http/profile/route.ts"
+import { Controller, Get, Req, Res } from 'exisjs/decorators'
+import type { Request, Response } from 'exisjs/router'
+
+@Controller()
+export default class ProfileController {
+  @Get('/profile')
+  profile(@Req() req: Request, @Res() res: Response) {
+    // Read Request details
+    const ip = req.ip
+    const headers = req.headers
+
+    // Chain Response methods
+    res
+      .status(202)
+      .cookie('session', 'xyz123', { httpOnly: true, secure: true })
+      .header('X-Custom-Header', 'Exis')
+      .json({ message: 'Accepted' })
+  }
+}
+```
+
+  
+
+<Info title="Default Responses">
+When a request handler returns a JavaScript object or array, it is automatically serialized to JSON and sent with a default `200 OK` status code. You only need to use the `res` object when you want to explicitly modify headers, cookies, or status codes!
+</Info>
+
+## Payloads & Query Parameters
+
+You can easily extract query strings from the URL or parsed JSON bodies from POST requests directly through the `req` object (or via decorators in OOP).
+
+#### Functional Paradigm
+
+
+```typescript filename="src/http/search/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  search: route.get('/search', {
+    handle({ req }) {
+      // e.g., GET /search?q=exis&limit=10
+      const { q, limit } = req.query
+      return { query: q, limit }
+    }
+  }),
+  create: route.post('/create', {
+    handle({ req }) {
+      // Access parsed JSON body natively
+      const data = req.body
+      return { received: data }
+    }
+  })
+})
+```
+
+  
+#### Class-Based (OOP) Paradigm
+
+
+```typescript filename="src/http/search/route.ts"
+import { Controller, Get, Post, Query, Body } from 'exisjs/decorators'
+
+@Controller()
+export default class SearchController {
+  @Get('/search')
+  search(@Query('q') q: string, @Query('limit') limit: number) {
+    // e.g., GET /search?q=exis&limit=10
+    return { query: q, limit }
+  }
+
+  @Post('/create')
+  create(@Body() data: any) {
+    // Access parsed JSON body natively
+    return { received: data }
+  }
+}
+```
+
+  
+
+## Dependency Injection in Functional Controllers
+
+ExisJS natively supports **Request-Scoped Dependency Injection** directly inside functional routes. You don't need to use classes to get the benefits of DI!
+
+By destructuring `resolve` from the context, you can dynamically fetch services without relying on global imports. This perfectly solves the "Fat Handler" problem by encouraging you to abstract business logic into clean Service classes, and makes unit testing incredibly easy.
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { UsersService } from './service'
+
+export default controller({
+  list: route.get('/', {
+    async handle({ resolve }) {
+      // 1. Resolves UsersService from the IoC Container
+      // 2. Maintains request-scope (the same instance is returned throughout this HTTP request)
+      const usersService = resolve(UsersService)
+      
+      return usersService.getAll()
+    }
+  })
+})
+```
+
+## The Context API (Advanced)
+
+For applications where passing `(req, res)` arguments through multiple service layers becomes tedious, ExisJS offers a Next.js-inspired approach: **The Context API**. Powered by Node.js `AsyncLocalStorage`, ExisJS provides hooks to access the current request state from anywhere in the execution context.
+
+#### Functional Paradigm
+
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route, getContext, getRequest, getResponse, after } from 'exisjs/router'
+
+export default controller({
+  create: route.post('/', {
+    async handle() {
+      // Access request/response without prop-drilling
+      const req = getRequest()
+      const res = getResponse()
+      
+      // Access data injected by gateways
+      const { userId } = getContext<{ userId: string }>()
+      
+      // Run background tasks after sending response to client
+      after(async () => {
+        await sendNotificationEmail(userId)
+      })
+
+      res.status(201)
+      return { success: true }
+    }
+  })
+})
+```
+
+  
+#### Class-Based (OOP) Paradigm
+
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post } from 'exisjs/decorators'
+import { getContext, getRequest, getResponse, after } from 'exisjs/router'
+
+@Controller()
+export default class OrdersController {
+  @Post('/')
+  async create() {
+    // You can still use the Context API seamlessly in OOP classes!
+    const req = getRequest()
+    const res = getResponse()
+    const { userId } = getContext<{ userId: string }>()
+    
+    after(async () => {
+      await sendNotificationEmail(userId)
+    })
+
+    res.status(201)
+    return { success: true }
+  }
+}
+```
+
+  
+
+## Modular Architecture
+
+While putting all logic in `route.ts` is fine for small apps, ExisJS strongly encourages separating concerns alongside your route definition:
+
+- **`schema.ts`**: Defines expected input validation constraints.
+- **`service.ts`**: Pure functions that interact with your database.
+- **`controller.ts`**: Handles business orchestration.
+- **`route.ts`**: Wires it to the HTTP network.

package/dist/docs/content/rpc.mdx

@@ -0,0 +1,146 @@
+---
+nextUrl: "/docs/decorators"
+nextTitle: "Custom Decorators"
+---
+
+# RPC Client (End-to-End Type Safety)
+
+ExisJS comes with a native RPC (Remote Procedure Call) client designed to give you **end-to-end type safety** without needing code generation (like OpenAPI/Swagger) or GraphQL. 
+
+Because ExisJS infers the types of your backend routes natively, you can share those types directly with your frontend (React, Vue, React Native) and get autocomplete, payload validation, and response typing.
+
+---
+
+## 1. Exporting the AppRouter Type
+
+To use the strictly typed client, you simply need to export the inferred type of your ExisJS application from your main backend entry point.
+
+```typescript filename="backend/src/http/server.ts"
+import { exis } from 'exisjs'
+
+const app = exis({
+  async onStart(app) {
+    // Backend boot logic...
+  }
+})
+
+// Export the inferred router type for the frontend
+export type AppRouter = typeof app
+
+export default app
+```
+
+*(Note: Because this is just a TypeScript `type` export, no backend code gets compiled into your frontend bundle.)*
+
+---
+
+## 2. Initializing the Client
+
+On your frontend (React, Vue, Svelte, etc.), install the lightweight client package:
+
+```bash
+npm install @exisjs/client
+```
+
+Then, initialize the client using the `AppRouter` type from your backend:
+
+```typescript filename="frontend/src/api.ts"
+import { createClient } from '@exisjs/client'
+import type { AppRouter } from '../../backend/src/http/server'
+
+export const client = createClient<AppRouter>({
+  baseUrl: 'http://localhost:3000',
+  
+  // Optionally provide default headers (like Auth tokens)
+  headers: () => ({
+    'Authorization': `Bearer ${localStorage.getItem('token')}`
+  }),
+
+  // Global error handler
+  onError: (err) => {
+    if (err.status === 401) {
+      window.location.href = '/login'
+    }
+  }
+})
+```
+
+---
+
+## 3. Using the Client
+
+Because ExisJS uses an ES6 `Proxy` under the hood, the client dynamically maps your chained object calls into HTTP requests. It mirrors your backend's folder structure.
+
+If you have a backend route at `src/http/api/users/route.ts` with a `get` handler:
+
+```typescript filename="frontend/src/components/UserProfile.tsx"
+import { client } from '../api'
+
+async function fetchUser() {
+  // 1. Autocomplete for .api.users.get
+  // 2. Strong typing for the payload (e.g. { id: string })
+  // 3. The `user` variable is strictly typed to whatever the backend returns
+  const user = await client.api.users.get({
+    id: "123"
+  })
+  
+  console.log(user.name) 
+}
+```
+
+### Passing Query Parameters
+
+If you need to pass HTTP query parameters (like `?sort=desc`), you can use the `options` argument (the second parameter):
+
+```typescript filename="frontend/src/components/UserList.tsx"
+const users = await client.api.users.get(
+  // The first argument is the JSON payload (Body/Params)
+  {}, 
+  // The second argument configures the Request Options
+  { 
+    query: { sort: 'desc', limit: 10 },
+    headers: { 'X-Custom-Override': 'true' }
+  }
+)
+```
+
+---
+
+## 4. Advanced Configuration
+
+The `createClient` function accepts configuration options to intercept requests and responses globally.
+
+```typescript
+export interface ClientConfig {
+  // The base URL of your ExisJS backend
+  baseUrl: string
+  
+  // Static headers, or a dynamic function evaluated per-request
+  headers?: Record<string, string> | (() => Record<string, string>)
+  
+  // Provide a custom fetch implementation (useful for testing or Polyfills)
+  fetch?: typeof fetch
+  
+  // A global hook that runs BEFORE the request is dispatched
+  onRequest?: (req: RequestInit, url: string) => void | Promise<void>
+  
+  // A global hook that runs AFTER the request successfully completes
+  onResponse?: (res: Response, url: string) => void | Promise<void>
+  
+  // A global hook that catches any failed requests
+  onError?: (err: Error) => void | Promise<void>
+}
+```
+
+### ExisClientError
+
+If an HTTP request fails (e.g., the backend returns a `400 Bad Request` or `500 Internal Server Error`), the client throws an `ExisClientError`. This error attaches the status code and parsed JSON response.
+
+```typescript
+try {
+  await client.api.users.post({ email: "invalid-email" })
+} catch (err) {
+  console.log(err.status) // 400
+  console.log(err.data) // { success: false, error: "Validation Failed..." }
+}
+```