schema-components 1.21.0 → 1.23.0

package/README.md

@@ -16,7 +16,9 @@ Peer dependencies: `zod@^4.0.0`, `react@^18.0.0 || ^19.0.0`.
 
 ### Zod version requirement
 
-schema-components requires **Zod 4**. If you are on Zod 3, see the [Zod 4 migration guide](https://zod.dev/v4/migration). The library detects Zod 3 inputs and throws a descriptive error rather than silently misbehaving.
+schema-components requires **Zod 4**. If you are on Zod 3, see the [Zod 4 migration guide](https://zod.dev/v4/migration). Zod 3 schemas are detected structurally — any object exposing `_def` without the Zod 4 `_zod` marker is classified as Zod 3, with or without the historical `_def.typeName` field. (Some third-party Zod-3-style libraries omit `typeName`; the detector keys on the presence of `_def` alone.) A descriptive `SchemaNormalisationError` is raised pointing at the Zod 4 migration guide.
+
+Schemas from other libraries that conform to the [Standard Schema](https://standardschema.dev/) spec (valibot, arktype, ...) are also detected and rejected. When the input advertises a `~standard.vendor` field, the error message includes the vendor name so consumers know which library produced the input.
 
 ## `SchemaComponent`
 

package/dist/core/adapter.d.mts

@@ -1,10 +1,103 @@
-import { T as SchemaMeta, m as JsonObject } from "../types-BnxPEElk.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { m as JsonObject, w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;
-type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi";
+type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi" | "unsupported-schema-lib";
+/**
+ * Classify the input schema by its structural markers.
+ *
+ * - `zod4` — has a `_zod` marker (further validation that `_zod.def` is a
+ *   non-null object happens inside `normaliseZod4`).
+ * - `zod3` — has `_def` and no `_zod`. The `typeName` field is no longer
+ *   required: any `_def` without `_zod` is treated as a probable Zod 3
+ *   schema. Third-party libraries that expose `_def` without `_zod` are
+ *   nearly always Zod 3 forks; surfacing the migration message is the
+ *   correct response.
+ * - `openapi` — has `openapi` or `swagger` at the root.
+ * - `unsupported-schema-lib` — has `parse` and `safeParse` callables but
+ *   no `_zod` and no `_def` marker. This catches Standard Schema
+ *   implementations (valibot, arktype, etc.) that would otherwise flow
+ *   through as "malformed JSON Schema".
+ * - `jsonSchema` — fallback for anything that does not match the above.
+ */
 declare function detectSchemaKind(input: unknown): SchemaKind;
+/**
+ * Wraps z.toJSONSchema() for a runtime-validated Zod schema.
+ *
+ * The _zod guard in normaliseZod4 has confirmed this is a valid Zod schema,
+ * but TypeScript cannot represent "has _zod.def" as the $ZodType parameter
+ * that z.toJSONSchema expects. This is the library boundary equivalent of
+ * object → Record<string, unknown> — the type mismatch is genuinely unavoidable.
+ *
+ * # Options
+ *
+ * `z.toJSONSchema` is invoked with an explicit options object rather than
+ * Zod's defaults so the conversion contract is pinned and stable:
+ *
+ * - `target: "draft-2020-12"` — matches the walker's draft target.
+ * - `unrepresentable: "throw"` — keeps the unrepresentable-type rules in
+ *   the classifier table firing instead of silently emitting `{}`.
+ * - `cycles: "ref"` — converts cyclic graphs into $ref pairs rather than
+ *   throwing. Cycles in user schemas surface through the walker's $ref
+ *   resolution rather than the adapter.
+ * - `io` — selects which side of every transform / pipe / codec is
+ *   converted. Defaults to `"output"` (the OUTPUT side); pass `"input"`
+ *   to render the INPUT side instead. The input side is invisible to
+ *   the converted schema when `io: "output"` is in force, even though
+ *   `safeParse` on the same Zod schema consumes the input shape. For
+ *   transforms this divergence is fatal and the call throws via
+ *   `Transforms cannot be represented`; for `z.codec(...)` the call
+ *   succeeds but only the selected side is rendered. Consumers receive
+ *   a `zod-codec-output-only` diagnostic in the codec case so the
+ *   asymmetry is visible — see `screenPreConversion`.
+ *
+ * # Error classification
+ *
+ * Any exception thrown by z.toJSONSchema is classified into a
+ * SchemaNormalisationError so the caller does not have to re-parse error
+ * message strings. The classification covers:
+ *
+ * - Nested Zod 3 schemas inside a Zod 4 tree → zod3-unsupported.
+ *   Detected structurally (presence of `_def.typeName` markers anywhere
+ *   in the schema tree) so the check works across V8, JavaScriptCore,
+ *   and SpiderMonkey, none of which agree on the wording of
+ *   "Cannot read properties of undefined".
+ * - Transforms → zod-transform-unsupported. This also catches `z.codec(…)`
+ *   because Zod implements codecs as a pipe + transform internally, so
+ *   they trip the same processor when round-tripping is forced. (Plain
+ *   `z.toJSONSchema(codec)` itself does NOT throw because Zod picks one
+ *   side of the codec; the static rejection in `typeInference.ts` is the
+ *   compile-time guard.)
+ * - Dynamic catch values whose handler throws → zod-type-unrepresentable
+ *   with zodType "dynamic-catch".
+ * - Unrepresentable types — bigint, date, map, set, symbol, function, custom,
+ *   undefined, void, NaN, and the literal-only forms `z.literal(undefined)`
+ *   ("undefined-literal") and `z.literal(<bigint>)` ("bigint-literal") →
+ *   zod-type-unrepresentable.
+ * - The catch-all "Non-representable type encountered: <type>" fallback Zod
+ *   emits for any new schema kind without a registered processor →
+ *   zod-type-unrepresentable with zodType set to the offending def.type.
+ * - Cycle detected (`cycles: "throw"`) → zod-cycle-detected.
+ * - Duplicate schema id → zod-duplicate-id.
+ * - "Unprocessed schema. This is a bug in Zod." → zod-conversion-bug.
+ * - "Error converting schema to JSON." → zod-conversion-failed (explicit
+ *   classification rather than the generic fallback so the contract test
+ *   protects the prefix from drift).
+ * - Anything else → zod-conversion-failed.
+ *
+ * The original error is preserved on each classified error via the `cause`
+ * field so consumers can still inspect the Zod stack trace.
+ */
+/**
+ * IO side passed to {@link callToJsonSchema}. The Zod runtime accepts
+ * `"input" | "output"` for the corresponding `io` option on
+ * `z.toJSONSchema`. Defaults to `"output"` everywhere in the adapter
+ * pipeline; the parameter exists so a future renderer or component
+ * (currently SchemaComponent — see TODO below) can request the input
+ * side without forking the helper.
+ */
+type SchemaIoSide = "input" | "output";
 /**
  * Exposed for unit testing — lets the contract test enumerate every rule's
  * `prefix` value and assert mutual non-prefixing.
@@ -27,5 +120,23 @@ interface NormaliseOptions {
   diagnostics?: DiagnosticsOptions;
 }
 declare function normaliseSchema(input: unknown, ref?: string, options?: NormaliseOptions): NormalisedSchema;
+/**
+ * Surface root-level metadata from the JSON Schema into the `rootMeta`
+ * shape consumed by the walker. Pulls `readOnly`, `writeOnly`,
+ * `description`, `title`, `deprecated`, `examples`, and `default`
+ * directly from the schema root.
+ *
+ * `examples` is forwarded only when present as an array (per JSON Schema
+ * Draft 2020-12 — Draft 04's `example` singular is normalised upstream).
+ * `default` is forwarded for any value the schema declares (any JSON
+ * value, including `null` and `false`); the presence check uses `in`
+ * so a literal `false` or `null` default is preserved.
+ *
+ * `examples` and `default` ride on the `[key: string]: unknown` index
+ * signature of {@link SchemaMeta}. They are not declared as named fields
+ * on `SchemaMeta` because that type lives in `types.ts` and is shared
+ * with the walker; the index signature is the agreed extension point.
+ */
+declare function extractRootMetaFromJson(jsonSchema: JsonObject): SchemaMeta | undefined;
 //#endregion
-export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaKind, type SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, normaliseSchema };
+export { type JsonObject, NormaliseOptions, NormalisedSchema, SchemaInput, SchemaIoSide, SchemaKind, type SchemaMeta, __CLASSIFIER_RULES_FOR_TEST, detectSchemaKind, extractRootMetaFromJson, normaliseSchema };