@alxia/create 0.1.6 → 0.1.7
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
CHANGED
|
@@ -166,7 +166,7 @@ or CI.
|
|
|
166
166
|
template's minor, `2.5.15` writing `2.5.16` but never `2.6.0`, whose new
|
|
167
167
|
rules the template was not checked against.
|
|
168
168
|
- **`@nxgt/openapi-codegen`** is pinned exactly and kept at the template's
|
|
169
|
-
version, `0.
|
|
169
|
+
version, `0.7.0`, never moved to a newer patch: `bun run verify` runs
|
|
170
170
|
`generate --check` over the committed `src/generated/`, which a release
|
|
171
171
|
that writes the files differently would fail in a fresh project.
|
|
172
172
|
|
package/docs/guide.md
CHANGED
|
@@ -232,19 +232,20 @@ bun run generate
|
|
|
232
232
|
git diff src/generated
|
|
233
233
|
```
|
|
234
234
|
|
|
235
|
-
What the generator does not write, in 0.
|
|
235
|
+
What the generator does not write, in 0.7.0, and how the app does it
|
|
236
236
|
instead:
|
|
237
237
|
|
|
238
238
|
- **`security`**: no middleware is generated from it. Authentication is
|
|
239
239
|
a middleware the app writes, `requireKey` here, given to the routes
|
|
240
240
|
that need it.
|
|
241
|
-
- **A cookie parameter
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
- **
|
|
246
|
-
|
|
247
|
-
by hand with `@alxia/core`'s `eventStream`.
|
|
241
|
+
- **A cookie parameter in the client files**: `alxia.ts` validates it as
|
|
242
|
+
the route's `cookies`; `types.ts`, `zod.ts`, `operations.ts` and
|
|
243
|
+
`paths.ts` leave it out with an `ignored` warning, since a client does not
|
|
244
|
+
set cookies.
|
|
245
|
+
- **Server-sent events with text data**: the operation is left out of
|
|
246
|
+
`alxia.ts` with a warning; give each event's data a JSON `contentSchema`,
|
|
247
|
+
or declare that route by hand with `@alxia/core`'s `eventStream`. Named
|
|
248
|
+
events whose data is JSON are generated.
|
|
248
249
|
|
|
249
250
|
### `src/context.ts`
|
|
250
251
|
|
|
@@ -771,7 +772,7 @@ template pins exactly:
|
|
|
771
772
|
| `vite` | `^7.0.0 \|\| ^8.0.0`, `@alxia/react-router`'s |
|
|
772
773
|
| `react-router`, `@react-router/*` | `^8.0.0`, `@alxia/react-router`'s; the `@react-router/*` packages take `react-router`'s version, which `@react-router/node` pins exactly |
|
|
773
774
|
| `@biomejs/biome` | its own minor, from the exact version the template pins (`~2.5.15`): written exactly, `2.5.16`, never `^`. A minor of Biome may add a recommended rule |
|
|
774
|
-
| `@nxgt/openapi-codegen` | none: the template's exact version, `0.
|
|
775
|
+
| `@nxgt/openapi-codegen` | none: the template's exact version, `0.7.0`, is kept. Any release may write `src/generated/` differently, and `bun run verify` checks it with `generate --check` |
|
|
775
776
|
| anything else: `react`, `isbot`, Tailwind, `@types/*` | no alxia range: npm's `latest` |
|
|
776
777
|
|
|
777
778
|
The command prints each move, and each newer major it left out:
|
package/docs/troubleshooting.md
CHANGED
|
@@ -32,7 +32,6 @@ print, or — for a trap that prints 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)
|
|
36
35
|
|
|
37
36
|
**After**
|
|
38
37
|
|
|
@@ -48,7 +47,6 @@ print, or — for a trap that prints nothing — the symptom.
|
|
|
48
47
|
- [`src/generated/` changes after moving `@nxgt/openapi-codegen`](#srcgenerated-changes-after-moving-nxgtopenapi-codegen)
|
|
49
48
|
- [`TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`](#typeerror-matchesspec-1-operation-has-no-route-delete-todosid-deletetodo)
|
|
50
49
|
- [`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
50
|
|
|
53
51
|
**Biome**
|
|
54
52
|
|
|
@@ -255,23 +253,6 @@ the next steps.
|
|
|
255
253
|
**Fix:** what its output says, then `cd my-app && bun install`. The
|
|
256
254
|
project is complete; only `node_modules` is missing.
|
|
257
255
|
|
|
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
|
-
|
|
275
256
|
## After
|
|
276
257
|
|
|
277
258
|
### `error: lockfile had changes, but lockfile is frozen`
|
|
@@ -445,7 +426,7 @@ A change made by hand in `src/generated/` is lost: make it in
|
|
|
445
426
|
right after `bun add --dev --exact @nxgt/openapi-codegen@…`, with no
|
|
446
427
|
change to `openapi.yaml`.
|
|
447
428
|
|
|
448
|
-
**When:** the generator moved to another minor, `0.
|
|
429
|
+
**When:** the generator moved to another minor, `0.7.x` to `0.8.0`. A new
|
|
449
430
|
project never hits it: the command keeps the template's version
|
|
450
431
|
([Versions](guide.md#versions)).
|
|
451
432
|
|
|
@@ -464,8 +445,8 @@ bun run verify
|
|
|
464
445
|
|
|
465
446
|
The diff is what the new release writes differently; `bun run verify`
|
|
466
447
|
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.
|
|
448
|
+
where you were, pin the previous version again, `0.7.0` after a move to `0.8.0`:
|
|
449
|
+
`bun add --dev --exact @nxgt/openapi-codegen@0.7.0`.
|
|
469
450
|
|
|
470
451
|
### `TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`
|
|
471
452
|
|
|
@@ -529,34 +510,6 @@ reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id
|
|
|
529
510
|
The other forms of the error, and how to turn the check off, are in
|
|
530
511
|
[`@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
512
|
|
|
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
513
|
## Biome
|
|
561
514
|
|
|
562
515
|
### `bun ci` installs, and checks nothing
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alxia/create",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
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",
|
|
@@ -40,9 +40,9 @@
|
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
42
|
"@alxia/core": "^0.4.0",
|
|
43
|
-
"@alxia/openapi": "^0.4.
|
|
43
|
+
"@alxia/openapi": "^0.4.1",
|
|
44
44
|
"@alxia/react-router": "^0.5.0",
|
|
45
|
-
"@nxgt/openapi-codegen": "0.
|
|
45
|
+
"@nxgt/openapi-codegen": "0.7.0",
|
|
46
46
|
"@types/bun": "^1.4.2",
|
|
47
47
|
"zod": "^4.6.5"
|
|
48
48
|
}
|
|
@@ -1,9 +1,19 @@
|
|
|
1
1
|
// Generated by @nxgt/openapi-codegen from ../../openapi.yaml. Do not edit.
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* Each operation as `@alxia/core`'s `app.route(operation, ...middlewares, handler)`
|
|
5
|
+
* takes it, @alxia/core 0.4 or later. The route validates the request and
|
|
6
|
+
* checks the handler's reply against `schema.response`, both just before
|
|
7
|
+
* the handler: `validate(operation)` or `responds(operation)` stands
|
|
8
|
+
* earlier among the middlewares when one is placed there.
|
|
9
|
+
* `matchesSpec(app, operations)`, from `@alxia/openapi`, fails while an
|
|
10
|
+
* operation has no route.
|
|
11
|
+
*/
|
|
12
|
+
|
|
3
13
|
import { z } from 'zod';
|
|
4
14
|
import { zNewTodo, zNotFound, zTodo, zUnauthorized, zValidationError } from './zod';
|
|
5
15
|
|
|
6
|
-
/** A number in a path, a query or a
|
|
16
|
+
/** A number in a path, a query, a header or a cookie: digits, where z.coerce.number() would read '' as 0. */
|
|
7
17
|
const numeric = z
|
|
8
18
|
.string()
|
|
9
19
|
.regex(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/)
|
|
@@ -53,7 +63,7 @@ export const getTodo = {
|
|
|
53
63
|
},
|
|
54
64
|
} as const;
|
|
55
65
|
|
|
56
|
-
/** Every operation alxia routes, by operationId: `app.route(operations.listTodos, handler)`. */
|
|
66
|
+
/** Every operation alxia routes, by operationId: `app.route(operations.listTodos, ...middlewares, handler)`. */
|
|
57
67
|
export const operations = {
|
|
58
68
|
listTodos,
|
|
59
69
|
createTodo,
|
|
@@ -52,7 +52,7 @@ export interface OperationSpec<Client = unknown> {
|
|
|
52
52
|
/** A location with no parameters declared: whatever arrives there is dropped. */
|
|
53
53
|
const none = z.object({});
|
|
54
54
|
|
|
55
|
-
/** A number in a path, a query or a
|
|
55
|
+
/** A number in a path, a query, a header or a cookie: digits, where z.coerce.number() would read '' as 0. */
|
|
56
56
|
const numeric = z
|
|
57
57
|
.string()
|
|
58
58
|
.regex(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/)
|