atchara 0.1.1

package/dist/release/index.d.cts

@@ -0,0 +1,563 @@
+import { Schema, DeferredPrimitive, Parser, InferDeferred, LargeParseResult, LazyContext, SerializedSchema, DeferredObject, DeferredNullable, DeferredValue, DeferredTuple, DeferredRecord, DeferredUnion, DeferredArray } from '@atcharajs/core';
+export { AtcharaError, AtcharaErrorCode, AtcharaPosition, DeferredArray, DeferredNullable, DeferredObject, DeferredPrimitive, DeferredRecord, DeferredTuple, DeferredUnion, InferDeferred, InferInput, InferValue, InvalidSchema, InvalidUtf8, LargeParseResult, MissingRequired, Parser, Schema, SerializedSchema, UnexpectedCharacter, UnexpectedEof, UnexpectedField, UnionNoMatch, Unwrap, ValidationError, isAtcharaError, toBytes, wrapDeferred } from '@atcharajs/core';
+import { Readable } from 'stream';
+
+interface StringConstraints {
+    min?: number;
+    max?: number;
+    pattern?: string;
+}
+declare class StringSchema implements Schema<string, void, DeferredPrimitive<string>>, Parser<StringSchema> {
+    readonly _output: string;
+    readonly _input: void;
+    readonly _deferred: DeferredPrimitive<string>;
+    private _constraints;
+    private _parser?;
+    get schema(): StringSchema;
+    get constraints(): StringConstraints | undefined;
+    min(n: number): StringSchema;
+    max(n: number): StringSchema;
+    pattern(regex: RegExp | string): StringSchema;
+    parse(input: Uint8Array): InferDeferred<StringSchema>;
+    parseLarge(stream: Readable): Promise<LargeParseResult<StringSchema>>;
+    private getParser;
+    serializeSchema(counter: {
+        value: number;
+    } | null, _lazy?: LazyContext): SerializedSchema;
+}
+
+type ObjectOutput<T extends Record<string, Parser<Schema>>> = {
+    [K in keyof T]: T[K]['schema']['_output'];
+};
+type ObjectInput<T extends Record<string, Parser<Schema>>> = {
+    [K in keyof T]: T[K]['schema']['_input'];
+};
+type ObjectDeferred<T extends Record<string, Parser<Schema>>> = {
+    [K in keyof T]: T[K]['schema']['_deferred'];
+};
+declare class ObjectSchema<T extends Record<string, Parser<Schema>>> implements Schema<ObjectOutput<T>, ObjectInput<T>, DeferredObject<ObjectOutput<T>, ObjectDeferred<T>>> {
+    readonly _shape: T;
+    readonly _output: ObjectOutput<T>;
+    readonly _input: ObjectInput<T>;
+    readonly _deferred: DeferredObject<ObjectOutput<T>, ObjectDeferred<T>>;
+    constructor(_shape: T);
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+interface NumberConstraints {
+    min?: number;
+    max?: number;
+    gt?: number;
+    lt?: number;
+    multipleOf?: number;
+}
+declare class NumberSchema implements Schema<number, void, DeferredPrimitive<number>>, Parser<NumberSchema> {
+    readonly _output: number;
+    readonly _input: void;
+    readonly _deferred: DeferredPrimitive<number>;
+    private _constraints;
+    private _parser?;
+    get schema(): NumberSchema;
+    get constraints(): NumberConstraints | undefined;
+    min(n: number): NumberSchema;
+    max(n: number): NumberSchema;
+    gt(n: number): NumberSchema;
+    lt(n: number): NumberSchema;
+    multipleOf(n: number): NumberSchema;
+    parse(input: Uint8Array): InferDeferred<NumberSchema>;
+    parseLarge(stream: Readable): Promise<LargeParseResult<NumberSchema>>;
+    private getParser;
+    serializeSchema(counter: {
+        value: number;
+    } | null, _lazy?: LazyContext): SerializedSchema;
+}
+
+interface IntegerConstraints {
+    min?: number;
+    max?: number;
+    gt?: number;
+    lt?: number;
+    multipleOf?: number;
+}
+declare class IntegerSchema implements Schema<number, void, DeferredPrimitive<number>>, Parser<IntegerSchema> {
+    readonly _output: number;
+    readonly _input: void;
+    readonly _deferred: DeferredPrimitive<number>;
+    private _constraints;
+    private _parser?;
+    get schema(): IntegerSchema;
+    get constraints(): IntegerConstraints | undefined;
+    min(n: number): IntegerSchema;
+    max(n: number): IntegerSchema;
+    gt(n: number): IntegerSchema;
+    lt(n: number): IntegerSchema;
+    multipleOf(n: number): IntegerSchema;
+    parse(input: Uint8Array): InferDeferred<IntegerSchema>;
+    parseLarge(stream: Readable): Promise<LargeParseResult<IntegerSchema>>;
+    private getParser;
+    serializeSchema(counter: {
+        value: number;
+    } | null, _lazy?: LazyContext): SerializedSchema;
+}
+
+declare class BooleanSchema implements Schema<boolean, void, DeferredPrimitive<boolean>> {
+    readonly _output: boolean;
+    readonly _input: void;
+    readonly _deferred: DeferredPrimitive<boolean>;
+    serializeSchema(counter: {
+        value: number;
+    } | null, _lazy?: LazyContext): SerializedSchema;
+}
+
+declare class NullableSchema<T extends Parser<Schema>> implements Schema<T['schema']['_output'] | null, T['schema']['_input'] | null, DeferredNullable<T['schema']['_output']>> {
+    readonly _valueParser: T;
+    readonly _output: T['schema']['_output'] | null;
+    readonly _input: T['schema']['_input'] | null;
+    readonly _deferred: DeferredNullable<T['schema']['_output']>;
+    readonly _brand: "nullable";
+    constructor(_valueParser: T);
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+declare class OptionalSchema<T extends Parser<Schema>> implements Schema<T['schema']['_output'] | undefined, T['schema']['_input'] | undefined, T['schema']['_deferred'] | DeferredValue<undefined>> {
+    readonly _valueParser: T;
+    readonly _output: T['schema']['_output'] | undefined;
+    readonly _input: T['schema']['_input'] | undefined;
+    readonly _deferred: T['schema']['_deferred'] | DeferredValue<undefined>;
+    readonly _brand: "optional";
+    constructor(_valueParser: T);
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+declare class LiteralSchema<T extends string | number | boolean | null> implements Schema<T, T, DeferredPrimitive<T>> {
+    readonly _value: T;
+    readonly _output: T;
+    readonly _input: T;
+    readonly _deferred: DeferredPrimitive<T>;
+    constructor(_value: T);
+    serializeSchema(counter: {
+        value: number;
+    } | null, _lazy?: LazyContext): SerializedSchema;
+}
+
+type TupleOutput<T extends readonly Parser<Schema>[]> = {
+    [K in keyof T]: T[K] extends Parser<Schema> ? T[K]['schema']['_output'] : never;
+};
+type TupleInput<T extends readonly Parser<Schema>[]> = {
+    [K in keyof T]: T[K] extends Parser<Schema> ? T[K]['schema']['_input'] : never;
+};
+type TupleDeferred<T extends readonly Parser<Schema>[]> = {
+    [K in keyof T]: T[K] extends Parser<Schema> ? T[K]['schema']['_deferred'] : never;
+};
+declare class TupleSchema<T extends readonly Parser<Schema>[]> implements Schema<TupleOutput<T>, TupleInput<T>, DeferredTuple<TupleOutput<T>, TupleDeferred<T>>> {
+    readonly _elements: T;
+    readonly _output: TupleOutput<T>;
+    readonly _input: TupleInput<T>;
+    readonly _deferred: DeferredTuple<TupleOutput<T>, TupleDeferred<T>>;
+    constructor(_elements: T);
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+interface RecordConstraints {
+    min?: number;
+    max?: number;
+}
+declare class RecordSchema<T extends Parser<Schema>> implements Schema<Record<string, T['schema']['_output']>, Record<string, T['schema']['_input']>, DeferredRecord<T['schema']['_output'], T['schema']['_deferred']>>, Parser<RecordSchema<T>> {
+    readonly _valueSchema: T;
+    readonly _output: Record<string, T['schema']['_output']>;
+    readonly _input: Record<string, T['schema']['_input']>;
+    readonly _deferred: DeferredRecord<T['schema']['_output'], T['schema']['_deferred']>;
+    private _constraints;
+    private _parser?;
+    constructor(_valueSchema: T);
+    get schema(): RecordSchema<T>;
+    get constraints(): RecordConstraints | undefined;
+    min(n: number): RecordSchema<T>;
+    max(n: number): RecordSchema<T>;
+    parse(input: Uint8Array): InferDeferred<RecordSchema<T>>;
+    parseLarge(stream: Readable): Promise<LargeParseResult<RecordSchema<T>>>;
+    private getParser;
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+type UnionOutput<T extends readonly Parser<Schema>[]> = T[number]['schema']['_output'];
+type UnionInput<T extends readonly Parser<Schema>[]> = T[number]['schema']['_input'];
+declare class UnionSchema<T extends readonly [Parser<Schema>, ...Parser<Schema>[]]> implements Schema<UnionOutput<T>, UnionInput<T>, DeferredUnion<UnionOutput<T>>> {
+    readonly _variants: T;
+    readonly _output: UnionOutput<T>;
+    readonly _input: UnionInput<T>;
+    readonly _deferred: DeferredUnion<UnionOutput<T>>;
+    constructor(_variants: T);
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+interface ArrayConstraints {
+    min?: number;
+    max?: number;
+}
+declare class ArraySchema<T extends Parser<Schema>> implements Schema<T['schema']['_output'][], T['schema']['_input'][], DeferredArray<T['schema']['_output'], T['schema']['_deferred']>>, Parser<ArraySchema<T>> {
+    readonly _elements: T;
+    readonly _output: T['schema']['_output'][];
+    readonly _input: T['schema']['_input'][];
+    readonly _deferred: DeferredArray<T['schema']['_output'], T['schema']['_deferred']>;
+    private _constraints;
+    private _parser?;
+    constructor(_elements: T);
+    get schema(): ArraySchema<T>;
+    get constraints(): ArrayConstraints | undefined;
+    min(n: number): ArraySchema<T>;
+    max(n: number): ArraySchema<T>;
+    parse(input: Uint8Array): InferDeferred<ArraySchema<T>>;
+    parseLarge(stream: Readable): Promise<LargeParseResult<ArraySchema<T>>>;
+    /**
+     * Parse a JSON array from a stream, yielding each element's deferred wrapper as it is parsed.
+     * Yielded deferreds become invalid after the iterator completes.
+     */
+    parseEach(stream: Readable): AsyncIterableIterator<T['schema']['_deferred']>;
+    private getParser;
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+declare class LazySchema<T extends Parser<Schema>> implements Schema<T['schema']['_output'], T['schema']['_input'], T['schema']['_deferred']>, Parser<LazySchema<T>> {
+    private _thunk;
+    readonly _output: T['schema']['_output'];
+    readonly _input: T['schema']['_input'];
+    readonly _deferred: T['schema']['_deferred'];
+    private _resolved?;
+    private _parser?;
+    private _resolving;
+    constructor(_thunk: () => T);
+    get schema(): LazySchema<T>;
+    parse(input: Uint8Array): InferDeferred<LazySchema<T>>;
+    parseLarge(stream: Readable): Promise<LargeParseResult<LazySchema<T>>>;
+    private getParser;
+    private resolve;
+    serializeSchema(counter: {
+        value: number;
+    } | null, lazy?: LazyContext): SerializedSchema;
+}
+
+/**
+ * Native API implementation - provides tree-shakeable functional API for creating parsers
+ */
+
+type RejectOptional<T> = T extends Parser<OptionalSchema<Parser<Schema>>> ? never : T;
+/**
+ * Initialize the parser module.
+ * With native bindings, initialization is automatic. This function is kept for backwards compatibility.
+ *
+ * @returns A promise that resolves immediately
+ *
+ * @example
+ * ```ts
+ * import { initialize, object, string, number, toBytes as b } from 'atchara'
+ *
+ * await initialize()
+ *
+ * const User = object({
+ *   name: string(),
+ *   age: number()
+ * })
+ *
+ * const user = User.parse(b`{"name": "Alice", "age": 30}`)
+ * ```
+ */
+declare function initialize(): Promise<void>;
+/**
+ * Creates a parser that validates and parses JSON strings.
+ *
+ * @returns A parser for string values
+ *
+ * @example
+ * ```ts
+ * import { string, toBytes as b } from 'atchara'
+ *
+ * const parser = string()
+ * parser.parse(b`"hello"`) // "hello"
+ *
+ * // With constraints
+ * const bounded = string().min(1).max(255)
+ * ```
+ */
+declare function string(): StringSchema;
+/**
+ * Creates a parser that validates and parses JSON numbers (integers and floats).
+ *
+ * @returns A parser for number values
+ *
+ * @example
+ * ```ts
+ * import { number, toBytes as b } from 'atchara'
+ *
+ * const parser = number()
+ * parser.parse(b`42`)      // 42
+ * parser.parse(b`3.14`)    // 3.14
+ * parser.parse(b`-1.5e10`) // -1.5e10
+ *
+ * // With constraints
+ * const positive = number().min(0)
+ * const percentage = number().min(0).max(100)
+ * ```
+ */
+declare function number(): NumberSchema;
+/**
+ * Creates a parser that validates and parses JSON integers.
+ * Unlike `number()`, this rejects floating-point values.
+ *
+ * @returns A parser for integer values
+ *
+ * @example
+ * ```ts
+ * import { integer, toBytes as b } from 'atchara'
+ *
+ * const parser = integer()
+ * parser.parse(b`42`)   // 42
+ * parser.parse(b`-100`) // -100
+ * parser.parse(b`3.14`) // throws - not an integer
+ *
+ * // With constraints
+ * const natural = integer().min(0)
+ * ```
+ */
+declare function integer(): IntegerSchema;
+/**
+ * Creates a parser that validates and parses JSON booleans.
+ *
+ * @returns A parser for boolean values
+ *
+ * @example
+ * ```ts
+ * import { boolean, toBytes as b } from 'atchara'
+ *
+ * const parser = boolean()
+ * parser.parse(b`true`)  // true
+ * parser.parse(b`false`) // false
+ * ```
+ */
+declare function boolean(): Parser<BooleanSchema>;
+/**
+ * Creates a parser that accepts either the wrapped type or `null`.
+ *
+ * @param valueParser - The parser for the non-null value
+ * @returns A parser that accepts the value type or null
+ *
+ * @example
+ * ```ts
+ * import { nullable, string, toBytes as b } from 'atchara'
+ *
+ * const parser = nullable(string())
+ * parser.parse(b`"hello"`) // "hello"
+ * parser.parse(b`null`)    // null
+ *
+ * // Type is inferred as: string | null
+ * ```
+ */
+declare function nullable<T extends Parser<Schema>>(valueParser: T): Parser<NullableSchema<T>>;
+/**
+ * Marks an object field as optional, allowing it to be omitted.
+ * This should only be used within `object()` shape definitions.
+ *
+ * @param valueParser - The parser for the field value when present
+ * @returns A parser that marks the field as optional
+ *
+ * @example
+ * ```ts
+ * import { object, string, number, optional, toBytes as b } from 'atchara'
+ *
+ * const parser = object({
+ *   name: string(),
+ *   age: optional(number())
+ * })
+ *
+ * parser.parse(b`{"name":"Alice"}`)          // { name: "Alice", age: undefined }
+ * parser.parse(b`{"name":"Bob","age":30}`)   // { name: "Bob", age: 30 }
+ *
+ * // Type is inferred as: { name: string; age?: number }
+ * ```
+ */
+declare function optional<T extends Parser<Schema>>(valueParser: T): Parser<OptionalSchema<T>>;
+/**
+ * Creates a parser for JSON objects with a defined shape.
+ * Each key in the shape corresponds to an expected field in the JSON object.
+ *
+ * @param shape - An object mapping field names to their parsers
+ * @returns A parser for objects matching the shape
+ *
+ * @example
+ * ```ts
+ * import { object, number, string, optional, literal, toBytes as b } from 'atchara'
+ *
+ * const userParser = object({
+ *   id: number(),
+ *   name: string(),
+ *   email: optional(string()),
+ *   role: literal('admin')
+ * })
+ *
+ * const user = userParser.parse(b`{"id":1,"name":"Alice","role":"admin"}`)
+ * // user: { id: number; name: string; email?: string; role: "admin" }
+ * ```
+ */
+declare function object<T extends Record<string, Parser<Schema>>>(shape: T): Parser<ObjectSchema<T>>;
+/**
+ * Creates a parser for JSON arrays where all elements share the same type.
+ *
+ * @param elements - The parser for each element in the array
+ * @returns A parser for arrays of the element type
+ *
+ * @example
+ * ```ts
+ * import { array, number, toBytes as b } from 'atchara'
+ *
+ * const parser = array(number())
+ * parser.parse(b`[1,2,3]`) // [1, 2, 3]
+ *
+ * // With constraints
+ * const bounded = array(number()).min(1).max(10)
+ * ```
+ */
+declare function array<T extends Parser<Schema>>(elements: T): ArraySchema<T>;
+/**
+ * Creates a parser that only accepts a specific literal value.
+ * Useful for discriminated unions, constants, and exact value matching.
+ *
+ * @param value - The exact value to match (string, number, boolean, or null)
+ * @returns A parser that only accepts the literal value
+ *
+ * @example
+ * ```ts
+ * import { literal, union, object, number, string, toBytes as b } from 'atchara'
+ *
+ * const parser = literal('success')
+ * parser.parse(b`"success"`) // "success"
+ * parser.parse(b`"failure"`) // throws - not the expected literal
+ *
+ * // Discriminated unions
+ * const eventParser = union([
+ *   object({ type: literal('click'), x: number(), y: number() }),
+ *   object({ type: literal('keypress'), key: string() })
+ * ])
+ * ```
+ */
+declare function literal<T extends string | number | boolean | null>(value: T): Parser<LiteralSchema<T>>;
+/**
+ * Creates a parser for fixed-length arrays where each position has a specific type.
+ * Unlike `array()`, tuples have a known length and can have different types per position.
+ *
+ * @param elements - An array of parsers, one for each position in the tuple
+ * @returns A parser for tuples matching the element types
+ *
+ * @example
+ * ```ts
+ * import { tuple, number, string, boolean, toBytes as b } from 'atchara'
+ *
+ * // Coordinate pair
+ * const point = tuple([number(), number()])
+ * point.parse(b`[10,20]`) // [10, 20] as [number, number]
+ *
+ * // Mixed types
+ * const entry = tuple([string(), number(), boolean()])
+ * entry.parse(b`["key",42,true]`) // ["key", 42, true] as [string, number, boolean]
+ *
+ * // Empty tuple
+ * const empty = tuple([])
+ * empty.parse(b`[]`) // [] as []
+ * ```
+ */
+declare function tuple<T extends readonly [] | readonly [Parser<Schema>, ...Parser<Schema>[]]>(elements: T): Parser<TupleSchema<T>>;
+/**
+ * Creates a parser for objects with string keys and uniform value types.
+ * Unlike `object()`, record keys are not known at compile time.
+ *
+ * @param valueSchema - The parser for each value in the record
+ * @returns A parser for records with the value type
+ *
+ * @example
+ * ```ts
+ * import { record, number, string, toBytes as b } from 'atchara'
+ *
+ * // String-to-number mapping
+ * const scores = record(number())
+ * scores.parse(b`{"alice":100,"bob":85}`)
+ * // { alice: 100, bob: 85 } as Record<string, number>
+ *
+ * // Nested records
+ * const config = record(record(string()))
+ * config.parse(b`{"db":{"host":"localhost"}}`)
+ * ```
+ */
+declare function record<T extends Parser<Schema>>(valueSchema: T): RecordSchema<T>;
+/**
+ * Creates a parser that accepts any of the provided variant types.
+ * Variants are tried in order until one succeeds.
+ *
+ * @param variants - An array of parsers representing possible types
+ * @returns A parser that accepts any of the variant types
+ *
+ * @example
+ * ```ts
+ * import { union, string, number, object, literal, toBytes as b } from 'atchara'
+ *
+ * // Simple union
+ * const stringOrNumber = union([string(), number()])
+ * stringOrNumber.parse(b`"hello"`) // "hello"
+ * stringOrNumber.parse(b`42`)      // 42
+ *
+ * // Discriminated union (recommended for objects)
+ * const shape = union([
+ *   object({ kind: literal('circle'), radius: number() }),
+ *   object({ kind: literal('rect'), width: number(), height: number() })
+ * ])
+ *
+ * shape.parse(b`{"kind":"circle","radius":5}`)
+ * // { kind: "circle", radius: 5 }
+ * ```
+ */
+declare function union<T extends readonly [Parser<Schema>, ...Parser<Schema>[]]>(variants: {
+    [K in keyof T]: RejectOptional<T[K]>;
+} & T): Parser<UnionSchema<{ [K in keyof T]: RejectOptional<T[K]>; } & T>>;
+/**
+ * Creates a lazily-evaluated schema for recursive data structures.
+ * The schema is resolved on first use, enabling self-referential definitions.
+ *
+ * Provide the output type as a type parameter to enable recursive self-reference
+ * without a variable annotation. TypeScript resolves the return type from the
+ * type parameter alone, breaking the circular inference.
+ *
+ * @param fn - A function that returns the parser to defer to
+ * @returns A parser wrapping the lazily-resolved schema
+ *
+ * @example
+ * ```ts
+ * import { lazy, object, number, array, toBytes as b } from 'atchara'
+ *
+ * type TreeNode = { value: number; children: TreeNode[] }
+ *
+ * const Node = lazy<TreeNode>(() =>
+ *   object({
+ *     value: number(),
+ *     children: array(Node),
+ *   })
+ * )
+ *
+ * Node.parse(b`{"value": 1, "children": []}`)
+ * ```
+ */
+declare function lazy<TOutput>(fn: () => any): LazySchema<Parser<Schema<TOutput>>>;
+declare function lazy<T extends Parser<Schema>>(fn: () => T): LazySchema<T>;
+
+export { ArraySchema, IntegerSchema, LazySchema, NumberSchema, StringSchema, array, boolean, initialize, integer, lazy, literal, nullable, number, object, optional, record, string, tuple, union };