@stonyx/rest-server 0.2.1-alpha.4 → 0.2.1-alpha.6

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.2.1-alpha.4",
+  "version": "0.2.1-alpha.6",
   "description": "Rest Server Module for Stonyx Framework",
   "repository": {
     "type": "git",
@@ -20,6 +20,11 @@
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "files": [
+    "src",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -27,10 +32,10 @@
   "dependencies": {
     "cors": "^2.8.5",
     "express": "^5.1.0",
-    "stonyx": "0.2.3-beta.4"
+    "stonyx": "0.2.3-beta.11"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.4",
+    "@stonyx/utils": "0.2.3-beta.7",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/src/request.js

@@ -59,7 +59,7 @@ export default class Request {
 
           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 { redirect } = getState(req);
           if (redirect) return res.redirect(redirect);

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,150 +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                     |
-| `trustProxy`        | **Boolean**       | `false`                       | `REST_TRUST_PROXY=true` to enable           | Trust reverse proxy headers (`X-Forwarded-Proto`) for correct protocol detection behind load balancers |
-| `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