@agentuity/schema 0.0.69

package/src/complex/record.ts

@@ -0,0 +1,129 @@
+import type { Schema, Infer } from '../base';
+import { createIssue, failure, success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+/**
+ * Schema for validating records (objects with string keys and typed values).
+ * Like TypeScript's Record<string, T> type.
+ *
+ * @template K - The key schema (must be string)
+ * @template V - The value schema
+ *
+ * @example
+ * ```typescript
+ * const schema = s.record(s.string(), s.number());
+ * schema.parse({ a: 1, b: 2 }); // { a: 1, b: 2 }
+ * schema.parse({ a: 'invalid' }); // throws ValidationError
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class RecordSchema<K extends Schema<string, string>, V extends Schema<any, any>>
+	implements Schema<Record<Infer<K>, Infer<V>>, Record<Infer<K>, Infer<V>>>
+{
+	description?: string;
+	private recordParseMethods = createParseMethods<Record<Infer<K>, Infer<V>>>();
+
+	constructor(
+		private keySchema: K,
+		private valueSchema: V
+	) {}
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (value === null) {
+				return failure([createIssue('Expected record, got null')]);
+			}
+			if (Array.isArray(value)) {
+				return failure([createIssue('Expected record, got array')]);
+			}
+			if (typeof value !== 'object') {
+				return failure([createIssue(`Expected record, got ${typeof value}`)]);
+			}
+
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			const result: Record<string, any> = {};
+			const issues: ReturnType<typeof createIssue>[] = [];
+
+			for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+				// Validate key
+				const keyValidation = this.keySchema['~standard'].validate(key);
+				if (keyValidation instanceof Promise) {
+					throw new Error('Async validation not supported');
+				}
+				if (keyValidation.issues) {
+					for (const issue of keyValidation.issues) {
+						issues.push(createIssue(`Invalid key "${key}": ${issue.message}`, [key]));
+					}
+					continue;
+				}
+
+				// Validate value
+				const valueValidation = this.valueSchema['~standard'].validate(val);
+				if (valueValidation instanceof Promise) {
+					throw new Error('Async validation not supported');
+				}
+				if (valueValidation.issues) {
+					for (const issue of valueValidation.issues) {
+						issues.push(
+							createIssue(issue.message, issue.path ? [key, ...issue.path] : [key])
+						);
+					}
+				} else {
+					result[key] = valueValidation.value;
+				}
+			}
+
+			if (issues.length > 0) {
+				return failure(issues);
+			}
+
+			return success(result as Record<Infer<K>, Infer<V>>);
+		},
+		types: undefined as unknown as {
+			input: Record<Infer<K>, Infer<V>>;
+			output: Record<Infer<K>, Infer<V>>;
+		},
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+
+	parse = this.recordParseMethods.parse;
+	safeParse = this.recordParseMethods.safeParse;
+}
+
+/**
+ * Create a record schema for objects with string keys and typed values.
+ *
+ * @param keySchema - Schema for keys (typically s.string())
+ * @param valueSchema - Schema for values
+ *
+ * @example
+ * ```typescript
+ * const configSchema = s.record(s.string(), s.number());
+ * const config = configSchema.parse({ timeout: 30, retries: 3 });
+ *
+ * const metadataSchema = s.record(s.string(), s.unknown());
+ * const metadata = metadataSchema.parse({ any: 'data', here: 123 });
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function record<K extends Schema<string, string>, V extends Schema<any, any>>(
+	keySchema: K,
+	valueSchema: V
+): RecordSchema<K, V> {
+	return new RecordSchema(keySchema, valueSchema);
+}

package/src/index.ts

@@ -0,0 +1,177 @@
+export type {
+	Schema,
+	Infer,
+	InferInput,
+	InferOutput,
+	ValidationIssue,
+	ValidationResult,
+	SafeParseResult,
+	SafeParseSuccess,
+	SafeParseError,
+} from './base';
+export { createIssue, success, failure, ValidationError } from './base';
+
+export { StringSchema, string } from './primitives/string';
+export { NumberSchema, number } from './primitives/number';
+export { BooleanSchema, boolean } from './primitives/boolean';
+export { NullSchema, null_ } from './primitives/null';
+export { UndefinedSchema, undefined_ } from './primitives/undefined';
+export { UnknownSchema, unknown } from './primitives/unknown';
+export { AnySchema, any } from './primitives/any';
+
+export { ObjectSchema, object } from './complex/object';
+export { ArraySchema, array } from './complex/array';
+export { RecordSchema, record } from './complex/record';
+
+export { LiteralSchema, literal } from './utils/literal';
+export { OptionalSchema, optional } from './utils/optional';
+export { NullableSchema, nullable } from './utils/nullable';
+export { UnionSchema, union } from './utils/union';
+
+export { toJSONSchema, fromJSONSchema, type JSONSchema } from './json-schema';
+
+export { CoerceStringSchema, coerceString } from './coerce/string';
+export { CoerceNumberSchema, coerceNumber } from './coerce/number';
+export { CoerceBooleanSchema, coerceBoolean } from './coerce/boolean';
+export { CoerceDateSchema, coerceDate } from './coerce/date';
+
+import { string } from './primitives/string';
+import { number } from './primitives/number';
+import { boolean } from './primitives/boolean';
+import { null_ } from './primitives/null';
+import { undefined_ } from './primitives/undefined';
+import { unknown } from './primitives/unknown';
+import { any } from './primitives/any';
+import { object } from './complex/object';
+import { array } from './complex/array';
+import { record } from './complex/record';
+import { literal } from './utils/literal';
+import { optional } from './utils/optional';
+import { nullable } from './utils/nullable';
+import { union } from './utils/union';
+import { toJSONSchema, fromJSONSchema } from './json-schema';
+import { coerceString } from './coerce/string';
+import { coerceNumber } from './coerce/number';
+import { coerceBoolean } from './coerce/boolean';
+import { coerceDate } from './coerce/date';
+
+import type { Infer as InferType, Schema } from './base';
+
+/**
+ * Create an enum schema (union of literal values).
+ * Shorthand for creating a union of literals.
+ *
+ * @param values - Array of literal values
+ *
+ * @example
+ * ```typescript
+ * const roleSchema = s.enum(['admin', 'user', 'guest']);
+ * const role = roleSchema.parse('admin'); // 'admin'
+ *
+ * // Equivalent to:
+ * s.union(s.literal('admin'), s.literal('user'), s.literal('guest'))
+ * ```
+ */
+function enumSchema<
+	T extends readonly [string | number | boolean, ...(string | number | boolean)[]],
+>(values: T) {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	return union(...values.map((v) => literal(v as any)));
+}
+
+/**
+ * Main schema builder object.
+ * Provides access to all schema types and utilities.
+ *
+ * @example
+ * ```typescript
+ * import { s } from '@agentuity/schema';
+ *
+ * // Define a schema
+ * const User = s.object({
+ *   name: s.string(),
+ *   age: s.number(),
+ *   role: s.enum(['admin', 'user'])
+ * });
+ *
+ * // Extract type
+ * type User = s.infer<typeof User>;
+ *
+ * // Parse data
+ * const user = User.parse(data);
+ * ```
+ */
+export const s = {
+	/** Create a string schema */
+	string,
+	/** Create a number schema */
+	number,
+	/** Create a boolean schema */
+	boolean,
+	/** Create a null schema */
+	null: null_,
+	/** Create an undefined schema */
+	undefined: undefined_,
+	/** Create an unknown schema (accepts any value) */
+	unknown,
+	/** Create an any schema (accepts any value) */
+	any,
+	/** Create an object schema with typed properties */
+	object,
+	/** Create an array schema with typed elements */
+	array,
+	/** Create a record schema (object with string keys and typed values) */
+	record,
+	/** Create a literal value schema */
+	literal,
+	/** Make a schema optional (T | undefined) */
+	optional,
+	/** Make a schema nullable (T | null) */
+	nullable,
+	/** Create a union of schemas */
+	union,
+	/** Create an enum schema (union of literals) */
+	enum: enumSchema,
+	/** Convert schema to JSON Schema format */
+	toJSONSchema,
+	/** Convert JSON Schema to schema */
+	fromJSONSchema,
+	/** Coercion schemas for type conversion */
+	coerce: {
+		/** Coerce to string using String(value) */
+		string: coerceString,
+		/** Coerce to number using Number(value) */
+		number: coerceNumber,
+		/** Coerce to boolean using Boolean(value) */
+		boolean: coerceBoolean,
+		/** Coerce to Date using new Date(value) */
+		date: coerceDate,
+	},
+};
+
+/**
+ * Namespace for s.infer type extraction (like zod's z.infer).
+ *
+ * @example
+ * ```typescript
+ * const User = s.object({ name: s.string(), age: s.number() });
+ * type User = s.infer<typeof User>;
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace s {
+	/**
+	 * Extract the TypeScript type from a schema (like zod's z.infer).
+	 *
+	 * @template T - The schema type
+	 *
+	 * @example
+	 * ```typescript
+	 * const Player = s.object({ username: s.string(), xp: s.number() });
+	 * type Player = s.infer<typeof Player>;
+	 * // { username: string; xp: number }
+	 * ```
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	export type infer<T extends Schema<any, any>> = InferType<T>;
+}

package/src/json-schema.ts

@@ -0,0 +1,331 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Schema } from './base';
+import { StringSchema, string } from './primitives/string';
+import { NumberSchema, number } from './primitives/number';
+import { BooleanSchema, boolean } from './primitives/boolean';
+import { NullSchema, null_ } from './primitives/null';
+import { UndefinedSchema } from './primitives/undefined';
+import { ObjectSchema, object } from './complex/object';
+import { ArraySchema, array } from './complex/array';
+import { LiteralSchema, literal } from './utils/literal';
+import { OptionalSchema, optional } from './utils/optional';
+import { NullableSchema, nullable } from './utils/nullable';
+import { UnionSchema, union } from './utils/union';
+
+/**
+ * JSON Schema object representation.
+ * Subset of JSON Schema Draft 7 specification.
+ */
+export interface JSONSchema {
+	type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+	description?: string;
+	const?: string | number | boolean;
+	enum?: Array<string | number | boolean>;
+	properties?: Record<string, JSONSchema>;
+	required?: string[];
+	items?: JSONSchema;
+	anyOf?: JSONSchema[];
+	oneOf?: JSONSchema[];
+	allOf?: JSONSchema[];
+}
+
+/**
+ * Convert a schema to JSON Schema format.
+ * Supports primitives, objects, arrays, unions, literals, optional, and nullable types.
+ *
+ * @param schema - The schema to convert
+ * @returns JSON Schema object
+ *
+ * @example
+ * ```typescript
+ * const userSchema = s.object({
+ *   name: s.string().describe('User name'),
+ *   age: s.number().describe('User age')
+ * });
+ *
+ * const jsonSchema = s.toJSONSchema(userSchema);
+ * // { type: 'object', properties: {...}, required: [...] }
+ * ```
+ */
+export function toJSONSchema(schema: Schema<any, any>): JSONSchema {
+	const result: JSONSchema = {};
+
+	// Add description if available
+	if (schema.description) {
+		result.description = schema.description;
+	}
+
+	// Primitive types
+	if (schema instanceof StringSchema) {
+		result.type = 'string';
+		return result;
+	}
+
+	if (schema instanceof NumberSchema) {
+		result.type = 'number';
+		return result;
+	}
+
+	if (schema instanceof BooleanSchema) {
+		result.type = 'boolean';
+		return result;
+	}
+
+	if (schema instanceof NullSchema) {
+		result.type = 'null';
+		return result;
+	}
+
+	if (schema instanceof UndefinedSchema) {
+		// JSON Schema doesn't have a direct "undefined" type
+		// We can represent it as an empty schema or omit the field
+		return {};
+	}
+
+	// Literal types
+	if (schema instanceof LiteralSchema) {
+		const value = (schema as any).value;
+		result.const = value;
+		if (typeof value === 'string') {
+			result.type = 'string';
+		} else if (typeof value === 'number') {
+			result.type = 'number';
+		} else if (typeof value === 'boolean') {
+			result.type = 'boolean';
+		}
+		return result;
+	}
+
+	// Object types
+	if (schema instanceof ObjectSchema) {
+		result.type = 'object';
+		const shape = (schema as any).shape;
+		result.properties = {};
+		result.required = [];
+
+		for (const [key, fieldSchema] of Object.entries(shape) as Array<[string, Schema<any, any>]>) {
+			result.properties[key] = toJSONSchema(fieldSchema);
+
+			// If the field is not optional, add it to required
+			if (!(fieldSchema instanceof OptionalSchema)) {
+				result.required.push(key);
+			}
+		}
+
+		// Remove required if empty
+		if (result.required.length === 0) {
+			delete result.required;
+		}
+
+		return result;
+	}
+
+	// Array types
+	if (schema instanceof ArraySchema) {
+		result.type = 'array';
+		const itemSchema = (schema as any).itemSchema;
+		result.items = toJSONSchema(itemSchema);
+		return result;
+	}
+
+	// Optional types
+	if (schema instanceof OptionalSchema) {
+		const innerSchema = (schema as any).schema;
+		const innerJSON = toJSONSchema(innerSchema);
+		// Optional is typically handled at the object level via required array
+		return innerJSON;
+	}
+
+	// Nullable types
+	if (schema instanceof NullableSchema) {
+		const innerSchema = (schema as any).schema;
+		const innerJSON = toJSONSchema(innerSchema);
+		// Nullable can be represented as anyOf with null
+		return {
+			anyOf: [innerJSON, { type: 'null' }],
+			...(schema.description && { description: schema.description }),
+		};
+	}
+
+	// Union types
+	if (schema instanceof UnionSchema) {
+		const schemas = (schema as any).schemas as Schema<any, any>[];
+		result.anyOf = schemas.map((schema) => toJSONSchema(schema));
+		return result;
+	}
+
+	// Fallback for unknown schema types
+	return result;
+}
+
+/**
+ * Convert a JSON Schema object to a schema.
+ * Supports round-trip conversion with toJSONSchema.
+ *
+ * @param jsonSchema - The JSON Schema object to convert
+ * @returns Schema instance
+ *
+ * @example
+ * ```typescript
+ * const jsonSchema = {
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string' },
+ *     age: { type: 'number' }
+ *   },
+ *   required: ['name', 'age']
+ * };
+ *
+ * const schema = s.fromJSONSchema(jsonSchema);
+ * const user = schema.parse({ name: 'John', age: 30 });
+ * ```
+ */
+export function fromJSONSchema(jsonSchema: JSONSchema): Schema<any, any> {
+	// Handle const (literal values)
+	if (jsonSchema.const !== undefined) {
+		const schema = literal(jsonSchema.const);
+		if (jsonSchema.description) {
+			schema.describe(jsonSchema.description);
+		}
+		return schema;
+	}
+
+	// Handle anyOf (union or nullable)
+	if (jsonSchema.anyOf && Array.isArray(jsonSchema.anyOf)) {
+		// Check if it's a nullable pattern (anyOf with one schema and one null)
+		if (jsonSchema.anyOf.length === 2) {
+			const nullIndex = jsonSchema.anyOf.findIndex((s) => s.type === 'null');
+			if (nullIndex !== -1) {
+				const otherIndex = nullIndex === 0 ? 1 : 0;
+				const innerSchema = fromJSONSchema(jsonSchema.anyOf[otherIndex]);
+				const schema = nullable(innerSchema);
+				if (jsonSchema.description) {
+					schema.describe(jsonSchema.description);
+				}
+				return schema;
+			}
+		}
+
+		// Otherwise treat as union
+		const schemas = jsonSchema.anyOf.map((s) => fromJSONSchema(s));
+		const schema = union(...schemas);
+		if (jsonSchema.description) {
+			schema.describe(jsonSchema.description);
+		}
+		return schema;
+	}
+
+	// Handle oneOf (union)
+	if (jsonSchema.oneOf && Array.isArray(jsonSchema.oneOf)) {
+		const schemas = jsonSchema.oneOf.map((s) => fromJSONSchema(s));
+		const schema = union(...schemas);
+		if (jsonSchema.description) {
+			schema.describe(jsonSchema.description);
+		}
+		return schema;
+	}
+
+	// Handle enum (union of literals)
+	if (jsonSchema.enum && Array.isArray(jsonSchema.enum)) {
+		const schemas = jsonSchema.enum.map((value) => literal(value as string | number | boolean));
+		const schema = union(...schemas);
+		if (jsonSchema.description) {
+			schema.describe(jsonSchema.description);
+		}
+		return schema;
+	}
+
+	// Handle primitive types
+	switch (jsonSchema.type) {
+		case 'string': {
+			const schema = string();
+			if (jsonSchema.description) {
+				schema.describe(jsonSchema.description);
+			}
+			return schema;
+		}
+
+		case 'number':
+		case 'integer': {
+			const schema = number();
+			if (jsonSchema.description) {
+				schema.describe(jsonSchema.description);
+			}
+			return schema;
+		}
+
+		case 'boolean': {
+			const schema = boolean();
+			if (jsonSchema.description) {
+				schema.describe(jsonSchema.description);
+			}
+			return schema;
+		}
+
+		case 'null': {
+			const schema = null_();
+			if (jsonSchema.description) {
+				schema.describe(jsonSchema.description);
+			}
+			return schema;
+		}
+
+		case 'array': {
+			if (!jsonSchema.items) {
+				throw new Error('Array type must have items property');
+			}
+			const itemSchema = fromJSONSchema(jsonSchema.items);
+			const schema = array(itemSchema);
+			if (jsonSchema.description) {
+				schema.describe(jsonSchema.description);
+			}
+			return schema;
+		}
+
+		case 'object': {
+			if (!jsonSchema.properties) {
+				// Empty object schema
+				const schema = object({});
+				if (jsonSchema.description) {
+					schema.describe(jsonSchema.description);
+				}
+				return schema;
+			}
+
+			const shape: Record<string, Schema<any, any>> = {};
+			const requiredFields = new Set(jsonSchema.required || []);
+
+			for (const [key, propSchema] of Object.entries(jsonSchema.properties)) {
+				let fieldSchema = fromJSONSchema(propSchema);
+
+				// If field is not in required array, make it optional
+				if (!requiredFields.has(key)) {
+					fieldSchema = optional(fieldSchema);
+				}
+
+				shape[key] = fieldSchema;
+			}
+
+			const schema = object(shape);
+			if (jsonSchema.description) {
+				schema.describe(jsonSchema.description);
+			}
+			return schema;
+		}
+
+		default: {
+			// If no type is specified, try to infer from other properties
+			if (jsonSchema.properties) {
+				// Treat as object
+				return fromJSONSchema({ ...jsonSchema, type: 'object' });
+			}
+			if (jsonSchema.items) {
+				// Treat as array
+				return fromJSONSchema({ ...jsonSchema, type: 'array' });
+			}
+			// Fallback to string schema for unrecognized/untyped JSON Schema
+			// This provides a permissive default but may mask schema issues
+			return string();
+		}
+	}
+}

package/src/primitives/any.ts

@@ -0,0 +1,64 @@
+import type { Schema } from '../base';
+import { success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const parseMethods = createParseMethods<any>();
+
+/**
+ * Schema that accepts any value with 'any' type.
+ * Returns the value as-is without validation or type safety.
+ * Use this sparingly - prefer unknown() for better type safety.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.any();
+ * const value = schema.parse(123); // any
+ * const value2 = schema.parse('hello'); // any
+ *
+ * // No type checking required
+ * value.toUpperCase(); // No error, but may fail at runtime
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class AnySchema implements Schema<any, any> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		validate: (value: unknown) => success(value as any),
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		types: undefined as unknown as { input: any; output: any },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+	parse = parseMethods.parse;
+	safeParse = parseMethods.safeParse;
+}
+
+/**
+ * Create an any schema that accepts any value.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.any();
+ * const value = schema.parse(anything); // Type is any
+ * ```
+ */
+export function any(): AnySchema {
+	return new AnySchema();
+}