typesea 0.1.0 → 0.2.0

package/dist/adapters/index.js

@@ -1,11 +1,14 @@
 import { isAsyncDecoderValue } from "../async/index.js";
 import { isDecoderValue } from "../decoder/index.js";
 import { TypeSeaAssertionError } from "../guard/index.js";
+import { isConstructedGuard } from "../guard/registry.js";
 import { formatIssue } from "../message/index.js";
 import { toJsonSchema } from "../json-schema/index.js";
 import { isSchemaValue } from "../schema/index.js";
 /**
  * @brief to trpc parser.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
  */
 export function toTrpcParser(source) {
     readSyncAdapterSource(source, "tRPC parser source");
@@ -21,6 +24,8 @@ export function toTrpcParser(source) {
 }
 /**
  * @brief to async trpc parser.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
  */
 export function toAsyncTrpcParser(source) {
     readAsyncAdapterSource(source, "async tRPC parser source");
@@ -36,6 +41,8 @@ export function toAsyncTrpcParser(source) {
 }
 /**
  * @brief to fastify route schema.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
  */
 export function toFastifyRouteSchema(guard, options) {
     const part = readFastifyPart(options);
@@ -52,6 +59,8 @@ export function toFastifyRouteSchema(guard, options) {
 }
 /**
  * @brief to fastify validator compiler.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
  */
 export function toFastifyValidatorCompiler(source) {
     const readSource = readFastifyValidatorCompilerSource(source);
@@ -72,6 +81,8 @@ export function toFastifyValidatorCompiler(source) {
 }
 /**
  * @brief to react hook form resolver.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
  */
 export function toReactHookFormResolver(source, options) {
     const config = readReactHookFormOptions(options);
@@ -91,7 +102,13 @@ export function toReactHookFormResolver(source, options) {
     };
 }
 /**
- * @brief decode sync source.
+ * @brief Run a synchronous adapter source against one submitted value.
+ * @param source Guard or decoder selected for the adapter call.
+ * @param value Framework payload being validated.
+ * @returns TypeSea Result produced by the selected source.
+ * @details Decoders already own their result shape. Guard-like values are first
+ * normalized through readGuard so structural receivers cannot smuggle inherited
+ * schema or check fields into adapter execution.
  */
 function decodeSyncSource(source, value) {
     if (isDecoderValue(source)) {
@@ -101,7 +118,13 @@ function decodeSyncSource(source, value) {
     return guard.check(value);
 }
 /**
- * @brief decode async source.
+ * @brief Run a possibly asynchronous adapter source.
+ * @param source Guard, decoder, or async decoder selected for the adapter call.
+ * @param value Framework payload being validated.
+ * @returns Promise resolving to a TypeSea Result.
+ * @details The ordering keeps native async decoders on their own private runner
+ * path while preserving the same hardened guard normalization used by sync
+ * adapters.
  */
 async function decodeAsyncSource(source, value) {
     if (isAsyncDecoderValue(source)) {
@@ -114,21 +137,36 @@ async function decodeAsyncSource(source, value) {
     return guard.check(value);
 }
 /**
- * @brief read guard.
+ * @brief Normalize a guard-like adapter source.
+ * @param value Candidate adapter source.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Guard object safe to call through the adapter layer.
+ * @throws TypeError when schema or check are not valid guard fields.
+ * @details Constructed guards use registry identity. Structural guard support is
+ * limited to own data `schema` and `check` slots so adapter entry points do not
+ * execute prototype getters supplied by a framework payload or plugin wrapper.
  */
 function readGuard(value, label) {
+    if (isConstructedGuard(value)) {
+        return value;
+    }
     if (!isRecord(value)) {
         throw new TypeError(`${label} must be a TypeSea guard or decoder`);
     }
     const guard = value;
-    const schema = value["schema"];
-    if (!isSchemaValue(schema) || typeof guard.check !== "function") {
+    const schema = readOwnDataProperty(value, "schema");
+    const check = readOwnDataProperty(value, "check");
+    if (!isSchemaValue(schema) || typeof check !== "function") {
         throw new TypeError(`${label} must be a TypeSea guard or decoder`);
     }
     return guard;
 }
 /**
- * @brief read sync adapter source.
+ * @brief Validate a source accepted by sync-only adapters.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
+ * @param source Candidate guard or decoder.
+ * @param label Message prefix for TypeError diagnostics.
  */
 function readSyncAdapterSource(source, label) {
     if (isDecoderValue(source)) {
@@ -137,8 +175,11 @@ function readSyncAdapterSource(source, label) {
     readGuard(source, label);
 }
 /**
- * @brief read fastify validator compiler source.
- * @details Normalizes a single validator source or a route-part source table into one selector.
+ * @brief Normalize Fastify validator sources into a route selector.
+ * @details A single source applies to all route parts. A source map is copied
+ * into a null-prototype table so route selection cannot observe later prototype
+ * mutations or inherited body/querystring/params/headers fields.
+ * @param source Guard, decoder, or route-part source table supplied by the user.
  * @returns Source selector used by the Fastify compiler callback.
  */
 function readFastifyValidatorCompilerSource(source) {
@@ -149,10 +190,15 @@ function readFastifyValidatorCompilerSource(source) {
     if (!isRecord(source)) {
         throw new TypeError("Fastify validator source must be a TypeSea guard, decoder, or route map");
     }
-    readFastifyCompilerMap(source);
+    /*
+     * Route maps are copied once before Fastify requests per-route validators.
+     * Later route selection reads the hardened copy, not caller-controlled
+     * prototype state.
+     */
+    const sourceMap = readFastifyCompilerMap(source);
     return (route) => {
         const part = readFastifyRouteHttpPart(route);
-        const selected = source[part];
+        const selected = sourceMap[part];
         if (selected === undefined) {
             throw new TypeError(`Fastify validator source is missing ${part}`);
         }
@@ -160,46 +206,79 @@ function readFastifyValidatorCompilerSource(source) {
     };
 }
 /**
- * @brief is guard value.
- * @details Performs the same structural guard check as `readGuard` without throwing.
+ * @brief Test whether a value is usable as a guard source.
+ * @details Performs the same structural guard check as `readGuard` without
+ * throwing, which lets the Fastify source normalizer distinguish a single guard
+ * from a route-part map.
+ * @param value Candidate source.
  * @returns True when the value is a TypeSea guard object.
  */
 function isGuardValue(value) {
+    if (isConstructedGuard(value)) {
+        return true;
+    }
     if (!isRecord(value)) {
         return false;
     }
-    const guard = value;
-    return isSchemaValue(value["schema"]) && typeof guard.check === "function";
+    const schema = readOwnDataProperty(value, "schema");
+    const check = readOwnDataProperty(value, "check");
+    return isSchemaValue(schema) && typeof check === "function";
 }
 /**
- * @brief read fastify compiler map.
- * @details Validates every present route-part source before Fastify starts compiling routes.
- * @post No result value is produced; malformed sources throw TypeError.
+ * @brief Copy and validate a Fastify route-part source map.
+ * @details Validates every present route-part source before Fastify starts
+ * compiling routes. The returned table is a frozen null-prototype copy owned by
+ * TypeSea.
+ * @param source Route-part source table supplied by the user.
+ * @returns Frozen null-prototype map containing only own data-property sources.
+ * @post Accessor properties are rejected without executing getters.
  */
 function readFastifyCompilerMap(source) {
-    readOptionalFastifyCompilerPart(source, "body");
-    readOptionalFastifyCompilerPart(source, "querystring");
-    readOptionalFastifyCompilerPart(source, "params");
-    readOptionalFastifyCompilerPart(source, "headers");
+    /*
+     * Null prototype prevents inherited body/querystring/params/headers slots
+     * from becoming validator sources during route selection.
+     */
+    const target = Object.create(null);
+    readOptionalFastifyCompilerPart(source, target, "body");
+    readOptionalFastifyCompilerPart(source, target, "querystring");
+    readOptionalFastifyCompilerPart(source, target, "params");
+    readOptionalFastifyCompilerPart(source, target, "headers");
+    return Object.freeze(target);
 }
 /**
- * @brief read optional fastify compiler part.
- * @details Checks one optional source-map slot without consulting prototype state.
- * @post No result value is produced; malformed present sources throw TypeError.
+ * @brief Copy one optional Fastify route-part source.
+ * @details Copies one own data-property source without consulting prototype
+ * state. Missing parts stay undefined so route selection can fail with the
+ * concrete missing part later.
+ * @param source User supplied route-part source table.
+ * @param target Hardened lookup receiving validated sources.
+ * @param part Fastify HTTP part to copy.
+ * @post Malformed present sources throw TypeError before the compiler is returned.
  */
-function readOptionalFastifyCompilerPart(source, part) {
-    if (!Object.prototype.hasOwnProperty.call(source, part)) {
+function readOptionalFastifyCompilerPart(source, target, part) {
+    /*
+     * getOwnPropertyDescriptor observes own metadata without reading the value
+     * through the prototype chain or invoking an accessor getter.
+     */
+    const descriptor = Object.getOwnPropertyDescriptor(source, part);
+    if (descriptor === undefined) {
         return;
     }
-    const partSource = source[part];
+    if (!Object.prototype.hasOwnProperty.call(descriptor, "value")) {
+        throw new TypeError(`Fastify validator source for ${part} must be a data property`);
+    }
+    const partSource = descriptor.value;
     if (partSource === undefined) {
         throw new TypeError(`Fastify validator source for ${part} must be defined`);
     }
     readSyncAdapterSource(partSource, `Fastify validator source for ${part}`);
+    target[part] = partSource;
 }
 /**
- * @brief read fastify route http part.
- * @details Converts Fastify's route descriptor slot into TypeSea's closed part union.
+ * @brief Normalize Fastify route metadata into a supported HTTP part.
+ * @details Converts Fastify's route descriptor slot into TypeSea's closed part
+ * union so one validator source is never silently reused for a different part.
+ * @param route Fastify validator route descriptor.
  * @returns Validated Fastify HTTP part.
  */
 function readFastifyRouteHttpPart(route) {
@@ -214,7 +293,11 @@ function readFastifyRouteHttpPart(route) {
     }
 }
 /**
- * @brief read async adapter source.
+ * @brief Validate a source accepted by async-capable adapters.
+ * @param source Candidate guard, decoder, or async decoder.
+ * @param label Message prefix for TypeError diagnostics.
+ * @details Async decoders and sync decoders already prove identity through
+ * private registries. Guard-like values still pass through readGuard.
  */
 function readAsyncAdapterSource(source, label) {
     if (isAsyncDecoderValue(source) || isDecoderValue(source)) {
@@ -223,7 +306,11 @@ function readAsyncAdapterSource(source, label) {
     readGuard(source, label);
 }
 /**
- * @brief read fastify part.
+ * @brief Resolve the Fastify route part used for JSON Schema output.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
+ * @param options Optional Fastify route schema options.
+ * @returns The selected HTTP part, defaulting to body.
  */
 function readFastifyPart(options) {
     if (options?.part === undefined) {
@@ -240,8 +327,10 @@ function readFastifyPart(options) {
     }
 }
 /**
- * @brief read fastify json schema options.
- * @details Copies only JSON Schema exporter options out of the adapter options object.
+ * @brief Extract JSON Schema exporter options from Fastify options.
+ * @details Copies only JSON Schema exporter options out of the adapter options
+ * object. The returned object avoids exact-optional undefined fields.
+ * @param options Optional Fastify route schema options.
  * @returns Partial JSON Schema options without exact-optional undefined slots.
  */
 function readFastifyJsonSchemaOptions(options) {
@@ -255,7 +344,12 @@ function readFastifyJsonSchemaOptions(options) {
     return output;
 }
 /**
- * @brief read react hook form options.
+ * @brief Normalize React Hook Form resolver options.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
+ * @param options Optional resolver options.
+ * @returns Required options object used by the resolver.
+ * @throws TypeError when options are not object-like.
  */
 function readReactHookFormOptions(options) {
     if (options === undefined) {
@@ -271,7 +365,12 @@ function readReactHookFormOptions(options) {
     };
 }
 /**
- * @brief issues to react hook form errors.
+ * @brief Convert TypeSea issues into React Hook Form field errors.
+ * @param issues Frozen TypeSea issue vector.
+ * @param options Message formatting options.
+ * @returns Frozen nested FieldErrors-compatible object.
+ * @details React Hook Form resolves nested fields by object traversal, so
+ * TypeSea paths are inserted as nested branches rather than flat dotted keys.
  */
 function issuesToReactHookFormErrors(issues, options) {
     const errors = makeReactHookFormErrorBranch();
@@ -285,19 +384,21 @@ function issuesToReactHookFormErrors(issues, options) {
     return freezeReactHookFormErrors(errors);
 }
 /**
- * @brief make react hook form error branch.
- * @details Allocates one null-prototype object so form field names cannot collide with inherited keys.
+ * @brief Allocate one mutable React Hook Form error branch.
+ * @details Null prototype branches keep field names such as `constructor` or
+ * `__proto__` from colliding with inherited object members.
  * @returns Mutable branch owned by the caller.
  */
 function makeReactHookFormErrorBranch() {
     return Object.create(null);
 }
 /**
- * @brief insert react hook form issue.
- * @details Inserts one TypeSea issue into a nested React Hook Form error tree.
- * @param errors Borrowed output branch that receives the leaf error when absent.
- * @param issue Borrowed input issue; its path is converted into string map keys.
- * @param options Borrowed input message options used only for new leaf formatting.
+ * @brief Insert one TypeSea issue into a nested React Hook Form tree.
+ * @details Existing leaf errors are preserved because React Hook Form reports
+ * the first error for a field by default.
+ * @param errors Mutable root branch receiving the leaf error when absent.
+ * @param issue Issue whose path is converted into branch keys.
+ * @param options Message options used only when a leaf is created.
  * @post Existing first errors are preserved to match React Hook Form resolver behavior.
  */
 function insertReactHookFormIssue(errors, issue, options) {
@@ -337,7 +438,7 @@ function insertReactHookFormIssue(errors, issue, options) {
 /**
  * @brief react hook form path key.
  * @details Converts one TypeSea path segment into the object key React Hook Form traverses.
- * @param segment Borrowed input path segment.
+ * @param segment Path segment from a TypeSea issue.
  * @returns Stable string key for object or array-index lookup.
  */
 function reactHookFormPathKey(segment) {
@@ -346,7 +447,7 @@ function reactHookFormPathKey(segment) {
 /**
  * @brief freeze react hook form errors.
  * @details Recursively freezes the null-prototype tree after all issues have been inserted.
- * @param errors Borrowed mutable branch that becomes immutable before publication.
+ * @param errors Mutable branch that becomes immutable before publication.
  * @returns Frozen React Hook Form error tree.
  */
 function freezeReactHookFormErrors(errors) {
@@ -364,7 +465,7 @@ function freezeReactHookFormErrors(errors) {
     return Object.freeze(errors);
 }
 /**
- * @brief is react hook form error branch.
+ * @brief Test whether a React Hook Form node is an internal branch.
  * @details Distinguishes internal branch objects from frozen leaf error objects.
  * @param value Candidate branch or leaf error value.
  * @returns True when value is a null-prototype branch object.
@@ -381,16 +482,36 @@ function isReactHookFormErrorBranch(value) {
  */
 const rootIssuePath = Object.freeze(["root"]);
 /**
- * @brief is record.
+ * @brief Check record.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief empty errors.
+ * @brief Read one own data slot from an adapter input object.
+ * @details Adapter shapes stay local so TypeSea diagnostics can be translated without
+ * adding framework dependencies.
+ * @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 Shared immutable success errors object for React Hook Form.
+ * @details Reusing this object avoids allocating a fresh empty tree on every
+ * successful resolver call.
  */
 const emptyErrors = Object.freeze({});
 /**
- * @brief empty values.
+ * @brief Shared immutable values object used when resolver validation fails.
+ * @details React Hook Form expects failed resolvers to return no accepted values.
  */
 const emptyValues = Object.freeze({});

package/dist/aot/index.d.ts

@@ -1,12 +1,17 @@
+import type { CompileMode } from "../compile/index.js";
 import type { Guard, Presence } from "../guard/index.js";
 import type { PathSegment } from "../issue/index.js";
 import { type Result } from "../result/index.js";
 /**
  * @brief aot issue code.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 export type AotIssueCode = "unsupported_aot_lazy" | "unsupported_aot_refine" | "unsupported_aot_symbol_literal";
 /**
  * @brief aot issue.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 export interface AotIssue {
     readonly path: readonly PathSegment[];
@@ -15,19 +20,30 @@ export interface AotIssue {
 }
 /**
  * @brief aot compile options.
+ * @details AOT helpers serialize only portable data because standalone modules cannot close
+ * over runtime side tables.
  */
 export interface AotCompileOptions {
     readonly name: string | undefined;
+    readonly mode: CompileMode | undefined;
 }
 /**
- * @brief aot module.
+ * @brief Source pair emitted for ahead-of-time validation.
+ * @details `source` is the JavaScript module body; `declarationSource` is the
+ * companion TypeScript declaration used by package consumers.
  */
 export interface AotModule {
     readonly source: string;
     readonly declarationSource: string;
 }
 /**
- * @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 declare function emitAotModule(guard: Guard<unknown, Presence>, options?: Partial<AotCompileOptions>): Result<AotModule, readonly AotIssue[]>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/aot/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAQ1D;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,sBAAsB,GACtB,wBAAwB,GACxB,gCAAgC,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AASD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,MAAM,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC,CAsBxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/aot/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAQ1D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAClB,sBAAsB,GACtB,wBAAwB,GACxB,gCAAgC,CAAC;AAEvC;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,CAAC;CAC1C;AAYD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CACzB,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACrC,MAAM,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC,CAsBxC"}