effect 4.0.0-beta.104 → 4.0.0-beta.106

package/dist/Schema.d.ts

@@ -42,7 +42,7 @@ import * as SchemaParser from "./SchemaParser.ts";
 import type * as SchemaRepresentation from "./SchemaRepresentation.ts";
 import type { Assign, Lambda, Mutable, Simplify } from "./Struct.ts";
 import * as Struct_ from "./Struct.ts";
-import * as FastCheck from "./testing/FastCheck.ts";
+import type * as FastCheck from "./testing/FastCheck.ts";
 import type { RequiredKeys, UnionToIntersection } from "./Types.ts";
 import type { Unify } from "./Unify.ts";
 declare const TypeId = "~effect/Schema/Schema";
@@ -149,7 +149,9 @@ export interface BottomWithoutNew<out T, out E, out RD, out RE, out Ast extends
      * **Gotchas**
      *
      * Throws an `Error` with the schema issue in its `cause` when validation
-     * fails.
+     * fails. Schema validation failures use the generic message
+     * `"Schema validation failed"`; format the `cause` explicitly with
+     * `SchemaIssue.makeFormatterDefault()` when human-readable details are needed.
      * Causes that contain defects, interruptions, or other non-schema reasons
      * throw with the underlying `Cause` attached instead.
      *
@@ -190,10 +192,15 @@ export interface BottomWithoutNew<out T, out E, out RD, out RE, out Ast extends
      * Use when constructor input may fail validation and you want to
      * compose that failure with other `Effect` operations instead of throwing.
      *
+     * **Details**
+     *
+     * Validation failures are returned directly as `SchemaIssue.Issue` values
+     * and are not wrapped in `SchemaError`.
+     *
      * @see {@link BottomWithoutNew.make} — construct synchronously when validation failure should throw
      * @see {@link BottomWithoutNew.makeOption} — construct synchronously and discard validation details
      */
-    makeEffect(input: this["~type.make.in"], options?: MakeOptions): Effect.Effect<this["Type"], SchemaError>;
+    makeEffect(input: this["~type.make.in"], options?: MakeOptions): Effect.Effect<this["Type"], SchemaIssue.Issue>;
 }
 /**
  * Fully-parameterized base interface for schemas that can be extended directly
@@ -299,7 +306,7 @@ export interface declareConstructor<T, E, TypeParameters extends ReadonlyArray<C
  * **Example** (Schema for a parametric `Box<A>` type)
  *
  * ```ts import.meta.vitest
- * import { Effect, Schema, SchemaIssue as Issue, SchemaParser } from "effect"
+ * import { Effect, Schema, SchemaIssue, SchemaParser } from "effect"
  *
  * interface Box<A> {
  *   readonly value: A
@@ -314,7 +321,7 @@ export interface declareConstructor<T, E, TypeParameters extends ReadonlyArray<C
  *     ([itemCodec]) =>
  *       (u, ast, options) => {
  *         if (!isBox(u)) {
- *           return Effect.fail(new SchemaIssue.InvalidType(ast))
+ *           return Effect.fail(new SchemaIssue.InvalidType(ast, u, options))
  *         }
  *         return Effect.map(
  *           SchemaParser.decodeUnknownEffect(itemCodec)(u.value, options),
@@ -915,10 +922,12 @@ isSchemaError,
  *
  * The `issue` field contains a structured {@link SchemaIssue.Issue} tree describing
  * every validation failure, including the path to the problematic value and
- * the expected type or constraint. Built-in issues have no `actual` field,
- * and built-in messages do not include the rejected value. Other Issue fields
- * and custom annotations or messages are not sanitized. `message` renders the
- * issue tree as a human-readable string.
+ * the expected type or constraint. Parsing with `reportInput: true` adds an
+ * enumerable `input` field to value-bearing issues created by the parser.
+ * Built-in messages may include reported input. Other issue fields and
+ * custom annotations or messages are not sanitized.
+ * `message` renders the issue tree as a human-readable string and can disclose
+ * retained input.
  *
  * Use {@link isSchemaError} to narrow an unknown value to `SchemaError`.
  *
@@ -1071,6 +1080,9 @@ export declare const is: typeof SchemaParser.is;
  *
  * The input is narrowed if the assertion succeeds. If schema validation fails,
  * the assertion throws an `Error` whose cause is `SchemaIssue.Issue`.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -4368,7 +4380,7 @@ export declare function decodeTo<To extends Constraint, From extends Constraint,
  * ```
  *
  * @category transforming
- * @since 3.10.0
+ * @since 4.0.0
  */
 export declare function decode<S extends Constraint, RD = never, RE = never>(transformation: {
     readonly decode: SchemaGetter.Getter<S["Type"], S["Type"], RD>;
@@ -4433,7 +4445,7 @@ export declare function encodeTo<To extends Constraint, From extends Constraint,
  * ```
  *
  * @category transforming
- * @since 3.10.0
+ * @since 4.0.0
  */
 export declare function encode<S extends Constraint, RD = never, RE = never>(transformation: {
     readonly decode: SchemaGetter.Getter<S["Encoded"], S["Encoded"], RD>;
@@ -4474,7 +4486,7 @@ export interface withConstructorDefault<S extends Constraint & WithoutConstructo
  * **Details**
  *
  * Constructor defaults are applied only during `make*`, not during decoding or
- * encoding.
+ * encoding. Failures are represented directly as `SchemaIssue.Issue` values.
  *
  * **Example** (Defining an optional field with a static default)
  *
@@ -4494,7 +4506,7 @@ export interface withConstructorDefault<S extends Constraint & WithoutConstructo
  * @category constructors
  * @since 3.10.0
  */
-export declare function withConstructorDefault<S extends Constraint & WithoutConstructorDefault>(defaultValue: Effect.Effect<S["~type.make.in"], SchemaError>): (schema: S) => withConstructorDefault<S>;
+export declare function withConstructorDefault<S extends Constraint & WithoutConstructorDefault>(defaultValue: Effect.Effect<S["~type.make.in"], SchemaIssue.Issue>): (schema: S) => withConstructorDefault<S>;
 /**
  * Type-level representation returned by {@link withDecodingDefaultKey}.
  *
@@ -5092,12 +5104,13 @@ export declare const makeFilter: <T>(filter: (input: T, ast: SchemaAST.AST, opti
  *
  * - `string`: failure with that string as the message. Produces an
  *   {@link SchemaIssue.InvalidValue} with the string used as the issue's
- *   `message` annotation.
- * - {@link SchemaIssue.Issue}: a fully-formed issue, returned as-is.
+ *   `message` annotation and honors `reportInput`.
+ * - {@link SchemaIssue.Issue}: a fully-formed issue, returned as-is. It is not
+ *   enriched when `reportInput` is enabled.
  * - `{ path, issue }`: failure attached to a nested path. `issue` is either
- *   a `string` (wrapped in an {@link SchemaIssue.InvalidValue}) or a full
- *   {@link SchemaIssue.Issue}; the result is wrapped in an {@link SchemaIssue.Pointer}
- *   at the given `path`.
+ *   a `string` (wrapped in an {@link SchemaIssue.InvalidValue} that honors
+ *   `reportInput`) or a full {@link SchemaIssue.Issue} (returned unchanged);
+ *   the result is wrapped in an {@link SchemaIssue.Pointer} at the given `path`.
  *
  * @category models
  * @since 3.10.0
@@ -5118,7 +5131,7 @@ export type FilterIssue = string | SchemaIssue.Issue | {
  * - `true`: success. Equivalent to `undefined`, useful when the predicate is
  *   a plain boolean expression.
  * - `false`: generic failure. Produces an {@link SchemaIssue.InvalidValue}
- *   with no custom message.
+ *   with no custom message and honors `reportInput`.
  * - {@link FilterIssue}: a single failure. See {@link FilterIssue} for the
  *   shapes (`string`, {@link SchemaIssue.Issue}, or `{ path, issue }`).
  * - `ReadonlyArray<FilterIssue>`: several failures reported together. An
@@ -9201,8 +9214,8 @@ type InheritStaticMembers<C, Static> = C & Pick<Static, Exclude<keyof Static, ke
 type MissingSelfGeneric<Usage extends string> = `Missing \`Self\` generic - use \`class Self extends ${Usage}<Self>(...)\``;
 /**
  * Creates a schema-backed class whose constructor validates input against a
- * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
- * input.
+ * {@link Struct} schema. Construction throws an `Error` with a
+ * `SchemaIssue.Issue` in its `cause` on invalid input.
  *
  * **When to use**
  *
@@ -9271,8 +9284,8 @@ type MissingSelfGeneric<Usage extends string> = `Missing \`Self\` generic - use
 export declare const Class: {
     /**
      * Creates a schema-backed class whose constructor validates input against a
-     * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-     * input.
+     * {@link Struct} schema. Construction throws an `Error` with a
+     * `SchemaIssue.Issue` in its `cause` on invalid input.
      *
      * **When to use**
      *
@@ -9341,8 +9354,8 @@ export declare const Class: {
     <Self = never, Brand = {}>(identifier: string): {
         /**
          * Creates a schema-backed class whose constructor validates input against a
-         * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-         * input.
+         * {@link Struct} schema. Construction throws an `Error` with a
+         * `SchemaIssue.Issue` in its `cause` on invalid input.
          *
          * **When to use**
          *
@@ -9411,8 +9424,8 @@ export declare const Class: {
         <const Fields extends Struct.Fields>(fields: Fields, annotations?: Annotations.Declaration<Self, readonly [Struct<Fields>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.Class"> : Class<Self, Struct<Fields>, Brand>;
         /**
          * Creates a schema-backed class whose constructor validates input against a
-         * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-         * input.
+         * {@link Struct} schema. Construction throws an `Error` with a
+         * `SchemaIssue.Issue` in its `cause` on invalid input.
          *
          * **When to use**
          *
@@ -9844,39 +9857,31 @@ export declare const TaggedError: {
     };
 };
 /**
- * A thunk that, given the `fast-check` module, returns an `Arbitrary<T>`.
- * Use this type when you need to defer instantiation of the arbitrary, for
- * example to support recursive schemas.
+ * Represents a function that builds a fast-check `Arbitrary<T>` from the
+ * `fast-check` module.
+ *
+ * **When to use**
+ *
+ * Use as the result type of schema arbitrary derivation.
  *
  * @category utility types
  * @since 4.0.0
  */
-export type LazyArbitrary<T> = (fc: typeof FastCheck) => FastCheck.Arbitrary<T>;
+export type Arbitrary<T> = (fc: typeof FastCheck) => FastCheck.Arbitrary<T>;
 /**
- * Derives a {@link LazyArbitrary} from a schema. The result is memoized so
- * repeated calls with the same schema are cheap.
+ * Returns an {@link Arbitrary} factory derived from a schema. The generated
+ * values satisfy the schema and use its decoded `Type`.
  *
- * **Details**
- *
- * Prefer {@link toArbitrary} when you need the arbitrary directly, or when you
- * want derivation diagnostics via `{ report: true }`. Unsupported schema
- * nodes, impossible constraints, invalid candidates, and recursive schemas
- * without a finite terminal path fail immediately.
+ * **When to use**
  *
- * @category generators
- * @since 4.0.0
- */
-export declare function toArbitraryLazy<S extends Constraint>(schema: S): LazyArbitrary<S["Type"]>;
-/**
- * Derives a `fast-check` `Arbitrary` from a schema for property-based
- * testing. The derived arbitrary generates values that satisfy the schema.
+ * Use when you need a fast-check generator for values accepted by a schema.
  *
  * **Details**
  *
  * Constraints refine base generators; candidates add weighted sources while
- * filters still validate every value. `{ report: true }` returns warnings such
- * as `OpaqueFilter`, while derivation errors remain fail-fast. Recursive
- * schemas use terminal branches and fail when no finite terminal path exists.
+ * filters still validate every value. Recursive schemas use terminal branches
+ * and fail when no finite terminal path exists. The result is memoized so
+ * repeated calls with the same schema are cheap.
  *
  * **Example** (Generating arbitrary values)
  *
@@ -9884,21 +9889,18 @@ export declare function toArbitraryLazy<S extends Constraint>(schema: S): LazyAr
  * import { Schema } from "effect"
  * import * as FastCheck from "fast-check"
  *
- * const PersonArb = Schema.toArbitrary(
+ * const makePersonArbitrary = Schema.toArbitrary(
  *   Schema.Struct({ name: Schema.String, age: Schema.Number })
  * )
  *
- * // Sample a random value
- * FastCheck.sample(PersonArb, 1)
+ * const PersonArbitrary = makePersonArbitrary(FastCheck)
+ * FastCheck.sample(PersonArbitrary, 1)
  * ```
  *
  * @category generators
  * @since 4.0.0
  */
-export declare function toArbitrary<S extends Constraint>(schema: S): FastCheck.Arbitrary<S["Type"]>;
-export declare function toArbitrary<S extends Constraint>(schema: S, options: {
-    readonly report: true;
-}): Annotations.ToArbitrary.WithReport<FastCheck.Arbitrary<S["Type"]>>;
+export declare function toArbitrary<S extends Constraint>(schema: S): Arbitrary<S["Type"]>;
 /**
  * Attaches a custom formatter used by `toFormatter`.
  *
@@ -10360,6 +10362,18 @@ export declare const isBetweenBigIntReviver: SchemaRepresentation.FilterReviver<
  * Derives an `Iso` optic from a schema that isomorphically converts between
  * the schema's `Type` and its `Iso` (intermediate / serialized form).
  *
+ * **Details**
+ *
+ * Reading through the `Iso` encodes the schema value, while replacing through
+ * it decodes the new focus.
+ *
+ * **Gotchas**
+ *
+ * Either direction can throw an `Error` with the generic message
+ * `"Schema validation failed"` and a `SchemaIssue.Issue` in its `cause`. Format
+ * the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -10420,6 +10434,19 @@ export declare function overrideToCodecIso<S extends Constraint, Iso>(to: Constr
  * {@link toCodecJson}), computes RFC 6902 JSON Patch operations between old
  * and new values, and can apply patches back to the typed value.
  *
+ * **Details**
+ *
+ * `diff` encodes both values before computing the patch. `patch` encodes the old
+ * value, applies the patch to its JSON representation, and decodes the result.
+ *
+ * **Gotchas**
+ *
+ * Schema encoding or decoding failures throw an `Error` with the generic message
+ * `"Schema validation failed"` and a `SchemaIssue.Issue` in its `cause`. Format
+ * the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed. Errors produced by {@link JsonPatch.apply}
+ * for invalid patch operations are separate from schema validation failures.
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -10797,6 +10824,15 @@ export declare namespace Annotations {
      */
     interface Filter extends Augment {
         readonly representation?: SchemaRepresentation.CheckRepresentationAnnotation<SchemaAST.AST> | undefined;
+        /**
+         * Compiles this filter to a JSON Schema fragment.
+         *
+         * **Gotchas**
+         *
+         * Treat the input schemas as immutable. The returned value must be a valid JSON Schema object graph and must not be
+         * mutated after this function returns. Return a new object graph to produce different output during a later
+         * compilation.
+         */
         readonly toJsonSchema?: SchemaRepresentation.ToJsonSchema.Check | undefined;
         readonly toCode?: SchemaRepresentation.Generation.Check | undefined;
         /**
@@ -10844,8 +10880,7 @@ export declare namespace Annotations {
     }
     /**
      * Types used by arbitrary-derivation annotations to configure `toArbitrary`
-     * hooks, filter hints, candidate sources, diagnostics, and merged generation
-     * constraints.
+     * hooks, filter hints, candidate sources, and merged generation constraints.
      *
      * @since 4.0.0
      */
@@ -10858,8 +10893,7 @@ export declare namespace Annotations {
          * `constraint` refines the schema node's base generator. `candidate` adds a
          * weighted source before all filters run. If neither hint is provided, the
          * filter does not guide generation; generated values are still checked by
-         * the filter predicate. With `{ report: true }`, this is reported as
-         * `OpaqueFilter`.
+         * the filter predicate.
          *
          * @category models
          * @since 4.0.0
@@ -11034,54 +11068,6 @@ export declare namespace Annotations {
                 readonly [K in keyof TypeParameters]: TypeParameter<TypeParameters[K]["Type"]>;
             }): (fc: typeof FastCheck, context: Context) => Output<T>;
         }
-        /**
-         * Wraps a derived value together with arbitrary-derivation diagnostics.
-         *
-         * @category models
-         * @since 4.0.0
-         */
-        interface WithReport<A> {
-            readonly value: A;
-            readonly report: Report;
-        }
-        /**
-         * Diagnostics collected while deriving an arbitrary.
-         *
-         * **Details**
-         *
-         * Reports contain warnings only. Unsupported schema nodes, impossible
-         * constraints, invalid candidate weights, and throwing candidate factories
-         * fail immediately.
-         *
-         * @category models
-         * @since 4.0.0
-         */
-        interface Report {
-            readonly warnings: ReadonlyArray<Warning>;
-        }
-        /**
-         * Non-fatal arbitrary-derivation warning.
-         *
-         * @category models
-         * @since 4.0.0
-         */
-        type Warning = OpaqueFilterWarning;
-        /**
-         * Warning emitted when a filter is handled only by the final `.filter`.
-         *
-         * **Details**
-         *
-         * The filter is still enforced. The warning means it did not contribute
-         * a constraint or candidate, so generation may rely on fast-check discards.
-         *
-         * @category models
-         * @since 4.0.0
-         */
-        interface OpaqueFilterWarning {
-            readonly _tag: "OpaqueFilter";
-            readonly path: ReadonlyArray<PropertyKey>;
-            readonly description?: string | undefined;
-        }
     }
     /**
      * Types used by formatter annotations to customize formatter derivation for
@@ -11134,12 +11120,22 @@ export declare namespace Annotations {
      *
      * **Details**
      *
-     * The optional `message` field overrides the default issue message.
+     * For `InvalidValue` issues, `message` overrides the complete formatted
+     * message. When `message` is absent, `expected` uses the default expected
+     * value policy, including reported input when available. Other issue types
+     * ignore `expected`.
      *
      * @category models
      * @since 4.0.0
      */
     interface Issue extends Annotations {
+        /**
+         * The expected value description for an `InvalidValue` issue.
+         */
+        readonly expected?: string | undefined;
+        /**
+         * The complete formatted message for the issue.
+         */
         readonly message?: string | undefined;
     }
 }