@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.
- package/README.md +80 -25
- package/dist/args.d.ts +3 -1
- package/dist/args.d.ts.map +1 -1
- package/dist/index.js +19 -9
- package/dist/index.js.map +7 -7
- package/dist/main.d.ts +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/registry.d.ts +2 -0
- package/dist/registry.d.ts.map +1 -1
- package/dist/versions.d.ts +5 -2
- package/dist/versions.d.ts.map +1 -1
- package/docs/README.md +16 -6
- package/docs/guide.md +428 -47
- package/docs/roadmap.md +24 -0
- package/docs/troubleshooting.md +152 -9
- package/package.json +16 -5
- package/templates/api/.env.example +9 -1
- package/templates/api/README.md +40 -12
- package/templates/api/openapi.yaml +13 -9
- package/templates/api/package.json +5 -3
- package/templates/api/src/app.spec.ts +42 -28
- package/templates/api/src/app.ts +13 -3
- package/templates/api/src/context.ts +3 -4
- package/templates/api/src/env.ts +20 -0
- package/templates/api/src/generated/alxia.ts +3 -3
- package/templates/api/src/generated/operations.ts +3 -3
- package/templates/api/src/generated/paths.ts +6 -6
- package/templates/api/src/generated/types.ts +14 -10
- package/templates/api/src/generated/zod.ts +6 -2
- package/templates/api/src/routes/todos.ts +2 -2
- package/templates/api/src/server.ts +8 -16
- package/templates/graphql/.dockerignore +6 -0
- package/templates/graphql/.env.example +3 -0
- package/templates/graphql/.vscode/extensions.json +3 -0
- package/templates/graphql/.vscode/settings.json +8 -0
- package/templates/graphql/Dockerfile +26 -0
- package/templates/graphql/README.md +185 -0
- package/templates/graphql/_biome.json +32 -0
- package/templates/graphql/codegen.ts +22 -0
- package/templates/graphql/gitignore +6 -0
- package/templates/graphql/package.json +35 -0
- package/templates/graphql/schema.graphql +26 -0
- package/templates/graphql/src/app.spec.ts +146 -0
- package/templates/graphql/src/app.ts +18 -0
- package/templates/graphql/src/context.ts +26 -0
- package/templates/graphql/src/env.ts +8 -0
- package/templates/graphql/src/generated/resolvers.ts +180 -0
- package/templates/graphql/src/graphql.d.ts +6 -0
- package/templates/graphql/src/loaders.ts +13 -0
- package/templates/graphql/src/resolvers.ts +39 -0
- package/templates/graphql/src/schema.ts +6 -0
- package/templates/graphql/src/server.ts +10 -0
- package/templates/graphql/src/store.ts +38 -0
- package/templates/graphql/tsconfig.json +25 -0
- package/templates/minimal/.dockerignore +6 -0
- package/templates/minimal/.vscode/extensions.json +3 -0
- package/templates/minimal/.vscode/settings.json +8 -0
- package/templates/minimal/Dockerfile +26 -0
- package/templates/minimal/README.md +107 -0
- package/templates/minimal/_biome.json +32 -0
- package/templates/minimal/gitignore +6 -0
- package/templates/minimal/package.json +25 -0
- package/templates/minimal/src/index.spec.ts +12 -0
- package/templates/minimal/src/index.ts +17 -0
- package/templates/minimal/tsconfig.json +25 -0
- 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
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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.
|
|
4
|
-
"description": "Start an alxia app: `bun create @alxia` writes
|
|
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.
|
|
43
|
-
"@alxia/
|
|
44
|
-
"@alxia/
|
|
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
|
package/templates/api/README.md
CHANGED
|
@@ -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),
|
|
16
|
-
|
|
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, `
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
58
|
-
`
|
|
59
|
-
`dev-key
|
|
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. `
|
|
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/
|
|
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/
|
|
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
|
-
|
|
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/
|
|
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
|
-
|
|
97
|
+
ValidationProblem:
|
|
98
98
|
type: object
|
|
99
|
-
required: [
|
|
99
|
+
required: [type, title, status, detail, instance, issues]
|
|
100
100
|
properties:
|
|
101
|
-
|
|
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 {
|
|
5
|
+
import { env } from "./env";
|
|
5
6
|
import { operations } from "./generated/alxia";
|
|
7
|
+
import type { paths } from "./generated/paths";
|
|
6
8
|
|
|
7
|
-
|
|
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
|
|
15
|
-
|
|
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(
|
|
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
|
|
29
|
-
|
|
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(
|
|
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
|
|
39
|
-
|
|
40
|
-
headers: { "
|
|
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(
|
|
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
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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
|
-
|
|
54
|
-
|
|
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
|
});
|
package/templates/api/src/app.ts
CHANGED
|
@@ -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
|
|
5
|
-
//
|
|
6
|
-
|
|
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
|
-
|
|
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.
|