exisjs 0.5.10 → 0.5.11

package/dist/docs/content/cli/commands.mdx

@@ -0,0 +1,214 @@
+---
+nextUrl: "/docs"
+nextTitle: "Introduction"
+---
+
+# CLI command reference
+
+### `exisjs init`
+
+Creates a new ExisJS project.
+
+```bash
+$ npx exisjs init
+```
+
+**Description**
+Creates and initializes a new ExisJS project. Prompts for configuration options (such as whether to include TypeScript, ESLint, Database integrations, etc.) and generates a boilerplate project structure for you.
+
+---
+
+### `exisjs generate`
+
+Generates and/or modifies files based on a schematic.
+
+```bash
+$ npx exisjs generate <type> <name> [options]
+$ npx exisjs g <type> <name> [options]
+```
+
+**Description**
+Generates new features for your application, such as routes, plugins, middleware, or tests.
+
+**Arguments**
+
+| Argument | Description |
+| :--- | :--- |
+| `<type>` | The type of the feature to generate. See the Schematics table below. |
+| `<name>` | The name of the generated component. |
+
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `--oop` | Generate using Class-Based (OOP) paradigm instead of Functional. |
+
+**Schematics**
+
+| Name | Alias | Description |
+| :--- | :--- | :--- |
+| `route` | `r` | Generates a new Route controller. |
+| `plugin` | `p` | Generates a new ExisJS Plugin module. |
+| `middleware` | `m` | Generates a new Middleware function. |
+| `test` | `t` | Generates a new test suite file. |
+
+---
+
+### `exisjs build`
+
+Compiles an application or workspace into an output folder.
+
+```bash
+$ npx exisjs build [options]
+```
+
+**Description**
+Compiles TypeScript to production JavaScript.
+
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `-o, --out-dir <dir>` | Output directory (default: dist). |
+| `--no-clean` | Skip cleaning the output directory. |
+
+---
+
+### `exisjs start`
+
+Compiles and runs an application from the compiled `dist` directory.
+
+```bash
+$ npx exisjs start [options]
+```
+
+**Description**
+Starts the production server by executing the compiled application entry file.
+
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `-p, --port <port>` | Port to listen on (overrides `.env`). |
+| `-e, --entry <file>` | Custom compiled entry file path (default: `dist/http/server.js`). |
+
+---
+
+### `exisjs dev`
+
+Starts the development server with Hot Module Replacement (HMR) and automatic restarts.
+
+```bash
+$ npx exisjs dev [options]
+```
+
+**Description**
+Starts the development server and handles TypeScript compilation on the fly.
+- **Port Detection:** If your requested port is already in use by another process, it detects the collision, automatically increments the port, and binds to the next available one.
+- **Lazy Routing (.exis):** ExisJS leverages the hidden `.exis` folder during development to lazy-load routes on demand.
+
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `-p, --port <port>` | Port to listen on (overrides `.env`). |
+| `-h, --host <host>` | Host to bind to. |
+| `-e, --entry <file>` | Custom entry file path (default: `src/http/server.ts`). |
+
+---
+
+### `exisjs test`
+
+Runs the native Node.js test runner (`node:test`) across your project.
+
+```bash
+$ npx exisjs test [files...] [options]
+```
+
+**Description**
+Automatically sets up the ExisJS environment and parses TypeScript natively to run tests using the built-in `node:test` runner.
+
+**Arguments**
+
+| Argument | Description |
+| :--- | :--- |
+| `[files...]` | Specific test files or directories to run (optional). |
+
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `--watch` | Watch for file changes and re-run tests. |
+| `-u, --update` | Update test snapshots. |
+| `-e, --entry <file>` | Custom entry file path to bootstrap before tests. |
+
+---
+
+### `exisjs routes`
+
+Analyzes your application and prints a tabular representation of your entire routing table to the terminal.
+
+```bash
+$ npx exisjs routes [options]
+```
+
+**Description**
+Loads your application context and outputs a formatted table showing all registered HTTP routes.
+
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `-e, --entry <file>` | Custom entry file path to bootstrap the app from. |
+
+---
+
+### `exisjs repl`
+
+Starts an interactive Read-Eval-Print Loop (REPL) console loaded with your application's context.
+
+```bash
+$ npx exisjs repl [options]
+$ npx exisjs console [options]
+```
+
+**Description**
+Provides an interactive command-line environment with direct access to your application's database, plugins, and services.
+
+**Options**
+
+| Option | Description |
+| :--- | :--- |
+| `-e, --entry <file>` | Custom entry file path to bootstrap the app from. |
+
+---
+
+### `exisjs exports`
+
+Lists all the available framework exports and public APIs exposed by ExisJS.
+
+```bash
+$ npx exisjs exports
+```
+
+**Description**
+Outputs a list of everything that can be imported from the `exisjs` package.
+
+---
+
+### `exisjs info`
+
+Displays environment and version information for debugging and bug reporting.
+
+```bash
+$ npx exisjs info
+```
+
+**Description**
+Prints out the current ExisJS version, Node.js version, platform, and architecture.
+
+---
+
+## Requirements
+
+ExisJS CLI requires a Node.js binary. We recommend Node.js v20+ to ensure compatibility with modern native features (like the built-in test runner).

package/dist/docs/content/cli/overview.mdx

@@ -0,0 +1,92 @@
+---
+nextUrl: "/docs/cli/usage"
+nextTitle: "CLI Usage"
+---
+
+# Overview
+
+The ExisJS CLI is a command-line interface tool that helps you initialize, develop, and maintain your ExisJS applications. It assists in scaffolding the project, serving it in development mode, and building the application for production. 
+
+An ExisJS application is a standard TypeScript application that needs to be compiled to JavaScript before execution. The CLI provides a standard build and execute process with reasonable defaults, while ensuring developers can access the underlying tools (like `tsc` and `node`) to customize them if necessary.
+
+## Installation
+
+You have several options available for managing how your OS command line resolves the location of the `exisjs` binary file. 
+
+You can install the CLI globally using the `npm install -g` command. This provides convenience and ensures the `exisjs` binary is available across your system.
+
+```bash
+$ npm install -g exisjs
+```
+
+> [!NOTE]
+> Alternatively, you can use `npx exisjs` to run the CLI without installing it globally. This ensures you run the latest version or a managed local version.
+
+## Basic workflow
+
+Once installed, you can invoke CLI commands directly from your OS command line through the `exisjs` executable. See the available commands by entering the following:
+
+```bash
+$ exisjs --help
+```
+
+Get help on an individual command using the `--help` flag. Substitute any command to get detailed help:
+
+```bash
+$ exisjs generate --help
+```
+
+To create, build, and run a new basic ExisJS project in development mode, navigate to the folder that should be the parent of your new project, and run the following commands:
+
+```bash
+$ exisjs init my-project
+$ cd my-project
+$ npm run dev
+```
+
+In your browser, open `http://localhost:3000` to see the new application running. The application will automatically recompile and reload when you change any source files.
+
+## CLI command syntax
+
+All `exisjs` commands follow the same format:
+
+```bash
+exisjs <command> [arguments] [options]
+```
+
+For example:
+
+```bash
+$ exisjs generate route users --oop
+```
+
+Here, `generate` is the command, `route` and `users` are the arguments, and `--oop` is the option. 
+
+Most commands and some options have aliases. For example, `generate` can be invoked as `g`:
+
+```bash
+$ exisjs g route users --oop
+```
+
+## Command overview
+
+Run `exisjs <command> --help` for any of the following commands to see command-specific options.
+
+See [CLI Commands](/docs/cli/commands) for detailed descriptions of each command.
+
+| Command | Alias | Description |
+| :--- | :--- | :--- |
+| `init` | | Creates and initializes a new ExisJS project. |
+| `generate` | `g` | Generates features based on schematics (routes, plugins, etc.). |
+| `build` | | Compiles an application into an output folder. |
+| `start` | | Runs an application from the compiled directory. |
+| `dev` | | Starts the development server with hot module replacement. |
+| `test` | | Runs the native Node.js test runner across your project. |
+| `routes` | | Prints a tabular representation of your routing table. |
+| `repl` | `console` | Starts an interactive REPL console loaded with your application context. |
+| `exports` | | Lists all available framework exports. |
+| `info` | | Displays environment and version information. |
+
+## Requirements
+
+The ExisJS CLI requires a Node.js binary. We recommend Node.js v20+ to ensure compatibility with modern native features, such as the built-in test runner.

package/dist/docs/content/cli/usage.mdx

@@ -0,0 +1,61 @@
+---
+nextUrl: "/docs/cli/commands"
+nextTitle: "CLI Commands"
+---
+
+# CLI Usage
+
+The ExisJS CLI can be executed in two primary contexts: **globally** via your operating system's PATH, or **locally** via your project's `package.json` scripts. Understanding the distinction between these execution contexts is critical for maintaining stable development environments.
+
+## Global vs. Local Execution
+
+When you install the CLI globally (`npm install -g exisjs`) or run it on-demand via `npx`, the binary operates outside of your project's dependency tree. While this is necessary for initializing new projects, it presents a challenge for long-term maintenance: if two developers have different global versions of the CLI installed, they may experience inconsistent build outputs or behavior.
+
+To solve this, ExisJS manages its build and execution tools as **local development dependencies**. When you run `exisjs init`, the framework automatically installs the `exisjs` package into your `node_modules` and wires it up to your `package.json` scripts. 
+
+By executing the CLI through `npm run`, npm automatically resolves the binary to the exact version pinned in your `package.json`, ensuring deterministic behavior across your entire engineering team and CI/CD pipelines.
+
+## Default Package Scripts
+
+Every ExisJS project is scaffolded with a standard set of `package.json` scripts that wrap the underlying CLI commands:
+
+```json
+{
+  "scripts": {
+    "dev": "exisjs dev",
+    "build": "exisjs build",
+    "start": "exisjs start",
+    "test": "exisjs test"
+  }
+}
+```
+
+You invoke these scripts using your package manager:
+
+```bash
+$ npm run dev
+$ npm run build
+$ npm run start
+```
+
+## Passing Arguments via Scripts
+
+If you need to pass additional arguments or options to the CLI while using package scripts, append a double-dash (`--`) before the CLI options. This instructs npm to pass the remaining arguments directly to the underlying `exisjs` command.
+
+For example, to start the development server on a custom port:
+
+```bash
+$ npm run dev -- --port 4000
+```
+
+To generate a new route using `npx` (which bypasses the script requirement while still using the local binary):
+
+```bash
+$ npx exisjs generate route users
+```
+
+## Recommended Workflow
+
+1. Use the global CLI (or `npx exisjs`) **only** for scaffolding new projects (`exisjs init`).
+2. Use the `package.json` scripts (e.g., `npm run dev`) for all day-to-day development, building, and testing.
+3. Use `npx exisjs` inside an existing project directory for one-off commands (like `generate`, `routes`, or `repl`).

package/dist/docs/content/config.mdx

@@ -0,0 +1,214 @@
+---
+nextUrl: '/docs/routing'
+nextTitle: 'Routing'
+---
+
+# Configuration (`exis.config.ts`)
+
+ExisJS uses a fully typed configuration engine that closely resembles Vite or Next.js.
+
+By placing an `exis.config.ts` file in the root of your project, you gain complete control over the underlying server (Node.js or uWebSockets), middleware (CORS, Helmet, Compression), SSL, and the Plugin ecosystem.
+
+---
+
+## 1. Basic Configuration
+
+A basic configuration simply exports the result of `defineConfig`. This provides TypeScript autocomplete for all available options.
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+
+export default defineConfig({
+  port: 4000,
+  host: '0.0.0.0',
+
+  cors: {
+    origin: '*',
+    credentials: true,
+  },
+
+  logger: {
+    level: 'debug',
+    pretty: true,
+  },
+})
+```
+
+---
+
+## 2. Dynamic & Phase-Based Config
+
+Often, you'll need different configurations for Development, Production, or Testing (e.g., enabling pretty logging only in development, or changing the Database URL).
+
+ExisJS allows you to export an `async function` that provides the current `phase` (Environment).
+
+```typescript filename="exis.config.ts"
+import { defineConfig, PHASE_DEVELOPMENT_SERVER } from 'exisjs/config'
+
+export default async (phase: string, { defaultConfig }: any) => {
+  const isDev = phase === PHASE_DEVELOPMENT_SERVER
+
+  return defineConfig({
+    port: Number(process.env.PORT) || 4000,
+
+    // Enable pretty logging only in Development
+    logger: isDev ? { level: 'debug', pretty: true } : false,
+
+    // Compress responses in Production
+    compression: !isDev,
+  })
+}
+```
+
+The available phases are:
+
+- `PHASE_DEVELOPMENT_SERVER` (Triggered via `exis dev`)
+- `PHASE_PRODUCTION_SERVER` (Triggered via `exis start`)
+- `PHASE_TEST` (Triggered when `NODE_ENV=test`)
+
+---
+
+## 3. Type-Safe Environment Variables
+
+We highly recommend using `v.env()` from `exisjs/validator` to strongly type and validate your environment variables before the server starts. You can create an `env.ts` file and import it directly into your `exis.config.ts`.
+
+```typescript filename="env.ts"
+import { tex } from 'exisjs/validator'
+
+export const env = tex.object({
+  PORT: tex.number({ coerce: true, optional: true }),
+  NODE_ENV: tex.string({ optional: true }),
+  MONGODB_URI: tex.string(),
+}).parse(process.env)
+```
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+import { env } from './env.ts' // Fails fast if variables are missing!
+
+export default defineConfig({
+  port: env.PORT,
+  logger: {
+    pretty: env.NODE_ENV !== 'production',
+  },
+})
+```
+
+---
+
+## 4. Background Jobs & Workers
+
+To enable the background job engine (which powers scheduled Cron jobs and the task queue), you must explicitly configure a `queue` driver in `exis.config.ts`.
+
+If this is missing, the job scheduler is completely disabled to save memory.
+
+```typescript filename="exis.config.ts"
+export default defineConfig({
+  queue: {
+    driver: 'memory', // Use 'redis' for multi-server production
+    enableWorkers: true, // Set to false to push jobs but not process them
+  },
+})
+```
+
+---
+
+## 5. The Underlying Server Engine
+
+By default, ExisJS uses the native Node.js HTTP/HTTPS modules. However, you can seamlessly switch the underlying engine to **uWebSockets.js (uWS)** for significantly higher throughput.
+
+```typescript filename="exis.config.ts"
+export default defineConfig({
+  // 'auto' will use uWS if installed, otherwise gracefully fallback to Node
+  server: 'auto', // 'auto' | 'node' | 'bun'
+})
+```
+
+---
+
+## 6. Complete Options Reference
+
+Here is a full breakdown of the configuration schema:
+
+### Network & SSL
+
+- `port` _(number)_: The port the server will bind to. (Default: `4000`)
+- `host` _(string)_: The host interface to bind to. (Default: `'0.0.0.0'`)
+- `ssl` _(object)_: Provide `{ key, cert }` strings or Buffers to enable HTTPS natively.
+- `http2` _(boolean)_: Enables HTTP/2 support natively. (Defaults to `true` when SSL is provided).
+- `redirectHttp` _(boolean | number)_: Automatically intercepts HTTP requests and redirects them to HTTPS.
+
+### Global Middleware
+
+- `cors` _(object | boolean)_: Global CORS policy configuration (`origin`, `methods`, `credentials`, etc.).
+- `helmet` _(object | boolean)_: Automatically secures your app with standard HTTP headers. (Enabled by default).
+- `compression` _(object | boolean)_: Enables Gzip/Brotli compression for all HTTP responses.
+- `logger` _(object | boolean)_: Configures the internal Pino-based logger (`level`, `pretty`).
+- `etag` _(boolean)_: Automatically generates ETag headers for cache-invalidation.
+
+### Performance & Security
+
+- `bodyLimit` _(number)_: The maximum allowed size (in bytes) for incoming request bodies. (Default: `1MB`)
+- `trustProxy` _(boolean | number)_: If true, respects `X-Forwarded-For` and `X-Forwarded-Host` headers (essential for apps deployed behind NGINX, Cloudflare, or AWS ELB). If a number, trusts that many hops.
+- `keepAlive` _(object | boolean)_: Tunes the Keep-Alive timeout and Header timeout limits.
+- `workers` _(number | 'safe' | 'max')_: Number of CPU workers for cluster mode. Defaults to 1. 'safe' caps to 2. 'max' uses all available cores.
+
+### Execution & Debugging
+
+- `env` _(string)_: Overrides the environment. Can be 'development', 'production', or 'test'.
+- `server` _('auto' | 'node' | 'uws')_: Server backend to use. Defaults to 'node'.
+- `debugRouting` _(boolean)_: Enables detailed logging of the resolved route file and applied gateways for every incoming request.
+- `test` _(object)_: Configuration for the native test runner (`include`, `exclude`, `setupFiles`, `concurrency`, `coverage`).
+
+### Queues & Plugins
+
+- `queue` _(object)_: Configures the Global Job Queue driver (`memory` or `redis`) and backpressure settings.
+- `plugins` _(array)_: Registers framework-level plugins.
+
+---
+
+## 7. ExisJS Plugin Ecosystem
+
+The ExisJS configuration file is also where you integrate native plugins and modules.
+
+You can easily build your own plugins using `defineModule` from `exisjs/module`. Under the hood, plugins get full access to the `app` instance to register routes, providers, or lifecycle hooks!
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+import { defineModule } from 'exisjs/module'
+
+// 1. Create a custom plugin (e.g., a mock GraphQL endpoint)
+const graphqlPlugin = (options: { endpoint: string }) =>
+  defineModule({
+    name: 'graphql',
+    routes: (app) => {
+      app.post(options.endpoint, (req, res) =>
+        res.json({ data: 'GraphQL Response' })
+      )
+    },
+  })
+
+// 2. Register it in your config
+export default defineConfig({
+  plugins: [graphqlPlugin({ endpoint: '/graphql' })],
+})
+```
+
+---
+
+## 8. Process Model & Multi-Tenancy
+
+ExisJS expects a **One App Per Process** architecture.
+
+### Zero-Config Singletons
+
+ExisJS's highly ergonomic integrations (e.g., `redis.ts`, `prisma.ts`, `s3.ts`) are implemented using ES6 Proxies that cache the underlying clients at the module level. This means they are **process-wide singletons**.
+If you attempt to mount multiple `App` instances inside a single Node.js process to serve different tenants, they will **share the exact same database connections, redis pools, and caches**.
+
+### Multi-Tenant Guidance
+
+If you are building a multi-tenant B2B application, do not boot multiple ExisJS `App` instances per tenant. Instead, use one of the following standard approaches:
+
+1. **Row-Level Tenancy (Recommended)**: Run a single `App` connected to a single database. Use request context or middleware to inject the `tenantId` and scope all queries via Prisma/SQL.
+2. **Factory-Based Clients**: If you need true database-per-tenant isolation, do not use the zero-config singleton exports (like `import { db } from 'exisjs/prisma'`). Instead, manually construct the client factories inside a tenant-resolution middleware and attach them to the request context (`req.tenantDb`).
+3. **Containerized Deployments**: Run separate Node.js processes (Docker containers) for each tenant, passing tenant-specific `DATABASE_URL`s to each container.