@quickback-dev/cli 0.58.1 → 0.58.3
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 +3 -1
- package/dist/commands/compile.d.ts +5 -0
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +34 -0
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/schema.d.ts +16 -0
- package/dist/commands/schema.d.ts.map +1 -0
- package/dist/commands/schema.js +122 -0
- package/dist/commands/schema.js.map +1 -0
- package/dist/commands/schema.test.d.ts +2 -0
- package/dist/commands/schema.test.d.ts.map +1 -0
- package/dist/commands/schema.test.js +57 -0
- package/dist/commands/schema.test.js.map +1 -0
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +7 -2
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +14 -4
- package/dist/index.js.map +1 -1
- package/dist/lib/action-harvest.d.ts +9 -6
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +28 -15
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +21 -0
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/api-client.d.ts +53 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +2 -0
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +18 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/migrations/command-runner.d.ts +10 -0
- package/dist/lib/migrations/command-runner.d.ts.map +1 -0
- package/dist/lib/migrations/command-runner.js +66 -0
- package/dist/lib/migrations/command-runner.js.map +1 -0
- package/dist/lib/migrations/drizzle.d.ts +12 -0
- package/dist/lib/migrations/drizzle.d.ts.map +1 -0
- package/dist/lib/migrations/drizzle.js +60 -0
- package/dist/lib/migrations/drizzle.js.map +1 -0
- package/dist/lib/migrations/drizzle.test.d.ts +2 -0
- package/dist/lib/migrations/drizzle.test.d.ts.map +1 -0
- package/dist/lib/migrations/drizzle.test.js +61 -0
- package/dist/lib/migrations/drizzle.test.js.map +1 -0
- package/dist/lib/migrations/errors.d.ts +6 -0
- package/dist/lib/migrations/errors.d.ts.map +1 -0
- package/dist/lib/migrations/errors.js +9 -0
- package/dist/lib/migrations/errors.js.map +1 -0
- package/dist/lib/migrations/executor.d.ts +52 -0
- package/dist/lib/migrations/executor.d.ts.map +1 -0
- package/dist/lib/migrations/executor.js +190 -0
- package/dist/lib/migrations/executor.js.map +1 -0
- package/dist/lib/migrations/executor.test.d.ts +2 -0
- package/dist/lib/migrations/executor.test.d.ts.map +1 -0
- package/dist/lib/migrations/executor.test.js +241 -0
- package/dist/lib/migrations/executor.test.js.map +1 -0
- package/dist/lib/migrations/index.d.ts +11 -0
- package/dist/lib/migrations/index.d.ts.map +1 -0
- package/dist/lib/migrations/index.js +11 -0
- package/dist/lib/migrations/index.js.map +1 -0
- package/dist/lib/migrations/inventory.d.ts +19 -0
- package/dist/lib/migrations/inventory.d.ts.map +1 -0
- package/dist/lib/migrations/inventory.js +135 -0
- package/dist/lib/migrations/inventory.js.map +1 -0
- package/dist/lib/migrations/inventory.test.d.ts +2 -0
- package/dist/lib/migrations/inventory.test.d.ts.map +1 -0
- package/dist/lib/migrations/inventory.test.js +81 -0
- package/dist/lib/migrations/inventory.test.js.map +1 -0
- package/dist/lib/migrations/lock.d.ts +6 -0
- package/dist/lib/migrations/lock.d.ts.map +1 -0
- package/dist/lib/migrations/lock.js +101 -0
- package/dist/lib/migrations/lock.js.map +1 -0
- package/dist/lib/migrations/lock.test.d.ts +2 -0
- package/dist/lib/migrations/lock.test.d.ts.map +1 -0
- package/dist/lib/migrations/lock.test.js +35 -0
- package/dist/lib/migrations/lock.test.js.map +1 -0
- package/dist/lib/migrations/paths.d.ts +12 -0
- package/dist/lib/migrations/paths.d.ts.map +1 -0
- package/dist/lib/migrations/paths.js +82 -0
- package/dist/lib/migrations/paths.js.map +1 -0
- package/dist/lib/migrations/paths.test.d.ts +2 -0
- package/dist/lib/migrations/paths.test.d.ts.map +1 -0
- package/dist/lib/migrations/paths.test.js +32 -0
- package/dist/lib/migrations/paths.test.js.map +1 -0
- package/dist/lib/migrations/plan.d.ts +7 -0
- package/dist/lib/migrations/plan.d.ts.map +1 -0
- package/dist/lib/migrations/plan.js +189 -0
- package/dist/lib/migrations/plan.js.map +1 -0
- package/dist/lib/migrations/plan.test.d.ts +2 -0
- package/dist/lib/migrations/plan.test.d.ts.map +1 -0
- package/dist/lib/migrations/plan.test.js +104 -0
- package/dist/lib/migrations/plan.test.js.map +1 -0
- package/dist/lib/migrations/staging.d.ts +18 -0
- package/dist/lib/migrations/staging.d.ts.map +1 -0
- package/dist/lib/migrations/staging.js +150 -0
- package/dist/lib/migrations/staging.js.map +1 -0
- package/dist/lib/migrations/staging.test.d.ts +2 -0
- package/dist/lib/migrations/staging.test.d.ts.map +1 -0
- package/dist/lib/migrations/staging.test.js +73 -0
- package/dist/lib/migrations/staging.test.js.map +1 -0
- package/dist/lib/migrations/types.d.ts +49 -0
- package/dist/lib/migrations/types.d.ts.map +1 -0
- package/dist/lib/migrations/types.js +18 -0
- package/dist/lib/migrations/types.js.map +1 -0
- package/dist/lib/schema-engine-loader.d.ts +8 -0
- package/dist/lib/schema-engine-loader.d.ts.map +1 -0
- package/dist/lib/schema-engine-loader.js +26 -0
- package/dist/lib/schema-engine-loader.js.map +1 -0
- package/dist/lib/schema-sync/index.d.ts +41 -0
- package/dist/lib/schema-sync/index.d.ts.map +1 -0
- package/dist/lib/schema-sync/index.js +246 -0
- package/dist/lib/schema-sync/index.js.map +1 -0
- package/dist/lib/schema-sync/index.test.d.ts +2 -0
- package/dist/lib/schema-sync/index.test.d.ts.map +1 -0
- package/dist/lib/schema-sync/index.test.js +128 -0
- package/dist/lib/schema-sync/index.test.js.map +1 -0
- package/dist/schema-engine/index.d.ts +3 -0
- package/dist/schema-engine/index.d.ts.map +1 -0
- package/dist/schema-engine/index.js +854 -0
- package/dist/schema-engine/index.js.map +7 -0
- package/dist/schema-engine/managed-columns.d.ts +82 -0
- package/dist/schema-engine/managed-columns.d.ts.map +1 -0
- package/dist/schema-engine/source-sync.d.ts +64 -0
- package/dist/schema-engine/source-sync.d.ts.map +1 -0
- package/dist/skill/docs/compiler/definitions/actions.md +14 -6
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +7 -4
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/typescript.md +141 -0
- package/package.json +4 -2
- package/src/skill/docs/compiler/definitions/actions.md +14 -6
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +7 -4
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/typescript.md +141 -0
|
@@ -31,14 +31,17 @@ Each endpoint includes request/response schemas derived from your Drizzle column
|
|
|
31
31
|
|
|
32
32
|
The generated component schemas carry enough type information that strict validators (zod, openapi-typescript, openapi-fetch) produce non-optional, narrowed types out of the box:
|
|
33
33
|
|
|
34
|
-
- **`required[]` on response components** — every
|
|
34
|
+
- **`required[]` on response components** — every selected column is listed; nullable columns are present as `T | null`, not optional.
|
|
35
|
+
- **Logical q types survive database lowering** — `q.bool()` remains `boolean`, `q.timestamp()` remains an ISO date-time string, and `q.url()` retains its URI format even when D1 stores the value as text or integer.
|
|
35
36
|
- **Closed enums on `text(_, { enum: [...] })` columns** — emitted as `{ type: "string", enum: [...] }`, narrowing to a literal union in TS.
|
|
36
37
|
- **`Error.code` is a closed enum** — every `code` value the API can emit (`AUTH_MISSING`, `DB_UNIQUE_VIOLATION`, `BATCH_SIZE_EXCEEDED`, …) is enumerated so consumers can `switch` exhaustively.
|
|
37
38
|
- **ID `format`** — only emitted as `format: "uuid"` when your project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators get plain `{ type: "string" }`, keeping strict OpenAPI validators happy.
|
|
38
39
|
|
|
39
|
-
### Action input schemas
|
|
40
|
+
### Action input and output schemas
|
|
40
41
|
|
|
41
|
-
Actions defined with [`defineAction({ input
|
|
42
|
+
Actions defined with [`defineAction({ input, output })`](/compiler/definitions/actions) get both Zod schemas lifted into the operation. `GET` inputs become typed query parameters; other methods use a JSON request body. A declared `output` becomes the success response schema and the generated helper requires `execute` to return a compatible value.
|
|
43
|
+
|
|
44
|
+
The CLI evaluates only the schema declarations in an isolated local bundle and converts them with Zod 4's `z.toJSONSchema()`. It never invokes `execute`, and the hosted compiler only receives plain JSON Schema data. Discriminated unions, refinements, recursive schemas, and shared schema references therefore flow to OpenAPI and generated TypeScript without relying on the compiler's static fallback parser.
|
|
42
45
|
|
|
43
46
|
## Configuration
|
|
44
47
|
|
|
@@ -154,7 +157,7 @@ export default defineConfig({
|
|
|
154
157
|
|
|
155
158
|
The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback compile` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
|
|
156
159
|
|
|
157
|
-
|
|
160
|
+
For application code, prefer the compact first-party [`quickback.gen.ts` type tree](/compiler/targets/hono-api/using-the-api/typescript). Keep `api-types.gen.ts` for `openapi-fetch` and third-party OpenAPI tooling.
|
|
158
161
|
|
|
159
162
|
### External viewer
|
|
160
163
|
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# TypeScript Type Tree
|
|
2
|
+
|
|
3
|
+
Every compile emits `quickback.gen.ts`: a compact, type-only tree designed for application code. It is generated directly from the same compiler model that drives routes and OpenAPI, so there is no runtime package and no code to initialize.
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import type { Api, Qb } from "../quickback.gen";
|
|
7
|
+
|
|
8
|
+
type Application = Api.applications.Row;
|
|
9
|
+
type NewApplication = Api.applications.Insert;
|
|
10
|
+
type ApplicationPatch = Api.applications.Update;
|
|
11
|
+
type ApplicationId = Api.applications.Id;
|
|
12
|
+
|
|
13
|
+
type AdvanceInput = Api.applications.actions.advance.Input;
|
|
14
|
+
type AdvanceOutput = Api.applications.actions.advance.Output;
|
|
15
|
+
type PipelineItem = Api.applications.views.pipeline.Item;
|
|
16
|
+
type PipelineResponse = Api.applications.views.pipeline.Response;
|
|
17
|
+
|
|
18
|
+
type Page = Qb.Page<Application>;
|
|
19
|
+
type ApiProblem = Qb.Problem;
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Feature areas preserve their authored hierarchy:
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
type Booking = Api.events.travel.bookings.Row;
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Table types
|
|
29
|
+
|
|
30
|
+
Each resource table exposes:
|
|
31
|
+
|
|
32
|
+
| Member | Meaning |
|
|
33
|
+
|---|---|
|
|
34
|
+
| `Id` | Nominal table-specific primary-key type |
|
|
35
|
+
| `Row` | Complete selected wire shape |
|
|
36
|
+
| `Insert` | Createable fields, with defaults and nullable fields optional |
|
|
37
|
+
| `Update` | Updatable fields, all optional |
|
|
38
|
+
| `ListResponse` | `Qb.Page<Row>` |
|
|
39
|
+
| `columns.<name>` | Type of one row column |
|
|
40
|
+
| `views.<name>.Item` | A view's projected row |
|
|
41
|
+
| `views.<name>.Response` | Page plus typed aggregations where declared |
|
|
42
|
+
| `actions.<name>.Input` | The action's Zod input contract |
|
|
43
|
+
| `actions.<name>.Output` | The declared Zod output contract, or `unknown` |
|
|
44
|
+
|
|
45
|
+
Primary and foreign keys are branded by default. That makes accidentally passing a candidate ID where a job ID is required a TypeScript error, while both values remain ordinary strings or numbers at runtime.
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
function loadJob(id: Api.jobs.Id) {}
|
|
49
|
+
|
|
50
|
+
declare const candidateId: Api.candidates.Id;
|
|
51
|
+
loadJob(candidateId); // TypeScript error
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
At an untyped boundary, validate the value and cast it once:
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
const jobId = routeParams.id as Api.jobs.Id;
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Reading collections
|
|
61
|
+
|
|
62
|
+
List and view responses share one envelope: rows under `data`, pagination
|
|
63
|
+
metadata under `pagination`, and `view` naming the projection behind the
|
|
64
|
+
response (`null` for the default collection read).
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
declare const res: Api.applications.ListResponse; // Qb.Page<Api.applications.Row>
|
|
68
|
+
|
|
69
|
+
res.data; // Api.applications.Row[]
|
|
70
|
+
res.view; // string | null
|
|
71
|
+
res.pagination.count; // rows in this page
|
|
72
|
+
res.pagination.hasMore;
|
|
73
|
+
res.pagination.nextCursor; // pass back as ?starting_after=
|
|
74
|
+
res.pagination.total; // number | undefined — only when ?total=true
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`total` and `totalPages` are counted only when the request passes
|
|
78
|
+
`?total=true`, so both are optional; every other member is always present. A
|
|
79
|
+
view that declares aggregations intersects this shape with a typed
|
|
80
|
+
`aggregations` object, and an aggregate-only view returns `{ view,
|
|
81
|
+
aggregations }` with no rows or pagination.
|
|
82
|
+
|
|
83
|
+
## Declaring action outputs
|
|
84
|
+
|
|
85
|
+
Add an optional `output` Zod schema to make an action end-to-end typed:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
export default defineAction({
|
|
89
|
+
description: "Advance an application",
|
|
90
|
+
input: z.object({
|
|
91
|
+
nextStatus: z.enum(["screening", "interview", "offer"]),
|
|
92
|
+
}),
|
|
93
|
+
output: z.object({
|
|
94
|
+
id: z.string(),
|
|
95
|
+
status: z.enum(["screening", "interview", "offer"]),
|
|
96
|
+
}),
|
|
97
|
+
access: { roles: ["recruiter+"] },
|
|
98
|
+
async execute({ record, input }) {
|
|
99
|
+
return { id: record.id, status: input.nextStatus };
|
|
100
|
+
},
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The generated feature helper checks `execute` against the declared output. The CLI harvests both schemas locally without invoking `execute`; the resulting contract feeds `quickback.gen.ts`, OpenAPI, and `api-types.gen.ts`.
|
|
105
|
+
|
|
106
|
+
## Configuration
|
|
107
|
+
|
|
108
|
+
The artifact is on by default:
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
export default defineConfig({
|
|
112
|
+
// Default: quickback.gen.ts
|
|
113
|
+
types: true,
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Use a custom path, fan out identical copies to colocated apps, disable branding, or turn the artifact off:
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
export default defineConfig({
|
|
121
|
+
types: {
|
|
122
|
+
output: [
|
|
123
|
+
"quickback.gen.ts",
|
|
124
|
+
"apps/web/src/lib/quickback.gen.ts",
|
|
125
|
+
],
|
|
126
|
+
brandIds: true,
|
|
127
|
+
},
|
|
128
|
+
});
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
| `types` value | Behavior |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `true` or omitted | Write `quickback.gen.ts` |
|
|
134
|
+
| `false` | Do not emit the first-party type tree |
|
|
135
|
+
| `"src/lib/quickback.gen.ts"` | Write to one custom path |
|
|
136
|
+
| `["quickback.gen.ts", "apps/web/src/quickback.gen.ts"]` | Fan out identical copies |
|
|
137
|
+
| `{ output, brandIds: false }` | Configure paths and use structural IDs |
|
|
138
|
+
|
|
139
|
+
`api-types.gen.ts` remains available through `openapi.types` for `openapi-fetch` and third-party OpenAPI tools. The two artifacts are independent: disabling OpenAPI types does not disable the first-party tree.
|
|
140
|
+
|
|
141
|
+
The compiler also emits `reports/types.parity.gen.ts` when both artifacts exist. Quickback's output-matrix CI compiles that proof separately to require mutual assignability between direct table/action types and the OpenAPI wire types; it is outside the generated application's `src/**/*` build.
|