@ai-sdk/provider-utils 4.0.5 → 4.0.6

package/src/to-json-schema/zod3-to-json-schema/parse-def.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod/v3';
+import { parseDef } from './parse-def';
+import { getRefs } from './refs';
+import { JSONSchema7 } from '@ai-sdk/provider';
+
+describe('parseDef', () => {
+  it('should return a proper json schema with some common types without validation', () => {
+    const zodSchema = z.object({
+      requiredString: z.string(),
+      optionalString: z.string().optional(),
+      literalString: z.literal('literalStringValue'),
+      stringArray: z.array(z.string()),
+      stringEnum: z.enum(['stringEnumOptionA', 'stringEnumOptionB']),
+      tuple: z.tuple([z.string(), z.number(), z.boolean()]),
+      record: z.record(z.boolean()),
+      requiredNumber: z.number(),
+      optionalNumber: z.number().optional(),
+      numberOrNull: z.number().nullable(),
+      numberUnion: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+      mixedUnion: z.union([
+        z.literal('abc'),
+        z.literal(123),
+        z.object({ nowItGetsAnnoying: z.literal(true) }),
+      ]),
+      objectOrNull: z.object({ myString: z.string() }).nullable(),
+      passthrough: z.object({ myString: z.string() }).passthrough(),
+    });
+
+    const parsedSchema = parseDef(zodSchema._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'object',
+      properties: {
+        requiredString: {
+          type: 'string',
+        },
+        optionalString: {
+          type: 'string',
+        },
+        literalString: {
+          type: 'string',
+          const: 'literalStringValue',
+        },
+        stringArray: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+        },
+        stringEnum: {
+          type: 'string',
+          enum: ['stringEnumOptionA', 'stringEnumOptionB'],
+        },
+        tuple: {
+          type: 'array',
+          minItems: 3,
+          items: [
+            {
+              type: 'string',
+            },
+            {
+              type: 'number',
+            },
+            {
+              type: 'boolean',
+            },
+          ],
+          maxItems: 3,
+        },
+        record: {
+          type: 'object',
+          additionalProperties: {
+            type: 'boolean',
+          },
+        },
+        requiredNumber: {
+          type: 'number',
+        },
+        optionalNumber: {
+          type: 'number',
+        },
+        numberOrNull: {
+          type: ['number', 'null'],
+        },
+        numberUnion: {
+          type: 'number',
+          enum: [1, 2, 3],
+        },
+        mixedUnion: {
+          anyOf: [
+            {
+              type: 'string',
+              const: 'abc',
+            },
+            {
+              type: 'number',
+              const: 123,
+            },
+            {
+              type: 'object',
+              properties: {
+                nowItGetsAnnoying: {
+                  type: 'boolean',
+                  const: true,
+                },
+              },
+              required: ['nowItGetsAnnoying'],
+              additionalProperties: false,
+            },
+          ],
+        },
+        objectOrNull: {
+          anyOf: [
+            {
+              type: 'object',
+              properties: {
+                myString: {
+                  type: 'string',
+                },
+              },
+              required: ['myString'],
+              additionalProperties: false,
+            },
+            {
+              type: 'null',
+            },
+          ],
+        },
+        passthrough: {
+          type: 'object',
+          properties: {
+            myString: {
+              type: 'string',
+            },
+          },
+          required: ['myString'],
+          additionalProperties: true,
+        },
+      },
+      required: [
+        'requiredString',
+        'literalString',
+        'stringArray',
+        'stringEnum',
+        'tuple',
+        'record',
+        'requiredNumber',
+        'numberOrNull',
+        'numberUnion',
+        'mixedUnion',
+        'objectOrNull',
+        'passthrough',
+      ],
+      additionalProperties: false,
+    } satisfies JSONSchema7);
+  });
+
+  it('should handle a nullable string properly', () => {
+    const shorthand = z.string().nullable();
+    const union = z.union([z.string(), z.null()]);
+
+    expect(parseDef(shorthand._def, getRefs())).toStrictEqual({
+      type: ['string', 'null'],
+    } satisfies JSONSchema7);
+    expect(parseDef(union._def, getRefs())).toStrictEqual({
+      type: ['string', 'null'],
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to use branded string', () => {
+    const schema = z.string().brand<'x'>();
+    const parsedSchema = parseDef(schema._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'string',
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to use readonly', () => {
+    const parsedSchema = parseDef(z.object({}).readonly()._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to use catch', () => {
+    const parsedSchema = parseDef(z.number().catch(5)._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'number',
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to use pipeline', () => {
+    const schema = z.number().pipe(z.number().int());
+
+    expect(parseDef(schema._def, getRefs())).toStrictEqual({
+      allOf: [{ type: 'number' }, { type: 'integer' }],
+    } satisfies JSONSchema7);
+  });
+
+  it('should get undefined for function', () => {
+    const parsedSchema = parseDef(z.function()._def, getRefs());
+    expect(parsedSchema).toBeUndefined();
+  });
+
+  it('should get undefined for void', () => {
+    const parsedSchema = parseDef(z.void()._def, getRefs());
+    expect(parsedSchema).toBeUndefined();
+  });
+
+  it('nested lazy', () => {
+    const zodSchema = z.lazy(() => z.lazy(() => z.string()));
+    const parsed = parseDef(zodSchema._def, getRefs());
+
+    expect(parsed).toStrictEqual({
+      type: 'string',
+    } satisfies JSONSchema7);
+  });
+});

package/src/to-json-schema/zod3-to-json-schema/parse-def.ts

@@ -0,0 +1,109 @@
+import { ZodTypeDef } from 'zod/v3';
+import { Refs, Seen } from './refs';
+import { ignoreOverride } from './options';
+import { JsonSchema7Type } from './parse-types';
+import { selectParser } from './select-parser';
+import { getRelativePath } from './get-relative-path';
+import { parseAnyDef } from './parsers/any';
+
+export function parseDef(
+  def: ZodTypeDef,
+  refs: Refs,
+  forceResolution = false, // Forces a new schema to be instantiated even though its def has been seen. Used for improving refs in definitions. See https://github.com/StefanTerdell/zod-to-json-schema/pull/61.
+): JsonSchema7Type | undefined {
+  const seenItem = refs.seen.get(def);
+
+  if (refs.override) {
+    const overrideResult = refs.override?.(
+      def,
+      refs,
+      seenItem,
+      forceResolution,
+    );
+
+    if (overrideResult !== ignoreOverride) {
+      return overrideResult;
+    }
+  }
+
+  if (seenItem && !forceResolution) {
+    const seenSchema = get$ref(seenItem, refs);
+
+    if (seenSchema !== undefined) {
+      return seenSchema;
+    }
+  }
+
+  const newItem: Seen = { def, path: refs.currentPath, jsonSchema: undefined };
+
+  refs.seen.set(def, newItem);
+
+  const jsonSchemaOrGetter = selectParser(def, (def as any).typeName, refs);
+
+  // If the return was a function, then the inner definition needs to be extracted before a call to parseDef (recursive)
+  const jsonSchema =
+    typeof jsonSchemaOrGetter === 'function'
+      ? parseDef(jsonSchemaOrGetter(), refs)
+      : jsonSchemaOrGetter;
+
+  if (jsonSchema) {
+    addMeta(def, refs, jsonSchema);
+  }
+
+  if (refs.postProcess) {
+    const postProcessResult = refs.postProcess(jsonSchema, def, refs);
+
+    newItem.jsonSchema = jsonSchema;
+
+    return postProcessResult;
+  }
+
+  newItem.jsonSchema = jsonSchema;
+
+  return jsonSchema;
+}
+
+const get$ref = (
+  item: Seen,
+  refs: Refs,
+):
+  | {
+      $ref: string;
+    }
+  | {}
+  | undefined => {
+  switch (refs.$refStrategy) {
+    case 'root':
+      return { $ref: item.path.join('/') };
+    case 'relative':
+      return { $ref: getRelativePath(refs.currentPath, item.path) };
+    case 'none':
+    case 'seen': {
+      if (
+        item.path.length < refs.currentPath.length &&
+        item.path.every((value, index) => refs.currentPath[index] === value)
+      ) {
+        console.warn(
+          `Recursive reference detected at ${refs.currentPath.join(
+            '/',
+          )}! Defaulting to any`,
+        );
+
+        return parseAnyDef();
+      }
+
+      return refs.$refStrategy === 'seen' ? parseAnyDef() : undefined;
+    }
+  }
+};
+
+const addMeta = (
+  def: ZodTypeDef,
+  refs: Refs,
+  jsonSchema: JsonSchema7Type,
+): JsonSchema7Type => {
+  if (def.description) {
+    jsonSchema.description = def.description;
+  }
+  return jsonSchema;
+};

package/src/to-json-schema/zod3-to-json-schema/parse-types.ts

@@ -0,0 +1,57 @@
+import { JsonSchema7AnyType } from './parsers/any';
+import { JsonSchema7ArrayType } from './parsers/array';
+import { JsonSchema7BigintType } from './parsers/bigint';
+import { JsonSchema7BooleanType } from './parsers/boolean';
+import { JsonSchema7DateType } from './parsers/date';
+import { JsonSchema7EnumType } from './parsers/enum';
+import { JsonSchema7AllOfType } from './parsers/intersection';
+import { JsonSchema7LiteralType } from './parsers/literal';
+import { JsonSchema7MapType } from './parsers/map';
+import { JsonSchema7NativeEnumType } from './parsers/native-enum';
+import { JsonSchema7NeverType } from './parsers/never';
+import { JsonSchema7NullType } from './parsers/null';
+import { JsonSchema7NullableType } from './parsers/nullable';
+import { JsonSchema7NumberType } from './parsers/number';
+import { JsonSchema7ObjectType } from './parsers/object';
+import { JsonSchema7RecordType } from './parsers/record';
+import { JsonSchema7SetType } from './parsers/set';
+import { JsonSchema7StringType } from './parsers/string';
+import { JsonSchema7TupleType } from './parsers/tuple';
+import { JsonSchema7UndefinedType } from './parsers/undefined';
+import { JsonSchema7UnionType } from './parsers/union';
+import { JsonSchema7UnknownType } from './parsers/unknown';
+
+type JsonSchema7RefType = { $ref: string };
+type JsonSchema7Meta = {
+  title?: string;
+  default?: any;
+  description?: string;
+};
+
+export type JsonSchema7TypeUnion =
+  | JsonSchema7StringType
+  | JsonSchema7ArrayType
+  | JsonSchema7NumberType
+  | JsonSchema7BigintType
+  | JsonSchema7BooleanType
+  | JsonSchema7DateType
+  | JsonSchema7EnumType
+  | JsonSchema7LiteralType
+  | JsonSchema7NativeEnumType
+  | JsonSchema7NullType
+  | JsonSchema7NumberType
+  | JsonSchema7ObjectType
+  | JsonSchema7RecordType
+  | JsonSchema7TupleType
+  | JsonSchema7UnionType
+  | JsonSchema7UndefinedType
+  | JsonSchema7RefType
+  | JsonSchema7NeverType
+  | JsonSchema7MapType
+  | JsonSchema7AnyType
+  | JsonSchema7NullableType
+  | JsonSchema7AllOfType
+  | JsonSchema7UnknownType
+  | JsonSchema7SetType;
+
+export type JsonSchema7Type = JsonSchema7TypeUnion & JsonSchema7Meta;

package/src/to-json-schema/zod3-to-json-schema/parsers/any.ts

@@ -0,0 +1,5 @@
+export type JsonSchema7AnyType = { $ref?: string };
+
+export function parseAnyDef(): JsonSchema7AnyType {
+  return {};
+}

package/src/to-json-schema/zod3-to-json-schema/parsers/array.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import { JSONSchema7 } from '@ai-sdk/provider';
+import { z } from 'zod/v3';
+import { parseArrayDef } from './array';
+import { getRefs } from '../refs';
+
+describe('array', () => {
+  it('should be possible to describe a simple array', () => {
+    const parsedSchema = parseArrayDef(z.array(z.string())._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to describe a simple array with any item', () => {
+    const parsedSchema = parseArrayDef(z.array(z.any())._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'array',
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to describe a string array with a minimum and maximum length', () => {
+    const parsedSchema = parseArrayDef(
+      z.array(z.string()).min(2).max(4)._def,
+      getRefs(),
+    );
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      minItems: 2,
+      maxItems: 4,
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to describe a string array with an exact length', () => {
+    const parsedSchema = parseArrayDef(
+      z.array(z.string()).length(5)._def,
+      getRefs(),
+    );
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      minItems: 5,
+      maxItems: 5,
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to describe a string array with a minimum length of 1 by using nonempty', () => {
+    const parsedSchema = parseArrayDef(
+      z.array(z.any()).nonempty()._def,
+      getRefs(),
+    );
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'array',
+      minItems: 1,
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible do properly reference array items', () => {
+    const willHaveBeenSeen = z.object({ hello: z.string() });
+    const unionSchema = z.union([willHaveBeenSeen, willHaveBeenSeen]);
+    const arraySchema = z.array(unionSchema);
+    const jsonSchema = parseArrayDef(arraySchema._def, getRefs());
+
+    expect(jsonSchema).toStrictEqual({
+      items: {
+        anyOf: [
+          {
+            additionalProperties: false,
+            properties: {
+              hello: {
+                type: 'string',
+              },
+            },
+            required: ['hello'],
+            type: 'object',
+          },
+          {
+            $ref: '#/items/anyOf/0',
+          },
+        ],
+      },
+      type: 'array',
+    } satisfies JSONSchema7);
+  });
+});

package/src/to-json-schema/zod3-to-json-schema/parsers/array.ts

@@ -0,0 +1,38 @@
+import { ZodArrayDef, ZodFirstPartyTypeKind } from 'zod/v3';
+import { parseDef } from '../parse-def';
+import { JsonSchema7Type } from '../parse-types';
+import { Refs } from '../refs';
+
+export type JsonSchema7ArrayType = {
+  type: 'array';
+  items?: JsonSchema7Type;
+  minItems?: number;
+  maxItems?: number;
+};
+
+export function parseArrayDef(def: ZodArrayDef, refs: Refs) {
+  const res: JsonSchema7ArrayType = {
+    type: 'array',
+  };
+  if (
+    def.type?._def &&
+    def.type?._def?.typeName !== ZodFirstPartyTypeKind.ZodAny
+  ) {
+    res.items = parseDef(def.type._def, {
+      ...refs,
+      currentPath: [...refs.currentPath, 'items'],
+    });
+  }
+
+  if (def.minLength) {
+    res.minItems = def.minLength.value;
+  }
+  if (def.maxLength) {
+    res.maxItems = def.maxLength.value;
+  }
+  if (def.exactLength) {
+    res.minItems = def.exactLength.value;
+    res.maxItems = def.exactLength.value;
+  }
+  return res;
+}

package/src/to-json-schema/zod3-to-json-schema/parsers/bigint.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { JSONSchema7 } from '@ai-sdk/provider';
+import { z } from 'zod/v3';
+import { parseBigintDef } from './bigint';
+
+describe('bigint', () => {
+  it('should be possible to use bigint', () => {
+    const parsedSchema = parseBigintDef(z.bigint()._def);
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'integer',
+      format: 'int64',
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to define gt/lt', () => {
+    const parsedSchema = parseBigintDef(
+      z.bigint().gte(BigInt(10)).lte(BigInt(20))._def,
+    );
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'integer',
+      format: 'int64',
+      minimum: BigInt(10) as any, // json schema type does not support bigint
+      maximum: BigInt(20) as any, // json schema type does not support bigint
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to define gt/lt', () => {
+    const parsedSchema = parseBigintDef(
+      z.bigint().gt(BigInt(10)).lt(BigInt(20))._def,
+    );
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'integer',
+      format: 'int64',
+      exclusiveMinimum: BigInt(10) as any, // json schema type does not support bigint
+      exclusiveMaximum: BigInt(20) as any, // json schema type does not support bigint
+    } satisfies JSONSchema7);
+  });
+
+  it('should be possible to define multipleOf', () => {
+    const parsedSchema = parseBigintDef(z.bigint().multipleOf(BigInt(5))._def);
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'integer',
+      format: 'int64',
+      multipleOf: BigInt(5) as any, // json schema type does not support bigint
+    } satisfies JSONSchema7);
+  });
+});

package/src/to-json-schema/zod3-to-json-schema/parsers/bigint.ts

@@ -0,0 +1,44 @@
+import { ZodBigIntDef } from 'zod/v3';
+
+export type JsonSchema7BigintType = {
+  type: 'integer';
+  format: 'int64';
+  minimum?: BigInt;
+  exclusiveMinimum?: BigInt;
+  maximum?: BigInt;
+  exclusiveMaximum?: BigInt;
+  multipleOf?: BigInt;
+};
+
+export function parseBigintDef(def: ZodBigIntDef): JsonSchema7BigintType {
+  const res: JsonSchema7BigintType = {
+    type: 'integer',
+    format: 'int64',
+  };
+
+  if (!def.checks) return res;
+
+  for (const check of def.checks) {
+    switch (check.kind) {
+      case 'min':
+        if (check.inclusive) {
+          res.minimum = check.value;
+        } else {
+          res.exclusiveMinimum = check.value;
+        }
+        break;
+      case 'max':
+        if (check.inclusive) {
+          res.maximum = check.value;
+        } else {
+          res.exclusiveMaximum = check.value;
+        }
+
+        break;
+      case 'multipleOf':
+        res.multipleOf = check.value;
+        break;
+    }
+  }
+  return res;
+}

package/src/to-json-schema/zod3-to-json-schema/parsers/boolean.ts

@@ -0,0 +1,7 @@
+export type JsonSchema7BooleanType = {
+  type: 'boolean';
+};
+
+export function parseBooleanDef(): JsonSchema7BooleanType {
+  return { type: 'boolean' };
+}

package/src/to-json-schema/zod3-to-json-schema/parsers/branded.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod/v3';
+import { parseBrandedDef } from './branded';
+import { getRefs } from '../refs';
+import { JSONSchema7 } from '@ai-sdk/provider';
+
+describe('branded', () => {
+  it('should be possible to use branded string', () => {
+    const schema = z.string().brand<'x'>();
+    const parsedSchema = parseBrandedDef(schema._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'string',
+    } satisfies JSONSchema7);
+  });
+});

package/src/to-json-schema/zod3-to-json-schema/parsers/branded.ts

@@ -0,0 +1,7 @@
+import { ZodBrandedDef } from 'zod/v3';
+import { parseDef } from '../parse-def';
+import { Refs } from '../refs';
+
+export function parseBrandedDef(_def: ZodBrandedDef<any>, refs: Refs) {
+  return parseDef(_def.type._def, refs);
+}

package/src/to-json-schema/zod3-to-json-schema/parsers/catch.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod/v3';
+import { parseCatchDef } from './catch';
+import { getRefs } from '../refs';
+import { JSONSchema7 } from '@ai-sdk/provider';
+
+describe('catch', () => {
+  it('should be possible to use catch', () => {
+    const parsedSchema = parseCatchDef(z.number().catch(5)._def, getRefs());
+
+    expect(parsedSchema).toStrictEqual({
+      type: 'number',
+    } satisfies JSONSchema7);
+  });
+});

package/src/to-json-schema/zod3-to-json-schema/parsers/catch.ts

@@ -0,0 +1,7 @@
+import { ZodCatchDef } from 'zod/v3';
+import { parseDef } from '../parse-def';
+import { Refs } from '../refs';
+
+export const parseCatchDef = (def: ZodCatchDef<any>, refs: Refs) => {
+  return parseDef(def.innerType._def, refs);
+};