exisjs 0.5.9 → 0.5.11

package/dist/docs/content/gateways.mdx

@@ -0,0 +1,376 @@
+---
+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!)
+```
+
+## Advanced 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 {}
+```

package/dist/docs/content/installation.mdx

@@ -0,0 +1,210 @@
+---
+nextUrl: '/docs/structure'
+nextTitle: 'Project Structure'
+---
+
+# Getting Started
+
+In this guide, you'll learn the core fundamentals of ExisJS. To get familiar with the essential building blocks, we'll scaffold a new project, explore the file structure, and create our very first API server.
+
+<Info title="Language Support">
+  We recommend **TypeScript** for type-safety and automatic frontend client generation. However, ExisJS fully supports vanilla JavaScript as well. ExisJS leverages esbuild under the hood, meaning you do not need to manually run `tsc` to start your server.
+</Info>
+
+## Prerequisites
+
+Please make sure that **Node.js (version >= 20)** is installed on your operating system.
+
+## Setup
+
+Setting up a new project can be done using our CLI tool. Open your terminal and run the following command to scaffold a new ExisJS project:
+
+<div className="my-6 max-w-lg">
+  <CopyCommand command="npx @exisjs/create@latest my-backend" />
+</div>
+
+The CLI will prompt you with a few simple questions to customize your project:
+
+```text filename="Terminal"
+√ Would you like to use TypeScript? ... No / Yes
+√ Would you like to use ESLint? ... No / Yes
+√ Would you like your code inside a `src/` directory? ... No / Yes
+√ Would you like to customize the import alias (`@/*` by default)? ... No / Yes
+
+Creating a new Exis JS app in my-backend.
+```
+
+The CLI will then create the `my-backend` directory, install all required dependencies, and populate the project with a conventional base structure.
+
+## Core Files
+
+Once the installation is complete, your project directory will look something like this:
+
+<div className="bg-muted/30 border border-border/50 rounded-md p-4 mb-6 font-mono text-sm">
+  <div className="flex gap-4 mb-2">
+    <span className="text-muted-foreground w-40 shrink-0">exis.config.ts</span>{' '}
+    <span>
+      The root configuration for your application (CORS, Logger, Port).
+    </span>
+  </div>
+  <div className="flex gap-4 mb-2">
+    <span className="text-muted-foreground w-40 shrink-0">src/env.ts</span>{' '}
+    <span>Environment variable validation and typing.</span>
+  </div>
+  <div className="flex gap-4 mb-2">
+    <span className="text-muted-foreground w-40 shrink-0">src/http/</span>{' '}
+    <span>The file-system routing directory.</span>
+  </div>
+  <div className="flex gap-4 mb-2 pl-4">
+    <span className="text-muted-foreground w-36 shrink-0">server.ts</span>{' '}
+    <span>The strict entry point of your application.</span>
+  </div>
+  <div className="flex gap-4 pl-4">
+    <span className="text-muted-foreground w-36 shrink-0">route.ts</span>{' '}
+    <span>A basic GET endpoint mapped to the root route.</span>
+  </div>
+</div>
+
+## Your First Server
+
+Let's look at the generated `src/http/server.ts`. This is the strict entry point of your application, where you can connect to databases and register global plugins.
+
+### Functional Server Setup
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+
+export default exis({
+  async onStart(app) {
+    // 1. Connect to your database
+    // await db.connect()
+    // 2. Register plugins
+    // app.plugin(authPlugin)
+    // The Exis CLI automatically boots the server and file-system routes
+  },
+
+  async onClose(app) {
+    // Gracefully close database connections here
+    // await db.disconnect()
+  },
+})
+```
+
+### Class-Based (OOP) Server Setup
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import type { App } from 'exisjs'
+
+@Server()
+export default class RootServer {
+  async onStart(app: App) {
+    // 1. Connect to your database
+    // await db.connect()
+    // 2. Register plugins
+    // app.plugin(authPlugin)
+    // The Exis CLI automatically boots the server and file-system routes
+  }
+
+  async onClose(app: App) {
+    // Gracefully close database connections here
+    // await db.disconnect()
+  }
+}
+```
+
+With ExisJS, the framework automatically handles booting up your server and loading your routes based on the file system. You don't need to manually call `app.listen()`!
+
+## Your First Route
+
+ExisJS uses **folder-based routing**. Your API structure maps directly to your folders in `src/http/`.
+
+ExisJS supports two primary styles of writing routes: **Functional** and **OOP (Class-based)**. You are free to use whichever paradigm fits your team best.
+
+### Functional Routing
+
+Functional routing provides a lean, inference-heavy developer experience similar to modern frontend frameworks. Let's declare our first route in `src/http/users/route.ts`:
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  getUsers: route.get('/', {
+    handle(req) {
+      // Return a realistic response structure
+      return { 
+        data: [
+          { id: 1, name: 'Alice' },
+          { id: 2, name: 'Bob' }
+        ],
+        total: 2 
+      }
+    },
+  }),
+})
+```
+
+### OOP Routing
+
+If you prefer a highly-structured architecture heavily inspired by Angular and NestJS, ExisJS natively provides robust class-based routing using Decorators:
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  getUsers(@Req() req: Request) {
+    // Return a realistic response structure
+    return { 
+      data: [
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' }
+      ],
+      total: 2 
+    }
+  }
+}
+```
+
+In both examples, because this file is named `route.ts` and is located in the `users` folder, it automatically responds to `GET /users` requests. Whatever you return is automatically serialized to JSON.
+
+## Running the Application
+
+Your generated `package.json` comes pre-configured with the Exis CLI commands. Start the development server with hot-reload by running:
+
+<div className="my-6 max-w-lg">
+  <CopyCommand command="npm run dev" />
+</div>
+
+You will see the server boot up in your terminal:
+
+```text filename="Terminal"
+6:18:28 pm [exis] starting development server (v0.1.0)...
+
+ EXIS v0.1.0 ready in 125 ms
+
+ → Local:   http://localhost:4000/
+ → Network: http://10.39.14.177:4000/
+ → Environ: development
+ → press h + enter to show help
+```
+
+Open your browser and navigate to [http://localhost:4000/](http://localhost:4000/) (or the port defined in your `.env`). You will see:
+
+```json filename="Response"
+{
+  "data": [
+    {
+      "id": 1,
+      "name": "Alice"
+    },
+    {
+      "id": 2,
+      "name": "Bob"
+    }
+  ],
+  "total": 2
+}
+```

package/dist/docs/content/introduction.mdx

@@ -0,0 +1,96 @@
+---
+nextUrl: '/docs/installation'
+nextTitle: 'Installation'
+---
+
+# Introduction
+
+Exis (ExisJS) is a batteries-included backend framework for Node.js. It brings the file-based, convention-over-configuration developer experience of modern frontend meta-frameworks to backend API development: folders and files instead of manual wiring, with the essentials (routing, validation, queues, WebSockets, cron, DI) built in rather than assembled from a dozen separate packages.
+
+Routing is handled by a radix-tree matcher, and the framework supports two ways to define the same routes: **Functional** (factory functions) and **Class-Based / OOP** (decorators, in the style of Angular/NestJS). Both compile to the same internal route representation, run through the same middleware pipeline, and can be mixed file-by-file in the same project. Pick whichever fits a given part of your codebase.
+
+## Philosophy
+
+Frontend frameworks like Next.js, Remix, and Nuxt improved developer productivity significantly through file-based routing and convention-over-configuration architecture. Good tools exist for Node.js backends too, but assembling them into a coherent application still typically means a lot of manual wiring and architectural boilerplate.
+
+Exis aims to provide that out-of-the-box application architecture for backends: create a folder, get a route; create a `gateway.ts`, get folder-scoped middleware; import a module, get its providers registered. Job queues, WebSockets, cron scheduling, and schema validation are part of the standard library rather than bring-your-own dependencies. This means a new project starts with a coherent structure instead of a blank `index.js` and a pile of choices to make first.
+
+## Installation
+
+The fastest way to start is the Exis CLI, which scaffolds a new project directory with the core files and a conventional base structure already in place. This is the recommended path for first-time users.
+
+<div className="my-6 max-w-lg">
+  <CopyCommand command="npx @exisjs/create@latest my-backend" />
+</div>
+
+<Hint>
+  The CLI walks you through initial project setup (TypeScript config, import
+  aliases, and package manager selection: it detects npm, yarn, pnpm, or bun
+  automatically). See [Installation](/docs/installation) for the full list of
+  prompts and options.
+</Hint>
+
+## Quick Start
+
+Both paradigms are shown throughout these docs side by side. Pick whichever you're using, or mix them across your project.
+
+### Functional API
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  getUsers: route.get('/', {
+    handle(req) {
+      // Return a realistic response structure
+      return { 
+        data: [
+          { id: 1, name: 'Alice' },
+          { id: 2, name: 'Bob' }
+        ],
+        total: 2 
+      }
+    },
+  }),
+})
+```
+
+### Class-Based (OOP) API
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  getUsers(@Req() req: Request) {
+    // Return a realistic response structure
+    return { 
+      data: [
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' }
+      ],
+      total: 2 
+    }
+  }
+}
+```
+
+Save this as `src/http/users/route.ts`, run `exis dev`, and `GET /users` will return your mocked users list.
+
+## Adding to an existing project
+
+You can also add Exis to an existing Node.js project instead of scaffolding a new one:
+
+<div className="my-6 max-w-lg">
+  <CopyCommand command="npm install exisjs" />
+</div>
+
+In this case you'll set up the project structure yourself: an `exis.config.ts` at the project root and a `src/http` directory for your routes. See [Structure](/docs/structure) for the conventions the framework expects.
+
+## What's next
+
+- [Installation](/docs/installation): CLI setup and project scaffolding in detail.
+- [Structure](/docs/structure): the folder conventions Exis expects and why.
+- [Routing](/docs/routing): how file-based routing, dynamic segments, and gateways work together.