@alxia/create 0.1.5 → 0.1.7
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 +43 -18
- package/dist/index.js +29 -19
- package/dist/index.js.map +7 -6
- package/dist/main.d.ts +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/packument.d.ts +18 -0
- package/dist/packument.d.ts.map +1 -0
- package/dist/registry.d.ts +19 -10
- package/dist/registry.d.ts.map +1 -1
- package/dist/versions.d.ts +1 -1
- package/dist/versions.d.ts.map +1 -1
- package/docs/README.md +6 -5
- package/docs/guide.md +372 -53
- package/docs/roadmap.md +36 -4
- package/docs/troubleshooting.md +135 -4
- package/package.json +5 -4
- package/templates/api/README.md +53 -8
- package/templates/api/_biome.json +1 -1
- package/templates/api/openapi-codegen.config.ts +11 -0
- package/templates/api/openapi.yaml +116 -0
- package/templates/api/package.json +5 -3
- package/templates/api/src/app.spec.ts +33 -14
- package/templates/api/src/app.ts +5 -30
- package/templates/api/src/context.ts +19 -0
- package/templates/api/src/generated/alxia.ts +71 -0
- package/templates/api/src/generated/operations.ts +133 -0
- package/templates/api/src/generated/paths.ts +170 -0
- package/templates/api/src/generated/types.ts +170 -0
- package/templates/api/src/generated/zod.ts +31 -0
- package/templates/api/src/routes/todos.ts +31 -0
package/docs/troubleshooting.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Troubleshooting
|
|
2
2
|
|
|
3
3
|
Each entry is headed by the text you see: what `create-alxia` printed, what
|
|
4
|
-
Bun or the shell printed before it ran,
|
|
5
|
-
nothing — the symptom.
|
|
4
|
+
Bun or the shell printed before it ran, what a new project's own commands
|
|
5
|
+
print, or — for a trap that prints nothing — the symptom.
|
|
6
6
|
|
|
7
7
|
**Before it runs**
|
|
8
8
|
|
|
@@ -41,6 +41,13 @@ nothing — the symptom.
|
|
|
41
41
|
- [`error: … is linked against glibc (DT_NEEDED libm.so.6), but this Bun build uses musl.`](#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)
|
|
42
42
|
- [The project's `@alxia/*` are older than npm's latest](#the-projects-alxia-are-older-than-npms-latest)
|
|
43
43
|
|
|
44
|
+
**The `api` project's spec**
|
|
45
|
+
|
|
46
|
+
- [`openapi.yaml → src/generated: out of date, run nxgt-openapi generate`](#openapiyaml--srcgenerated-out-of-date-run-nxgt-openapi-generate)
|
|
47
|
+
- [`src/generated/` changes after moving `@nxgt/openapi-codegen`](#srcgenerated-changes-after-moving-nxgtopenapi-codegen)
|
|
48
|
+
- [`TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`](#typeerror-matchesspec-1-operation-has-no-route-delete-todosid-deletetodo)
|
|
49
|
+
- [`ResponseValidationError: POST /todos: the 201 reply does not match its schema`](#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)
|
|
50
|
+
|
|
44
51
|
**Biome**
|
|
45
52
|
|
|
46
53
|
- [`bun ci` installs, and checks nothing](#bun-ci-installs-and-checks-nothing)
|
|
@@ -227,7 +234,7 @@ hand after the project is created.
|
|
|
227
234
|
|
|
228
235
|
**When:** a notice, not an error, right after an alxia release: the
|
|
229
236
|
registry lists `@alxia/create`'s new version but not yet the
|
|
230
|
-
`@alxia/core` (or `@alxia/
|
|
237
|
+
`@alxia/core` (or `@alxia/react-router`) published beside
|
|
231
238
|
it. npm can take a few minutes to serve a version everywhere.
|
|
232
239
|
|
|
233
240
|
**Why:** a project written with `^0.3.1` would fail its `bun install` with
|
|
@@ -374,11 +381,135 @@ new `@alxia/create`.
|
|
|
374
381
|
|
|
375
382
|
**Fix:** `bunx @alxia/create@latest` for the newest `@alxia/create`, and in
|
|
376
383
|
an existing project
|
|
377
|
-
`bun add @alxia/core@latest @alxia/
|
|
384
|
+
`bun add @alxia/core@latest && bun add --dev @alxia/openapi@latest` (`api`) or
|
|
378
385
|
`bun add @alxia/core@latest @alxia/react-router@latest` (`react-router`), reading
|
|
379
386
|
[`@alxia/core`'s upgrading page](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md)
|
|
380
387
|
for what a minor changed.
|
|
381
388
|
|
|
389
|
+
## The `api` project's spec
|
|
390
|
+
|
|
391
|
+
### `openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
|
|
392
|
+
|
|
393
|
+
`bun run verify` stops at its first step, with the stale files listed
|
|
394
|
+
below the line:
|
|
395
|
+
|
|
396
|
+
```
|
|
397
|
+
openapi.yaml → src/generated: out of date, run nxgt-openapi generate
|
|
398
|
+
src/generated/types.ts
|
|
399
|
+
src/generated/operations.ts
|
|
400
|
+
src/generated/paths.ts
|
|
401
|
+
src/generated/alxia.ts
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
**When:** `bun run generate --check`, alone or as `verify`'s first step,
|
|
405
|
+
after `openapi.yaml` changed and `bun run generate` was not run, or after
|
|
406
|
+
a file of `src/generated/` was edited by hand. It writes nothing and exits 1.
|
|
407
|
+
|
|
408
|
+
**Why:** `src/generated/` is committed, so that nothing is generated at
|
|
409
|
+
install or build ([the `api` template](guide.md#srcgenerated)); the check
|
|
410
|
+
is what keeps it equal to `openapi.yaml`.
|
|
411
|
+
|
|
412
|
+
**Fix:** generate, then commit the files with the spec:
|
|
413
|
+
|
|
414
|
+
```sh
|
|
415
|
+
bun run generate
|
|
416
|
+
git add openapi.yaml src/generated
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
A change made by hand in `src/generated/` is lost: make it in
|
|
420
|
+
`openapi.yaml`.
|
|
421
|
+
|
|
422
|
+
### `src/generated/` changes after moving `@nxgt/openapi-codegen`
|
|
423
|
+
|
|
424
|
+
**Symptom:** `bun run verify` fails with
|
|
425
|
+
`openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
|
|
426
|
+
right after `bun add --dev --exact @nxgt/openapi-codegen@…`, with no
|
|
427
|
+
change to `openapi.yaml`.
|
|
428
|
+
|
|
429
|
+
**When:** the generator moved to another minor, `0.7.x` to `0.8.0`. A new
|
|
430
|
+
project never hits it: the command keeps the template's version
|
|
431
|
+
([Versions](guide.md#versions)).
|
|
432
|
+
|
|
433
|
+
**Why:** the generated files are the output of one release of the
|
|
434
|
+
generator, and another minor may write them differently: an option's
|
|
435
|
+
default, a new file, another form for a schema. That is why the template
|
|
436
|
+
pins it exactly.
|
|
437
|
+
|
|
438
|
+
**Fix:** generate again, then read what changed before committing it:
|
|
439
|
+
|
|
440
|
+
```sh
|
|
441
|
+
bun run generate
|
|
442
|
+
git diff src/generated
|
|
443
|
+
bun run verify
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
The diff is what the new release writes differently; `bun run verify`
|
|
447
|
+
tells whether the app still compiles and passes against it. To stay
|
|
448
|
+
where you were, pin the previous version again, `0.7.0` after a move to `0.8.0`:
|
|
449
|
+
`bun add --dev --exact @nxgt/openapi-codegen@0.7.0`.
|
|
450
|
+
|
|
451
|
+
### `TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`
|
|
452
|
+
|
|
453
|
+
With several, `2 operations have no route: …`; a route outside the spec
|
|
454
|
+
reads `1 route has no operation: …`, after a `;` when both happen.
|
|
455
|
+
|
|
456
|
+
**When:** `bun test`, in `src/app.spec.ts`, after an operation was added
|
|
457
|
+
to `openapi.yaml` and `bun run generate` run, before `src/routes/todos.ts` routes
|
|
458
|
+
it. The path is in alxia's form, `/todos/:id`, and the `operationId` is
|
|
459
|
+
in parentheses.
|
|
460
|
+
|
|
461
|
+
**Why:** `matchesSpec(app, operations)` checks both ways: every operation
|
|
462
|
+
of `src/generated/alxia.ts` has a route of its method and path, and every
|
|
463
|
+
route has an operation.
|
|
464
|
+
|
|
465
|
+
**Fix:** bind the operation in `src/routes/todos.ts`
|
|
466
|
+
([Adding an operation](guide.md#adding-an-operation)):
|
|
467
|
+
|
|
468
|
+
```ts
|
|
469
|
+
.route(operations.deleteTodo, requireKey, ({ params, todos, reply }) => {
|
|
470
|
+
const index = todos.findIndex(({ id }) => id === params.id);
|
|
471
|
+
if (index === -1) return reply.notFound({ error: "not_found" as const });
|
|
472
|
+
todos.splice(index, 1);
|
|
473
|
+
return reply.noContent();
|
|
474
|
+
});
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
For a route deliberately outside the spec, a health check say, see
|
|
478
|
+
[`@alxia/openapi`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/troubleshooting.md#typeerror-matchesspec--routes-have-no-operation-).
|
|
479
|
+
|
|
480
|
+
### `ResponseValidationError: POST /todos: the 201 reply does not match its schema`
|
|
481
|
+
|
|
482
|
+
The client gets `500 {"error":"internal"}`, and the server prints the
|
|
483
|
+
error, with the field that broke the schema after the colon:
|
|
484
|
+
|
|
485
|
+
```text
|
|
486
|
+
ResponseValidationError: POST /todos: the 201 reply does not match its schema: title: Invalid input: expected string, received undefined
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
The method, path and status are the route's and the reply's.
|
|
490
|
+
|
|
491
|
+
**When:** the handler's reply does not match what `openapi.yaml` declares
|
|
492
|
+
for its status. A middleware's own reply, such as `requireKey`'s 401, is
|
|
493
|
+
not checked, unless `responds(operation)` stands before it. The types refuse most of
|
|
494
|
+
these, so it comes from data the types do not see (a database row,
|
|
495
|
+
`JSON.parse`, `any`, a cast), or from `openapi.yaml` changed and
|
|
496
|
+
generated while the code still sends the old shape.
|
|
497
|
+
|
|
498
|
+
**Why:** a route bound with `route(operation, …)` checks the handler's
|
|
499
|
+
reply against the operation's responses, so a client generated from the same
|
|
500
|
+
spec never reads a body it was not told about. A body the spec refuses is
|
|
501
|
+
not sent.
|
|
502
|
+
|
|
503
|
+
**Fix:** send what the spec declares, or change the spec, generate, and
|
|
504
|
+
send that:
|
|
505
|
+
|
|
506
|
+
```ts
|
|
507
|
+
reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id, title, done }
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
The other forms of the error, and how to turn the check off, are in
|
|
511
|
+
[`@alxia/core`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#responsevalidationerror--the-200-reply-does-not-match-its-schema).
|
|
512
|
+
|
|
382
513
|
## Biome
|
|
383
514
|
|
|
384
515
|
### `bun ci` installs, and checks nothing
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alxia/create",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"description": "Start an alxia app: `bun create @alxia` writes an API with Zod, or React Router's official template served by alxia",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -39,9 +39,10 @@
|
|
|
39
39
|
]
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
|
-
"@alxia/
|
|
43
|
-
"@alxia/
|
|
44
|
-
"@alxia/react-router": "^0.
|
|
42
|
+
"@alxia/core": "^0.4.0",
|
|
43
|
+
"@alxia/openapi": "^0.4.1",
|
|
44
|
+
"@alxia/react-router": "^0.5.0",
|
|
45
|
+
"@nxgt/openapi-codegen": "0.7.0",
|
|
45
46
|
"@types/bun": "^1.4.2",
|
|
46
47
|
"zod": "^4.6.5"
|
|
47
48
|
}
|
package/templates/api/README.md
CHANGED
|
@@ -1,14 +1,57 @@
|
|
|
1
1
|
# An alxia API
|
|
2
2
|
|
|
3
3
|
An [alxia](https://github.com/softistx/alxia) app with
|
|
4
|
-
[Zod](https://zod.dev), made with `bun create @alxia`.
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
[Zod](https://zod.dev), made with `bun create @alxia`. It is OpenAPI spec
|
|
5
|
+
first: `openapi.yaml` is the contract, the routes are bound to the
|
|
6
|
+
operations generated from it, and a client is generated from the same file.
|
|
7
|
+
|
|
8
|
+
- `openapi.yaml`: the API's operations, `GET /todos`, `POST /todos` and
|
|
9
|
+
`GET /todos/{id}`, their bodies, parameters and replies.
|
|
10
|
+
- `src/generated/`: what `bun run generate` writes from it, with
|
|
11
|
+
[`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen)
|
|
12
|
+
(`openapi-codegen.config.ts`). `alxia.ts` holds each operation as the
|
|
13
|
+
data `app.route()` takes. Never edit it: change `openapi.yaml`, then
|
|
14
|
+
generate.
|
|
15
|
+
- `src/context.ts`: the base, what every route reads (the todos), and
|
|
16
|
+
its `Register` declaration: a route file reads that context with no
|
|
17
|
+
import of the app. Register the base, never the app, which mounts the
|
|
18
|
+
route files and would be typed by itself.
|
|
19
|
+
- `src/routes/todos.ts`: the routes, `defineRoutes()`, each bound to an
|
|
20
|
+
operation. `route(operations.createTodo, requireKey, handler)` runs its
|
|
21
|
+
middlewares in order: `requireKey`, made with `defineMiddleware`,
|
|
22
|
+
answers 401 without the `x-api-key` header; the operation's body is
|
|
23
|
+
validated just before the handler, and the handler's reply checked
|
|
24
|
+
against the operation's responses.
|
|
25
|
+
- `src/app.ts`: the app, `base.plugin(todoRoutes)`. Mounting the routes on
|
|
26
|
+
an app that does not give the base's context is a compile error.
|
|
8
27
|
- `src/server.ts`: listens on `PORT`, 3000 by default.
|
|
9
|
-
- `src/app.spec.ts`: `app.request()
|
|
28
|
+
- `src/app.spec.ts`: `app.request()`, no port, and `matchesSpec` from
|
|
29
|
+
[`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every
|
|
30
|
+
operation of `openapi.yaml` has its route, and no route is outside it.
|
|
10
31
|
- `biome.json`: Biome's lint and format settings ([Lint and format](#lint-and-format)).
|
|
11
32
|
|
|
33
|
+
## The contract first
|
|
34
|
+
|
|
35
|
+
A new route starts in `openapi.yaml`:
|
|
36
|
+
|
|
37
|
+
1. Add the operation, with an `operationId`: `deleteTodo`, say.
|
|
38
|
+
2. `bun run generate`: `src/generated/alxia.ts` now exports
|
|
39
|
+
`operations.deleteTodo`.
|
|
40
|
+
3. Bind it in `src/routes/todos.ts`, with the middlewares it needs:
|
|
41
|
+
`.route(operations.deleteTodo, requireKey, ({ params, reply }) => …)`.
|
|
42
|
+
The handler's `params`, `body` and `reply` are typed by the spec.
|
|
43
|
+
4. `bun test`: `matchesSpec` fails while an operation has no route.
|
|
44
|
+
|
|
45
|
+
`src/generated/` is committed, so the project builds with no generation
|
|
46
|
+
step, in Docker too. `bun run verify` runs `bun run generate --check`
|
|
47
|
+
first: it fails when `src/generated/` is not what `openapi.yaml` gives.
|
|
48
|
+
`@nxgt/openapi-codegen` is pinned exactly, since another release may
|
|
49
|
+
write the files differently: after moving it, run `bun run generate`.
|
|
50
|
+
|
|
51
|
+
A client in another project is generated from the same `openapi.yaml`,
|
|
52
|
+
with the generator of its choice: `@nxgt/openapi-codegen` writes types,
|
|
53
|
+
Zod validators and the operations a typed client reads.
|
|
54
|
+
|
|
12
55
|
## Environment
|
|
13
56
|
|
|
14
57
|
Bun loads `.env` on every command. Copy `.env.example` to `.env` to set
|
|
@@ -34,22 +77,24 @@ curl -X POST localhost:3000/todos \
|
|
|
34
77
|
## Test
|
|
35
78
|
|
|
36
79
|
```sh
|
|
37
|
-
bun test # src/app.spec.ts: in process,
|
|
80
|
+
bun test # src/app.spec.ts: in process, no port
|
|
38
81
|
bun run typecheck
|
|
82
|
+
bun run generate # src/generated/, from openapi.yaml
|
|
39
83
|
```
|
|
40
84
|
|
|
41
85
|
## Lint and format
|
|
42
86
|
|
|
43
87
|
[Biome](https://biomejs.dev) lints and formats the project, as `biome.json`
|
|
44
88
|
sets it: Biome's recommended rules, spaces, double quotes, imports
|
|
45
|
-
sorted. What the build writes, `dist/`, is skipped
|
|
89
|
+
sorted. What the build writes, `dist/`, is skipped, and so is what
|
|
90
|
+
`bun run generate` writes, `src/generated/`.
|
|
46
91
|
|
|
47
92
|
```sh
|
|
48
93
|
bun run check # lint, format and sort imports, fixing what it can
|
|
49
94
|
bun run lint # lint only
|
|
50
95
|
bun run format # format only, in place
|
|
51
96
|
bun run check:ci # what CI runs: changes nothing, fails on an error
|
|
52
|
-
bun run verify # check:ci,
|
|
97
|
+
bun run verify # generate --check, check:ci, typecheck, then test
|
|
53
98
|
```
|
|
54
99
|
|
|
55
100
|
`bun run check:ci`, not `bun ci`: `bun ci` is Bun's frozen-lockfile
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { defineConfig } from "@nxgt/openapi-codegen";
|
|
2
|
+
|
|
3
|
+
// `bun run generate` writes src/generated/ from openapi.yaml; `alxia` adds
|
|
4
|
+
// alxia.ts, the operations src/routes/todos.ts binds. The 400 is alxia's own,
|
|
5
|
+
// declared in openapi.yaml, not the one validationErrors would add.
|
|
6
|
+
export default defineConfig({
|
|
7
|
+
input: "openapi.yaml",
|
|
8
|
+
output: "src/generated",
|
|
9
|
+
alxia: true,
|
|
10
|
+
validationErrors: false,
|
|
11
|
+
});
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# The API's contract: the routes of src/routes/todos.ts are bound to the operations
|
|
2
|
+
# generated from it. Edit it first, then run `bun run generate`.
|
|
3
|
+
openapi: 3.1.0
|
|
4
|
+
info:
|
|
5
|
+
title: my-api
|
|
6
|
+
version: 0.1.0
|
|
7
|
+
paths:
|
|
8
|
+
/todos:
|
|
9
|
+
get:
|
|
10
|
+
operationId: listTodos
|
|
11
|
+
summary: Every todo
|
|
12
|
+
responses:
|
|
13
|
+
"200":
|
|
14
|
+
description: The todos, oldest first
|
|
15
|
+
content:
|
|
16
|
+
application/json:
|
|
17
|
+
schema:
|
|
18
|
+
type: array
|
|
19
|
+
items: { $ref: "#/components/schemas/Todo" }
|
|
20
|
+
post:
|
|
21
|
+
operationId: createTodo
|
|
22
|
+
summary: Add a todo
|
|
23
|
+
security:
|
|
24
|
+
- apiKey: []
|
|
25
|
+
requestBody:
|
|
26
|
+
required: true
|
|
27
|
+
content:
|
|
28
|
+
application/json:
|
|
29
|
+
schema: { $ref: "#/components/schemas/NewTodo" }
|
|
30
|
+
responses:
|
|
31
|
+
"201":
|
|
32
|
+
description: The todo, created
|
|
33
|
+
content:
|
|
34
|
+
application/json:
|
|
35
|
+
schema: { $ref: "#/components/schemas/Todo" }
|
|
36
|
+
"400":
|
|
37
|
+
$ref: "#/components/responses/ValidationError"
|
|
38
|
+
"401":
|
|
39
|
+
description: No x-api-key header, or not the key
|
|
40
|
+
content:
|
|
41
|
+
application/json:
|
|
42
|
+
schema: { $ref: "#/components/schemas/Unauthorized" }
|
|
43
|
+
/todos/{id}:
|
|
44
|
+
get:
|
|
45
|
+
operationId: getTodo
|
|
46
|
+
summary: One todo
|
|
47
|
+
parameters:
|
|
48
|
+
- name: id
|
|
49
|
+
in: path
|
|
50
|
+
required: true
|
|
51
|
+
schema: { type: integer, minimum: 1 }
|
|
52
|
+
responses:
|
|
53
|
+
"200":
|
|
54
|
+
description: The todo
|
|
55
|
+
content:
|
|
56
|
+
application/json:
|
|
57
|
+
schema: { $ref: "#/components/schemas/Todo" }
|
|
58
|
+
"400":
|
|
59
|
+
$ref: "#/components/responses/ValidationError"
|
|
60
|
+
"404":
|
|
61
|
+
description: No todo has this id
|
|
62
|
+
content:
|
|
63
|
+
application/json:
|
|
64
|
+
schema: { $ref: "#/components/schemas/NotFound" }
|
|
65
|
+
components:
|
|
66
|
+
securitySchemes:
|
|
67
|
+
apiKey: { type: apiKey, in: header, name: x-api-key }
|
|
68
|
+
responses:
|
|
69
|
+
ValidationError:
|
|
70
|
+
description: alxia's own 400, for a request the schemas refuse
|
|
71
|
+
content:
|
|
72
|
+
application/json:
|
|
73
|
+
schema: { $ref: "#/components/schemas/ValidationError" }
|
|
74
|
+
schemas:
|
|
75
|
+
Todo:
|
|
76
|
+
type: object
|
|
77
|
+
required: [id, title, done]
|
|
78
|
+
properties:
|
|
79
|
+
id: { type: integer }
|
|
80
|
+
title: { type: string }
|
|
81
|
+
done: { type: boolean }
|
|
82
|
+
NewTodo:
|
|
83
|
+
type: object
|
|
84
|
+
required: [title]
|
|
85
|
+
properties:
|
|
86
|
+
title: { type: string, minLength: 1 }
|
|
87
|
+
Unauthorized:
|
|
88
|
+
type: object
|
|
89
|
+
required: [error]
|
|
90
|
+
properties:
|
|
91
|
+
error: { type: string, enum: [unauthorized] }
|
|
92
|
+
NotFound:
|
|
93
|
+
type: object
|
|
94
|
+
required: [error]
|
|
95
|
+
properties:
|
|
96
|
+
error: { type: string, enum: [not_found] }
|
|
97
|
+
ValidationError:
|
|
98
|
+
type: object
|
|
99
|
+
required: [error, issues]
|
|
100
|
+
properties:
|
|
101
|
+
error: { type: string, enum: [validation] }
|
|
102
|
+
issues:
|
|
103
|
+
type: array
|
|
104
|
+
items:
|
|
105
|
+
type: object
|
|
106
|
+
required: [target, path, code, message]
|
|
107
|
+
properties:
|
|
108
|
+
target:
|
|
109
|
+
type: string
|
|
110
|
+
enum: [params, query, headers, cookies, body]
|
|
111
|
+
path:
|
|
112
|
+
type: array
|
|
113
|
+
items:
|
|
114
|
+
anyOf: [{ type: string }, { type: integer }]
|
|
115
|
+
code: { type: string }
|
|
116
|
+
message: { type: string }
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
"private": true,
|
|
4
4
|
"type": "module",
|
|
5
5
|
"scripts": {
|
|
6
|
+
"generate": "nxgt-openapi generate",
|
|
6
7
|
"dev": "bun --watch src/server.ts",
|
|
7
8
|
"build": "bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked",
|
|
8
9
|
"start": "bun dist/server.js",
|
|
@@ -12,15 +13,16 @@
|
|
|
12
13
|
"format": "biome format --write",
|
|
13
14
|
"check": "biome check --write",
|
|
14
15
|
"check:ci": "biome ci",
|
|
15
|
-
"verify": "bun run check:ci && bun run typecheck && bun run test"
|
|
16
|
+
"verify": "bun run generate --check && bun run check:ci && bun run typecheck && bun run test"
|
|
16
17
|
},
|
|
17
18
|
"dependencies": {
|
|
18
19
|
"@alxia/core": "workspace:^",
|
|
19
|
-
"zod": "^4.
|
|
20
|
+
"zod": "^4.5.4"
|
|
20
21
|
},
|
|
21
22
|
"devDependencies": {
|
|
22
|
-
"@alxia/
|
|
23
|
+
"@alxia/openapi": "workspace:^",
|
|
23
24
|
"@biomejs/biome": "2.5.15",
|
|
25
|
+
"@nxgt/openapi-codegen": "0.7.0",
|
|
24
26
|
"@types/bun": "^1.4.2",
|
|
25
27
|
"typescript": "^6.0.3"
|
|
26
28
|
}
|
|
@@ -1,9 +1,15 @@
|
|
|
1
1
|
import { expect, test } from "bun:test";
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
2
|
+
import { matchesSpec } from "@alxia/openapi";
|
|
3
|
+
import { app } from "./app";
|
|
4
|
+
import { apiKey } from "./context";
|
|
5
|
+
import { operations } from "./generated/alxia";
|
|
4
6
|
|
|
5
7
|
const json = { "content-type": "application/json", "x-api-key": apiKey };
|
|
6
8
|
|
|
9
|
+
test("routes every operation of openapi.yaml, and nothing else", () => {
|
|
10
|
+
matchesSpec(app, operations);
|
|
11
|
+
});
|
|
12
|
+
|
|
7
13
|
test("creates a todo from JSON", async () => {
|
|
8
14
|
const response = await app.request("/todos", {
|
|
9
15
|
method: "POST",
|
|
@@ -28,19 +34,32 @@ test("refuses an empty title with a 400 naming it", async () => {
|
|
|
28
34
|
expect((await response.json()).issues[0].path).toEqual(["title"]);
|
|
29
35
|
});
|
|
30
36
|
|
|
31
|
-
test("the
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
body: { title: "
|
|
37
|
+
test("asks for the key before it reads the body", async () => {
|
|
38
|
+
const response = await app.request("/todos", {
|
|
39
|
+
method: "POST",
|
|
40
|
+
headers: { "content-type": "application/json" },
|
|
41
|
+
body: JSON.stringify({ title: "" }),
|
|
36
42
|
});
|
|
37
|
-
|
|
38
|
-
expect(
|
|
43
|
+
expect(response.status).toBe(401); // requireKey stands before the validation
|
|
44
|
+
expect(await response.json()).toEqual({ error: "unauthorized" });
|
|
45
|
+
});
|
|
39
46
|
|
|
40
|
-
|
|
41
|
-
|
|
47
|
+
test("reads the id from the path as a number, as the spec types it", async () => {
|
|
48
|
+
const created = await app.request("/todos", {
|
|
49
|
+
method: "POST",
|
|
50
|
+
headers: json,
|
|
51
|
+
body: JSON.stringify({ title: "Find me" }),
|
|
42
52
|
});
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
53
|
+
const { id } = await created.json();
|
|
54
|
+
const found = await app.request(`/todos/${id}`);
|
|
55
|
+
expect(found.status).toBe(200);
|
|
56
|
+
expect((await found.json()).title).toBe("Find me");
|
|
57
|
+
expect((await app.request("/todos/9999")).status).toBe(404);
|
|
58
|
+
expect((await app.request("/todos/first")).status).toBe(400);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
test("lists the todos", async () => {
|
|
62
|
+
const response = await app.request("/todos");
|
|
63
|
+
expect(response.status).toBe(200);
|
|
64
|
+
expect(Array.isArray(await response.json())).toBe(true);
|
|
46
65
|
});
|
package/templates/api/src/app.ts
CHANGED
|
@@ -1,33 +1,8 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
1
|
+
import { base } from "./context";
|
|
2
|
+
import { todoRoutes } from "./routes/todos";
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
/** Set API_KEY in the environment: this default is for development. */
|
|
8
|
-
export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
|
|
9
|
-
|
|
10
|
-
// A hook of the routes it is given to: it answers 401 without the key, and
|
|
11
|
-
// that 401 joins the type of each, so the client reads it.
|
|
12
|
-
const requireKey = defineHook(({ request, reply }) =>
|
|
13
|
-
request.headers.get("x-api-key") === apiKey
|
|
14
|
-
? undefined
|
|
15
|
-
: reply(401, { error: "unauthorized" as const }),
|
|
16
|
-
);
|
|
17
|
-
|
|
18
|
-
const todos: z.infer<typeof Todo>[] = [];
|
|
19
|
-
|
|
20
|
-
export const app = alxia()
|
|
21
|
-
.decorate({ todos })
|
|
22
|
-
.post(
|
|
23
|
-
"/todos",
|
|
24
|
-
[requireKey],
|
|
25
|
-
{ body: NewTodo, response: { 201: Todo } },
|
|
26
|
-
({ body, todos, reply }) => {
|
|
27
|
-
const todo = { id: todos.length + 1, title: body.title, done: false };
|
|
28
|
-
todos.push(todo);
|
|
29
|
-
return reply.created(todo);
|
|
30
|
-
},
|
|
31
|
-
);
|
|
4
|
+
// The base, then the route files: each requires the base's context, so
|
|
5
|
+
// mounting one before it is a compile error.
|
|
6
|
+
export const app = base.plugin(todoRoutes);
|
|
32
7
|
|
|
33
8
|
export type App = typeof app;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { alxia } from "@alxia/core";
|
|
2
|
+
import type { Todo } from "./generated/types";
|
|
3
|
+
|
|
4
|
+
/** Set API_KEY in the environment: this default is for development. */
|
|
5
|
+
export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
|
|
6
|
+
|
|
7
|
+
const todos: Todo[] = [];
|
|
8
|
+
|
|
9
|
+
// The base: what every route reads, decorated or derived here. It is
|
|
10
|
+
// registered below, so a route file reads it with no import of the app.
|
|
11
|
+
export const base = alxia().decorate({ todos });
|
|
12
|
+
|
|
13
|
+
// Register the base, never the app: the app mounts the route files, whose
|
|
14
|
+
// type reads this, and would then be typed by itself.
|
|
15
|
+
declare module "@alxia/core" {
|
|
16
|
+
interface Register {
|
|
17
|
+
context: typeof base;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
// Generated by @nxgt/openapi-codegen from ../../openapi.yaml. Do not edit.
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Each operation as `@alxia/core`'s `app.route(operation, ...middlewares, handler)`
|
|
5
|
+
* takes it, @alxia/core 0.4 or later. The route validates the request and
|
|
6
|
+
* checks the handler's reply against `schema.response`, both just before
|
|
7
|
+
* the handler: `validate(operation)` or `responds(operation)` stands
|
|
8
|
+
* earlier among the middlewares when one is placed there.
|
|
9
|
+
* `matchesSpec(app, operations)`, from `@alxia/openapi`, fails while an
|
|
10
|
+
* operation has no route.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { z } from 'zod';
|
|
14
|
+
import { zNewTodo, zNotFound, zTodo, zUnauthorized, zValidationError } from './zod';
|
|
15
|
+
|
|
16
|
+
/** A number in a path, a query, a header or a cookie: digits, where z.coerce.number() would read '' as 0. */
|
|
17
|
+
const numeric = z
|
|
18
|
+
.string()
|
|
19
|
+
.regex(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/)
|
|
20
|
+
.transform(Number);
|
|
21
|
+
|
|
22
|
+
/** Every todo */
|
|
23
|
+
export const listTodos = {
|
|
24
|
+
method: 'GET',
|
|
25
|
+
path: '/todos',
|
|
26
|
+
schema: {
|
|
27
|
+
response: {
|
|
28
|
+
200: z.array(zTodo),
|
|
29
|
+
},
|
|
30
|
+
detail: { operationId: 'listTodos', summary: 'Every todo' },
|
|
31
|
+
},
|
|
32
|
+
} as const;
|
|
33
|
+
|
|
34
|
+
/** Add a todo */
|
|
35
|
+
export const createTodo = {
|
|
36
|
+
method: 'POST',
|
|
37
|
+
path: '/todos',
|
|
38
|
+
schema: {
|
|
39
|
+
body: zNewTodo,
|
|
40
|
+
response: {
|
|
41
|
+
201: zTodo,
|
|
42
|
+
400: zValidationError,
|
|
43
|
+
401: zUnauthorized,
|
|
44
|
+
},
|
|
45
|
+
detail: { operationId: 'createTodo', summary: 'Add a todo' },
|
|
46
|
+
},
|
|
47
|
+
} as const;
|
|
48
|
+
|
|
49
|
+
/** One todo */
|
|
50
|
+
export const getTodo = {
|
|
51
|
+
method: 'GET',
|
|
52
|
+
path: '/todos/:id',
|
|
53
|
+
schema: {
|
|
54
|
+
params: z.object({
|
|
55
|
+
id: numeric.pipe(z.int().min(1)),
|
|
56
|
+
}),
|
|
57
|
+
response: {
|
|
58
|
+
200: zTodo,
|
|
59
|
+
400: zValidationError,
|
|
60
|
+
404: zNotFound,
|
|
61
|
+
},
|
|
62
|
+
detail: { operationId: 'getTodo', summary: 'One todo' },
|
|
63
|
+
},
|
|
64
|
+
} as const;
|
|
65
|
+
|
|
66
|
+
/** Every operation alxia routes, by operationId: `app.route(operations.listTodos, ...middlewares, handler)`. */
|
|
67
|
+
export const operations = {
|
|
68
|
+
listTodos,
|
|
69
|
+
createTodo,
|
|
70
|
+
getTodo,
|
|
71
|
+
} as const;
|