typesea 0.1.0 → 0.2.0

package/dist/aot/index.js

@@ -3,7 +3,13 @@ import { SchemaTag } from "../kind/index.js";
 import { err, ok } from "../result/index.js";
 import { freezeSchema, isSchemaValue } from "../schema/index.js";
 /**
- * @brief emit aot module.
+ * @brief Emit a standalone validator module for a guard schema.
+ * @param guard Guard whose schema is exported.
+ * @param options Optional function name and compile mode.
+ * @returns Result carrying source text, or closed issues for unsupported schema nodes.
+ * @details AOT output cannot close over runtime side tables. The schema is
+ * scanned before code emission so lazy, refine, and symbol-literal constructs
+ * fail as explicit issues instead of producing partially faithful source.
  */
 export function emitAotModule(guard, options) {
     const schema = readAotSchema(guard);
@@ -13,7 +19,7 @@ export function emitAotModule(guard, options) {
     if (issues.length !== 0) {
         return err(freezeAotIssues(issues));
     }
-    const bundle = emitCompiledSourceBundle(schema, config.name);
+    const bundle = emitCompiledSourceBundle(schema, config.name, config.mode);
     if (bundle.dynamicSchemas.length !== 0) {
         return err(freezeAotIssues([
             {
@@ -29,25 +35,36 @@ export function emitAotModule(guard, options) {
     }));
 }
 /**
- * @brief read aot schema.
+ * @brief Normalize the guard input used by AOT emission.
+ * @param guard Candidate guard-like value.
+ * @returns Frozen schema safe for source generation.
+ * @throws TypeError when the value is not a TypeSea guard.
+ * @details The schema slot is descriptor-read to reject forged prototypes before
+ * the generator traverses schema data.
  */
 function readAotSchema(guard) {
     if (!isRecord(guard)) {
         throw new TypeError("AOT guard must be a TypeSea guard");
     }
-    const schema = guard["schema"];
+    const schema = readOwnDataProperty(guard, "schema");
     if (!isSchemaValue(schema)) {
         throw new TypeError("AOT guard must contain a valid TypeSea schema");
     }
     return freezeSchema(schema);
 }
 /**
- * @brief read options.
+ * @brief Normalize AOT compile options.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
+ * @param options Optional user options object.
+ * @returns Complete options with defaults.
+ * @throws TypeError when option fields have unsupported types.
  */
 function readOptions(options) {
     if (options === undefined) {
         return {
-            name: "typesea_aot"
+            name: "typesea_aot",
+            mode: "safe"
         };
     }
     if (!isRecord(options)) {
@@ -56,18 +73,45 @@ function readOptions(options) {
     const name = options.name;
     if (name === undefined) {
         return {
-            name: "typesea_aot"
+            name: "typesea_aot",
+            mode: readAotMode(options)
         };
     }
     if (typeof name !== "string") {
         throw new TypeError("AOT name must be a string");
     }
     return {
-        name
+        name,
+        mode: readAotMode(options)
     };
 }
 /**
- * @brief scan aot schema.
+ * @brief Normalize the requested AOT compile mode.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
+ * @param options Options object already accepted as a record.
+ * @returns Safe, unsafe, or unchecked codegen mode.
+ * @throws TypeError when the mode is outside the supported set.
+ */
+function readAotMode(options) {
+    const mode = options["mode"];
+    if (mode === undefined) {
+        return "safe";
+    }
+    if (mode === "safe" || mode === "unsafe" || mode === "unchecked") {
+        return mode;
+    }
+    throw new TypeError("AOT mode must be \"safe\", \"unsafe\", or \"unchecked\"");
+}
+/**
+ * @brief Walk a schema tree and record constructs that AOT cannot preserve.
+ * @param schema Current schema node.
+ * @param path Diagnostic path to the current node.
+ * @param issues Mutable issue vector owned by the caller.
+ * @param seen Schema object set used to avoid repeated traversal.
+ * @details Runtime compilation can keep dynamic schemas in side tables; emitted
+ * modules cannot. This scan keeps the public API honest by refusing source that
+ * would silently weaken lazy, refine, or symbol literal semantics.
  */
 function scanAotSchema(schema, path, issues, seen) {
     if (seen.has(schema)) {
@@ -131,6 +175,8 @@ function scanAotSchema(schema, path, issues, seen) {
 }
 /**
  * @brief scan schema array.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 function scanSchemaArray(schemas, path, issues, seen) {
     for (let index = 0; index < schemas.length; index += 1) {
@@ -142,6 +188,8 @@ function scanSchemaArray(schemas, path, issues, seen) {
 }
 /**
  * @brief scan object entries.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 function scanObjectEntries(entries, path, issues, seen) {
     for (let index = 0; index < entries.length; index += 1) {
@@ -153,6 +201,8 @@ function scanObjectEntries(entries, path, issues, seen) {
 }
 /**
  * @brief emit module source.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 function emitModuleSource(bundle) {
     return [
@@ -170,9 +220,8 @@ function emitModuleSource(bundle) {
         "const __typesea=(function(l,r,k,u,d,m,sk){",
         bundle.source,
         "})(l,r,k,u,d,m,sk);",
-        "const freezeIssues=function(xs){if(xs.length===0)return Object.freeze([]);const out=new Array(xs.length);for(let i=0;i<xs.length;i+=1){const x=xs[i];const p=x.path.slice();Object.freeze(p);const y={path:p,code:x.code,expected:x.expected,actual:x.actual,message:x.message};Object.freeze(y);out[i]=y;}return Object.freeze(out);};",
         "export function is(value){return __typesea.is(value);}",
-        "export function check(value){const issues=freezeIssues(__typesea.check(value));if(issues.length===0)return Object.freeze({ok:true,value});return Object.freeze({ok:false,error:issues});}",
+        "export function check(value){return __typesea.result(value);}",
         "export function assert(value){const result=check(value);if(!result.ok){const error=new Error(\"TypeSea assertion failed\");Object.defineProperty(error,\"issues\",{configurable:false,enumerable:true,value:result.error,writable:false});throw error;}}",
         "export default Object.freeze({is,check,assert});",
         ""
@@ -180,6 +229,8 @@ function emitModuleSource(bundle) {
 }
 /**
  * @brief emit declaration source.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 function emitDeclarationSource() {
     return [
@@ -207,6 +258,8 @@ function emitDeclarationSource() {
 }
 /**
  * @brief serialize literal array.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 function serializeLiteralArray(values) {
     const parts = new Array(values.length);
@@ -220,6 +273,8 @@ function serializeLiteralArray(values) {
 }
 /**
  * @brief serialize literal.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 function serializeLiteral(value) {
     switch (typeof value) {
@@ -253,6 +308,8 @@ function serializeLiteral(value) {
 }
 /**
  * @brief serialize reg exp array.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 function serializeRegExpArray(values) {
     const parts = new Array(values.length);
@@ -265,7 +322,8 @@ function serializeRegExpArray(values) {
     return `[${parts.join(",")}]`;
 }
 /**
- * @brief push issue.
+ * @brief Execute push issue.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function pushIssue(path, issues, code, message) {
     issues.push({
@@ -275,7 +333,8 @@ function pushIssue(path, issues, code, message) {
     });
 }
 /**
- * @brief freeze aot issues.
+ * @brief Execute freeze aot issues.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function freezeAotIssues(issues) {
     for (let index = 0; index < issues.length; index += 1) {
@@ -288,8 +347,28 @@ function freezeAotIssues(issues) {
     return Object.freeze(issues);
 }
 /**
- * @brief is record.
+ * @brief Accept option and guard records before local field reads.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
+ * @param value Candidate object.
+ * @returns True for non-array objects.
  */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * @brief Read one own data slot from an AOT input object.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
+ * @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;
+}

package/dist/async/index.d.ts

@@ -1,110 +1,82 @@
 import { type DecodeSource, type Decoder, type InferDecoder } from "../decoder/index.js";
 import type { Guard, Presence, RuntimeValue } from "../guard/index.js";
 import { type CheckResult } from "../issue/index.js";
-/**
- * @brief async decode runner.
- */
 type AsyncDecodeRunner<TValue> = (value: unknown) => Promise<CheckResult<TValue>>;
-/**
- * @brief async predicate.
- */
 type AsyncPredicate<TValue> = (value: TValue) => boolean | Promise<boolean>;
-/**
- * @brief async mapper.
- */
 type AsyncMapper<TValue, TNext> = (value: TValue) => TNext | Promise<TNext>;
 /**
- * @brief async decoder run symbol.
+ * @brief Private runner slot for async decoder instances.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 declare const AsyncDecoderRunSymbol: unique symbol;
-/**
- * @brief async decode source.
- */
 export type AsyncDecodeSource = DecodeSource | AsyncDecoder<unknown>;
-/**
- * @brief infer async decoder.
- */
 export type InferAsyncDecoder<TSource> = TSource extends AsyncDecoder<infer TValue> ? TValue : InferDecoder<TSource>;
 /**
- * @brief async decoder.
+ * @brief Promise-returning decode pipeline.
+ * @details The API keeps validation failures in Result values; rejected
+ * promises are reserved for programmer errors thrown by user mappers.
  */
 export interface AsyncDecoder<TValue> {
-    /**
-     * @brief decode async.
-           */
     decodeAsync(value: unknown): Promise<CheckResult<TValue>>;
-    /**
-     * @brief refine async.
-             */
     refineAsync(predicate: AsyncPredicate<TValue>, name: string): BaseAsyncDecoder<TValue>;
-    /**
-     * @brief transform async.
-           */
     transformAsync<TNext>(mapper: AsyncMapper<TValue, TNext>): BaseAsyncDecoder<TNext>;
-    /**
-     * @brief pipe async.
-           */
     pipeAsync<TNext extends AsyncDecodeSource>(next: TNext): BaseAsyncDecoder<InferAsyncDecoder<TNext>>;
 }
 /**
- * @brief base async 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 wrapper around one async decode runner.
+ * @details Receiver validation mirrors BaseDecoder so detached method calls do
+ * not bypass TypeSea's object construction checks.
  */
 export declare class BaseAsyncDecoder<TValue> implements AsyncDecoder<TValue> {
     private readonly [AsyncDecoderRunSymbol];
-    /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
-     */
     constructor(run: AsyncDecodeRunner<TValue>);
-    /**
-     * @brief decode async.
-             */
     decodeAsync(this: unknown, value: unknown): Promise<CheckResult<TValue>>;
-    /**
-     * @brief refine async.
-             */
     refineAsync(predicate: AsyncPredicate<TValue>, name: string): BaseAsyncDecoder<TValue>;
-    /**
-     * @brief transform async.
-           */
     transformAsync<TNext>(mapper: AsyncMapper<TValue, TNext>): BaseAsyncDecoder<TNext>;
-    /**
-     * @brief pipe async.
-           */
     pipeAsync<TNext extends AsyncDecodeSource>(next: TNext): BaseAsyncDecoder<InferAsyncDecoder<TNext>>;
 }
 /**
- * @brief async decoder.
+ * @brief Wrap a guard, decoder, or async decoder as an async decoder pipeline.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 export declare function asyncDecoder<TValue, TPresence extends Presence>(source: Guard<TValue, TPresence>): BaseAsyncDecoder<RuntimeValue<TValue, TPresence>>;
 /**
- * @brief async decoder.
+ * @brief Execute async decoder.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function asyncDecoder<TValue>(source: Decoder<TValue> | AsyncDecoder<TValue>): BaseAsyncDecoder<TValue>;
 /**
- * @brief async refine.
+ * @brief Build an async decoder and append an async refinement.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 export declare function asyncRefine<TValue, TPresence extends Presence>(source: Guard<TValue, TPresence>, predicate: AsyncPredicate<RuntimeValue<TValue, TPresence>>, name: string): BaseAsyncDecoder<RuntimeValue<TValue, TPresence>>;
 /**
- * @brief async refine.
+ * @brief Execute async refine.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function asyncRefine<TValue>(source: Decoder<TValue> | AsyncDecoder<TValue>, predicate: AsyncPredicate<TValue>, name: string): BaseAsyncDecoder<TValue>;
 /**
- * @brief async transform.
+ * @brief Build an async decoder and append an async mapper.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 export declare function asyncTransform<TValue, TPresence extends Presence, TNext>(source: Guard<TValue, TPresence>, mapper: AsyncMapper<RuntimeValue<TValue, TPresence>, TNext>): BaseAsyncDecoder<TNext>;
 /**
- * @brief async transform.
+ * @brief Execute async transform.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function asyncTransform<TValue, TNext>(source: Decoder<TValue> | AsyncDecoder<TValue>, mapper: AsyncMapper<TValue, TNext>): BaseAsyncDecoder<TNext>;
 /**
- * @brief async pipe.
+ * @brief Execute async pipe.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function asyncPipe<TNext extends AsyncDecodeSource>(source: AsyncDecodeSource, next: TNext): BaseAsyncDecoder<InferAsyncDecoder<TNext>>;
 /**
- * @brief is async decoder value.
+ * @brief Check async decoder value.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function isAsyncDecoderValue(value: unknown): value is AsyncDecoder<unknown>;
 export {};

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

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

package/dist/async/index.js

@@ -4,23 +4,23 @@ import { freezeIssueArray, makeIssue } from "../issue/index.js";
 import { err, ok } from "../result/index.js";
 import { freezeSchema, isSchemaValue } from "../schema/index.js";
 /**
- * @brief async decoder run symbol.
+ * @brief Private runner slot for async decoder instances.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 const AsyncDecoderRunSymbol = Symbol("TypeSea.asyncDecoder.run");
 /**
- * @brief constructed async decoders.
+ * @brief Real async decoder instances tracked without extending object lifetime.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 const constructedAsyncDecoders = new WeakSet();
 /**
- * @brief base async 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 wrapper around one async decode runner.
+ * @details Receiver validation mirrors BaseDecoder so detached method calls do
+ * not bypass TypeSea's object construction checks.
  */
 export class BaseAsyncDecoder {
-    /**
-     * @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("async decoder run must be a function");
@@ -29,15 +29,9 @@ export class BaseAsyncDecoder {
         constructedAsyncDecoders.add(this);
         Object.freeze(this);
     }
-    /**
-     * @brief decode async.
-             */
     decodeAsync(value) {
         return readAsyncDecoderRunner(this, "async decoder receiver")(value);
     }
-    /**
-     * @brief refine async.
-             */
     refineAsync(predicate, name) {
         if (typeof predicate !== "function") {
             throw new TypeError("async refinement predicate must be a function");
@@ -58,9 +52,6 @@ export class BaseAsyncDecoder {
             return failRefinement(name, decoded.value);
         });
     }
-    /**
-     * @brief transform async.
-           */
     transformAsync(mapper) {
         if (typeof mapper !== "function") {
             throw new TypeError("async transform mapper must be a function");
@@ -74,9 +65,6 @@ export class BaseAsyncDecoder {
             return ok(await mapper(decoded.value));
         });
     }
-    /**
-     * @brief pipe async.
-           */
     pipeAsync(next) {
         const run = readAsyncDecoderRunner(this, "async pipe receiver");
         const nextRun = readAsyncDecodeSourceRunner(next, "async pipe target");
@@ -90,44 +78,58 @@ export class BaseAsyncDecoder {
     }
 }
 /**
- * @brief async decoder.
+ * @brief Execute async decoder.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncDecoder(source) {
     return makeAsyncDecoder(source);
 }
 /**
- * @brief async refine.
+ * @brief Execute async refine.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncRefine(source, predicate, name) {
     return makeAsyncDecoder(source).refineAsync(predicate, name);
 }
 /**
- * @brief async transform.
+ * @brief Execute async transform.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncTransform(source, mapper) {
     return makeAsyncDecoder(source).transformAsync(mapper);
 }
 /**
- * @brief async pipe.
+ * @brief Execute async pipe.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncPipe(source, next) {
     return makeAsyncDecoder(source).pipeAsync(next);
 }
 /**
- * @brief is async decoder value.
+ * @brief Check async decoder value.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function isAsyncDecoderValue(value) {
     return isConstructedAsyncDecoder(value);
 }
 /**
- * @brief make async decoder.
+ * @brief Construct an async decoder from a guard, decoder, or async decoder.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param source Source pipeline element.
+ * @returns Async decoder wrapping the normalized runner.
  */
 function makeAsyncDecoder(source) {
     const run = readAsyncDecodeSourceRunner(source, "async decoder source");
     return new BaseAsyncDecoder(run);
 }
 /**
- * @brief read async decode source runner.
+ * @brief Resolve an async decode source into a promise-returning runner.
+ * @param source Candidate source supplied to async decoder composition.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Runner that always reports through a Promise.
+ * @details Sync decoders and guards are wrapped with Promise.resolve so the
+ * outer async pipeline has one uniform scheduling shape.
  */
 function readAsyncDecodeSourceRunner(source, label) {
     if (isConstructedAsyncDecoder(source)) {
@@ -140,7 +142,13 @@ function readAsyncDecodeSourceRunner(source, label) {
     return (value) => Promise.resolve(checkSchema(schema, value));
 }
 /**
- * @brief read async decoder runner.
+ * @brief Read the private runner from a constructed async decoder.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate async decoder object.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Stored async decode runner.
+ * @throws TypeError when the value was not registered by the constructor.
  */
 function readAsyncDecoderRunner(value, label) {
     if (!isConstructedAsyncDecoder(value)) {
@@ -149,26 +157,41 @@ function readAsyncDecoderRunner(value, label) {
     return value[AsyncDecoderRunSymbol];
 }
 /**
- * @brief is constructed async decoder.
+ * @brief Test async 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 async decoder.
+ * @returns True when TypeSea constructed the instance.
  */
 function isConstructedAsyncDecoder(value) {
     return isRecord(value) && constructedAsyncDecoders.has(value);
 }
 /**
- * @brief read guard schema.
+ * @brief Normalize a guard-like source used in an async decode pipeline.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate guard-like source.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Frozen schema used by the promise-wrapped check runner.
+ * @throws TypeError when the schema slot is absent or malformed.
  */
 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 fail refinement.
+ * @brief Build a single-issue failure for an async refinement.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param name Diagnostic refinement name.
+ * @param value Runtime value rejected by the predicate.
+ * @returns Failure result with a root-level refinement issue.
  */
 function failRefinement(name, value) {
     return err(freezeIssueArray([
@@ -176,7 +199,11 @@ function failRefinement(name, value) {
     ]));
 }
 /**
- * @brief actual type.
+ * @brief Produce the compact runtime type label used in async 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) {
@@ -197,13 +224,23 @@ function actualType(value) {
     return typeof value;
 }
 /**
- * @brief is strict true.
+ * @brief Accept only the literal boolean success value from async predicates.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Predicate return value.
+ * @returns True only for `true`.
  */
 function isStrictTrue(value) {
     return value === true;
 }
 /**
- * @brief define readonly property.
+ * @brief Define one immutable async decoder instance slot.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param target Async 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, {
@@ -214,8 +251,28 @@ function defineReadonlyProperty(target, key, value, enumerable) {
     });
 }
 /**
- * @brief is record.
+ * @brief Accept objects that can carry async 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 Read one own data slot from an async 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;
+}