effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/SchemaIssue.ts

@@ -95,12 +95,11 @@ const TypeId = "~effect/SchemaIssue/Issue"
  *
  * **When to use**
  *
- * - Narrowing an `unknown` value to `Issue` in error-handling code.
+ * Use when narrowing an `unknown` value to `Issue` in error-handling code.
  * - Distinguishing an `Issue` from other error types in a catch-all handler.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Checks for the internal `TypeId` brand on the value.
  *
  * **Example** (Type-guarding an unknown error)
@@ -129,7 +128,7 @@ export function isIssue(u: unknown): u is Issue {
  *
  * **When to use**
  *
- * - Constraining formatter hooks to only handle terminal nodes.
+ * Use when constraining formatter hooks to only handle terminal nodes.
  * - Pattern-matching on the `_tag` of an issue when you only care about leaves.
  *
  * **Details**
@@ -156,7 +155,7 @@ export type Leaf =
  *
  * **When to use**
  *
- * - Typing the error channel in `Effect<A, Issue, R>` results from schema
+ * Use when typing the error channel in `Effect<A, Issue, R>` results from schema
  *   parsing.
  * - Writing custom formatters or issue-tree walkers.
  *
@@ -192,12 +191,11 @@ class Base {
 }
 
 /**
- * Issue produced when a schema filter (refinement check) fails.
+ * Represents a schema issue produced when a schema filter (refinement check) fails.
  *
  * **When to use**
  *
- * - Inspect which filter rejected the value.
- * - Walk the inner `issue` for the specific validation failure.
+ * Use when you need to inspect which filter rejected the value.
  *
  * **Details**
  *
@@ -262,13 +260,12 @@ export class Filter extends Base {
 }
 
 /**
- * Issue produced when a schema transformation (encode/decode step) fails.
+ * Represents a schema issue produced when a schema transformation (encode/decode step) fails.
  *
  * **When to use**
  *
- * - Inspect failures from `Schema.decodeTo` / `Schema.encodeTo`
+ * Use when you need to inspect failures from `Schema.decodeTo` / `Schema.encodeTo`
  *   transformations.
- * - Walk the inner `issue` for the root cause of the transformation failure.
  *
  * **Details**
  *
@@ -325,8 +322,8 @@ export class Encoding extends Base {
  *
  * **When to use**
  *
- * - Walk the issue tree to accumulate path segments for error reporting.
- * - Match on `_tag === "Pointer"` when flattening nested issues.
+ * Use when you need to walk the issue tree to accumulate path segments for error
+ * reporting.
  *
  * **Details**
  *
@@ -369,13 +366,11 @@ export class Pointer extends Base {
 }
 
 /**
- * Issue produced when a required key or tuple index is missing from the input.
+ * Represents a schema issue produced when a required key or tuple index is missing from the input.
  *
  * **When to use**
  *
- * - Detect absent fields in struct/tuple validation.
- * - Typically found inside a {@link Pointer} that indicates which key is
- *   missing.
+ * Use when you need to detect absent fields in struct/tuple validation.
  *
  * **Details**
  *
@@ -407,14 +402,13 @@ export class MissingKey extends Base {
 }
 
 /**
- * Issue produced when an input object or tuple contains a key/index not
+ * Represents a schema issue produced when an input object or tuple contains a key/index not
  * declared by the schema.
  *
  * **When to use**
  *
- * - Detect excess properties during strict struct/tuple validation.
- * - Typically found inside a {@link Pointer} that indicates which key was
- *   unexpected.
+ * Use when you need to detect excess properties during strict struct/tuple
+ * validation.
  *
  * **Details**
  *
@@ -456,13 +450,12 @@ export class UnexpectedKey extends Base {
 }
 
 /**
- * Issue that groups multiple child issues under a single schema node.
+ * Represents a schema issue that groups multiple child issues under a single schema node.
  *
  * **When to use**
  *
- * - Walk the issue tree for struct/tuple schemas that collect all field errors
- *   rather than failing on the first.
- * - Match on `_tag === "Composite"` to iterate over `issues`.
+ * Use when you need to walk the issue tree for struct/tuple schemas that collect
+ * all field errors rather than failing on the first.
  *
  * **Details**
  *
@@ -514,14 +507,13 @@ export class Composite extends Base {
 }
 
 /**
- * Issue produced when the runtime type of the input does not match the type
+ * Represents a schema issue produced when the runtime type of the input does not match the type
  * expected by the schema (e.g. got `null` when `string` was expected).
  *
  * **When to use**
  *
- * - Detect basic type mismatches (wrong primitive, null where object expected,
- *   etc.).
- * - The most common leaf issue in typical validation failures.
+ * Use when you need to detect basic type mismatches, such as a wrong primitive
+ * or `null` where an object was expected.
  *
  * **Details**
  *
@@ -578,14 +570,13 @@ export class InvalidType extends Base {
 }
 
 /**
- * Issue produced when the input has the correct type but its value violates a
+ * Represents a schema issue produced when the input has the correct type but its value violates a
  * constraint (e.g. a string that is too short, a number out of range).
  *
  * **When to use**
  *
- * - Detect constraint violations from `Schema.filter`, `Schema.minLength`,
- *   `Schema.greaterThan`, etc.
- * - Create custom validation errors in `Schema.makeFilter` callbacks.
+ * Use when you need to detect constraint violations from `Schema.filter`,
+ * `Schema.minLength`, `Schema.greaterThan`, or similar checks.
  *
  * **Details**
  *
@@ -642,13 +633,13 @@ export class InvalidValue extends Base {
 }
 
 /**
- * Issue produced when a forbidden operation is encountered during parsing,
+ * Represents a schema issue produced when a forbidden operation is encountered during parsing,
  * such as an asynchronous Effect running inside `Schema.decodeUnknownSync`.
  *
  * **When to use**
  *
- * - Detect that a schema requires async execution but was run synchronously.
- * - Provide custom error messages via the `annotations.message` field.
+ * Use when you need to detect that a schema requires async execution but was run
+ * synchronously.
  *
  * **Details**
  *
@@ -703,13 +694,12 @@ export class Forbidden extends Base {
 }
 
 /**
- * Issue produced when a value does not match *any* member of a union schema.
+ * Represents a schema issue produced when a value does not match *any* member of a union schema.
  *
  * **When to use**
  *
- * - Inspect which union members were attempted and why each failed.
- * - `issues` may be empty when the union has no members or when the input does
- *   not pass the initial type guard.
+ * Use when you need to inspect which union members were attempted and why each
+ * failed.
  *
  * **Details**
  *
@@ -761,13 +751,13 @@ export class AnyOf extends Base {
 }
 
 /**
- * Issue produced when a value matches *multiple* members of a union that is
+ * Represents a schema issue produced when a value matches *multiple* members of a union that is
  * configured to allow exactly one match (oneOf mode).
  *
  * **When to use**
  *
- * - Detect ambiguous union matches when `oneOf` validation is enabled.
- * - Inspect `successes` to see which members matched.
+ * Use when you need to detect ambiguous union matches when `oneOf` validation is
+ * enabled.
  *
  * **Details**
  *
@@ -823,12 +813,11 @@ export class OneOf extends Base {
  *
  * **When to use**
  *
- * - Retrieve the offending value for logging or custom error rendering.
+ * Use when retrieve the offending value for logging or custom error rendering.
  * - Uniformly access `actual` regardless of which issue variant you have.
  *
  * **Details**
  *
- * - Pure; does not mutate the issue.
  * - Returns `Option.none()` for `Pointer` and `MissingKey` (they carry no
  *   value).
  * - Returns the existing `Option` for variants that already store `actual` as
@@ -928,8 +917,8 @@ export interface Formatter<out Format> extends FormatterI<Issue, Format> {}
  *
  * **When to use**
  *
- * - Pass a custom `LeafHook` to {@link makeFormatterStandardSchemaV1} to
- *   override how terminal issues are rendered.
+ * Use when customizing how {@link makeFormatterStandardSchemaV1} renders
+ * terminal issues.
  *
  * @see {@link defaultLeafHook} — the built-in implementation
  * @see {@link Leaf} — the union of terminal issue types
@@ -940,12 +929,12 @@ export interface Formatter<out Format> extends FormatterI<Issue, Format> {}
 export type LeafHook = (issue: Leaf) => string
 
 /**
- * The built-in {@link LeafHook} used by default formatters.
+ * Returns the built-in {@link LeafHook} used by default formatters.
  *
  * **When to use**
  *
- * - Use as-is when you only need to customise the {@link CheckHook} but want
- *   the default leaf rendering.
+ * Use as the default leaf renderer when you only need to customise the
+ * {@link CheckHook}.
  * - Reference as a starting point for custom `LeafHook` implementations.
  *
  * **Details**
@@ -999,8 +988,8 @@ export const defaultLeafHook: LeafHook = (issue): string => {
  *
  * **When to use**
  *
- * - Pass a custom `CheckHook` to {@link makeFormatterStandardSchemaV1} to
- *   override how filter failures are rendered.
+ * Use when customizing how {@link makeFormatterStandardSchemaV1} renders
+ * filter failures.
  *
  * **Details**
  *
@@ -1016,12 +1005,12 @@ export const defaultLeafHook: LeafHook = (issue): string => {
 export type CheckHook = (issue: Filter) => string | undefined
 
 /**
- * The built-in {@link CheckHook} used by default formatters.
+ * Returns the built-in {@link CheckHook} used by default formatters.
  *
  * **When to use**
  *
- * - Use as-is when you only need to customise the {@link LeafHook} but want
- *   the default filter rendering.
+ * Use as the default filter renderer when you only need to customise the
+ * {@link LeafHook}.
  *
  * **Details**
  *
@@ -1045,7 +1034,7 @@ export const defaultCheckHook: CheckHook = (issue): string | undefined => {
  *
  * **When to use**
  *
- * - Integrate with libraries that consume the
+ * Use when integrate with libraries that consume the
  *   [Standard Schema V1](https://github.com/standard-schema/standard-schema)
  *   error format.
  * - Customise error rendering by providing `leafHook` and/or `checkHook`.
@@ -1153,7 +1142,7 @@ function formatCheck<T>(check: AST.Check<T>): string {
  *
  * **When to use**
  *
- * - Produce error messages for logging, CLI output, or developer-facing
+ * Use when produce error messages for logging, CLI output, or developer-facing
  *   diagnostics.
  * - This is the default formatter used by `Issue.toString()`.
  *