@mastra/schema-compat
Version:
Tool schema compatibility layer for Mastra.ai
315 lines • 12.7 kB
TypeScript
import { z, ZodOptional, ZodObject, ZodArray, ZodUnion, ZodString, ZodNumber, ZodDate, ZodDefault, ZodNull, ZodNullable, ZodIntersection } from 'zod/v3';
import type { ZodTypeAny } from 'zod/v3';
import type { Targets } from 'zod-to-json-schema';
import type { JSONSchema7, Schema } from './json-schema/index.js';
import type { SchemaCompatLayer as ParentSchemaCompatLayer } from './schema-compatibility.js';
import type { ModelInformation } from './types.js';
/**
* All supported string validation check types that can be processed or converted to descriptions.
* @constant
*/
export declare const ALL_STRING_CHECKS: readonly ["regex", "emoji", "email", "url", "uuid", "cuid", "min", "max"];
/**
* All supported number validation check types that can be processed or converted to descriptions.
* @constant
*/
export declare const ALL_NUMBER_CHECKS: readonly ["min", "max", "multipleOf"];
/**
* All supported array validation check types that can be processed or converted to descriptions.
* @constant
*/
export declare const ALL_ARRAY_CHECKS: readonly ["min", "max", "length"];
export declare const isOptional: (v: ZodTypeAny) => v is ZodOptional<any>;
export declare const isObj: (v: ZodTypeAny) => v is ZodObject<any, any, any>;
export declare const isNull: (v: ZodTypeAny) => v is ZodNull;
export declare const isNullable: (v: ZodTypeAny) => v is ZodNullable<any>;
export declare const isArr: (v: ZodTypeAny) => v is ZodArray<any, any>;
export declare const isUnion: (v: ZodTypeAny) => v is ZodUnion<[ZodTypeAny, ...ZodTypeAny[]]>;
export declare const isString: (v: ZodTypeAny) => v is ZodString;
export declare const isNumber: (v: ZodTypeAny) => v is ZodNumber;
export declare const isDate: (v: ZodTypeAny) => v is ZodDate;
export declare const isDefault: (v: ZodTypeAny) => v is ZodDefault<any>;
export declare const isIntersection: (v: ZodTypeAny) => v is ZodIntersection<any, any>;
/**
* Zod types that are not supported by most AI model providers and should be avoided.
* @constant
*/
export declare const UNSUPPORTED_ZOD_TYPES: readonly ["ZodIntersection", "ZodNever", "ZodNull", "ZodTuple", "ZodUndefined"];
/**
* Zod types that are generally supported by AI model providers.
* @constant
*/
export declare const SUPPORTED_ZOD_TYPES: readonly ["ZodObject", "ZodArray", "ZodUnion", "ZodString", "ZodNumber", "ZodDate", "ZodAny", "ZodDefault", "ZodNullable"];
/**
* All Zod types (both supported and unsupported).
* @constant
*/
export declare const ALL_ZOD_TYPES: readonly ["ZodObject", "ZodArray", "ZodUnion", "ZodString", "ZodNumber", "ZodDate", "ZodAny", "ZodDefault", "ZodNullable", "ZodIntersection", "ZodNever", "ZodNull", "ZodTuple", "ZodUndefined"];
/**
* Type representing string validation checks.
*/
export type StringCheckType = (typeof ALL_STRING_CHECKS)[number];
/**
* Type representing number validation checks.
*/
export type NumberCheckType = (typeof ALL_NUMBER_CHECKS)[number];
/**
* Type representing array validation checks.
*/
export type ArrayCheckType = (typeof ALL_ARRAY_CHECKS)[number];
/**
* Type representing unsupported Zod schema types.
*/
export type UnsupportedZodType = (typeof UNSUPPORTED_ZOD_TYPES)[number];
/**
* Type representing supported Zod schema types.
*/
export type SupportedZodType = (typeof SUPPORTED_ZOD_TYPES)[number];
/**
* Type representing all Zod schema types (supported and unsupported).
*/
export type AllZodType = (typeof ALL_ZOD_TYPES)[number];
/**
* Utility type to extract the shape of a Zod object schema.
*/
export type ZodShape<T extends z.AnyZodObject> = T['shape'];
/**
* Utility type to extract the keys from a Zod object shape.
*/
export type ShapeKey<T extends z.AnyZodObject> = keyof ZodShape<T>;
/**
* Utility type to extract the value types from a Zod object shape.
*/
export type ShapeValue<T extends z.AnyZodObject> = ZodShape<T>[ShapeKey<T>];
type ConstraintHelperText = string[];
/**
* Abstract base class for creating schema compatibility layers for different AI model providers.
*
* This class provides a framework for transforming Zod schemas to work with specific AI model
* provider requirements and limitations. Each provider may have different support levels for
* JSON Schema features, validation constraints, and data types.
*
*
* @example
* ```typescript
* import { SchemaCompatLayer } from '@mastra/schema-compat';
* import type { LanguageModelV1 } from 'ai';
*
* class CustomProviderCompat extends SchemaCompatLayer {
* constructor(model: ModelInformation) {
* super(model);
* }
*
* shouldApply(): boolean {
* return this.getModel().provider === 'custom-provider';
* }
*
* getSchemaTarget() {
* return 'jsonSchema7';
* }
*
* processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
* // Custom processing logic for this provider
* switch (value._def.typeName) {
* case 'ZodString':
* return this.defaultZodStringHandler(value, ['email', 'url']);
* default:
* return this.defaultUnsupportedZodTypeHandler(value);
* }
* }
* }
* ```
*/
export declare class SchemaCompatLayer {
private model;
private parent;
/**
* Creates a new schema compatibility instance.
*
* @param model - The language model this compatibility layer applies to
*/
constructor(model: ModelInformation, parent: ParentSchemaCompatLayer);
/**
* Gets the language model associated with this compatibility layer.
*
* @returns The language model instance
*/
getModel(): ModelInformation;
getUnsupportedZodTypes(): readonly string[];
/**
* Type guard for optional Zod types
*/
isOptional(v: ZodTypeAny): v is ZodOptional<any>;
/**
* Type guard for object Zod types
*/
isObj(v: ZodTypeAny): v is ZodObject<any, any, any>;
/**
* Type guard for null Zod types
*/
isNull(v: ZodTypeAny): v is ZodNull;
/**
* Type guard for nullable Zod types
*/
isNullable(v: ZodTypeAny): v is ZodNullable<any>;
/**
* Type guard for array Zod types
*/
isArr(v: ZodTypeAny): v is ZodArray<any, any>;
/**
* Type guard for union Zod types
*/
isUnion(v: ZodTypeAny): v is ZodUnion<[ZodTypeAny, ...ZodTypeAny[]]>;
/**
* Type guard for string Zod types
*/
isString(v: ZodTypeAny): v is ZodString;
/**
* Type guard for number Zod types
*/
isNumber(v: ZodTypeAny): v is ZodNumber;
/**
* Type guard for date Zod types
*/
isDate(v: ZodTypeAny): v is ZodDate;
/**
* Type guard for default Zod types
*/
isDefault(v: ZodTypeAny): v is ZodDefault<any>;
/**
* Type guard for intersection Zod types
*/
isIntersection(v: ZodTypeAny): v is ZodIntersection<any, any>;
/**
* Determines whether this compatibility layer should be applied for the current model.
*
* @returns True if this compatibility layer should be used, false otherwise
* @abstract
*/
shouldApply(): boolean;
/**
* Returns the JSON Schema target format for this provider.
*
* @returns The schema target format, or undefined to use the default 'jsonSchema7'
* @abstract
*/
getSchemaTarget(): Targets | undefined;
/**
* Processes a specific Zod type according to the provider's requirements.
*
* @param value - The Zod type to process
* @returns The processed Zod type
* @abstract
*/
processZodType(value: ZodTypeAny): ZodTypeAny;
/**
* Default handler for Zod object types. Recursively processes all properties in the object.
*
* @param value - The Zod object to process
* @returns The processed Zod object
*/
defaultZodObjectHandler(value: ZodObject<any, any, any>, options?: {
passthrough?: boolean;
}): ZodObject<any, any, any>;
/**
* Merges validation constraints into a parameter description.
*
* This helper method converts validation constraints that may not be supported
* by a provider into human-readable descriptions.
*
* @param description - The existing parameter description
* @param constraints - The validation constraints to merge
* @returns The updated description with constraints, or undefined if no constraints
*/
mergeParameterDescription(description: string | undefined, constraints: ConstraintHelperText): string | undefined;
/**
* Default handler for unsupported Zod types. Throws an error for specified unsupported types.
*
* @param value - The Zod type to check
* @param throwOnTypes - Array of type names to throw errors for
* @returns The original value if not in the throw list
* @throws Error if the type is in the unsupported list
*/
defaultUnsupportedZodTypeHandler<T extends z.AnyZodObject>(value: z.ZodTypeAny, throwOnTypes?: readonly UnsupportedZodType[]): ShapeValue<T>;
/**
* Default handler for Zod array types. Processes array constraints according to provider support.
*
* @param value - The Zod array to process
* @param handleChecks - Array constraints to convert to descriptions vs keep as validation
* @returns The processed Zod array
*/
defaultZodArrayHandler(value: ZodArray<any, any>, handleChecks?: readonly ArrayCheckType[]): ZodArray<any, any>;
/**
* Default handler for Zod union types. Processes all union options.
*
* @param value - The Zod union to process
* @returns The processed Zod union
* @throws Error if union has fewer than 2 options
*/
defaultZodUnionHandler(value: ZodUnion<[ZodTypeAny, ...ZodTypeAny[]]>): ZodTypeAny;
/**
* Default handler for Zod string types. Processes string validation constraints.
*
* @param value - The Zod string to process
* @param handleChecks - String constraints to convert to descriptions vs keep as validation
* @returns The processed Zod string
*/
defaultZodStringHandler(value: ZodString, handleChecks?: readonly StringCheckType[]): ZodString;
/**
* Default handler for Zod number types. Processes number validation constraints.
*
* @param value - The Zod number to process
* @param handleChecks - Number constraints to convert to descriptions vs keep as validation
* @returns The processed Zod number
*/
defaultZodNumberHandler(value: ZodNumber, handleChecks?: readonly NumberCheckType[]): ZodNumber;
/**
* Default handler for Zod date types. Converts dates to ISO strings with constraint descriptions.
*
* @param value - The Zod date to process
* @returns A Zod string schema representing the date in ISO format
*/
defaultZodDateHandler(value: ZodDate): ZodString;
/**
* Default handler for Zod optional types. Processes the inner type and maintains optionality.
*
* @param value - The Zod optional to process
* @param handleTypes - Types that should be processed vs passed through
* @returns The processed Zod optional
*/
defaultZodOptionalHandler(value: ZodOptional<any>, handleTypes?: readonly AllZodType[]): ZodTypeAny;
/**
* Default handler for Zod nullable types. Processes the inner type and maintains nullability.
*
* @param value - The Zod nullable to process
* @param handleTypes - Types that should be processed vs passed through
* @returns The processed Zod nullable
*/
defaultZodNullableHandler(value: ZodNullable<any>, handleTypes?: readonly AllZodType[]): ZodTypeAny;
/**
* Recursively collects leaf types from a ZodIntersection tree.
*/
private collectIntersectionLeaves;
/**
* Default handler for Zod intersection types.
* Flattens the intersection tree and merges object shapes into a single z.object().
* Falls back to z.any() for non-object intersections.
*/
defaultZodIntersectionHandler(value: ZodIntersection<any, any>): ZodTypeAny;
/**
* Processes a Zod object schema and converts it to an AI SDK Schema.
*
* @param zodSchema - The Zod object schema to process
* @returns An AI SDK Schema with provider-specific compatibility applied
*/
processToAISDKSchema(zodSchema: z.ZodSchema): Schema;
/**
* Processes a Zod object schema and converts it to a JSON Schema.
*
* @param zodSchema - The Zod object schema to process
* @returns A JSONSchema7 object with provider-specific compatibility applied
*/
processToJSONSchema(zodSchema: z.ZodSchema): JSONSchema7;
}
export {};
//# sourceMappingURL=schema-compatibility-v3.d.ts.map