@agentuity/schema 0.0.69

package/src/primitives/boolean.ts

@@ -0,0 +1,60 @@
+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<boolean>();
+
+/**
+ * Schema for validating boolean values.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.boolean();
+ * const active = schema.parse(true); // true
+ * schema.parse('true'); // throws ValidationError
+ * ```
+ */
+export class BooleanSchema implements Schema<boolean, boolean> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (typeof value !== 'boolean') {
+				return failure([createIssue(`Expected boolean, got ${typeof value}`)]);
+			}
+			return success(value);
+		},
+		types: undefined as unknown as { input: boolean; 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 boolean schema.
+ *
+ * @example
+ * ```typescript
+ * const activeSchema = s.boolean().describe('Account status');
+ * const active = activeSchema.parse(true);
+ * ```
+ */
+export function boolean(): BooleanSchema {
+	return new BooleanSchema();
+}

package/src/primitives/null.ts

@@ -0,0 +1,47 @@
+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<null>();
+
+/**
+ * Schema for validating null values.
+ */
+export class NullSchema implements Schema<null, null> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (value !== null) {
+				return failure([createIssue(`Expected null, got ${typeof value}`)]);
+			}
+			return success(value);
+		},
+		types: undefined as unknown as { input: null; output: null },
+	};
+
+	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 null schema.
+ */
+export function null_(): NullSchema {
+	return new NullSchema();
+}

package/src/primitives/number.ts

@@ -0,0 +1,141 @@
+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 for validating number values.
+ * Rejects NaN values.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.number();
+ * const age = schema.parse(30); // 30
+ * schema.parse('30'); // throws ValidationError
+ * schema.parse(NaN); // throws ValidationError
+ * ```
+ */
+export class NumberSchema implements Schema<number, number> {
+	description?: string;
+	private _finite = false;
+	private _min?: number;
+	private _max?: number;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (typeof value !== 'number' || Number.isNaN(value)) {
+				return failure([createIssue(`Expected number, got ${typeof value}`)]);
+			}
+			if (this._finite && !Number.isFinite(value)) {
+				return failure([createIssue('Expected finite number (not Infinity or -Infinity)')]);
+			}
+			if (this._min !== undefined && value < this._min) {
+				return failure([createIssue(`Expected number >= ${this._min}, got ${value}`)]);
+			}
+			if (this._max !== undefined && value > this._max) {
+				return failure([createIssue(`Expected number <= ${this._max}, got ${value}`)]);
+			}
+			return success(value);
+		},
+		types: undefined as unknown as { input: number; output: number },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	/**
+	 * Require the number to be finite (not Infinity, -Infinity, or NaN).
+	 *
+	 * @example
+	 * ```typescript
+	 * const schema = s.number().finite();
+	 * schema.parse(123); // 123
+	 * schema.parse(Infinity); // throws ValidationError
+	 * schema.parse(-Infinity); // throws ValidationError
+	 * ```
+	 */
+	finite(): NumberSchema {
+		const clone = this._clone();
+		clone._finite = true;
+		return clone;
+	}
+
+	/**
+	 * Set minimum value (inclusive).
+	 *
+	 * @example
+	 * ```typescript
+	 * const schema = s.number().min(0);
+	 * schema.parse(5); // 5
+	 * schema.parse(-1); // throws ValidationError
+	 * ```
+	 */
+	min(value: number): NumberSchema {
+		const clone = this._clone();
+		clone._min = value;
+		return clone;
+	}
+
+	/**
+	 * Set maximum value (inclusive).
+	 *
+	 * @example
+	 * ```typescript
+	 * const schema = s.number().max(100);
+	 * schema.parse(50); // 50
+	 * schema.parse(101); // throws ValidationError
+	 * ```
+	 */
+	max(value: number): NumberSchema {
+		const clone = this._clone();
+		clone._max = value;
+		return clone;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+
+	private _clone(): NumberSchema {
+		const clone = new NumberSchema();
+		clone.description = this.description;
+		clone._finite = this._finite;
+		clone._min = this._min;
+		clone._max = this._max;
+		return clone;
+	}
+
+	parse = parseMethods.parse;
+	safeParse = parseMethods.safeParse;
+}
+
+/**
+ * Create a number schema.
+ *
+ * @example
+ * ```typescript
+ * const ageSchema = s.number().describe('User age');
+ * const age = ageSchema.parse(30);
+ *
+ * const finiteSchema = s.number().finite();
+ * finiteSchema.parse(123); // OK
+ * finiteSchema.parse(Infinity); // throws
+ *
+ * const rangeSchema = s.number().min(0).max(100);
+ * rangeSchema.parse(50); // OK
+ * rangeSchema.parse(101); // throws
+ * ```
+ */
+export function number(): NumberSchema {
+	return new NumberSchema();
+}

package/src/primitives/string.ts

@@ -0,0 +1,113 @@
+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<string>();
+
+/**
+ * Schema for validating string values.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.string();
+ * const name = schema.parse('John'); // "John"
+ * schema.parse(123); // throws ValidationError
+ * ```
+ */
+export class StringSchema implements Schema<string, string> {
+	description?: string;
+	private _min?: number;
+	private _max?: number;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (typeof value !== 'string') {
+				return failure([createIssue(`Expected string, got ${typeof value}`)]);
+			}
+			if (this._min !== undefined && value.length < this._min) {
+				return failure([
+					createIssue(`String must be at least ${this._min} characters, got ${value.length}`),
+				]);
+			}
+			if (this._max !== undefined && value.length > this._max) {
+				return failure([
+					createIssue(`String must be at most ${this._max} characters, got ${value.length}`),
+				]);
+			}
+			return success(value);
+		},
+		types: undefined as unknown as { input: string; output: string },
+	};
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	/**
+	 * Set minimum length.
+	 *
+	 * @example
+	 * ```typescript
+	 * const schema = s.string().min(3);
+	 * schema.parse('hello'); // "hello"
+	 * schema.parse('hi'); // throws ValidationError
+	 * ```
+	 */
+	min(length: number): StringSchema {
+		const clone = this._clone();
+		clone._min = length;
+		return clone;
+	}
+
+	/**
+	 * Set maximum length.
+	 *
+	 * @example
+	 * ```typescript
+	 * const schema = s.string().max(10);
+	 * schema.parse('hello'); // "hello"
+	 * schema.parse('hello world'); // throws ValidationError
+	 * ```
+	 */
+	max(length: number): StringSchema {
+		const clone = this._clone();
+		clone._max = length;
+		return clone;
+	}
+
+	optional() {
+		return optional(this);
+	}
+
+	nullable() {
+		return nullable(this);
+	}
+
+	private _clone(): StringSchema {
+		const clone = new StringSchema();
+		clone.description = this.description;
+		clone._min = this._min;
+		clone._max = this._max;
+		return clone;
+	}
+
+	parse = parseMethods.parse;
+	safeParse = parseMethods.safeParse;
+}
+
+/**
+ * Create a string schema.
+ *
+ * @example
+ * ```typescript
+ * const nameSchema = s.string().describe('User name');
+ * const name = nameSchema.parse('John');
+ * ```
+ */
+export function string(): StringSchema {
+	return new StringSchema();
+}

package/src/primitives/undefined.ts

@@ -0,0 +1,47 @@
+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<undefined>();
+
+/**
+ * Schema for validating undefined values.
+ */
+export class UndefinedSchema implements Schema<undefined, undefined> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (value !== undefined) {
+				return failure([createIssue(`Expected undefined, got ${typeof value}`)]);
+			}
+			return success(value);
+		},
+		types: undefined as unknown as { input: undefined; output: undefined },
+	};
+
+	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 undefined schema.
+ */
+export function undefined_(): UndefinedSchema {
+	return new UndefinedSchema();
+}

package/src/primitives/unknown.ts

@@ -0,0 +1,63 @@
+import type { Schema } from '../base';
+import { success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+const parseMethods = createParseMethods<unknown>();
+
+/**
+ * Schema that accepts any value with type-safe unknown.
+ * Returns the value as-is without validation.
+ * Use this when you want to accept any value but force type checking at usage site.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.unknown();
+ * const value = schema.parse(123); // unknown
+ * const value2 = schema.parse('hello'); // unknown
+ * const value3 = schema.parse(null); // unknown
+ *
+ * // Forces type narrowing
+ * if (typeof value === 'string') {
+ *   console.log(value.toUpperCase());
+ * }
+ * ```
+ */
+export class UnknownSchema implements Schema<unknown, unknown> {
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => success(value),
+		types: undefined as unknown as { input: unknown; output: unknown },
+	};
+
+	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 unknown schema that accepts any value.
+ *
+ * @example
+ * ```typescript
+ * const schema = s.unknown();
+ * const value = schema.parse(anything); // Type is unknown
+ * ```
+ */
+export function unknown(): UnknownSchema {
+	return new UnknownSchema();
+}

package/src/utils/literal.ts

@@ -0,0 +1,71 @@
+import type { Schema } from '../base';
+import { createIssue, failure, success, createParseMethods } from '../base';
+import { optional } from '../utils/optional';
+import { nullable } from '../utils/nullable';
+
+/**
+ * Schema for validating exact literal values.
+ *
+ * @template T - The exact value type
+ *
+ * @example
+ * ```typescript
+ * const adminSchema = s.literal('admin');
+ * adminSchema.parse('admin'); // 'admin'
+ * adminSchema.parse('user'); // throws ValidationError
+ * ```
+ */
+export class LiteralSchema<T extends string | number | boolean> implements Schema<T, T> {
+	description?: string;
+	private parseMethods = createParseMethods<T>();
+
+	constructor(private value: T) {}
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (input: unknown) => {
+			if (input !== this.value) {
+				return failure([
+					createIssue(
+						`Expected literal value ${JSON.stringify(this.value)}, got ${JSON.stringify(input)}`
+					),
+				]);
+			}
+			return success(this.value);
+		},
+		types: undefined as unknown as { input: T; output: 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 a schema for an exact literal value.
+ *
+ * @param value - The exact value to match
+ *
+ * @example
+ * ```typescript
+ * const adminRole = s.literal('admin');
+ * const maxValue = s.literal(100);
+ * const enabled = s.literal(true);
+ * ```
+ */
+export function literal<T extends string | number | boolean>(value: T): LiteralSchema<T> {
+	return new LiteralSchema(value);
+}

package/src/utils/nullable.ts

@@ -0,0 +1,80 @@
+import type { Schema, Infer } from '../base';
+import { success, createParseMethods } from '../base';
+
+/**
+ * Schema for nullable values (T | null).
+ * Accepts null or the wrapped schema's type.
+ *
+ * @template T - The wrapped schema type
+ *
+ * @example
+ * ```typescript
+ * const schema = s.nullable(s.string());
+ * schema.parse('hello'); // 'hello'
+ * schema.parse(null); // null
+ * schema.parse(123); // throws ValidationError
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class NullableSchema<T extends Schema<any, any>>
+	implements Schema<Infer<T> | null, Infer<T> | null>
+{
+	readonly schema: T;
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (value === null) {
+				return success(null as Infer<T> | null);
+			}
+			return this.schema['~standard'].validate(value);
+		},
+		types: undefined as unknown as { input: Infer<T> | null; output: Infer<T> | null },
+	};
+
+	// Type-safe parse methods for this instance
+	private parseMethods = createParseMethods<Infer<T> | null>();
+
+	constructor(schema: T) {
+		this.schema = schema;
+	}
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional(): Schema<Infer<T> | null | undefined, Infer<T> | null | undefined> {
+		// Import here to avoid circular dependency
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const { optional } = require('./optional.js');
+		return optional(this);
+	}
+
+	nullable() {
+		return this; // Already nullable
+	}
+
+	parse = this.parseMethods.parse;
+	safeParse = this.parseMethods.safeParse;
+}
+
+/**
+ * Make a schema nullable (T | null).
+ *
+ * @param schema - The schema to make nullable
+ *
+ * @example
+ * ```typescript
+ * const userSchema = s.object({
+ *   name: s.string(),
+ *   bio: s.nullable(s.string())
+ * });
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function nullable<T extends Schema<any, any>>(schema: T): NullableSchema<T> {
+	return new NullableSchema(schema);
+}

package/src/utils/optional.ts

@@ -0,0 +1,80 @@
+import type { Schema, Infer } from '../base';
+import { success, createParseMethods } from '../base';
+
+/**
+ * Schema for optional values (T | undefined).
+ * Accepts undefined or the wrapped schema's type.
+ *
+ * @template T - The wrapped schema type
+ *
+ * @example
+ * ```typescript
+ * const schema = s.optional(s.string());
+ * schema.parse('hello'); // 'hello'
+ * schema.parse(undefined); // undefined
+ * schema.parse(123); // throws ValidationError
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class OptionalSchema<T extends Schema<any, any>>
+	implements Schema<Infer<T> | undefined, Infer<T> | undefined>
+{
+	readonly schema: T;
+	description?: string;
+
+	readonly '~standard' = {
+		version: 1 as const,
+		vendor: 'agentuity',
+		validate: (value: unknown) => {
+			if (value === undefined) {
+				return success(undefined as Infer<T> | undefined);
+			}
+			return this.schema['~standard'].validate(value);
+		},
+		types: undefined as unknown as { input: Infer<T> | undefined; output: Infer<T> | undefined },
+	};
+
+	// Type-safe parse methods for this instance
+	private parseMethods = createParseMethods<Infer<T> | undefined>();
+
+	constructor(schema: T) {
+		this.schema = schema;
+	}
+
+	describe(description: string): this {
+		this.description = description;
+		return this;
+	}
+
+	optional() {
+		return this; // Already optional
+	}
+
+	nullable(): Schema<Infer<T> | undefined | null, Infer<T> | undefined | null> {
+		// Import here to avoid circular dependency
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const { nullable } = require('./nullable.js');
+		return nullable(this);
+	}
+
+	parse = this.parseMethods.parse;
+	safeParse = this.parseMethods.safeParse;
+}
+
+/**
+ * Make a schema optional (T | undefined).
+ *
+ * @param schema - The schema to make optional
+ *
+ * @example
+ * ```typescript
+ * const userSchema = s.object({
+ *   name: s.string(),
+ *   nickname: s.optional(s.string())
+ * });
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function optional<T extends Schema<any, any>>(schema: T): OptionalSchema<T> {
+	return new OptionalSchema(schema);
+}