typesea 0.2.0 → 0.3.1

package/dist/decoder/index.d.ts

@@ -1,12 +1,15 @@
 import type { Guard, Presence, RuntimeValue } from "../guard/index.js";
 import type { CheckResult } from "../issue/index.js";
 type DecodeRunner<TValue> = (value: unknown) => CheckResult<TValue>;
+type EncodeRunner<TValue> = (value: unknown) => CheckResult<TValue>;
+type DefaultInput<TValue> = TValue | (() => TValue);
 /**
  * @brief Private runner slot for decoder instances.
  * @details A symbol slot keeps the public object small while avoiding accidental
  * collision with user-visible properties.
  */
 declare const DecoderRunSymbol: unique symbol;
+declare const CodecEncodeSymbol: unique symbol;
 export type DecodeSource = Guard<unknown, Presence> | Decoder<unknown>;
 export type InferDecoder<TSource> = TSource extends Decoder<infer TValue> ? TValue : TSource extends Guard<infer TValue, infer TPresence> ? RuntimeValue<TValue, TPresence> : never;
 /**
@@ -18,6 +21,12 @@ export interface Decoder<TValue> {
     decode(value: unknown): CheckResult<TValue>;
     transform<TNext>(mapper: (value: TValue) => TNext): BaseDecoder<TNext>;
     pipe<TNext extends DecodeSource>(next: TNext): BaseDecoder<InferDecoder<TNext>>;
+    default(fallback: DefaultInput<TValue>): BaseDecoder<TValue>;
+    prefault(fallback: unknown): BaseDecoder<TValue>;
+    catch(fallback: DefaultInput<TValue>): BaseDecoder<TValue>;
+}
+export interface Codec<TEncoded, TDecoded> extends Decoder<TDecoded> {
+    encode(value: TDecoded): CheckResult<TEncoded>;
 }
 /**
  * @brief Frozen decoder wrapper around one runner function.
@@ -30,6 +39,19 @@ export declare class BaseDecoder<TValue> implements Decoder<TValue> {
     decode(this: unknown, value: unknown): CheckResult<TValue>;
     transform<TNext>(mapper: (value: TValue) => TNext): BaseDecoder<TNext>;
     pipe<TNext extends DecodeSource>(next: TNext): BaseDecoder<InferDecoder<TNext>>;
+    default(fallback: DefaultInput<TValue>): BaseDecoder<TValue>;
+    prefault(fallback: unknown): BaseDecoder<TValue>;
+    catch(fallback: DefaultInput<TValue>): BaseDecoder<TValue>;
+}
+/**
+ * @brief Frozen bidirectional codec wrapper.
+ * @details Decode uses the BaseDecoder runner. Encode has a separate private
+ * symbol so detached encode calls fail through the same receiver discipline.
+ */
+export declare class BaseCodec<TEncoded, TDecoded> extends BaseDecoder<TDecoded> implements Codec<TEncoded, TDecoded> {
+    private readonly [CodecEncodeSymbol];
+    constructor(decodeRun: DecodeRunner<TDecoded>, encodeRun: EncodeRunner<TEncoded>);
+    encode(this: unknown, value: TDecoded): CheckResult<TEncoded>;
 }
 /**
  * @brief Wrap a guard or decoder as a synchronous decoder pipeline.
@@ -58,6 +80,38 @@ export declare function transform<TValue, TNext>(source: Decoder<TValue>, mapper
  * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function pipe<TNext extends DecodeSource>(source: DecodeSource, next: TNext): BaseDecoder<InferDecoder<TNext>>;
+/**
+ * @brief Add a short-circuit default output for undefined input.
+ * @param source Guard or decoder used for non-undefined input.
+ * @param fallback Output value or zero-argument producer.
+ * @returns Decoder that returns fallback output when input is undefined.
+ */
+export declare function defaultValue<TSource extends DecodeSource>(source: TSource, fallback: DefaultInput<InferDecoder<TSource>>): BaseDecoder<InferDecoder<TSource>>;
+/**
+ * @brief Add a pre-parse fallback input for undefined input.
+ * @param source Guard or decoder used for actual validation.
+ * @param fallback Input value passed through the source when input is undefined.
+ * @returns Decoder that validates fallback input instead of short-circuiting.
+ */
+export declare function prefault<TSource extends DecodeSource>(source: TSource, fallback: unknown): BaseDecoder<InferDecoder<TSource>>;
+/**
+ * @brief Add a failure fallback output for decode errors.
+ * @param source Guard or decoder used for validation.
+ * @param fallback Output value or zero-argument producer returned on failure.
+ * @returns Decoder that converts validation failure into fallback success.
+ */
+export declare function catchValue<TSource extends DecodeSource>(source: TSource, fallback: DefaultInput<InferDecoder<TSource>>): BaseDecoder<InferDecoder<TSource>>;
+/**
+ * @brief Build a bidirectional codec from input and output validation sources.
+ * @param input Source schema for encoded values.
+ * @param output Source schema for decoded values.
+ * @param mapping Decode and encode mapping functions.
+ * @returns Codec that validates both sides of each conversion.
+ */
+export declare function codec<TInput extends DecodeSource, TOutput extends DecodeSource>(input: TInput, output: TOutput, mapping: {
+    readonly decode: (value: InferDecoder<TInput>) => InferDecoder<TOutput>;
+    readonly encode: (value: InferDecoder<TOutput>) => InferDecoder<TInput>;
+}): BaseCodec<InferDecoder<TInput>, InferDecoder<TOutput>>;
 /**
  * @brief Primitive coercion decoders with explicit failure issues.
  * @details Decoder helpers keep validation failures explicit in Result values while
@@ -88,5 +142,11 @@ export declare function coerceBoolean(): BaseDecoder<boolean>;
  * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function isDecoderValue(value: unknown): value is Decoder<unknown>;
+/**
+ * @brief Check codec value.
+ * @param value Candidate runtime value.
+ * @returns True when the value is a TypeSea codec.
+ */
+export declare function isCodecValue(value: unknown): value is Codec<unknown, unknown>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/decoder/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decoder/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decoder/index.ts"],"names":[],"mappings":"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"}

package/dist/decoder/index.js

@@ -9,6 +9,7 @@ import { freezeSchema, isSchemaValue } from "../schema/index.js";
  * collision with user-visible properties.
  */
 const DecoderRunSymbol = Symbol("TypeSea.decoder.run");
+const CodecEncodeSymbol = Symbol("TypeSea.codec.encode");
 /**
  * @brief Real decoder instances tracked without extending object lifetime.
  * @details Decoder helpers keep validation failures explicit in Result values while
@@ -27,7 +28,9 @@ export class BaseDecoder {
         }
         defineReadonlyProperty(this, DecoderRunSymbol, run, false);
         constructedDecoders.add(this);
-        Object.freeze(this);
+        if (new.target === BaseDecoder) {
+            Object.freeze(this);
+        }
     }
     decode(value) {
         return readDecoderRunner(this, "decoder receiver")(value);
@@ -56,6 +59,47 @@ export class BaseDecoder {
             return nextRun(decoded.value);
         });
     }
+    default(fallback) {
+        const run = readDecoderRunner(this, "decoder default receiver");
+        return new BaseDecoder((value) => {
+            if (value === undefined) {
+                return okResult(resolveDefault(fallback));
+            }
+            return run(value);
+        });
+    }
+    prefault(fallback) {
+        const run = readDecoderRunner(this, "decoder prefault receiver");
+        return new BaseDecoder((value) => run(value === undefined ? fallback : value));
+    }
+    catch(fallback) {
+        const run = readDecoderRunner(this, "decoder catch receiver");
+        return new BaseDecoder((value) => {
+            const decoded = run(value);
+            if (decoded.ok) {
+                return decoded;
+            }
+            return okResult(resolveDefault(fallback));
+        });
+    }
+}
+/**
+ * @brief Frozen bidirectional codec wrapper.
+ * @details Decode uses the BaseDecoder runner. Encode has a separate private
+ * symbol so detached encode calls fail through the same receiver discipline.
+ */
+export class BaseCodec extends BaseDecoder {
+    constructor(decodeRun, encodeRun) {
+        super(decodeRun);
+        if (typeof encodeRun !== "function") {
+            throw new TypeError("codec encode run must be a function");
+        }
+        defineReadonlyProperty(this, CodecEncodeSymbol, encodeRun, false);
+        Object.freeze(this);
+    }
+    encode(value) {
+        return readCodecEncodeRunner(this, "codec receiver")(value);
+    }
 }
 /**
  * @brief Execute decoder.
@@ -86,6 +130,76 @@ export function transform(source, mapper) {
 export function pipe(source, next) {
     return makeDecoder(source).pipe(next);
 }
+/**
+ * @brief Add a short-circuit default output for undefined input.
+ * @param source Guard or decoder used for non-undefined input.
+ * @param fallback Output value or zero-argument producer.
+ * @returns Decoder that returns fallback output when input is undefined.
+ */
+export function defaultValue(source, fallback) {
+    const run = readDecodeSourceRunner(source, "default source");
+    return new BaseDecoder((value) => {
+        if (value === undefined) {
+            return okResult(resolveDefault(fallback));
+        }
+        return run(value);
+    });
+}
+/**
+ * @brief Add a pre-parse fallback input for undefined input.
+ * @param source Guard or decoder used for actual validation.
+ * @param fallback Input value passed through the source when input is undefined.
+ * @returns Decoder that validates fallback input instead of short-circuiting.
+ */
+export function prefault(source, fallback) {
+    const run = readDecodeSourceRunner(source, "prefault source");
+    return new BaseDecoder((value) => run(value === undefined ? fallback : value));
+}
+/**
+ * @brief Add a failure fallback output for decode errors.
+ * @param source Guard or decoder used for validation.
+ * @param fallback Output value or zero-argument producer returned on failure.
+ * @returns Decoder that converts validation failure into fallback success.
+ */
+export function catchValue(source, fallback) {
+    const run = readDecodeSourceRunner(source, "catch source");
+    return new BaseDecoder((value) => {
+        const decoded = run(value);
+        if (decoded.ok) {
+            return decoded;
+        }
+        return okResult(resolveDefault(fallback));
+    });
+}
+/**
+ * @brief Build a bidirectional codec from input and output validation sources.
+ * @param input Source schema for encoded values.
+ * @param output Source schema for decoded values.
+ * @param mapping Decode and encode mapping functions.
+ * @returns Codec that validates both sides of each conversion.
+ */
+export function codec(input, output, mapping) {
+    if (!isRecord(mapping) ||
+        typeof mapping.decode !== "function" ||
+        typeof mapping.encode !== "function") {
+        throw new TypeError("codec mapping must contain decode and encode functions");
+    }
+    const inputRun = readDecodeSourceRunner(input, "codec input");
+    const outputRun = readDecodeSourceRunner(output, "codec output");
+    return new BaseCodec((value) => {
+        const decodedInput = inputRun(value);
+        if (!decodedInput.ok) {
+            return decodedInput;
+        }
+        return outputRun(mapping.decode(decodedInput.value));
+    }, (value) => {
+        const decodedOutput = outputRun(value);
+        if (!decodedOutput.ok) {
+            return decodedOutput;
+        }
+        return inputRun(mapping.encode(decodedOutput.value));
+    });
+}
 /**
  * @brief Primitive coercion decoders with explicit failure issues.
  * @details Decoder helpers keep validation failures explicit in Result values while
@@ -167,6 +281,14 @@ export function coerceBoolean() {
 export function isDecoderValue(value) {
     return isConstructedDecoder(value);
 }
+/**
+ * @brief Check codec value.
+ * @param value Candidate runtime value.
+ * @returns True when the value is a TypeSea codec.
+ */
+export function isCodecValue(value) {
+    return isConstructedCodec(value);
+}
 /**
  * @brief Test decoder identity through the private registry.
  * @details Decoder helpers keep validation failures explicit in Result values while
@@ -177,6 +299,25 @@ export function isDecoderValue(value) {
 function isConstructedDecoder(value) {
     return isRecord(value) && constructedDecoders.has(value);
 }
+/**
+ * @brief Test codec identity through the private encode slot.
+ * @param value Candidate codec.
+ * @returns True when TypeSea constructed the codec instance.
+ */
+function isConstructedCodec(value) {
+    return isConstructedDecoder(value) &&
+        Object.prototype.hasOwnProperty.call(value, CodecEncodeSymbol);
+}
+/**
+ * @brief Resolve a default value or zero-argument producer.
+ * @param fallback Stored fallback value or producer.
+ * @returns Concrete fallback output.
+ */
+function resolveDefault(fallback) {
+    return typeof fallback === "function"
+        ? fallback()
+        : fallback;
+}
 /**
  * @brief Resolve a decode source into an executable runner.
  * @param source Decoder or guard-like value supplied by the caller.
@@ -207,6 +348,19 @@ function readDecoderRunner(value, label) {
     }
     return value[DecoderRunSymbol];
 }
+/**
+ * @brief Read the private encode runner from a constructed codec.
+ * @param value Candidate codec object.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Stored encode runner.
+ * @throws TypeError when the receiver is not a TypeSea codec.
+ */
+function readCodecEncodeRunner(value, label) {
+    if (!isConstructedCodec(value)) {
+        throw new TypeError(`${label} must be a TypeSea codec`);
+    }
+    return value[CodecEncodeSymbol];
+}
 /**
  * @brief Normalize a guard-like value used as a decode source.
  * @param value Candidate guard-like source.
@@ -267,6 +421,15 @@ function actualType(value) {
     if (Array.isArray(value)) {
         return "array";
     }
+    if (value instanceof Date) {
+        return "date";
+    }
+    if (value instanceof Map) {
+        return "map";
+    }
+    if (value instanceof Set) {
+        return "set";
+    }
     if (typeof value === "number" && Number.isNaN(value)) {
         return "nan";
     }

package/dist/evaluate/check-composite.d.ts

@@ -26,7 +26,9 @@ export type IssueCollector = (schema: Schema, value: unknown, path: PathSegment[
  * @param collectChild Dispatcher for nested schema diagnostics.
  * @post Every pushed path segment is popped before return.
  */
-export declare function collectArrayIssues(item: Schema, value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
+export declare function collectArrayIssues(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.Array;
+}>, value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
 /**
  * @brief collect tuple issues.
  * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
@@ -39,7 +41,9 @@ export declare function collectArrayIssues(item: Schema, value: unknown, path: P
  * @param collectChild Dispatcher for nested schema diagnostics.
  * @post Every pushed tuple index is popped before return.
  */
-export declare function collectTupleIssues(items: readonly Schema[], value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
+export declare function collectTupleIssues(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.Tuple;
+}>, value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
 /**
  * @brief collect record issues.
  * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
@@ -53,6 +57,52 @@ export declare function collectTupleIssues(items: readonly Schema[], value: unkn
  * @post Every pushed record key is popped before return.
  */
 export declare function collectRecordIssues(item: Schema, value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
+/**
+ * @brief collect Map issues.
+ * @param schema Map schema with key and value validators.
+ * @param value Candidate runtime value.
+ * @param path Mutable diagnostic path stack.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ */
+export declare function collectMapIssues(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.Map;
+}>, value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
+/**
+ * @brief collect Set issues.
+ * @param schema Set schema with item validator.
+ * @param value Candidate runtime value.
+ * @param path Mutable diagnostic path stack.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ */
+export declare function collectSetIssues(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.Set;
+}>, value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
+/**
+ * @brief collect instanceOf issues.
+ * @param schema InstanceOf schema with constructor metadata.
+ * @param value Candidate runtime value.
+ * @param path Current diagnostic path.
+ * @param issues Output issue buffer.
+ */
+export declare function collectInstanceOfIssues(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.InstanceOf;
+}>, value: unknown, path: PathSegment[], issues: Issue[]): void;
+/**
+ * @brief collect property issues.
+ * @param schema Property schema with base and own data property validator.
+ * @param value Candidate runtime value.
+ * @param path Mutable diagnostic path stack.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ */
+export declare function collectPropertyIssues(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.Property;
+}>, value: unknown, path: PathSegment[], issues: Issue[], state: ValidationState, collectChild: IssueCollector): void;
 /**
  * @brief collect object issues.
  * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection

package/dist/evaluate/check-composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-composite.d.ts","sourceRoot":"","sources":["../../src/evaluate/check-composite.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGH,SAAS,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EACR,sBAAsB,EACtB,MAAM,EACT,MAAM,oBAAoB,CAAC;AAe5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,eAAe,KACrB,IAAI,CAAC;AAEV;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,cAAc,GAC7B,IAAI,CAkCN;AA+CD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,cAAc,GAC7B,IAAI,CAuCN;AAyCD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,cAAc,GAC7B,IAAI,CAwBN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,cAAc,GAC7B,IAAI,CAsDN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAC3C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,cAAc,GAC7B,IAAI,CA2CN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,EACtC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,cAAc,GAC7B,IAAI,CAWN"}
+{"version":3,"file":"check-composite.d.ts","sourceRoot":"","sources":["../../src/evaluate/check-composite.ts"],"names":[],"mappings":"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"}