@alxia/create 0.1.4 → 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.
Files changed (44) hide show
  1. package/README.md +81 -24
  2. package/dist/copy.d.ts +11 -3
  3. package/dist/copy.d.ts.map +1 -1
  4. package/dist/index.js +51 -23
  5. package/dist/index.js.map +8 -7
  6. package/dist/main.d.ts +1 -1
  7. package/dist/main.d.ts.map +1 -1
  8. package/dist/packument.d.ts +18 -0
  9. package/dist/packument.d.ts.map +1 -0
  10. package/dist/registry.d.ts +29 -10
  11. package/dist/registry.d.ts.map +1 -1
  12. package/dist/versions.d.ts +1 -1
  13. package/dist/versions.d.ts.map +1 -1
  14. package/docs/README.md +6 -5
  15. package/docs/guide.md +503 -59
  16. package/docs/roadmap.md +49 -4
  17. package/docs/troubleshooting.md +249 -4
  18. package/package.json +5 -4
  19. package/templates/api/.vscode/extensions.json +3 -0
  20. package/templates/api/.vscode/settings.json +8 -0
  21. package/templates/api/README.md +78 -6
  22. package/templates/api/_biome.json +32 -0
  23. package/templates/api/openapi-codegen.config.ts +11 -0
  24. package/templates/api/openapi.yaml +116 -0
  25. package/templates/api/package.json +27 -19
  26. package/templates/api/src/app.spec.ts +57 -38
  27. package/templates/api/src/app.ts +5 -30
  28. package/templates/api/src/context.ts +19 -0
  29. package/templates/api/src/generated/alxia.ts +61 -0
  30. package/templates/api/src/generated/operations.ts +133 -0
  31. package/templates/api/src/generated/paths.ts +170 -0
  32. package/templates/api/src/generated/types.ts +170 -0
  33. package/templates/api/src/generated/zod.ts +31 -0
  34. package/templates/api/src/routes/todos.ts +31 -0
  35. package/templates/api/src/server.ts +12 -12
  36. package/templates/api/tsconfig.json +23 -23
  37. package/templates/react-router/.vscode/extensions.json +3 -0
  38. package/templates/react-router/.vscode/settings.json +8 -0
  39. package/templates/react-router/README.md +27 -0
  40. package/templates/react-router/_biome.json +49 -0
  41. package/templates/react-router/app/app.css +3 -2
  42. package/templates/react-router/app/routes/home.tsx +1 -1
  43. package/templates/react-router/app/routes.ts +1 -1
  44. package/templates/react-router/package.json +7 -1
package/docs/roadmap.md CHANGED
@@ -7,7 +7,11 @@ number on it. Every release, with each change it made, is in
7
7
 
8
8
  ## Now
9
9
 
10
- Nothing scheduled yet.
10
+ - **The `api` project split across files.** `src/context.ts` holds the
11
+ base the routes read and registers it with `@alxia/core`'s `Register`;
12
+ `src/routes/todos.ts` binds the operations with `defineRoutes()`,
13
+ reading that context with no import of the app; `src/app.ts` mounts
14
+ them, `base.plugin(todoRoutes)`.
11
15
 
12
16
  ## Next
13
17
 
@@ -23,12 +27,53 @@ Nothing scheduled yet.
23
27
  output, committed and copied: a new project needs nothing but the
24
28
  registry, and no change upstream can stop the command. It is generated
25
29
  again from the scaffold when React Router ships a new major.
30
+ - **Generating the `api` project's code at install or build.**
31
+ `src/generated/` is committed: `bun install` runs no script, the
32
+ `Dockerfile` needs no generation step, a clone builds offline, and a
33
+ review shows what a change to `openapi.yaml` changed in the code.
34
+ `bun run verify`'s `generate --check` keeps the files equal to the spec.
35
+ - **Generating the OpenAPI document from the app.** The document is
36
+ written first and the routes are bound to it; a spec read back from the
37
+ code would describe whatever the code does.
26
38
  - **A runtime dependency.** The prompts are Bun's `prompt()`, the registry
27
39
  is read with `fetch`, versions are compared with `Bun.semver`.
28
40
 
29
41
  ## Shipped
30
42
 
31
- ### Next release
43
+ ### 0.1.6
44
+
45
+ - **The `api` project is OpenAPI spec first.** `openapi.yaml` declares
46
+ its operations; `bun run generate` writes `src/generated/` from it with
47
+ `@nxgt/openapi-codegen`, committed, so the project and its image build
48
+ with no generation step and offline; `src/app.ts` binds each operation
49
+ with `route(operations.createTodo, requireKey, handler)`, which
50
+ validates the request and checks the handler's reply against the spec; the
51
+ spec asserts `matchesSpec` from `@alxia/openapi`, so no operation lacks
52
+ a route; and `bun run verify` starts with `generate --check`, which
53
+ fails when `src/generated/` drifts from `openapi.yaml`. New projects
54
+ install `@alxia/openapi` at the version this release was published
55
+ beside, and `@nxgt/openapi-codegen` pinned exactly, at the version the template ships.
56
+ - **The `api` project is written in `@alxia/core`'s middleware model.**
57
+ `requireKey` is a `defineMiddleware` that answers 401 before the body
58
+ is read, given to the route among its middlewares.
59
+ - **No client package in a new project.** The `api` template's spec calls
60
+ the app with `app.request()`; a typed client is generated from
61
+ `openapi.yaml`, with a generator such as `@nxgt/openapi-codegen`.
62
+
63
+ ### 0.1.5
64
+
65
+ - **Both projects lint and format with Biome.** Each has a `biome.json`
66
+ of its own (recommended rules, spaces and double quotes, imports
67
+ sorted, the build output skipped), `@biomejs/biome` pinned exactly,
68
+ the scripts `lint`, `format`, `check`, `check:ci` and `verify`, and
69
+ `.vscode/` recommending Biome's extension. A new project passes
70
+ `bun run check:ci` with no finding.
71
+ - **The project's name in its README.** The name given to the command,
72
+ normalised, replaces the template's own, as a whole word, in every text
73
+ file, as the README's
74
+ `docker build -t` and `docker run`.
75
+
76
+ ### 0.1.4
32
77
 
33
78
  - **The images run on Alpine.** Every `Dockerfile`'s final stage is
34
79
  `oven/bun:1-alpine`, the build stages staying on `oven/bun:1`: each
@@ -65,8 +110,8 @@ Nothing scheduled yet.
65
110
  template ships inside `@alxia/create`, with alxia's layer, and is copied
66
111
  as it is: no `create-react-router` runs, and no change in it can make the
67
112
  command refuse.
68
- - **alxia's packages resolve at creation too.** `@alxia/core`,
69
- `@alxia/client` and `@alxia/react-router` move to the newest version
113
+ - **alxia's packages resolve at creation too.** `@alxia/core`
114
+ and `@alxia/react-router` move to the newest version
70
115
  within the ranges `@alxia/create` was published with. Right after a
71
116
  release, while the registry does not serve that version yet, the newest
72
117
  of the same minor is written, so `bun install` no longer fails with
@@ -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,20 @@ 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
+
53
+ **Biome**
54
+
55
+ - [`bun ci` installs, and checks nothing](#bun-ci-installs-and-checks-nothing)
56
+ - [`× Found a nested root configuration, but there's already a root configuration.`](#-found-a-nested-root-configuration-but-theres-already-a-root-configuration)
57
+ - [`× Biome couldn't find an ignore file in the following folder: …`](#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)
58
+
44
59
  ## Before it runs
45
60
 
46
61
  ### `error: GET https://registry.npmjs.org/@alxia%2fcreate - 404`
@@ -221,7 +236,7 @@ hand after the project is created.
221
236
 
222
237
  **When:** a notice, not an error, right after an alxia release: the
223
238
  registry lists `@alxia/create`'s new version but not yet the
224
- `@alxia/core` (or `@alxia/client`, `@alxia/react-router`) published beside
239
+ `@alxia/core` (or `@alxia/react-router`) published beside
225
240
  it. npm can take a few minutes to serve a version everywhere.
226
241
 
227
242
  **Why:** a project written with `^0.3.1` would fail its `bun install` with
@@ -240,6 +255,23 @@ the next steps.
240
255
  **Fix:** what its output says, then `cd my-app && bun install`. The
241
256
  project is complete; only `node_modules` is missing.
242
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
+
243
275
  ## After
244
276
 
245
277
  ### `error: lockfile had changes, but lockfile is frozen`
@@ -368,7 +400,220 @@ new `@alxia/create`.
368
400
 
369
401
  **Fix:** `bunx @alxia/create@latest` for the newest `@alxia/create`, and in
370
402
  an existing project
371
- `bun add @alxia/core@latest @alxia/client@latest` (`api`) or
403
+ `bun add @alxia/core@latest && bun add --dev @alxia/openapi@latest` (`api`) or
372
404
  `bun add @alxia/core@latest @alxia/react-router@latest` (`react-router`), reading
373
405
  [`@alxia/core`'s upgrading page](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md)
374
406
  for what a minor changed.
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
+
560
+ ## Biome
561
+
562
+ ### `bun ci` installs, and checks nothing
563
+
564
+ **Symptom:** `bun ci` in a project prints an install, `bun install
565
+ v1.4.2`, and no Biome output; a CI step meant to lint passes whatever the
566
+ code.
567
+
568
+ **Why:** `bun ci` is Bun's own command, `bun install --frozen-lockfile`,
569
+ and a command Bun knows wins over a script. The projects name their
570
+ read-only check `check:ci` for that reason
571
+ ([Lint and format](guide.md#lint-and-format)).
572
+
573
+ **Fix:** run the script by `bun run`:
574
+
575
+ ```sh
576
+ bun run check:ci # biome ci alone
577
+ bun run verify # biome ci, typecheck, then test or build
578
+ ```
579
+
580
+ ### `× Found a nested root configuration, but there's already a root configuration.`
581
+
582
+ **When:** Biome runs from a folder above the project that has its own
583
+ `biome.json`: the project was created inside a monorepo, and `biome ci`
584
+ runs from the monorepo's root.
585
+
586
+ **Why:** the project's `biome.json` is a root configuration, so that it
587
+ works on its own. Biome takes one root per run; a configuration below it
588
+ must say it is nested.
589
+
590
+ **Fix:** to keep the monorepo's settings and add the project's, make the
591
+ project's nested, at the top of its `biome.json`:
592
+
593
+ ```json
594
+ {
595
+ "root": false,
596
+ "extends": "//",
597
+ "$schema": "./node_modules/@biomejs/biome/configuration_schema.json"
598
+ }
599
+ ```
600
+
601
+ and keep the rest of the file. `"extends": "//"` takes the root's
602
+ settings, which the project's own override. To use the monorepo's
603
+ settings alone, delete the project's `biome.json` and its
604
+ `@biomejs/biome`.
605
+
606
+ ### `× Biome couldn't find an ignore file in the following folder: …`
607
+
608
+ **When:** `bun run check:ci`, `check`, `lint` or `format` in a project
609
+ with no `.gitignore`, deleted or renamed, and outside any git repository.
610
+ Inside one, Biome reads git's ignore rules and runs.
611
+
612
+ **Why:** `biome.json` sets `vcs.useIgnoreFile`, which skips what
613
+ `.gitignore` names. Inside a git repository Biome falls back on git's
614
+ own ignore rules; with no `.gitignore` and no repository, it refuses to
615
+ run rather than skip nothing.
616
+
617
+ **Fix:** put a `.gitignore` back, even an empty one, or set
618
+ `"useIgnoreFile": false` in `biome.json`'s `vcs`: `files.includes` still
619
+ skips the build output.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alxia/create",
3
- "version": "0.1.4",
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
  }
@@ -0,0 +1,3 @@
1
+ {
2
+ "recommendations": ["biomejs.biome"]
3
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "editor.defaultFormatter": "biomejs.biome",
3
+ "editor.formatOnSave": true,
4
+ "editor.codeActionsOnSave": {
5
+ "source.fixAll.biome": "explicit",
6
+ "source.organizeImports.biome": "explicit"
7
+ }
8
+ }
@@ -1,12 +1,56 @@
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.
31
+ - `biome.json`: Biome's lint and format settings ([Lint and format](#lint-and-format)).
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.
10
54
 
11
55
  ## Environment
12
56
 
@@ -33,8 +77,36 @@ curl -X POST localhost:3000/todos \
33
77
  ## Test
34
78
 
35
79
  ```sh
36
- bun test # src/app.spec.ts: in process, and through the typed client
80
+ bun test # src/app.spec.ts: in process, no port
37
81
  bun run typecheck
82
+ bun run generate # src/generated/, from openapi.yaml
83
+ ```
84
+
85
+ ## Lint and format
86
+
87
+ [Biome](https://biomejs.dev) lints and formats the project, as `biome.json`
88
+ sets it: Biome's recommended rules, spaces, double quotes, imports
89
+ sorted. What the build writes, `dist/`, is skipped, and so is what
90
+ `bun run generate` writes, `src/generated/`.
91
+
92
+ ```sh
93
+ bun run check # lint, format and sort imports, fixing what it can
94
+ bun run lint # lint only
95
+ bun run format # format only, in place
96
+ bun run check:ci # what CI runs: changes nothing, fails on an error
97
+ bun run verify # generate --check, check:ci, typecheck, then test
98
+ ```
99
+
100
+ `bun run check:ci`, not `bun ci`: `bun ci` is Bun's frozen-lockfile
101
+ install. In VS Code, `.vscode/` recommends Biome's extension and formats
102
+ on save with it.
103
+
104
+ `@biomejs/biome` is pinned exactly, since a release of Biome may format
105
+ differently. To move it:
106
+
107
+ ```sh
108
+ bun add --dev --exact @biomejs/biome@latest
109
+ bunx biome migrate --write
38
110
  ```
39
111
 
40
112
  ## Build
@@ -0,0 +1,32 @@
1
+ {
2
+ "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
3
+ "vcs": {
4
+ "enabled": true,
5
+ "clientKind": "git",
6
+ "useIgnoreFile": true
7
+ },
8
+ "files": {
9
+ "includes": ["**", "!!**/dist", "!!**/src/generated"]
10
+ },
11
+ "formatter": {
12
+ "enabled": true,
13
+ "indentStyle": "space"
14
+ },
15
+ "linter": {
16
+ "enabled": true,
17
+ "rules": {
18
+ "preset": "recommended",
19
+ "complexity": {
20
+ "useLiteralKeys": "off"
21
+ }
22
+ }
23
+ },
24
+ "assist": {
25
+ "enabled": true,
26
+ "actions": {
27
+ "source": {
28
+ "organizeImports": "on"
29
+ }
30
+ }
31
+ }
32
+ }
@@ -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 }