effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/SchemaRepresentation.js

@@ -878,9 +878,14 @@ export const $MultiDocument = /*#__PURE__*/Schema.Struct({
 /**
  * Converts a Schema AST into a {@link Document}.
  *
- * - Use when you have a single schema and need its representation.
- * - Pure function; does not mutate the input AST.
- * - Shared/recursive sub-schemas are extracted into the `references` map.
+ * **When to use**
+ *
+ * Use this when you have a single schema and need its representation.
+ *
+ * **Details**
+ *
+ * This is a pure function and does not mutate the input AST.
+ * Shared/recursive sub-schemas are extracted into the `references` map.
  *
  * **Example** (Converting a Schema to a Document)
  *
@@ -907,9 +912,14 @@ export const fromAST = InternalRepresentation.fromAST;
 /**
  * Converts one or more Schema ASTs into a {@link MultiDocument}.
  *
- * - Use when you have multiple schemas that may share references.
- * - Pure function; does not mutate the input ASTs.
- * - All schemas share a single `references` map.
+ * **When to use**
+ *
+ * Use this when you have multiple schemas that may share references.
+ *
+ * **Details**
+ *
+ * This is a pure function and does not mutate the input ASTs. All schemas share
+ * a single `references` map.
  *
  * @see {@link MultiDocument}
  * @see {@link fromAST}
@@ -921,8 +931,10 @@ export const fromASTs = InternalRepresentation.fromASTs;
 /**
  * Schema codec that decodes a {@link Document} from JSON and encodes it back.
  *
- * - Use with `Schema.decodeUnknownSync` / `Schema.encodeSync` to
- *   serialize/deserialize documents.
+ * **When to use**
+ *
+ * Use this with `Schema.decodeUnknownSync` or `Schema.encodeSync` to serialize
+ * and deserialize documents.
  *
  * **Example** (Round-tripping a Document through JSON)
  *
@@ -956,9 +968,14 @@ export const MultiDocumentFromJson = /*#__PURE__*/Schema.toCodecJson($MultiDocum
  * Wraps a single {@link Document} as a {@link MultiDocument} with one
  * representation.
  *
- * - Use when an API expects a `MultiDocument` but you only have a single
- *   `Document`.
- * - Pure function; does not mutate the input.
+ * **When to use**
+ *
+ * Use this when an API expects a `MultiDocument` but you only have a single
+ * `Document`.
+ *
+ * **Details**
+ *
+ * This is a pure function and does not mutate the input.
  *
  * @see {@link Document}
  * @see {@link MultiDocument}
@@ -974,14 +991,18 @@ export function toMultiDocument(document) {
 }
 /**
  * Default {@link Reviver} for {@link toSchema} that handles built-in Effect
- * types (Option, Result, Redacted, Cause, Exit, ReadonlyMap, HashMap,
- * ReadonlySet,
- * Date, Duration, URL, RegExp, etc.).
+ * types, including Option, Result, Redacted, Cause, Exit, ReadonlyMap, HashMap,
+ * ReadonlySet, Date, Duration, URL, and RegExp.
  *
- * - Pass as `options.reviver` to {@link toSchema} to reconstruct schemas that
- *   use these types.
- * - Returns `undefined` for unrecognized declarations, causing fallback to
- *   `encodedSchema`.
+ * **When to use**
+ *
+ * Pass this as `options.reviver` to {@link toSchema} to reconstruct schemas
+ * that use these types.
+ *
+ * **Details**
+ *
+ * The reviver returns `undefined` for unrecognized declarations, causing
+ * fallback to `encodedSchema`.
  *
  * @see {@link toSchema}
  * @see {@link Reviver}
@@ -1060,13 +1081,21 @@ export const toSchemaDefaultReviver = (s, recur) => {
 /**
  * Reconstructs a runtime Schema from a {@link Document}.
  *
- * - Use when you have a serialized or computed representation and need a
- *   working Schema for decoding/encoding.
- * - Pass `options.reviver` (e.g. {@link toSchemaDefaultReviver}) to handle
- *   {@link Declaration} nodes for types like `Date`, `Option`, etc.
- * - Without a reviver, declarations fall back to their `encodedSchema`.
- * - Handles circular references via lazy `Schema.suspend`.
- * - Throws if a `$ref` is not found in `document.references`.
+ * **When to use**
+ *
+ * Use this when you have a serialized or computed representation and need a
+ * working Schema for decoding/encoding.
+ *
+ * **Details**
+ *
+ * Pass `options.reviver`, such as {@link toSchemaDefaultReviver}, to handle
+ * {@link Declaration} nodes for types like `Date` and `Option`. Without a
+ * reviver, declarations fall back to their `encodedSchema`. Circular references
+ * are handled via lazy `Schema.suspend`.
+ *
+ * **Gotchas**
+ *
+ * This throws if a `$ref` is not found in `document.references`.
  *
  * **Example** (Reconstructing a Schema)
  *
@@ -1372,8 +1401,14 @@ export function toSchema(document, options) {
 /**
  * Converts a {@link Document} to a Draft 2020-12 JSON Schema document.
  *
- * - Use to produce a standard JSON Schema from an Effect Schema representation.
- * - Pure function; does not mutate the input.
+ * **When to use**
+ *
+ * Use this to produce a standard JSON Schema from an Effect Schema
+ * representation.
+ *
+ * **Details**
+ *
+ * This is a pure function and does not mutate the input.
  *
  * **Example** (Generating JSON Schema)
  *
@@ -1398,8 +1433,13 @@ export const toJsonSchemaDocument = InternalRepresentation.toJsonSchemaDocument;
  * Converts a {@link MultiDocument} to a Draft 2020-12 JSON Schema
  * multi-document.
  *
- * - Use when you have multiple schemas sharing references.
- * - Pure function; does not mutate the input.
+ * **When to use**
+ *
+ * Use this when you have multiple schemas sharing references.
+ *
+ * **Details**
+ *
+ * This is a pure function and does not mutate the input.
  *
  * @see {@link MultiDocument}
  * @see {@link toJsonSchemaDocument}
@@ -1427,13 +1467,18 @@ export function makeCode(runtime, Type) {
 /**
  * Generates TypeScript code strings from a {@link MultiDocument}.
  *
- * - Use to produce source code for Schema definitions (e.g. for codegen tools).
- * - `options.reviver` can customize code generation for {@link Declaration}
- *   nodes. Return `undefined` to fall back to the default logic (which uses
- *   `generation` annotations or the encoded schema).
- * - Performs topological sorting of references to emit non-recursive
- *   definitions before their dependents.
- * - Produces sanitized JavaScript identifiers for `$ref` keys.
+ * **When to use**
+ *
+ * Use this to produce source code for Schema definitions, such as in codegen
+ * tools.
+ *
+ * **Details**
+ *
+ * `options.reviver` can customize code generation for {@link Declaration}
+ * nodes. Return `undefined` to fall back to the default logic, which uses
+ * `generation` annotations or the encoded schema. References are
+ * topologically sorted so non-recursive definitions are emitted before their
+ * dependents. `$ref` keys are converted to sanitized JavaScript identifiers.
  *
  * **Example** (Generating TypeScript code)
  *
@@ -1943,11 +1988,20 @@ function toRuntimeRegExp(regExp) {
 /**
  * Parses a Draft 2020-12 JSON Schema document into a {@link Document}.
  *
- * - Use to import external JSON Schemas into the Effect representation system.
- * - `options.onEnter` is an optional hook called on each JSON Schema node
- *   before processing, allowing pre-transformation.
- * - Throws if a `$ref` cannot be resolved within the document's definitions.
- * - Circular `$ref`s are detected and cause an error.
+ * **When to use**
+ *
+ * Use this to import external JSON Schemas into the Effect representation
+ * system.
+ *
+ * **Details**
+ *
+ * `options.onEnter` is an optional hook called on each JSON Schema node before
+ * processing, allowing pre-transformation.
+ *
+ * **Gotchas**
+ *
+ * This throws if a `$ref` cannot be resolved within the document's definitions.
+ * Circular `$ref`s are detected and cause an error.
  *
  * @see {@link Document}
  * @see {@link toJsonSchemaDocument}
@@ -1974,10 +2028,18 @@ export function fromJsonSchemaDocument(document, options) {
  * Parses a Draft 2020-12 JSON Schema multi-document into a
  * {@link MultiDocument}.
  *
- * - Use to import multiple JSON Schemas sharing definitions.
- * - `options.onEnter` is an optional hook called on each JSON Schema node
- *   before processing.
- * - Throws if a `$ref` cannot be resolved.
+ * **When to use**
+ *
+ * Use this to import multiple JSON Schemas sharing definitions.
+ *
+ * **Details**
+ *
+ * `options.onEnter` is an optional hook called on each JSON Schema node before
+ * processing.
+ *
+ * **Gotchas**
+ *
+ * This throws if a `$ref` cannot be resolved.
  *
  * @see {@link MultiDocument}
  * @see {@link toJsonSchemaMultiDocument}