@stonyx/rest-server 0.2.1-alpha.34 → 0.2.1-alpha.36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -4
- package/dist/main.d.ts +1 -0
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -15,11 +15,36 @@ REST server module for the [Stonyx framework](https://github.com/abofs/stonyx),
|
|
|
15
15
|
* **Singleton server:** Only one RestServer instance runs, preventing accidental multiple listeners.
|
|
16
16
|
* **Framework integration:** Works seamlessly as part of the Stonyx framework—auto-initialized with the rest of your modules.
|
|
17
17
|
|
|
18
|
-
##
|
|
18
|
+
## Exports
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
| Import path | What it exports |
|
|
21
|
+
| :--- | :--- |
|
|
22
|
+
| `@stonyx/rest-server` | `RestServer` (default), `Request` (named); types `RouteHandlers`, `RequestHandler`, `AuthHandler`, `RequestState` |
|
|
21
23
|
|
|
22
|
-
|
|
24
|
+
There are no subpath exports.
|
|
25
|
+
|
|
26
|
+
## Samples
|
|
27
|
+
|
|
28
|
+
The request classes in [`test/sample/requests/`](https://github.com/abofs/stonyx-rest-server/tree/dev/test/sample/requests) are the canonical usage reference. They import only `@stonyx/rest-server`, so you can copy them into your app's `requests/` directory as TypeScript, or as JavaScript by deleting the type annotations. [`test/integration/sample-patterns-test.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/integration/sample-patterns-test.ts) exercises each one over HTTP, and [`test/unit/sample-imports-test.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/unit/sample-imports-test.ts) fails if a sample imports anything a consumer cannot resolve. They are not included in the npm package.
|
|
29
|
+
|
|
30
|
+
| How do I… | Sample |
|
|
31
|
+
| :--- | :--- |
|
|
32
|
+
| Run the same middleware (a version gate, say) in front of many routes, and return my own status and JSON body from it | [`base/api-request.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/sample/requests/base/api-request.ts): async middleware added to `this.expressInstance` in the constructor of a base class. Subclasses inherit it. There is no global request hook; this is the pattern |
|
|
33
|
+
| Share one `auth` hook across request classes | [`base/api-request.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/sample/requests/base/api-request.ts), extended by [`accounts.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/sample/requests/accounts.ts). Keep base classes in a subdirectory: route discovery does not recurse, so they are never mounted |
|
|
34
|
+
| Do async work (a lookup) before a handler, and stop the request if it fails | [`accounts.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/sample/requests/accounts.ts): handler-array middleware is awaited; return a status to stop, or set `state` and return `undefined` to continue |
|
|
35
|
+
| Set response headers, or a status other than 200 with a JSON body | [`widgets.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/sample/requests/widgets.ts): `request.res` in a handler for one route, `this.expressInstance` middleware for every route in the class |
|
|
36
|
+
| Use middleware, URL params and `this` in handlers | [`public.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/sample/requests/public.ts) |
|
|
37
|
+
|
|
38
|
+
Two contracts the samples rely on, both pinned by `sample-patterns-test.ts`:
|
|
39
|
+
|
|
40
|
+
* `auth(request, state)` is synchronous. A returned Promise is not awaited; the request fails with **500** whatever the Promise resolves to. Do async checks in middleware.
|
|
41
|
+
* The last function of a route is called without binding `this`. Use an arrow function (as the samples do) to reach the class instance; a method reference fails with 500. Middleware functions are bound.
|
|
42
|
+
|
|
43
|
+
`private.ts` carries one deliberately invalid entry (`someInvalidMethod`) that the suite uses to check unknown methods are skipped. Do not copy it.
|
|
44
|
+
|
|
45
|
+
## Security notes
|
|
46
|
+
|
|
47
|
+
[`docs/security.md`](https://github.com/abofs/stonyx-rest-server/blob/dev/docs/security.md) covers the security-relevant behaviour: what an `auth` return value allows (any falsy value, including `0`, lets the request through; a Promise does not), unchecked `state.redirect` targets, the `'*'` CORS default, `trustProxy`, and the `X-Powered-By` header. Read it before you write an `auth` hook or deploy.
|
|
23
48
|
|
|
24
49
|
## RestServer
|
|
25
50
|
|
|
@@ -218,7 +243,7 @@ export default class MyRequest extends Request {
|
|
|
218
243
|
### Handler Features
|
|
219
244
|
|
|
220
245
|
* Middleware support by passing an array of functions for a route
|
|
221
|
-
*
|
|
246
|
+
* Middleware functions are called with `this` bound to the request class; the final handler is not bound, so write it as an arrow function
|
|
222
247
|
* Returns integers as HTTP status codes
|
|
223
248
|
* Returns objects as JSON responses
|
|
224
249
|
* Undefined responses default to `200 OK`
|
package/dist/main.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type Express } from 'express';
|
|
2
2
|
import type { Server } from 'http';
|
|
3
3
|
export { default as Request } from './request.js';
|
|
4
|
+
export type { AuthHandler, RequestHandler, RequestState, RouteHandlers } from './request.js';
|
|
4
5
|
export default class RestServer {
|
|
5
6
|
static instance: RestServer;
|
|
6
7
|
api: Express;
|
package/dist/main.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
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;
|
|
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;AAClD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7F,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC;IAE5B,GAAG,EAAG,OAAO,CAAC;IACd,MAAM,EAAG,MAAM,CAAC;;IAwBhB,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.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,OAA2F,MAAM,SAAS,CAAC;AAClH,OAAO,MAAM,MAAM,eAAe,CAAC;AACnC,OAAO,GAAG,MAAM,YAAY,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,OAA2F,MAAM,SAAS,CAAC;AAClH,OAAO,MAAM,MAAM,eAAe,CAAC;AACnC,OAAO,GAAG,MAAM,YAAY,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAGlD,MAAM,CAAC,OAAO,OAAO,UAAU;IAC7B,MAAM,CAAC,QAAQ,CAAa;IAE5B,GAAG,CAAW;IACd,MAAM,CAAU;IAEhB;QACE,IAAI,UAAU,CAAC,QAAQ;YAAE,OAAO,UAAU,CAAC,QAAQ,CAAC;QACpD,UAAU,CAAC,QAAQ,GAAG,IAAI,CAAC;QAE3B,sEAAsE;QACtE,0EAA0E;QAC1E,uEAAuE;QACvE,qEAAqE;QACrE,iFAAiF;QACjF,MAAM,mBAAmB,GAAG,MAAM,CAAC,UAAU,EAAE,mBAAmB,KAAK,KAAK,CAAC;QAE7E,IAAI,CAAC,GAAG,GAAG,OAAO,EAAE,CAAC;QAErB,qEAAqE;QACrE,mEAAmE;QACnE,2EAA2E;QAC3E,oEAAoE;QACpE,sEAAsE;QACtE,kEAAkE;QAClE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,wBAAwB,EAAE,mBAAmB,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,CAAC,KAAK;QACV,IAAI,CAAC,UAAU,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAErF,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC;QACvC,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC7B,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,yEAAyE;QACzE,yEAAyE;QACzE,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,SAAS,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC;QACrE,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAEpC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAEzB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC;QAEnC,oBAAoB;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpC,GAAG,CAAC,KAAK,CAAC,mCAAmC,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,WAAW;QACf,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC;QACtE,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAE7B,IAAI,CAAC;YACH,MAAM,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,eAAe,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC,CAAC;YAEnH,IAAI,iBAAiB;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAoB,EAAE,GAAoB,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;QACtH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,CAAC,KAAK;gBAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACrC,GAAG,CAAC,KAAK,CAAC,wDAAwD,GAAG,EAAE,CAAC,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,wDAAwD,GAAG,EAAE,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED,qBAAqB;QACnB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC;QAE1D,IAAI,UAAU;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAElD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YACX,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YACzB,OAAO,CAAC,IAAI,EAAE;SACf,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC,iBAA0B,EAAE,EAAE,IAAI,EAAE,OAAO,EAAuC;QAC3F,MAAM,UAAU,GAAG,iBAAmG,CAAC;QACvH,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QACrB,MAAM,aAAa,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QAClD,MAAM,EAAE,eAAe,EAAE,GAAG,aAAa,CAAC;QAE1C,aAAa,CAAC,aAAa,EAAE,CAAC;QAC9B,eAAe,CAAC,SAAS,GAAG,KAAK,CAAC;QAElC,qCAAqC;QACrC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;IAClC,CAAC;CACF"}
|
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"stonyx-async",
|
|
5
5
|
"stonyx-module"
|
|
6
6
|
],
|
|
7
|
-
"version": "0.2.1-alpha.
|
|
7
|
+
"version": "0.2.1-alpha.36",
|
|
8
8
|
"description": "Rest Server Module for Stonyx Framework",
|
|
9
9
|
"repository": {
|
|
10
10
|
"type": "git",
|
|
@@ -34,14 +34,14 @@
|
|
|
34
34
|
"provenance": true
|
|
35
35
|
},
|
|
36
36
|
"dependencies": {
|
|
37
|
+
"@types/express": "^5.0.6",
|
|
37
38
|
"cors": "^2.8.5",
|
|
38
39
|
"express": "^5.1.0",
|
|
39
|
-
"stonyx": "0.2.3-beta.
|
|
40
|
+
"stonyx": "0.2.3-beta.100"
|
|
40
41
|
},
|
|
41
42
|
"devDependencies": {
|
|
42
43
|
"@stonyx/utils": "0.2.3-beta.27",
|
|
43
44
|
"@types/cors": "^2.8.17",
|
|
44
|
-
"@types/express": "^5.0.6",
|
|
45
45
|
"@types/node": "^25.5.2",
|
|
46
46
|
"@types/qunit": "^2.19.13",
|
|
47
47
|
"@types/sinon": "^21.0.1",
|