@alxia/create 0.1.4 → 0.1.6

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 (44) hide show
  1. package/README.md +81 -24
  2. package/dist/copy.d.ts +11 -3
  3. package/dist/copy.d.ts.map +1 -1
  4. package/dist/index.js +51 -23
  5. package/dist/index.js.map +8 -7
  6. package/dist/main.d.ts +1 -1
  7. package/dist/main.d.ts.map +1 -1
  8. package/dist/packument.d.ts +18 -0
  9. package/dist/packument.d.ts.map +1 -0
  10. package/dist/registry.d.ts +29 -10
  11. package/dist/registry.d.ts.map +1 -1
  12. package/dist/versions.d.ts +1 -1
  13. package/dist/versions.d.ts.map +1 -1
  14. package/docs/README.md +6 -5
  15. package/docs/guide.md +503 -59
  16. package/docs/roadmap.md +49 -4
  17. package/docs/troubleshooting.md +249 -4
  18. package/package.json +5 -4
  19. package/templates/api/.vscode/extensions.json +3 -0
  20. package/templates/api/.vscode/settings.json +8 -0
  21. package/templates/api/README.md +78 -6
  22. package/templates/api/_biome.json +32 -0
  23. package/templates/api/openapi-codegen.config.ts +11 -0
  24. package/templates/api/openapi.yaml +116 -0
  25. package/templates/api/package.json +27 -19
  26. package/templates/api/src/app.spec.ts +57 -38
  27. package/templates/api/src/app.ts +5 -30
  28. package/templates/api/src/context.ts +19 -0
  29. package/templates/api/src/generated/alxia.ts +61 -0
  30. package/templates/api/src/generated/operations.ts +133 -0
  31. package/templates/api/src/generated/paths.ts +170 -0
  32. package/templates/api/src/generated/types.ts +170 -0
  33. package/templates/api/src/generated/zod.ts +31 -0
  34. package/templates/api/src/routes/todos.ts +31 -0
  35. package/templates/api/src/server.ts +12 -12
  36. package/templates/api/tsconfig.json +23 -23
  37. package/templates/react-router/.vscode/extensions.json +3 -0
  38. package/templates/react-router/.vscode/settings.json +8 -0
  39. package/templates/react-router/README.md +27 -0
  40. package/templates/react-router/_biome.json +49 -0
  41. package/templates/react-router/app/app.css +3 -2
  42. package/templates/react-router/app/routes/home.tsx +1 -1
  43. package/templates/react-router/app/routes.ts +1 -1
  44. package/templates/react-router/package.json +7 -1
@@ -1,21 +1,29 @@
1
1
  {
2
- "name": "my-api",
3
- "private": true,
4
- "type": "module",
5
- "scripts": {
6
- "dev": "bun --watch src/server.ts",
7
- "build": "bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked",
8
- "start": "bun dist/server.js",
9
- "test": "bun test",
10
- "typecheck": "tsc --noEmit"
11
- },
12
- "dependencies": {
13
- "@alxia/core": "workspace:^",
14
- "zod": "^4.2.0"
15
- },
16
- "devDependencies": {
17
- "@alxia/client": "workspace:^",
18
- "@types/bun": "^1.4.2",
19
- "typescript": "^6.0.3"
20
- }
2
+ "name": "my-api",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "generate": "nxgt-openapi generate",
7
+ "dev": "bun --watch src/server.ts",
8
+ "build": "bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked",
9
+ "start": "bun dist/server.js",
10
+ "test": "bun test",
11
+ "typecheck": "tsc --noEmit",
12
+ "lint": "biome lint",
13
+ "format": "biome format --write",
14
+ "check": "biome check --write",
15
+ "check:ci": "biome ci",
16
+ "verify": "bun run generate --check && bun run check:ci && bun run typecheck && bun run test"
17
+ },
18
+ "dependencies": {
19
+ "@alxia/core": "workspace:^",
20
+ "zod": "^4.5.4"
21
+ },
22
+ "devDependencies": {
23
+ "@alxia/openapi": "workspace:^",
24
+ "@biomejs/biome": "2.5.15",
25
+ "@nxgt/openapi-codegen": "0.6.0",
26
+ "@types/bun": "^1.4.2",
27
+ "typescript": "^6.0.3"
28
+ }
21
29
  }
@@ -1,46 +1,65 @@
1
- import { expect, test } from 'bun:test';
2
- import { client } from '@alxia/client';
3
- import { apiKey, app } from './app';
1
+ import { expect, test } from "bun:test";
2
+ import { matchesSpec } from "@alxia/openapi";
3
+ import { app } from "./app";
4
+ import { apiKey } from "./context";
5
+ import { operations } from "./generated/alxia";
4
6
 
5
- const json = { 'content-type': 'application/json', 'x-api-key': apiKey };
7
+ const json = { "content-type": "application/json", "x-api-key": apiKey };
6
8
 
7
- test('creates a todo from JSON', async () => {
8
- const response = await app.request('/todos', {
9
- method: 'POST',
10
- headers: json,
11
- body: JSON.stringify({ title: 'Write a route' }),
12
- });
13
- expect(response.status).toBe(201);
14
- expect(await response.json()).toEqual({
15
- id: expect.any(Number),
16
- title: 'Write a route',
17
- done: false,
18
- });
9
+ test("routes every operation of openapi.yaml, and nothing else", () => {
10
+ matchesSpec(app, operations);
19
11
  });
20
12
 
21
- test('refuses an empty title with a 400 naming it', async () => {
22
- const response = await app.request('/todos', {
23
- method: 'POST',
24
- headers: json,
25
- body: JSON.stringify({ title: '' }),
26
- });
27
- expect(response.status).toBe(400);
28
- expect((await response.json()).issues[0].path).toEqual(['title']);
13
+ 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" }),
18
+ });
19
+ expect(response.status).toBe(201);
20
+ expect(await response.json()).toEqual({
21
+ id: expect.any(Number),
22
+ title: "Write a route",
23
+ done: false,
24
+ });
29
25
  });
30
26
 
31
- test('the typed client reads each status the route answers', async () => {
32
- // Given the app itself, the client calls its fetch in process.
33
- const api = client(app, { headers: { 'x-api-key': apiKey } });
34
- const created = await api.post('/todos', {
35
- body: { title: 'Call it typed' },
36
- });
37
- if (created.status !== 201) throw new Error(`got ${created.status}`);
38
- expect(created.data.title).toBe('Call it typed'); // data is the Todo schema's type
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: "" }),
32
+ });
33
+ expect(response.status).toBe(400);
34
+ expect((await response.json()).issues[0].path).toEqual(["title"]);
35
+ });
36
+
37
+ 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: "" }),
42
+ });
43
+ expect(response.status).toBe(401); // requireKey stands before the validation
44
+ expect(await response.json()).toEqual({ error: "unauthorized" });
45
+ });
46
+
47
+ 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" }),
52
+ });
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);
58
+ expect((await app.request("/todos/first")).status).toBe(400);
59
+ });
39
60
 
40
- const anonymous = await client(app).post('/todos', {
41
- body: { title: 'No key' },
42
- });
43
- expect(anonymous.status).toBe(401);
44
- if (anonymous.status === 401)
45
- expect(anonymous.data.error).toBe('unauthorized');
61
+ test("lists the todos", async () => {
62
+ const response = await app.request("/todos");
63
+ expect(response.status).toBe(200);
64
+ expect(Array.isArray(await response.json())).toBe(true);
46
65
  });
@@ -1,33 +1,8 @@
1
- import { alxia, defineHook } from '@alxia/core';
2
- import { z } from 'zod';
1
+ import { base } from "./context";
2
+ import { todoRoutes } from "./routes/todos";
3
3
 
4
- const Todo = z.object({ id: z.number(), title: z.string(), done: z.boolean() });
5
- const NewTodo = z.object({ title: z.string().min(1) });
6
-
7
- /** Set API_KEY in the environment: this default is for development. */
8
- export const apiKey = Bun.env['API_KEY'] ?? 'dev-key';
9
-
10
- // A hook of the routes it is given to: it answers 401 without the key, and
11
- // that 401 joins the type of each, so the client reads it.
12
- const requireKey = defineHook(({ request, reply }) =>
13
- request.headers.get('x-api-key') === apiKey
14
- ? undefined
15
- : reply(401, { error: 'unauthorized' as const }),
16
- );
17
-
18
- const todos: z.infer<typeof Todo>[] = [];
19
-
20
- export const app = alxia()
21
- .decorate({ todos })
22
- .post(
23
- '/todos',
24
- [requireKey],
25
- { body: NewTodo, response: { 201: Todo } },
26
- ({ body, todos, reply }) => {
27
- const todo = { id: todos.length + 1, title: body.title, done: false };
28
- todos.push(todo);
29
- return reply.created(todo);
30
- },
31
- );
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);
32
7
 
33
8
  export type App = typeof app;
@@ -0,0 +1,19 @@
1
+ import { alxia } from "@alxia/core";
2
+ import type { Todo } from "./generated/types";
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
+ const todos: Todo[] = [];
8
+
9
+ // The base: what every route reads, decorated or derived here. It is
10
+ // registered below, so a route file reads it with no import of the app.
11
+ export const base = alxia().decorate({ todos });
12
+
13
+ // Register the base, never the app: the app mounts the route files, whose
14
+ // type reads this, and would then be typed by itself.
15
+ declare module "@alxia/core" {
16
+ interface Register {
17
+ context: typeof base;
18
+ }
19
+ }
@@ -0,0 +1,61 @@
1
+ // Generated by @nxgt/openapi-codegen from ../../openapi.yaml. Do not edit.
2
+
3
+ import { z } from 'zod';
4
+ import { zNewTodo, zNotFound, zTodo, zUnauthorized, zValidationError } from './zod';
5
+
6
+ /** A number in a path, a query or a header: digits, where z.coerce.number() would read '' as 0. */
7
+ const numeric = z
8
+ .string()
9
+ .regex(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/)
10
+ .transform(Number);
11
+
12
+ /** Every todo */
13
+ export const listTodos = {
14
+ method: 'GET',
15
+ path: '/todos',
16
+ schema: {
17
+ response: {
18
+ 200: z.array(zTodo),
19
+ },
20
+ detail: { operationId: 'listTodos', summary: 'Every todo' },
21
+ },
22
+ } as const;
23
+
24
+ /** Add a todo */
25
+ export const createTodo = {
26
+ method: 'POST',
27
+ path: '/todos',
28
+ schema: {
29
+ body: zNewTodo,
30
+ response: {
31
+ 201: zTodo,
32
+ 400: zValidationError,
33
+ 401: zUnauthorized,
34
+ },
35
+ detail: { operationId: 'createTodo', summary: 'Add a todo' },
36
+ },
37
+ } as const;
38
+
39
+ /** One todo */
40
+ export const getTodo = {
41
+ method: 'GET',
42
+ path: '/todos/:id',
43
+ schema: {
44
+ params: z.object({
45
+ id: numeric.pipe(z.int().min(1)),
46
+ }),
47
+ response: {
48
+ 200: zTodo,
49
+ 400: zValidationError,
50
+ 404: zNotFound,
51
+ },
52
+ detail: { operationId: 'getTodo', summary: 'One todo' },
53
+ },
54
+ } as const;
55
+
56
+ /** Every operation alxia routes, by operationId: `app.route(operations.listTodos, handler)`. */
57
+ export const operations = {
58
+ listTodos,
59
+ createTodo,
60
+ getTodo,
61
+ } as const;
@@ -0,0 +1,133 @@
1
+ // Generated by @nxgt/openapi-codegen from ../../openapi.yaml. Do not edit.
2
+
3
+ import { z } from 'zod';
4
+ import { zNewTodo, zNotFound, zTodo, zUnauthorized, zValidationError } from './zod';
5
+ import type { ClientOperations, Operations } from './types';
6
+
7
+ /** How a server reads a parameter, and how a client writes it. */
8
+ export interface ParameterSpec {
9
+ readonly name: string;
10
+ readonly in: 'path' | 'query' | 'header';
11
+ readonly required: boolean;
12
+ /** A query list as `?a=1&a=2` (true) or `?a=1,2` (false). */
13
+ readonly explode: boolean;
14
+ /** Validated as a list: every value of a repeated query key, or one split on commas. */
15
+ readonly list: boolean;
16
+ }
17
+
18
+ export interface MediaSpec {
19
+ readonly kind: 'json' | 'form' | 'text' | 'binary' | 'sse' | 'jsonl';
20
+ /** Absent for binary content, which is passed through unvalidated, and for a stream. */
21
+ readonly schema?: z.ZodType;
22
+ /** `sse`: each event's data, by name: a schema for JSON, `null` for text. Absent: any event, as text. */
23
+ readonly events?: { readonly [event: string]: z.ZodType | null };
24
+ /** `jsonl`: each item. Absent: any JSON. */
25
+ readonly item?: z.ZodType;
26
+ }
27
+
28
+ /** An operation of the table; `Client` is its entry of `ClientOperations`. */
29
+ export interface OperationSpec<Client = unknown> {
30
+ readonly method: 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace' | 'query';
31
+ readonly path: string;
32
+ readonly honoPath: string;
33
+ readonly tags: readonly string[];
34
+ readonly parameters: readonly ParameterSpec[];
35
+ /** Validates the path parameters, each read as a string. */
36
+ readonly param: z.ZodType;
37
+ /** Validates the query: a string per parameter, or every value of a list. */
38
+ readonly query: z.ZodType;
39
+ /** Validates the headers, keyed by lowercased name. */
40
+ readonly header: z.ZodType;
41
+ readonly body?: {
42
+ readonly required: boolean;
43
+ readonly content: { readonly [mediaType: string]: MediaSpec };
44
+ };
45
+ readonly responses: {
46
+ readonly [status: number]: { readonly [mediaType: string]: MediaSpec };
47
+ };
48
+ /** Never set: carries `Client`, so `createOpenApiClient(http, operations)` reads the spec's types off the table. */
49
+ readonly '~client'?: Client;
50
+ }
51
+
52
+ /** A location with no parameters declared: whatever arrives there is dropped. */
53
+ const none = z.object({});
54
+
55
+ /** A number in a path, a query or a header: digits, where z.coerce.number() would read '' as 0. */
56
+ const numeric = z
57
+ .string()
58
+ .regex(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/)
59
+ .transform(Number);
60
+
61
+ export const zGetTodoParam = z.object({
62
+ id: numeric.pipe(z.int().min(1)),
63
+ });
64
+
65
+ export const operations: {
66
+ readonly [K in keyof Operations]: OperationSpec<ClientOperations[K]>;
67
+ } = {
68
+ listTodos: {
69
+ method: 'get',
70
+ path: '/todos',
71
+ honoPath: '/todos',
72
+ tags: [],
73
+ parameters: [],
74
+ param: none,
75
+ query: none,
76
+ header: none,
77
+ responses: {
78
+ 200: {
79
+ 'application/json': { kind: 'json', schema: z.array(zTodo) },
80
+ },
81
+ },
82
+ },
83
+ createTodo: {
84
+ method: 'post',
85
+ path: '/todos',
86
+ honoPath: '/todos',
87
+ tags: [],
88
+ parameters: [],
89
+ param: none,
90
+ query: none,
91
+ header: none,
92
+ body: {
93
+ required: true,
94
+ content: {
95
+ 'application/json': { kind: 'json', schema: zNewTodo },
96
+ },
97
+ },
98
+ responses: {
99
+ 201: {
100
+ 'application/json': { kind: 'json', schema: zTodo },
101
+ },
102
+ 400: {
103
+ 'application/json': { kind: 'json', schema: zValidationError },
104
+ },
105
+ 401: {
106
+ 'application/json': { kind: 'json', schema: zUnauthorized },
107
+ },
108
+ },
109
+ },
110
+ getTodo: {
111
+ method: 'get',
112
+ path: '/todos/{id}',
113
+ honoPath: '/todos/:id',
114
+ tags: [],
115
+ parameters: [
116
+ { name: 'id', in: 'path', required: true, explode: false, list: false },
117
+ ],
118
+ param: zGetTodoParam,
119
+ query: none,
120
+ header: none,
121
+ responses: {
122
+ 200: {
123
+ 'application/json': { kind: 'json', schema: zTodo },
124
+ },
125
+ 400: {
126
+ 'application/json': { kind: 'json', schema: zValidationError },
127
+ },
128
+ 404: {
129
+ 'application/json': { kind: 'json', schema: zNotFound },
130
+ },
131
+ },
132
+ },
133
+ };
@@ -0,0 +1,170 @@
1
+ // Generated by @nxgt/openapi-codegen from ../../openapi.yaml. Do not edit.
2
+
3
+ import type { NewTodo, NotFound, Todo, Unauthorized, ValidationError } from './types';
4
+
5
+ export interface paths {
6
+ '/todos': {
7
+ parameters: {
8
+ query?: never;
9
+ header?: never;
10
+ path?: never;
11
+ cookie?: never;
12
+ };
13
+ /** Every todo */
14
+ get: operations['listTodos'];
15
+ put?: never;
16
+ /** Add a todo */
17
+ post: operations['createTodo'];
18
+ delete?: never;
19
+ options?: never;
20
+ head?: never;
21
+ patch?: never;
22
+ trace?: never;
23
+ };
24
+ '/todos/{id}': {
25
+ parameters: {
26
+ query?: never;
27
+ header?: never;
28
+ path: {
29
+ id: number;
30
+ };
31
+ cookie?: never;
32
+ };
33
+ /** One todo */
34
+ get: operations['getTodo'];
35
+ put?: never;
36
+ post?: never;
37
+ delete?: never;
38
+ options?: never;
39
+ head?: never;
40
+ patch?: never;
41
+ trace?: never;
42
+ };
43
+ }
44
+
45
+ export type webhooks = Record<string, never>;
46
+
47
+ export interface components {
48
+ schemas: {
49
+ Todo: Todo;
50
+ NewTodo: NewTodo;
51
+ Unauthorized: Unauthorized;
52
+ NotFound: NotFound;
53
+ ValidationError: ValidationError;
54
+ };
55
+ responses: never;
56
+ parameters: never;
57
+ requestBodies: never;
58
+ headers: never;
59
+ pathItems: never;
60
+ }
61
+
62
+ export type $defs = Record<string, never>;
63
+
64
+ export interface operations {
65
+ /** Every todo */
66
+ listTodos: {
67
+ parameters: {
68
+ query?: never;
69
+ header?: never;
70
+ path?: never;
71
+ cookie?: never;
72
+ };
73
+ requestBody?: never;
74
+ responses: {
75
+ /** The todos, oldest first */
76
+ 200: {
77
+ headers: {
78
+ [name: string]: unknown;
79
+ };
80
+ content: {
81
+ 'application/json': Todo[];
82
+ };
83
+ };
84
+ };
85
+ };
86
+ /** Add a todo */
87
+ createTodo: {
88
+ parameters: {
89
+ query?: never;
90
+ header?: never;
91
+ path?: never;
92
+ cookie?: never;
93
+ };
94
+ requestBody: {
95
+ content: {
96
+ 'application/json': NewTodo;
97
+ };
98
+ };
99
+ responses: {
100
+ /** The todo, created */
101
+ 201: {
102
+ headers: {
103
+ [name: string]: unknown;
104
+ };
105
+ content: {
106
+ 'application/json': Todo;
107
+ };
108
+ };
109
+ /** alxia's own 400, for a request the schemas refuse */
110
+ 400: {
111
+ headers: {
112
+ [name: string]: unknown;
113
+ };
114
+ content: {
115
+ 'application/json': ValidationError;
116
+ };
117
+ };
118
+ /** No x-api-key header, or not the key */
119
+ 401: {
120
+ headers: {
121
+ [name: string]: unknown;
122
+ };
123
+ content: {
124
+ 'application/json': Unauthorized;
125
+ };
126
+ };
127
+ };
128
+ };
129
+ /** One todo */
130
+ getTodo: {
131
+ parameters: {
132
+ query?: never;
133
+ header?: never;
134
+ path: {
135
+ id: number;
136
+ };
137
+ cookie?: never;
138
+ };
139
+ requestBody?: never;
140
+ responses: {
141
+ /** The todo */
142
+ 200: {
143
+ headers: {
144
+ [name: string]: unknown;
145
+ };
146
+ content: {
147
+ 'application/json': Todo;
148
+ };
149
+ };
150
+ /** alxia's own 400, for a request the schemas refuse */
151
+ 400: {
152
+ headers: {
153
+ [name: string]: unknown;
154
+ };
155
+ content: {
156
+ 'application/json': ValidationError;
157
+ };
158
+ };
159
+ /** No todo has this id */
160
+ 404: {
161
+ headers: {
162
+ [name: string]: unknown;
163
+ };
164
+ content: {
165
+ 'application/json': NotFound;
166
+ };
167
+ };
168
+ };
169
+ };
170
+ }