@digitraffic/common 2026.10.30-1 → 2026.11.2-1

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.
@@ -131,11 +131,15 @@ describe("createKyHooks", () => {
131
131
  expect(httpLogger.logResponse).toHaveBeenCalledWith(200, 5);
132
132
  expect(cloneSpy).not.toHaveBeenCalled();
133
133
  });
134
- test("afterResponse measures body length when header is missing and keeps body readable", async () => {
134
+ test("afterResponse leaves length unknown when header is missing and keeps body readable", async () => {
135
135
  const { httpLogger, fn } = hook("afterResponse");
136
136
  const response = new Response("hello", { status: 201 });
137
+ const cloneSpy = vi.spyOn(response, "clone");
137
138
  const result = (await fn({ response }));
138
- expect(httpLogger.logResponse).toHaveBeenCalledWith(201, 5);
139
+ // The body must not be read just for logging. Buffering it would hold
140
+ // the whole payload in memory and block streaming consumers.
141
+ expect(httpLogger.logResponse).toHaveBeenCalledWith(201, undefined);
142
+ expect(cloneSpy).not.toHaveBeenCalled();
139
143
  expect(await result.text()).toBe("hello");
140
144
  });
141
145
  test("beforeError logs and returns non-HTTP errors", () => {
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,443 @@
1
+ import { describe, expect, test } from "vitest";
2
+ import { z } from "zod";
3
+ import { convertJsonSchemaNullableToOneOfDeep, toApiGatewayJsonSchema, } from "../../utils/api-model.js";
4
+ describe("convertJsonSchemaNullableToOneOfDeep", () => {
5
+ test("does not change a schema without nullable", () => {
6
+ const input = {
7
+ type: "object",
8
+ properties: {
9
+ name: { type: "string", description: "Vessel name" },
10
+ ids: { type: "array", items: { type: "number" } },
11
+ union: { anyOf: [{ type: "string" }, { type: "number" }] },
12
+ },
13
+ required: ["name"],
14
+ additionalProperties: false,
15
+ };
16
+ expect(convertJsonSchemaNullableToOneOfDeep(input)).toEqual(input);
17
+ });
18
+ test("converts nullable fields to oneOf", () => {
19
+ const schema = convertJsonSchemaNullableToOneOfDeep({
20
+ type: "object",
21
+ properties: {
22
+ reason: {
23
+ type: "string",
24
+ nullable: true,
25
+ description: "Optional reason",
26
+ },
27
+ },
28
+ });
29
+ expect(schema).toEqual({
30
+ type: "object",
31
+ properties: {
32
+ reason: {
33
+ oneOf: [
34
+ { type: "string", description: "Optional reason" },
35
+ { type: "null" },
36
+ ],
37
+ },
38
+ },
39
+ });
40
+ });
41
+ test("converts nested nullable fields", () => {
42
+ const schema = convertJsonSchemaNullableToOneOfDeep({
43
+ type: "array",
44
+ items: {
45
+ type: "object",
46
+ properties: {
47
+ reason: { type: "string", nullable: true },
48
+ },
49
+ },
50
+ });
51
+ expect(schema).toEqual({
52
+ type: "array",
53
+ items: {
54
+ type: "object",
55
+ properties: {
56
+ reason: {
57
+ oneOf: [{ type: "string" }, { type: "null" }],
58
+ },
59
+ },
60
+ },
61
+ });
62
+ });
63
+ test("adds null to an existing union", () => {
64
+ const schema = convertJsonSchemaNullableToOneOfDeep({
65
+ anyOf: [{ type: "string" }, { type: "number" }],
66
+ nullable: true,
67
+ });
68
+ expect(schema).toEqual({
69
+ anyOf: [{ type: "string" }, { type: "number" }, { type: "null" }],
70
+ });
71
+ });
72
+ test("keeps null allowed when nullable schema uses allOf", () => {
73
+ // Zod can emit nullable intersections as { nullable: true, allOf: [...] }.
74
+ // anyOf is used instead of oneOf because an allOf alternative could also
75
+ // accept null, and oneOf would then reject it.
76
+ const schema = convertJsonSchemaNullableToOneOfDeep({
77
+ allOf: [{ type: "object" }, { type: "object" }],
78
+ nullable: true,
79
+ });
80
+ expect(schema).toEqual({
81
+ anyOf: [
82
+ { allOf: [{ type: "object" }, { type: "object" }] },
83
+ { type: "null" },
84
+ ],
85
+ });
86
+ });
87
+ test("keeps null allowed when nullable schema is only a reference", () => {
88
+ const schema = convertJsonSchemaNullableToOneOfDeep({
89
+ type: "object",
90
+ definitions: {
91
+ Vessel: { type: "object" },
92
+ },
93
+ properties: {
94
+ vessel: { ref: "#/definitions/Vessel", nullable: true },
95
+ },
96
+ });
97
+ expect(schema).toEqual({
98
+ type: "object",
99
+ definitions: {
100
+ Vessel: { type: "object" },
101
+ },
102
+ properties: {
103
+ vessel: {
104
+ anyOf: [{ ref: "#/definitions/Vessel" }, { type: "null" }],
105
+ },
106
+ },
107
+ });
108
+ });
109
+ test("keeps null allowed when nullable schema is empty", () => {
110
+ // An empty schema accepts everything, including null. oneOf would reject
111
+ // null because both alternatives match, so anyOf must be used.
112
+ const schema = convertJsonSchemaNullableToOneOfDeep({
113
+ nullable: true,
114
+ });
115
+ expect(schema).toEqual({
116
+ anyOf: [{}, { type: "null" }],
117
+ });
118
+ });
119
+ test("keeps a property named nullable", () => {
120
+ // "nullable" here is a field name, not the OpenAPI keyword
121
+ const schema = convertJsonSchemaNullableToOneOfDeep({
122
+ type: "object",
123
+ properties: {
124
+ nullable: { type: "boolean" },
125
+ },
126
+ required: ["nullable"],
127
+ });
128
+ expect(schema).toEqual({
129
+ type: "object",
130
+ properties: {
131
+ nullable: { type: "boolean" },
132
+ },
133
+ required: ["nullable"],
134
+ });
135
+ });
136
+ test("keeps literal values such as defaults untouched", () => {
137
+ // The default value is data, not schema. It must not be rewritten.
138
+ const schema = convertJsonSchemaNullableToOneOfDeep({
139
+ type: "object",
140
+ properties: {
141
+ settings: {
142
+ type: "object",
143
+ default: { nullable: true },
144
+ },
145
+ },
146
+ });
147
+ expect(schema).toEqual({
148
+ type: "object",
149
+ properties: {
150
+ settings: {
151
+ type: "object",
152
+ default: { nullable: true },
153
+ },
154
+ },
155
+ });
156
+ });
157
+ test("converts nullable inside dependencies schemas", () => {
158
+ const schema = convertJsonSchemaNullableToOneOfDeep({
159
+ type: "object",
160
+ dependencies: {
161
+ // schema dependency: applied when "credit" is present
162
+ credit: {
163
+ properties: {
164
+ billingAddress: { type: "string", nullable: true },
165
+ },
166
+ },
167
+ // property dependency: a plain name list, must stay unchanged
168
+ name: ["firstName"],
169
+ },
170
+ });
171
+ expect(schema).toEqual({
172
+ type: "object",
173
+ dependencies: {
174
+ credit: {
175
+ properties: {
176
+ billingAddress: {
177
+ oneOf: [{ type: "string" }, { type: "null" }],
178
+ },
179
+ },
180
+ },
181
+ name: ["firstName"],
182
+ },
183
+ });
184
+ });
185
+ test("keeps definitions resolvable when a nullable root is wrapped", () => {
186
+ // definitions must stay at the root, otherwise "#/definitions/Code"
187
+ // would point to nothing after wrapping
188
+ const schema = convertJsonSchemaNullableToOneOfDeep({
189
+ type: "object",
190
+ definitions: {
191
+ Code: { type: "string", nullable: true },
192
+ },
193
+ properties: {
194
+ code: { ref: "#/definitions/Code" },
195
+ },
196
+ nullable: true,
197
+ });
198
+ expect(schema).toEqual({
199
+ definitions: {
200
+ Code: { oneOf: [{ type: "string" }, { type: "null" }] },
201
+ },
202
+ oneOf: [
203
+ {
204
+ type: "object",
205
+ properties: {
206
+ code: { ref: "#/definitions/Code" },
207
+ },
208
+ },
209
+ { type: "null" },
210
+ ],
211
+ });
212
+ });
213
+ test("wraps a nullable anyOf that has sibling constraints", () => {
214
+ // enum applies to the whole schema, so null added inside anyOf alone
215
+ // would still be rejected by it
216
+ const schema = convertJsonSchemaNullableToOneOfDeep({
217
+ anyOf: [{ type: "string" }, { type: "number" }],
218
+ enum: ["a", 1],
219
+ nullable: true,
220
+ });
221
+ expect(schema).toEqual({
222
+ anyOf: [
223
+ {
224
+ anyOf: [{ type: "string" }, { type: "number" }],
225
+ enum: ["a", 1],
226
+ },
227
+ { type: "null" },
228
+ ],
229
+ });
230
+ });
231
+ test("removes nullable false from root and nested schemas", () => {
232
+ const schema = convertJsonSchemaNullableToOneOfDeep({
233
+ type: "object",
234
+ nullable: false,
235
+ properties: {
236
+ name: { type: "string", nullable: false },
237
+ },
238
+ });
239
+ expect(schema).toEqual({
240
+ type: "object",
241
+ properties: {
242
+ name: { type: "string" },
243
+ },
244
+ });
245
+ });
246
+ test("throws when wrapping would break a local reference", () => {
247
+ // "#/properties/..." would point to nothing after wrapping, so the
248
+ // conversion must fail at synth time instead of producing a broken model
249
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
250
+ type: "object",
251
+ nullable: true,
252
+ properties: {
253
+ homeAddress: { type: "object" },
254
+ billingAddress: { ref: "#/properties/homeAddress" },
255
+ },
256
+ })).toThrow(/#\/properties\/homeAddress/);
257
+ });
258
+ test("allows definitions references when wrapping", () => {
259
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
260
+ type: "object",
261
+ nullable: true,
262
+ definitions: { Code: { type: "string" } },
263
+ properties: {
264
+ code: { ref: "#/definitions/Code" },
265
+ },
266
+ })).not.toThrow();
267
+ });
268
+ test("does not treat references inside literal values as broken", () => {
269
+ // The default value is data. A "ref" inside it is not a schema reference
270
+ // and must not fail the conversion.
271
+ const schema = convertJsonSchemaNullableToOneOfDeep({
272
+ type: "object",
273
+ nullable: true,
274
+ properties: {
275
+ settings: {
276
+ type: "object",
277
+ default: { ref: "#/properties/code" },
278
+ },
279
+ },
280
+ });
281
+ expect(schema).toEqual({
282
+ oneOf: [
283
+ {
284
+ type: "object",
285
+ properties: {
286
+ settings: {
287
+ type: "object",
288
+ default: { ref: "#/properties/code" },
289
+ },
290
+ },
291
+ },
292
+ { type: "null" },
293
+ ],
294
+ });
295
+ });
296
+ test("throws when a sibling reference points inside a wrapped schema", () => {
297
+ // The reference target moves under oneOf[0] when address is wrapped,
298
+ // so the pointer would be left dangling
299
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
300
+ type: "object",
301
+ properties: {
302
+ address: {
303
+ type: "object",
304
+ nullable: true,
305
+ properties: { code: { type: "string" } },
306
+ },
307
+ billingCode: { ref: "#/properties/address/properties/code" },
308
+ },
309
+ })).toThrow(/#\/properties\/address\/properties\/code/);
310
+ });
311
+ test("throws when a definitions reference points inside a wrapped schema", () => {
312
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
313
+ type: "object",
314
+ definitions: {
315
+ Shortcut: { ref: "#/properties/address/properties/code" },
316
+ },
317
+ properties: {
318
+ address: {
319
+ type: "object",
320
+ nullable: true,
321
+ properties: { code: { type: "string" } },
322
+ },
323
+ link: { ref: "#/definitions/Shortcut" },
324
+ },
325
+ })).toThrow(/#\/properties\/address\/properties\/code/);
326
+ });
327
+ test("allows references whose target does not move", () => {
328
+ // address is wrapped, but the reference points to plain, which stays put
329
+ const schema = convertJsonSchemaNullableToOneOfDeep({
330
+ type: "object",
331
+ properties: {
332
+ plain: { type: "string" },
333
+ address: { type: "object", nullable: true },
334
+ copy: { ref: "#/properties/plain" },
335
+ },
336
+ });
337
+ expect(schema).toEqual({
338
+ type: "object",
339
+ properties: {
340
+ plain: { type: "string" },
341
+ address: { oneOf: [{ type: "object" }, { type: "null" }] },
342
+ copy: { ref: "#/properties/plain" },
343
+ },
344
+ });
345
+ });
346
+ test("accepts percent-encoded references", () => {
347
+ // "#/definitions/Postal%20Code" is a valid URI fragment pointer to
348
+ // a definition named "Postal Code"
349
+ const schema = {
350
+ type: "object",
351
+ definitions: {
352
+ "Postal Code": { type: "string" },
353
+ },
354
+ properties: {
355
+ code: { ref: "#/definitions/Postal%20Code" },
356
+ name: { type: "string", nullable: true },
357
+ },
358
+ };
359
+ expect(() => convertJsonSchemaNullableToOneOfDeep(schema)).not.toThrow();
360
+ });
361
+ test("rejects an array index with a leading zero", () => {
362
+ // "01" is not a valid JSON Pointer array index, so the reference
363
+ // cannot be resolved even though Number("01") is 1
364
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
365
+ type: "object",
366
+ properties: {
367
+ choice: { anyOf: [{ type: "string" }, { type: "number" }] },
368
+ copy: { ref: "#/properties/choice/anyOf/01" },
369
+ name: { type: "string", nullable: true },
370
+ },
371
+ })).toThrow(/#\/properties\/choice\/anyOf\/01/);
372
+ });
373
+ test("rejects references to inherited object properties", () => {
374
+ // toString exists on Object.prototype but not in the JSON document
375
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
376
+ type: "object",
377
+ definitions: {},
378
+ properties: {
379
+ bad: { ref: "#/definitions/toString" },
380
+ name: { type: "string", nullable: true },
381
+ },
382
+ })).toThrow(/#\/definitions\/toString/);
383
+ });
384
+ test("treats an encoded slash as a separator per RFC 6901", () => {
385
+ // RFC 6901 section 6: the whole fragment is percent-decoded first and
386
+ // then tokenized, so %2F becomes a separator. A slash inside a key must
387
+ // be escaped as ~1 instead.
388
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
389
+ type: "object",
390
+ definitions: {
391
+ "a/b": { type: "string" },
392
+ },
393
+ properties: {
394
+ bad: { ref: "#/definitions/a%2Fb" },
395
+ name: { type: "string", nullable: true },
396
+ },
397
+ })).toThrow(/#\/definitions\/a%2Fb/);
398
+ });
399
+ test("resolves a slash in a key escaped as ~1", () => {
400
+ expect(() => convertJsonSchemaNullableToOneOfDeep({
401
+ type: "object",
402
+ definitions: {
403
+ "a/b": { type: "string" },
404
+ },
405
+ properties: {
406
+ good: { ref: "#/definitions/a~1b" },
407
+ name: { type: "string", nullable: true },
408
+ },
409
+ })).not.toThrow();
410
+ });
411
+ test("creates an API Gateway schema from Zod", () => {
412
+ const schema = toApiGatewayJsonSchema(z.object({
413
+ reason: z.string().nullable(),
414
+ timestamp: z.iso.datetime(),
415
+ }));
416
+ expect(schema).toMatchObject({
417
+ type: "object",
418
+ properties: {
419
+ reason: {
420
+ oneOf: [{ type: "string" }, { type: "null" }],
421
+ },
422
+ timestamp: { type: "string", format: "date-time" },
423
+ },
424
+ });
425
+ expect(schema).not.toHaveProperty("properties.timestamp.pattern");
426
+ });
427
+ test("keeps a property named pattern but removes the pattern keyword", () => {
428
+ const schema = toApiGatewayJsonSchema(z.object({
429
+ // a field that happens to be named "pattern"
430
+ pattern: z.string().regex(/^[a-z]+$/),
431
+ }));
432
+ expect(schema).toMatchObject({
433
+ type: "object",
434
+ properties: {
435
+ pattern: { type: "string" },
436
+ },
437
+ required: ["pattern"],
438
+ });
439
+ // the regex keyword itself must not reach API Gateway
440
+ expect(schema).not.toHaveProperty("properties.pattern.pattern");
441
+ });
442
+ });
443
+ //# sourceMappingURL=api-model.test.js.map
@@ -59,17 +59,12 @@ export function createKyHooks(httpLogger) {
59
59
  },
60
60
  ],
61
61
  afterResponse: [
62
- async (state) => {
63
- const contentLengthFromHeader = parseContentLengthFromHeader(state.response.headers.get("content-length"));
64
- // use header when available to determine content length
65
- if (contentLengthFromHeader !== undefined) {
66
- httpLogger.logResponse(state.response.status, contentLengthFromHeader);
67
- return state.response;
68
- }
69
- // create clone from the response, so we can read its body without affecting the original response
70
- const resp = state.response.clone();
71
- const contentLength = (await resp.bytes()).length;
72
- httpLogger.logResponse(resp.status, contentLength);
62
+ (state) => {
63
+ // Content length is taken from the header only. When the header is
64
+ // missing, for example with chunked responses, the length is left
65
+ // unknown: reading the body here would buffer the whole payload in
66
+ // memory and block streaming consumers until EOF.
67
+ httpLogger.logResponse(state.response.status, parseContentLengthFromHeader(state.response.headers.get("content-length")));
73
68
  return state.response;
74
69
  },
75
70
  ],
@@ -1,6 +1,73 @@
1
1
  import type { JsonSchema, Model, RequestValidator, RestApi } from "aws-cdk-lib/aws-apigateway";
2
+ import type { ZodType } from "zod";
2
3
  import type { ModelWithReference } from "../aws/types/model-with-reference.js";
3
4
  type ModelReferenceUrl = `https://apigateway.amazonaws.com/restapis/${string}/models/${string}`;
5
+ type JsonSchemaWithNullable = JsonSchema & {
6
+ nullable?: boolean;
7
+ };
8
+ /**
9
+ * Converts nullable fields in an OpenAPI 3.0 JSON Schema to a form accepted by
10
+ * API Gateway model schemas.
11
+ *
12
+ * API Gateway rejects the OpenAPI 3.0 `nullable` keyword. Importing a model
13
+ * with it fails with errors such as "ArrayNode cannot be cast to TextNode".
14
+ * This input is not accepted:
15
+ *
16
+ * ```json
17
+ * { "type": "string", "nullable": true }
18
+ * ```
19
+ *
20
+ * This function removes `nullable` and expresses null as an alternative,
21
+ * which API Gateway accepts:
22
+ *
23
+ * ```json
24
+ * { "oneOf": [{ "type": "string" }, { "type": "null" }] }
25
+ * ```
26
+ *
27
+ * If the nullable schema is already an `anyOf` union, the null alternative is
28
+ * added to it. If it has no `type` at all (for example `allOf` or a plain
29
+ * reference), the whole schema is wrapped in an `anyOf` so that null stays
30
+ * allowed. The conversion is applied recursively to nested schemas. Field
31
+ * names and literal values such as defaults are left untouched.
32
+ *
33
+ * Limitation: wrapping moves schema content under oneOf/anyOf, which can
34
+ * break local references such as `#/properties/...` pointing at the old
35
+ * location. After conversion every local reference is checked against the
36
+ * result, and an error is thrown instead of producing a model with dangling
37
+ * references. References to `#/definitions/...` targets stay valid because
38
+ * definitions are kept at the root. Zod output never contains such
39
+ * references, so this only matters for hand-written schemas.
40
+ */
41
+ export declare function convertJsonSchemaNullableToOneOfDeep(schema: JsonSchemaWithNullable): JsonSchemaWithNullable;
42
+ /**
43
+ * Creates a JSON Schema that can be used as an API Gateway model from a Zod schema.
44
+ *
45
+ * API Gateway does not accept Zod's default nullable output or regex patterns in
46
+ * model schemas. This helper keeps nullable values as `oneOf` alternatives and
47
+ * removes the `pattern` keyword that API Gateway cannot import. Field names and
48
+ * literal values are not touched, so a field may safely be named for example
49
+ * "pattern" or "nullable".
50
+ *
51
+ * For example, this Zod schema:
52
+ *
53
+ * ```ts
54
+ * z.object({ reason: z.string().nullable() });
55
+ * ```
56
+ *
57
+ * becomes this API Gateway schema:
58
+ *
59
+ * ```json
60
+ * {
61
+ * "type": "object",
62
+ * "properties": {
63
+ * "reason": {
64
+ * "oneOf": [{ "type": "string" }, { "type": "null" }]
65
+ * }
66
+ * }
67
+ * }
68
+ * ```
69
+ */
70
+ export declare function toApiGatewayJsonSchema(schema: ZodType): JsonSchema;
4
71
  /**
5
72
  * Get a reference to an OpenAPI model object in a REST API.
6
73
  * Can be used to supply a reference to properties of a GeoJSON feature.
@@ -1,4 +1,295 @@
1
1
  import { JsonSchemaType, JsonSchemaVersion } from "aws-cdk-lib/aws-apigateway";
2
+ import { toJSONSchema } from "zod";
3
+ function isObject(value) {
4
+ return typeof value === "object" && value !== null && !Array.isArray(value);
5
+ }
6
+ // Keywords whose value is a map from a name to a schema. The names are data
7
+ // (for example field names) and must not be changed, only the schema values.
8
+ // A dependencies value can also be a string array, which is left unchanged.
9
+ const SCHEMA_MAP_KEYWORDS = [
10
+ "properties",
11
+ "patternProperties",
12
+ "definitions",
13
+ "dependencies",
14
+ ];
15
+ // Keywords whose value is a list of schemas.
16
+ const SCHEMA_LIST_KEYWORDS = ["oneOf", "anyOf", "allOf"];
17
+ // Keywords whose value is a single schema.
18
+ const SCHEMA_KEYWORDS = [
19
+ "items",
20
+ "additionalProperties",
21
+ "additionalItems",
22
+ "contains",
23
+ "propertyNames",
24
+ "not",
25
+ ];
26
+ /**
27
+ * Walks a JSON Schema and applies the transform to every schema object,
28
+ * starting from the innermost ones. Only values of known schema keywords are
29
+ * treated as schemas. Everything else, such as field names in `properties`
30
+ * and literal values like `default`, is left untouched.
31
+ */
32
+ function transformSchemaDeep(schema, transform) {
33
+ if (!isObject(schema)) {
34
+ return schema;
35
+ }
36
+ const result = {};
37
+ for (const [key, value] of Object.entries(schema)) {
38
+ if (SCHEMA_MAP_KEYWORDS.includes(key) && isObject(value)) {
39
+ result[key] = Object.fromEntries(Object.entries(value).map(([name, subSchema]) => [
40
+ name,
41
+ transformSchemaDeep(subSchema, transform),
42
+ ]));
43
+ }
44
+ else if (SCHEMA_LIST_KEYWORDS.includes(key) && Array.isArray(value)) {
45
+ result[key] = value.map((item) => transformSchemaDeep(item, transform));
46
+ }
47
+ else if (key === "items" && Array.isArray(value)) {
48
+ result[key] = value.map((item) => transformSchemaDeep(item, transform));
49
+ }
50
+ else if (SCHEMA_KEYWORDS.includes(key) && isObject(value)) {
51
+ result[key] = transformSchemaDeep(value, transform);
52
+ }
53
+ else {
54
+ result[key] = value;
55
+ }
56
+ }
57
+ return transform(result);
58
+ }
59
+ /**
60
+ * Collects all local reference values ("#/...") from a schema. Walks only
61
+ * known schema keywords, so references inside literal values such as defaults
62
+ * or enums are not collected. Both the CDK property name "ref" and the raw
63
+ * JSON Schema keyword "$ref" are checked.
64
+ */
65
+ function findLocalReferences(schema) {
66
+ if (!isObject(schema)) {
67
+ return [];
68
+ }
69
+ const references = [];
70
+ for (const [key, value] of Object.entries(schema)) {
71
+ if ((key === "ref" || key === "$ref") &&
72
+ typeof value === "string" &&
73
+ value.startsWith("#/")) {
74
+ references.push(value);
75
+ }
76
+ else if (SCHEMA_MAP_KEYWORDS.includes(key) && isObject(value)) {
77
+ for (const subSchema of Object.values(value)) {
78
+ references.push(...findLocalReferences(subSchema));
79
+ }
80
+ }
81
+ else if ((SCHEMA_LIST_KEYWORDS.includes(key) || key === "items") &&
82
+ Array.isArray(value)) {
83
+ for (const item of value) {
84
+ references.push(...findLocalReferences(item));
85
+ }
86
+ }
87
+ else if (SCHEMA_KEYWORDS.includes(key) && isObject(value)) {
88
+ references.push(...findLocalReferences(value));
89
+ }
90
+ }
91
+ return references;
92
+ }
93
+ /**
94
+ * Checks whether a local JSON Pointer such as "#/definitions/Code" resolves
95
+ * to a value in the document. The pointer is a URI fragment: per RFC 6901
96
+ * section 6 the whole fragment is percent-decoded first and then tokenized,
97
+ * so an encoded slash (%2F) is a separator. A slash inside a key must be
98
+ * escaped as ~1.
99
+ */
100
+ function resolvesInDocument(root, pointer) {
101
+ let decoded;
102
+ try {
103
+ decoded = decodeURIComponent(pointer.slice(1));
104
+ }
105
+ catch {
106
+ // malformed percent-encoding cannot resolve
107
+ return false;
108
+ }
109
+ const parts = decoded
110
+ .slice(1)
111
+ .split("/")
112
+ .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
113
+ let current = root;
114
+ for (const part of parts) {
115
+ if (Array.isArray(current)) {
116
+ // RFC 6901: an array index is "0" or digits without a leading zero
117
+ if (!/^(0|[1-9][0-9]*)$/.test(part)) {
118
+ return false;
119
+ }
120
+ const index = Number(part);
121
+ if (index >= current.length) {
122
+ return false;
123
+ }
124
+ current = current[index];
125
+ }
126
+ else if (isObject(current)) {
127
+ // own property only: inherited ones such as toString are not
128
+ // members of the JSON document
129
+ if (!Object.hasOwn(current, part)) {
130
+ return false;
131
+ }
132
+ current = current[part];
133
+ }
134
+ else {
135
+ return false;
136
+ }
137
+ }
138
+ return true;
139
+ }
140
+ /**
141
+ * Throws if the converted schema contains local references that no longer
142
+ * resolve. Wrapping nullable schemas moves their content under oneOf/anyOf,
143
+ * which can leave references pointing at the old location. Failing at synth
144
+ * time is safer than deploying a model with dangling references.
145
+ *
146
+ * This is an existence check only. In the unlikely case that a reference
147
+ * path stays occupied but its content changes, for example "#/oneOf/1"
148
+ * pointing at a union that gets a null alternative inserted, the change is
149
+ * not detected. Do not reference union alternatives by index.
150
+ */
151
+ function assertLocalReferencesResolve(schema) {
152
+ const broken = findLocalReferences(schema).filter((reference) => !resolvesInDocument(schema, reference));
153
+ if (broken.length > 0) {
154
+ throw new Error(`Converting nullable schemas broke local references: ${broken.join(", ")}. Restructure the schema, for example move the referenced schema to definitions.`);
155
+ }
156
+ }
157
+ /**
158
+ * Wraps a schema and a null alternative into a union. Definitions are kept at
159
+ * the root, otherwise local references like "#/definitions/X" would point to
160
+ * nothing after wrapping.
161
+ */
162
+ function wrapSchemaWithNull(schema, unionKeyword) {
163
+ const { definitions, ...rest } = schema;
164
+ const wrapped = {
165
+ [unionKeyword]: [rest, { type: "null" }],
166
+ };
167
+ if (definitions !== undefined) {
168
+ // biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
169
+ wrapped["definitions"] = definitions;
170
+ }
171
+ return wrapped;
172
+ }
173
+ /**
174
+ * Converts one schema object with `nullable: true` to a form that accepts null.
175
+ */
176
+ function convertNullableSchema(schema) {
177
+ if (!("nullable" in schema)) {
178
+ return schema;
179
+ }
180
+ // The nullable keyword is always removed because API Gateway rejects it.
181
+ // A null alternative is added only when the value was true.
182
+ const { nullable, ...rest } = schema;
183
+ if (nullable !== true) {
184
+ return rest;
185
+ }
186
+ // A simple typed schema cannot overlap with null, so oneOf is safe.
187
+ // biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
188
+ if (typeof rest["type"] === "string") {
189
+ return wrapSchemaWithNull(rest, "oneOf");
190
+ }
191
+ // A standalone anyOf can take null as one more alternative. This is only
192
+ // safe when anyOf is the sole keyword: sibling keywords such as enum apply
193
+ // to the whole schema and would still reject null.
194
+ // biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
195
+ const anyOf = rest["anyOf"];
196
+ if (Array.isArray(anyOf) && Object.keys(rest).length === 1) {
197
+ const hasNull = anyOf.some(
198
+ // biome-ignore lint/complexity/useLiteralKeys: index signature requires bracket notation
199
+ (item) => isObject(item) && item["type"] === "null");
200
+ return hasNull ? rest : { anyOf: [...anyOf, { type: "null" }] };
201
+ }
202
+ // Everything else: oneOf, allOf, references or an empty schema. Wrap in
203
+ // anyOf instead of oneOf, because the schema itself may also accept null
204
+ // and oneOf would then reject it (oneOf requires exactly one match).
205
+ return wrapSchemaWithNull(rest, "anyOf");
206
+ }
207
+ /**
208
+ * Removes the `pattern` keyword from one schema object. Field names that
209
+ * happen to be called "pattern" live inside `properties` and are not touched.
210
+ */
211
+ function removePatternKeyword(schema) {
212
+ if (!("pattern" in schema)) {
213
+ return schema;
214
+ }
215
+ const { pattern: _pattern, ...rest } = schema;
216
+ return rest;
217
+ }
218
+ /**
219
+ * Converts nullable fields in an OpenAPI 3.0 JSON Schema to a form accepted by
220
+ * API Gateway model schemas.
221
+ *
222
+ * API Gateway rejects the OpenAPI 3.0 `nullable` keyword. Importing a model
223
+ * with it fails with errors such as "ArrayNode cannot be cast to TextNode".
224
+ * This input is not accepted:
225
+ *
226
+ * ```json
227
+ * { "type": "string", "nullable": true }
228
+ * ```
229
+ *
230
+ * This function removes `nullable` and expresses null as an alternative,
231
+ * which API Gateway accepts:
232
+ *
233
+ * ```json
234
+ * { "oneOf": [{ "type": "string" }, { "type": "null" }] }
235
+ * ```
236
+ *
237
+ * If the nullable schema is already an `anyOf` union, the null alternative is
238
+ * added to it. If it has no `type` at all (for example `allOf` or a plain
239
+ * reference), the whole schema is wrapped in an `anyOf` so that null stays
240
+ * allowed. The conversion is applied recursively to nested schemas. Field
241
+ * names and literal values such as defaults are left untouched.
242
+ *
243
+ * Limitation: wrapping moves schema content under oneOf/anyOf, which can
244
+ * break local references such as `#/properties/...` pointing at the old
245
+ * location. After conversion every local reference is checked against the
246
+ * result, and an error is thrown instead of producing a model with dangling
247
+ * references. References to `#/definitions/...` targets stay valid because
248
+ * definitions are kept at the root. Zod output never contains such
249
+ * references, so this only matters for hand-written schemas.
250
+ */
251
+ export function convertJsonSchemaNullableToOneOfDeep(schema) {
252
+ const converted = transformSchemaDeep(schema, convertNullableSchema);
253
+ assertLocalReferencesResolve(converted);
254
+ return converted;
255
+ }
256
+ /**
257
+ * Creates a JSON Schema that can be used as an API Gateway model from a Zod schema.
258
+ *
259
+ * API Gateway does not accept Zod's default nullable output or regex patterns in
260
+ * model schemas. This helper keeps nullable values as `oneOf` alternatives and
261
+ * removes the `pattern` keyword that API Gateway cannot import. Field names and
262
+ * literal values are not touched, so a field may safely be named for example
263
+ * "pattern" or "nullable".
264
+ *
265
+ * For example, this Zod schema:
266
+ *
267
+ * ```ts
268
+ * z.object({ reason: z.string().nullable() });
269
+ * ```
270
+ *
271
+ * becomes this API Gateway schema:
272
+ *
273
+ * ```json
274
+ * {
275
+ * "type": "object",
276
+ * "properties": {
277
+ * "reason": {
278
+ * "oneOf": [{ "type": "string" }, { "type": "null" }]
279
+ * }
280
+ * }
281
+ * }
282
+ * ```
283
+ */
284
+ export function toApiGatewayJsonSchema(schema) {
285
+ const jsonSchema = toJSONSchema(schema, {
286
+ target: "openapi-3.0",
287
+ unrepresentable: "any",
288
+ });
289
+ const converted = transformSchemaDeep(jsonSchema, (schemaObject) => convertNullableSchema(removePatternKeyword(schemaObject)));
290
+ assertLocalReferencesResolve(converted);
291
+ return converted;
292
+ }
2
293
  /**
3
294
  * Get a reference to an OpenAPI model object in a REST API.
4
295
  * Can be used to supply a reference to properties of a GeoJSON feature.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@digitraffic/common",
3
- "version": "2026.10.30-1",
3
+ "version": "2026.11.2-1",
4
4
  "private": false,
5
5
  "description": "",
6
6
  "repository": {
@@ -149,7 +149,7 @@
149
149
  "undici": "8.12.2",
150
150
  "velocityjs": "2.1.7",
151
151
  "vitest": "4.1.12",
152
- "zod": "4.4.3"
152
+ "zod": "4.6.7"
153
153
  },
154
154
  "peerDependencies": {
155
155
  "@aws-sdk/client-api-gateway": "3.1098.0",
@@ -169,7 +169,7 @@
169
169
  "pg-native": "3.8.0",
170
170
  "pg-promise": "12.7.0",
171
171
  "undici": "8.12.2",
172
- "zod": "4.4.3"
172
+ "zod": "4.6.7"
173
173
  },
174
174
  "engines": {
175
175
  "node": ">=24 <25"