kizunajs 2.0.0-beta.2 → 2.0.0-beta.21

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 (81) hide show
  1. package/README.md +3 -2
  2. package/dist/{adapter-CZW-unqX.mjs → adapter-BSqNrxhq.mjs} +522 -104
  3. package/dist/adapter-C3WYdSfx.d.cts +2754 -0
  4. package/dist/{adapter-DDR_yo9L.cjs → adapter-ClaFZoab.cjs} +638 -196
  5. package/dist/adapter-D4bTPElA.d.mts +2754 -0
  6. package/dist/adapter.cjs +37 -29
  7. package/dist/adapter.d.cts +3 -5
  8. package/dist/adapter.d.mts +3 -5
  9. package/dist/adapter.mjs +5 -5
  10. package/dist/{error-response-C8Ragjcd.cjs → error-response-C9ymqSU4.cjs} +25 -5
  11. package/dist/{error-response-C839d8By.mjs → error-response-CNQaKVYd.mjs} +20 -6
  12. package/dist/{security-scheme-BrszwGD5.d.cts → error-response-NoOGdh8H.d.mts} +151 -24
  13. package/dist/{security-scheme-D3nb4XKj.d.mts → error-response-YbkRMKno.d.cts} +151 -24
  14. package/dist/generator.cjs +190 -95
  15. package/dist/generator.d.cts +189 -28
  16. package/dist/generator.d.mts +189 -28
  17. package/dist/generator.mjs +151 -60
  18. package/dist/index.cjs +159 -84
  19. package/dist/index.d.cts +193 -253
  20. package/dist/index.d.mts +193 -253
  21. package/dist/index.mjs +112 -38
  22. package/dist/jobs-entry.cjs +12 -11
  23. package/dist/jobs-entry.d.cts +1 -1
  24. package/dist/jobs-entry.d.mts +1 -1
  25. package/dist/jobs-entry.mjs +3 -2
  26. package/dist/plugin-Dw-yCjTY.cjs +233 -0
  27. package/dist/{cache-CLN5y0Xp.mjs → plugin-server-BztlE1fz.mjs} +188 -49
  28. package/dist/{cache-BgohRj0i.cjs → plugin-server-kUsK7thV.cjs} +238 -93
  29. package/dist/plugin-xxCxibmu.mjs +138 -0
  30. package/dist/plugin.cjs +8 -72
  31. package/dist/plugin.d.cts +3 -3
  32. package/dist/plugin.d.mts +3 -3
  33. package/dist/plugin.mjs +2 -68
  34. package/dist/{protected-resource-metadata-CA0v5cjg.d.mts → protected-resource-metadata-B9hMFQ9N.d.cts} +1 -1
  35. package/dist/{protected-resource-metadata-Cprrv0mt.d.cts → protected-resource-metadata-CfBVsqIk.d.mts} +1 -1
  36. package/dist/{schemas-C56no6bv.cjs → schemas-DNPVDvkd.cjs} +28 -1
  37. package/dist/{schemas-CJQcc97N.mjs → schemas-HW2FDsvz.mjs} +23 -2
  38. package/dist/schemas.cjs +3 -2
  39. package/dist/schemas.d.cts +24 -3
  40. package/dist/schemas.d.mts +24 -3
  41. package/dist/schemas.mjs +3 -3
  42. package/package.json +1 -1
  43. package/src/adapter.ts +245 -29
  44. package/src/api-definition.ts +12 -16
  45. package/src/api.ts +7 -3
  46. package/src/brand.ts +29 -0
  47. package/src/config.ts +51 -10
  48. package/src/configured.ts +13 -6
  49. package/src/define-config.ts +118 -39
  50. package/src/generator.ts +363 -46
  51. package/src/group-routes.ts +106 -0
  52. package/src/groups.ts +140 -0
  53. package/src/handler-pipeline.ts +78 -19
  54. package/src/index.ts +15 -6
  55. package/src/job-runner.ts +5 -0
  56. package/src/job-transport.ts +3 -3
  57. package/src/job.ts +8 -6
  58. package/src/jobs-dev-runner.ts +6 -0
  59. package/src/jobs.ts +61 -8
  60. package/src/kizuna.ts +56 -33
  61. package/src/plugin-server.ts +129 -19
  62. package/src/plugin.ts +269 -127
  63. package/src/routes.ts +80 -32
  64. package/src/schemas.ts +1 -0
  65. package/src/tool-answer.ts +21 -0
  66. package/src/tool-definitions.ts +166 -0
  67. package/src/tool-events.ts +90 -18
  68. package/src/tool-records.ts +11 -3
  69. package/src/tool-runner.ts +298 -0
  70. package/src/types.ts +90 -24
  71. package/src/zod-internals.ts +22 -5
  72. package/src/zod-meta.ts +7 -2
  73. package/dist/adapter-BGfMqEkM.d.cts +0 -563
  74. package/dist/adapter-Ci3cfcoT.d.mts +0 -563
  75. package/dist/api-definition-BHnh15zD.d.mts +0 -803
  76. package/dist/api-definition-DQj-ewHy.d.cts +0 -803
  77. package/dist/error-response-BBGSdgYw.d.mts +0 -67
  78. package/dist/error-response-Do38sr-9.d.cts +0 -67
  79. package/dist/plugin-Cz0kn6Lk.d.mts +0 -830
  80. package/dist/plugin-DhKvx_T0.d.cts +0 -830
  81. package/src/tags.ts +0 -67
@@ -1,6 +1,5 @@
1
- import { H as ResponseHeaders, J as Routes, W as RouteDefinition, k as CachePolicy } from "./security-scheme-BrszwGD5.cjs";
2
- import { St as streamStatuses, _t as routeStreams, bt as streamMode, gt as isNamedStream, it as EVENT_STREAM_MEDIA_TYPE, pt as StreamMode, rt as parsePath, vt as soleStreamResponse, xt as streamSchemas, yt as streamContentType } from "./plugin-DhKvx_T0.cjs";
3
- import { A as resolveResponseStream, C as localTypeName, D as resolveResponseContentType, E as resolveResponseCache, F as toCamelCase, I as toPascalCase, M as sanitizeIdentifier, N as shortTypeName, O as resolveResponseEtag, P as statusToCamelCase, S as isZodSchema, T as resolveResponseBody, V as FlattenedJob, X as Jobs, b as isStreamResponse, et as flattenJobs, j as sanitizeFieldName, k as resolveResponseHeaders, rt as jobAt, t as ApiDefinition, tt as isCompiledJob, v as isHintPrefix, w as mergeHeaderFields, x as isSuccessStatus, y as isJsonMediaType, z as CompiledJob } from "./api-definition-DQj-ewHy.cjs";
1
+ import { K as RouteDefinition, W as ResponseHeaders, Z as Routes, j as CachePolicy } from "./error-response-YbkRMKno.cjs";
2
+ import { $n as jobAt, At as shortTypeName, Ct as resolveResponseCache, Dt as resolveResponseStream, Et as resolveResponseHeaders, Fn as FlattenedJob, Ki as parsePath, Kn as Jobs, Mt as toCamelCase, Nn as CompiledJob, Nt as toPascalCase, Ot as sanitizeFieldName, Sn as GeneratedFile, St as resolveResponseBody, Tt as resolveResponseEtag, Xn as flattenJobs, Zn as isCompiledJob, _t as isStreamResponse, aa as isNamedStream, bt as localTypeName, ca as streamContentType, da as streamStatuses, gt as isJsonMediaType, ht as isHintPrefix, jt as statusToCamelCase, kt as sanitizeIdentifier, la as streamMode, na as StreamMode, oa as routeStreams, qi as EVENT_STREAM_MEDIA_TYPE, sa as soleStreamResponse, ua as streamSchemas, vt as isSuccessStatus, wn as ApiDefinition, wt as resolveResponseContentType, xt as mergeHeaderFields, yt as isZodSchema } from "./adapter-C3WYdSfx.cjs";
4
3
  import { z } from "zod";
5
4
 
6
5
  //#region src/zod-internals.d.ts
@@ -12,6 +11,8 @@ interface ZodDef {
12
11
  coerce?: boolean;
13
12
  innerType?: z.core.$ZodType;
14
13
  element?: z.core.$ZodType;
14
+ items?: z.core.$ZodType[];
15
+ rest?: z.core.$ZodType | null;
15
16
  in?: z.core.$ZodType;
16
17
  out?: z.core.$ZodType;
17
18
  shape?: Record<string, z.core.$ZodType>;
@@ -55,12 +56,14 @@ declare const isIntegerSchema: (schema: z.core.$ZodType) => boolean;
55
56
  */
56
57
  declare const readObjectShape: (schema: z.core.$ZodType) => Record<string, z.core.$ZodType> | undefined;
57
58
  /**
58
- * Removes optional/nullable/default wrappers, returning the inner schema and
59
- * whether any were present.
59
+ * Removes optional/nullable/default wrappers, returning the inner schema,
60
+ * whether the key may be absent, and whether the value may be null. A
61
+ * `z.string().nullable()` field is required, so it reports `optional: false`.
60
62
  */
61
63
  declare const unwrapOptionalWrappers: (schema: z.core.$ZodType) => {
62
64
  inner: z.core.$ZodType;
63
65
  optional: boolean;
66
+ nullable: boolean;
64
67
  };
65
68
  interface DiscriminatedUnion {
66
69
  discriminator: string;
@@ -128,6 +131,10 @@ declare const readMetaExamples: (schema: z.core.$ZodType) => readonly unknown[];
128
131
  * Returns a schema's `description` metadata, or undefined.
129
132
  */
130
133
  declare const readMetaDescription: (schema: z.core.$ZodType) => string | undefined;
134
+ /**
135
+ * Returns a schema's `brand` metadata, set by `Kizuna.brand`, or undefined.
136
+ */
137
+ declare const readMetaBrand: (schema: z.core.$ZodType) => string | undefined;
131
138
  /**
132
139
  * The `Kizuna.model` schemas in the global registry, keyed by their `id`.
133
140
  */
@@ -176,7 +183,10 @@ declare const cacheHeaders: (cache: CachePolicy | undefined) => ResponseHeaders;
176
183
  interface GeneratorRouteContext {
177
184
  routeKey: string;
178
185
  route: RouteDefinition;
179
- routeTags: string[];
186
+ /**
187
+ * The route's groups, as dotted paths, its own first.
188
+ */
189
+ routeGroups: string[];
180
190
  /**
181
191
  * Whether the route is deprecated.
182
192
  */
@@ -186,33 +196,184 @@ interface GeneratorRouteContext {
186
196
  * `undefined` when the route declares neither.
187
197
  */
188
198
  deprecationMessage: string | undefined;
199
+ /**
200
+ * Whether the route is `hidden`. Clients and the OpenAPI document leave a
201
+ * hidden route out; a generator listing every served route marks it.
202
+ */
203
+ hidden: boolean;
204
+ /**
205
+ * The plugin the route comes from, or `undefined` for the app's own. A
206
+ * plugin's routes sit under its slug.
207
+ */
208
+ plugin: GeneratorPluginInfo | undefined;
209
+ }
210
+ /**
211
+ * Where a plugin's route came from.
212
+ */
213
+ interface GeneratorPluginInfo {
214
+ /**
215
+ * The slug the app installed the plugin under.
216
+ */
217
+ slug: string;
218
+ }
219
+ /**
220
+ * The route tree the generated clients hold: the app's routes, less every
221
+ * `hidden` one.
222
+ */
223
+ declare const listedRoutes: (contract: ApiDefinition) => Routes;
224
+ /**
225
+ * A named model the api uses.
226
+ */
227
+ interface GeneratorModelContext {
228
+ /**
229
+ * The model's title, e.g. `User`.
230
+ */
231
+ name: string;
232
+ /**
233
+ * The schema to generate a type from.
234
+ */
235
+ schema: z.ZodType;
236
+ /**
237
+ * The model's description, for a doc comment.
238
+ */
239
+ description: string | undefined;
240
+ /**
241
+ * The plugin that brought it, when only a plugin's routes use it.
242
+ */
243
+ plugin: GeneratorPluginInfo | undefined;
244
+ }
245
+ /**
246
+ * What a client's or a generator's `generate` returns: a callback for each
247
+ * model and route, then `finalize`, which returns the result.
248
+ */
249
+ interface GeneratorWalk<Output = string> {
250
+ /**
251
+ * Called once for every named model the walked routes use, sorted by name.
252
+ */
253
+ processModel?: (model: GeneratorModelContext) => void;
254
+ /**
255
+ * Called once for every route, in the order the api declares them.
256
+ */
257
+ processRoute?: (context: GeneratorRouteContext) => void;
258
+ /**
259
+ * Called once, after the walk.
260
+ */
261
+ finalize: () => Output;
262
+ }
263
+ interface WalkApiOptions {
264
+ /**
265
+ * Leave `hidden` routes out of the walk, and the models only they use.
266
+ *
267
+ * @default false
268
+ */
269
+ skipHidden?: boolean;
270
+ }
271
+ /**
272
+ * Run a walk over an api: its models, then every route it serves, the app's
273
+ * and each plugin's under its slug. Returns what `finalize` returns.
274
+ *
275
+ * @example
276
+ * const routeList = walkApi(api, {
277
+ * processRoute: ({ route }) => lines.push(`${route.method} ${route.path}`),
278
+ * finalize: () => lines.join('\n'),
279
+ * });
280
+ */
281
+ declare const walkApi: <Output>(api: ApiDefinition, walk: GeneratorWalk<Output>, options?: WalkApiOptions) => Output;
282
+ type OptionsOutput<Schema> = Schema extends z.ZodType ? z.output<Schema> : Record<string, never>;
283
+ type OptionsInput<Schema> = Schema extends z.ZodType ? z.input<Schema> : {};
284
+ /**
285
+ * What `generate` receives.
286
+ */
287
+ interface GenerateContext<Options> {
288
+ /**
289
+ * The options the app passed, less `output`, validated against the
290
+ * `options` schema.
291
+ */
292
+ options: Options;
293
+ /**
294
+ * The api being generated from.
295
+ */
296
+ api: ApiDefinition;
297
+ }
298
+ /**
299
+ * What every client and generator takes beside its own options.
300
+ */
301
+ interface GeneratedFileOptions {
302
+ /**
303
+ * Path the file is written to, resolved against the config's directory.
304
+ */
305
+ output: string;
306
+ }
307
+ /**
308
+ * What {@link defineClient} takes.
309
+ */
310
+ interface ClientDefinition<Schema extends z.ZodType | undefined> {
311
+ /**
312
+ * The language this client generates, like `dart`.
313
+ */
314
+ target: string;
315
+ /**
316
+ * A Zod schema for what the app passes in, beside `output`.
317
+ */
318
+ options?: Schema;
319
+ /**
320
+ * Returns the walk. Kizuna calls it on every `kizuna generate`, and skips
321
+ * hidden routes, so one never reaches `processRoute`.
322
+ */
323
+ generate: (context: GenerateContext<OptionsOutput<Schema>>) => GeneratorWalk;
189
324
  }
190
325
  /**
191
- * Factory for building type-safe routes generators.
326
+ * Declare a client for a language: the options an app passes it, and the walk
327
+ * that returns its file. Returns the function an app names under `clients`.
192
328
  *
193
- * Centralises routes walking and deprecation resolution so generator authors
194
- * only need to implement `processRoute` and `finalize`. Field-level deprecation
195
- * lives on the schemas themselves, read with `readDeprecation`.
329
+ * @example
330
+ * export const dartClient = defineClient({
331
+ * target: 'dart',
332
+ * options: z.object({
333
+ * library: z.string().default('api'),
334
+ * }),
335
+ * generate: ({ options }) => {
336
+ * const writer = new DartWriter(options.library);
196
337
  *
197
- * ```ts
198
- * const generateRouteList = createGenerator(() => {
199
- * const routeList: string[] = [];
200
- * return {
201
- * processRoute({ route, deprecated }) {
202
- * routeList.push(`${route.method} ${route.path}${deprecated ? ' (deprecated)' : ''}`);
203
- * },
204
- * finalize() {
205
- * return routeList;
206
- * },
207
- * };
338
+ * return {
339
+ * processModel: (model) => writer.model(model),
340
+ * processRoute: (context) => writer.method(context),
341
+ * finalize: () => writer.render(),
342
+ * };
343
+ * },
208
344
  * });
345
+ */
346
+ declare const defineClient: <Schema extends z.ZodType | undefined = undefined>(definition: ClientDefinition<Schema>) => ((options: OptionsInput<Schema> & GeneratedFileOptions) => GeneratedFile);
347
+ /**
348
+ * What {@link defineGenerator} takes.
349
+ */
350
+ interface GeneratorDefinition<Schema extends z.ZodType | undefined> {
351
+ /**
352
+ * A Zod schema for what the plugin passes in, beside `output`.
353
+ */
354
+ options?: Schema;
355
+ /**
356
+ * Returns the walk. It sees every served route, hidden ones included, and
357
+ * decides what to leave out.
358
+ */
359
+ generate: (context: GenerateContext<OptionsOutput<Schema>>) => GeneratorWalk;
360
+ }
361
+ /**
362
+ * Declare a generator for a file that isn't a client, like a document or a
363
+ * manifest. A plugin installs it by returning it from `setup`.
364
+ *
365
+ * @example
366
+ * export const gatewayManifest = defineGenerator({
367
+ * generate: () => {
368
+ * const entries: string[] = [];
209
369
  *
210
- * const list = generateRouteList(kizuna.api, {});
211
- * ```
370
+ * return {
371
+ * processRoute: ({ route }) => entries.push(`${route.method} ${route.path}`),
372
+ * finalize: () => entries.join('\n'),
373
+ * };
374
+ * },
375
+ * });
212
376
  */
213
- declare const createGenerator: <Options, Output>(factory: (options: Options, contract: ApiDefinition) => {
214
- processRoute: (context: GeneratorRouteContext) => void;
215
- finalize: () => Output;
216
- }) => ((contract: ApiDefinition, options: Options) => Output);
377
+ declare const defineGenerator: <Schema extends z.ZodType | undefined = undefined>(definition: GeneratorDefinition<Schema>) => ((options: OptionsInput<Schema> & GeneratedFileOptions) => GeneratedFile);
217
378
  //#endregion
218
- export { type CompiledJob, type DiscriminatedUnion, EVENT_STREAM_MEDIA_TYPE, FILE_PROBE, type FlattenedJob, GeneratorRouteContext, type Jobs, type RouteDefinition, type Routes, type StreamMode, type ToolNameEntry, type ToolOrigin, type ZodDef, cacheHeaders, createGenerator, deprecationHeaders, deriveToolNames, flattenJobs, globalRegistrySchemas, isBinarySchema, isCompiledJob, isDiscriminatedUnionSchema, isFileSchema, isHintPrefix, isIntegerSchema, isJsonMediaType, isNamedStream, isObjectSchema, isStreamResponse, isSuccessStatus, isVoidSchema, isZodSchema, jobAt, localTypeName, mergeHeaderFields, parsePath, readDef, readDefType, readDeprecation, readDiscriminatedUnion, readDiscriminatorLiteral, readDiscriminatorStringLiteral, readMeta, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, resolveResponseStream, routeStreams, sanitizeFieldName, sanitizeIdentifier, shortTypeName, soleStreamResponse, statusToCamelCase, streamContentType, streamMode, streamSchemas, streamStatuses, toCamelCase, toPascalCase, toToolName, unwrapOptionalWrappers };
379
+ export { ClientDefinition, type CompiledJob, type DiscriminatedUnion, EVENT_STREAM_MEDIA_TYPE, FILE_PROBE, type FlattenedJob, GenerateContext, type GeneratedFile, GeneratedFileOptions, GeneratorDefinition, GeneratorModelContext, GeneratorPluginInfo, GeneratorRouteContext, GeneratorWalk, type Jobs, type RouteDefinition, type Routes, type StreamMode, type ToolNameEntry, type ToolOrigin, WalkApiOptions, type ZodDef, cacheHeaders, defineClient, defineGenerator, deprecationHeaders, deriveToolNames, flattenJobs, globalRegistrySchemas, isBinarySchema, isCompiledJob, isDiscriminatedUnionSchema, isFileSchema, isHintPrefix, isIntegerSchema, isJsonMediaType, isNamedStream, isObjectSchema, isStreamResponse, isSuccessStatus, isVoidSchema, isZodSchema, jobAt, listedRoutes, localTypeName, mergeHeaderFields, parsePath, readDef, readDefType, readDeprecation, readDiscriminatedUnion, readDiscriminatorLiteral, readDiscriminatorStringLiteral, readMeta, readMetaBrand, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, resolveResponseStream, routeStreams, sanitizeFieldName, sanitizeIdentifier, shortTypeName, soleStreamResponse, statusToCamelCase, streamContentType, streamMode, streamSchemas, streamStatuses, toCamelCase, toPascalCase, toToolName, unwrapOptionalWrappers, walkApi };
@@ -1,6 +1,5 @@
1
- import { H as ResponseHeaders, J as Routes, W as RouteDefinition, k as CachePolicy } from "./security-scheme-D3nb4XKj.mjs";
2
- import { St as streamStatuses, _t as routeStreams, bt as streamMode, gt as isNamedStream, it as EVENT_STREAM_MEDIA_TYPE, pt as StreamMode, rt as parsePath, vt as soleStreamResponse, xt as streamSchemas, yt as streamContentType } from "./plugin-Cz0kn6Lk.mjs";
3
- import { A as resolveResponseStream, C as localTypeName, D as resolveResponseContentType, E as resolveResponseCache, F as toCamelCase, I as toPascalCase, M as sanitizeIdentifier, N as shortTypeName, O as resolveResponseEtag, P as statusToCamelCase, S as isZodSchema, T as resolveResponseBody, V as FlattenedJob, X as Jobs, b as isStreamResponse, et as flattenJobs, j as sanitizeFieldName, k as resolveResponseHeaders, rt as jobAt, t as ApiDefinition, tt as isCompiledJob, v as isHintPrefix, w as mergeHeaderFields, x as isSuccessStatus, y as isJsonMediaType, z as CompiledJob } from "./api-definition-BHnh15zD.mjs";
1
+ import { K as RouteDefinition, W as ResponseHeaders, Z as Routes, j as CachePolicy } from "./error-response-NoOGdh8H.mjs";
2
+ import { $n as jobAt, At as shortTypeName, Ct as resolveResponseCache, Dt as resolveResponseStream, Et as resolveResponseHeaders, Fn as FlattenedJob, Ki as parsePath, Kn as Jobs, Mt as toCamelCase, Nn as CompiledJob, Nt as toPascalCase, Ot as sanitizeFieldName, Sn as GeneratedFile, St as resolveResponseBody, Tt as resolveResponseEtag, Xn as flattenJobs, Zn as isCompiledJob, _t as isStreamResponse, aa as isNamedStream, bt as localTypeName, ca as streamContentType, da as streamStatuses, gt as isJsonMediaType, ht as isHintPrefix, jt as statusToCamelCase, kt as sanitizeIdentifier, la as streamMode, na as StreamMode, oa as routeStreams, qi as EVENT_STREAM_MEDIA_TYPE, sa as soleStreamResponse, ua as streamSchemas, vt as isSuccessStatus, wn as ApiDefinition, wt as resolveResponseContentType, xt as mergeHeaderFields, yt as isZodSchema } from "./adapter-D4bTPElA.mjs";
4
3
  import { z } from "zod";
5
4
 
6
5
  //#region src/zod-internals.d.ts
@@ -12,6 +11,8 @@ interface ZodDef {
12
11
  coerce?: boolean;
13
12
  innerType?: z.core.$ZodType;
14
13
  element?: z.core.$ZodType;
14
+ items?: z.core.$ZodType[];
15
+ rest?: z.core.$ZodType | null;
15
16
  in?: z.core.$ZodType;
16
17
  out?: z.core.$ZodType;
17
18
  shape?: Record<string, z.core.$ZodType>;
@@ -55,12 +56,14 @@ declare const isIntegerSchema: (schema: z.core.$ZodType) => boolean;
55
56
  */
56
57
  declare const readObjectShape: (schema: z.core.$ZodType) => Record<string, z.core.$ZodType> | undefined;
57
58
  /**
58
- * Removes optional/nullable/default wrappers, returning the inner schema and
59
- * whether any were present.
59
+ * Removes optional/nullable/default wrappers, returning the inner schema,
60
+ * whether the key may be absent, and whether the value may be null. A
61
+ * `z.string().nullable()` field is required, so it reports `optional: false`.
60
62
  */
61
63
  declare const unwrapOptionalWrappers: (schema: z.core.$ZodType) => {
62
64
  inner: z.core.$ZodType;
63
65
  optional: boolean;
66
+ nullable: boolean;
64
67
  };
65
68
  interface DiscriminatedUnion {
66
69
  discriminator: string;
@@ -128,6 +131,10 @@ declare const readMetaExamples: (schema: z.core.$ZodType) => readonly unknown[];
128
131
  * Returns a schema's `description` metadata, or undefined.
129
132
  */
130
133
  declare const readMetaDescription: (schema: z.core.$ZodType) => string | undefined;
134
+ /**
135
+ * Returns a schema's `brand` metadata, set by `Kizuna.brand`, or undefined.
136
+ */
137
+ declare const readMetaBrand: (schema: z.core.$ZodType) => string | undefined;
131
138
  /**
132
139
  * The `Kizuna.model` schemas in the global registry, keyed by their `id`.
133
140
  */
@@ -176,7 +183,10 @@ declare const cacheHeaders: (cache: CachePolicy | undefined) => ResponseHeaders;
176
183
  interface GeneratorRouteContext {
177
184
  routeKey: string;
178
185
  route: RouteDefinition;
179
- routeTags: string[];
186
+ /**
187
+ * The route's groups, as dotted paths, its own first.
188
+ */
189
+ routeGroups: string[];
180
190
  /**
181
191
  * Whether the route is deprecated.
182
192
  */
@@ -186,33 +196,184 @@ interface GeneratorRouteContext {
186
196
  * `undefined` when the route declares neither.
187
197
  */
188
198
  deprecationMessage: string | undefined;
199
+ /**
200
+ * Whether the route is `hidden`. Clients and the OpenAPI document leave a
201
+ * hidden route out; a generator listing every served route marks it.
202
+ */
203
+ hidden: boolean;
204
+ /**
205
+ * The plugin the route comes from, or `undefined` for the app's own. A
206
+ * plugin's routes sit under its slug.
207
+ */
208
+ plugin: GeneratorPluginInfo | undefined;
209
+ }
210
+ /**
211
+ * Where a plugin's route came from.
212
+ */
213
+ interface GeneratorPluginInfo {
214
+ /**
215
+ * The slug the app installed the plugin under.
216
+ */
217
+ slug: string;
218
+ }
219
+ /**
220
+ * The route tree the generated clients hold: the app's routes, less every
221
+ * `hidden` one.
222
+ */
223
+ declare const listedRoutes: (contract: ApiDefinition) => Routes;
224
+ /**
225
+ * A named model the api uses.
226
+ */
227
+ interface GeneratorModelContext {
228
+ /**
229
+ * The model's title, e.g. `User`.
230
+ */
231
+ name: string;
232
+ /**
233
+ * The schema to generate a type from.
234
+ */
235
+ schema: z.ZodType;
236
+ /**
237
+ * The model's description, for a doc comment.
238
+ */
239
+ description: string | undefined;
240
+ /**
241
+ * The plugin that brought it, when only a plugin's routes use it.
242
+ */
243
+ plugin: GeneratorPluginInfo | undefined;
244
+ }
245
+ /**
246
+ * What a client's or a generator's `generate` returns: a callback for each
247
+ * model and route, then `finalize`, which returns the result.
248
+ */
249
+ interface GeneratorWalk<Output = string> {
250
+ /**
251
+ * Called once for every named model the walked routes use, sorted by name.
252
+ */
253
+ processModel?: (model: GeneratorModelContext) => void;
254
+ /**
255
+ * Called once for every route, in the order the api declares them.
256
+ */
257
+ processRoute?: (context: GeneratorRouteContext) => void;
258
+ /**
259
+ * Called once, after the walk.
260
+ */
261
+ finalize: () => Output;
262
+ }
263
+ interface WalkApiOptions {
264
+ /**
265
+ * Leave `hidden` routes out of the walk, and the models only they use.
266
+ *
267
+ * @default false
268
+ */
269
+ skipHidden?: boolean;
270
+ }
271
+ /**
272
+ * Run a walk over an api: its models, then every route it serves, the app's
273
+ * and each plugin's under its slug. Returns what `finalize` returns.
274
+ *
275
+ * @example
276
+ * const routeList = walkApi(api, {
277
+ * processRoute: ({ route }) => lines.push(`${route.method} ${route.path}`),
278
+ * finalize: () => lines.join('\n'),
279
+ * });
280
+ */
281
+ declare const walkApi: <Output>(api: ApiDefinition, walk: GeneratorWalk<Output>, options?: WalkApiOptions) => Output;
282
+ type OptionsOutput<Schema> = Schema extends z.ZodType ? z.output<Schema> : Record<string, never>;
283
+ type OptionsInput<Schema> = Schema extends z.ZodType ? z.input<Schema> : {};
284
+ /**
285
+ * What `generate` receives.
286
+ */
287
+ interface GenerateContext<Options> {
288
+ /**
289
+ * The options the app passed, less `output`, validated against the
290
+ * `options` schema.
291
+ */
292
+ options: Options;
293
+ /**
294
+ * The api being generated from.
295
+ */
296
+ api: ApiDefinition;
297
+ }
298
+ /**
299
+ * What every client and generator takes beside its own options.
300
+ */
301
+ interface GeneratedFileOptions {
302
+ /**
303
+ * Path the file is written to, resolved against the config's directory.
304
+ */
305
+ output: string;
306
+ }
307
+ /**
308
+ * What {@link defineClient} takes.
309
+ */
310
+ interface ClientDefinition<Schema extends z.ZodType | undefined> {
311
+ /**
312
+ * The language this client generates, like `dart`.
313
+ */
314
+ target: string;
315
+ /**
316
+ * A Zod schema for what the app passes in, beside `output`.
317
+ */
318
+ options?: Schema;
319
+ /**
320
+ * Returns the walk. Kizuna calls it on every `kizuna generate`, and skips
321
+ * hidden routes, so one never reaches `processRoute`.
322
+ */
323
+ generate: (context: GenerateContext<OptionsOutput<Schema>>) => GeneratorWalk;
189
324
  }
190
325
  /**
191
- * Factory for building type-safe routes generators.
326
+ * Declare a client for a language: the options an app passes it, and the walk
327
+ * that returns its file. Returns the function an app names under `clients`.
192
328
  *
193
- * Centralises routes walking and deprecation resolution so generator authors
194
- * only need to implement `processRoute` and `finalize`. Field-level deprecation
195
- * lives on the schemas themselves, read with `readDeprecation`.
329
+ * @example
330
+ * export const dartClient = defineClient({
331
+ * target: 'dart',
332
+ * options: z.object({
333
+ * library: z.string().default('api'),
334
+ * }),
335
+ * generate: ({ options }) => {
336
+ * const writer = new DartWriter(options.library);
196
337
  *
197
- * ```ts
198
- * const generateRouteList = createGenerator(() => {
199
- * const routeList: string[] = [];
200
- * return {
201
- * processRoute({ route, deprecated }) {
202
- * routeList.push(`${route.method} ${route.path}${deprecated ? ' (deprecated)' : ''}`);
203
- * },
204
- * finalize() {
205
- * return routeList;
206
- * },
207
- * };
338
+ * return {
339
+ * processModel: (model) => writer.model(model),
340
+ * processRoute: (context) => writer.method(context),
341
+ * finalize: () => writer.render(),
342
+ * };
343
+ * },
208
344
  * });
345
+ */
346
+ declare const defineClient: <Schema extends z.ZodType | undefined = undefined>(definition: ClientDefinition<Schema>) => ((options: OptionsInput<Schema> & GeneratedFileOptions) => GeneratedFile);
347
+ /**
348
+ * What {@link defineGenerator} takes.
349
+ */
350
+ interface GeneratorDefinition<Schema extends z.ZodType | undefined> {
351
+ /**
352
+ * A Zod schema for what the plugin passes in, beside `output`.
353
+ */
354
+ options?: Schema;
355
+ /**
356
+ * Returns the walk. It sees every served route, hidden ones included, and
357
+ * decides what to leave out.
358
+ */
359
+ generate: (context: GenerateContext<OptionsOutput<Schema>>) => GeneratorWalk;
360
+ }
361
+ /**
362
+ * Declare a generator for a file that isn't a client, like a document or a
363
+ * manifest. A plugin installs it by returning it from `setup`.
364
+ *
365
+ * @example
366
+ * export const gatewayManifest = defineGenerator({
367
+ * generate: () => {
368
+ * const entries: string[] = [];
209
369
  *
210
- * const list = generateRouteList(kizuna.api, {});
211
- * ```
370
+ * return {
371
+ * processRoute: ({ route }) => entries.push(`${route.method} ${route.path}`),
372
+ * finalize: () => entries.join('\n'),
373
+ * };
374
+ * },
375
+ * });
212
376
  */
213
- declare const createGenerator: <Options, Output>(factory: (options: Options, contract: ApiDefinition) => {
214
- processRoute: (context: GeneratorRouteContext) => void;
215
- finalize: () => Output;
216
- }) => ((contract: ApiDefinition, options: Options) => Output);
377
+ declare const defineGenerator: <Schema extends z.ZodType | undefined = undefined>(definition: GeneratorDefinition<Schema>) => ((options: OptionsInput<Schema> & GeneratedFileOptions) => GeneratedFile);
217
378
  //#endregion
218
- export { type CompiledJob, type DiscriminatedUnion, EVENT_STREAM_MEDIA_TYPE, FILE_PROBE, type FlattenedJob, GeneratorRouteContext, type Jobs, type RouteDefinition, type Routes, type StreamMode, type ToolNameEntry, type ToolOrigin, type ZodDef, cacheHeaders, createGenerator, deprecationHeaders, deriveToolNames, flattenJobs, globalRegistrySchemas, isBinarySchema, isCompiledJob, isDiscriminatedUnionSchema, isFileSchema, isHintPrefix, isIntegerSchema, isJsonMediaType, isNamedStream, isObjectSchema, isStreamResponse, isSuccessStatus, isVoidSchema, isZodSchema, jobAt, localTypeName, mergeHeaderFields, parsePath, readDef, readDefType, readDeprecation, readDiscriminatedUnion, readDiscriminatorLiteral, readDiscriminatorStringLiteral, readMeta, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, resolveResponseStream, routeStreams, sanitizeFieldName, sanitizeIdentifier, shortTypeName, soleStreamResponse, statusToCamelCase, streamContentType, streamMode, streamSchemas, streamStatuses, toCamelCase, toPascalCase, toToolName, unwrapOptionalWrappers };
379
+ export { ClientDefinition, type CompiledJob, type DiscriminatedUnion, EVENT_STREAM_MEDIA_TYPE, FILE_PROBE, type FlattenedJob, GenerateContext, type GeneratedFile, GeneratedFileOptions, GeneratorDefinition, GeneratorModelContext, GeneratorPluginInfo, GeneratorRouteContext, GeneratorWalk, type Jobs, type RouteDefinition, type Routes, type StreamMode, type ToolNameEntry, type ToolOrigin, WalkApiOptions, type ZodDef, cacheHeaders, defineClient, defineGenerator, deprecationHeaders, deriveToolNames, flattenJobs, globalRegistrySchemas, isBinarySchema, isCompiledJob, isDiscriminatedUnionSchema, isFileSchema, isHintPrefix, isIntegerSchema, isJsonMediaType, isNamedStream, isObjectSchema, isStreamResponse, isSuccessStatus, isVoidSchema, isZodSchema, jobAt, listedRoutes, localTypeName, mergeHeaderFields, parsePath, readDef, readDefType, readDeprecation, readDiscriminatedUnion, readDiscriminatorLiteral, readDiscriminatorStringLiteral, readMeta, readMetaBrand, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, resolveResponseStream, routeStreams, sanitizeFieldName, sanitizeIdentifier, shortTypeName, soleStreamResponse, statusToCamelCase, streamContentType, streamMode, streamSchemas, streamStatuses, toCamelCase, toPascalCase, toToolName, unwrapOptionalWrappers, walkApi };