exisjs 0.6.1 → 0.7.0

package/dist/docs/integrations/resend.mdx

@@ -1,117 +0,0 @@
----
-nextUrl: "/docs/integrations/openai"
-nextTitle: "OpenAI"
----
-
-# Resend (Email) Integration
-
-ExisJS provides an integration for Resend to send emails. 
-
-Just like all our other integrations, ExisJS treats the `resend` SDK as an optional dependency. You only install it if you need it, keeping your core application lightweight.
-
----
-
-## Environment Variables
-
-The Resend plugin securely reads your API key directly from your `.env` file. 
-
-Before using the plugin, ensure you have your API key set:
-
-```bash filename=".env"
-RESEND_API_KEY="re_123456789"
-```
-
----
-
-## Installation
-
-ExisJS wraps the official `resend` Node.js SDK.
-
-```bash
-npm install resend
-```
-
----
-
-## Usage
-
-Simply import the `resend` proxy from `exisjs/resend`. ExisJS will boot the client behind the scenes the first time you attempt to send an email.
-
-#### Functional Paradigm
-
-```typescript filename="src/http/emails/route.ts"
-import { controller, route } from 'exisjs/router'
-import { resend } from 'exisjs/resend'
-
-export default controller({
-  sendWelcomeEmail: route.post('/welcome', {
-    async handle(req) {
-      const { email, name } = req.body
-
-    // The resend client lazy-loads here
-      const { data, error } = await resend.emails.send({
-        from: 'Acme <onboarding@resend.dev>',
-        to: [email],
-        subject: 'Welcome to Acme!',
-        html: `<strong>Hello ${name}, welcome aboard!</strong>`
-      })
-
-      if (error) {
-        return { success: false, error }
-      }
-
-      return { success: true, data }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/emails/route.ts"
-import { Controller, Post, Body } from 'exisjs/decorators'
-import { resend } from 'exisjs/resend'
-
-@Controller('/emails')
-export default class EmailsController {
-  
-  @Post('/welcome')
-  async sendWelcomeEmail(@Body() body: any) {
-    // The resend client automatically lazy-loads here!
-    const { data, error } = await resend.emails.send({
-      from: 'Acme <onboarding@resend.dev>',
-      to: [body.email],
-      subject: 'Welcome to Acme!',
-      html: `<strong>Hello ${body.name}, welcome aboard!</strong>`
-    })
-
-    if (error) {
-      return { success: false, error }
-    }
-
-    return { success: true, data }
-  }
-}
-```
-
----
-
-## Customizing Connection Options
-
-If you need to pass custom options to the Resend Client, call `configureResend(options)` inside your `server.ts` `onStart` hook.
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { configureResend } from 'exisjs/resend'
-
-export default exis({
-  async onStart() {
-    // Inject custom fetch options or headers
-    configureResend({
-      headers: {
-        'X-Custom-Header': 'ExisJS'
-      }
-    })
-  }
-})
-```

package/dist/docs/integrations/s3.mdx

@@ -1,122 +0,0 @@
----
-nextUrl: "/docs/integrations/resend"
-nextTitle: "Resend"
----
-
-# AWS S3 Integration
-
-ExisJS provides an integration for AWS S3 via the official `@aws-sdk/client-s3` package. 
-
-You do **NOT** need to write boilerplate to initialize the AWS SDK. The S3 client is lazily initialized when you execute your first `PutObject` or `GetObject` command.
-
----
-
-## Environment Variables
-
-The AWS S3 plugin securely reads your credentials directly from your `.env` file using the industry-standard AWS variable names.
-
-Before using the plugin, ensure you have your credentials set:
-
-```bash filename=".env"
-AWS_ACCESS_KEY_ID="your_access_key"
-AWS_SECRET_ACCESS_KEY="your_secret_key"
-AWS_REGION="us-east-1"
-```
-
----
-
-## Installation
-
-ExisJS wraps the `@aws-sdk/client-s3` library.
-
-```bash
-npm install @aws-sdk/client-s3
-```
-
----
-
-## Usage
-
-Simply import the `s3` proxy from `exisjs/s3` and use standard AWS SDK commands. ExisJS will boot the client behind the scenes.
-
-#### Functional Paradigm
-
-```typescript filename="src/http/uploads/route.ts"
-import { controller, route } from 'exisjs/router'
-import { s3 } from 'exisjs/s3'
-import { PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3'
-
-export default controller({
-  // ExisJS parses multipart/form-data when you access req.files
-  uploadFile: route.post('/', {
-    async handle(req) {
-      // req.files is automatically populated natively by ExisJS
-      const file = req.files[0] 
-      
-      const command = new PutObjectCommand({
-        Bucket: 'my-exis-bucket',
-        Key: file.filename,
-        Body: file.data, // Buffer
-        ContentType: file.mimetype,
-      })
-
-    // The s3 client lazy-loads here
-      await s3.send(command)
-
-      return { success: true, url: `https://my-exis-bucket.s3.amazonaws.com/${file.filename}` }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/uploads/route.ts"
-import { Controller, Post, UploadedFile, type ExisFile } from 'exisjs/decorators'
-import { s3 } from 'exisjs/s3'
-import { PutObjectCommand } from '@aws-sdk/client-s3'
-
-@Controller('/uploads')
-export default class UploadsController {
-  
-  @Post('/')
-  async uploadFile(@UploadedFile('avatar') file: ExisFile) {
-    const command = new PutObjectCommand({
-      Bucket: 'my-exis-bucket',
-      Key: file.filename,
-      Body: file.data, // Buffer
-      ContentType: file.mimetype,
-    })
-
-    // The s3 client automatically lazy-loads here!
-    await s3.send(command)
-
-    return { success: true, url: `https://my-exis-bucket.s3.amazonaws.com/${file.filename}` }
-  }
-}
-```
-
----
-
-## Customizing Connection Options
-
-If you need to pass custom options to the S3 Client (like a custom Endpoint URL for Cloudflare R2 or DigitalOcean Spaces), call `configureS3(options)` inside your `server.ts` `onStart` hook.
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { configureS3 } from 'exisjs/s3'
-
-export default exis({
-  async onStart() {
-    // Compatible with S3 APIs like Cloudflare R2
-    configureS3({
-      endpoint: 'https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
-      forcePathStyle: true
-    })
-  }
-})
-```
-
-<Hint>
-Because ExisJS uses the official AWS SDK under the hood, the S3 integration works with Cloudflare R2, DigitalOcean Spaces, MinIO, and any other S3-compatible storage provider.
-</Hint>

package/dist/docs/integrations/swagger.mdx

@@ -1,113 +0,0 @@
----
-nextUrl: "/docs/integrations/s3"
-nextTitle: "AWS S3"
----
-
-# Swagger OpenAPI
-
-ExisJS comes with a native **Swagger UI & OpenAPI 3.0** generator built directly into the framework. It parses your routes, path parameters, and schema validations to generate an API explorer.
-
-You do **not** need to maintain OpenAPI YAML files or write decorators.
-
----
-
-## Usage
-
-To enable Swagger UI, simply import `serveSwagger` and call it inside the `onStart` hook in your `server.ts`.
-
-```typescript filename="src/http/server.ts"
-import { exis } from 'exisjs'
-import { serveSwagger } from 'exisjs/swagger'
-
-export default exis({
-  async onStart(app) {
-    // Generate and mount Swagger UI
-    serveSwagger(app, {
-      path: '/api-docs', // Defaults to '/docs'
-      title: 'My Startup API',
-      version: '1.0.0',
-      components: {
-        securitySchemes: {
-          bearerAuth: {
-            type: 'http',
-            scheme: 'bearer',
-            bearerFormat: 'JWT'
-          }
-        }
-      }
-    })
-  }
-})
-```
-
-Once your server starts, navigate to `http://localhost:4000/api-docs` to see your auto-generated Swagger UI. The raw OpenAPI JSON payload will be available at `/api-docs/json`.
-
----
-
-## Automatic Schema Generation
-
-ExisJS integrates with its internal `v` validator. Any validation schemas attached to your routes (whether Functional or OOP) are automatically translated into OpenAPI specifications.
-
-#### Functional Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { controller, route } from 'exisjs/router'
-import { tex } from 'exisjs/validator'
-
-export default controller({
-  createUser: route.post('/', {
-    // This schema is automatically translated to OpenAPI request body definitions
-    body: tex.object({
-      name: tex.string(),
-      age: tex.number({ optional: true })
-    }),
-    async handle(req) {
-      return { success: true, name: req.body.name }
-    }
-  })
-})
-```
-
-#### Class-Based (OOP) Paradigm
-
-```typescript filename="src/http/users/route.ts"
-import { Controller, Post, Body } from 'exisjs/decorators'
-import { tex } from 'exisjs/validator'
-
-const CreateUserSchema = tex.object({
-  name: tex.string(),
-  age: tex.number({ optional: true })
-})
-
-@Controller('/users')
-export default class UsersController {
-  @Post('/', { body: CreateUserSchema })
-  async createUser(@Body() body: any) {
-    return { success: true, name: body.name }
-  }
-}
-```
-
-When you view Swagger UI, the `POST /users` endpoint will show the JSON body required, properly displaying the string/number types and required/optional flags.
-
----
-
-## Gateway Cascading Metadata
-
-If you want to apply OpenAPI tags or security schemas to an entire folder of routes without decorating every endpoint, you can use ExisJS Gateways.
-
-```typescript filename="src/http/admin/gateway.ts"
-import { defineGateway } from 'exisjs/router'
-
-export default defineGateway({
-  // Every route in the /admin folder automatically inherits these OpenAPI tags
-  metadata: {
-    openapi: { 
-      tags: ['Admin Management API'], 
-      security: ['bearerAuth'] 
-    }
-  }
-})
-```
-
-Now, every route under `/admin/*` will be grouped under the "Admin Management API" section in your Swagger UI.

package/dist/docs/reference/adapters.mdx

@@ -1,130 +0,0 @@
----
-title: "Adapters"
-description: "Strict API Reference for all Serverless and Edge adapters."
----
-
-# Adapters (`exisjs/adapters`)
-
-This document provides the strict API signatures and TypeScript interfaces exported by the `exisjs/adapters` module. For high-level deployment guides, see the [Adapters Guide](/docs/adapters).
-
----
-
-## `aws`
-
-Converts API Gateway events into a native Node.js HTTP stream.
-
-```typescript
-function aws(app: App): (event: APIGatewayEvent) => Promise<APIGatewayResult>
-```
-
-### `APIGatewayEvent`
-```typescript
-interface APIGatewayEvent {
-  httpMethod: string;
-  path: string;
-  headers: Record<string, string | undefined>;
-  body: string | null;
-  isBase64Encoded: boolean;
-  queryStringParameters?: Record<string, string | undefined>;
-}
-```
-
-### `APIGatewayResult`
-```typescript
-interface APIGatewayResult {
-  statusCode: number;
-  headers: Record<string, string>;
-  body: string;
-  isBase64Encoded: boolean;
-}
-```
-
----
-
-## `vercel`
-
-Provides a bridge between Vercel's Node.js Serverless runtime and ExisJS.
-
-```typescript
-function vercel(
-  app: App, 
-  options?: { cwd?: string }
-): (req: VercelRequest, res: VercelResponse) => void | Promise<void>
-```
-
-### `VercelRequest` & `VercelResponse`
-These are re-exported from `@vercel/node`. The adapter intercepts these and patches the internal socket state to satisfy the ExisJS pipeline.
-
----
-
-## `fetch`
-
-The universal Web Standard adapter. Converts standard Web `Request` objects into internal HTTP pipelines and resolves back to a Web `Response`.
-
-```typescript
-function fetch(
-  app: App
-): (request: Request, env?: any, ctx?: any) => Promise<Response>
-```
-
-*Note: The `env` and `ctx` arguments are seamlessly injected into the ExisJS routing context, allowing you to access platform-specific bindings (e.g. Cloudflare KV).*
-
----
-
-## `cloudflare`
-
-A dedicated wrapper for Cloudflare Workers that returns the expected ES Module format.
-
-```typescript
-function cloudflare(
-  app: App
-): { fetch: (request: Request, env: any, ctx: ExecutionContext) => Promise<Response> }
-```
-
----
-
-## `bun`
-
-A dedicated wrapper for the `Bun.serve()` configuration object.
-
-```typescript
-function bun(
-  app: App
-): { fetch: (request: Request) => Promise<Response> }
-```
-
----
-
-## `deno`
-
-A dedicated wrapper for `Deno.serve()`.
-
-```typescript
-function deno(
-  app: App
-): (request: Request) => Promise<Response>
-```
-
----
-
-## `netlify`
-
-A dedicated wrapper for Netlify Edge Functions.
-
-```typescript
-function netlify(
-  app: App
-): (request: Request, context: NetlifyContext) => Promise<Response>
-```
-
----
-
-## `fastly`
-
-A dedicated wrapper for Fastly Compute@Edge which binds to the global `addEventListener` fetch event.
-
-```typescript
-function fastly(
-  app: App
-): (event: FetchEvent) => void
-```

package/dist/docs/reference/auth.mdx

@@ -1,183 +0,0 @@
----
-title: "Authentication"
-description: "API Reference for ExisJS Authentication utilities (`exisjs/auth`)."
----
-
-# Authentication (`exisjs/auth`)
-
-ExisJS ships with a completely native, dependency-free `auth` module that covers the most critical security implementations: Scrypt Password Hashing, JWT (JSON Web Tokens), Session Management, and Role-Based Access Control (RBAC).
-
----
-
-## 1. Password Hashing (Scrypt)
-
-ExisJS natively uses Node's highly secure `scrypt` algorithm to hash passwords. It automatically generates a cryptographically secure salt and stores the parameters in a single string format (`scrypt:N:r:p:keylen:salt:hash`) so you never have to manage them separately.
-
-```typescript filename="src/services/AuthService.ts"
-import { Password } from 'exisjs/auth'
-
-// Hashing a new password
-const hashedPassword = await Password.hashPassword('my-super-secret-password', {
-  cost: 16384, // Higher cost = harder to brute force, but slower to compute
-})
-
-// Verifying a login attempt
-const isValid = await Password.verifyPassword('my-super-secret-password', hashedPassword)
-```
-
----
-
-## 2. JSON Web Tokens (JWT)
-
-You can instantly sign and verify JWTs without needing third-party libraries like `jsonwebtoken`.
-
-```typescript
-import { JWT } from 'exisjs/auth'
-
-// Sign a token valid for 2 hours
-const token = JWT.signJWT(
-  { userId: '123', role: 'admin' }, 
-  process.env.JWT_SECRET,
-  { expiresIn: 2 * 60 * 60 } 
-)
-
-try {
-  // Verifying token returns the exact typed payload
-  const payload = JWT.verifyJWT<{ userId: string, role: string }>(token, process.env.JWT_SECRET)
-  console.log(payload.userId)
-} catch (err) {
-  if (err.name === 'TokenExpiredError') {
-    // Handle expired token
-  }
-}
-```
-
----
-
-## 3. Session Middleware
-
-If you prefer stateful authentication, ExisJS provides extremely robust session middleware out of the box. It leverages signed HTTP-only cookies to track users and automatically synchronizes session state back to the store (Memory, Redis, etc.) when the request ends.
-
-### Global Setup via Plugin (`exis.config.ts`)
-
-Because ExisJS utilizes a file-based architecture with no manual server entry point, global middlewares like `session` should be attached using a Plugin.
-
-```typescript filename="src/plugins/session.ts"
-import { definePlugin } from 'exisjs/plugin'
-import { session } from 'exisjs/auth'
-
-export const sessionPlugin = definePlugin({
-  name: 'global-session',
-  register(app) {
-    app.use(session({
-      secret: process.env.SESSION_SECRET || 'fallback-secret-minimum-32-chars-long!',
-      cookieName: 'exis_sid',
-      ttl: 86400 * 1000, // 1 day in milliseconds
-      // store: new RedisSessionStore(...) 
-    }))
-  }
-})
-```
-
-Then, natively register your plugin in `exis.config.ts`:
-
-```typescript filename="exis.config.ts"
-import { defineConfig } from 'exisjs/config'
-import { sessionPlugin } from './src/plugins/session'
-
-export default defineConfig({
-  plugins: [
-    sessionPlugin()
-  ]
-})
-```
-
-Once registered, you can read and write to `req.session` anywhere in your application!
-
-### Functional Example
-
-```typescript filename="src/http/auth/route.ts"
-import { controller, route } from 'exisjs/router'
-import { HttpError } from 'exisjs/error'
-
-export default controller({
-  login: route.post('/login', {
-    async handle(ctx) {
-      const user = await db.users.findByEmail(ctx.body.email)
-      if (!user) throw HttpError.unauthorized('Invalid credentials')
-
-      // Login the user by attaching data to the session
-      ctx.req.session.userId = user.id
-      ctx.req.session.role = user.role
-      
-      return { success: true }
-    }
-  })
-})
-```
-
-### Class-Based (OOP) Example
-
-```typescript filename="src/http/auth/route.ts"
-import { Controller, Post, Body, Req } from 'exisjs/decorators'
-import type { Request } from 'exisjs'
-
-@Controller('/auth')
-export default class AuthController {
-  
-  @Post('/login')
-  async login(@Body() body: any, @Req() req: Request) {
-    const user = await db.users.findByEmail(body.email)
-    
-    // Attach to session
-    req.session.userId = user.id
-    req.session.role = user.role
-    
-    return { success: true }
-  }
-}
-```
-
----
-
-## 4. Role-Based Access Control (RBAC)
-
-The `requireRole` middleware checks if the current authenticated user has the necessary permissions to access a route.
-
-*Note: This middleware expects that `req.user.role` was populated by an earlier authentication middleware (like a JWT Verifier or a Session Restorer).*
-
-### Functional Example
-
-```typescript filename="src/http/admin/route.ts"
-import { controller, route } from 'exisjs/router'
-import { requireRole } from 'exisjs/auth'
-
-export default controller({
-  getDashboard: route.get('/dashboard', {
-    middleware: [
-      // Only users with 'admin' or 'superadmin' roles can access this route
-      requireRole(['admin', 'superadmin'])
-    ],
-    async handle() {
-      return { metrics: [] }
-    }
-  })
-})
-```
-
-### Class-Based (OOP) Example
-
-```typescript filename="src/http/admin/route.ts"
-import { Controller, Get, Use } from 'exisjs/decorators'
-import { requireRole } from 'exisjs/auth'
-
-@Controller('/admin')
-export default class AdminController {
-  
-  @Get('/dashboard')
-  @Use(requireRole(['admin', 'superadmin']))
-  async getDashboard() {
-    return { metrics: [] }
-  }
-}
-```