exisjs 0.6.0 → 0.7.0

package/dist/docs/content/cache.mdx

@@ -1,239 +0,0 @@
----
-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

@@ -1,130 +0,0 @@
----
-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`.

package/dist/docs/content/cron.mdx

@@ -1,109 +0,0 @@
----
-nextUrl: "/docs/rpc"
-nextTitle: "RPC Client"
----
-
-# Cron Jobs
-
-ExisJS ships with a distributed Cron Scheduler. Because the cron engine is integrated with the [Job Queue](/docs/queues) system, you can turn any standard background job into a recurring cron task with a single line of code.
-
----
-
-## 1. Defining a Cron Job
-
-To schedule a recurring task, add the `cron` property to any Job definition (`defineJob`) or inline `queue()` handler using standard 5-part cron syntax (`minute hour day month day-of-week`).
-
-### Using `defineJob`
-```typescript filename="src/jobs/cleanup.ts"
-import { defineJob } from 'exisjs/queue'
-
-export default defineJob({
-  name: 'database-cleanup',
-  // Run this job at exactly 2:00 AM every single day
-  cron: '0 2 * * *', 
-  
-  async handler(job) {
-    console.log("Running daily database cleanup...")
-    await db.users.deleteInactive()
-  }
-})
-```
-
-### Using Inline Handlers (`queue`)
-If you prefer functional programming, you can define recurring jobs right alongside your application setup:
-
-```typescript filename="src/http/server.ts"
-import { queue } from 'exisjs/queue'
-
-queue('sync-metrics', async () => {
-  console.log("Syncing metrics to data warehouse...")
-}, {
-  cron: '*/15 * * * *', // Run every 15 minutes
-  defaultOptions: { attempts: 3 }
-})
-```
-
----
-
-## 2. Distributed Locking (Cluster Safe)
-
-In modern web architecture, you rarely run a single NodeJS process. If you run your application across 10 load-balanced servers, a traditional `setInterval` or standard node-cron library would execute your scheduled task 10 times simultaneously.
-
-ExisJS solves this natively through **Distributed Locking**.
-
-When you configure your Queue system to use the `redis` driver, the ExisJS Cron Scheduler automatically utilizes a `SETNX` (Set if Not Exists) Redis lock.
-
-### How it works:
-1. Every 60 seconds, all 10 of your servers will attempt to trigger the cron job.
-2. The *very first* server to hit Redis acquires a 55-second lock for that specific minute.
-3. The other 9 servers see the lock and silently skip execution.
-4. The winning server instantly enqueues the job into the standard ExisJS Queue.
-
-This guarantees that **your cron job will only execute exactly once per minute**, regardless of how many servers or Docker containers you spin up.
-
----
-
-## 3. Supported Cron Syntax
-
-ExisJS implements a integrated cron parser that supports all standard operations:
-
-- `*` - Any value (e.g., run every minute)
-- `,` - Value list (e.g., `1,15,30` to run on the 1st, 15th, and 30th minute)
-- `-` - Value range (e.g., `1-5` to run from Monday to Friday)
-- `/` - Step values (e.g., `*/10` to run every 10 minutes)
-
-**Examples:**
-- `* * * * *`: Every minute
-- `*/5 * * * *`: Every 5 minutes
-- `0 0 * * *`: Every day at midnight
-- `0 9 * * 1-5`: At 9:00 AM on Monday through Friday
-- `0 12 1,15 * *`: At 12:00 PM on the 1st and 15th of every month
-
----
-
-## 4. Important Considerations
-
-### Empty Payloads
-Because cron jobs are triggered by the system clock rather than a user action, they are always dispatched with an empty payload (`{}`). Your job handler should not expect dynamic data to be passed into the `data` property when triggered via cron.
-
-### Retries & Error Handling
-Cron jobs are standard background jobs under the hood. This means they fully support your `defaultOptions`. If a cron job throws an error, it will automatically be retried according to the `attempts` and `backoff` settings defined in the job.
-
-```typescript filename="src/jobs/cleanup.ts"
-export default defineJob({
-  name: 'database-cleanup',
-  cron: '0 2 * * *', 
-  defaultOptions: {
-    attempts: 3,
-    backoff: { type: 'exponential', delay: 5000 }
-  },
-  async handler(job) {
-    // If this fails, it will retry 3 times, backing off exponentially
-  }
-})
-```
-
-### Redis Requirement
-Because ExisJS is designed for cluster-safe, distributed deployments, **the Cron Scheduler strictly requires the `redis` queue driver**. 
-
-If you attempt to run a cron job while using the `memory` driver, ExisJS will skip execution and log an error. This is a deliberate design choice to prevent you from accidentally triggering scheduled jobs multiple times simultaneously across a load-balanced cluster.