exisjs 0.5.9 → 0.5.11

package/dist/docs/content/adapters.mdx

@@ -0,0 +1,199 @@
+---
+nextUrl: "/"
+nextTitle: "Back to Home"
+---
+
+# Adapters & Serverless
+
+ExisJS was engineered using modern web standards (Fetch API, Request/Response patterns). Because of this, ExisJS can run across various JavaScript runtimes.
+
+To deploy your ExisJS application to serverless or edge environments, you simply wrap your `app` with the corresponding adapter from `exisjs/adapters`.
+
+Every adapter handles **lazy initialization** automatically—your routes, plugins, and lifecycle hooks (`onStart`) are bootstrapped on the very first incoming request (cold start), so you never have to worry about manual setup in serverless environments.
+
+---
+
+## Available Adapters
+
+| Adapter | Import | Environment |
+|---------|--------|-------------|
+| `vercel` | `exisjs/adapters` | Vercel Serverless Functions |
+| `aws` | `exisjs/adapters` | AWS Lambda + API Gateway |
+| `cloudflare` | `exisjs/adapters` | Cloudflare Workers |
+| `netlify` | `exisjs/adapters` | Netlify Edge Functions |
+| `deno` | `exisjs/adapters` | Deno Deploy / Deno.serve |
+| `bun` | `exisjs/adapters` | Bun.serve |
+| `fastly` | `exisjs/adapters` | Fastly Compute@Edge |
+
+> [!WARNING]
+> **Edge Limitations**: When deploying to Edge runtimes (Cloudflare Workers, Vercel Edge, Netlify Edge, Fastly), some Node.js specific features will not function. Specifically:
+> - **Queues & Cron**: Background jobs and scheduled tasks require a long-running process and are unsupported on Edge.
+> - **WebSockets**: State-heavy WebSockets are not supported via the standard Edge Fetch adapters.
+> - **FileSystem Cache**: `FileSystemCacheStore` cannot write to a filesystem on Edge. You must configure a `RedisCacheStore` if you need caching on the Edge.
+
+---
+
+## Vercel
+
+To deploy an ExisJS app to Vercel, create an `api/index.js` entrypoint that wraps your app with the `vercel` adapter.
+
+```javascript filename="api/index.js"
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { vercel } from "exisjs/adapters";
+
+const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// We use a dynamic import with a file URL to prevent Vercel's bundler (@vercel/node)
+// from statically cloning dependencies (like Mongoose) into the entrypoint.
+// This ensures your dynamic routes and server use the exact same module instances.
+const serverPath = join(projectRoot, ".exis", "server", "src", "http", "server.js");
+const { default: app } = await import("file://" + serverPath);
+
+export default vercel(app, { cwd: projectRoot });
+```
+
+Then configure `vercel.json` to route all traffic to this function and bundle the compiled `.exis` directory:
+
+```json filename="vercel.json"
+{
+  "version": 2,
+  "buildCommand": "npm run build",
+  "functions": {
+    "api/index.js": {
+      "includeFiles": ".exis/**/*"
+    }
+  },
+  "rewrites": [
+    { "source": "/(.*)", "destination": "/api/index" }
+  ]
+}
+```
+
+> **Note:** ExisJS compiles your application into the `.exis/` directory during `exisjs build`. The `includeFiles` configuration ensures Vercel bundles these compiled files alongside your serverless function. You also need a `public/` directory (even an empty one with a `.keep` file) to prevent Vercel's missing output directory error.
+
+---
+
+## AWS Lambda
+
+Deploying an ExisJS API as an AWS Lambda function (behind API Gateway) takes one line of code. The `aws` adapter converts API Gateway events into native Node.js HTTP streams that ExisJS understands.
+
+```typescript filename="src/lambda.ts"
+import app from './http/server'
+import { aws } from 'exisjs/adapters'
+
+// Export the AWS Lambda handler
+export const handler = aws(app)
+```
+
+The adapter automatically handles:
+- Mapping `httpMethod`, `path`, and `queryStringParameters` from API Gateway events
+- Converting headers and request bodies
+- Collecting the response stream and returning a properly formatted `APIGatewayResult`
+- Base64 encoding for binary responses
+
+---
+
+## Cloudflare Workers
+
+ExisJS works on Cloudflare Workers using the Web Standard Fetch API.
+
+```typescript filename="src/worker.ts"
+import app from './http/server'
+import { cloudflare } from 'exisjs/adapters'
+
+export default cloudflare(app)
+```
+
+The adapter returns an object with a `fetch` method that Cloudflare Workers expects. Your `env` and `ctx` (execution context) are automatically passed through to your route handlers.
+
+---
+
+## Netlify
+
+Netlify Edge Functions use the Web Standard Fetch API, which ExisJS supports.
+
+```typescript filename="netlify/edge-functions/api.ts"
+import app from '../../src/http/server'
+import { netlify } from 'exisjs/adapters'
+
+export default netlify(app)
+```
+
+The adapter wraps your app and passes both the incoming `Request` and Netlify's `Context` object through to ExisJS.
+
+---
+
+## Deno
+
+Deno natively supports the Web Standard Fetch API, so ExisJS runs on it without any compatibility layers.
+
+```typescript filename="src/main.ts"
+import app from './http/server'
+import { deno } from 'exisjs/adapters'
+
+Deno.serve({ port: 8000 }, deno(app))
+```
+
+---
+
+## Bun
+
+Bun provides a native HTTP server. The `bun` adapter ties directly into Bun's `serve` function.
+
+```typescript filename="src/main.ts"
+import app from './http/server'
+import { bun } from 'exisjs/adapters'
+
+Bun.serve({
+  port: 3000,
+  ...bun(app)
+})
+```
+
+---
+
+## Fastly Compute@Edge
+
+Fastly's Compute@Edge platform runs your code at the network edge. The `fastly` adapter integrates with Fastly's event-driven model.
+
+```typescript filename="src/index.ts"
+import app from './http/server'
+import { fastly } from 'exisjs/adapters'
+
+addEventListener('fetch', fastly(app))
+```
+
+---
+
+## The Fetch Adapter (Building Custom Adapters)
+
+Under the hood, ExisJS provides a universal **Fetch adapter** (`handleFetch`) that bridges the gap between the Web Standard `Request`/`Response` API and ExisJS's internal Node.js-style request pipeline.
+
+Every edge/serverless adapter (Cloudflare, Deno, Bun, Netlify, Fastly) ultimately calls `app.fetch()`, which internally uses `handleFetch` to:
+
+1. **Convert** a Web Standard `Request` into a Node.js-compatible `IncomingMessage` (via `FetchIncomingMessage`)
+2. **Route** the request through ExisJS's full middleware and routing pipeline
+3. **Collect** the response and convert it back into a Web Standard `Response` (via `FetchServerResponse`)
+
+This means you can create your own custom adapter for **any** runtime that supports the Fetch API:
+
+```typescript filename="src/my-custom-adapter.ts"
+import app from './http/server'
+
+// app.fetch() works anywhere that has the Web Standard Request/Response API
+const server = createMyCustomServer({
+  async handler(request: Request): Promise<Response> {
+    return app.fetch(request)
+  }
+})
+```
+
+The `app.fetch()` method accepts an optional `env` and `ctx` parameter, which are passed through to your route handlers—allowing platform-specific features (like Cloudflare's KV bindings or Deno's connection info) to be accessed from within your ExisJS routes.
+
+```typescript
+// Signature
+app.fetch(request: Request, env?: any, ctx?: any): Promise<Response>
+```
+
+This architecture ensures that ExisJS remains portable. Your application code stays the same—only the deployment wrapper changes.

package/dist/docs/content/cache.mdx

@@ -0,0 +1,239 @@
+---
+nextUrl: "/docs/dataloader"
+nextTitle: "Dataloader"
+---
+
+# Route Caching
+
+ExisJS comes with a built-in Caching Engine. It provides Next.js-style **Tag-based Revalidation** directly in your backend API.
+
+By default, ExisJS uses a local File System cache (`.exis/cache`), meaning you get persistent, server-side caching with **zero configuration** required. 
+
+---
+
+## 1. Basic Route Caching
+
+To cache an endpoint, simply attach the `cache()` middleware to it. By default, it will cache `GET` requests based on the URL path.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/products/route.ts"
+import { controller, route } from 'exisjs/router'
+import { cache } from 'exisjs/middleware'
+
+export default controller({
+  // Cache this route for 60 seconds (60,000 milliseconds)
+  list: route.get('/', {
+    middlewares: [cache({ ttlMs: 60000 })],
+    handle(req, res) {
+      // This database query only runs once a minute
+      const products = await db.products.findMany()
+      return products
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/products/route.ts"
+import { Controller, Get, Use } from 'exisjs/decorators'
+import { cache } from 'exisjs/middleware'
+
+@Controller()
+export default class ProductsController {
+  // Cache this route for 60 seconds (60,000 milliseconds)
+  @Use(cache({ ttlMs: 60000 }))
+  @Get('/')
+  async list() {
+    // This database query only runs once a minute
+    const products = await db.products.findMany()
+    return products
+  }
+}
+```
+
+When a user hits this route:
+1. The first request takes full execution time. ExisJS automatically intercepts the response and writes it to the local cache. The response header `X-Exis-Cache: MISS` is set.
+2. The next 10,000 requests over the next minute hit the cache instantly without running your handler. The response header `X-Exis-Cache: HIT` is set.
+
+---
+
+## 2. Dynamic Cache Keys
+
+By default, the cache key is the exact request path (`req.path`). But what if your response depends on a user's language, or a query parameter? You can customize the key generation logic.
+
+```typescript
+cache({
+  ttlMs: 60000,
+  keyGenerator: (req) => {
+    // Cache separately for English vs French users
+    const lang = req.query.lang || 'en'
+    return `${req.path}?lang=${lang}`
+  }
+})
+```
+
+> [!WARNING]
+> **Authentication Leak Hazard**: When using `cache()` on authenticated routes, you **must** include the user's ID or session token in your `keyGenerator`. Failing to do so will result in User B receiving a cached response generated for User A.
+
+```typescript
+cache({
+  ttlMs: 60000,
+  keyGenerator: (req) => {
+    // SAFE: The cache key includes the user ID
+    return `${req.path}?user=${req.user?.id}`
+  }
+})
+```
+
+---
+
+## 3. Tag-Based Revalidation (On-Demand)
+
+Time-based caching (`ttlMs`) is great, but what if a product's price changes and you want to instantly invalidate the cache? 
+
+ExisJS allows you to assign **tags** to your cached responses.
+
+### Step 1: Assign a Tag
+
+#### Functional Paradigm
+
+```typescript filename="src/http/products/route.ts"
+import { controller, route } from 'exisjs/router'
+import { cache } from 'exisjs/middleware'
+
+export default controller({
+  list: route.get('/', {
+    middlewares: [
+      cache({ 
+        // We assign the 'products-list' tag to this cached route
+        tags: ['products-list'] 
+      })
+    ],
+    async handle(req, res) {
+      return await db.products.findMany()
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/products/route.ts"
+import { Controller, Get, Use } from 'exisjs/decorators'
+import { cache } from 'exisjs/middleware'
+
+@Controller()
+export default class ProductsController {
+  @Use(cache({ tags: ['products-list'] }))
+  @Get('/')
+  async list() {
+    return await db.products.findMany()
+  }
+}
+```
+
+### Step 2: Invalidate the Tag
+
+Now, inside an admin route or webhook where a product is updated, you can instantly purge the cache using `revalidateTag()`.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/admin/products/route.ts"
+import { controller, route } from 'exisjs/router'
+import { revalidateTag } from 'exisjs/cache'
+
+export default controller({
+  update: route.post('/:id', {
+    async handle(req, res) {
+      // 1. Update the product in the database
+      await db.products.update(req.params.id, req.body)
+
+      // 2. Instantly purge all routes cached with 'products-list'
+      await revalidateTag('products-list')
+
+      return { success: true }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/admin/products/route.ts"
+import { Controller, Post, Param, Body } from 'exisjs/decorators'
+import { revalidateTag } from 'exisjs/cache'
+
+@Controller()
+export default class AdminProductsController {
+  @Post('/:id')
+  async update(@Param('id') id: string, @Body() body: any) {
+    // 1. Update the product in the database
+    await db.products.update(id, body)
+
+    // 2. Instantly purge all routes cached with 'products-list'
+    await revalidateTag('products-list')
+
+    return { success: true }
+  }
+}
+```
+
+Dynamic tags are also supported by passing a function to `tags`:
+```typescript
+cache({
+  tags: (req) => [`product-${req.params.id}`]
+})
+```
+
+---
+
+## 4. Custom Cache Stores (Redis)
+
+By default, ExisJS uses the local File System (`.exis/cache`) to store responses. This works well for single-server setups. 
+
+If you are deploying horizontally across a cluster (e.g. Kubernetes, AWS ECS) or Serverless (AWS Lambda), you will want a distributed cache. ExisJS exposes the `CacheStore` interface, making it possible to plug in Redis.
+
+*(Note: The official `exisjs/redis` integration provides a Redis Cache Store out of the box, which we will cover in the Integrations documentation.)*
+
+---
+
+## 5. API Reference (`exisjs/cache`)
+
+For advanced use-cases, you can import several utilities directly from the `exisjs/cache` package. Here is the full list of what is exported and how to use it:
+
+### `revalidateTag(tag: string)`
+Purges all cached responses associated with a specific tag. 
+```typescript
+import { revalidateTag } from 'exisjs/cache'
+await revalidateTag('products-list')
+```
+
+### `setCacheStore(store: CacheStore)`
+Allows you to globally override the default file-system cache with a custom distributed cache (like Redis or Memcached). This is typically done once in your `server.ts` or `exis.config.ts`.
+```typescript
+import { setCacheStore } from 'exisjs/cache'
+import { RedisCacheStore } from 'exisjs/redis'
+
+setCacheStore(new RedisCacheStore(process.env.REDIS_URL))
+```
+
+### `getCacheStore(): CacheStore`
+Retrieves the currently active cache store. Useful if you want to manually read/write to the cache outside of the middleware layer.
+```typescript
+import { getCacheStore } from 'exisjs/cache'
+
+const store = getCacheStore()
+await store.set('/custom-key', { data: 'hello' }, [], 60000)
+```
+
+### Interfaces & Classes
+If you are building your own Custom Cache Store, ExisJS exports the required interfaces:
+- `CacheStore`: The interface you must implement (`get`, `set`, `revalidateTag`, `getTags`).
+- `CacheItem`: The expected shape of a cached response (`data`, `tags`, `createdAt`).
+- `FileSystemCacheStore`: The default implementation used by the framework (safe for multi-process cluster mode).
+- `MemoryCacheStore`: An in-memory implementation.
+
+> [!IMPORTANT]
+> **MemoryCacheStore Cluster Limitations**: The `MemoryCacheStore` is strictly process-local. If you are running in cluster mode (`workers > 1`) or multi-instance deployments, calling `revalidateTag()` on one worker will **not** invalidate the cache held in memory by sibling workers. For any multi-process setup, use `FileSystemCacheStore` (for a single server) or `RedisCacheStore` (for multiple servers).

package/dist/docs/content/circuit-breaker.mdx

@@ -0,0 +1,130 @@
+---
+nextUrl: "/docs/responses"
+nextTitle: "Responses"
+---
+
+# Circuit Breaker
+
+Microservices and external APIs fail. It is a reality of distributed systems. When an external service goes down, continuing to send it traffic can cause cascading failures across your entire infrastructure as requests queue up and connection pools are exhausted.
+
+ExisJS ships with a native **Circuit Breaker** pattern built into the core framework. It automatically detects failures and "trips" the circuit, rejecting subsequent requests so your system can recover.
+
+---
+
+## 1. How It Works
+
+The ExisJS Circuit Breaker operates as a state machine with three states:
+
+1. **`CLOSED`** (Normal): The circuit is closed, and traffic flows normally.
+2. **`OPEN`** (Failing): The failure threshold has been reached. The circuit is tripped, and all requests are rejected with a `CircuitBreakerError` to protect the system.
+3. **`HALF_OPEN`** (Testing Recovery): After a timeout period, the circuit allows exactly *one* request through. If it succeeds, the circuit resets to `CLOSED`. If it fails, it trips back to `OPEN`.
+
+---
+
+## 2. Basic Usage
+
+To protect an external API or a database query, wrap the call inside the `CircuitBreaker.fire()` method.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/payment/route.ts"
+import { controller, route } from 'exisjs/router'
+import { CircuitBreaker } from 'exisjs'
+
+// 1. Initialize the Circuit Breaker outside the route handler
+const stripeCircuit = new CircuitBreaker({
+  failureThreshold: 5,     // Trip after 5 consecutive failures
+  resetTimeoutMs: 10000,   // Wait 10 seconds before testing recovery
+})
+
+export default controller({
+  charge: route.post('/charge', {
+    async handle(req, res) {
+      try {
+        // 2. Wrap your logic inside .fire()
+        const result = await stripeCircuit.fire(async () => {
+          // If this throws an error 5 times, the circuit trips
+          return await fetch('https://api.stripe.com/v1/charges', {
+            method: 'POST',
+            body: JSON.stringify(req.body)
+          })
+        })
+
+        return { success: true, data: result }
+        
+      } catch (err) {
+        if (err.name === 'CircuitBreakerError') {
+          // Fast-fail response without hanging the server
+          res.status(503).json({ error: "Payment gateway is currently overloaded. Please try again later." })
+        } else {
+          res.status(500).json({ error: "Payment failed" })
+        }
+      }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/payment/route.ts"
+import { Controller, Post, Body, Res } from 'exisjs/decorators'
+import { CircuitBreaker } from 'exisjs'
+
+// 1. Initialize the Circuit Breaker outside the controller
+const stripeCircuit = new CircuitBreaker({
+  failureThreshold: 5,     // Trip after 5 consecutive failures
+  resetTimeoutMs: 10000,   // Wait 10 seconds before testing recovery
+})
+
+@Controller()
+export default class PaymentController {
+  @Post('/charge')
+  async charge(@Body() body: any, @Res() res: any) {
+    try {
+      // 2. Wrap your logic inside .fire()
+      const result = await stripeCircuit.fire(async () => {
+        // If this throws an error 5 times, the circuit trips
+        return await fetch('https://api.stripe.com/v1/charges', {
+          method: 'POST',
+          body: JSON.stringify(body)
+        })
+      })
+
+      return { success: true, data: result }
+      
+    } catch (err: any) {
+      if (err.name === 'CircuitBreakerError') {
+        // Fast-fail response without hanging the server
+        res.status(503).json({ error: "Payment gateway is currently overloaded. Please try again later." })
+      } else {
+        res.status(500).json({ error: "Payment failed" })
+      }
+    }
+  }
+}
+```
+
+---
+
+## 3. Configuration Options
+
+When instantiating `new CircuitBreaker(options)`, you can configure:
+
+- **`failureThreshold`** *(number)*: The number of consecutive failures before the circuit state transitions from `CLOSED` to `OPEN`. Default: `5`.
+- **`resetTimeoutMs`** *(number)*: The time in milliseconds to wait before transitioning from `OPEN` to `HALF_OPEN` to test recovery. Default: `10000` (10 seconds).
+
+---
+
+## API Reference (`exisjs`)
+
+You can import the following from the root `exisjs` package:
+
+### `CircuitBreaker`
+The main class. Use `new CircuitBreaker(options)` to instantiate a state machine.
+
+### `CircuitBreakerError`
+The native error class thrown when the circuit is `OPEN` or `HALF_OPEN` (while a probe is already in-flight). You can check `err.name === 'CircuitBreakerError'` or `err instanceof CircuitBreakerError`.
+
+### `CircuitState`
+An enum containing the exact states (`CLOSED`, `OPEN`, `HALF_OPEN`) if you need to manually inspect the breaker's current condition via `circuit.state`.