@aeye/core 0.1.1 → 0.2.0

package/dist/schema.js

@@ -1,22 +1,5 @@
 import z from 'zod';
 /**
-* Transfer description and metadata from source Zod schema to target Zod schema
-*
-* @param target - target Zod schema
-* @param source - source Zod schema
-* @returns
-*/
-function transferMetadata(target, source) {
-    if (source.description) {
-        target = target.describe(source.description);
-    }
-    const meta = source.meta();
-    if (meta) {
-        target = target.meta(meta);
-    }
-    return target;
-}
-/**
 * Recursively transforms a Zod schema to support strict mode.
 *
 * @param schema - input Zod schema
@@ -43,6 +26,44 @@ export function strictify(schema) {
     return transform(schema);
 }
 /**
+* Transfer description and metadata from source Zod schema to target Zod schema
+*
+* @param target - target Zod schema
+* @param source - source Zod schema
+* @returns
+*/
+function transferMetadata(target, source) {
+    if (source.description) {
+        target = target.describe(source.description);
+    }
+    const meta = source.meta();
+    if (meta) {
+        target = target.meta(meta);
+    }
+    return target;
+}
+/**
+ * Extracts the input schema from a transformed schema (codec or preprocess).
+ * For preprocess with optional, we need the nullable version for strict mode input.
+ * This is needed when building input schemas that contain transformed fields.
+ */
+function getInputSchema(schema) {
+    if (schema instanceof z.ZodCodec) {
+        return schema.def.in;
+    }
+    // For ZodPipe (which preprocess creates), check if the output is optional
+    // If so, we need to return a nullable version for the input schema
+    if (schema instanceof z.ZodPipe) {
+        const outputSchema = schema.def.out;
+        if (outputSchema instanceof z.ZodOptional) {
+            // The input from preprocess is already set up to handle null->undefined conversion
+            // So we just need to make sure the base type accepts null
+            return z.nullable(outputSchema.unwrap());
+        }
+    }
+    return schema;
+}
+/**
 * Recursively transforms a Zod schema to support strict mode.
 *
 * @param schema - input Zod schema
@@ -51,11 +72,14 @@ export function strictify(schema) {
 function strictifySimple(schema, transform) {
     // Handle ZodOptional - get the inner schema and make it optional
     if (schema instanceof z.ZodOptional) {
-        const transformed = transform(schema.unwrap());
-        return transferMetadata(z.codec(transformed.nullable(), transformed.optional(), {
-            decode: (val) => val === null ? undefined : val,
-            encode: (val) => val === undefined ? null : val,
-        }), schema);
+        const innerSchema = schema.unwrap();
+        const transformed = transform(innerSchema);
+        // Check if the inner schema is nullable
+        // If it's nullable, don't convert null to undefined
+        const isNullable = innerSchema instanceof z.ZodNullable;
+        // Use a preprocess to convert null to undefined only for non-nullable schemas
+        // This avoids issues with codec output validation in recursive schemas
+        return transferMetadata(z.preprocess((val) => (!isNullable && val === null) ? undefined : val, transformed.optional()), schema);
     }
     // Handle ZodObject
     if (schema instanceof z.ZodObject) {
@@ -68,8 +92,8 @@ function strictifySimple(schema, transform) {
     // Handle ZodCodec
     if (schema instanceof z.ZodCodec) {
         return transferMetadata(z.codec(transform(schema.def.in), transform(schema.def.out), {
-            encode: schema.def.transform,
-            decode: schema.def.reverseTransform,
+            decode: schema.def.transform,
+            encode: schema.def.reverseTransform,
         }), schema);
     }
     // Handle ZodPipe
@@ -86,9 +110,12 @@ function strictifySimple(schema, transform) {
     }
     // Handle ZodRecord
     if (schema instanceof z.ZodRecord) {
-        const key = schema.keyType ? transform(schema.keyType) : z.string();
-        const value = transform(schema.valueType);
-        return transferMetadata(z.codec(z.array(z.object({ key, value })), z.record(key, value), {
+        const keyTransformed = schema.keyType ? transform(schema.keyType) : z.string();
+        const valueTransformed = transform(schema.valueType);
+        // For the input schema (array of {key, value}), use the input side of any codecs
+        const key = getInputSchema(keyTransformed);
+        const value = getInputSchema(valueTransformed);
+        return transferMetadata(z.codec(z.array(z.object({ key, value })), z.record(keyTransformed, valueTransformed), {
             decode: (arr) => {
                 const record = {};
                 for (const { key, value } of arr) {
@@ -126,41 +153,146 @@ function strictifySimple(schema, transform) {
     // For all other types (primitives, etc.), return as-is
     return schema;
 }
+/**
+ * Modify a JSON Schema property to make it optional (accept null)
+ *
+ * @param prop - input JSON Schema property
+ * @returns
+ */
+const makeOptional = (prop) => {
+    if (prop.type) {
+        const values = Array.isArray(prop.type) ? prop.type : [prop.type];
+        if (!values.includes('null')) {
+            prop.type = [...values, 'null'];
+        }
+        return prop;
+    }
+    else if (prop.$ref) {
+        // If it's a $ref, wrap it in anyOf with null
+        return {
+            anyOf: [
+                { $ref: prop.$ref },
+                { type: 'null' }
+            ],
+        };
+    }
+    else if (prop.allOf) {
+        // If it's an allOf with a single entry containing a $ref, extract and wrap the $ref
+        // This handles the common case: { allOf: [{ $ref: "..." }] }
+        if (prop.allOf.length === 1 && prop.allOf[0].$ref) {
+            return {
+                anyOf: [
+                    { $ref: prop.allOf[0].$ref },
+                    { type: 'null' }
+                ],
+            };
+        }
+        // Otherwise preserve the allOf structure
+        return {
+            anyOf: [
+                { allOf: prop.allOf },
+                { type: 'null' }
+            ],
+        };
+    }
+    else {
+        const { title, description, default: defaultValue, ...rest } = prop;
+        return {
+            title,
+            description,
+            default: defaultValue,
+            anyOf: [
+                rest,
+                { type: 'null' }
+            ],
+        };
+    }
+};
 /**
  * Override function to modify JSON Schema generation
  * to make optional fields accept null values.
  */
-const typeOverride = ({ jsonSchema }) => {
-    if (jsonSchema.type === 'object') {
+const typeOverride = ({ zodSchema, jsonSchema, path }) => {
+    if (jsonSchema.type === 'object' && zodSchema instanceof z.ZodObject) {
         const properties = jsonSchema.properties || {};
         const propertyKeys = Object.keys(properties);
         const required = jsonSchema.required || [];
         const optional = propertyKeys.filter((key) => !required.includes(key));
+        // Add null to optional fields (those not in required array)
         for (const key of optional) {
-            const { title, description, default: defaultValue, ...rest } = properties[key];
-            properties[key] = {
-                title,
-                description,
-                default: defaultValue,
-                anyOf: [
-                    rest,
-                    { type: 'null' }
-                ],
-            };
+            properties[key] = makeOptional(properties[key]);
+        }
+        // Check fields that are required - if they use preprocess with optional, add null
+        for (const key of required) {
+            const fieldSchema = zodSchema.shape[key];
+            // Check if this is a ZodPipe (from preprocess) wrapping optional
+            if (fieldSchema instanceof z.ZodPipe) {
+                const outputSchema = fieldSchema.def.out;
+                if (outputSchema instanceof z.ZodOptional) {
+                    const prop = properties[key];
+                    // Skip empty objects - they're placeholders for recursive schemas that will be filled in later
+                    if (Object.keys(prop).length === 0) {
+                        continue;
+                    }
+                    properties[key] = makeOptional(prop);
+                }
+            }
         }
         jsonSchema.required = propertyKeys;
         jsonSchema.additionalProperties = false;
     }
+    // Convert allOf with single entry to that entry or anyOf.
+    // allOf is not supported by some AI schema parsers.
     if (jsonSchema.allOf?.length) {
         if (jsonSchema.allOf.length === 1) {
             if (Object.keys(jsonSchema).length === 1) {
-                Object.assign(jsonSchema, jsonSchema.allOf[0]);
+                // Delete allOf first, THEN assign the content
+                const content = jsonSchema.allOf[0];
+                delete jsonSchema.allOf;
+                Object.assign(jsonSchema, content);
             }
             else {
                 jsonSchema.anyOf = jsonSchema.allOf;
+                delete jsonSchema.allOf;
+            }
+        }
+    }
+    // For anyOf with null, convert to type array
+    if (jsonSchema.anyOf?.length === 2) {
+        if (jsonSchema.anyOf[1].type === 'null'
+            && Object.keys(jsonSchema.anyOf[1]).length === 1
+            && jsonSchema.anyOf[0].type
+            && !Array.isArray(jsonSchema.anyOf[0].type)) {
+            const first = jsonSchema.anyOf[0];
+            const nullableType = [first.type, 'null'];
+            delete jsonSchema.anyOf;
+            Object.assign(jsonSchema, first);
+            // Set type after assign to avoid it being overwritten
+            jsonSchema.type = nullableType;
+        }
+    }
+    // anyOf in an anyOf - flatten
+    // BUT: Don't flatten if it would lose $ref or other important properties
+    if (jsonSchema.anyOf?.length) {
+        const newAnyOf = [];
+        for (const subSchema of jsonSchema.anyOf) {
+            // Check if this sub-schema has a nested anyOf that should be flattened
+            // Only flatten if:
+            // 1. The sub-schema has an anyOf property
+            // 2. The sub-schema has no other properties except anyOf (it's a pure wrapper)
+            // 3. None of the elements in the nested anyOf are $refs (which should be preserved)
+            const isPureAnyOfWrapper = subSchema.anyOf?.length && Object.keys(subSchema).length === 1;
+            const hasRefInNested = subSchema.anyOf?.some((nested) => nested.$ref);
+            if (isPureAnyOfWrapper && !hasRefInNested) {
+                // Safe to flatten
+                newAnyOf.push(...subSchema.anyOf);
+            }
+            else {
+                // Keep as-is
+                newAnyOf.push(subSchema);
             }
-            delete jsonSchema.allOf;
         }
+        jsonSchema.anyOf = newAnyOf;
     }
 };
 /**
@@ -178,4 +310,420 @@ export function toJSONSchema(schema, strict) {
         override: strict ? typeOverride : undefined,
     });
 }
+/**
+ * Converts a Zod schema to JSON Schema V2 with support for different provider formats.
+ *
+ * This is a custom implementation that recursively inspects Zod schemas and converts them
+ * to JSON Schema following the pattern of strictify/strictifySimple.
+ *
+ * @param schema - The Zod schema to convert
+ * @param options - Configuration options for the conversion
+ * @returns JSON Schema object compatible with the specified format
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   name: z.string(),
+ *   age: z.number().optional(),
+ * });
+ *
+ * // For OpenAI strict mode
+ * const strictSchema = strictify(schema);
+ * const jsonSchema = toJSONSchemaV2(strictSchema, { strict: true, format: 'openai' });
+ * ```
+ */
+export function toJSONSchemaV2(schema, options) {
+    const { strict, format = 'openai' } = options;
+    // Currently only OpenAI format is supported
+    if (format !== 'openai') {
+        throw new Error(`Unsupported format: ${format}. Currently only 'openai' is supported.`);
+    }
+    const context = {
+        strict,
+        format,
+        definitions: new Map(),
+        definitionSchemas: new Map(),
+        refCounter: 0,
+        path: [],
+    };
+    const result = convertSchema(schema, context);
+    // Add definitions if any were created
+    if (context.definitionSchemas.size > 0) {
+        result.$defs = Object.fromEntries(context.definitionSchemas);
+    }
+    return result;
+}
+/**
+ * Main recursive conversion function
+ */
+function convertSchema(schema, context) {
+    // Check if we've seen this schema before (for recursion)
+    if (context.definitions.has(schema)) {
+        const refName = context.definitions.get(schema);
+        return { $ref: `#/$defs/${refName}` };
+    }
+    // Handle ZodOptional
+    if (schema instanceof z.ZodOptional) {
+        const innerSchema = schema.unwrap();
+        const innerJson = convertSchema(innerSchema, context);
+        if (context.strict) {
+            // In strict mode, optional fields become nullable
+            return makeNullable(innerJson);
+        }
+        else {
+            // In non-strict mode, optional fields are just not required
+            return innerJson;
+        }
+    }
+    // Handle ZodNullable
+    if (schema instanceof z.ZodNullable) {
+        const innerSchema = schema.unwrap();
+        const innerJson = convertSchema(innerSchema, context);
+        return makeNullable(innerJson);
+    }
+    // Handle ZodObject
+    if (schema instanceof z.ZodObject) {
+        // Check if this object is recursive (contains self-references through getters)
+        // If it has an 'aid' in meta, create a definition for it
+        const meta = schema.meta();
+        if (meta?.aid && !context.definitions.has(schema)) {
+            // Register this schema as a definition
+            const refName = meta.aid;
+            context.definitions.set(schema, refName);
+            // Convert the schema
+            const properties = {};
+            const required = [];
+            const shape = schema.shape;
+            for (const key in shape) {
+                const fieldSchema = shape[key];
+                const isOptional = fieldSchema instanceof z.ZodOptional ||
+                    (fieldSchema instanceof z.ZodPipe && fieldSchema.def.out instanceof z.ZodOptional);
+                properties[key] = convertSchema(fieldSchema, context);
+                // In strict mode, ALL fields are required (optional ones are nullable)
+                // In non-strict mode, only non-optional fields are required
+                if (context.strict || !isOptional) {
+                    required.push(key);
+                }
+            }
+            const schemaJson = {
+                type: 'object',
+                properties,
+                required,
+            };
+            if (context.strict) {
+                schemaJson.additionalProperties = false;
+            }
+            addMetadata(schemaJson, schema);
+            context.definitionSchemas.set(refName, schemaJson);
+            return { $ref: `#/$defs/${refName}` };
+        }
+        const properties = {};
+        const required = [];
+        const shape = schema.shape;
+        for (const key in shape) {
+            const fieldSchema = shape[key];
+            const isOptional = fieldSchema instanceof z.ZodOptional ||
+                (fieldSchema instanceof z.ZodPipe && fieldSchema.def.out instanceof z.ZodOptional);
+            properties[key] = convertSchema(fieldSchema, context);
+            // In strict mode, ALL fields are required (optional ones are nullable)
+            // In non-strict mode, only non-optional fields are required
+            if (context.strict || !isOptional) {
+                required.push(key);
+            }
+        }
+        const result = {
+            type: 'object',
+            properties,
+            required,
+        };
+        if (context.strict) {
+            result.additionalProperties = false;
+        }
+        return addMetadata(result, schema);
+    }
+    // Handle ZodArray
+    if (schema instanceof z.ZodArray) {
+        const items = convertSchema(schema.element, context);
+        const result = {
+            type: 'array',
+            items,
+        };
+        return addMetadata(result, schema);
+    }
+    // Handle ZodRecord - convert to array of {key, value} pairs in strict mode
+    if (schema instanceof z.ZodRecord) {
+        const keySchema = schema.keyType || z.string();
+        const valueSchema = schema.valueType;
+        if (context.strict) {
+            // In strict mode, records become arrays of {key, value} objects
+            const keyJson = convertSchema(keySchema, context);
+            const valueJson = convertSchema(valueSchema, context);
+            return {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        key: keyJson,
+                        value: valueJson,
+                    },
+                    required: ['key', 'value'],
+                    additionalProperties: false,
+                },
+            };
+        }
+        else {
+            // In non-strict mode, use additionalProperties
+            const valueJson = convertSchema(valueSchema, context);
+            return {
+                type: 'object',
+                additionalProperties: valueJson,
+            };
+        }
+    }
+    // Handle ZodUnion
+    if (schema instanceof z.ZodUnion) {
+        const anyOf = schema.options.map((option) => convertSchema(option, context));
+        return { anyOf };
+    }
+    // Handle ZodDiscriminatedUnion
+    if (schema instanceof z.ZodDiscriminatedUnion) {
+        const anyOf = schema.options.map((option) => convertSchema(option, context));
+        return { anyOf };
+    }
+    // Handle ZodIntersection - not supported in OpenAI strict mode, convert to anyOf
+    if (schema instanceof z.ZodIntersection) {
+        if (context.strict && context.format === 'openai') {
+            // Convert intersection to anyOf for OpenAI compatibility
+            return {
+                anyOf: [
+                    convertSchema(schema.def.left, context),
+                    convertSchema(schema.def.right, context),
+                ],
+            };
+        }
+        // For non-strict, we could try to merge objects, but for now use anyOf
+        return {
+            anyOf: [
+                convertSchema(schema.def.left, context),
+                convertSchema(schema.def.right, context),
+            ],
+        };
+    }
+    // Handle ZodTuple
+    if (schema instanceof z.ZodTuple) {
+        // Tuples in JSON Schema can be represented as arrays with prefixItems
+        // For simplicity, we'll use an array type
+        const items = schema.def.items.map((item) => convertSchema(item, context));
+        // If all items are the same type, simplify to a single items schema
+        if (items.length > 0 && items.every((item) => JSON.stringify(item) === JSON.stringify(items[0]))) {
+            return {
+                type: 'array',
+                items: items[0],
+            };
+        }
+        // Otherwise, use anyOf for the items
+        return {
+            type: 'array',
+            items: {
+                anyOf: items,
+            },
+        };
+    }
+    // Handle ZodEnum
+    if (schema instanceof z.ZodEnum) {
+        const result = {
+            type: 'string',
+            enum: schema.options,
+        };
+        return addMetadata(result, schema);
+    }
+    // Handle ZodNativeEnum
+    if (schema._def?.typeName === 'ZodNativeEnum') {
+        const enumValues = Object.values(schema._def.values);
+        return {
+            type: typeof enumValues[0] === 'number' ? 'number' : 'string',
+            enum: enumValues,
+        };
+    }
+    // Handle ZodLiteral
+    if (schema instanceof z.ZodLiteral) {
+        const value = schema.value;
+        return {
+            type: typeof value,
+            const: value,
+        };
+    }
+    // Handle ZodDefault
+    if (schema instanceof z.ZodDefault) {
+        const innerJson = convertSchema(schema.def.innerType, context);
+        innerJson.default = schema.def.defaultValue;
+        return innerJson;
+    }
+    // Handle ZodLazy
+    if (schema instanceof z.ZodLazy) {
+        // Check if schema has an 'aid' in meta for custom definition name
+        const meta = schema.meta();
+        const refName = meta?.aid || `LazySchema${context.refCounter++}`;
+        context.definitions.set(schema, refName);
+        // Get the actual schema
+        const actualSchema = schema.def.getter();
+        const schemaJson = convertSchema(actualSchema, context);
+        context.definitionSchemas.set(refName, schemaJson);
+        return { $ref: `#/$defs/${refName}` };
+    }
+    // Handle ZodCodec
+    if (schema instanceof z.ZodCodec) {
+        // For codecs, use the input schema for JSON Schema generation
+        return convertSchema(schema.def.in, context);
+    }
+    // Handle ZodPipe (from preprocess)
+    if (schema instanceof z.ZodPipe) {
+        // For pipes, use the output schema if in strict mode (since strictify creates pipes for optional->nullable conversion)
+        // Otherwise use input schema
+        if (context.strict && schema.def.out instanceof z.ZodOptional) {
+            // This is from strictify - the output is optional, so we want nullable
+            const innerSchema = schema.def.out.unwrap();
+            const innerJson = convertSchema(innerSchema, context);
+            return makeNullable(innerJson);
+        }
+        return convertSchema(schema.def.in, context);
+    }
+    // Handle ZodTransform (from z.transform())
+    if (schema._def?.typeName === 'ZodTransform') {
+        // Use the input schema for JSON Schema generation
+        return convertSchema(schema._def.schema, context);
+    }
+    // Handle primitive types
+    if (schema instanceof z.ZodString) {
+        const result = { type: 'string' };
+        // Add string constraints if present
+        const checks = schema._def.checks || [];
+        for (const check of checks) {
+            if (check.kind === 'regex') {
+                result.pattern = check.regex.source;
+            }
+            else if (check.kind === 'email') {
+                result.format = 'email';
+            }
+            else if (check.kind === 'url') {
+                result.format = 'uri';
+            }
+            else if (check.kind === 'uuid') {
+                result.format = 'uuid';
+            }
+            else if (check.kind === 'datetime') {
+                result.format = 'date-time';
+            }
+        }
+        return addMetadata(result, schema);
+    }
+    if (schema instanceof z.ZodNumber) {
+        const result = { type: 'number' };
+        // Add number constraints if present
+        const checks = schema._def.checks || [];
+        for (const check of checks) {
+            if (check.kind === 'min') {
+                if (check.inclusive) {
+                    result.minimum = check.value;
+                }
+                else {
+                    result.exclusiveMinimum = check.value;
+                }
+            }
+            else if (check.kind === 'max') {
+                if (check.inclusive) {
+                    result.maximum = check.value;
+                }
+                else {
+                    result.exclusiveMaximum = check.value;
+                }
+            }
+            else if (check.kind === 'multipleOf') {
+                result.multipleOf = check.value;
+            }
+        }
+        return addMetadata(result, schema);
+    }
+    if (schema instanceof z.ZodBoolean) {
+        return addMetadata({ type: 'boolean' }, schema);
+    }
+    if (schema instanceof z.ZodBigInt) {
+        return addMetadata({ type: 'integer' }, schema);
+    }
+    if (schema instanceof z.ZodDate) {
+        return addMetadata({ type: 'string', format: 'date-time' }, schema);
+    }
+    if (schema instanceof z.ZodNull) {
+        return { type: 'null' };
+    }
+    if (schema instanceof z.ZodUndefined) {
+        return { type: 'null' }; // Treat undefined as null in JSON
+    }
+    if (schema instanceof z.ZodAny) {
+        return {}; // Any type has no constraints
+    }
+    // Handle ZodEffects (transformations, refinements) - use inner schema
+    if (schema._def?.typeName === 'ZodEffects') {
+        return convertSchema(schema._def.schema, context);
+    }
+    // Fallback for unknown types
+    console.warn(`Unknown Zod schema type: ${schema.constructor.name}`);
+    return {};
+}
+/**
+ * Makes a JSON Schema nullable by adding null to the type
+ */
+function makeNullable(schema) {
+    if (schema.$ref) {
+        // If it's a reference, wrap in anyOf with null
+        return {
+            anyOf: [
+                { $ref: schema.$ref },
+                { type: 'null' },
+            ],
+        };
+    }
+    if (schema.type) {
+        // Add null to the type
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if (!types.includes('null')) {
+            return {
+                ...schema,
+                type: [...types, 'null'],
+            };
+        }
+        return schema;
+    }
+    if (schema.anyOf) {
+        // Already has anyOf, add null option if not present
+        const hasNull = schema.anyOf.some((s) => s.type === 'null');
+        if (!hasNull) {
+            return {
+                ...schema,
+                anyOf: [...schema.anyOf, { type: 'null' }],
+            };
+        }
+        return schema;
+    }
+    // For complex schemas without type, wrap in anyOf
+    return {
+        anyOf: [
+            schema,
+            { type: 'null' },
+        ],
+    };
+}
+/**
+ * Adds metadata (description, meta) from Zod schema to JSON Schema
+ */
+function addMetadata(jsonSchema, zodSchema) {
+    if (zodSchema.description) {
+        jsonSchema.description = zodSchema.description;
+    }
+    const meta = zodSchema.meta();
+    if (meta?.title) {
+        jsonSchema.title = meta.title;
+    }
+    return jsonSchema;
+}
 //# sourceMappingURL=schema.js.map