exisjs 0.7.2 → 0.7.3

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

@@ -79,4 +79,5 @@ $ npx exisjs g r users --oop
 | `repl` | `console` | Starts an interactive Node.js REPL loaded with the application context. |
 | `exports` | | Displays all available `@exisjs` and `exisjs/*` subpath exports. |
 | `info` | | Displays system, Node.js, and ExisJS runtime information. |
+| `doctor` | | Performs system, native Rust acceleration, TypeScript, and routing diagnostics. |
 | `init` | | Initializes a new ExisJS application in the current directory. |

package/dist/docs/content/config.mdx

@@ -140,7 +140,14 @@ Here is a full breakdown of the configuration schema:
 
 ### Global Middleware
 
-- `cors` _(object | boolean)_: Global CORS policy configuration (`origin`, `methods`, `credentials`, etc.).
+- `cors` _(object | boolean)_: Global CORS policy configuration. Supports:
+  - Exact string origins (e.g. `'https://example.com'` or `'*'`).
+  - Regular expressions (e.g. `/localhost:\d+/`).
+  - Arrays mixing strings and regexes (`['https://app.example.com', /https:\/\/.*\.domain\.com/']`).
+  - Dynamic callbacks: `(origin, cb) => ...` or async functions: `async (origin) => boolean` for multi-tenant setups.
+- `transformResponse` _(boolean | function)_: Automatically wraps all successful handler responses into a standardized envelope:
+  - When `true`: `{ success: true, data: ..., timestamp: ... }` (matching `HttpError`'s `{ success: false, error: ... }`).
+  - When a function: `(data, req, res) => ({ ... })` to provide your own custom envelope.
 - `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`).

package/dist/docs/content/errors.mdx

@@ -247,8 +247,8 @@ You can use the `metrics` middleware to track request durations and counts.
 
 ### Functional Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { defineGateway } from 'exisjs/router'
+```typescript filename="src/http/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
 import { metrics } from 'exisjs/observability'
 
 const myPrometheusAdapter = {
@@ -261,15 +261,15 @@ const myPrometheusAdapter = {
   }
 }
 
-export default defineGateway({
+export const config = defineBoundary({
   middleware: [metrics(myPrometheusAdapter)]
 })
 ```
 
 ### Class-Based (OOP) Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
+```typescript filename="src/http/boundary.ts"
+import { Boundary } from 'exisjs/decorators'
 import { metrics } from 'exisjs/observability'
 
 const myPrometheusAdapter = {
@@ -280,10 +280,10 @@ const myPrometheusAdapter = {
   }
 }
 
-@Gateway({
+@Boundary({
   middleware: [metrics(myPrometheusAdapter)]
 })
-export default class RootGateway {}
+export default class RootBoundary {}
 ```
 
 *Note: ExisJS normalizes dynamic paths (e.g., turning `/users/123` into `/users/:id`) to prevent metrics cardinality issues.*
@@ -294,8 +294,8 @@ ExisJS seamlessly integrates with OpenTelemetry (OTel) via the `tracing` middlew
 
 ### Functional Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { defineGateway } from 'exisjs/router'
+```typescript filename="src/http/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
 import { tracing } from 'exisjs/observability'
 
 const myOtelAdapter = {
@@ -312,15 +312,15 @@ const myOtelAdapter = {
   }
 }
 
-export default defineGateway({
+export const config = defineBoundary({
   middleware: [tracing(myOtelAdapter)]
 })
 ```
 
 ### Class-Based (OOP) Paradigm
 
-```typescript filename="src/http/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
+```typescript filename="src/http/boundary.ts"
+import { Boundary } from 'exisjs/decorators'
 import { tracing } from 'exisjs/observability'
 
 const myOtelAdapter = {
@@ -335,10 +335,10 @@ const myOtelAdapter = {
   }
 }
 
-@Gateway({
+@Boundary({
   middleware: [tracing(myOtelAdapter)]
 })
-export default class RootGateway {}
+export default class RootBoundary {}
 ```
 
 By providing these standard interfaces natively, your application metrics and traces are bound to the ExisJS router lifecycle.

package/dist/docs/content/responses.mdx

@@ -269,3 +269,109 @@ ExisJS features native, automatic ETag generation.
 If the client sends an `If-None-Match` header matching the ETag of the current response, ExisJS will immediately abort serialization and send a `304 Not Modified` header with an empty body, saving bandwidth and CPU cycles.
 
 *Note: ETag generation is disabled by default, but can be enabled globally in your `exis()` config, or manually per-route via `res.etagEnabled = true`.*
+
+---
+
+## 7. Server-Sent Events (SSE) & AI Streaming
+
+ExisJS provides a first-class `res.sse()` method for real-time live events and AI chat completions (OpenAI, Anthropic, Ollama, LangChain).
+
+When called, `res.sse()` automatically configures and flushes the required HTTP headers:
+- `Content-Type: text/event-stream; charset=utf-8`
+- `Cache-Control: no-cache, no-transform`
+- `Connection: keep-alive`
+- `X-Accel-Buffering: no` (disables NGINX proxy buffering)
+
+You can import `SSEStream`, `formatSSEEvent`, `SSEMessage`, and `SSEOptions` from `exisjs/router`.
+
+### Basic SSE Stream
+
+#### Functional Paradigm
+
+```typescript filename="src/http/events/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  liveEvents: route.get('/', {
+    handle(req, res) {
+      // Initialize the stream (heartbeat ping every 15s by default)
+      const sse = res.sse()
+
+      sse.send({ event: 'connected', data: { timestamp: Date.now() } })
+
+      const interval = setInterval(() => {
+        sse.send({ event: 'price-update', data: { symbol: 'BTC', price: 95000 } })
+      }, 1000)
+
+      // Automatically clean up intervals when the client disconnects or closes the tab
+      sse.onClose(() => {
+        clearInterval(interval)
+      })
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/events/route.ts"
+import { Controller, Get, Res } from 'exisjs/decorators'
+import type { Response } from 'exisjs/router'
+
+@Controller()
+export default class EventsController {
+  @Get('/events')
+  streamEvents(@Res() res: Response) {
+    const sse = res.sse()
+
+    sse.send({ event: 'connected', data: { status: 'ok' } })
+
+    sse.onClose(() => {
+      console.log('Client disconnected from SSE stream')
+    })
+  }
+}
+```
+
+### AI / LLM Streaming with `sse.pipeFrom()`
+
+You can directly stream chunks from any `AsyncIterable` (such as the OpenAI SDK or custom generators) using `sse.pipeFrom()`:
+
+```typescript filename="src/http/ai/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  chat: route.post('/', {
+    handle(req, res) {
+      res.sse(async (sse) => {
+        // Stream directly from an async generator or AI SDK
+        async function* generateTokens() {
+          yield 'Hello'
+          yield ' from'
+          yield ' ExisJS'
+          yield ' AI streaming!'
+        }
+
+        await sse.pipeFrom(generateTokens(), (token) => ({
+          event: 'delta',
+          data: { text: token }
+        }))
+
+        sse.close()
+      })
+    }
+  })
+})
+```
+
+### SSE Options & Methods
+
+- `res.sse(options?)`: Options include:
+  - `heartbeat`: Heartbeat interval in milliseconds (default: `15000`). Pass `false` to disable.
+  - `heartbeatComment`: Custom comment string for keep-alive pings (default: `": ping\n\n"`).
+  - `headers`: Additional custom HTTP headers.
+- `sse.send(message)`: Sends an event. Accepts string, number, object (auto JSON-stringified), or `{ event, data, id, retry }`.
+- `sse.comment(text)`: Sends a raw SSE comment line (e.g. `: ping\n\n`) without triggering client-side event listeners.
+- `sse.onClose(callback)`: Registers a callback fired when the client disconnects.
+- `sse.close()`: Gracefully terminates the stream and closes the HTTP response.
+

package/dist/docs/content/routing.mdx

@@ -15,11 +15,11 @@ ExisJS natively supports both a **Functional Paradigm** and a **Class-Based OOP
 
 ExisJS uses **folder-based file-system routing** instead of programmatic route declaration in a single entry file.
 
-For a folder to become an accessible API endpoint, it must contain a `route.ts` file that exports a route definition. 
+For a folder to become an accessible API endpoint, it must contain a `route.ts` or `<feature>.route.ts` (e.g. `user.route.ts`) file that exports a route definition. 
 
 In addition to `route.ts`, the ExisJS router utilizes two other special gatekeeper files:
 - **`server.ts`**: Placed at the root of your `http` directory, it is the entry point that boots your application, registers global plugins, and connects to databases.
-- **`gateway.ts`**: Can be placed in any folder. It acts as a gatekeeper, automatically applying middleware, CORS, headers, and dependencies to *all* routes within its directory and subdirectories.
+- **`boundary.ts`** (or `*.boundary.ts`): Can be placed in any folder. It acts as a gatekeeper and request pipeline, automatically configuring middleware, CORS, headers, and dependencies for *all* routes within its directory and subdirectories.
 
 ### Routing Conventions
 
@@ -38,9 +38,9 @@ The `server.ts` file acts as the root configuration for your application. It pro
 import { exis } from 'exisjs'
 
 export default exis({
-  async onStart(app) {
-    // Boot your database here!
-  }
+  providers: [
+    ['LoggerService', { useValue: console }]
+  ]
 })
 ```
 
@@ -59,27 +59,27 @@ export default class RootServer {
 }
 ```
 
-### Folder Gateways (`gateway.ts`)
+### Folder Boundaries (`boundary.ts`)
 
-Gateways apply configurations to all routes in their directory and subdirectories.
+Boundaries apply configurations, security policies, and request pipelines to all routes in their directory and subdirectories.
 
 #### Functional Paradigm
-```typescript filename="src/http/admin/gateway.ts"
-import { defineGateway } from 'exisjs/router'
+```typescript filename="src/http/admin/boundary.ts"
+import { defineBoundary } from 'exisjs/router'
 
-export default defineGateway({
+export const config = defineBoundary({
   headers: { 'X-Admin-Area': 'true' }
 })
 ```
 
 #### Class-Based (OOP) Paradigm
-```typescript filename="src/http/admin/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
+```typescript filename="src/http/admin/boundary.ts"
+import { Boundary } from 'exisjs/decorators'
 
-@Gateway({
+@Boundary({
   headers: { 'X-Admin-Area': 'true' }
 })
-export default class AdminGateway {}
+export default class AdminBoundary {}
 ```
 
 ### Route Definitions (`route.ts`)
@@ -264,13 +264,18 @@ export default controller({
   }),
   getSingle: route.get('/:id', {
     handle({ params }) {
+      // params.id is automatically inferred as string with full autocomplete!
       const { id } = params
-      return { message: \`Fetching user \${id}\` }
+      return { message: `Fetching user ${id}` }
     }
   })
 })
 ```
 
+<Info title="Automatic Route Parameter Type Inference">
+In ExisJS v0.7+, paths with named parameters like `route.get('/users/:userId/posts/:postId', ...)` automatically parse the path string literal to infer `params: { userId: string; postId: string }` on the `handle` context. No manual casting or boilerplate interfaces required.
+</Info>
+
   
 #### Class-Based (OOP) Paradigm
 

package/dist/docs/content/security.mdx

@@ -16,18 +16,23 @@ The following security middlewares are available from `exisjs/middleware` and ca
 - `helmet(options?)`: Sets 14+ secure HTTP headers (Strict-Transport-Security, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and CSP).
 - `csrf(options)`: Enforces the Signed Double Submit Cookie pattern to protect state-changing requests (POST, PUT, DELETE) from CSRF attacks.
 - `hpp()`: Protects against HTTP Parameter Pollution attacks by ensuring array query parameters/form fields are safely handled.
+- `mongoSanitize()`: Strips MongoDB operator keys (keys starting with `$` or containing `.`) from `req.body`, `req.query`, and `req.params`.
 - `dbSanitize(options?)`: Protects against NoSQL query operator injection (`$where` and other malicious keys) before reaching database layers.
 - `timeout(ms)`: Automatically terminates requests that exceed the specified timeout limit, returning a 503 response.
 
+> [!TIP]
+> Security middlewares like `hpp()`, `mongoSanitize()`, and `dbSanitize()` automatically synchronize with the request body parser. If registered globally before route handlers, they safely await the body and sanitize it deterministically without runtime crashes.
+
 ```typescript filename="src/http/server.ts"
 import { exis } from 'exisjs'
-import { helmet, csrf, timeout, hpp } from 'exisjs/middleware'
+import { helmet, csrf, timeout, hpp, mongoSanitize } from 'exisjs/middleware'
 
 export default exis({
   async onStart(app) {
     app.use(helmet())
     app.use(timeout(10000))
     app.use(hpp())
+    app.use(mongoSanitize())
   }
 })
 ```

package/dist/docs/content/structure.mdx

@@ -60,12 +60,18 @@ my-backend/
 A file's name declares its role. Functional vs. class-based (OOP) only changes
 _syntax_, never _responsibility_.
 
-| File          | Role                                                                                                 | Never contains                   |
-| ------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------- |
-| `route.ts`    | Binds a URL + method to a handler.                                                                   | Business logic, validation logic |
-| `schema.ts`   | `tex` validation schemas, imported by `route.ts`. Mandatory for every `route.ts` that accepts input. | Handlers, routing                |
-| `service.ts`  | Business logic and data access. DI-injectable.                                                       | Routing, response shaping        |
-| `boundary.ts` | Folder-scoped config + request pipeline for everything in this folder and below.                     | —                                |
+ExisJS supports two naming conventions seamlessly:
+1. **Standard Flat Names** (default): `route.ts`, `schema.ts`, `service.ts`, `boundary.ts`.
+2. **Feature-Prefixed Named Files**: `<name>.route.ts`, `<name>.schema.ts`, `<name>.service.ts`, `<name>.boundary.ts` (e.g., `user.route.ts`, `user.schema.ts`, `user.service.ts`).
+
+Both styles are automatically detected by the route scanner, CLI manifest generator, and development watcher with 100% parity.
+
+| File Pattern | Role | Never contains |
+| :--- | :--- | :--- |
+| `route.ts` / `*.route.ts` | Binds a URL + method to a handler. | Business logic, validation logic |
+| `schema.ts` / `*.schema.ts` | `tex` validation schemas, imported by route files. Mandatory for every route accepting input. | Handlers, routing |
+| `service.ts` / `*.service.ts` | Business logic and data access. DI-injectable. | Routing, response shaping |
+| `boundary.ts` / `*.boundary.ts` | Folder-scoped config + request pipeline for everything in this folder and below. | — |
 
 ---
 

package/dist/middleware/compression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/middleware/compression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,UAAU,CAAA;AAE1D;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAiFrC"}
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/middleware/compression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,UAAU,CAAA;AAE1D;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAgGrC"}

package/dist/middleware/compression.js

@@ -59,21 +59,36 @@ function compression() {
             res.raw.setHeader('Vary', 'Accept-Encoding');
             // Remove Content-Length since compressed size will differ
             res.raw.removeHeader('Content-Length');
-            // Compress synchronously for small-to-medium payloads to avoid extra async overhead
+            // Compress using hardware-accelerated Rust engine (@exisjs/rs) if available, with graceful zlib fallback
             let compressed;
             try {
                 if (selectedEncoding === 'br') {
-                    compressed = node_zlib_1.default.brotliCompressSync(buf);
+                    // eslint-disable-next-line @typescript-eslint/no-require-imports
+                    const rs = require('@exisjs/rs');
+                    compressed =
+                        typeof rs.brotliCompress === 'function'
+                            ? rs.brotliCompress(buf)
+                            : node_zlib_1.default.brotliCompressSync(buf);
                 }
                 else if (selectedEncoding === 'gzip') {
-                    compressed = node_zlib_1.default.gzipSync(buf);
+                    // eslint-disable-next-line @typescript-eslint/no-require-imports
+                    const rs = require('@exisjs/rs');
+                    compressed =
+                        typeof rs.gzipCompress === 'function'
+                            ? rs.gzipCompress(buf)
+                            : node_zlib_1.default.gzipSync(buf);
                 }
                 else {
-                    compressed = node_zlib_1.default.deflateSync(buf);
+                    // eslint-disable-next-line @typescript-eslint/no-require-imports
+                    const rs = require('@exisjs/rs');
+                    compressed =
+                        typeof rs.deflateCompress === 'function'
+                            ? rs.deflateCompress(buf)
+                            : node_zlib_1.default.deflateSync(buf);
                 }
             }
             catch {
-                // If compression fails, send uncompressed
+                // If native or zlib compression fails, send uncompressed
                 originalEnd(data);
                 return;
             }

package/dist/middleware/compression.js.map

@@ -1 +1 @@
-{"version":3,"file":"compression.js","sourceRoot":"","sources":["../../src/middleware/compression.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compression.js","sourceRoot":"","sources":["../../src/middleware/compression.ts"],"names":[],"mappings":"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"}

package/dist/middleware/middleware.d.ts

@@ -18,6 +18,9 @@ export * from './guard';
 export * from './pipe';
 export declare function serveStatic(root: string, options?: {
     maxAge?: number;
+    etag?: boolean;
+    brotli?: boolean;
+    gzip?: boolean;
 }): Handler;
 export interface ValidateSchema {
     body?: TexEngine<any>;

package/dist/middleware/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACzE,OAAO,EACL,SAAS,EAEV,MAAM,kBAAkB,CAAA;AAKzB,wBAAgB,IAAI,CAAC,MAAM,GAAE,UAAe,GAAG,OAAO,CAwFrD;AAMD,wBAAgB,SAAS,IAAI,OAAO,CAenC;AAID,wBAAgB,aAAa,CAC3B,cAAc,GAAE,MAAM,GAAG,YAAiB,GACzC,OAAO,CAqDT;AAID,eAAO,MAAM,QAAQ,EAAE,OAQtB,CAAA;AAID,OAAO,EAAE,WAAW,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EACL,MAAM,EACN,IAAI,EACJ,OAAO,EACP,GAAG,EACH,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EAAE,gBAAgB,IAAI,MAAM,EAAE,MAAM,UAAU,CAAA;AACrD,OAAO,EAAE,sBAAsB,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAA;AACvE,OAAO,EAAE,kBAAkB,IAAI,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AAEtB,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,OAAO,CA0ET;AAID,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;CACxB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CA8BxD;AAID,wBAAgB,cAAc,IAAI,OAAO,CAKxC;AAED,cAAc,eAAe,CAAA"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACzE,OAAO,EACL,SAAS,EAEV,MAAM,kBAAkB,CAAA;AAKzB,wBAAgB,IAAI,CAAC,MAAM,GAAE,UAAe,GAAG,OAAO,CAoIrD;AAMD,wBAAgB,SAAS,IAAI,OAAO,CAenC;AAID,wBAAgB,aAAa,CAC3B,cAAc,GAAE,MAAM,GAAG,YAAiB,GACzC,OAAO,CAqDT;AAID,eAAO,MAAM,QAAQ,EAAE,OAQtB,CAAA;AAID,OAAO,EAAE,WAAW,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EACL,MAAM,EACN,IAAI,EACJ,OAAO,EACP,GAAG,EACH,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EAAE,gBAAgB,IAAI,MAAM,EAAE,MAAM,UAAU,CAAA;AACrD,OAAO,EAAE,sBAAsB,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAA;AACvE,OAAO,EAAE,kBAAkB,IAAI,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AAEtB,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,OAAO,CAAA;CACV,GACL,OAAO,CAgHT;AAID,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;CACxB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CA8BxD;AAID,wBAAgB,cAAc,IAAI,OAAO,CAKxC;AAED,cAAc,eAAe,CAAA"}

package/dist/middleware/middleware.js

@@ -35,63 +35,100 @@ function cors(config = {}) {
     return (req, res, next) => {
         const reqOrigin = req.get('origin');
         // 1. Resolve Origin
-        let allowOrigin = '';
-        if (origin === '*') {
-            allowOrigin = '*';
-        }
-        else if (typeof origin === 'string') {
-            allowOrigin = origin;
-        }
-        else if (reqOrigin) {
-            if (Array.isArray(origin)) {
-                allowOrigin = origin.some((o) => o instanceof RegExp ? o.test(reqOrigin) : o === reqOrigin)
-                    ? reqOrigin
-                    : '';
+        const applyOriginAndProceed = (allowOrigin) => {
+            if (allowOrigin) {
+                res.set('Access-Control-Allow-Origin', allowOrigin);
             }
-            else if (origin instanceof RegExp) {
-                allowOrigin = origin.test(reqOrigin) ? reqOrigin : '';
+            // 2. Credentials
+            if (credentials) {
+                res.set('Access-Control-Allow-Credentials', 'true');
             }
-            else if (typeof origin === 'function') {
-                allowOrigin = origin(reqOrigin) ? reqOrigin : '';
+            // 3. Exposed Headers
+            if (exposedHeaders && exposedHeaders.length > 0) {
+                res.set('Access-Control-Expose-Headers', exposedHeaders.join(', '));
+            }
+            // 4. Preflight (OPTIONS)
+            if (req.method === 'OPTIONS') {
+                res.set('Access-Control-Allow-Methods', methods.join(', '));
+                const reqHeaders = req.get('access-control-request-headers');
+                if (reqHeaders) {
+                    res.set('Access-Control-Allow-Headers', reqHeaders);
+                }
+                else if (allowedHeaders && allowedHeaders.length > 0) {
+                    res.set('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+                }
+                if (maxAge) {
+                    res.set('Access-Control-Max-Age', String(maxAge));
+                }
+                if (!allowOrigin && reqOrigin) {
+                    if (req.log && typeof req.log.warn === 'function') {
+                        req.log.warn({ origin: reqOrigin }, `[CORS] Rejected preflight request from origin '${reqOrigin}' (not in allowed origins)`);
+                    }
+                }
+                if (config.preflightContinue) {
+                    next();
+                    return;
+                }
+                res.status(204).send('');
+                return;
             }
+            next();
+        };
+        if (origin === '*' || !origin) {
+            applyOriginAndProceed(origin === '*' ? '*' : '');
+            return;
         }
-        if (allowOrigin) {
-            res.set('Access-Control-Allow-Origin', allowOrigin);
+        if (typeof origin === 'string') {
+            applyOriginAndProceed(origin);
+            return;
         }
-        // 2. Credentials
-        if (credentials) {
-            res.set('Access-Control-Allow-Credentials', 'true');
+        if (!reqOrigin) {
+            applyOriginAndProceed('');
+            return;
         }
-        // 3. Exposed Headers
-        if (exposedHeaders && exposedHeaders.length > 0) {
-            res.set('Access-Control-Expose-Headers', exposedHeaders.join(', '));
+        if (Array.isArray(origin)) {
+            const matched = origin.some((o) => o instanceof RegExp ? o.test(reqOrigin) : o === reqOrigin);
+            applyOriginAndProceed(matched ? reqOrigin : '');
+            return;
         }
-        // 4. Preflight (OPTIONS)
-        if (req.method === 'OPTIONS') {
-            res.set('Access-Control-Allow-Methods', methods.join(', '));
-            const reqHeaders = req.get('access-control-request-headers');
-            if (reqHeaders) {
-                res.set('Access-Control-Allow-Headers', reqHeaders);
-            }
-            else if (allowedHeaders && allowedHeaders.length > 0) {
-                res.set('Access-Control-Allow-Headers', allowedHeaders.join(', '));
-            }
-            if (maxAge) {
-                res.set('Access-Control-Max-Age', String(maxAge));
+        if (origin instanceof RegExp) {
+            applyOriginAndProceed(origin.test(reqOrigin) ? reqOrigin : '');
+            return;
+        }
+        if (typeof origin === 'function') {
+            // Check if function accepts a callback (origin, callback)
+            if (origin.length >= 2) {
+                try {
+                    origin(reqOrigin, (err, allow) => {
+                        if (err)
+                            return next(err);
+                        applyOriginAndProceed(allow ? reqOrigin : '');
+                    });
+                }
+                catch (err) {
+                    next(err);
+                }
+                return;
             }
-            if (!allowOrigin && reqOrigin) {
-                if (req.log && typeof req.log.warn === 'function') {
-                    req.log.warn({ origin: reqOrigin }, `[CORS] Rejected preflight request from origin '${reqOrigin}' (not in allowed origins)`);
+            try {
+                const result = origin(reqOrigin);
+                if (result && typeof result.then === 'function') {
+                    ;
+                    result
+                        .then((allow) => applyOriginAndProceed(allow ? reqOrigin : ''))
+                        .catch(next);
+                    return;
                 }
+                applyOriginAndProceed(result ? reqOrigin : '');
+                return;
             }
-            if (config.preflightContinue) {
-                next();
+            catch (err) {
+                next(err);
                 return;
             }
-            res.status(204).send('');
-            return;
         }
-        next();
+        applyOriginAndProceed('');
+        return;
     };
 }
 // ─── Request ID ───────────────────────────────────────────────────────────────
@@ -233,7 +270,23 @@ function serveStatic(root, options = {}) {
             if (!filePath.startsWith(rootPath)) {
                 return next();
             }
-            fs.stat(filePath, (err, stat) => {
+            const acceptEncoding = req.headers['accept-encoding'] || '';
+            // Check for pre-compressed Brotli or Gzip static file if supported
+            let targetPath = filePath;
+            let contentEncoding = null;
+            if (options.brotli !== false &&
+                acceptEncoding.includes('br') &&
+                fs.existsSync(filePath + '.br')) {
+                targetPath = filePath + '.br';
+                contentEncoding = 'br';
+            }
+            else if (options.gzip !== false &&
+                acceptEncoding.includes('gzip') &&
+                fs.existsSync(filePath + '.gz')) {
+                targetPath = filePath + '.gz';
+                contentEncoding = 'gzip';
+            }
+            fs.stat(targetPath, (err, stat) => {
                 if (err || !stat.isFile()) {
                     return next();
                 }
@@ -241,14 +294,27 @@ function serveStatic(root, options = {}) {
                 const mime = mimeTypes[ext] || 'application/octet-stream';
                 res.set('Content-Type', mime);
                 res.set('Content-Length', String(stat.size));
+                if (contentEncoding) {
+                    res.set('Content-Encoding', contentEncoding);
+                    res.set('Vary', 'Accept-Encoding');
+                }
                 if (options.maxAge !== undefined) {
                     res.set('Cache-Control', `public, max-age=${options.maxAge}`);
                 }
+                if (options.etag !== false) {
+                    // Strong ETag based on mtime and size
+                    const etag = `"${stat.size.toString(16)}-${stat.mtime.getTime().toString(16)}"`;
+                    res.set('ETag', etag);
+                    if (req.headers['if-none-match'] === etag) {
+                        res.status(304).send('');
+                        return;
+                    }
+                }
                 if (req.method === 'HEAD') {
                     res.status(200).send('');
                     return;
                 }
-                const sendStream = fs.createReadStream(filePath);
+                const sendStream = fs.createReadStream(targetPath);
                 const abortHandler = () => sendStream.destroy();
                 req.raw.on('aborted', abortHandler);
                 req.raw.on('close', abortHandler);