@stonyx/rest-server 0.2.1-beta.160 → 0.2.1-beta.161
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 +22 -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 +2 -2
package/README.md
CHANGED
|
@@ -19,15 +19,33 @@ REST server module for the [Stonyx framework](https://github.com/abofs/stonyx),
|
|
|
19
19
|
|
|
20
20
|
| Import path | What it exports |
|
|
21
21
|
| :--- | :--- |
|
|
22
|
-
| `@stonyx/rest-server` | `RestServer` (default), `Request` (named) |
|
|
22
|
+
| `@stonyx/rest-server` | `RestServer` (default), `Request` (named); types `RouteHandlers`, `RequestHandler`, `AuthHandler`, `RequestState` |
|
|
23
23
|
|
|
24
24
|
There are no subpath exports.
|
|
25
25
|
|
|
26
26
|
## Samples
|
|
27
27
|
|
|
28
|
-
The
|
|
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`, `node:` built-ins and each other, so you can copy them into your app's `requests/` directory:
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
* **As TypeScript:** copy them unchanged. `stonyx serve` runs them with Node's type stripping, which loads a relative import only by its real file name, so `accounts.ts` imports `./base/api-request.ts`, not `.js`. For `tsc` to accept that specifier, set `"rewriteRelativeImportExtensions": true` and `"noEmit": true` in your `tsconfig.json` (TypeScript 5.7+); the `stonyx new` tsconfig sets neither, and reports `TS5097` without the first. `noEmit` matters because the scaffold's `build` script compiles into the app directory: route discovery loads a `.js` left beside a `.ts` as well, and that stale copy keeps answering after you edit the `.ts`. `stonyx serve` runs the `.ts` files, so `pnpm build` then only type-checks. If you have built before, delete the `.js` files in `requests/`.
|
|
31
|
+
* **As JavaScript:** remove all TypeScript-only syntax (annotations, `interface`, `import type` and inline `type` imports, `!` assertions; `stripTypeScriptTypes` from `node:module` does this), rename each file to `.js`, and change the `.ts` in that relative import to `.js`.
|
|
32
|
+
|
|
33
|
+
[`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. [`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 other than `@stonyx/rest-server`, a `node:` built-in, or another sample file that exists under the exact name imported. The suite itself runs under tsx, which would load a `.js` specifier from a `.ts` file, so that check is what keeps the TypeScript copy loadable by `stonyx serve`. The samples are not included in the npm package.
|
|
34
|
+
|
|
35
|
+
| How do I… | Sample |
|
|
36
|
+
| :--- | :--- |
|
|
37
|
+
| 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 |
|
|
38
|
+
| 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 |
|
|
39
|
+
| 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 |
|
|
40
|
+
| 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 |
|
|
41
|
+
| Use middleware, URL params and `this` in handlers | [`public.ts`](https://github.com/abofs/stonyx-rest-server/blob/dev/test/sample/requests/public.ts) |
|
|
42
|
+
|
|
43
|
+
Two contracts the samples rely on, both pinned by `sample-patterns-test.ts`:
|
|
44
|
+
|
|
45
|
+
* `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.
|
|
46
|
+
* 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.
|
|
47
|
+
|
|
48
|
+
`private.ts` carries one deliberately invalid entry (`someInvalidMethod`) that the suite uses to check unknown methods are skipped, and its `auth` returns fixture statuses (505, 403) for the tests. Do not copy either; copy the `auth` in `base/api-request.ts`, which compares the token in constant time.
|
|
31
49
|
|
|
32
50
|
## Security notes
|
|
33
51
|
|
|
@@ -230,7 +248,7 @@ export default class MyRequest extends Request {
|
|
|
230
248
|
### Handler Features
|
|
231
249
|
|
|
232
250
|
* Middleware support by passing an array of functions for a route
|
|
233
|
-
*
|
|
251
|
+
* Middleware functions are called with `this` bound to the request class; the final handler is not bound, so write it as an arrow function
|
|
234
252
|
* Returns integers as HTTP status codes
|
|
235
253
|
* Returns objects as JSON responses
|
|
236
254
|
* 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":"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"}
|
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"stonyx-async",
|
|
5
5
|
"stonyx-module"
|
|
6
6
|
],
|
|
7
|
-
"version": "0.2.1-beta.
|
|
7
|
+
"version": "0.2.1-beta.161",
|
|
8
8
|
"description": "Rest Server Module for Stonyx Framework",
|
|
9
9
|
"repository": {
|
|
10
10
|
"type": "git",
|
|
@@ -34,6 +34,7 @@
|
|
|
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
40
|
"stonyx": "0.2.3-beta.103"
|
|
@@ -41,7 +42,6 @@
|
|
|
41
42
|
"devDependencies": {
|
|
42
43
|
"@stonyx/utils": "0.2.3-beta.28",
|
|
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",
|