@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 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.
@@ -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.0",
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",
@@ -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`