@stonyx/rest-server 0.2.1-beta.0 → 0.2.1-beta.2

package/.claude/improvements.md

@@ -0,0 +1,44 @@
+# 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

@@ -0,0 +1,149 @@
+# @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/publish.yml

@@ -1,6 +1,8 @@
 name: Publish to NPM
 
 on:
+  repository_dispatch:
+    types: [cascade-publish]
   workflow_dispatch:
     inputs:
       version-type:
@@ -17,10 +19,14 @@ on:
         type: string
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: [main, dev]
+    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
@@ -28,8 +34,18 @@ permissions:
 
 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/README.md

@@ -41,16 +41,13 @@ export default {
 };
 ```
 
-Then initialize the Stonyx framework, which auto-initializes all of its modules, including `@stonyx/rest-server`:
+Then run the application via the Stonyx CLI, which auto-initializes all modules including the REST server:
 
-```js
-import Stonyx from 'stonyx';
-import config from './config/environment.js';
-
-new Stonyx(config);
+```bash
+stonyx serve
 ```
 
-For further framework initialization instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
+For further framework instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
 
 ### Optional Direct Usage
 
@@ -72,12 +69,13 @@ Configuration is read from `stonyx/config` under `restServer`:
 
 |       Option      |         Type        | Default     | Description                                                |
 | :---------------: | :-----------------: | :---------- | :--------------------------------------------------------- |
-|       `dir`       |      **String**     | `undefined` | Directory containing request classes to mount as routes    |
+|       `dir`       |      **String**     | `'./requests'` | Directory containing request classes to mount as routes    |
 | `camelCaseRoutes` |     **Boolean**     | `true`      | Convert filenames to camelCase when generating route paths |
-|       `port`      |      **Number**     | `3000`      | Port to listen on                                          |
+|       `port`      |      **Number**     | `2666`      | Port to listen on                                          |
 |      `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`) |
 |    `statusMap`    |      **Object**     | `{}`        | Optional mapping of HTTP status codes to custom messages   |
-|      `debug`      |     **Boolean**     | `false`     | Enable debug logging during route setup                    |
 
 ## Request Class
 
@@ -135,10 +133,6 @@ project-root/
 
 The `RestServer` will automatically mount these routes using the filenames as paths (`/public` and `/private` by default, or camelCased if configured).
 
-Perfect! Here’s a self-contained **“Example Requests”** section with sample `curl` calls:
-
----
-
 ### Example Requests
 
 Assuming you have `public.js` and `private.js` routes mounted, you can test them like this:

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-beta.0",
+  "version": "0.2.1-beta.2",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",
@@ -27,14 +27,14 @@
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "stonyx": "^0.2.2"
+    "stonyx": "0.2.3-beta.1"
   },
   "devDependencies": {
-    "@stonyx/utils": "^0.2.2",
+    "@stonyx/utils": "0.2.3-beta.2",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },
   "scripts": {
-    "test": "qunit --require ./stonyx-bootstrap.cjs"
+    "test": "stonyx test"
   }
 }

package/stonyx-bootstrap.cjs

@@ -1,12 +0,0 @@
-/**
- * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
- */
-const { default:Stonyx } = require('stonyx');
-const { default:config } = require('./config/environment.js');
-
-// Override dir for tests
-config.dir = './test/sample/requests';
-
-new Stonyx(config, __dirname);
-
-module.exports = Stonyx;