@alxia/create 0.1.7 → 0.3.0

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 (66) hide show
  1. package/README.md +80 -25
  2. package/dist/args.d.ts +3 -1
  3. package/dist/args.d.ts.map +1 -1
  4. package/dist/index.js +19 -9
  5. package/dist/index.js.map +7 -7
  6. package/dist/main.d.ts +1 -1
  7. package/dist/main.d.ts.map +1 -1
  8. package/dist/registry.d.ts +2 -0
  9. package/dist/registry.d.ts.map +1 -1
  10. package/dist/versions.d.ts +5 -2
  11. package/dist/versions.d.ts.map +1 -1
  12. package/docs/README.md +16 -6
  13. package/docs/guide.md +428 -47
  14. package/docs/roadmap.md +24 -0
  15. package/docs/troubleshooting.md +152 -9
  16. package/package.json +16 -5
  17. package/templates/api/.env.example +9 -1
  18. package/templates/api/README.md +40 -12
  19. package/templates/api/openapi.yaml +13 -9
  20. package/templates/api/package.json +5 -3
  21. package/templates/api/src/app.spec.ts +42 -28
  22. package/templates/api/src/app.ts +13 -3
  23. package/templates/api/src/context.ts +3 -4
  24. package/templates/api/src/env.ts +20 -0
  25. package/templates/api/src/generated/alxia.ts +3 -3
  26. package/templates/api/src/generated/operations.ts +3 -3
  27. package/templates/api/src/generated/paths.ts +6 -6
  28. package/templates/api/src/generated/types.ts +14 -10
  29. package/templates/api/src/generated/zod.ts +6 -2
  30. package/templates/api/src/routes/todos.ts +2 -2
  31. package/templates/api/src/server.ts +8 -16
  32. package/templates/graphql/.dockerignore +6 -0
  33. package/templates/graphql/.env.example +3 -0
  34. package/templates/graphql/.vscode/extensions.json +3 -0
  35. package/templates/graphql/.vscode/settings.json +8 -0
  36. package/templates/graphql/Dockerfile +26 -0
  37. package/templates/graphql/README.md +185 -0
  38. package/templates/graphql/_biome.json +32 -0
  39. package/templates/graphql/codegen.ts +22 -0
  40. package/templates/graphql/gitignore +6 -0
  41. package/templates/graphql/package.json +35 -0
  42. package/templates/graphql/schema.graphql +26 -0
  43. package/templates/graphql/src/app.spec.ts +146 -0
  44. package/templates/graphql/src/app.ts +18 -0
  45. package/templates/graphql/src/context.ts +26 -0
  46. package/templates/graphql/src/env.ts +8 -0
  47. package/templates/graphql/src/generated/resolvers.ts +180 -0
  48. package/templates/graphql/src/graphql.d.ts +6 -0
  49. package/templates/graphql/src/loaders.ts +13 -0
  50. package/templates/graphql/src/resolvers.ts +39 -0
  51. package/templates/graphql/src/schema.ts +6 -0
  52. package/templates/graphql/src/server.ts +10 -0
  53. package/templates/graphql/src/store.ts +38 -0
  54. package/templates/graphql/tsconfig.json +25 -0
  55. package/templates/minimal/.dockerignore +6 -0
  56. package/templates/minimal/.vscode/extensions.json +3 -0
  57. package/templates/minimal/.vscode/settings.json +8 -0
  58. package/templates/minimal/Dockerfile +26 -0
  59. package/templates/minimal/README.md +107 -0
  60. package/templates/minimal/_biome.json +32 -0
  61. package/templates/minimal/gitignore +6 -0
  62. package/templates/minimal/package.json +25 -0
  63. package/templates/minimal/src/index.spec.ts +12 -0
  64. package/templates/minimal/src/index.ts +17 -0
  65. package/templates/minimal/tsconfig.json +25 -0
  66. package/templates/react-router/package.json +2 -2
package/docs/roadmap.md CHANGED
@@ -7,11 +7,32 @@ number on it. Every release, with each change it made, is in
7
7
 
8
8
  ## Now
9
9
 
10
+ - **Two templates: `minimal` and `graphql`.** `minimal` is one file, one
11
+ dependency and a test, the template to try alxia with, and what the
12
+ prompt offers first. `graphql` is a GraphQL Yoga API served by
13
+ `@alxia/graphql`, schema first: `schema.graphql` is the contract, GraphQL
14
+ Code Generator types the resolvers (committed, checked by
15
+ `generate --check`), `viewer` is typed in every resolver, and
16
+ `noteAdded` is a subscription over server-sent events.
17
+ - **The `api` template reads its environment with `defineEnv`.**
18
+ `src/env.ts`, from `@alxia/env`, checks `PORT` and `API_KEY` (a secret)
19
+ once, before the server listens; `src/context.ts` no longer exports
20
+ `apiKey`.
10
21
  - **The `api` project split across files.** `src/context.ts` holds the
11
22
  base the routes read and registers it with `@alxia/core`'s `Register`;
12
23
  `src/routes/todos.ts` binds the operations with `defineRoutes()`,
13
24
  reading that context with no import of the app; `src/app.ts` mounts
14
25
  them, `base.plugin(todoRoutes)`.
26
+ - **Production-safe defaults.** Every `dev` script sets
27
+ `NODE_ENV=development`, the only mode alxia's dev helps run in; the
28
+ `api` project's `API_KEY` is required outside development and test; the
29
+ `api` and `graphql` projects mount `health()`, the `api` project answers
30
+ alxia's own errors as problems and serves `/docs` from the bundled
31
+ `openapi.yaml`; no template installs signal handlers of its own, as
32
+ `listen` drains and exits on `SIGINT` and `SIGTERM`.
33
+ - **The `api` template's tests use a typed client.** `src/app.spec.ts` calls
34
+ the app through openapi-fetch over the generated `paths.ts`, with
35
+ `app.fetch` as its `fetch`: in process, typed by `openapi.yaml`.
15
36
 
16
37
  ## Next
17
38
 
@@ -37,6 +58,9 @@ Nothing scheduled yet.
37
58
  code would describe whatever the code does.
38
59
  - **A runtime dependency.** The prompts are Bun's `prompt()`, the registry
39
60
  is read with `fetch`, versions are compared with `Bun.semver`.
61
+ - **A code-first GraphQL template (Pothos, Nexus).** The `graphql`
62
+ template is schema first, as the `api` one is spec first: the schema file
63
+ is the contract, and the resolvers are typed from it.
40
64
 
41
65
  ## Shipped
42
66
 
@@ -11,8 +11,8 @@ print, or — for a trap that prints nothing — the symptom.
11
11
 
12
12
  **The command line**
13
13
 
14
- - [`create-alxia: unknown template vue: use api or react-router.`](#create-alxia-unknown-template-vue-use-api-or-react-router)
15
- - [`create-alxia: --template needs a template: api or react-router.`](#create-alxia---template-needs-a-template-api-or-react-router)
14
+ - [`create-alxia: unknown template vue: use minimal, api, graphql or react-router.`](#create-alxia-unknown-template-vue-use-minimal-api-graphql-or-react-router)
15
+ - [`create-alxia: --template needs a template: minimal, api, graphql or react-router.`](#create-alxia---template-needs-a-template-minimal-api-graphql-or-react-router)
16
16
  - [`create-alxia: unknown option --yes.`](#create-alxia-unknown-option---yes)
17
17
  - [`create-alxia: one directory only, given a and b.`](#create-alxia-one-directory-only-given-a-and-b)
18
18
  - [`create-alxia: no directory given, and no terminal to ask in.`](#create-alxia-no-directory-given-and-no-terminal-to-ask-in)
@@ -48,6 +48,17 @@ print, or — for a trap that prints nothing — the symptom.
48
48
  - [`TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`](#typeerror-matchesspec-1-operation-has-no-route-delete-todosid-deletetodo)
49
49
  - [`ResponseValidationError: POST /todos: the 201 reply does not match its schema`](#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)
50
50
 
51
+ **The `graphql` project's schema**
52
+
53
+ - [`The following stale files were detected: src/generated/resolvers.ts`](#the-following-stale-files-were-detected-srcgeneratedresolversts)
54
+ - [`src/generated/` changes after moving `@graphql-codegen/*`](#srcgenerated-changes-after-moving-graphql-codegen)
55
+ - [`error: Could not resolve: "../schema.graphql"`, or `TS2307` for it](#error-could-not-resolve-schemagraphql-or-ts2307-for-it)
56
+ - [`Sign in to add a note`](#sign-in-to-add-a-note)
57
+
58
+ **The environment**
59
+
60
+ - [`EnvError: The environment is invalid:`](#enverror-the-environment-is-invalid)
61
+
51
62
  **Biome**
52
63
 
53
64
  - [`bun ci` installs, and checks nothing](#bun-ci-installs-and-checks-nothing)
@@ -85,21 +96,21 @@ then run `bun create @alxia`.
85
96
 
86
97
  ## The command line
87
98
 
88
- ### `create-alxia: unknown template vue: use api or react-router.`
99
+ ### `create-alxia: unknown template vue: use minimal, api, graphql or react-router.`
89
100
 
90
101
  **When:** `--template` names a template the command does not have, or the
91
102
  prompt was answered with one.
92
103
 
93
- **Fix:** `--template api` or `--template react-router`. `bun create @alxia
94
- --help` lists them.
104
+ **Fix:** `--template minimal`, `--template api`, `--template graphql` or
105
+ `--template react-router`. `bun create @alxia --help` lists them.
95
106
 
96
- ### `create-alxia: --template needs a template: api or react-router.`
107
+ ### `create-alxia: --template needs a template: minimal, api, graphql or react-router.`
97
108
 
98
109
  **When:** `--template` is the last argument, or `--template=` is empty.
99
110
  The message names the option as typed: `-t needs a template` for `-t`,
100
111
  `--template= needs a template` for the empty form.
101
112
 
102
- **Fix:** name one: `bun create @alxia my-app --template api`.
113
+ **Fix:** name one: `bun create @alxia my-app --template minimal`.
103
114
 
104
115
  ### `create-alxia: unknown option --yes.`
105
116
 
@@ -130,7 +141,8 @@ terminal: a script, CI, a pipe.
130
141
 
131
142
  **When:** a directory but no `--template`, with no terminal.
132
143
 
133
- **Fix:** add `--template api` or `--template react-router`.
144
+ **Fix:** add `--template minimal`, `--template api`, `--template graphql` or
145
+ `--template react-router`.
134
146
 
135
147
  ### `create-alxia: cancelled, nothing written.`
136
148
 
@@ -274,7 +286,7 @@ traps of the `react-router` image, a write refused to the `bun` user among them,
274
286
  **When:** `bun start` in an `api` project that was never built, or whose
275
287
  `dist/` was deleted.
276
288
 
277
- **Why:** `start` runs the build, `bun dist/server.js`, as the image does;
289
+ **Why:** `start` runs the build, `NODE_ENV=production bun dist/server.js`, as the image does;
278
290
  it no longer runs `src/server.ts`. `bun dev` runs the sources.
279
291
 
280
292
  **Fix:** build first:
@@ -510,6 +522,137 @@ reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id
510
522
  The other forms of the error, and how to turn the check off, are in
511
523
  [`@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
524
 
525
+ ## The `graphql` project's schema
526
+
527
+ ### `The following stale files were detected: src/generated/resolvers.ts`
528
+
529
+ `bun run verify` stops at its first step, with the stale file listed
530
+ below the line:
531
+
532
+ ```
533
+ The following stale files were detected:
534
+ - src/generated/resolvers.ts
535
+ ```
536
+
537
+ **When:** `bun run generate --check`, alone or as `verify`'s first step,
538
+ after `schema.graphql` or `codegen.ts` changed and `bun run generate` was
539
+ not run, or after `src/generated/resolvers.ts` was edited by hand. It
540
+ writes nothing and exits 1.
541
+
542
+ **Why:** `src/generated/` is committed, so that nothing is generated at
543
+ install or build; the check is what keeps it equal to `schema.graphql`.
544
+
545
+ **Fix:** generate, then commit the file with the schema:
546
+
547
+ ```sh
548
+ bun run generate
549
+ git add schema.graphql src/generated
550
+ ```
551
+
552
+ A change made by hand in `src/generated/` is lost: make it in
553
+ `schema.graphql`, or in `codegen.ts`.
554
+
555
+ ### `src/generated/` changes after moving `@graphql-codegen/*`
556
+
557
+ **Symptom:** `bun run verify` fails with
558
+ `The following stale files were detected` right after
559
+ `bun add --dev --exact @graphql-codegen/cli@…`, or one of the two
560
+ plugins, with no change to `schema.graphql`.
561
+
562
+ **When:** a generator moved to another version. A new project never hits
563
+ it: the command keeps the template's versions, `@graphql-codegen/cli` 7.4.3,
564
+ `typescript` 6.1.0 and `typescript-resolvers` 6.1.0
565
+ ([Versions](guide.md#versions)).
566
+
567
+ **Why:** `src/generated/resolvers.ts` is the output of one release of the
568
+ generator and its plugins, and another may write it differently. That is
569
+ why the template pins the three exactly.
570
+
571
+ **Fix:** generate again, read what changed before committing it, and verify:
572
+
573
+ ```sh
574
+ bun run generate
575
+ git diff src/generated
576
+ bun run verify
577
+ ```
578
+
579
+ To stay where you were, pin the previous versions again:
580
+ `bun add --dev --exact @graphql-codegen/cli@7.4.3`.
581
+
582
+ ### `error: Could not resolve: "../schema.graphql"`, or `TS2307` for it
583
+
584
+ **When:** `bun run build` prints `error: Could not resolve: "../schema.graphql"`, or `bun run typecheck` prints `error TS2307: Cannot find module '../schema.graphql' or its corresponding type declarations`: neither can resolve the import
585
+ of `schema.graphql` that `src/schema.ts` makes, or the file is not where
586
+ `../schema.graphql` says: the project's root.
587
+
588
+ **Why:** the import is `import typeDefs from "../schema.graphql" with { type: "text" }`:
589
+ Bun reads the file as text, and `bun run build` bundles it into
590
+ `dist/server.js`. TypeScript knows the module through `src/graphql.d.ts`,
591
+ which declares `*.graphql`, and the text attribute is what makes Bun read
592
+ it as a string and not as a module.
593
+
594
+ **Fix:** keep `schema.graphql` at the root, `src/graphql.d.ts` in
595
+ `src/` (the `tsconfig.json` includes `src`), and the import as written,
596
+ attribute included:
597
+
598
+ ```ts
599
+ import typeDefs from "../schema.graphql" with { type: "text" };
600
+ ```
601
+
602
+ ### `Sign in to add a note`
603
+
604
+ **When:** a new project's `addNote` mutation answers an error with the
605
+ message `Sign in to add a note` and the code `UNAUTHENTICATED`. It is the
606
+ template working, not failing.
607
+
608
+ **Why:** `viewerOf` reads `Authorization: Bearer <token>` and gives each
609
+ resolver a `viewer`, `null` without a known token; `addNote` throws a
610
+ `GraphQLError` when it is `null`. The development token is `ada-token`.
611
+
612
+ **Fix:** send it:
613
+
614
+ ```sh
615
+ curl localhost:3000/graphql -H 'content-type: application/json' \
616
+ -H 'authorization: Bearer ada-token' \
617
+ -d '{"query":"mutation { addNote(text: \"Hello\") { id } }"}'
618
+ ```
619
+
620
+ Tokens live in `src/store.ts`: replace them with a session lookup or a
621
+ JWT check outside development.
622
+
623
+ ## The environment
624
+
625
+ ### `EnvError: The environment is invalid:`
626
+
627
+ `bun dev`, `bun start` or `bun test` stops before it listens, in the `api`
628
+ and `graphql` projects, with every variable that failed:
629
+
630
+ ```
631
+ EnvError: The environment is invalid:
632
+ PORT: Invalid input: expected number, received NaN; expected number
633
+ API_KEY: Invalid input: expected string, received undefined; expected string
634
+ ```
635
+
636
+ **Why:** `src/env.ts` calls `defineEnv` from `@alxia/env`, which checks each
637
+ variable with its own Zod schema once, when the module is first imported,
638
+ from `Bun.env` (the shell's, and the `.env` Bun loads). A value that fails
639
+ stops the process, as the first request that read it would have failed
640
+ later. A secret's value is never printed: `API_KEY` shows as `***`.
641
+
642
+ **Fix:** set the variables the message names, in the shell or in `.env`
643
+ (`cp .env.example .env`), or remove the wrong line:
644
+
645
+ ```sh
646
+ PORT=3000 bun dev
647
+ ```
648
+
649
+ A variable the schema gives a default (`PORT`, the `api` project's
650
+ `API_DOCS`) is fine unset. The `api` project's `API_KEY` defaults to
651
+ `dev-key` under `NODE_ENV=development` (`bun dev`) and `test` (`bun test`)
652
+ alone: `bun start`, the image and any other `NODE_ENV` require it, so set
653
+ it there (`docker run -e API_KEY=…`). `bun test` sets `NODE_ENV=test`: a
654
+ `.env` that sets `NODE_ENV` to another value overrides it.
655
+
513
656
  ## Biome
514
657
 
515
658
  ### `bun ci` installs, and checks nothing
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@alxia/create",
3
- "version": "0.1.7",
4
- "description": "Start an alxia app: `bun create @alxia` writes an API with Zod, or React Router's official template served by alxia",
3
+ "version": "0.3.0",
4
+ "description": "Start an alxia app: `bun create @alxia` writes a minimal API, a spec-first one, a GraphQL one, or React Router's official template served by alxia",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {
@@ -10,7 +10,9 @@
10
10
  "files": [
11
11
  "dist",
12
12
  "docs",
13
+ "templates/minimal",
13
14
  "templates/api",
15
+ "templates/graphql",
14
16
  "templates/react-router",
15
17
  "README.md",
16
18
  "package.json",
@@ -39,11 +41,20 @@
39
41
  ]
40
42
  },
41
43
  "devDependencies": {
42
- "@alxia/core": "^0.4.0",
43
- "@alxia/openapi": "^0.4.1",
44
- "@alxia/react-router": "^0.5.0",
44
+ "@alxia/core": "^0.6.0",
45
+ "@alxia/env": "^0.2.0",
46
+ "@alxia/graphql": "^0.3.1",
47
+ "@alxia/openapi": "^0.5.1",
48
+ "@alxia/react-router": "^0.6.1",
49
+ "@graphql-codegen/cli": "7.4.3",
50
+ "@graphql-codegen/typescript": "6.1.0",
51
+ "@graphql-codegen/typescript-resolvers": "6.1.0",
45
52
  "@nxgt/openapi-codegen": "0.7.0",
46
53
  "@types/bun": "^1.4.2",
54
+ "dataloader": "^2.2.3",
55
+ "graphql": "^16.11.0 || ^17.0.0",
56
+ "graphql-yoga": "^5.16.0",
57
+ "openapi-fetch": "^0.17.0",
47
58
  "zod": "^4.6.5"
48
59
  }
49
60
  }
@@ -1,3 +1,11 @@
1
1
  # Copy to .env, which Bun loads on every command: bun dev, bun test, bun start.
2
+ # string, required; default dev-key in development and test alone, secret
3
+ # Left out: a .env holding it would give `bun start` the development key too.
4
+ # An empty value is refused, even under bun dev: give it one, or leave it out.
5
+ # API_KEY=change-me
6
+
7
+ # boolean, optional, default true in development, false elsewhere: the API reference at /docs
8
+ # API_DOCS=true
9
+
10
+ # number, optional, default 3000
2
11
  PORT=3000
3
- API_KEY=dev-key
@@ -12,8 +12,10 @@ operations generated from it, and a client is generated from the same file.
12
12
  (`openapi-codegen.config.ts`). `alxia.ts` holds each operation as the
13
13
  data `app.route()` takes. Never edit it: change `openapi.yaml`, then
14
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
15
+ - `src/context.ts`: the base, what every route reads (the todos), alxia's
16
+ own errors as RFC 9457 problems (`alxia({ errors: "problem" })`: a 400
17
+ the schemas refuse is `application/problem+json`, as `openapi.yaml`
18
+ declares it), and its `Register` declaration: a route file reads that context with no
17
19
  import of the app. Register the base, never the app, which mounts the
18
20
  route files and would be typed by itself.
19
21
  - `src/routes/todos.ts`: the routes, `defineRoutes()`, each bound to an
@@ -22,10 +24,23 @@ operations generated from it, and a client is generated from the same file.
22
24
  answers 401 without the `x-api-key` header; the operation's body is
23
25
  validated just before the handler, and the handler's reply checked
24
26
  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.
27
- - `src/server.ts`: listens on `PORT`, 3000 by default.
28
- - `src/app.spec.ts`: `app.request()`, no port, and `matchesSpec` from
27
+ - `src/app.ts`: the app: the base, `health()`'s probes (`GET /health`,
28
+ liveness, and `GET /ready`, readiness), `apiDocs` from `@alxia/openapi`
29
+ (the API reference at `/docs`, `openapi.yaml` at `/docs/openapi.yaml`),
30
+ then `todoRoutes`. `openapi.yaml` is imported, so the build bundles it.
31
+ Mounting the routes on an app that does not give the base's context is a
32
+ compile error.
33
+ - `src/env.ts`: the environment, `defineEnv` from
34
+ [`@alxia/env`](https://www.npmjs.com/package/@alxia/env): `PORT`,
35
+ `API_KEY` and `API_DOCS`, each checked by its own Zod schema once, when
36
+ the module is first imported. A missing or malformed one stops the
37
+ process with every issue, before it listens, and `API_KEY` prints as
38
+ `***`.
39
+ - `src/server.ts`: listens on `env.PORT`, 3000 by default, and shuts down
40
+ gracefully on `SIGINT` and `SIGTERM`, which `listen` handles.
41
+ - `src/app.spec.ts`: a typed client (openapi-fetch over `generated/paths.ts`,
42
+ its `fetch` being `app.fetch`: no server, no port), one `app.request()`
43
+ test, and `matchesSpec` from
29
44
  [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every
30
45
  operation of `openapi.yaml` has its route, and no route is outside it.
31
46
  - `biome.json`: Biome's lint and format settings ([Lint and format](#lint-and-format)).
@@ -54,9 +69,15 @@ Zod validators and the operations a typed client reads.
54
69
 
55
70
  ## Environment
56
71
 
57
- Bun loads `.env` on every command. Copy `.env.example` to `.env` to set
58
- `PORT` and `API_KEY`. Outside development, set `API_KEY`: its default,
59
- `dev-key`, is for development only.
72
+ Bun loads `.env` on every command, and `src/env.ts` checks what it finds.
73
+ Copy `.env.example` to `.env` to set `PORT`, `API_KEY` and `API_DOCS`.
74
+ `API_KEY` defaults to `dev-key` under `NODE_ENV=development` (`bun dev`)
75
+ and `test` (`bun test`) alone: anywhere else, `bun start` and the image
76
+ included, it is required, and the app does not start without it.
77
+ `API_DOCS` serves the API reference at `/docs`: on in development, off
78
+ elsewhere unless set to `true`. The document is public wherever it is on.
79
+ A variable that fails its schema stops the app with every issue named,
80
+ never the secret's value.
60
81
 
61
82
  ```sh
62
83
  cp .env.example .env
@@ -65,13 +86,19 @@ cp .env.example .env
65
86
  ## Develop
66
87
 
67
88
  ```sh
68
- bun dev # http://localhost:3000, restarted on every change
89
+ bun dev # NODE_ENV=development: http://localhost:3000, restarted on every change
69
90
  ```
70
91
 
92
+ `bun dev` sets `NODE_ENV=development`, alxia's dev switch: `listen`
93
+ prints the route table, a 404 hints at the closest route, a 500 shows its
94
+ error, and `/docs` is on. Under any other `NODE_ENV`, none of them is.
95
+
71
96
  ```sh
72
97
  curl -X POST localhost:3000/todos \
73
98
  -H 'content-type: application/json' -H 'x-api-key: dev-key' \
74
99
  -d '{"title":"Write a route"}'
100
+ curl localhost:3000/health # {"status":"ok"}
101
+ open http://localhost:3000/docs
75
102
  ```
76
103
 
77
104
  ## Test
@@ -117,7 +144,7 @@ runs it: what production and the image run.
117
144
 
118
145
  ```sh
119
146
  bun run build # dist/server.js and dist/server.js.map
120
- bun start # bun dist/server.js
147
+ bun start # NODE_ENV=production bun dist/server.js
121
148
  ```
122
149
 
123
150
  `bun start` before any build fails with `Module not found
@@ -139,13 +166,14 @@ that `bun install` wrote (commit it), and runs `bun run build`. The image
139
166
  holds `dist/` alone, no `node_modules` and no `src/`, and runs
140
167
  `bun --no-install dist/server.js` as its non-root `bun` user: a package
141
168
  missing from the bundle fails at startup instead of being fetched from
142
- npm. `src/server.ts` stops the app on `SIGTERM`, so `docker stop` is
169
+ npm. `listen` drains the app and exits on `SIGTERM`, so `docker stop` is
143
170
  immediate. A native addon built for glibc alone does not load on
144
171
  Alpine: put the final stage back on `oven/bun:1`.
145
172
 
146
173
  ```sh
147
174
  docker build -t my-api .
148
175
  docker run --rm -p 3000:3000 -e API_KEY=change-me my-api
176
+ # with the API reference at /docs: -e API_DOCS=true
149
177
  ```
150
178
 
151
179
  Next: [Getting started](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/getting-started.md)
@@ -34,7 +34,7 @@ paths:
34
34
  application/json:
35
35
  schema: { $ref: "#/components/schemas/Todo" }
36
36
  "400":
37
- $ref: "#/components/responses/ValidationError"
37
+ $ref: "#/components/responses/ValidationProblem"
38
38
  "401":
39
39
  description: No x-api-key header, or not the key
40
40
  content:
@@ -56,7 +56,7 @@ paths:
56
56
  application/json:
57
57
  schema: { $ref: "#/components/schemas/Todo" }
58
58
  "400":
59
- $ref: "#/components/responses/ValidationError"
59
+ $ref: "#/components/responses/ValidationProblem"
60
60
  "404":
61
61
  description: No todo has this id
62
62
  content:
@@ -66,11 +66,11 @@ components:
66
66
  securitySchemes:
67
67
  apiKey: { type: apiKey, in: header, name: x-api-key }
68
68
  responses:
69
- ValidationError:
70
- description: alxia's own 400, for a request the schemas refuse
69
+ ValidationProblem:
70
+ description: alxia's own 400, for a request the schemas refuse, as an RFC 9457 problem
71
71
  content:
72
- application/json:
73
- schema: { $ref: "#/components/schemas/ValidationError" }
72
+ application/problem+json:
73
+ schema: { $ref: "#/components/schemas/ValidationProblem" }
74
74
  schemas:
75
75
  Todo:
76
76
  type: object
@@ -94,11 +94,15 @@ components:
94
94
  required: [error]
95
95
  properties:
96
96
  error: { type: string, enum: [not_found] }
97
- ValidationError:
97
+ ValidationProblem:
98
98
  type: object
99
- required: [error, issues]
99
+ required: [type, title, status, detail, instance, issues]
100
100
  properties:
101
- error: { type: string, enum: [validation] }
101
+ type: { type: string }
102
+ title: { type: string }
103
+ status: { type: integer }
104
+ detail: { type: string }
105
+ instance: { type: string }
102
106
  issues:
103
107
  type: array
104
108
  items:
@@ -4,9 +4,9 @@
4
4
  "type": "module",
5
5
  "scripts": {
6
6
  "generate": "nxgt-openapi generate",
7
- "dev": "bun --watch src/server.ts",
7
+ "dev": "NODE_ENV=development bun --watch src/server.ts",
8
8
  "build": "bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked",
9
- "start": "bun dist/server.js",
9
+ "start": "NODE_ENV=production bun dist/server.js",
10
10
  "test": "bun test",
11
11
  "typecheck": "tsc --noEmit",
12
12
  "lint": "biome lint",
@@ -17,13 +17,15 @@
17
17
  },
18
18
  "dependencies": {
19
19
  "@alxia/core": "workspace:^",
20
+ "@alxia/env": "workspace:^",
21
+ "@alxia/openapi": "workspace:^",
20
22
  "zod": "^4.5.4"
21
23
  },
22
24
  "devDependencies": {
23
- "@alxia/openapi": "workspace:^",
24
25
  "@biomejs/biome": "2.5.15",
25
26
  "@nxgt/openapi-codegen": "0.7.0",
26
27
  "@types/bun": "^1.4.2",
28
+ "openapi-fetch": "^0.17.0",
27
29
  "typescript": "^6.0.3"
28
30
  }
29
31
  }
@@ -1,65 +1,79 @@
1
1
  import { expect, test } from "bun:test";
2
2
  import { matchesSpec } from "@alxia/openapi";
3
+ import createClient from "openapi-fetch";
3
4
  import { app } from "./app";
4
- import { apiKey } from "./context";
5
+ import { env } from "./env";
5
6
  import { operations } from "./generated/alxia";
7
+ import type { paths } from "./generated/paths";
6
8
 
7
- const json = { "content-type": "application/json", "x-api-key": apiKey };
9
+ // The client types every call from openapi.yaml (generated/paths.ts) and
10
+ // sends it to the app in-process: no server, no port.
11
+ const api = createClient<paths>({
12
+ baseUrl: "http://alxia.test",
13
+ fetch: (request) => app.fetch(request),
14
+ headers: { "x-api-key": env.API_KEY },
15
+ });
8
16
 
9
17
  test("routes every operation of openapi.yaml, and nothing else", () => {
10
18
  matchesSpec(app, operations);
11
19
  });
12
20
 
13
21
  test("creates a todo from JSON", async () => {
14
- const response = await app.request("/todos", {
15
- method: "POST",
16
- headers: json,
17
- body: JSON.stringify({ title: "Write a route" }),
22
+ const { data, response } = await api.POST("/todos", {
23
+ body: { title: "Write a route" },
18
24
  });
19
25
  expect(response.status).toBe(201);
20
- expect(await response.json()).toEqual({
26
+ expect(data).toEqual({
21
27
  id: expect.any(Number),
22
28
  title: "Write a route",
23
29
  done: false,
24
30
  });
25
31
  });
26
32
 
27
- test("refuses an empty title with a 400 naming it", async () => {
28
- const response = await app.request("/todos", {
29
- method: "POST",
30
- headers: json,
31
- body: JSON.stringify({ title: "" }),
33
+ test("refuses an empty title with a 400 problem naming it", async () => {
34
+ const { error, response } = await api.POST("/todos", {
35
+ body: { title: "" },
32
36
  });
33
37
  expect(response.status).toBe(400);
34
- expect((await response.json()).issues[0].path).toEqual(["title"]);
38
+ expect(response.headers.get("content-type")).toBe("application/problem+json");
39
+ // error is the 400 or the 401 body: a match, not a property read
40
+ expect(error).toMatchObject({ status: 400, issues: [{ path: ["title"] }] });
35
41
  });
36
42
 
37
43
  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: "" }),
44
+ const { error, response } = await api.POST("/todos", {
45
+ body: { title: "" },
46
+ headers: { "x-api-key": "wrong" },
42
47
  });
43
48
  expect(response.status).toBe(401); // requireKey stands before the validation
44
- expect(await response.json()).toEqual({ error: "unauthorized" });
49
+ expect(error).toEqual({ error: "unauthorized" });
45
50
  });
46
51
 
47
52
  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" }),
53
+ const created = await api.POST("/todos", { body: { title: "Find me" } });
54
+ const id = created.data?.id ?? 0;
55
+ const found = await api.GET("/todos/{id}", { params: { path: { id } } });
56
+ expect(found.data?.title).toBe("Find me");
57
+ const missing = await api.GET("/todos/{id}", {
58
+ params: { path: { id: 9999 } },
52
59
  });
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);
60
+ expect(missing.response.status).toBe(404);
61
+ // `id: "first"` is a compile error here; app.request sends what it is told.
58
62
  expect((await app.request("/todos/first")).status).toBe(400);
59
63
  });
60
64
 
61
65
  test("lists the todos", async () => {
66
+ const { data } = await api.GET("/todos");
67
+ expect(Array.isArray(data)).toBe(true);
68
+ });
69
+
70
+ test("answers the liveness probe", async () => {
71
+ const response = await app.request("/health");
72
+ expect(response.status).toBe(200);
73
+ expect(await response.json()).toEqual({ status: "ok" });
74
+ });
75
+
76
+ test("app.request is the same app, with a hand-written request", async () => {
62
77
  const response = await app.request("/todos");
63
78
  expect(response.status).toBe(200);
64
- expect(Array.isArray(await response.json())).toBe(true);
65
79
  });
@@ -1,8 +1,18 @@
1
+ import { health } from "@alxia/core";
2
+ import { apiDocs } from "@alxia/openapi";
3
+ import spec from "../openapi.yaml";
1
4
  import { base } from "./context";
5
+ import { env } from "./env";
2
6
  import { todoRoutes } from "./routes/todos";
3
7
 
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);
8
+ // The base, then the probes (GET /health, GET /ready) before any guard,
9
+ // the API reference at /docs (on in development; API_DOCS=true elsewhere),
10
+ // and the route files: each requires the base's context, so mounting one
11
+ // before it is a compile error. openapi.yaml is imported, so `bun run build`
12
+ // puts it inside dist/server.js: the image needs no copy of it.
13
+ export const app = base
14
+ .plugin(health())
15
+ .plugin(apiDocs({ spec, enabled: env.API_DOCS }))
16
+ .plugin(todoRoutes);
7
17
 
8
18
  export type App = typeof app;
@@ -1,14 +1,13 @@
1
1
  import { alxia } from "@alxia/core";
2
2
  import type { Todo } from "./generated/types";
3
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
4
  const todos: Todo[] = [];
8
5
 
9
6
  // The base: what every route reads, decorated or derived here. It is
10
7
  // registered below, so a route file reads it with no import of the app.
11
- export const base = alxia().decorate({ todos });
8
+ // alxia's own errors — a 400 the schemas refuse, a 404 no route matches, a
9
+ // 500 — are RFC 9457 problems, as openapi.yaml declares them.
10
+ export const base = alxia({ errors: "problem" }).decorate({ todos });
12
11
 
13
12
  // Register the base, never the app: the app mounts the route files, whose
14
13
  // type reads this, and would then be typed by itself.