@fabrika/app 0.9.0-dev.14 → 0.9.0-dev.15

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 (64) hide show
  1. package/package.json +14 -9
  2. package/skill/SKILL.md +2 -2
  3. package/skill/references/app-setup.md +10 -9
  4. package/skill/references/endpoint.md +8 -1
  5. package/src/build-contract-child.ts +16 -0
  6. package/src/build.ts +48 -2
  7. package/src/client/contract.ts +6 -4
  8. package/src/cloudflare/application.ts +3 -0
  9. package/src/contract/artifact-schema.ts +355 -301
  10. package/src/contract/attachment.ts +4 -3
  11. package/src/contract/compile.ts +3 -2
  12. package/src/contract/context.ts +2 -3
  13. package/src/contract/define.ts +17 -5
  14. package/src/contract/group.ts +8 -7
  15. package/src/contract/index.ts +1 -1
  16. package/src/contract/kit.ts +2 -2
  17. package/src/contract/problems.ts +4 -0
  18. package/src/contract/schema-shape.ts +14 -2
  19. package/src/contract/token.ts +4 -3
  20. package/src/from-row.ts +12 -6
  21. package/src/implement/approved.ts +57 -0
  22. package/src/implement/attachment.ts +2 -1
  23. package/src/implement/boot.ts +90 -12
  24. package/src/implement/dispatch.ts +14 -10
  25. package/src/implement/egress.ts +7 -6
  26. package/src/implement/faults.ts +1 -0
  27. package/src/implement/project.ts +3 -1
  28. package/src/implement/tokens.ts +3 -2
  29. package/src/implement/types.ts +18 -6
  30. package/src/react/hooks.ts +12 -11
  31. package/src/react/provider.tsx +2 -1
  32. package/src/react/types.ts +2 -2
  33. package/src/schema/builder.ts +146 -0
  34. package/src/schema/data-schema.ts +365 -0
  35. package/src/schema/index.ts +18 -0
  36. package/src/schema/replay.ts +623 -0
  37. package/src/testing/kit.ts +3 -3
  38. package/types/src/build-contract-child.d.ts +1 -0
  39. package/types/src/build.d.ts +16 -1
  40. package/types/src/client/contract.d.ts +3 -4
  41. package/types/src/cloudflare/application.d.ts +2 -0
  42. package/types/src/contract/artifact-schema.d.ts +8 -0
  43. package/types/src/contract/attachment.d.ts +3 -2
  44. package/types/src/contract/context.d.ts +2 -3
  45. package/types/src/contract/define.d.ts +14 -5
  46. package/types/src/contract/group.d.ts +5 -6
  47. package/types/src/contract/index.d.ts +1 -1
  48. package/types/src/contract/kit.d.ts +2 -3
  49. package/types/src/contract/problems.d.ts +1 -0
  50. package/types/src/contract/schema-shape.d.ts +3 -2
  51. package/types/src/contract/token.d.ts +3 -3
  52. package/types/src/from-row.d.ts +9 -5
  53. package/types/src/implement/approved.d.ts +11 -0
  54. package/types/src/implement/boot.d.ts +6 -0
  55. package/types/src/implement/faults.d.ts +1 -0
  56. package/types/src/implement/project.d.ts +2 -1
  57. package/types/src/implement/types.d.ts +4 -5
  58. package/types/src/react/hooks.d.ts +4 -5
  59. package/types/src/react/types.d.ts +2 -2
  60. package/types/src/schema/builder.d.ts +45 -0
  61. package/types/src/schema/data-schema.d.ts +124 -0
  62. package/types/src/schema/index.d.ts +3 -0
  63. package/types/src/schema/replay.d.ts +27 -0
  64. package/types/src/testing/kit.d.ts +2 -3
@@ -0,0 +1,365 @@
1
+ // A schema held as data: the `z` call that made it, its receiver and its arguments, and no zod object. Zod is built
2
+ // from it only when something validates, by replaying the same calls (`replay.ts`), and a bounded cache keeps the most
3
+ // recently used builds, so an application's schemas cost their recipe, not the whole zod graph, while it runs.
4
+
5
+ import { z } from 'zod/v4'
6
+ import { type ReplayArg, replayStep, SCHEMA_SUBSET, SchemaRefusal, Unreadable } from './replay'
7
+
8
+ /** A schema a contract may hold: one held as data, or a zod schema (a framework schema such as `signedToken()`). */
9
+ export type AnySchema = DataSchema<z.ZodType> | z.ZodType
10
+
11
+ /** The zod type a schema denotes: its own type for a zod schema. */
12
+ export type ZodOf<S> = S extends DataSchema<infer T extends z.core.$ZodType> ? T : S extends z.core.$ZodType ? S : never
13
+
14
+ /** The fields an object is declared with. */
15
+ export type DataShapeInput = { readonly [key: string]: AnySchema }
16
+
17
+ /** The zod shape of `S`, as `z.strictObject` would hold it. */
18
+ export type ZodShape<S extends DataShapeInput> = { [K in keyof S]: ZodOf<S[K]> }
19
+
20
+ /** The zod types of a list of schemas, as `z.union` or `z.tuple` would hold them. */
21
+ export type ZodList<O extends readonly AnySchema[]> = { [I in keyof O]: ZodOf<O[I]> }
22
+
23
+ /** An error message, or the options object that carries one. */
24
+ export type Message = string | { readonly message?: string; readonly error?: string }
25
+
26
+ /** What `min`, `max` and `length` bound: a string's length, an array's items, a number. */
27
+ type Sized = (z.ZodString | z.ZodStringFormat | z.ZodArray) & z.core.$ZodType
28
+ type Bounded = (Sized | z.ZodNumber) & z.core.$ZodType
29
+ type Text = (z.ZodString | z.ZodStringFormat) & z.core.$ZodType
30
+
31
+ /** The name `~zod` marks a node that wraps a zod schema given where a schema stands. */
32
+ const WRAPPED = '~zod'
33
+
34
+ /**
35
+ * A call's argument as the node keeps it: a plain object or array copied and frozen all the way down, so a shape changed
36
+ * after the call cannot change a later rebuild of the same node. A schema, a regex or a function is kept as it is.
37
+ */
38
+ function held(value: unknown): unknown {
39
+ if (Array.isArray(value)) {
40
+ return Object.freeze(value.map(held))
41
+ }
42
+ if (typeof value === 'object' && value !== null && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
43
+ return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, held(entry)])))
44
+ }
45
+ return value
46
+ }
47
+
48
+ export class DataSchema<T extends z.core.$ZodType = z.core.$ZodType> {
49
+ /** The zod type this schema denotes; declared only, never set. */
50
+ declare readonly '~type'?: T
51
+ /** The factory (`z.<name>`, `z.iso.<name>` when `iso`) or the method that made this schema. */
52
+ readonly name: string
53
+ readonly iso: boolean
54
+ /** The schema a method was called on; `null` for a factory. */
55
+ readonly receiver: DataSchema | null
56
+ readonly args: readonly unknown[]
57
+
58
+ constructor(name: string, iso: boolean, receiver: DataSchema | null, args: readonly unknown[]) {
59
+ this.name = name
60
+ this.iso = iso
61
+ this.receiver = receiver
62
+ // A trailing omitted argument is absent, as in the call written without it.
63
+ let length = args.length
64
+ while (length > 0 && args[length - 1] === undefined) {
65
+ length--
66
+ }
67
+ this.args = Object.freeze(args.slice(0, length).map(held))
68
+ Object.freeze(this)
69
+ }
70
+
71
+ /** A zod schema given where a schema stands, held as one. */
72
+ static wrap<S extends z.core.$ZodType>(schema: S): DataSchema<S> {
73
+ return new DataSchema<S>(WRAPPED, false, null, [schema])
74
+ }
75
+
76
+ /** Whether this node only wraps a zod schema. */
77
+ get wrapped(): z.ZodType | null {
78
+ const [schema] = this.args
79
+ return this.name === WRAPPED && schema instanceof z.ZodType ? schema : null
80
+ }
81
+
82
+ protected derive<U extends z.core.$ZodType>(name: string, args: readonly unknown[]): DataSchema<U> {
83
+ return new DataSchema<U>(name, false, this, args)
84
+ }
85
+
86
+ min<S extends Bounded>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
87
+ return this.derive<S>('min', [value, params])
88
+ }
89
+
90
+ max<S extends Bounded>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
91
+ return this.derive<S>('max', [value, params])
92
+ }
93
+
94
+ length<S extends Sized>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
95
+ return this.derive<S>('length', [value, params])
96
+ }
97
+
98
+ nonempty<S extends Sized>(this: DataSchema<S>, params?: Message): DataSchema<S> {
99
+ return this.derive<S>('nonempty', [params])
100
+ }
101
+
102
+ email(this: DataSchema<z.ZodString>, params?: Message): DataSchema<z.ZodString> {
103
+ return this.derive<z.ZodString>('email', [params])
104
+ }
105
+
106
+ url(this: DataSchema<z.ZodString>, params?: Message): DataSchema<z.ZodString> {
107
+ return this.derive<z.ZodString>('url', [params])
108
+ }
109
+
110
+ uuid(this: DataSchema<z.ZodString>, params?: UuidOptions): DataSchema<z.ZodString> {
111
+ return this.derive<z.ZodString>('uuid', [params])
112
+ }
113
+
114
+ startsWith<S extends Text>(this: DataSchema<S>, prefix: string, params?: Message): DataSchema<S> {
115
+ return this.derive<S>('startsWith', [prefix, params])
116
+ }
117
+
118
+ endsWith<S extends Text>(this: DataSchema<S>, suffix: string, params?: Message): DataSchema<S> {
119
+ return this.derive<S>('endsWith', [suffix, params])
120
+ }
121
+
122
+ includes<S extends Text>(this: DataSchema<S>, part: string, params?: IncludesOptions): DataSchema<S> {
123
+ return this.derive<S>('includes', [part, params])
124
+ }
125
+
126
+ regex<S extends Text>(this: DataSchema<S>, pattern: RegExp, params?: Message): DataSchema<S> {
127
+ return this.derive<S>('regex', [pattern, params])
128
+ }
129
+
130
+ int<S extends z.ZodNumber>(this: DataSchema<S>, params?: Message): DataSchema<S> {
131
+ return this.derive<S>('int', [params])
132
+ }
133
+
134
+ positive<S extends z.ZodNumber>(this: DataSchema<S>, params?: Message): DataSchema<S> {
135
+ return this.derive<S>('positive', [params])
136
+ }
137
+
138
+ negative<S extends z.ZodNumber>(this: DataSchema<S>, params?: Message): DataSchema<S> {
139
+ return this.derive<S>('negative', [params])
140
+ }
141
+
142
+ nonnegative<S extends z.ZodNumber>(this: DataSchema<S>, params?: Message): DataSchema<S> {
143
+ return this.derive<S>('nonnegative', [params])
144
+ }
145
+
146
+ nonpositive<S extends z.ZodNumber>(this: DataSchema<S>, params?: Message): DataSchema<S> {
147
+ return this.derive<S>('nonpositive', [params])
148
+ }
149
+
150
+ gt<S extends z.ZodNumber>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
151
+ return this.derive<S>('gt', [value, params])
152
+ }
153
+
154
+ gte<S extends z.ZodNumber>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
155
+ return this.derive<S>('gte', [value, params])
156
+ }
157
+
158
+ lt<S extends z.ZodNumber>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
159
+ return this.derive<S>('lt', [value, params])
160
+ }
161
+
162
+ lte<S extends z.ZodNumber>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
163
+ return this.derive<S>('lte', [value, params])
164
+ }
165
+
166
+ multipleOf<S extends z.ZodNumber>(this: DataSchema<S>, value: number, params?: Message): DataSchema<S> {
167
+ return this.derive<S>('multipleOf', [value, params])
168
+ }
169
+
170
+ optional(): DataSchema<z.ZodOptional<T>> {
171
+ return this.derive<z.ZodOptional<T>>('optional', [])
172
+ }
173
+
174
+ nullable(): DataSchema<z.ZodNullable<T>> {
175
+ return this.derive<z.ZodNullable<T>>('nullable', [])
176
+ }
177
+
178
+ nullish(): DataSchema<z.ZodOptional<z.ZodNullable<T>>> {
179
+ return this.derive<z.ZodOptional<z.ZodNullable<T>>>('nullish', [])
180
+ }
181
+
182
+ array(): DataSchema<z.ZodArray<T>> {
183
+ return this.derive<z.ZodArray<T>>('array', [])
184
+ }
185
+
186
+ default(value: z.core.util.NoUndefined<z.output<T>>): DataSchema<z.ZodDefault<T>> {
187
+ return this.derive<z.ZodDefault<T>>('default', [value])
188
+ }
189
+
190
+ describe(description: string): DataSchema<T> {
191
+ return this.derive<T>('describe', [description])
192
+ }
193
+
194
+ or<U extends AnySchema>(option: U): DataSchema<z.ZodUnion<[T, ZodOf<U>]>> {
195
+ return this.derive<z.ZodUnion<[T, ZodOf<U>]>>('or', [option])
196
+ }
197
+
198
+ /** What zod's `parse` returns for `value`, from the schema this one denotes. */
199
+ parse(value: unknown): z.output<T> {
200
+ return z.parse(this.#zod(), value)
201
+ }
202
+
203
+ safeParse(value: unknown): z.ZodSafeParseResult<z.output<T>> {
204
+ return z.safeParse(this.#zod(), value)
205
+ }
206
+
207
+ get '~standard'(): T['~standard'] {
208
+ return this.#zod()['~standard']
209
+ }
210
+
211
+ #zod(): T {
212
+ return zodOf<DataSchema<T>>(this)
213
+ }
214
+ }
215
+
216
+ /** An object schema: what `z.strictObject` and the methods that derive objects make. */
217
+ export class DataObject<Shape extends z.core.$ZodShape, Config extends z.core.$ZodObjectConfig> extends DataSchema<z.ZodObject<Shape, Config>> {
218
+ /** The zod fields, as zod's `.shape` holds them. */
219
+ get shape(): Shape {
220
+ return zodOf<DataSchema<z.ZodObject<Shape, Config>>>(this).shape
221
+ }
222
+
223
+ extend<U extends DataShapeInput>(shape: U): DataObject<z.core.util.Extend<Shape, ZodShape<U>>, Config> {
224
+ return new DataObject<z.core.util.Extend<Shape, ZodShape<U>>, Config>('extend', false, this, [shape])
225
+ }
226
+
227
+ pick<M extends z.core.util.Mask<keyof Shape>>(mask: M): DataObject<z.core.util.Flatten<Pick<Shape, Extract<keyof Shape, keyof M>>>, Config> {
228
+ return new DataObject<z.core.util.Flatten<Pick<Shape, Extract<keyof Shape, keyof M>>>, Config>('pick', false, this, [mask])
229
+ }
230
+
231
+ omit<M extends z.core.util.Mask<keyof Shape>>(mask: M): DataObject<z.core.util.Flatten<Omit<Shape, Extract<keyof Shape, keyof M>>>, Config> {
232
+ return new DataObject<z.core.util.Flatten<Omit<Shape, Extract<keyof Shape, keyof M>>>, Config>('omit', false, this, [mask])
233
+ }
234
+
235
+ partial<M extends z.core.util.Mask<keyof Shape> = { [K in keyof Shape]: true }>(mask?: M): DataObject<Partialized<Shape, M>, Config> {
236
+ return new DataObject<Partialized<Shape, M>, Config>('partial', false, this, [mask])
237
+ }
238
+
239
+ override describe(description: string): DataObject<Shape, Config> {
240
+ return new DataObject<Shape, Config>('describe', false, this, [description])
241
+ }
242
+ }
243
+
244
+ /** `Shape` with the fields `M` names optional, as zod's `.partial(mask)` makes it. */
245
+ type Partialized<Shape extends z.core.$ZodShape, M> = { [K in keyof Shape]: K extends keyof M ? z.ZodOptional<Shape[K]> : Shape[K] }
246
+
247
+ /** An enum schema: what `z.enum` and the methods that narrow an enum make. */
248
+ export class DataEnum<E extends z.core.util.EnumLike> extends DataSchema<z.ZodEnum<E>> {
249
+ get options(): z.ZodEnum<E>['options'] {
250
+ return zodOf<DataSchema<z.ZodEnum<E>>>(this).options
251
+ }
252
+
253
+ get enum(): E {
254
+ return zodOf<DataSchema<z.ZodEnum<E>>>(this).enum
255
+ }
256
+
257
+ exclude<const U extends readonly (keyof E)[]>(keys: U, params?: Message): DataEnum<z.core.util.Flatten<Omit<E, U[number]>>> {
258
+ return new DataEnum<z.core.util.Flatten<Omit<E, U[number]>>>('exclude', false, this, [keys, params])
259
+ }
260
+
261
+ extract<const U extends readonly (keyof E)[]>(keys: U, params?: Message): DataEnum<z.core.util.Flatten<Pick<E, U[number]>>> {
262
+ return new DataEnum<z.core.util.Flatten<Pick<E, U[number]>>>('extract', false, this, [keys, params])
263
+ }
264
+
265
+ override describe(description: string): DataEnum<E> {
266
+ return new DataEnum<E>('describe', false, this, [description])
267
+ }
268
+ }
269
+
270
+ export type UuidOptions = string | {
271
+ readonly message?: string
272
+ readonly error?: string
273
+ readonly version?: 'v1' | 'v2' | 'v3' | 'v4' | 'v5' | 'v6' | 'v7' | 'v8'
274
+ }
275
+
276
+ export type IncludesOptions = { readonly message?: string; readonly error?: string; readonly position?: number }
277
+
278
+ export function isDataSchema(value: unknown): value is DataSchema {
279
+ return value instanceof DataSchema
280
+ }
281
+
282
+ // ── Building zod ────────────────────────────────────────────────────────────────────────────────
283
+
284
+ /**
285
+ * How many built schemas stay cached: each holds the zod of one schema something validated with, and an endpoint uses
286
+ * two. Sized so a runtime that serves every endpoint of a large contract stays far below a Worker's 128 MB.
287
+ */
288
+ export const BUILT_SCHEMAS = 64
289
+
290
+ const built = new Map<DataSchema, z.ZodType>()
291
+
292
+ /**
293
+ * The zod schema `schema` denotes: a zod schema itself, or one held as data built. A cached build is reused and becomes
294
+ * the most recent; a schema built anew is cached, and the least recently used beyond `BUILT_SCHEMAS` is dropped. A step
295
+ * outside the subset throws a `SchemaRefusal`.
296
+ */
297
+ export function zodSchemaOf(schema: z.core.$ZodType | DataSchema): z.core.$ZodType {
298
+ return schema instanceof DataSchema ? buildCached(schema) : schema
299
+ }
300
+
301
+ /** `zodSchemaOf` with the zod type the schema denotes. */
302
+ export function zodOf<S extends z.core.$ZodType | DataSchema>(schema: S): ZodOf<S> {
303
+ // The replay calls exactly the zod functions whose types define the builder's type, so the build is a `ZodOf<S>`.
304
+ return zodSchemaOf(schema) as ZodOf<S>
305
+ }
306
+
307
+ function buildCached(node: DataSchema): z.ZodType {
308
+ const cached = built.get(node)
309
+ if (cached !== undefined) {
310
+ built.delete(node)
311
+ built.set(node, cached)
312
+ return cached
313
+ }
314
+ const schema = build(node)
315
+ built.set(node, schema)
316
+ if (built.size > BUILT_SCHEMAS) {
317
+ const [oldest] = built.keys()
318
+ if (oldest !== undefined) {
319
+ built.delete(oldest)
320
+ }
321
+ }
322
+ return schema
323
+ }
324
+
325
+ /** A schema built without caching it; a part already cached is reused. */
326
+ function build(node: DataSchema): z.ZodType {
327
+ const wrapped = node.wrapped
328
+ if (wrapped !== null) {
329
+ return wrapped
330
+ }
331
+ const args = node.args.map((arg) => replayArg(arg, node))
332
+ if (node.receiver === null) {
333
+ return replayStep({ factory: node.name, iso: node.iso }, args)
334
+ }
335
+ return replayStep({ method: node.name, receiver: built.get(node.receiver) ?? build(node.receiver) }, args)
336
+ }
337
+
338
+ /** An argument as zod takes it: a schema in it built, an omitted option left out. */
339
+ function replayArg(value: unknown, node: DataSchema): ReplayArg {
340
+ if (value instanceof DataSchema) {
341
+ return built.get(value) ?? build(value)
342
+ }
343
+ if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value instanceof RegExp) {
344
+ return value
345
+ }
346
+ if (value instanceof z.ZodType || value instanceof Unreadable) {
347
+ return value
348
+ }
349
+ if (Array.isArray(value)) {
350
+ return value.map((item: unknown) => replayArg(item, node))
351
+ }
352
+ if (typeof value === 'object') {
353
+ const prototype: unknown = Object.getPrototypeOf(value)
354
+ if (prototype === Object.prototype || prototype === null) {
355
+ const entries: [string, ReplayArg][] = []
356
+ for (const [key, entry] of Object.entries(value)) {
357
+ if (entry !== undefined) {
358
+ entries.push([key, replayArg(entry, node)])
359
+ }
360
+ }
361
+ return Object.fromEntries(entries)
362
+ }
363
+ }
364
+ throw new SchemaRefusal(`a ${typeof value} argument of ${node.receiver === null ? `z.${node.name}()` : `.${node.name}()`}`, SCHEMA_SUBSET)
365
+ }
@@ -0,0 +1,18 @@
1
+ // `@fabrika/app/schema`: contract schemas held as data. Import `z` from here instead of `zod/v4` in contract modules;
2
+ // the subset, the method names and the inferred types are zod's, and zod is built from a schema only when it is used.
3
+
4
+ export * as z from './builder'
5
+ export {
6
+ type AnySchema,
7
+ BUILT_SCHEMAS,
8
+ DataEnum,
9
+ DataObject,
10
+ DataSchema,
11
+ type DataShapeInput,
12
+ isDataSchema,
13
+ type Message,
14
+ type ZodOf,
15
+ zodOf,
16
+ zodSchemaOf,
17
+ } from './data-schema'
18
+ export { type ReplayArg, type ReplayStep, replayStep, SCHEMA_SUBSET, SchemaRefusal, Unreadable } from './replay'