@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.
@@ -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
 
@@ -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/client`, `@alxia/react-router`) published beside
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/client@latest` (`api`) or
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.5",
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/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.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
  }
@@ -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.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 { 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
+ }
@@ -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;