typesea 0.1.0 → 0.3.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";
+export type IssueCode = "expected_string" | "expected_number" | "expected_date" | "expected_bigint" | "expected_symbol" | "expected_boolean" | "expected_never" | "expected_literal" | "expected_array" | "expected_map" | "expected_set" | "expected_instance" | "expected_tuple" | "expected_tuple_length" | "expected_object" | "expected_record" | "expected_integer" | "expected_min_length" | "expected_max_length" | "expected_pattern" | "expected_gte" | "expected_lte" | "expected_gt" | "expected_lt" | "expected_multiple_of" | "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,eAAe,GACf,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,mBAAmB,GACnB,gBAAgB,GAChB,uBAAuB,GACvB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,qBAAqB,GACrB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,aAAa,GACb,aAAa,GACb,sBAAsB,GACtB,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,CAkCnE"}

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,12 +133,17 @@ 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) {
         case "expected_string":
         case "expected_number":
+        case "expected_date":
         case "expected_bigint":
         case "expected_symbol":
         case "expected_boolean":
@@ -121,6 +160,9 @@ export function isIssueCodeValue(value) {
         case "expected_pattern":
         case "expected_gte":
         case "expected_lte":
+        case "expected_gt":
+        case "expected_lt":
+        case "expected_multiple_of":
         case "expected_required_key":
         case "expected_union":
         case "expected_discriminant":
@@ -133,19 +175,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,30 @@ 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;
+export declare function emitArray(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.Array;
+}>, 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;
+export declare function emitTuple(schema: Extract<Schema, {
+    readonly tag: typeof SchemaTag.Tuple;
+}>, 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,EAIH,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,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,KAAK,CAAA;CAAE,CAAC,EACjE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAkCxB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACrB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,KAAK,CAAA;CAAE,CAAC,EACjE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAyDxB;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,CAgDxB"}

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

@@ -1,13 +1,18 @@
 /**
  * @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 { ArrayCheckTag, 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) {
+export function emitArray(schema, path, issues, emitChild, dialect) {
+    const item = schema.item;
     path.push("items");
     const emitted = emitChild(item, path, issues, dialect);
     if (emitted === undefined) {
@@ -16,15 +21,38 @@ export function emitArray(item, path, issues, emitChild, dialect) {
         return undefined;
     }
     path.pop();
-    return {
+    const result = {
         type: "array",
         items: emitted
     };
+    const checks = schema.checks;
+    for (let index = 0; index < checks.length; index += 1) {
+        const check = checks[index];
+        if (check === undefined) {
+            continue;
+        }
+        switch (check.tag) {
+            case ArrayCheckTag.Min:
+                result.minItems = result.minItems === undefined
+                    ? check.value
+                    : Math.max(result.minItems, check.value);
+                break;
+            case ArrayCheckTag.Max:
+                result.maxItems = result.maxItems === undefined
+                    ? check.value
+                    : Math.min(result.maxItems, check.value);
+                break;
+        }
+    }
+    return result;
 }
 /**
  * @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) {
+export function emitTuple(schema, path, issues, emitChild, dialect) {
+    const items = schema.items;
     const emitted = new Array(items.length);
     let failed = false;
     for (let index = 0; index < items.length; index += 1) {
@@ -46,24 +74,46 @@ export function emitTuple(items, path, issues, emitChild, dialect) {
     if (failed) {
         return undefined;
     }
+    let restSchema;
+    if (schema.rest !== undefined) {
+        path.push("rest");
+        restSchema = emitChild(schema.rest, path, issues, dialect);
+        if (restSchema === undefined) {
+            pushJsonSchemaIssue(path, issues, "unsupported_child", "Tuple rest schema is unsupported");
+            path.pop();
+            return undefined;
+        }
+        path.pop();
+    }
     if (dialect === "2020-12") {
-        return {
+        const result = {
             type: "array",
             prefixItems: emitted,
-            minItems: items.length,
-            maxItems: items.length
+            minItems: items.length
         };
+        if (restSchema === undefined) {
+            result.maxItems = items.length;
+        }
+        else {
+            result.items = restSchema;
+        }
+        return result;
     }
-    return {
+    const result = {
         type: "array",
         items: emitted,
-        additionalItems: false,
-        minItems: items.length,
-        maxItems: items.length
+        additionalItems: restSchema ?? false,
+        minItems: items.length
     };
+    if (restSchema === undefined) {
+        result.maxItems = items.length;
+    }
+    return result;
 }
 /**
  * @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 +131,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();
@@ -109,10 +161,22 @@ export function emitObject(schema, path, issues, emitChild, dialect) {
     if (failed) {
         return undefined;
     }
+    let additionalProperties = schema.mode !== ObjectModeTag.Strict;
+    if (schema.catchall !== undefined) {
+        path.push("additionalProperties");
+        const emittedCatchall = emitChild(schema.catchall, path, issues, dialect);
+        if (emittedCatchall === undefined) {
+            pushJsonSchemaIssue(path, issues, "unsupported_child", "Object catchall schema is unsupported");
+            path.pop();
+            return undefined;
+        }
+        path.pop();
+        additionalProperties = emittedCatchall;
+    }
     const result = {
         type: "object",
         properties,
-        additionalProperties: schema.mode !== ObjectModeTag.Strict
+        additionalProperties
     };
     if (required.length !== 0) {
         result.required = required;
@@ -120,7 +184,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);