typesea 0.1.0 → 0.3.0

package/dist/decoder/index.d.ts

@@ -1,85 +1,121 @@
 import type { Guard, Presence, RuntimeValue } from "../guard/index.js";
 import type { CheckResult } from "../issue/index.js";
-/**
- * @brief decode runner.
- */
 type DecodeRunner<TValue> = (value: unknown) => CheckResult<TValue>;
+type EncodeRunner<TValue> = (value: unknown) => CheckResult<TValue>;
+type DefaultInput<TValue> = TValue | (() => TValue);
 /**
- * @brief decoder run symbol.
+ * @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;
-/**
- * @brief decode source.
- */
+declare const CodecEncodeSymbol: unique symbol;
 export type DecodeSource = Guard<unknown, Presence> | Decoder<unknown>;
-/**
- * @brief infer decoder.
- */
 export type InferDecoder<TSource> = TSource extends Decoder<infer TValue> ? TValue : TSource extends Guard<infer TValue, infer TPresence> ? RuntimeValue<TValue, TPresence> : never;
 /**
- * @brief decoder.
+ * @brief Synchronous decode pipeline.
+ * @details Decoders are explicit Result producers; they do not throw for data
+ * validation failure.
  */
 export interface Decoder<TValue> {
-    /**
-     * @brief decode.
-           */
     decode(value: unknown): CheckResult<TValue>;
-    /**
-     * @brief transform.
-           */
     transform<TNext>(mapper: (value: TValue) => TNext): BaseDecoder<TNext>;
-    /**
-     * @brief pipe.
-           */
     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 base decoder.
- * @details Owns its state directly; methods expose receiver checks and explicit result flow.
- * @invariant Construction leaves the instance in a fully usable state before it escapes.
+ * @brief Frozen decoder wrapper around one runner function.
+ * @details Methods re-read the symbol runner from the receiver so detached
+ * method calls fail with TypeSea errors instead of touching undefined state.
  */
 export declare class BaseDecoder<TValue> implements Decoder<TValue> {
     private readonly [DecoderRunSymbol];
-    /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
-     */
     constructor(run: DecodeRunner<TValue>);
-    /**
-     * @brief decode.
-             */
     decode(this: unknown, value: unknown): CheckResult<TValue>;
-    /**
-     * @brief transform.
-           */
     transform<TNext>(mapper: (value: TValue) => TNext): BaseDecoder<TNext>;
-    /**
-     * @brief pipe.
-           */
     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 decoder.
+ * @brief Wrap a guard or decoder as a synchronous decoder pipeline.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 export declare function decoder<TValue, TPresence extends Presence>(source: Guard<TValue, TPresence>): BaseDecoder<RuntimeValue<TValue, TPresence>>;
 /**
- * @brief decoder.
+ * @brief Execute decoder.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function decoder<TValue>(source: Decoder<TValue>): BaseDecoder<TValue>;
 /**
- * @brief transform.
+ * @brief Build a decoder and append a synchronous mapper.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 export declare function transform<TValue, TPresence extends Presence, TNext>(source: Guard<TValue, TPresence>, mapper: (value: RuntimeValue<TValue, TPresence>) => TNext): BaseDecoder<TNext>;
 /**
- * @brief transform.
+ * @brief Execute transform.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function transform<TValue, TNext>(source: Decoder<TValue>, mapper: (value: TValue) => TNext): BaseDecoder<TNext>;
 /**
- * @brief pipe.
+ * @brief Execute pipe.
+ * @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 coerce.
+ * @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
+ * preserving the original input value.
  */
 export declare const coerce: Readonly<{
     readonly string: typeof coerceString;
@@ -87,20 +123,30 @@ export declare const coerce: Readonly<{
     readonly boolean: typeof coerceBoolean;
 }>;
 /**
- * @brief coerce string.
+ * @brief Execute coerce string.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function coerceString(): BaseDecoder<string>;
 /**
- * @brief coerce number.
+ * @brief Execute coerce number.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function coerceNumber(): BaseDecoder<number>;
 /**
- * @brief coerce boolean.
+ * @brief Execute coerce boolean.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function coerceBoolean(): BaseDecoder<boolean>;
 /**
- * @brief is decoder value.
+ * @brief Check decoder value.
+ * @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":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,mBAAmB,CAAC;AAMhE;;GAEG;AACH,KAAK,YAAY,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,WAAW,CAAC,MAAM,CAAC,CAAC;AAEpE;;GAEG;AACH,QAAA,MAAM,gBAAgB,eAAgC,CAAC;AAOvD;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,GACxB,OAAO,CAAC,OAAO,CAAC,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,IAC9B,OAAO,SAAS,OAAO,CAAC,MAAM,MAAM,CAAC,GACjC,MAAM,GACN,OAAO,SAAS,KAAK,CAAC,MAAM,MAAM,EAAE,MAAM,SAAS,CAAC,GAClD,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,GAC/B,KAAK,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,OAAO,CAAC,MAAM;IAE7B;;aAES;IACT,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAE5C;;aAES;IACT,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEvE;;aAES;IACT,IAAI,CAAC,KAAK,SAAS,YAAY,EAAE,IAAI,EAAE,KAAK,GAAG,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;CACjF;AASD;;;;GAIG;AACH,qBAAa,WAAW,CAAC,MAAM,CAAE,YAAW,OAAO,CAAC,MAAM,CAAC;IACzD,iBAAyB,CAAC,gBAAgB,CAAC,CAAuB;IAElE;;;OAGG;gBACgB,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC;IAS5C;;eAEW;IACJ,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC;IAIjE;;aAES;IACF,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC;IAc7E;;aAES;IACF,IAAI,CAAC,KAAK,SAAS,YAAY,EACpC,IAAI,EAAE,KAAK,GACV,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;CAapC;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,SAAS,QAAQ,EACxD,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,GAC/B,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEhD;;GAEG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAiB9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,SAAS,QAAQ,EAAE,KAAK,EACjE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,EAChC,MAAM,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,KAAK,GACxD,WAAW,CAAC,KAAK,CAAC,CAAC;AAEtB;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EACrC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,GAC/B,WAAW,CAAC,KAAK,CAAC,CAAC;AAYtB;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,SAAS,YAAY,EAC7C,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,KAAK,GACV,WAAW,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAElC;AAED;;GAEG;AACH,eAAO,MAAM,MAAM;;;;EAIR,CAAC;AAEZ;;GAEG;AACH,wBAAgB,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAkBlD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAclD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,WAAW,CAAC,OAAO,CAAC,CAiBpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAExE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decoder/index.ts"],"names":[],"mappings":"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"}

package/dist/decoder/index.js

@@ -4,40 +4,37 @@ import { SchemaTag } from "../kind/index.js";
 import { err } from "../result/index.js";
 import { freezeSchema, isSchemaValue } from "../schema/index.js";
 /**
- * @brief decoder run symbol.
+ * @brief Private runner slot for decoder instances.
+ * @details A symbol slot keeps the public object small while avoiding accidental
+ * collision with user-visible properties.
  */
 const DecoderRunSymbol = Symbol("TypeSea.decoder.run");
+const CodecEncodeSymbol = Symbol("TypeSea.codec.encode");
 /**
- * @brief constructed decoders.
+ * @brief Real decoder instances tracked without extending object lifetime.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 const constructedDecoders = new WeakSet();
 /**
- * @brief base decoder.
- * @details Owns its state directly; methods expose receiver checks and explicit result flow.
- * @invariant Construction leaves the instance in a fully usable state before it escapes.
+ * @brief Frozen decoder wrapper around one runner function.
+ * @details Methods re-read the symbol runner from the receiver so detached
+ * method calls fail with TypeSea errors instead of touching undefined state.
  */
 export class BaseDecoder {
-    /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
-     */
     constructor(run) {
         if (typeof run !== "function") {
             throw new TypeError("decoder run must be a function");
         }
         defineReadonlyProperty(this, DecoderRunSymbol, run, false);
         constructedDecoders.add(this);
-        Object.freeze(this);
+        if (new.target === BaseDecoder) {
+            Object.freeze(this);
+        }
     }
-    /**
-     * @brief decode.
-             */
     decode(value) {
         return readDecoderRunner(this, "decoder receiver")(value);
     }
-    /**
-     * @brief transform.
-           */
     transform(mapper) {
         if (typeof mapper !== "function") {
             throw new TypeError("decoder transform mapper must be a function");
@@ -51,9 +48,6 @@ export class BaseDecoder {
             return okResult(mapper(decoded.value));
         });
     }
-    /**
-     * @brief pipe.
-           */
     pipe(next) {
         const run = readDecoderRunner(this, "decoder pipe receiver");
         const nextRun = readDecodeSourceRunner(next, "decoder pipe target");
@@ -65,34 +59,151 @@ 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 decoder.
+ * @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.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function decoder(source) {
     return makeDecoder(source);
 }
 /**
- * @brief make decoder.
+ * @brief Build decoder.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function makeDecoder(source) {
     const run = readDecodeSourceRunner(source, "decoder source");
     return new BaseDecoder(run);
 }
 /**
- * @brief transform.
+ * @brief Execute transform.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function transform(source, mapper) {
     return makeDecoder(source).transform(mapper);
 }
 /**
- * @brief pipe.
+ * @brief Execute pipe.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function pipe(source, next) {
     return makeDecoder(source).pipe(next);
 }
 /**
- * @brief coerce.
+ * @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
+ * preserving the original input value.
  */
 export const coerce = Object.freeze({
     string: coerceString,
@@ -100,7 +211,8 @@ export const coerce = Object.freeze({
     boolean: coerceBoolean
 });
 /**
- * @brief coerce string.
+ * @brief Execute coerce string.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function coerceString() {
     return new BaseDecoder((value) => {
@@ -122,7 +234,8 @@ export function coerceString() {
     });
 }
 /**
- * @brief coerce number.
+ * @brief Execute coerce number.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function coerceNumber() {
     return new BaseDecoder((value) => {
@@ -140,7 +253,8 @@ export function coerceNumber() {
     });
 }
 /**
- * @brief coerce boolean.
+ * @brief Execute coerce boolean.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function coerceBoolean() {
     return new BaseDecoder((value) => {
@@ -161,19 +275,56 @@ export function coerceBoolean() {
     });
 }
 /**
- * @brief is decoder value.
+ * @brief Check decoder value.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function isDecoderValue(value) {
     return isConstructedDecoder(value);
 }
 /**
- * @brief is constructed decoder.
+ * @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
+ * preserving the original input value.
+ * @param value Candidate decoder.
+ * @returns True when TypeSea constructed the decoder instance.
  */
 function isConstructedDecoder(value) {
     return isRecord(value) && constructedDecoders.has(value);
 }
 /**
- * @brief read decode source runner.
+ * @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.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Function that validates one runtime value.
+ * @details Real decoders keep a private runner symbol. Guard-like values are
+ * lowered to schema checks after hardened schema normalization.
  */
 function readDecodeSourceRunner(source, label) {
     if (isConstructedDecoder(source)) {
@@ -183,7 +334,13 @@ function readDecodeSourceRunner(source, label) {
     return (value) => checkSchema(schema, value);
 }
 /**
- * @brief read decoder runner.
+ * @brief Read the private runner from a constructed decoder.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate decoder object.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Stored decode runner.
+ * @throws TypeError when the value was not registered by a decoder constructor.
  */
 function readDecoderRunner(value, label) {
     if (!isConstructedDecoder(value)) {
@@ -192,20 +349,43 @@ function readDecoderRunner(value, label) {
     return value[DecoderRunSymbol];
 }
 /**
- * @brief read guard schema.
+ * @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.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Frozen schema used by the generated decode runner.
+ * @throws TypeError when the schema slot is absent or malformed.
+ * @details Descriptor reads keep inherited schema getters out of the decode
+ * pipeline before the schema is frozen for repeated use.
  */
 function readGuardSchema(value, label) {
     if (!isRecord(value)) {
         throw new TypeError(`${label} must be a TypeSea guard or decoder`);
     }
-    const schema = value["schema"];
+    const schema = readOwnDataProperty(value, "schema");
     if (!isSchemaValue(schema)) {
         throw new TypeError(`${label} must contain a valid TypeSea schema`);
     }
     return freezeSchema(schema);
 }
 /**
- * @brief ok result.
+ * @brief Build a frozen success Result for decoder transforms.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Decoded value.
+ * @returns Frozen ok result.
  */
 function okResult(value) {
     return Object.freeze({
@@ -214,7 +394,13 @@ function okResult(value) {
     });
 }
 /**
- * @brief fail.
+ * @brief Build a frozen single-issue failure Result.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param code Issue code.
+ * @param expected Expected value description.
+ * @param value Runtime value that failed validation.
+ * @returns Failure result with a root-level issue.
  */
 function fail(code, expected, value) {
     return err(freezeIssueArray([
@@ -222,7 +408,11 @@ function fail(code, expected, value) {
     ]));
 }
 /**
- * @brief actual type.
+ * @brief Produce the compact runtime type label used in decoder issues.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Runtime value.
+ * @returns Stable diagnostic type name.
  */
 function actualType(value) {
     if (value === null) {
@@ -231,13 +421,28 @@ 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";
     }
     return typeof value;
 }
 /**
- * @brief define readonly property.
+ * @brief Define one immutable decoder instance slot.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param target Decoder instance.
+ * @param key Public key or private symbol.
+ * @param value Stored field value.
+ * @param enumerable Whether the field should appear in enumeration.
  */
 function defineReadonlyProperty(target, key, value, enumerable) {
     Object.defineProperty(target, key, {
@@ -248,13 +453,35 @@ function defineReadonlyProperty(target, key, value, enumerable) {
     });
 }
 /**
- * @brief is record.
+ * @brief Accept objects that can carry decoder or guard fields.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate object.
+ * @returns True for non-array objects.
  */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief number schema.
+ * @brief Read one own data slot from a decode source.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Object being normalized.
+ * @param key Field name or symbol.
+ * @returns Stored field value, or undefined when absent.
+ */
+function readOwnDataProperty(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined ||
+        !Object.prototype.hasOwnProperty.call(descriptor, "value")) {
+        return undefined;
+    }
+    return descriptor.value;
+}
+/**
+ * @brief Reused finite-number schema for string-to-number coercion.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 const numberSchema = Object.freeze({
     tag: SchemaTag.Number,