typesea 0.1.0 → 0.2.0

package/dist/issue/index.d.ts

@@ -1,14 +1,20 @@
 import type { Result } from "../result/index.js";
 /**
- * @brief path segment.
+ * @brief One segment in a validation issue path.
+ * @details Strings represent object keys and numbers represent array indexes.
+ * The path formatter decides how those segments become user-facing text.
  */
 export type PathSegment = string | number;
 /**
- * @brief issue code.
+ * @brief Closed set of validation issue codes emitted by TypeSea.
+ * @details Codes are stable machine-readable diagnostics shared by interpreters,
+ * compiled collectors, adapters, and message catalogs.
  */
 export type IssueCode = "expected_string" | "expected_number" | "expected_bigint" | "expected_symbol" | "expected_boolean" | "expected_never" | "expected_literal" | "expected_array" | "expected_tuple" | "expected_tuple_length" | "expected_object" | "expected_record" | "expected_integer" | "expected_min_length" | "expected_max_length" | "expected_pattern" | "expected_gte" | "expected_lte" | "expected_required_key" | "expected_union" | "expected_discriminant" | "expected_refinement" | "expected_depth_limit" | "unrecognized_key";
 /**
- * @brief issue.
+ * @brief Immutable validation diagnostic.
+ * @details The message field is optional so hot boolean validation and
+ * low-level collectors can defer human-readable formatting until requested.
  */
 export interface Issue {
     readonly path: readonly PathSegment[];
@@ -18,27 +24,53 @@ export interface Issue {
     readonly message: string | undefined;
 }
 /**
- * @brief check result.
+ * @brief Result shape returned by diagnostic validation APIs.
+ * @details Success carries the accepted value, failure carries a frozen issue
+ * array suitable for message formatting or adapter conversion.
  */
 export type CheckResult<TValue> = Result<TValue, readonly Issue[]>;
 /**
- * @brief make issue.
+ * @brief Construct one issue record without freezing it.
+ * @details Collectors use this helper while building mutable arrays, then
+ * freeze the final array at the API boundary.
+ * @param path Path to the failing value.
+ * @param code Stable issue code.
+ * @param expected Expected-value label, when available.
+ * @param actual Actual-value label, when available.
+ * @param message Pre-rendered human message, when available.
+ * @returns Mutable issue record ready for collection.
  */
 export declare function makeIssue(path: readonly PathSegment[], code: IssueCode, expected: string | undefined, actual: string | undefined, message: string | undefined): Issue;
 /**
- * @brief copy issue array.
+ * @brief Defensive-copy externally supplied issue arrays before publication.
+ * @details Adapter and user callback boundaries may hand back mutable objects.
+ * Copying revalidates shape and ensures TypeSea publishes frozen diagnostics.
+ * @param value Candidate issue array.
+ * @returns Frozen issue array with copied paths.
  */
 export declare function copyIssueArray(value: unknown): readonly Issue[];
 /**
- * @brief finalize issue array.
+ * @brief Normalize generated collector output into the public immutable shape.
+ * @details Generated collectors return arrays only on failure. Empty arrays use
+ * the shared sentinel so failed-but-empty states cannot allocate repeatedly.
+ * @param value Candidate issue array from a collector.
+ * @returns Frozen public issue array.
  */
 export declare function finalizeIssueArray(value: unknown): readonly Issue[];
 /**
- * @brief freeze issue array.
+ * @brief Freeze issues and their path arrays in-place.
+ * @details Paths are built mutably for speed during collection, then hardened
+ * before callers can retain or format the diagnostics.
+ * @param issues Issue array to harden.
+ * @returns The same issue array after freezing.
  */
 export declare function freezeIssueArray(issues: readonly Issue[]): readonly Issue[];
 /**
- * @brief is issue code value.
+ * @brief Check whether a value is one of TypeSea's stable issue codes.
+ * @details Issue helpers publish frozen diagnostics so adapters and callers cannot mutate
+ * validation results later.
+ * @param value Candidate issue code.
+ * @returns True when the value belongs to the closed issue-code set.
  */
 export declare function isIssueCodeValue(value: unknown): value is IssueCode;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/issue/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,uBAAuB,GACvB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,qBAAqB,GACrB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,uBAAuB,GACvB,gBAAgB,GAChB,uBAAuB,GACvB,qBAAqB,GACrB,sBAAsB,GACtB,kBAAkB,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC,CAAC;AAOnE;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAQP;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,KAAK,EAAE,CAS/D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,KAAK,EAAE,CAQnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,KAAK,EAAE,CAS3E;AAkDD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CA8BnE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/issue/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACf,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,uBAAuB,GACvB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,qBAAqB,GACrB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,uBAAuB,GACvB,gBAAgB,GAChB,uBAAuB,GACvB,qBAAqB,GACrB,sBAAsB,GACtB,kBAAkB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,WAAW,KAAK;IAClB,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC,CAAC;AAUnE;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACrB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,GAC5B,KAAK,CAQP;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,KAAK,EAAE,CAS/D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,KAAK,EAAE,CAQnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,KAAK,EAAE,CAS3E;AA6DD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CA8BnE"}

package/dist/issue/index.js

@@ -1,9 +1,20 @@
 /**
- * @brief empty issues.
+ * @brief Shared success sentinel for compiled check() paths.
+ * @details Reusing a frozen empty array avoids allocating diagnostics for
+ * successful validation.
  */
 const EMPTY_ISSUES = Object.freeze([]);
+const EMPTY_PATH = Object.freeze([]);
 /**
- * @brief make issue.
+ * @brief Construct one issue record without freezing it.
+ * @details Collectors use this helper while building mutable arrays, then
+ * freeze the final array at the API boundary.
+ * @param path Path to the failing value.
+ * @param code Stable issue code.
+ * @param expected Expected-value label, when available.
+ * @param actual Actual-value label, when available.
+ * @param message Pre-rendered human message, when available.
+ * @returns Mutable issue record ready for collection.
  */
 export function makeIssue(path, code, expected, actual, message) {
     return {
@@ -15,7 +26,11 @@ export function makeIssue(path, code, expected, actual, message) {
     };
 }
 /**
- * @brief copy issue array.
+ * @brief Defensive-copy externally supplied issue arrays before publication.
+ * @details Adapter and user callback boundaries may hand back mutable objects.
+ * Copying revalidates shape and ensures TypeSea publishes frozen diagnostics.
+ * @param value Candidate issue array.
+ * @returns Frozen issue array with copied paths.
  */
 export function copyIssueArray(value) {
     if (!isUnknownArray(value)) {
@@ -28,7 +43,11 @@ export function copyIssueArray(value) {
     return freezeIssueArray(copied);
 }
 /**
- * @brief finalize issue array.
+ * @brief Normalize generated collector output into the public immutable shape.
+ * @details Generated collectors return arrays only on failure. Empty arrays use
+ * the shared sentinel so failed-but-empty states cannot allocate repeatedly.
+ * @param value Candidate issue array from a collector.
+ * @returns Frozen public issue array.
  */
 export function finalizeIssueArray(value) {
     if (!isUnknownArray(value)) {
@@ -40,7 +59,11 @@ export function finalizeIssueArray(value) {
     return copyIssueArray(value);
 }
 /**
- * @brief freeze issue array.
+ * @brief Freeze issues and their path arrays in-place.
+ * @details Paths are built mutably for speed during collection, then hardened
+ * before callers can retain or format the diagnostics.
+ * @param issues Issue array to harden.
+ * @returns The same issue array after freezing.
  */
 export function freezeIssueArray(issues) {
     for (let index = 0; index < issues.length; index += 1) {
@@ -53,7 +76,11 @@ export function freezeIssueArray(issues) {
     return Object.freeze(issues);
 }
 /**
- * @brief copy issue.
+ * @brief Copy and validate one issue-like object.
+ * @details Only own data read syntax is used here because the candidate object
+ * has already been reduced to a plain record by `isRecord`.
+ * @param value Candidate issue object.
+ * @returns Normalized mutable issue record.
  */
 function copyIssue(value) {
     if (!isRecord(value)) {
@@ -75,12 +102,19 @@ function copyIssue(value) {
     return makeIssue(path, code, expected, actual, message);
 }
 /**
- * @brief copy path.
+ * @brief Copy and validate an issue path.
+ * @details Negative and fractional numeric segments are rejected because TypeSea
+ * only emits non-negative array indexes.
+ * @param value Candidate path array.
+ * @returns Copied path, or the shared empty-path sentinel.
  */
 function copyPath(value) {
     if (!isUnknownArray(value)) {
         throw new TypeError("issue path must be an array");
     }
+    if (value.length === 0) {
+        return EMPTY_PATH;
+    }
     const copied = new Array(value.length);
     for (let index = 0; index < value.length; index += 1) {
         const segment = value[index];
@@ -99,7 +133,11 @@ function copyPath(value) {
     return copied;
 }
 /**
- * @brief is issue code value.
+ * @brief Check whether a value is one of TypeSea's stable issue codes.
+ * @details Issue helpers publish frozen diagnostics so adapters and callers cannot mutate
+ * validation results later.
+ * @param value Candidate issue code.
+ * @returns True when the value belongs to the closed issue-code set.
  */
 export function isIssueCodeValue(value) {
     switch (value) {
@@ -133,19 +171,31 @@ export function isIssueCodeValue(value) {
     }
 }
 /**
- * @brief is optional string.
+ * @brief Accept optional text fields used by issue diagnostics.
+ * @details Issue helpers publish frozen diagnostics so adapters and callers cannot mutate
+ * validation results later.
+ * @param value Candidate issue text field.
+ * @returns True for string values and undefined.
  */
 function isOptionalString(value) {
     return value === undefined || typeof value === "string";
 }
 /**
- * @brief is record.
+ * @brief Check whether a value can be read as an issue-like record.
+ * @details Issue helpers publish frozen diagnostics so adapters and callers cannot mutate
+ * validation results later.
+ * @param value Candidate runtime value.
+ * @returns True for non-array object values.
  */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief is unknown array.
+ * @brief Check whether a value is an array before indexed reads.
+ * @details Issue helpers publish frozen diagnostics so adapters and callers cannot mutate
+ * validation results later.
+ * @param value Candidate runtime value.
+ * @returns True when the value is an array.
  */
 function isUnknownArray(value) {
     return Array.isArray(value);

package/dist/json-schema/emit-combinator.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file emit-combinator.ts
  * @brief Combinator TypeSea schema to JSON Schema emitters.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { SchemaTag } from "../kind/index.js";
 import type { PathSegment } from "../issue/index.js";
@@ -8,21 +10,59 @@ import type { Schema } from "../schema/index.js";
 import type { JsonSchemaEmitter } from "./emit-types.js";
 import type { JsonSchema, JsonSchemaDialect, JsonSchemaExportIssue } from "./types.js";
 /**
- * @brief emit union.
+ * @brief Emit a TypeSea union as a JSON Schema `anyOf` list.
+ * @details Each branch is emitted with its index appended to the issue path so
+ * unsupported children can be reported precisely. A single failed child aborts
+ * the whole union because dropping a branch would make the exported schema
+ * stricter than the TypeSea validator.
+ * @param options Union option schemas in declaration order.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema union, or undefined when a child cannot be emitted.
  */
 export declare function emitUnion(options: readonly Schema[], path: PathSegment[], issues: JsonSchemaExportIssue[], emitChild: JsonSchemaEmitter, dialect: JsonSchemaDialect): JsonSchema | undefined;
 /**
- * @brief emit intersection.
+ * @brief Emit a TypeSea intersection as a JSON Schema `allOf` pair.
+ * @details Both sides must be representable. If either side fails, the exported
+ * schema would no longer model the same acceptance set, so the emitter reports
+ * the failed side and returns undefined.
+ * @param left Left intersection operand.
+ * @param right Right intersection operand.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema intersection, or undefined when a side cannot be emitted.
  */
 export declare function emitIntersection(left: Schema, right: Schema, path: PathSegment[], issues: JsonSchemaExportIssue[], emitChild: JsonSchemaEmitter, dialect: JsonSchemaDialect): JsonSchema | undefined;
 /**
- * @brief emit discriminated union.
+ * @brief Emit a discriminated union through the general union exporter.
+ * @details JSON Schema output does not need TypeSea's dispatch table; it only
+ * needs the branch schemas. The discriminant proof has already been enforced at
+ * builder time, so preserving branch order is enough for diagnostics.
+ * @param cases Discriminated-union cases from the TypeSea schema.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema union, or undefined when a child cannot be emitted.
  */
 export declare function emitDiscriminatedUnion(cases: Extract<Schema, {
     readonly tag: typeof SchemaTag.DiscriminatedUnion;
 }>["cases"], path: PathSegment[], issues: JsonSchemaExportIssue[], emitChild: JsonSchemaEmitter, dialect: JsonSchemaDialect): JsonSchema | undefined;
 /**
- * @brief emit nullable.
+ * @brief Emit a nullable wrapper as an `anyOf` with `null`.
+ * @details The wrapped schema is emitted first so unsupported inner constructs
+ * are reported at a stable `nullable` path segment instead of silently widening
+ * to just null.
+ * @param inner Inner TypeSea schema.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns Nullable JSON Schema, or undefined when the inner schema fails.
  */
 export declare function emitNullable(inner: Schema, path: PathSegment[], issues: JsonSchemaExportIssue[], emitChild: JsonSchemaEmitter, dialect: JsonSchemaDialect): JsonSchema | undefined;
 //# sourceMappingURL=emit-combinator.d.ts.map

package/dist/json-schema/emit-combinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit-combinator.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-combinator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CAyBxB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CAuBxB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;IACrB,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,kBAAkB,CAAA;CAClD,CAAC,CAAC,OAAO,CAAC,EACX,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CASxB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CAiBxB"}
+{"version":3,"file":"emit-combinator.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-combinator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EACR,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACrB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAyBxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAuBxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;IACnB,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,kBAAkB,CAAA;CACpD,CAAC,CAAC,OAAO,CAAC,EACX,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CASxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAiBxB"}

package/dist/json-schema/emit-combinator.js

@@ -1,11 +1,23 @@
 /**
  * @file emit-combinator.ts
  * @brief Combinator TypeSea schema to JSON Schema emitters.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { SchemaTag } from "../kind/index.js";
 import { pushJsonSchemaIssue } from "./issue.js";
 /**
- * @brief emit union.
+ * @brief Emit a TypeSea union as a JSON Schema `anyOf` list.
+ * @details Each branch is emitted with its index appended to the issue path so
+ * unsupported children can be reported precisely. A single failed child aborts
+ * the whole union because dropping a branch would make the exported schema
+ * stricter than the TypeSea validator.
+ * @param options Union option schemas in declaration order.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema union, or undefined when a child cannot be emitted.
  */
 export function emitUnion(options, path, issues, emitChild, dialect) {
     const emitted = new Array(options.length);
@@ -34,7 +46,17 @@ export function emitUnion(options, path, issues, emitChild, dialect) {
     };
 }
 /**
- * @brief emit intersection.
+ * @brief Emit a TypeSea intersection as a JSON Schema `allOf` pair.
+ * @details Both sides must be representable. If either side fails, the exported
+ * schema would no longer model the same acceptance set, so the emitter reports
+ * the failed side and returns undefined.
+ * @param left Left intersection operand.
+ * @param right Right intersection operand.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema intersection, or undefined when a side cannot be emitted.
  */
 export function emitIntersection(left, right, path, issues, emitChild, dialect) {
     path.push("left");
@@ -61,7 +83,16 @@ export function emitIntersection(left, right, path, issues, emitChild, dialect)
     };
 }
 /**
- * @brief emit discriminated union.
+ * @brief Emit a discriminated union through the general union exporter.
+ * @details JSON Schema output does not need TypeSea's dispatch table; it only
+ * needs the branch schemas. The discriminant proof has already been enforced at
+ * builder time, so preserving branch order is enough for diagnostics.
+ * @param cases Discriminated-union cases from the TypeSea schema.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema union, or undefined when a child cannot be emitted.
  */
 export function emitDiscriminatedUnion(cases, path, issues, emitChild, dialect) {
     const options = new Array(cases.length);
@@ -74,7 +105,16 @@ export function emitDiscriminatedUnion(cases, path, issues, emitChild, dialect)
     return emitUnion(options, path, issues, emitChild, dialect);
 }
 /**
- * @brief emit nullable.
+ * @brief Emit a nullable wrapper as an `anyOf` with `null`.
+ * @details The wrapped schema is emitted first so unsupported inner constructs
+ * are reported at a stable `nullable` path segment instead of silently widening
+ * to just null.
+ * @param inner Inner TypeSea schema.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param emitChild Recursive schema emitter callback.
+ * @param dialect Target JSON Schema dialect.
+ * @returns Nullable JSON Schema, or undefined when the inner schema fails.
  */
 export function emitNullable(inner, path, issues, emitChild, dialect) {
     path.push("nullable");

package/dist/json-schema/emit-composite.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file emit-composite.ts
  * @brief Container TypeSea schema to JSON Schema emitters.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { SchemaTag } from "../kind/index.js";
 import type { PathSegment } from "../issue/index.js";
@@ -9,18 +11,26 @@ import type { JsonSchemaEmitter } from "./emit-types.js";
 import type { JsonSchema, JsonSchemaDialect, JsonSchemaExportIssue } from "./types.js";
 /**
  * @brief emit array.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export declare function emitArray(item: Schema, path: PathSegment[], issues: JsonSchemaExportIssue[], emitChild: JsonSchemaEmitter, dialect: JsonSchemaDialect): JsonSchema | undefined;
 /**
  * @brief emit tuple.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export declare function emitTuple(items: readonly Schema[], path: PathSegment[], issues: JsonSchemaExportIssue[], emitChild: JsonSchemaEmitter, dialect: JsonSchemaDialect): JsonSchema | undefined;
 /**
  * @brief emit record.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export declare function emitRecord(value: Schema, path: PathSegment[], issues: JsonSchemaExportIssue[], emitChild: JsonSchemaEmitter, dialect: JsonSchemaDialect): JsonSchema | undefined;
 /**
  * @brief emit object.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export declare function emitObject(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.Object;

package/dist/json-schema/emit-composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit-composite.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-composite.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,SAAS,EACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CAaxB;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CAqCxB;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CAaxB;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CAoCxB"}
+{"version":3,"file":"emit-composite.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-composite.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGH,SAAS,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,KAAK,EACR,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EAExB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,wBAAgB,SAAS,CACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAaxB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACrB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAqCxB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAaxB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAoCxB"}

package/dist/json-schema/emit-composite.js

@@ -1,11 +1,15 @@
 /**
  * @file emit-composite.ts
  * @brief Container TypeSea schema to JSON Schema emitters.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { ObjectModeTag, PresenceTag, SchemaTag } from "../kind/index.js";
 import { pushJsonSchemaIssue } from "./issue.js";
 /**
  * @brief emit array.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export function emitArray(item, path, issues, emitChild, dialect) {
     path.push("items");
@@ -23,6 +27,8 @@ export function emitArray(item, path, issues, emitChild, dialect) {
 }
 /**
  * @brief emit tuple.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export function emitTuple(items, path, issues, emitChild, dialect) {
     const emitted = new Array(items.length);
@@ -64,6 +70,8 @@ export function emitTuple(items, path, issues, emitChild, dialect) {
 }
 /**
  * @brief emit record.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export function emitRecord(value, path, issues, emitChild, dialect) {
     path.push("additionalProperties");
@@ -81,6 +89,8 @@ export function emitRecord(value, path, issues, emitChild, dialect) {
 }
 /**
  * @brief emit object.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export function emitObject(schema, path, issues, emitChild, dialect) {
     const properties = makeJsonSchemaProperties();
@@ -120,7 +130,11 @@ export function emitObject(schema, path, issues, emitChild, dialect) {
     return result;
 }
 /**
- * @brief make json schema properties.
+ * @brief Allocate the JSON Schema property table with no prototype chain.
+ * @details Object schema keys originate from user models. A null-prototype map
+ * prevents names such as `constructor` from colliding with inherited object
+ * members while keeping writes monomorphic for the emitter loop.
+ * @returns Empty mutable property table for an object schema emission pass.
  */
 function makeJsonSchemaProperties() {
     return Object.create(null);

package/dist/json-schema/emit-scalar.d.ts

@@ -1,25 +1,48 @@
 /**
  * @file emit-scalar.ts
  * @brief Scalar TypeSea schema to JSON Schema emitters.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { SchemaTag } from "../kind/index.js";
 import type { PathSegment } from "../issue/index.js";
 import { type LiteralValue, type Schema } from "../schema/index.js";
 import type { JsonSchema, JsonSchemaExportIssue } from "./types.js";
 /**
- * @brief emit string.
+ * @brief Emit TypeSea string checks into JSON Schema string keywords.
+ * @details Repeated min and max checks collapse to the strongest bounds.
+ * Regular expressions are emitted only when their flags can be preserved by the
+ * JSON Schema `pattern` keyword; unsupported flags are reported as issues.
+ * @param schema String schema to emit.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema string object.
  */
 export declare function emitString(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.String;
 }>, path: PathSegment[], issues: JsonSchemaExportIssue[]): JsonSchema;
 /**
- * @brief emit number.
+ * @brief Emit TypeSea number checks into JSON Schema number keywords.
+ * @details Integer checks narrow the emitted type, while finite lower and upper
+ * bounds collapse to the strongest minimum and maximum. Non-finite bounds are
+ * rejected because JSON Schema cannot preserve them portably.
+ * @param schema Number schema to emit.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema number object, or undefined when bounds are unsupported.
  */
 export declare function emitNumber(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.Number;
 }>, path: PathSegment[], issues: JsonSchemaExportIssue[]): JsonSchema | undefined;
 /**
- * @brief emit literal.
+ * @brief Emit a literal schema as a JSON Schema `const` value.
+ * @details Only JSON-compatible literals are accepted. Undefined, bigint,
+ * symbol, NaN, infinity, and negative zero have no faithful JSON Schema literal
+ * encoding, so they become export issues instead of weakened output.
+ * @param value Literal value carried by the TypeSea schema.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema const object, or undefined for unsupported literals.
  */
 export declare function emitLiteral(value: LiteralValue, path: PathSegment[], issues: JsonSchemaExportIssue[]): JsonSchema | undefined;
 //# sourceMappingURL=emit-scalar.d.ts.map

package/dist/json-schema/emit-scalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit-scalar.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-scalar.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEL,SAAS,EAEV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAC9B,UAAU,CAkCZ;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAC9B,UAAU,GAAG,SAAS,CAiCxB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAC9B,UAAU,GAAG,SAAS,CAyBxB"}
+{"version":3,"file":"emit-scalar.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-scalar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEH,SAAS,EAEZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAEH,KAAK,YAAY,EACjB,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EACR,UAAU,EACV,qBAAqB,EAExB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAChC,UAAU,CAwCZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAChC,UAAU,GAAG,SAAS,CAqCxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACvB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAChC,UAAU,GAAG,SAAS,CAyBxB"}