@stonyx/rest-server 0.2.1-beta.8 → 0.2.1-beta.80

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-rest-server/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-rest-server/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/rest-server.svg)](https://www.npmjs.com/package/@stonyx/rest-server)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # @stonyx/rest-server
 
 REST server module for the [Stonyx framework](https://github.com/abofs/stonyx), providing dynamic route registration and built-in request handling with optional authentication hooks.
@@ -75,8 +79,21 @@ Configuration is read from `stonyx/config` under `restServer`:
 |      `origin`     | **String \| Array** | `'*'`       | CORS origin(s) allowed                                     |
 |    `methods`      | **String**          | `'GET,POST,PATCH,PUT,DELETE'` | CORS allowed methods                              |
 | `enableHealthCheck` |   **Boolean**     | `true`      | Register `GET /health` endpoint (disable via `REST_HEALTH_CHECK_DISABLE=true`) |
+|  `trustProxy`   |     **Boolean**     | `false`     | Trust reverse proxy headers (e.g. `X-Forwarded-Proto`). Enable via `REST_TRUST_PROXY=true` when running behind a load balancer such as AWS ALB/ELB to ensure correct protocol detection. |
 |    `statusMap`    |      **Object**     | `{}`        | Optional mapping of HTTP status codes to custom messages   |
 
+### Running Behind a Load Balancer
+
+When your application runs behind a reverse proxy or load balancer (e.g. AWS ALB/ELB), the load balancer terminates SSL and forwards requests to your server over HTTP internally. This means Express sees `http` as the protocol even though the original client request used `https`.
+
+To fix this, enable the `trustProxy` option:
+
+```bash
+REST_TRUST_PROXY=true
+```
+
+This tells Express to trust the `X-Forwarded-Proto` header set by the load balancer, so `request.protocol` correctly returns `https`. This is important for any functionality that generates URLs based on the incoming request protocol, such as JSON:API relationship links.
+
 ## Request Class
 
 The `Request` class provides a structured way to define route handlers and authorization hooks. Route classes extend `Request` and define:

package/config/environment.js

@@ -3,15 +3,19 @@ const {
   REST_CORS_METHODS,
   REST_HEALTH_CHECK_DISABLE,
   REST_PORT,
-  REST_REQUEST_PATH
-} = process;
+  REST_REQUEST_PATH,
+  REST_TRUST_PROXY
+} = process.env;
 
-export default {
+const config = {
   enableHealthCheck: REST_HEALTH_CHECK_DISABLE !== 'true',
   origin: REST_CORS_ORIGIN ?? '*',
   methods: REST_CORS_METHODS ?? 'GET,POST,PATCH,PUT,DELETE',
   dir: REST_REQUEST_PATH ?? './requests',
   port: REST_PORT ?? 2666,
+  trustProxy: REST_TRUST_PROXY === 'true',
   logColor: 'yellow',
   logMethod: 'api'
 };
+
+export default config;

package/dist/main.d.ts

@@ -0,0 +1,18 @@
+import { type Express } from 'express';
+import type { Server } from 'http';
+export { default as Request } from './request.js';
+export default class RestServer {
+    static instance: RestServer;
+    api: Express;
+    server: Server;
+    constructor();
+    static close(): void;
+    init(): Promise<void>;
+    setupRouter(): Promise<void>;
+    setupGlobalMiddleware(): void;
+    mountRoute(routeClassUntyped: unknown, { name, options }: {
+        name: string;
+        options?: unknown;
+    }): void;
+}
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAiBA,OAAgB,EAAE,KAAK,OAAO,EAAoE,MAAM,SAAS,CAAC;AAIlH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC;IAE5B,GAAG,EAAG,OAAO,CAAC;IACd,MAAM,EAAG,MAAM,CAAC;;IAShB,MAAM,CAAC,KAAK,IAAI,IAAI;IAQd,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAerB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAelC,qBAAqB,IAAI,IAAI;IAW7B,UAAU,CAAC,iBAAiB,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAarG"}

package/dist/main.js

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import cors from 'cors';
+import express from 'express';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { forEachFileImport } from '@stonyx/utils/file';
+export { default as Request } from './request.js';
+export default class RestServer {
+    static instance;
+    api;
+    server;
+    constructor() {
+        if (RestServer.instance)
+            return RestServer.instance;
+        RestServer.instance = this;
+        this.api = express();
+    }
+    static close() {
+        if (!RestServer.instance)
+            throw new Error('RestServer has not been initialized yet');
+        const { server } = RestServer.instance;
+        server.closeAllConnections();
+        server.close();
+    }
+    async init() {
+        // Self-register so log.api works even when @stonyx/rest-server is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'yellow', logMethod = 'api' } = config.restServer;
+        log.defineType(logMethod, logColor);
+        await this.setupRouter();
+        const { port } = config.restServer;
+        // start REST server
+        this.server = this.api.listen(port);
+        log.title(`API Server is listening on port ${port}`);
+    }
+    async setupRouter() {
+        const { camelCaseRoutes, dir, enableHealthCheck } = config.restServer;
+        this.setupGlobalMiddleware();
+        try {
+            await forEachFileImport(dir, this.mountRoute.bind(this), { rawName: !camelCaseRoutes, ignoreAccessFailure: true });
+            if (enableHealthCheck)
+                this.api.get('/health', (_req, res) => res.sendStatus(200));
+        }
+        catch (error) {
+            if (config.debug)
+                console.log(error);
+            log.error(`Unable to dynamically configure routes from files in ${dir}`);
+            throw new Error(`Unable to dynamically configure routes from files in ${dir}`);
+        }
+    }
+    setupGlobalMiddleware() {
+        const { origin, methods, trustProxy } = config.restServer;
+        if (trustProxy)
+            this.api.set('trust proxy', true);
+        this.api.use([
+            cors({ origin, methods }),
+            express.json()
+        ]);
+    }
+    mountRoute(routeClassUntyped, { name, options }) {
+        const routeClass = routeClassUntyped;
+        const { api } = this;
+        const classInstance = new routeClass(options);
+        const route = name === 'index' ? '/' : `/${name}`;
+        const { expressInstance } = classInstance;
+        classInstance.registerCalls();
+        expressInstance.mountpath = route;
+        // Mount handler to main api instance
+        api.use(route, expressInstance);
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

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

package/dist/request.d.ts

@@ -0,0 +1,16 @@
+import { type Request as ExpressRequest, type Response as ExpressResponse, type Express } from 'express';
+export type RequestState = Record<string, unknown>;
+export type RequestHandler = (req: ExpressRequest, state: RequestState) => unknown | Promise<unknown>;
+export type AuthHandler = (req: ExpressRequest, state: RequestState) => number | undefined;
+export type RouteHandlers = Record<string, Record<string, RequestHandler | RequestHandler[]>>;
+export default class Request {
+    static stateProp: string;
+    static getState(req: ExpressRequest): RequestState;
+    static sendStatusResponse(res: ExpressResponse, status: number): void;
+    expressInstance: Express;
+    handlers: RouteHandlers;
+    auth?: AuthHandler;
+    constructor();
+    registerCalls(): void;
+}
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,OAAO,IAAI,cAAc,EAAE,KAAK,QAAQ,IAAI,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAMlH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AACtG,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;AAC3F,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC,CAAC,CAAC;AAE9F,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,SAAS,SAAmB;IAEnC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,YAAY;IASlD,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAWrE,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAG,aAAa,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,CAAC;;IAS3B,aAAa,IAAI,IAAI;CAqDtB"}

package/dist/request.js

@@ -0,0 +1,87 @@
+import express from 'express';
+import config from 'stonyx/config';
+import { makeArray } from '@stonyx/utils/object';
+const METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
+export default class Request {
+    static stateProp = '__stonyxState';
+    static getState(req) {
+        const { stateProp } = Request;
+        const record = req;
+        if (record[stateProp] !== undefined)
+            return record[stateProp];
+        record[stateProp] = {};
+        return record[stateProp];
+    }
+    static sendStatusResponse(res, status) {
+        const statusMap = config.restServer?.statusMap ?? {};
+        const message = statusMap[status] || '';
+        if (message) {
+            res.status(status).send(message);
+        }
+        else {
+            res.sendStatus(status);
+        }
+    }
+    expressInstance;
+    handlers;
+    constructor() {
+        const api = express();
+        api.disable('x-powered-by');
+        this.expressInstance = api;
+    }
+    registerCalls() {
+        const { expressInstance } = this;
+        const { getState, sendStatusResponse } = Request;
+        for (const [method, handlers] of Object.entries(this.handlers)) {
+            if (!METHODS.has(method)) {
+                console.warn(`Method "${method}" is not a valid HTTP method. Skipping...`);
+                continue;
+            }
+            for (const [route, handler] of Object.entries(handlers)) {
+                expressInstance[method](route, async (req, res) => {
+                    // Run auth after route matching so request.params is populated
+                    if (this.auth) {
+                        const status = this.auth(req, getState(req));
+                        if (status)
+                            return sendStatusResponse(res, status);
+                    }
+                    const callStack = [...makeArray(handler)];
+                    const mainCall = callStack.pop();
+                    let response;
+                    // Run middleware
+                    while (callStack.length) {
+                        response = await callStack.shift().bind(this)(req, getState(req));
+                        if (response !== undefined)
+                            break;
+                    }
+                    if (response === undefined)
+                        response = await mainCall(req, getState(req));
+                    if (Number.isInteger(response))
+                        return sendStatusResponse(res, response);
+                    // Handle redirect if set via call state object
+                    const state = getState(req);
+                    const { redirect } = state;
+                    if (redirect)
+                        return res.redirect(redirect);
+                    // Handle pipe if set via call state object
+                    const { pipe } = state;
+                    if (pipe) {
+                        const { headers, source } = pipe;
+                        if (headers)
+                            for (const [key, value] of Object.entries(headers))
+                                res.set(key, value);
+                        return source.pipe(res);
+                    }
+                    if (response === undefined) {
+                        res.sendStatus(200);
+                        return;
+                    }
+                    if (typeof response !== 'object')
+                        return sendStatusResponse(res, 500);
+                    res.send(response);
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=request.js.map

package/dist/request.js.map

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

package/package.json

@@ -4,22 +4,31 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.8",
+  "version": "0.2.1-beta.80",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",
     "url": "https://github.com/abofs/stonyx-rest-server"
   },
-  "main": "src/main.js",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
   "type": "module",
   "exports": {
-    ".": "./src/main.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    }
   },
   "author": "Stone Costa",
   "license": "Apache-2.0",
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "files": [
+    "dist",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -27,14 +36,23 @@
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "stonyx": "0.2.3-beta.3"
+    "stonyx": "0.2.3-beta.76"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.4",
+    "@stonyx/utils": "0.2.3-beta.26",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && pnpm typecheck && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
   }
 }

package/.claude/improvements.md

@@ -1,44 +0,0 @@
-# Improvement Opportunities
-
-## 1. `new express()` in RestServer constructor
-
-**File**: `src/main.js`, line 30
-
-```js
-this.api = new express();
-```
-
-Express 5 (which this project targets via `"express": "^5.1.0"`) documents calling `express()` as a plain function, not as a constructor with `new`. While `new express()` works in practice because the function returns a new object regardless, it is unconventional and may break if Express ever enforces non-constructor semantics. Consider changing to:
-
-```js
-this.api = express();
-```
-
-Note: The `Request` class in `src/request.js` line 26 already uses the correct pattern (`const api = express();` without `new`).
-
-## 2. `setupGlobalMiddleware` is `async` but contains no awaits
-
-**File**: `src/main.js`, lines 63-70
-
-```js
-async setupGlobalMiddleware() {
-  const { origin, methods } = config.restServer;
-
-  this.api.use([
-    cors({ origin, methods }),
-    express.json()
-  ]);
-}
-```
-
-The `async` keyword is unnecessary here since the method body contains no `await` expressions and `app.use()` is synchronous. The `async` keyword causes the method to return a `Promise` wrapping `undefined`, but the caller (`setupRouter`) does not `await` it either — it calls `this.setupGlobalMiddleware()` without `await` on line 52. Removing `async` would make the intent clearer.
-
-## 3. `logMethod` config option is not used in rest-server source
-
-**File**: `config/environment.js`, line 16
-
-```js
-logMethod: 'api'
-```
-
-The `logMethod` property is defined in the default config but is never referenced anywhere in `src/main.js` or `src/request.js`. It is likely consumed by the Stonyx framework core (`stonyx/log`) for registering a named log method, but this should be verified. If it is indeed framework-level plumbing, consider documenting that it is a Stonyx convention rather than a rest-server feature. If it is unused, consider removing it to reduce config surface area.

package/.claude/project-structure.md

@@ -1,149 +0,0 @@
-# @stonyx/rest-server — Project Structure
-
-## Overview
-
-REST server module for the Stonyx framework. Provides dynamic route registration from a file directory, built-in CORS/JSON middleware, per-route authorization hooks, and a structured `Request` base class for defining handlers.
-
-- **Package**: `@stonyx/rest-server` (v0.2.1-beta.1)
-- **License**: Apache-2.0
-- **Entry point**: `src/main.js`
-- **Module type**: ESM (`"type": "module"`)
-- **Node version**: v24.13.0 (per `.nvmrc`)
-- **Package manager**: pnpm
-
-## Architecture
-
-### RestServer (src/main.js)
-
-Singleton class wrapping an Express 5 instance.
-
-- **Constructor** — enforces singleton via `RestServer.instance`; creates the Express app with `new express()`
-- **`init()`** — calls `setupRouter()`, then starts listening on the configured port
-- **`setupRouter()`** — calls `setupGlobalMiddleware()`, then uses `forEachFileImport` (from `@stonyx/utils/file`) to dynamically import all files in the configured `dir` and mount each as a route via `mountRoute()`. Optionally registers a `/health` endpoint.
-- **`setupGlobalMiddleware()`** — attaches `cors()` and `express.json()` middleware to the Express app
-- **`mountRoute(routeClass, { name, options })`** — instantiates the imported Request subclass, wires up the `authorization` middleware if present, calls `registerCalls()`, and mounts the sub-app at `/<filename>`
-- **`RestServer.close()`** — static method to close the server
-
-### Request (src/request.js)
-
-Base class for route definitions. Each file in the requests directory exports a class extending `Request`.
-
-- **Constructor** — creates a child Express instance with `x-powered-by` disabled
-- **`handlers`** — instance property: object mapping HTTP methods (`get`, `post`, `put`, `delete`, `patch`) to route-path/handler pairs
-- **`auth(req, state)`** — optional hook. Return an integer status code to reject the request; return nothing to allow it through.
-- **`authorization(req, res, next)`** — wrapper that calls `auth()` and short-circuits with a status response if it returns a code
-- **`registerCalls()`** — iterates `handlers`, registers each route on the child Express instance. Supports:
-  - Single handler function or array (last element is the main handler, preceding elements are middleware)
-  - Middleware functions are bound to the class instance and executed in order
-  - Integer return = status code response (via `sendStatusResponse`)
-  - Object return = JSON response
-  - `undefined` return = 200 OK
-  - Pipe support via `state.pipe` (sets headers and pipes a stream)
-- **`Request.getState(req)`** — attaches/retrieves a `__stonyxState` object on the Express request
-- **`Request.sendStatusResponse(res, status)`** — sends status with optional custom message from `config.restServer.statusMap`
-
-Valid HTTP methods (enforced): `get`, `post`, `put`, `delete`, `patch`
-
-## Configuration Reference
-
-From `config/environment.js`. All values are overridable via environment variables.
-
-| Option              | Type              | Default                       | Env Var                    | Description                                                     |
-|---------------------|-------------------|-------------------------------|----------------------------|-----------------------------------------------------------------|
-| `enableHealthCheck` | **Boolean**       | `true`                        | `REST_HEALTH_CHECK_DISABLE=true` to disable | Registers `GET /health` returning 200                     |
-| `origin`            | **String**        | `'*'`                         | `REST_CORS_ORIGIN`         | CORS allowed origin(s)                                          |
-| `methods`           | **String**        | `'GET,POST,PATCH,PUT,DELETE'` | `REST_CORS_METHODS`        | CORS allowed methods                                            |
-| `dir`               | **String**        | `'./requests'`                | `REST_REQUEST_PATH`        | Directory containing Request class files to mount as routes     |
-| `port`              | **Number/String** | `2666`                        | `REST_PORT`                | Port the REST server listens on                                 |
-| `logColor`          | **String**        | `'yellow'`                    | —                          | Console log color for this module (Stonyx logging integration)  |
-| `logMethod`         | **String**        | `'api'`                       | —                          | Log method name (Stonyx logging integration)                    |
-
-Additional config used (not rest-server-specific):
-- `config.debug` (top-level Stonyx config) — if truthy, logs errors during route setup
-- `config.restServer.statusMap` (optional, no default in environment.js) — maps status codes to custom message strings
-- `config.restServer.camelCaseRoutes` (optional, no default in environment.js) — when falsy, passes `rawName: true` to `forEachFileImport` so filenames are used as-is for route paths
-
-## Test Structure
-
-Tests use **QUnit** and run via `stonyx test` (the `npm test` script).
-
-### test/config/environment.js
-Overrides `restServer.dir` to `'./test/sample/requests'` so tests load sample request classes.
-
-### test/unit/request-test.js
-Unit tests for `Request` static methods:
-- `getState` — creates/returns state object on request
-- `sendStatusResponse` — sends status with optional `statusMap` message
-
-### test/integration/rest-server-test.js
-Integration tests that boot the full server and make HTTP requests:
-- 404 for non-existent routes
-- `/public` — JSON response, 200 OK default, URL params, middleware (success/failure), `this` binding for handlers and middleware
-- `/private` — authenticated success, auth hook rejection (505)
-- `/health` — health check endpoint returns 200
-
-### test/sample/requests/
-Sample Request subclasses used by integration tests:
-- `public.js` — `PublicRequest` with various GET handlers demonstrating middleware, params, binding
-- `private.js` — `PrivateRequest` with `auth()` hook that rejects `/failure` with 505
-
-## CI/CD
-
-### .github/workflows/ci.yml
-Runs on pull requests to `dev` and `main`. Delegates to shared workflow at `abofs/stonyx-workflows`.
-
-### .github/workflows/publish.yml
-Publishes to NPM. Triggered by:
-- `workflow_dispatch` with version-type selection (patch/minor/major) or custom version
-- Pull requests to `main`/`dev`
-- Pushes to `main`
-
-Delegates to `abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main`.
-
-## File Structure
-
-```
-stonyx-rest-server/
-├── .claude/
-│   ├── improvements.md
-│   └── project-structure.md      # this file
-├── .github/
-│   └── workflows/
-│       ├── ci.yml                 # PR CI — delegates to shared workflow
-│       └── publish.yml            # NPM publish — delegates to shared workflow
-├── config/
-│   └── environment.js             # Default config with env var overrides
-├── src/
-│   ├── main.js                    # RestServer class (singleton, Express wrapper)
-│   └── request.js                 # Request base class (handler registration, auth hook)
-├── test/
-│   ├── config/
-│   │   └── environment.js         # Test config override (dir → test/sample/requests)
-│   ├── integration/
-│   │   └── rest-server-test.js    # Integration tests (QUnit)
-│   ├── sample/
-│   │   └── requests/
-│   │       ├── private.js         # Sample private request with auth hook
-│   │       └── public.js          # Sample public request with middleware demos
-│   └── unit/
-│       └── request-test.js        # Unit tests for Request statics (QUnit)
-├── .gitignore
-├── .npmignore
-├── .nvmrc                         # Node v24.13.0
-├── LICENSE.md                     # Apache 2.0
-├── package.json
-├── pnpm-lock.yaml
-└── README.md
-```
-
-## Dependencies
-
-### Runtime
-- `cors` ^2.8.5 — CORS middleware
-- `express` ^5.1.0 — HTTP framework
-- `stonyx` (local link) — Framework core (config, logging)
-
-### Dev
-- `@stonyx/utils` (local link) — Utility functions (file import, object helpers)
-- `qunit` ^2.24.1 — Test framework
-- `sinon` ^21.0.0 — Test stubs/spies

package/.github/workflows/ci.yml

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,51 +0,0 @@
-name: Publish to NPM
-
-on:
-  repository_dispatch:
-    types: [cascade-publish]
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-  pull_request:
-    types: [opened, synchronize, reopened]
-    branches: [main]
-  push:
-    branches: [main]
-
-concurrency:
-  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
-  cancel-in-progress: false
-
-permissions:
-  contents: write
-  id-token: write
-  pull-requests: write
-
-jobs:
-  publish:
-    if: "!contains(github.event.head_commit.message, '[skip ci]')"
-    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
-    with:
-      version-type: ${{ github.event.inputs.version-type }}
-      custom-version: ${{ github.event.inputs.custom-version }}
-      cascade-source: ${{ github.event.client_payload.source_package || '' }}
-    secrets: inherit
-
-  cascade:
-    needs: publish
-    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
-    with:
-      package-name: ${{ needs.publish.outputs.package-name }}
-      published-version: ${{ needs.publish.outputs.published-version }}
-    secrets: inherit

package/src/main.js

@@ -1,89 +0,0 @@
-/*
- * Copyright 2025 Stone Costa
- *
- * Licensed under the Apache License, Version 2.0 (the 'License');
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import cors from 'cors';
-import express from 'express';
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import { forEachFileImport } from '@stonyx/utils/file';
-
-export { default as Request } from './request.js';
-
-export default class RestServer {
-  constructor() {
-    if (RestServer.instance) return RestServer.instance;
-    RestServer.instance = this;
-
-    this.api = new express();
-  }
-
-  static close() {
-    if (!RestServer.instance) throw new Error('RestServer has not been initialized yet');
-
-    RestServer.instance.server.close();
-  }
-  
-  async init() {
-    await this.setupRouter();
-    
-    const { port } = config.restServer;
-
-    // start REST server
-    this.server = this.api.listen(port);
-    log.title(`API Server is listening on port ${port}`);
-  }
-
-  async setupRouter() {
-    const { camelCaseRoutes, dir, enableHealthCheck } = config.restServer;
-    this.setupGlobalMiddleware();
-
-    try {
-      await forEachFileImport(dir, this.mountRoute.bind(this), { rawName: !camelCaseRoutes, ignoreAccessFailure: true });
-
-      if (enableHealthCheck) this.api.get('/health', (_req, res) => res.sendStatus(200));
-    } catch (error) {
-      if (config.debug) console.log(error);
-      throw log.error(`Unable to dynamically configure routes from files in ${dir}`);
-    }
-  }
-
-  async setupGlobalMiddleware() {
-    const { origin, methods } = config.restServer;
-
-    this.api.use([
-      cors({ origin, methods }),
-      express.json()
-    ]);
-  }
-
-  async mountRoute(routeClass, { name, options }) {
-    const { api } = this;
-    const classInstance = new routeClass(options);
-    const route = name === 'index' ? '/' : `/${name}`;
-    const { expressInstance, authorization } = classInstance;
-    
-    const routeCalls = [ expressInstance ];
-
-    // Assign auth callback if it exists
-    if (authorization) routeCalls.unshift(authorization.bind(classInstance));
-
-    classInstance.registerCalls();
-    expressInstance.mountpath = route;
-    
-    // Mount handler to main api instance
-    api.use(route, ...routeCalls);
-  }
-}

package/src/request.js

@@ -1,85 +0,0 @@
-import express from 'express';
-import config from 'stonyx/config';
-import { makeArray } from '@stonyx/utils/object';
-
-const METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
-
-export default class Request {
-  static stateProp = '__stonyxState';
-
-  static getState(req) {
-    const { stateProp } = Request;
-    if (req[stateProp] !== undefined) return req[stateProp];
-    
-    req[stateProp] = {};
-    return req[stateProp];
-  }
-
-  static sendStatusResponse(res, status) {
-    const statusMap = config.restServer?.statusMap || {};
-    const message = statusMap[status] || '';
-  
-    return message ? res.status(status).send(message) : res.sendStatus(status);
-  }
-
-  constructor() {
-    const api = express();
-    api.disable('x-powered-by');
-    
-    this.expressInstance = api;
-  }
-
-  // auth hook wrapper
-  authorization(req, res, next) {
-    if (!this.auth) return next();
-
-    const status = this.auth(req, Request.getState(req));
-    if (status) return Request.sendStatusResponse(res, status);
-
-    next();
-  }
-
-  registerCalls() {
-    const { expressInstance } = this;
-    const { getState } = Request;
-    
-    for (const [method, handlers] of Object.entries(this.handlers)) {
-      if (!METHODS.has(method)) {
-        console.warn(`Method "${method}" is not a valid HTTP method. Skipping...`);
-        continue;
-      }
-
-      for (const [route, handler] of Object.entries(handlers)) {
-        expressInstance[method](route, async (req, res) => {
-          const callStack = [...makeArray(handler)];
-          const mainCall = callStack.pop();
-          const { sendStatusResponse } = Request;
-          let response;
-
-          // Run middleware
-          while(callStack.length) {
-            response = await callStack.shift().bind(this)(req, getState(req));
-            if (response !== undefined) break;
-          }
-
-          if (response === undefined) response = await mainCall(req, getState(req));
-          if (Number.isInteger(response)) return sendStatusResponse(res, response);
-          
-          // Handle pipe if set via call state object
-          const { pipe } = getState(req);
-          if (pipe) {
-            const { headers, source } = pipe;
-
-            if (headers) for (const [key, value] of Object.entries(headers)) res.set(key, value);
-            return source.pipe(res);
-          }
-
-          if (response === undefined) return res.sendStatus(200);
-          if (typeof response !== 'object') return sendStatusResponse(res, 500);
-
-          res.send(response);
-        });
-      }
-    }
-  }
-}