@alxia/create 0.5.0 → 0.5.1
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/docs/README.md +1 -1
- package/docs/guide.md +2 -0
- package/docs/roadmap.md +11 -0
- package/docs/troubleshooting.md +63 -0
- package/package.json +1 -1
- package/templates/api/README.md +5 -0
package/docs/README.md
CHANGED
|
@@ -10,7 +10,7 @@ errors the command and a new project print.
|
|
|
10
10
|
| Page | Read it when |
|
|
11
11
|
| --- | --- |
|
|
12
12
|
| [Guide](guide.md) | choosing a template, reading what it wrote, adding an operation to the `api` project's `openapi.yaml` or a field to the `graphql` project's `schema.graphql`, linting and formatting it with Biome, building its Docker image, pinning or moving versions, or running the command in a script or CI |
|
|
13
|
-
| [Troubleshooting](troubleshooting.md) | the command refused a directory, a template or an option, the registry did not answer or lacked a version, `bun install` failed, Biome refused to run in a project, or the `api` or `graphql` project's `generate --check`, an `api` `matchesSpec` or reply check, or a `graphql` schema import failed |
|
|
13
|
+
| [Troubleshooting](troubleshooting.md) | the command refused a directory, a template or an option, the registry did not answer or lacked a version, `bun install` failed, Biome refused to run in a project, or the `api` or `graphql` project's `generate --check`, an `api` `matchesSpec` or reply check, an `api` test's `ValidationError` or `UndeclaredStatusError`, or a `graphql` schema import failed |
|
|
14
14
|
| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |
|
|
15
15
|
|
|
16
16
|
## Recipes
|
package/docs/guide.md
CHANGED
|
@@ -570,6 +570,8 @@ request against the spec before it sends it, so the 400 and the 401 tests
|
|
|
570
570
|
use a second client built with `validate: { request: false }`, and a request
|
|
571
571
|
the types forbid (`/todos/first`) goes through `app.request`. See
|
|
572
572
|
[Testing with the generated client](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/testing.md).
|
|
573
|
+
A test that throws `ValidationError` or `UndeclaredStatusError` is in
|
|
574
|
+
[troubleshooting](troubleshooting.md#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters) ([the other](troubleshooting.md#undeclaredstatuserror-gettodo-get-todosid-no-418-reply-is-declared)).
|
|
573
575
|
|
|
574
576
|
### Adding an operation
|
|
575
577
|
|
package/docs/roadmap.md
CHANGED
|
@@ -39,6 +39,17 @@ Nothing scheduled yet.
|
|
|
39
39
|
|
|
40
40
|
## Shipped
|
|
41
41
|
|
|
42
|
+
### 0.5.1
|
|
43
|
+
|
|
44
|
+
- **The `api` template's client errors, documented and held in step.**
|
|
45
|
+
[Troubleshooting](troubleshooting.md#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters)
|
|
46
|
+
names the two errors a new project's tests can meet through the typed
|
|
47
|
+
client, `ValidationError` (a request the spec refuses never leaves the
|
|
48
|
+
test: use a second client with `validate: { request: false }`) and
|
|
49
|
+
`UndeclaredStatusError` (the app answered a status the spec does not
|
|
50
|
+
declare), and a spec of `@alxia/create` fails when the template's
|
|
51
|
+
`@nxgt/httpyz` and `@nxgt/openapi-httpyz` ranges differ from its own.
|
|
52
|
+
|
|
42
53
|
### 0.4.1
|
|
43
54
|
|
|
44
55
|
- **`graphqlClient` in the `graphql` template.** Its spec calls the app through `graphqlClient` from `@alxia/graphql/testing`, in place of a helper of its own.
|
package/docs/troubleshooting.md
CHANGED
|
@@ -47,6 +47,8 @@ print, or — for a trap that prints nothing — the symptom.
|
|
|
47
47
|
- [`src/generated/` changes after moving `@nxgt/openapi-codegen`](#srcgenerated-changes-after-moving-nxgtopenapi-codegen)
|
|
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
|
+
- [`ValidationError: createTodo (POST /todos): Too small: expected string to have >=1 characters`](#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters)
|
|
51
|
+
- [`UndeclaredStatusError: getTodo (GET /todos/{id}): no 418 reply is declared`](#undeclaredstatuserror-gettodo-get-todosid-no-418-reply-is-declared)
|
|
50
52
|
|
|
51
53
|
**The `graphql` project's schema**
|
|
52
54
|
|
|
@@ -523,6 +525,67 @@ reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id
|
|
|
523
525
|
The other forms of the error, and how to turn the check off, are in
|
|
524
526
|
[`@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).
|
|
525
527
|
|
|
528
|
+
### `ValidationError: createTodo (POST /todos): Too small: expected string to have >=1 characters`
|
|
529
|
+
|
|
530
|
+
A test of the app's own 400 or 401 throws in the test, before any request
|
|
531
|
+
reaches the app:
|
|
532
|
+
|
|
533
|
+
```text
|
|
534
|
+
ValidationError: createTodo (POST /todos): Too small: expected string to have >=1 characters
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
The operation, method and path are the call's, and the text after the colon is
|
|
538
|
+
the first issue's message (several are joined with `; `). The same class
|
|
539
|
+
also throws for a reply the spec does not describe (a body that is not valid
|
|
540
|
+
JSON, a value its schema refuses), whose `failure.kind` is `'response'`;
|
|
541
|
+
`'request'` is the one here.
|
|
542
|
+
|
|
543
|
+
**When:** the test sends what `openapi.yaml` refuses (an empty `title`, a
|
|
544
|
+
missing key) to see the app answer 400 or 401.
|
|
545
|
+
|
|
546
|
+
**Why:** the client checks every request against the spec before it sends
|
|
547
|
+
it, by default, and throws what the server would refuse. Nothing was sent.
|
|
548
|
+
|
|
549
|
+
**Fix:** build a second client that does not check requests, and use it for
|
|
550
|
+
the tests of a refusal. Keep the first one for the calls that must pass:
|
|
551
|
+
|
|
552
|
+
```ts
|
|
553
|
+
const api = createOpenApiClient(http, operations);
|
|
554
|
+
const raw = createOpenApiClient(http, operations, {
|
|
555
|
+
validate: { request: false },
|
|
556
|
+
});
|
|
557
|
+
|
|
558
|
+
const reply = await raw.op("createTodo", { json: { title: "" } });
|
|
559
|
+
expect(reply.status).toBe(400);
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
A request the types forbid (`/todos/first`) goes through `app.request()`.
|
|
563
|
+
See [Testing with the generated client](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/testing.md#keep-one-apprequest-test).
|
|
564
|
+
|
|
565
|
+
### `UndeclaredStatusError: getTodo (GET /todos/{id}): no 418 reply is declared`
|
|
566
|
+
|
|
567
|
+
A test through the client throws, naming the status the app answered:
|
|
568
|
+
|
|
569
|
+
```text
|
|
570
|
+
UndeclaredStatusError: getTodo (GET /todos/{id}): no 418 reply is declared
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
The error's `status` is the status and its `response` the unread `Response`,
|
|
574
|
+
so a test can read the body to see what the app sent.
|
|
575
|
+
|
|
576
|
+
**When:** the app answers a status `openapi.yaml` does not declare for that
|
|
577
|
+
operation: a 500 from a handler that threw, a 404 or 403 the spec never
|
|
578
|
+
mentioned, a status a middleware sent.
|
|
579
|
+
|
|
580
|
+
**Why:** the client reads a reply by the statuses the operation declares, so
|
|
581
|
+
a client generated from the spec never returns a body it was not told about.
|
|
582
|
+
|
|
583
|
+
**Fix:** if the status is right, declare it under the operation's
|
|
584
|
+
`responses` in `openapi.yaml`, then `bun run generate`; if the app should not
|
|
585
|
+
send it, fix the route (a 500 is usually the handler's bug, so read
|
|
586
|
+
`error.response`). A test of a status the spec leaves out on purpose goes through
|
|
587
|
+
`app.request()`, which reads whatever comes back.
|
|
588
|
+
|
|
526
589
|
## The `graphql` project's schema
|
|
527
590
|
|
|
528
591
|
### `The following stale files were detected: src/generated/resolvers.ts`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alxia/create",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.1",
|
|
4
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",
|
package/templates/api/README.md
CHANGED
|
@@ -139,6 +139,11 @@ bun run typecheck
|
|
|
139
139
|
bun run generate # src/generated/, from openapi.yaml
|
|
140
140
|
```
|
|
141
141
|
|
|
142
|
+
A test that throws `ValidationError` (the client refused a request the spec
|
|
143
|
+
forbids before sending it) or `UndeclaredStatusError` (the app answered a
|
|
144
|
+
status `openapi.yaml` does not declare) is in
|
|
145
|
+
[troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters).
|
|
146
|
+
|
|
142
147
|
## Lint and format
|
|
143
148
|
|
|
144
149
|
[Biome](https://biomejs.dev) lints and formats the project, as `biome.json`
|