@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.
@@ -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, or — for a trap that prints
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/client`, `@alxia/react-router`) published beside
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/client@latest` (`api`) or
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.5",
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/client": "^0.2.1",
43
- "@alxia/core": "^0.3.1",
44
- "@alxia/react-router": "^0.4.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
  }
@@ -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
- - `src/app.ts`: the app. `POST /todos` validates its body with Zod, and
7
- its own hook, `requireKey`, answers 401 without the `x-api-key` header.
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()` and `@alxia/client`, no port.
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, and through the typed client
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, then typecheck, then test
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
@@ -6,7 +6,7 @@
6
6
  "useIgnoreFile": true
7
7
  },
8
8
  "files": {
9
- "includes": ["**", "!!**/dist"]
9
+ "includes": ["**", "!!**/dist", "!!**/src/generated"]
10
10
  },
11
11
  "formatter": {
12
12
  "enabled": true,
@@ -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.2.0"
20
+ "zod": "^4.5.4"
20
21
  },
21
22
  "devDependencies": {
22
- "@alxia/client": "workspace:^",
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 { client } from "@alxia/client";
3
- import { apiKey, app } from "./app";
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 typed client reads each status the route answers", async () => {
32
- // Given the app itself, the client calls its fetch in process.
33
- const api = client(app, { headers: { "x-api-key": apiKey } });
34
- const created = await api.post("/todos", {
35
- body: { title: "Call it typed" },
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
- if (created.status !== 201) throw new Error(`got ${created.status}`);
38
- expect(created.data.title).toBe("Call it typed"); // data is the Todo schema's type
43
+ expect(response.status).toBe(401); // requireKey stands before the validation
44
+ expect(await response.json()).toEqual({ error: "unauthorized" });
45
+ });
39
46
 
40
- const anonymous = await client(app).post("/todos", {
41
- body: { title: "No key" },
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
- expect(anonymous.status).toBe(401);
44
- if (anonymous.status === 401)
45
- expect(anonymous.data.error).toBe("unauthorized");
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
  });
@@ -1,33 +1,8 @@
1
- import { alxia, defineHook } from "@alxia/core";
2
- import { z } from "zod";
1
+ import { base } from "./context";
2
+ import { todoRoutes } from "./routes/todos";
3
3
 
4
- const Todo = z.object({ id: z.number(), title: z.string(), done: z.boolean() });
5
- const NewTodo = z.object({ title: z.string().min(1) });
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
+ }