@agentuity/schema 0.0.69

package/src/base.ts

@@ -0,0 +1,185 @@
+import type { StandardSchemaV1 } from '@agentuity/core';
+
+/**
+ * A validation issue from a failed schema validation.
+ */
+export type ValidationIssue = StandardSchemaV1.Issue;
+
+/**
+ * The result of a schema validation (success or failure).
+ */
+export type ValidationResult<T> = StandardSchemaV1.Result<T>;
+
+/**
+ * Successful parse result containing validated data.
+ */
+export interface SafeParseSuccess<T> {
+	/** Indicates successful validation */
+	success: true;
+	/** The validated and typed data */
+	data: T;
+}
+
+/**
+ * Failed parse result containing validation error.
+ */
+export interface SafeParseError {
+	/** Indicates failed validation */
+	success: false;
+	/** The validation error with detailed issues */
+	error: ValidationError;
+}
+
+/**
+ * Result of safeParse - either success with data or failure with error.
+ */
+export type SafeParseResult<T> = SafeParseSuccess<T> | SafeParseError;
+
+/**
+ * Error thrown when schema validation fails.
+ * Contains detailed information about all validation issues including field paths.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   schema.parse(data);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log(error.message);  // Human-readable error
+ *     console.log(error.issues);   // Detailed issues array
+ *   }
+ * }
+ * ```
+ */
+export class ValidationError extends Error {
+	/** Array of validation issues with paths and messages */
+	readonly issues: readonly ValidationIssue[];
+
+	constructor(issues: readonly ValidationIssue[]) {
+		const message = issues
+			.map((issue) => {
+				const path = issue.path
+					? `[${issue.path
+							.map((p) =>
+								// eslint-disable-next-line @typescript-eslint/no-explicit-any
+								typeof p === 'object' ? (p as any).key : p
+							)
+							.join('.')}]`
+					: '';
+				return path ? `${path}: ${issue.message}` : issue.message;
+			})
+			.join('\n');
+
+		super(message);
+		this.name = 'ValidationError';
+		this.issues = issues;
+
+		// Maintain proper stack trace for where our error was thrown
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, ValidationError);
+		}
+	}
+
+	toString(): string {
+		return `${this.name}: ${this.message}`;
+	}
+}
+
+/**
+ * Base schema interface that all schemas implement.
+ * Provides StandardSchema v1 compliance plus additional methods for parsing and description.
+ */
+export interface Schema<Input = unknown, Output = Input> extends StandardSchemaV1<Input, Output> {
+	readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+	/** Optional description for documentation */
+	description?: string;
+	/** Add a description to the schema for documentation and JSON Schema */
+	describe(description: string): this;
+	/** Parse and validate data, throwing ValidationError on failure */
+	parse(value: unknown): Output;
+	/** Parse and validate data, returning result object without throwing */
+	safeParse(value: unknown): SafeParseResult<Output>;
+	/** Make this schema optional (allow undefined) */
+	optional(): Schema<Input | undefined, Output | undefined>;
+	/** Make this schema nullable (allow null) */
+	nullable(): Schema<Input | null, Output | null>;
+}
+
+/**
+ * Extract the output type from a schema (like zod's z.infer).
+ *
+ * @example
+ * ```typescript
+ * const User = s.object({ name: s.string(), age: s.number() });
+ * type User = Infer<typeof User>;  // { name: string; age: number }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Infer<T extends Schema<any, any>> = StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Extract the input type from a schema.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type InferInput<T extends Schema<any, any>> = StandardSchemaV1.InferInput<T>;
+
+/**
+ * Extract the output type from a schema (alias for Infer).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type InferOutput<T extends Schema<any, any>> = StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Create a validation issue with an optional field path.
+ */
+export function createIssue(
+	message: string,
+	path?: ReadonlyArray<PropertyKey | StandardSchemaV1.PathSegment>
+): ValidationIssue {
+	return path ? { message, path } : { message };
+}
+
+/**
+ * Create a successful validation result.
+ */
+export function success<T>(value: T): StandardSchemaV1.SuccessResult<T> {
+	return { value };
+}
+
+/**
+ * Create a failed validation result.
+ */
+export function failure(issues: ValidationIssue[]): StandardSchemaV1.FailureResult {
+	return { issues };
+}
+
+/**
+ * Create parse and safeParse methods for a schema.
+ * @internal
+ */
+export function createParseMethods<Output>() {
+	return {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		parse(this: Schema<any, Output>, value: unknown): Output {
+			const result = this['~standard'].validate(value);
+			if (result instanceof Promise) {
+				throw new Error('Async validation not supported in parse()');
+			}
+			if (result.issues) {
+				throw new ValidationError(result.issues);
+			}
+			return result.value;
+		},
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		safeParse(this: Schema<any, Output>, value: unknown): SafeParseResult<Output> {
+			const result = this['~standard'].validate(value);
+			if (result instanceof Promise) {
+				throw new Error('Async validation not supported in safeParse()');
+			}
+			if (result.issues) {
+				return { success: false, error: new ValidationError(result.issues) };
+			}
+			return { success: true, data: result.value };
+		},
+	};
+}

package/src/coerce/boolean.ts

@@ -0,0 +1,56 @@
+import type { Schema } from '../base';
+import { success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+const parseMethods = createParseMethods<boolean>();
+
+/**
+ * Schema that coerces values to booleans using Boolean(value).
+ * Uses JavaScript truthy/falsy rules.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.coerce.boolean();
+ * schema.parse(1); // true
+ * schema.parse(0); // false
+ * schema.parse(''); // false
+ * schema.parse('hello'); // true
+ * ```
+ */
+export class CoerceBooleanSchema implements Schema<unknown, boolean> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			// Coerce to boolean using JavaScript truthiness rules
+			return success(Boolean(value));
+		},
+		types: undefined as unknown as { input: unknown; output: boolean },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+	parse = parseMethods.parse;
+	safeParse = parseMethods.safeParse;
+}
+
+/**
+ * Create a schema that coerces values to booleans.
+ * Useful for parsing checkboxes or boolean flags from strings.
+ */
+export function coerceBoolean(): CoerceBooleanSchema {
+	return new CoerceBooleanSchema();
+}

package/src/coerce/date.ts

@@ -0,0 +1,68 @@
+import type { Schema } from '../base';
+import { createIssue, failure, success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+const parseMethods = createParseMethods<Date>();
+
+/**
+ * Schema that coerces values to Date objects using new Date(value).
+ * Fails if the result is an invalid date.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.coerce.date();
+ * schema.parse('2025-01-01'); // Date object
+ * schema.parse(1609459200000); // Date from timestamp
+ * schema.parse('invalid'); // throws ValidationError
+ * ```
+ */
+export class CoerceDateSchema implements Schema<unknown, Date> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			// Already a Date
+			if (value instanceof Date) {
+				if (isNaN(value.getTime())) {
+					return failure([createIssue('Invalid date')]);
+				}
+				return success(value);
+			}
+
+			// Coerce to Date
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			const coerced = new Date(value as any);
+			if (isNaN(coerced.getTime())) {
+				return failure([createIssue(`Cannot coerce ${typeof value} to date`)]);
+			}
+			return success(coerced);
+		},
+		types: undefined as unknown as { input: unknown; output: Date },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+	parse = parseMethods.parse;
+	safeParse = parseMethods.safeParse;
+}
+
+/**
+ * Create a schema that coerces values to Date objects.
+ * Useful for parsing ISO date strings or timestamps.
+ */
+export function coerceDate(): CoerceDateSchema {
+	return new CoerceDateSchema();
+}

package/src/coerce/number.ts

@@ -0,0 +1,67 @@
+import type { Schema } from '../base';
+import { createIssue, failure, success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+const parseMethods = createParseMethods<number>();
+
+/**
+ * Schema that coerces values to numbers using Number(value).
+ * Fails if the result is NaN.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.coerce.number();
+ * schema.parse('123'); // 123
+ * schema.parse(true); // 1
+ * schema.parse('abc'); // throws ValidationError
+ * ```
+ */
+export class CoerceNumberSchema implements Schema<unknown, number> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			// Already a number
+			if (typeof value === 'number') {
+				if (Number.isNaN(value)) {
+					return failure([createIssue('Cannot coerce NaN to number')]);
+				}
+				return success(value);
+			}
+
+			// Coerce to number
+			const coerced = Number(value);
+			if (Number.isNaN(coerced)) {
+				return failure([createIssue(`Cannot coerce ${typeof value} to number`)]);
+			}
+			return success(coerced);
+		},
+		types: undefined as unknown as { input: unknown; output: number },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+	parse = parseMethods.parse;
+	safeParse = parseMethods.safeParse;
+}
+
+/**
+ * Create a schema that coerces values to numbers.
+ * Useful for parsing form data or query parameters where numbers come as strings.
+ */
+export function coerceNumber(): CoerceNumberSchema {
+	return new CoerceNumberSchema();
+}

package/src/coerce/string.ts

@@ -0,0 +1,54 @@
+import type { Schema } from '../base';
+import { success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+const parseMethods = createParseMethods<string>();
+
+/**
+ * Schema that coerces any value to a string using String(value).
+ *
+ * @example
+ * ```typescript
+ * const schema = s.coerce.string();
+ * schema.parse(123); // '123'
+ * schema.parse(true); // 'true'
+ * schema.parse(null); // 'null'
+ * ```
+ */
+export class CoerceStringSchema implements Schema<unknown, string> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			// Coerce to string
+			return success(String(value));
+		},
+		types: undefined as unknown as { input: unknown; output: string },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+	parse = parseMethods.parse;
+	safeParse = parseMethods.safeParse;
+}
+
+/**
+ * Create a schema that coerces values to strings.
+ * Useful for parsing form data or query parameters.
+ */
+export function coerceString(): CoerceStringSchema {
+	return new CoerceStringSchema();
+}

package/src/complex/array.ts

@@ -0,0 +1,108 @@
+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 arrays with typed elements.
+ * Validates each element and collects all validation errors with array indices in paths.
+ *
+ * @template T - The schema type for array elements
+ *
+ * @example
+ * ```typescript
+ * const tagsSchema = s.array(s.string());
+ * const tags = tagsSchema.parse(['tag1', 'tag2']);
+ *
+ * const usersSchema = s.array(s.object({
+ *   name: s.string(),
+ *   age: s.number()
+ * }));
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class ArraySchema<T extends Schema<any, any>>
+	implements Schema<Array<Infer<T>>, Array<Infer<T>>>
+{
+	description?: string;
+	private parseMethods = createParseMethods<Array<Infer<T>>>();
+
+	constructor(private itemSchema: T) {}
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (value === null) {
+				return failure([createIssue('Expected array, got null')]);
+			}
+			if (!Array.isArray(value)) {
+				return failure([createIssue(`Expected array, got ${typeof value}`)]);
+			}
+
+			const result: Infer<T>[] = [];
+			const issues: ReturnType<typeof createIssue>[] = [];
+
+			for (let i = 0; i < value.length; i++) {
+				const validation = this.itemSchema['~standard'].validate(value[i]);
+
+				// Only support synchronous validation for now
+				if (validation instanceof Promise) {
+					throw new Error('Async validation not supported');
+				}
+
+				if (validation.issues) {
+					for (const issue of validation.issues) {
+						issues.push(createIssue(issue.message, issue.path ? [i, ...issue.path] : [i]));
+					}
+				} else {
+					result.push(validation.value);
+				}
+			}
+
+			if (issues.length > 0) {
+				return failure(issues);
+			}
+
+			return success(result);
+		},
+		types: undefined as unknown as { input: Array<Infer<T>>; output: Array<Infer<T>> },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+
+	parse = this.parseMethods.parse;
+	safeParse = this.parseMethods.safeParse;
+}
+
+/**
+ * Create an array schema with typed elements.
+ *
+ * @param itemSchema - The schema for validating each array element
+ *
+ * @example
+ * ```typescript
+ * const stringArray = s.array(s.string());
+ * const tags = stringArray.parse(['tag1', 'tag2']);
+ *
+ * const userArray = s.array(s.object({
+ *   name: s.string(),
+ *   age: s.number()
+ * }));
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function array<T extends Schema<any, any>>(itemSchema: T): ArraySchema<T> {
+	return new ArraySchema(itemSchema);
+}

package/src/complex/object.ts

@@ -0,0 +1,141 @@
+import type { Schema, Infer } from '../base';
+import { createIssue, failure, success, createParseMethods } from '../base';
+import { optional, OptionalSchema } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ObjectShape = Record<string, Schema<any, any>>;
+
+// Helper to check if a schema is optional
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type IsOptional<T> = T extends OptionalSchema<any> ? true : false;
+
+// Split required and optional keys
+type RequiredKeys<T extends ObjectShape> = {
+	[K in keyof T]: IsOptional<T[K]> extends true ? never : K;
+}[keyof T];
+
+type OptionalKeys<T extends ObjectShape> = {
+	[K in keyof T]: IsOptional<T[K]> extends true ? K : never;
+}[keyof T];
+
+// Infer object shape with proper optional handling
+type InferObjectShape<T extends ObjectShape> = {
+	[K in RequiredKeys<T>]: Infer<T[K]>;
+} & {
+	[K in OptionalKeys<T>]?: Infer<T[K]>;
+};
+
+/**
+ * Schema for validating objects with typed properties.
+ * Validates each property according to its schema and collects all validation errors.
+ *
+ * @template T - The object shape definition
+ *
+ * @example
+ * ```typescript
+ * const userSchema = s.object({
+ *   name: s.string(),
+ *   age: s.number(),
+ *   email: s.string()
+ * });
+ *
+ * const user = userSchema.parse({
+ *   name: 'John',
+ *   age: 30,
+ *   email: 'john@example.com'
+ * });
+ * ```
+ */
+export class ObjectSchema<T extends ObjectShape>
+	implements Schema<InferObjectShape<T>, InferObjectShape<T>>
+{
+	description?: string;
+	private parseMethods = createParseMethods<InferObjectShape<T>>();
+
+	constructor(private shape: T) {}
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (value === null) {
+				return failure([createIssue('Expected object, got null')]);
+			}
+			if (Array.isArray(value)) {
+				return failure([createIssue('Expected object, got array')]);
+			}
+			if (typeof value !== 'object') {
+				return failure([createIssue(`Expected object, 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, schema] of Object.entries(this.shape)) {
+				const fieldValue = (value as Record<string, unknown>)[key];
+				const validation = schema['~standard'].validate(fieldValue);
+
+				// Only support synchronous validation for now
+				if (validation instanceof Promise) {
+					throw new Error('Async validation not supported');
+				}
+
+				if (validation.issues) {
+					for (const issue of validation.issues) {
+						issues.push(
+							createIssue(issue.message, issue.path ? [key, ...issue.path] : [key])
+						);
+					}
+				} else {
+					result[key] = validation.value;
+				}
+			}
+
+			if (issues.length > 0) {
+				return failure(issues);
+			}
+
+			return success(result as InferObjectShape<T>);
+		},
+		types: undefined as unknown as { input: InferObjectShape<T>; output: InferObjectShape<T> },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+
+	parse = this.parseMethods.parse;
+	safeParse = this.parseMethods.safeParse;
+}
+
+/**
+ * Create an object schema with typed properties.
+ *
+ * @param shape - Object defining the schema for each property
+ *
+ * @example
+ * ```typescript
+ * const userSchema = s.object({
+ *   name: s.string().describe('Full name'),
+ *   age: s.number().describe('Age in years'),
+ *   email: s.optional(s.string())
+ * });
+ *
+ * type User = s.infer<typeof userSchema>;
+ * const user = userSchema.parse(data);
+ * ```
+ */
+export function object<T extends ObjectShape>(shape: T): ObjectSchema<T> {
+	return new ObjectSchema(shape);
+}