anyvali 0.3.1

package/src/schemas/optional.ts

@@ -0,0 +1,49 @@
+import type { ParseContext, SchemaNode } from "../types.js";
+import { BaseSchema, ABSENT } from "./base.js";
+
+export class OptionalSchema<
+  T extends BaseSchema<any, any> = BaseSchema,
+> extends BaseSchema<unknown, T["_output"] | undefined> {
+  /** @internal */ _inner: T;
+  /** @internal */ _isOptionalWrapper = true;
+
+  constructor(inner: T) {
+    super();
+    this._inner = inner;
+    // Inherit defaults/coercion from inner
+    this._defaultValue = inner._defaultValue as any;
+    this._coercionConfig = inner._coercionConfig;
+  }
+
+  _validate(input: unknown, ctx: ParseContext): unknown {
+    if (input === undefined || input === ABSENT) {
+      return undefined;
+    }
+    return this._inner._validate(input, ctx);
+  }
+
+  _runPipeline(input: unknown, ctx: ParseContext): unknown {
+    const isAbsent = input === undefined || input === ABSENT;
+
+    // If absent and we have a default from inner, apply it
+    if (isAbsent && this._inner._defaultValue !== ABSENT) {
+      return this._inner._runPipeline(input, ctx);
+    }
+
+    if (isAbsent) {
+      return undefined;
+    }
+
+    // Delegate to inner's pipeline for coercion etc.
+    return this._inner._runPipeline(input, ctx);
+  }
+
+  _toNode(): SchemaNode {
+    const node = {
+      kind: "optional" as const,
+      inner: this._inner._toNode(),
+    };
+    this._addDefault(node as unknown as SchemaNode);
+    return node as unknown as SchemaNode;
+  }
+}

package/src/schemas/record.ts

@@ -0,0 +1,55 @@
+import type { ParseContext, SchemaNode } from "../types.js";
+import { BaseSchema } from "./base.js";
+import { ISSUE_CODES } from "../issue-codes.js";
+import { describeType } from "../util.js";
+
+export class RecordSchema<
+  T extends BaseSchema<any, any> = BaseSchema,
+> extends BaseSchema<Record<string, unknown>, Record<string, T["_output"]>> {
+  private _valueSchema: T;
+
+  constructor(valueSchema: T) {
+    super();
+    this._valueSchema = valueSchema;
+  }
+
+  _validate(input: unknown, ctx: ParseContext): unknown {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+      ctx.issues.push({
+        code: ISSUE_CODES.INVALID_TYPE,
+        message: `Expected record, received ${describeType(input)}`,
+        path: [...ctx.path],
+        expected: "record",
+        received: describeType(input),
+      });
+      return undefined;
+    }
+
+    const obj = input as Record<string, unknown>;
+    const result: Record<string, unknown> = Object.create(null);
+
+    for (const [key, value] of Object.entries(obj)) {
+      ctx.path.push(key);
+      Object.defineProperty(result, key, {
+        value: this._valueSchema._runPipeline(value, ctx),
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+      ctx.path.pop();
+    }
+
+    Object.setPrototypeOf(result, Object.prototype);
+
+    return result;
+  }
+
+  _toNode(): SchemaNode {
+    const node = {
+      kind: "record" as const,
+      valueSchema: this._valueSchema._toNode(),
+    };
+    this._addDefault(node as unknown as SchemaNode);
+    return node as unknown as SchemaNode;
+  }
+}

package/src/schemas/ref.ts

@@ -0,0 +1,35 @@
+import type { ParseContext, SchemaNode } from "../types.js";
+import { BaseSchema } from "./base.js";
+import { ISSUE_CODES } from "../issue-codes.js";
+
+export class RefSchema extends BaseSchema<unknown, unknown> {
+  private _ref: string;
+  private _resolver?: () => BaseSchema;
+
+  constructor(ref: string, resolver?: () => BaseSchema) {
+    super();
+    this._ref = ref;
+    this._resolver = resolver;
+  }
+
+  _validate(input: unknown, ctx: ParseContext): unknown {
+    if (this._resolver) {
+      const resolved = this._resolver();
+      return resolved._validate(input, ctx);
+    }
+
+    ctx.issues.push({
+      code: ISSUE_CODES.UNSUPPORTED_SCHEMA_KIND,
+      message: `Unresolved ref: ${this._ref}`,
+      path: [...ctx.path],
+    });
+    return undefined;
+  }
+
+  _toNode(): SchemaNode {
+    return {
+      kind: "ref" as const,
+      ref: this._ref,
+    } as unknown as SchemaNode;
+  }
+}

package/src/schemas/string.ts

@@ -0,0 +1,192 @@
+import type { ParseContext, SchemaNode, StringFormat } from "../types.js";
+import { BaseSchema } from "./base.js";
+import { ISSUE_CODES } from "../issue-codes.js";
+import { validateFormat } from "../format/validators.js";
+import { describeType } from "../util.js";
+
+export class StringSchema extends BaseSchema<string, string> {
+  private _minLength?: number;
+  private _maxLength?: number;
+  private _pattern?: string;
+  private _startsWith?: string;
+  private _endsWith?: string;
+  private _includes?: string;
+  private _format?: StringFormat;
+  /**
+   * Cached compiled pattern. `undefined` = not yet compiled, `null` =
+   * compilation failed (invalid pattern). Avoids recompiling on every value.
+   */
+  private _patternRe?: RegExp | null;
+
+  _getCoercionTarget(): string {
+    return "string";
+  }
+
+  minLength(n: number): this {
+    const clone = this._clone();
+    clone._minLength = n;
+    return clone;
+  }
+
+  maxLength(n: number): this {
+    const clone = this._clone();
+    clone._maxLength = n;
+    return clone;
+  }
+
+  pattern(p: string): this {
+    const clone = this._clone();
+    clone._pattern = p;
+    // Reset cached compilation inherited from the source via _clone().
+    clone._patternRe = undefined;
+    return clone;
+  }
+
+  /** Lazily compile and cache the pattern. Returns null if invalid. */
+  private _getPatternRe(): RegExp | null {
+    if (this._patternRe !== undefined) return this._patternRe;
+    try {
+      this._patternRe = new RegExp(this._pattern as string);
+    } catch {
+      this._patternRe = null;
+    }
+    return this._patternRe;
+  }
+
+  startsWith(s: string): this {
+    const clone = this._clone();
+    clone._startsWith = s;
+    return clone;
+  }
+
+  endsWith(s: string): this {
+    const clone = this._clone();
+    clone._endsWith = s;
+    return clone;
+  }
+
+  includes(s: string): this {
+    const clone = this._clone();
+    clone._includes = s;
+    return clone;
+  }
+
+  format(f: StringFormat): this {
+    const clone = this._clone();
+    clone._format = f;
+    return clone;
+  }
+
+  _validate(input: unknown, ctx: ParseContext): unknown {
+    if (typeof input !== "string") {
+      ctx.issues.push({
+        code: ISSUE_CODES.INVALID_TYPE,
+        message: `Expected string, received ${describeType(input)}`,
+        path: [...ctx.path],
+        expected: "string",
+        received: describeType(input),
+      });
+      return undefined;
+    }
+
+    const val = input;
+    const length = Array.from(val).length;
+
+    if (this._minLength !== undefined && length < this._minLength) {
+      ctx.issues.push({
+        code: ISSUE_CODES.TOO_SMALL,
+        message: `String must have at least ${this._minLength} character(s)`,
+        path: [...ctx.path],
+        expected: String(this._minLength),
+        received: String(length),
+      });
+    }
+
+    if (this._maxLength !== undefined && length > this._maxLength) {
+      ctx.issues.push({
+        code: ISSUE_CODES.TOO_LARGE,
+        message: `String must have at most ${this._maxLength} character(s)`,
+        path: [...ctx.path],
+        expected: String(this._maxLength),
+        received: String(length),
+      });
+    }
+
+    if (this._pattern !== undefined) {
+      const re = this._getPatternRe();
+      if (re === null) {
+        // Invalid regex pattern - treat as validation failure
+        ctx.issues.push({
+          code: ISSUE_CODES.INVALID_STRING,
+          message: `Invalid regex pattern: ${this._pattern}`,
+          path: [...ctx.path],
+          expected: this._pattern,
+          received: val,
+        });
+      } else if (!re.test(val)) {
+        ctx.issues.push({
+          code: ISSUE_CODES.INVALID_STRING,
+          message: `String does not match pattern: ${this._pattern}`,
+          path: [...ctx.path],
+          expected: this._pattern,
+          received: val,
+        });
+      }
+    }
+
+    if (this._startsWith !== undefined && !val.startsWith(this._startsWith)) {
+      ctx.issues.push({
+        code: ISSUE_CODES.INVALID_STRING,
+        message: `String must start with "${this._startsWith}"`,
+        path: [...ctx.path],
+        expected: this._startsWith,
+        received: val,
+      });
+    }
+
+    if (this._endsWith !== undefined && !val.endsWith(this._endsWith)) {
+      ctx.issues.push({
+        code: ISSUE_CODES.INVALID_STRING,
+        message: `String must end with "${this._endsWith}"`,
+        path: [...ctx.path],
+        expected: this._endsWith,
+        received: val,
+      });
+    }
+
+    if (this._includes !== undefined && !val.includes(this._includes)) {
+      ctx.issues.push({
+        code: ISSUE_CODES.INVALID_STRING,
+        message: `String must include "${this._includes}"`,
+        path: [...ctx.path],
+        expected: this._includes,
+        received: val,
+      });
+    }
+
+    if (this._format !== undefined && !validateFormat(val, this._format)) {
+      ctx.issues.push({
+        code: ISSUE_CODES.INVALID_STRING,
+        message: `Invalid ${this._format} format`,
+        path: [...ctx.path],
+        expected: this._format,
+        received: val,
+      });
+    }
+
+    return val;
+  }
+
+  _toNode(): SchemaNode {
+    const node: Record<string, unknown> = { kind: "string" };
+    if (this._minLength !== undefined) node.minLength = this._minLength;
+    if (this._maxLength !== undefined) node.maxLength = this._maxLength;
+    if (this._pattern !== undefined) node.pattern = this._pattern;
+    if (this._startsWith !== undefined) node.startsWith = this._startsWith;
+    if (this._endsWith !== undefined) node.endsWith = this._endsWith;
+    if (this._includes !== undefined) node.includes = this._includes;
+    if (this._format !== undefined) node.format = this._format;
+    this._addDefault(node as unknown as SchemaNode);
+    return node as unknown as SchemaNode;
+  }
+}

package/src/schemas/tuple.ts

@@ -0,0 +1,74 @@
+import type { ParseContext, SchemaNode } from "../types.js";
+import { BaseSchema } from "./base.js";
+import { ISSUE_CODES } from "../issue-codes.js";
+import { describeType } from "../util.js";
+
+/** Map a tuple of schemas to a tuple of their output types. */
+type InferTuple<T extends BaseSchema<any, any>[]> = {
+  [K in keyof T]: T[K]["_output"];
+};
+
+export class TupleSchema<
+  T extends BaseSchema<any, any>[] = BaseSchema[],
+> extends BaseSchema<unknown[], InferTuple<T>> {
+  private _items: T;
+
+  constructor(items: [...T]) {
+    super();
+    this._items = items as T;
+  }
+
+  _validate(input: unknown, ctx: ParseContext): unknown {
+    if (!Array.isArray(input)) {
+      ctx.issues.push({
+        code: ISSUE_CODES.INVALID_TYPE,
+        message: `Expected tuple, received ${describeType(input)}`,
+        path: [...ctx.path],
+        expected: "tuple",
+        received: describeType(input),
+      });
+      return undefined;
+    }
+
+    if (input.length < this._items.length) {
+      ctx.issues.push({
+        code: ISSUE_CODES.TOO_SMALL,
+        message: `Tuple must have exactly ${this._items.length} element(s), received ${input.length}`,
+        path: [...ctx.path],
+        expected: String(this._items.length),
+        received: String(input.length),
+      });
+      return undefined;
+    }
+
+    if (input.length > this._items.length) {
+      ctx.issues.push({
+        code: ISSUE_CODES.TOO_LARGE,
+        message: `Tuple must have exactly ${this._items.length} element(s), received ${input.length}`,
+        path: [...ctx.path],
+        expected: String(this._items.length),
+        received: String(input.length),
+      });
+      return undefined;
+    }
+
+    const result: unknown[] = [];
+    for (let i = 0; i < this._items.length; i++) {
+      ctx.path.push(i);
+      const val = this._items[i]._runPipeline(input[i], ctx);
+      result.push(val);
+      ctx.path.pop();
+    }
+
+    return result;
+  }
+
+  _toNode(): SchemaNode {
+    const node = {
+      kind: "tuple" as const,
+      elements: this._items.map((s) => s._toNode()),
+    };
+    this._addDefault(node as unknown as SchemaNode);
+    return node as unknown as SchemaNode;
+  }
+}

package/src/schemas/union.ts

@@ -0,0 +1,53 @@
+import type { ParseContext, SchemaNode } from "../types.js";
+import { BaseSchema } from "./base.js";
+import { ISSUE_CODES } from "../issue-codes.js";
+import { describeType } from "../util.js";
+
+export class UnionSchema<
+  T extends BaseSchema<any, any>[] = BaseSchema[],
+> extends BaseSchema<unknown, T[number]["_output"]> {
+  private _variants: T;
+
+  constructor(variants: [...T]) {
+    super();
+    this._variants = variants as T;
+  }
+
+  _validate(input: unknown, ctx: ParseContext): unknown {
+    for (const variant of this._variants) {
+      const innerCtx: ParseContext = {
+        path: [...ctx.path],
+        issues: [],
+        // Propagate recursion depth and circular-reference tracking so the
+        // depth guard is not reset (and bypassed) at each union boundary.
+        definitions: ctx.definitions,
+        seen: ctx.seen,
+        depth: ctx.depth,
+      };
+      const result = variant._runPipeline(input, innerCtx);
+      if (innerCtx.issues.length === 0) {
+        return result;
+      }
+    }
+
+    const variantKinds = this._variants.map((v) => v._toNode().kind);
+    ctx.issues.push({
+      code: ISSUE_CODES.INVALID_UNION,
+      message: `Input did not match any variant of the union`,
+      path: [...ctx.path],
+      expected: variantKinds.join(" | "),
+      received: describeType(input),
+    });
+
+    return undefined;
+  }
+
+  _toNode(): SchemaNode {
+    const node = {
+      kind: "union" as const,
+      variants: this._variants.map((v) => v._toNode()),
+    };
+    this._addDefault(node as unknown as SchemaNode);
+    return node as unknown as SchemaNode;
+  }
+}

package/src/schemas/unknown.ts

@@ -0,0 +1,14 @@
+import type { ParseContext, SchemaNode } from "../types.js";
+import { BaseSchema } from "./base.js";
+
+export class UnknownSchema extends BaseSchema<unknown, unknown> {
+  _validate(input: unknown, _ctx: ParseContext): unknown {
+    return input;
+  }
+
+  _toNode(): SchemaNode {
+    const node: SchemaNode = { kind: "unknown" } as SchemaNode;
+    this._addDefault(node);
+    return node;
+  }
+}

package/src/types.ts

@@ -0,0 +1,239 @@
+// ---- Schema Node (interchange JSON representation) ----
+
+export type SchemaKind =
+  | "any"
+  | "unknown"
+  | "never"
+  | "null"
+  | "bool"
+  | "string"
+  | "number"
+  | "int"
+  | "float32"
+  | "float64"
+  | "int8"
+  | "int16"
+  | "int32"
+  | "int64"
+  | "uint8"
+  | "uint16"
+  | "uint32"
+  | "uint64"
+  | "literal"
+  | "enum"
+  | "array"
+  | "tuple"
+  | "object"
+  | "record"
+  | "union"
+  | "intersection"
+  | "optional"
+  | "nullable"
+  | "ref";
+
+export interface MetadataOptions {
+  replace?: boolean;
+}
+
+export interface DescribeOptions {
+  title?: string;
+  deprecated?: boolean;
+  deprecatedMessage?: string;
+  notStable?: boolean;
+  since?: string;
+  sensitive?: boolean;
+  readonly?: boolean;
+  writeonly?: boolean;
+  examples?: unknown[];
+}
+
+export interface SchemaNodeBase {
+  kind: SchemaKind;
+  default?: unknown;
+  coerce?: CoercionConfig | string | string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface CoercionConfig {
+  from?: string;
+  trim?: boolean;
+  lower?: boolean;
+  upper?: boolean;
+}
+
+// String node
+export interface StringSchemaNode extends SchemaNodeBase {
+  kind: "string";
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  startsWith?: string;
+  endsWith?: string;
+  includes?: string;
+  format?: StringFormat;
+}
+
+export type StringFormat =
+  | "email"
+  | "url"
+  | "uuid"
+  | "ipv4"
+  | "ipv6"
+  | "date"
+  | "date-time";
+
+// Numeric nodes
+export interface NumericSchemaNode extends SchemaNodeBase {
+  kind:
+    | "number"
+    | "int"
+    | "float32"
+    | "float64"
+    | "int8"
+    | "int16"
+    | "int32"
+    | "int64"
+    | "uint8"
+    | "uint16"
+    | "uint32"
+    | "uint64";
+  min?: number;
+  max?: number;
+  exclusiveMin?: number;
+  exclusiveMax?: number;
+  multipleOf?: number;
+}
+
+// Simple nodes
+export interface SimpleSchemaNode extends SchemaNodeBase {
+  kind: "any" | "unknown" | "never" | "null" | "bool";
+}
+
+// Literal node
+export interface LiteralSchemaNode extends SchemaNodeBase {
+  kind: "literal";
+  value: string | number | boolean | null;
+}
+
+// Enum node
+export interface EnumSchemaNode extends SchemaNodeBase {
+  kind: "enum";
+  values: (string | number)[];
+}
+
+// Array node
+export interface ArraySchemaNode extends SchemaNodeBase {
+  kind: "array";
+  items: SchemaNode;
+  minItems?: number;
+  maxItems?: number;
+}
+
+// Tuple node
+export interface TupleSchemaNode extends SchemaNodeBase {
+  kind: "tuple";
+  items: SchemaNode[];
+}
+
+// Object node
+export interface ObjectSchemaNode extends SchemaNodeBase {
+  kind: "object";
+  properties: Record<string, SchemaNode>;
+  required: string[];
+  unknownKeys?: UnknownKeyMode;
+}
+
+// Record node
+export interface RecordSchemaNode extends SchemaNodeBase {
+  kind: "record";
+  valueSchema: SchemaNode;
+}
+
+// Union node
+export interface UnionSchemaNode extends SchemaNodeBase {
+  kind: "union";
+  variants: SchemaNode[];
+}
+
+// Intersection node
+export interface IntersectionSchemaNode extends SchemaNodeBase {
+  kind: "intersection";
+  allOf: SchemaNode[];
+}
+
+// Optional node
+export interface OptionalSchemaNode extends SchemaNodeBase {
+  kind: "optional";
+  inner: SchemaNode;
+}
+
+// Nullable node
+export interface NullableSchemaNode extends SchemaNodeBase {
+  kind: "nullable";
+  inner: SchemaNode;
+}
+
+// Ref node
+export interface RefSchemaNode extends SchemaNodeBase {
+  kind: "ref";
+  ref: string;
+}
+
+export type SchemaNode =
+  | StringSchemaNode
+  | NumericSchemaNode
+  | SimpleSchemaNode
+  | LiteralSchemaNode
+  | EnumSchemaNode
+  | ArraySchemaNode
+  | TupleSchemaNode
+  | ObjectSchemaNode
+  | RecordSchemaNode
+  | UnionSchemaNode
+  | IntersectionSchemaNode
+  | OptionalSchemaNode
+  | NullableSchemaNode
+  | RefSchemaNode;
+
+// ---- Parse Result ----
+
+export type ParseResult<T> =
+  | { success: true; data: T }
+  | { success: false; issues: ValidationIssue[] };
+
+export interface ValidationIssue {
+  code: string;
+  message: string;
+  path: (string | number)[];
+  expected?: string;
+  received?: string;
+  meta?: Record<string, unknown>;
+}
+
+// ---- Interchange Document ----
+
+export interface AnyValiDocument {
+  anyvaliVersion: string;
+  schemaVersion: string;
+  root: SchemaNode;
+  definitions: Record<string, SchemaNode>;
+  extensions: Record<string, Record<string, unknown>>;
+}
+
+// ---- Modes ----
+
+export type ExportMode = "portable" | "extended";
+
+export type UnknownKeyMode = "reject" | "strip" | "allow";
+
+// ---- Parse Context (internal) ----
+
+export interface ParseContext {
+  path: (string | number)[];
+  issues: ValidationIssue[];
+  definitions?: Record<string, SchemaNode>;
+  /** Tracks objects already being validated to detect circular references. */
+  seen?: WeakSet<object>;
+  /** Current recursion depth, used to bound unbounded recursion (DoS guard). */
+  depth?: number;
+}