@alxia/create 0.1.5 → 0.1.6
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 +371 -53
- package/docs/roadmap.md +36 -4
- package/docs/troubleshooting.md +182 -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 +61 -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
|
|
|
@@ -32,6 +32,7 @@ nothing — the symptom.
|
|
|
32
32
|
- [`zod: no release within ^4.2.0; kept ^4.2.0`](#zod-no-release-within-420-kept-420)
|
|
33
33
|
- [`@alxia/core: the registry has no release within ^0.3.1 yet; wrote ^0.3.0, the newest of ~0.3.0`](#alxiacore-the-registry-has-no-release-within-031-yet-wrote-030-the-newest-of-030)
|
|
34
34
|
- [`create-alxia: bun install failed; the files are written.`](#create-alxia-bun-install-failed-the-files-are-written)
|
|
35
|
+
- [`warn: incorrect peer dependency "typescript@7.0.2"`](#warn-incorrect-peer-dependency-typescript702)
|
|
35
36
|
|
|
36
37
|
**After**
|
|
37
38
|
|
|
@@ -41,6 +42,14 @@ nothing — the symptom.
|
|
|
41
42
|
- [`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
43
|
- [The project's `@alxia/*` are older than npm's latest](#the-projects-alxia-are-older-than-npms-latest)
|
|
43
44
|
|
|
45
|
+
**The `api` project's spec**
|
|
46
|
+
|
|
47
|
+
- [`openapi.yaml → src/generated: out of date, run nxgt-openapi generate`](#openapiyaml--srcgenerated-out-of-date-run-nxgt-openapi-generate)
|
|
48
|
+
- [`src/generated/` changes after moving `@nxgt/openapi-codegen`](#srcgenerated-changes-after-moving-nxgtopenapi-codegen)
|
|
49
|
+
- [`TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`](#typeerror-matchesspec-1-operation-has-no-route-delete-todosid-deletetodo)
|
|
50
|
+
- [`ResponseValidationError: POST /todos: the 201 reply does not match its schema`](#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)
|
|
51
|
+
- [``cookie parameter `session` is not supported [unsupported_parameter]``](#cookie-parameter-session-is-not-supported-unsupported_parameter)
|
|
52
|
+
|
|
44
53
|
**Biome**
|
|
45
54
|
|
|
46
55
|
- [`bun ci` installs, and checks nothing](#bun-ci-installs-and-checks-nothing)
|
|
@@ -227,7 +236,7 @@ hand after the project is created.
|
|
|
227
236
|
|
|
228
237
|
**When:** a notice, not an error, right after an alxia release: the
|
|
229
238
|
registry lists `@alxia/create`'s new version but not yet the
|
|
230
|
-
`@alxia/core` (or `@alxia/
|
|
239
|
+
`@alxia/core` (or `@alxia/react-router`) published beside
|
|
231
240
|
it. npm can take a few minutes to serve a version everywhere.
|
|
232
241
|
|
|
233
242
|
**Why:** a project written with `^0.3.1` would fail its `bun install` with
|
|
@@ -246,6 +255,23 @@ the next steps.
|
|
|
246
255
|
**Fix:** what its output says, then `cd my-app && bun install`. The
|
|
247
256
|
project is complete; only `node_modules` is missing.
|
|
248
257
|
|
|
258
|
+
### `warn: incorrect peer dependency "typescript@7.0.2"`
|
|
259
|
+
|
|
260
|
+
**When:** `bun install` in a new `api` project, the one `bun create @alxia`
|
|
261
|
+
runs included, prints it once and finishes.
|
|
262
|
+
|
|
263
|
+
**Why:** the project gets the newest TypeScript alxia's packages accept,
|
|
264
|
+
`^6.0.3 || ^7.0.0`, and `@nxgt/openapi-codegen` 0.6.0, the generator the
|
|
265
|
+
template pins, declares `typescript` `^6.0.3` alone. The generator never
|
|
266
|
+
loads TypeScript, so nothing fails: `bun run generate`, `typecheck`, `test`
|
|
267
|
+
and `build` all pass.
|
|
268
|
+
|
|
269
|
+
**Fix:** none is needed. To silence it, hold the project to TypeScript 6:
|
|
270
|
+
|
|
271
|
+
```sh
|
|
272
|
+
bun add -d typescript@^6.0.3
|
|
273
|
+
```
|
|
274
|
+
|
|
249
275
|
## After
|
|
250
276
|
|
|
251
277
|
### `error: lockfile had changes, but lockfile is frozen`
|
|
@@ -374,11 +400,163 @@ new `@alxia/create`.
|
|
|
374
400
|
|
|
375
401
|
**Fix:** `bunx @alxia/create@latest` for the newest `@alxia/create`, and in
|
|
376
402
|
an existing project
|
|
377
|
-
`bun add @alxia/core@latest @alxia/
|
|
403
|
+
`bun add @alxia/core@latest && bun add --dev @alxia/openapi@latest` (`api`) or
|
|
378
404
|
`bun add @alxia/core@latest @alxia/react-router@latest` (`react-router`), reading
|
|
379
405
|
[`@alxia/core`'s upgrading page](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md)
|
|
380
406
|
for what a minor changed.
|
|
381
407
|
|
|
408
|
+
## The `api` project's spec
|
|
409
|
+
|
|
410
|
+
### `openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
|
|
411
|
+
|
|
412
|
+
`bun run verify` stops at its first step, with the stale files listed
|
|
413
|
+
below the line:
|
|
414
|
+
|
|
415
|
+
```
|
|
416
|
+
openapi.yaml → src/generated: out of date, run nxgt-openapi generate
|
|
417
|
+
src/generated/types.ts
|
|
418
|
+
src/generated/operations.ts
|
|
419
|
+
src/generated/paths.ts
|
|
420
|
+
src/generated/alxia.ts
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
**When:** `bun run generate --check`, alone or as `verify`'s first step,
|
|
424
|
+
after `openapi.yaml` changed and `bun run generate` was not run, or after
|
|
425
|
+
a file of `src/generated/` was edited by hand. It writes nothing and exits 1.
|
|
426
|
+
|
|
427
|
+
**Why:** `src/generated/` is committed, so that nothing is generated at
|
|
428
|
+
install or build ([the `api` template](guide.md#srcgenerated)); the check
|
|
429
|
+
is what keeps it equal to `openapi.yaml`.
|
|
430
|
+
|
|
431
|
+
**Fix:** generate, then commit the files with the spec:
|
|
432
|
+
|
|
433
|
+
```sh
|
|
434
|
+
bun run generate
|
|
435
|
+
git add openapi.yaml src/generated
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
A change made by hand in `src/generated/` is lost: make it in
|
|
439
|
+
`openapi.yaml`.
|
|
440
|
+
|
|
441
|
+
### `src/generated/` changes after moving `@nxgt/openapi-codegen`
|
|
442
|
+
|
|
443
|
+
**Symptom:** `bun run verify` fails with
|
|
444
|
+
`openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
|
|
445
|
+
right after `bun add --dev --exact @nxgt/openapi-codegen@…`, with no
|
|
446
|
+
change to `openapi.yaml`.
|
|
447
|
+
|
|
448
|
+
**When:** the generator moved to another minor, `0.6.x` to `0.7.0`. A new
|
|
449
|
+
project never hits it: the command keeps the template's version
|
|
450
|
+
([Versions](guide.md#versions)).
|
|
451
|
+
|
|
452
|
+
**Why:** the generated files are the output of one release of the
|
|
453
|
+
generator, and another minor may write them differently: an option's
|
|
454
|
+
default, a new file, another form for a schema. That is why the template
|
|
455
|
+
pins it exactly.
|
|
456
|
+
|
|
457
|
+
**Fix:** generate again, then read what changed before committing it:
|
|
458
|
+
|
|
459
|
+
```sh
|
|
460
|
+
bun run generate
|
|
461
|
+
git diff src/generated
|
|
462
|
+
bun run verify
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
The diff is what the new release writes differently; `bun run verify`
|
|
466
|
+
tells whether the app still compiles and passes against it. To stay
|
|
467
|
+
where you were, pin the previous version again:
|
|
468
|
+
`bun add --dev --exact @nxgt/openapi-codegen@0.6.0`.
|
|
469
|
+
|
|
470
|
+
### `TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`
|
|
471
|
+
|
|
472
|
+
With several, `2 operations have no route: …`; a route outside the spec
|
|
473
|
+
reads `1 route has no operation: …`, after a `;` when both happen.
|
|
474
|
+
|
|
475
|
+
**When:** `bun test`, in `src/app.spec.ts`, after an operation was added
|
|
476
|
+
to `openapi.yaml` and `bun run generate` run, before `src/routes/todos.ts` routes
|
|
477
|
+
it. The path is in alxia's form, `/todos/:id`, and the `operationId` is
|
|
478
|
+
in parentheses.
|
|
479
|
+
|
|
480
|
+
**Why:** `matchesSpec(app, operations)` checks both ways: every operation
|
|
481
|
+
of `src/generated/alxia.ts` has a route of its method and path, and every
|
|
482
|
+
route has an operation.
|
|
483
|
+
|
|
484
|
+
**Fix:** bind the operation in `src/routes/todos.ts`
|
|
485
|
+
([Adding an operation](guide.md#adding-an-operation)):
|
|
486
|
+
|
|
487
|
+
```ts
|
|
488
|
+
.route(operations.deleteTodo, requireKey, ({ params, todos, reply }) => {
|
|
489
|
+
const index = todos.findIndex(({ id }) => id === params.id);
|
|
490
|
+
if (index === -1) return reply.notFound({ error: "not_found" as const });
|
|
491
|
+
todos.splice(index, 1);
|
|
492
|
+
return reply.noContent();
|
|
493
|
+
});
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
For a route deliberately outside the spec, a health check say, see
|
|
497
|
+
[`@alxia/openapi`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/troubleshooting.md#typeerror-matchesspec--routes-have-no-operation-).
|
|
498
|
+
|
|
499
|
+
### `ResponseValidationError: POST /todos: the 201 reply does not match its schema`
|
|
500
|
+
|
|
501
|
+
The client gets `500 {"error":"internal"}`, and the server prints the
|
|
502
|
+
error, with the field that broke the schema after the colon:
|
|
503
|
+
|
|
504
|
+
```text
|
|
505
|
+
ResponseValidationError: POST /todos: the 201 reply does not match its schema: title: Invalid input: expected string, received undefined
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
The method, path and status are the route's and the reply's.
|
|
509
|
+
|
|
510
|
+
**When:** the handler's reply does not match what `openapi.yaml` declares
|
|
511
|
+
for its status. A middleware's own reply, such as `requireKey`'s 401, is
|
|
512
|
+
not checked, unless `responds(operation)` stands before it. The types refuse most of
|
|
513
|
+
these, so it comes from data the types do not see (a database row,
|
|
514
|
+
`JSON.parse`, `any`, a cast), or from `openapi.yaml` changed and
|
|
515
|
+
generated while the code still sends the old shape.
|
|
516
|
+
|
|
517
|
+
**Why:** a route bound with `route(operation, …)` checks the handler's
|
|
518
|
+
reply against the operation's responses, so a client generated from the same
|
|
519
|
+
spec never reads a body it was not told about. A body the spec refuses is
|
|
520
|
+
not sent.
|
|
521
|
+
|
|
522
|
+
**Fix:** send what the spec declares, or change the spec, generate, and
|
|
523
|
+
send that:
|
|
524
|
+
|
|
525
|
+
```ts
|
|
526
|
+
reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id, title, done }
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
The other forms of the error, and how to turn the check off, are in
|
|
530
|
+
[`@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).
|
|
531
|
+
|
|
532
|
+
### ``cookie parameter `session` is not supported [unsupported_parameter]``
|
|
533
|
+
|
|
534
|
+
```text
|
|
535
|
+
error openapi.yaml#/paths/~1todos/get/parameters/0/in: cookie parameter `session` is not supported [unsupported_parameter]
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
**When:** `bun run generate`, once `openapi.yaml` declares a parameter
|
|
539
|
+
`in: cookie`. It writes nothing and exits 1.
|
|
540
|
+
|
|
541
|
+
**Why:** `@nxgt/openapi-codegen` 0.6.0 does not generate cookie
|
|
542
|
+
parameters, and refuses the whole spec rather than leave one out.
|
|
543
|
+
|
|
544
|
+
**Fix:** take the parameter out of `openapi.yaml`, and read the cookie in
|
|
545
|
+
the app: in a middleware, or with a `validate({ cookies })` placed among
|
|
546
|
+
the route's middlewares:
|
|
547
|
+
|
|
548
|
+
```ts
|
|
549
|
+
import { alxia, validate } from "@alxia/core";
|
|
550
|
+
import { z } from "zod";
|
|
551
|
+
import { operations } from "./generated/alxia";
|
|
552
|
+
|
|
553
|
+
export const app = alxia().route(
|
|
554
|
+
operations.listTodos,
|
|
555
|
+
validate({ cookies: z.object({ session: z.string() }) }),
|
|
556
|
+
({ cookies, reply }) => reply.ok(todosOf(cookies.session)),
|
|
557
|
+
);
|
|
558
|
+
```
|
|
559
|
+
|
|
382
560
|
## Biome
|
|
383
561
|
|
|
384
562
|
### `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.6",
|
|
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.0",
|
|
44
|
+
"@alxia/react-router": "^0.5.0",
|
|
45
|
+
"@nxgt/openapi-codegen": "0.6.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.6.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
|
+
}
|