effect 4.0.0-beta.98 → 4.0.0-rc.108

package/dist/Optic.d.ts

@@ -15,6 +15,7 @@ import * as Option from "./Option.ts";
 import * as Result from "./Result.ts";
 import type * as Schema from "./Schema.ts";
 import * as SchemaAST from "./SchemaAST.ts";
+import * as SchemaIssue from "./SchemaIssue.ts";
 import type { IsUnion } from "./Types.ts";
 /**
  * A lossless, reversible conversion between types `S` and `A`.
@@ -34,7 +35,7 @@ import type { IsUnion } from "./Types.ts";
  *
  * **Example** (Converting between Celsius and Fahrenheit)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic } from "effect"
  *
  * const fahrenheit = Optic.makeIso<number, number>(
@@ -42,18 +43,16 @@ import type { IsUnion } from "./Types.ts";
  *   (f) => (f - 32) * 5 / 9
  * )
  *
- * console.log(fahrenheit.get(100))
- * // Output: 212
+ * fahrenheit.get(100) // => 212
  *
- * console.log(fahrenheit.set(32))
- * // Output: 0
+ * fahrenheit.set(32) // => 0
  * ```
  *
  * @see {@link makeIso} — constructor
  * @see {@link Lens} — when you only need a one-directional focus into a whole
  * @see {@link Prism} — when the focus may not be present
  *
- * @category Iso
+ * @category models
  * @since 4.0.0
  */
 export interface Iso<in out S, in out A> extends Lens<S, A>, Prism<S, A> {
@@ -72,7 +71,7 @@ export interface Iso<in out S, in out A> extends Lens<S, A>, Prism<S, A> {
  *
  * **Example** (Wrapping and unwrapping a branded type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic } from "effect"
  *
  * type Meters = { readonly value: number }
@@ -81,11 +80,9 @@ export interface Iso<in out S, in out A> extends Lens<S, A>, Prism<S, A> {
  *   (n) => ({ value: n })
  * )
  *
- * console.log(meters.get({ value: 100 }))
- * // Output: 100
+ * meters.get({ value: 100 }) // => 100
  *
- * console.log(meters.set(42))
- * // Output: { value: 42 }
+ * meters.set(42) // => { value: 42 }
  * ```
  *
  * @see {@link Iso} — the type this function returns
@@ -113,22 +110,21 @@ export declare function makeIso<S, A>(get: (s: S) => A, set: (a: A) => S): Iso<S
  *
  * **Example** (Focusing on a struct field)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic } from "effect"
  *
  * type Person = { readonly name: string; readonly age: number }
  *
  * const _name = Optic.id<Person>().key("name")
  *
- * console.log(_name.get({ name: "Alice", age: 30 }))
- * // Output: "Alice"
+ * _name.get({ name: "Alice", age: 30 }) // => "Alice"
  * ```
  *
  * @see {@link makeLens} — constructor
  * @see {@link Iso} — when conversion is lossless in both directions
  * @see {@link Optional} — when reading can also fail
  *
- * @category Lens
+ * @category models
  * @since 4.0.0
  */
 export interface Lens<in out S, in out A> extends Optional<S, A> {
@@ -149,7 +145,7 @@ export interface Lens<in out S, in out A> extends Optional<S, A> {
  *
  * **Example** (Focusing on the first element of a pair)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic } from "effect"
  *
  * const _first = Optic.makeLens<readonly [string, number], string>(
@@ -157,11 +153,9 @@ export interface Lens<in out S, in out A> extends Optional<S, A> {
  *   (s, pair) => [s, pair[1]]
  * )
  *
- * console.log(_first.get(["hello", 42]))
- * // Output: "hello"
+ * _first.get(["hello", 42]) // => "hello"
  *
- * console.log(_first.replace("world", ["hello", 42]))
- * // Output: ["world", 42]
+ * _first.replace("world", ["hello", 42]) // => ["world", 42]
  * ```
  *
  * @see {@link Lens} — the type this function returns
@@ -184,7 +178,7 @@ export declare function makeLens<S, A>(get: (s: S) => A, replace: (a: A, s: S) =
  * **Details**
  *
  * - `getResult(s)` returns `Result.Success<A>` when the focus matches, or
- *   `Result.Failure<string>` with an error message.
+ *   `Result.Failure<SchemaIssue.Issue>` with a structured issue.
  * - `set(a)` always succeeds and returns a new `S`.
  * - Extends {@link Optional}.
  * - Composing two Prisms produces a Prism; composing a Prism with a
@@ -192,7 +186,7 @@ export declare function makeLens<S, A>(get: (s: S) => A, replace: (a: A, s: S) =
  *
  * **Example** (Narrowing a tagged union)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Result } from "effect"
  *
  * type Shape =
@@ -201,18 +195,16 @@ export declare function makeLens<S, A>(get: (s: S) => A, replace: (a: A, s: S) =
  *
  * const _circle = Optic.id<Shape>().tag("Circle")
  *
- * console.log(Result.isSuccess(_circle.getResult({ _tag: "Circle", radius: 5 })))
- * // Output: true
+ * _circle.getResult({ _tag: "Circle", radius: 5 }) // => Result.succeed({ _tag: "Circle", radius: 5 })
  *
- * console.log(Result.isFailure(_circle.getResult({ _tag: "Rect", width: 10 })))
- * // Output: true
+ * Result.isFailure(_circle.getResult({ _tag: "Rect", width: 10 })) // => true
  * ```
  *
  * @see {@link makePrism} — constructor
  * @see {@link fromChecks} — build a Prism from schema checks
  * @see {@link Lens} — when reading always succeeds
  *
- * @category Prism
+ * @category models
  * @since 4.0.0
  */
 export interface Prism<in out S, in out A> extends Optional<S, A> {
@@ -228,26 +220,27 @@ export interface Prism<in out S, in out A> extends Optional<S, A> {
  *
  * **Details**
  *
- * - `getResult` should return `Result.fail(message)` on mismatch.
+ * - `getResult` should return `Result.fail(issue)` on mismatch.
+ * - Issues are not formatted automatically; callers choose how to render them.
  *
  * **Example** (Parsing a string to a number)
  *
- * ```ts
- * import { Optic, Result } from "effect"
+ * ```ts import.meta.vitest
+ * import { Optic, Result, SchemaIssue } from "effect"
  *
  * const numeric = Optic.makePrism<string, number>(
  *   (s) => {
  *     const n = Number(s)
- *     return Number.isNaN(n) ? Result.fail("not a number") : Result.succeed(n)
+ *     return Number.isNaN(n)
+ *       ? Result.fail(new SchemaIssue.InvalidValue({ message: "not a number" }))
+ *       : Result.succeed(n)
  *   },
  *   String
  * )
  *
- * console.log(Result.isSuccess(numeric.getResult("42")))
- * // Output: true
+ * numeric.getResult("42") // => Result.succeed(42)
  *
- * console.log(numeric.set(42))
- * // Output: "42"
+ * numeric.set(42) // => "42"
  * ```
  *
  * @see {@link Prism} — the type this function returns
@@ -256,7 +249,7 @@ export interface Prism<in out S, in out A> extends Optional<S, A> {
  * @category constructors
  * @since 4.0.0
  */
-export declare function makePrism<S, A>(getResult: (s: S) => Result.Result<A, string>, set: (a: A) => S): Prism<S, A>;
+export declare function makePrism<S, A>(getResult: (s: S) => Result.Result<A, SchemaIssue.Issue>, set: (a: A) => S): Prism<S, A>;
 /**
  * Creates a {@link Prism} from one or more `Schema` validation checks.
  *
@@ -268,13 +261,13 @@ export declare function makePrism<S, A>(getResult: (s: S) => Result.Result<A, st
  *
  * **Details**
  *
- * - `getResult` runs all checks; fails with a combined error message when
+ * - `getResult` runs all checks and preserves their structured issues when
  *   any check fails.
  * - `set` is identity — the value passes through unchanged.
  *
  * **Example** (Creating a positive integer prism)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Result, Schema } from "effect"
  *
  * const posInt = Optic.fromChecks<number>(
@@ -282,11 +275,9 @@ export declare function makePrism<S, A>(getResult: (s: S) => Result.Result<A, st
  *   Schema.isInt()
  * )
  *
- * console.log(Result.isSuccess(posInt.getResult(3)))
- * // Output: true
+ * posInt.getResult(3) // => Result.succeed(3)
  *
- * console.log(Result.isFailure(posInt.getResult(-1)))
- * // Output: true
+ * Result.isFailure(posInt.getResult(-1)) // => true
  * ```
  *
  * @see {@link makePrism} — constructor with custom getter/setter
@@ -296,49 +287,6 @@ export declare function makePrism<S, A>(getResult: (s: S) => Result.Result<A, st
  * @since 4.0.0
  */
 export declare function fromChecks<T>(...checks: readonly [SchemaAST.Check<T>, ...Array<SchemaAST.Check<T>>]): Prism<T, T>;
-type Node = IdentityNode | IsoNode<any, any> | LensNode<any, any> | PrismNode<any, any> | OptionalNode<any, any> | PathNode | CheckNode<any> | CompositionNode;
-declare class IdentityNode {
-    readonly _tag = "IdentityNode";
-}
-declare class CompositionNode {
-    readonly _tag = "CompositionNode";
-    readonly nodes: readonly [Node, ...Array<Node>];
-    constructor(nodes: readonly [Node, ...Array<Node>]);
-}
-declare class IsoNode<S, A> {
-    readonly _tag = "IsoNode";
-    readonly get: (s: S) => A;
-    readonly set: (a: A) => S;
-    constructor(get: (s: S) => A, set: (a: A) => S);
-}
-declare class LensNode<S, A> {
-    readonly _tag = "LensNode";
-    readonly get: (s: S) => A;
-    readonly set: (a: A, s: S) => S;
-    constructor(get: (s: S) => A, set: (a: A, s: S) => S);
-}
-declare class PrismNode<S, A> {
-    readonly _tag = "PrismNode";
-    readonly get: (s: S) => Result.Result<A, string>;
-    readonly set: (a: A) => S;
-    constructor(get: (s: S) => Result.Result<A, string>, set: (a: A) => S);
-}
-declare class OptionalNode<S, A> {
-    readonly _tag = "OptionalNode";
-    readonly get: (s: S) => Result.Result<A, string>;
-    readonly set: (a: A, s: S) => Result.Result<S, string>;
-    constructor(get: (s: S) => Result.Result<A, string>, set: (a: A, s: S) => Result.Result<S, string>);
-}
-declare class PathNode {
-    readonly _tag = "PathNode";
-    readonly path: ReadonlyArray<PropertyKey>;
-    constructor(path: ReadonlyArray<PropertyKey>);
-}
-declare class CheckNode<T> {
-    readonly _tag = "CheckNode";
-    readonly checks: readonly [SchemaAST.Check<T>, ...Array<SchemaAST.Check<T>>];
-    constructor(checks: readonly [SchemaAST.Check<T>, ...Array<SchemaAST.Check<T>>]);
-}
 type ForbidUnion<A, Message extends string> = IsUnion<A> extends true ? [Message] : [];
 /**
  * The most general optic — both reading and writing can fail.
@@ -352,47 +300,43 @@ type ForbidUnion<A, Message extends string> = IsUnion<A> extends true ? [Message
  *
  * **Details**
  *
- * - `getResult(s)` returns `Result.Success<A>` or `Result.Failure<string>`.
+ * - `getResult(s)` returns `Result.Success<A>` or `Result.Failure<SchemaIssue.Issue>`.
  * - `replaceResult(a, s)` returns `Result.Success<S>` or
- *   `Result.Failure<string>`.
+ *   `Result.Failure<SchemaIssue.Issue>`.
  * - `replace(a, s)` returns the original `s` on failure (never throws).
  * - `modify(f)` returns the original `s` on failure (never throws).
  * - All operations are pure; inputs are never mutated.
  *
  * **Example** (Focusing on an optional record key)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Result } from "effect"
  *
  * type Env = { [key: string]: string }
  * const _home = Optic.id<Env>().at("HOME")
  *
- * console.log(Result.isSuccess(_home.getResult({ HOME: "/root" })))
- * // Output: true
+ * _home.getResult({ HOME: "/root" }) // => Result.succeed("/root")
  *
- * console.log(Result.isFailure(_home.getResult({ PATH: "/bin" })))
- * // Output: true
+ * Result.isFailure(_home.getResult({ PATH: "/bin" })) // => true
  *
  * // replace returns original on failure
- * console.log(_home.replace("/new", { PATH: "/bin" }))
- * // Output: { PATH: "/bin" }
+ * _home.replace("/new", { PATH: "/bin" }) // => { PATH: "/bin" }
  * ```
  *
  * @see {@link makeOptional} — constructor
  * @see {@link Lens} — when reading always succeeds
  * @see {@link Prism} — when writing always succeeds
  *
- * @category Optional
+ * @category models
  * @since 4.0.0
  */
 export interface Optional<in out S, in out A> {
-    readonly node: Node;
     /**
      * Attempts to read the focus `A` from the whole `S`. Returns
      * `Result.Success<A>` when the focus exists, or
-     * `Result.Failure<string>` with a descriptive error otherwise.
+     * `Result.Failure<SchemaIssue.Issue>` with a structured issue otherwise.
      */
-    readonly getResult: (s: S) => Result.Result<A, string>;
+    readonly getResult: (s: S) => Result.Result<A, SchemaIssue.Issue>;
     /**
      * Replaces the focus in `S` with a new `A`. Returns the original `s`
      * unchanged when the optic cannot focus (never throws).
@@ -402,20 +346,21 @@ export interface Optional<in out S, in out A> {
      * Like {@link replace}, but returns an explicit `Result` so callers can
      * detect and handle failure.
      */
-    readonly replaceResult: (a: A, s: S) => Result.Result<S, string>;
+    readonly replaceResult: (a: A, s: S) => Result.Result<S, SchemaIssue.Issue>;
     /**
      * Composes this optic with another. The result type is the weakest of
      * the two: Iso + Iso = Iso, Lens + Prism = Optional, etc.
      *
      * **Example** (Composing a lens with a prism)
      *
-     * ```ts
-     * import { Optic, Option } from "effect"
+     * ```ts import.meta.vitest
+     * import { Optic, Option, Result } from "effect"
      *
      * type State = { value: Option.Option<number> }
      *
      * const _inner = Optic.id<State>().key("value").compose(Optic.some())
      * // _inner is Optional<State, number>
+     * _inner.getResult({ value: Option.some(1) }) // => Result.succeed(1)
      * ```
      *
      * @see {@link id} — start a composition chain
@@ -430,15 +375,14 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Incrementing a nested field)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic } from "effect"
      *
      * type S = { readonly a: { readonly b: number } }
      * const _b = Optic.id<S>().key("a").key("b")
      *
      * const inc = _b.modify((n) => n + 1)
-     * console.log(inc({ a: { b: 1 } }))
-     * // Output: { a: { b: 2 } }
+     * inc({ a: { b: 1 } }) // => { a: { b: 2 } }
      * ```
      */
     modify(f: (a: A) => A): (s: S) => S;
@@ -453,14 +397,13 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Drilling into nested structs)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic } from "effect"
      *
      * type S = { readonly a: { readonly b: number } }
      * const _b = Optic.id<S>().key("a").key("b")
      *
-     * console.log(_b.get({ a: { b: 42 } }))
-     * // Output: 42
+     * _b.get({ a: { b: 42 } }) // => 42
      * ```
      */
     key<S, A extends object, Key extends keyof A>(this: Lens<S, A>, key: Key, ..._err: ForbidUnion<A, "cannot use `key` on a union type">): Lens<S, A[Key]>;
@@ -476,17 +419,15 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Deleting an optional key)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic } from "effect"
      *
      * type S = { readonly a?: number }
      * const _a = Optic.id<S>().optionalKey("a")
      *
-     * console.log(_a.replace(undefined, { a: 1 }))
-     * // Output: {}
+     * _a.replace(undefined, { a: 1 }) // => {}
      *
-     * console.log(_a.replace(2, {}))
-     * // Output: { a: 2 }
+     * _a.replace(2, {}) // => { a: 2 }
      * ```
      */
     optionalKey<S, A extends object, Key extends keyof A>(this: Lens<S, A>, key: Key, ..._err: ForbidUnion<A, "cannot use `optionalKey` on a union type">): Lens<S, A[Key] | undefined>;
@@ -502,16 +443,14 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Focusing only on positive numbers)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic, Result, Schema } from "effect"
      *
      * const _pos = Optic.id<number>().check(Schema.isGreaterThan(0))
      *
-     * console.log(Result.isSuccess(_pos.getResult(5)))
-     * // Output: true
+     * _pos.getResult(5) // => Result.succeed(5)
      *
-     * console.log(Result.isFailure(_pos.getResult(-1)))
-     * // Output: true
+     * Result.isFailure(_pos.getResult(-1)) // => true
      * ```
      *
      * @see {@link fromChecks} — standalone prism from checks
@@ -529,7 +468,7 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Narrowing a union)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic, Result } from "effect"
      *
      * type B = { readonly _tag: "b"; readonly b: number }
@@ -540,8 +479,7 @@ export interface Optional<in out S, in out A> {
      *   { expected: `"b" tag` }
      * )
      *
-     * console.log(Result.isSuccess(_b.getResult({ _tag: "b", b: 1 })))
-     * // Output: true
+     * _b.getResult({ _tag: "b", b: 1 }) // => Result.succeed({ _tag: "b", b: 1 })
      * ```
      *
      * @see `.tag()` — shorthand for narrowing by `_tag`
@@ -557,10 +495,12 @@ export interface Optional<in out S, in out A> {
      * - On a {@link Prism}, returns a Prism.
      * - On an {@link Optional}, returns an Optional.
      * - Shorthand for `.refine(s => s._tag === tag)`.
+     * - A non-matching value fails with {@link SchemaIssue.InvalidValue} whose
+     *   `expected` annotation is `"<tag> tag"`.
      *
      * **Example** (Focusing a tagged variant)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic, Result } from "effect"
      *
      * type Shape =
@@ -569,11 +509,9 @@ export interface Optional<in out S, in out A> {
      *
      * const _radius = Optic.id<Shape>().tag("Circle").key("radius")
      *
-     * console.log(Result.isSuccess(_radius.getResult({ _tag: "Circle", radius: 5 })))
-     * // Output: true
+     * _radius.getResult({ _tag: "Circle", radius: 5 }) // => Result.succeed(5)
      *
-     * console.log(Result.isFailure(_radius.getResult({ _tag: "Rect", width: 10 })))
-     * // Output: true
+     * Result.isFailure(_radius.getResult({ _tag: "Rect", width: 10 })) // => true
      * ```
      *
      * @see `.refine()` — for arbitrary type guards
@@ -599,20 +537,21 @@ export interface Optional<in out S, in out A> {
      *
      * - Always returns an {@link Optional}.
      * - Does **not** work on union types (compile error).
+     * - A missing key fails with a {@link SchemaIssue.Pointer} at that key whose
+     *   inner issue is {@link SchemaIssue.MissingKey}, for both `getResult` and
+     *   `replaceResult`.
      *
      * **Example** (Accessing records safely)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic, Result } from "effect"
      *
      * type Env = { [key: string]: number }
      * const _x = Optic.id<Env>().at("x")
      *
-     * console.log(Result.isSuccess(_x.getResult({ x: 1 })))
-     * // Output: true
+     * _x.getResult({ x: 1 }) // => Result.succeed(1)
      *
-     * console.log(Result.isFailure(_x.getResult({ y: 2 })))
-     * // Output: true
+     * Result.isFailure(_x.getResult({ y: 2 })) // => true
      * ```
      *
      * @see `.key()` — when the key is always present
@@ -629,15 +568,14 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Picking keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic } from "effect"
      *
      * type S = { readonly a: string; readonly b: number; readonly c: boolean }
      *
      * const _ac = Optic.id<S>().pick(["a", "c"])
      *
-     * console.log(_ac.get({ a: "hi", b: 1, c: true }))
-     * // Output: { a: "hi", c: true }
+     * _ac.get({ a: "hi", b: 1, c: true }) // => { a: "hi", c: true }
      * ```
      *
      * @see `.omit()` — the inverse operation
@@ -655,15 +593,14 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Omitting keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic } from "effect"
      *
      * type S = { readonly a: string; readonly b: number; readonly c: boolean }
      *
      * const _ac = Optic.id<S>().omit(["b"])
      *
-     * console.log(_ac.get({ a: "hi", b: 1, c: true }))
-     * // Output: { a: "hi", c: true }
+     * _ac.get({ a: "hi", b: 1, c: true }) // => { a: "hi", c: true }
      * ```
      *
      * @see `.pick()` — the inverse operation
@@ -678,22 +615,20 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Filtering undefined values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic, Result } from "effect"
      *
      * const _defined = Optic.id<number | undefined>().notUndefined()
      *
-     * console.log(Result.isSuccess(_defined.getResult(42)))
-     * // Output: true
+     * _defined.getResult(42) // => Result.succeed(42)
      *
-     * console.log(Result.isFailure(_defined.getResult(undefined)))
-     * // Output: true
+     * Result.isFailure(_defined.getResult(undefined)) // => true
      * ```
      *
      * @since 4.0.0
      */
-    notUndefined(): Prism<S, Exclude<A, undefined>>;
-    notUndefined(): Optional<S, Exclude<A, undefined>>;
+    notUndefined<S, A>(this: Prism<S, A>): Prism<S, Exclude<A, undefined>>;
+    notUndefined<S, A>(this: Optional<S, A>): Optional<S, Exclude<A, undefined>>;
     /**
      * Focuses **all elements** of an array-like focus and optionally narrows
      * to a subset using an element-level optic.
@@ -707,11 +642,13 @@ export interface Optional<in out S, in out A> {
      *   element. Non-focusable elements are skipped.
      * - **replaceResult** expects exactly as many values as were collected by
      *   `getResult` and writes them back in order. Fails with a
-     *   length-mismatch error if counts differ.
+     *   {@link SchemaIssue.InvalidValue} if counts differ. If an inner replacement
+     *   fails, its issue is wrapped in a {@link SchemaIssue.Pointer} at the element
+     *   index.
      *
      * **Example** (Incrementing liked posts)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic, Schema } from "effect"
      *
      * type Post = { title: string; likes: number }
@@ -724,12 +661,10 @@ export interface Optional<in out S, in out A> {
      *
      * const addLike = _likes.modifyAll((n) => n + 1)
      *
-     * console.log(
-     *   addLike({
-     *     user: { posts: [{ title: "a", likes: 0 }, { title: "b", likes: 1 }] }
-     *   })
-     * )
-     * // Output: { user: { posts: [{ title: "a", likes: 0 }, { title: "b", likes: 2 }] } }
+     * const result = addLike({
+     *   user: { posts: [{ title: "a", likes: 0 }, { title: "b", likes: 1 }] }
+     * })
+     * result.user.posts // => [{ title: "a", likes: 0 }, { title: "b", likes: 2 }]
      * ```
      *
      * @see {@link getAll} — extract all focused elements as an array
@@ -749,7 +684,7 @@ export interface Optional<in out S, in out A> {
      *
      * **Example** (Doubling all focused values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Optic, Schema } from "effect"
      *
      * type S = { readonly items: ReadonlyArray<number> }
@@ -760,8 +695,7 @@ export interface Optional<in out S, in out A> {
      *
      * const doubled = _positive.modifyAll((n) => n * 2)
      *
-     * console.log(doubled({ items: [1, -2, 3] }))
-     * // Output: { items: [2, -2, 6] }
+     * doubled({ items: [1, -2, 3] }) // => { items: [2, -2, 6] }
      * ```
      *
      * @see `.forEach()` — create a sub-traversal
@@ -779,29 +713,31 @@ export interface Optional<in out S, in out A> {
  *
  * **Details**
  *
- * - `getResult` should return `Result.fail(message)` on mismatch.
- * - `set` should return `Result.fail(message)` when the update cannot be
+ * - `getResult` should return `Result.fail(issue)` on mismatch.
+ * - `set` should return `Result.fail(issue)` when the update cannot be
  *   applied.
+ * - Issues are not formatted automatically; callers choose how to render them.
  *
  * **Example** (Accessing record keys safely)
  *
- * ```ts
- * import { Optic, Result } from "effect"
+ * ```ts import.meta.vitest
+ * import { Optic, Result, SchemaIssue } from "effect"
  *
- * const atKey = (key: string) =>
- *   Optic.makeOptional<Record<string, number>, number>(
+ * const atKey = (key: string) => {
+ *   const issue = new SchemaIssue.Pointer([key], new SchemaIssue.MissingKey(undefined))
+ *   return Optic.makeOptional<Record<string, number>, number>(
  *     (s) =>
  *       Object.hasOwn(s, key)
  *         ? Result.succeed(s[key])
- *         : Result.fail(`Key "${key}" not found`),
+ *         : Result.fail(issue),
  *     (a, s) =>
  *       Object.hasOwn(s, key)
  *         ? Result.succeed({ ...s, [key]: a })
- *         : Result.fail(`Key "${key}" not found`)
+ *         : Result.fail(issue)
  *   )
+ * }
  *
- * console.log(Result.isSuccess(atKey("x").getResult({ x: 1 })))
- * // Output: true
+ * atKey("x").getResult({ x: 1 }) // => Result.succeed(1)
  * ```
  *
  * @see {@link Optional} — the type this function returns
@@ -811,7 +747,7 @@ export interface Optional<in out S, in out A> {
  * @category constructors
  * @since 4.0.0
  */
-export declare function makeOptional<S, A>(getResult: (s: S) => Result.Result<A, string>, set: (a: A, s: S) => Result.Result<S, string>): Optional<S, A>;
+export declare function makeOptional<S, A>(getResult: (s: S) => Result.Result<A, SchemaIssue.Issue>, set: (a: A, s: S) => Result.Result<S, SchemaIssue.Issue>): Optional<S, A>;
 /**
  * An optic that focuses on **zero or more** elements of type `A` inside `S`.
  *
@@ -831,7 +767,7 @@ export declare function makeOptional<S, A>(getResult: (s: S) => Result.Result<A,
  *
  * **Example** (Traversing array elements with a filter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Schema } from "effect"
  *
  * type S = { readonly items: ReadonlyArray<number> }
@@ -842,14 +778,13 @@ export declare function makeOptional<S, A>(getResult: (s: S) => Result.Result<A,
  *
  * const getPositive = Optic.getAll(_positive)
  *
- * console.log(getPositive({ items: [1, -2, 3] }))
- * // Output: [1, 3]
+ * getPositive({ items: [1, -2, 3] }) // => [1, 3]
  * ```
  *
  * @see {@link getAll} — extract focused elements
  * @see {@link Optional} — the base type
  *
- * @category Traversal
+ * @category models
  * @since 4.0.0
  */
 export interface Traversal<in out S, in out A> extends Optional<S, ReadonlyArray<A>> {
@@ -870,7 +805,7 @@ export interface Traversal<in out S, in out A> extends Optional<S, ReadonlyArray
  *
  * **Example** (Collecting positive numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Schema } from "effect"
  *
  * type S = { readonly values: ReadonlyArray<number> }
@@ -881,16 +816,14 @@ export interface Traversal<in out S, in out A> extends Optional<S, ReadonlyArray
  *
  * const getPositive = Optic.getAll(_pos)
  *
- * console.log(getPositive({ values: [3, -1, 5] }))
- * // Output: [3, 5]
+ * getPositive({ values: [3, -1, 5] }) // => [3, 5]
  *
- * console.log(getPositive({ values: [-1, -2] }))
- * // Output: []
+ * getPositive({ values: [-1, -2] }) // => []
  * ```
  *
  * @see {@link Traversal} — the optic type this operates on
  *
- * @category Traversal
+ * @category getters
  * @since 4.0.0
  */
 export declare function getAll<S, A>(traversal: Traversal<S, A>): (s: S) => Array<A>;
@@ -909,20 +842,19 @@ export declare function getAll<S, A>(traversal: Traversal<S, A>): (s: S) => Arra
  *
  * **Example** (Starting an optic chain)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic } from "effect"
  *
  * type S = { readonly x: number }
  *
  * const _x = Optic.id<S>().key("x")
  *
- * console.log(_x.get({ x: 42 }))
- * // Output: 42
+ * _x.get({ x: 42 }) // => 42
  * ```
  *
  * @see {@link Iso} — the type this function returns
  *
- * @category Iso
+ * @category constructors
  * @since 4.0.0
  */
 export declare function id<S>(): Iso<S, S>;
@@ -943,7 +875,7 @@ export declare function id<S>(): Iso<S, S>;
  *
  * **Example** (Traversing record values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Schema } from "effect"
  *
  * const _positiveValues = Optic.entries<number>()
@@ -951,14 +883,13 @@ export declare function id<S>(): Iso<S, S>;
  *
  * const inc = _positiveValues.modifyAll((n) => n + 1)
  *
- * console.log(inc({ a: 0, b: 3, c: -1 }))
- * // Output: { a: 0, b: 4, c: -1 }
+ * inc({ a: 0, b: 3, c: -1 }) // => { a: 0, b: 4, c: -1 }
  * ```
  *
  * @see {@link Iso} — the type this function returns
  * @see {@link id} — identity iso
  *
- * @category Iso
+ * @category constructors
  * @since 4.0.0
  */
 export declare function entries<A>(): Iso<Record<string, A>, ReadonlyArray<readonly [string, A]>>;
@@ -972,30 +903,27 @@ export declare function entries<A>(): Iso<Record<string, A>, ReadonlyArray<reado
  *
  * **Details**
  *
- * - `getResult` fails with an error message when the option is `None`.
+ * - `getResult` fails with a structured issue when the option is `None`.
  * - `set(a)` wraps `a` in `Option.some(a)`.
  *
  * **Example** (Accessing Some value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Option, Result } from "effect"
  *
  * const _some = Optic.id<Option.Option<number>>().compose(Optic.some())
  *
- * console.log(Result.isSuccess(_some.getResult(Option.some(42))))
- * // Output: true
+ * _some.getResult(Option.some(42)) // => Result.succeed(42)
  *
- * console.log(Result.isFailure(_some.getResult(Option.none())))
- * // Output: true
+ * Result.isFailure(_some.getResult(Option.none())) // => true
  *
- * console.log(_some.set(10))
- * // Output: { _tag: "Some", value: 10 }
+ * _some.set(10) // => Option.some(10)
  * ```
  *
  * @see {@link none} — focuses on `None` instead
  * @see {@link Prism} — the type this function returns
  *
- * @category Prism
+ * @category constructors
  * @since 4.0.0
  */
 export declare function some<A>(): Prism<Option.Option<A>, A>;
@@ -1014,22 +942,20 @@ export declare function some<A>(): Prism<Option.Option<A>, A>;
  *
  * **Example** (Matching None)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Option, Result } from "effect"
  *
  * const _none = Optic.id<Option.Option<number>>().compose(Optic.none())
  *
- * console.log(Result.isSuccess(_none.getResult(Option.none())))
- * // Output: true
+ * _none.getResult(Option.none()) // => Result.succeed(undefined)
  *
- * console.log(Result.isFailure(_none.getResult(Option.some(1))))
- * // Output: true
+ * Result.isFailure(_none.getResult(Option.some(1))) // => true
  * ```
  *
  * @see {@link some} — focuses on `Some` instead
  * @see {@link Prism} — the type this function returns
  *
- * @category Prism
+ * @category constructors
  * @since 4.0.0
  */
 export declare function none<A>(): Prism<Option.Option<A>, undefined>;
@@ -1048,22 +974,20 @@ export declare function none<A>(): Prism<Option.Option<A>, undefined>;
  *
  * **Example** (Accessing success)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Result } from "effect"
  *
  * const _ok = Optic.id<Result.Result<number, string>>().compose(Optic.success())
  *
- * console.log(Result.isSuccess(_ok.getResult(Result.succeed(42))))
- * // Output: true
+ * _ok.getResult(Result.succeed(42)) // => Result.succeed(42)
  *
- * console.log(Result.isFailure(_ok.getResult(Result.fail("err"))))
- * // Output: true
+ * Result.isFailure(_ok.getResult(Result.fail("err"))) // => true
  * ```
  *
  * @see {@link failure} — focuses on the failure side
  * @see {@link Prism} — the type this function returns
  *
- * @category Prism
+ * @category constructors
  * @since 4.0.0
  */
 export declare function success<A, E>(): Prism<Result.Result<A, E>, A>;
@@ -1082,22 +1006,20 @@ export declare function success<A, E>(): Prism<Result.Result<A, E>, A>;
  *
  * **Example** (Accessing failure)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Optic, Result } from "effect"
  *
  * const _err = Optic.id<Result.Result<number, string>>().compose(Optic.failure())
  *
- * console.log(Result.isSuccess(_err.getResult(Result.fail("oops"))))
- * // Output: true
+ * _err.getResult(Result.fail("oops")) // => Result.succeed("oops")
  *
- * console.log(Result.isFailure(_err.getResult(Result.succeed(42))))
- * // Output: true
+ * Result.isFailure(_err.getResult(Result.succeed(42))) // => true
  * ```
  *
  * @see {@link success} — focuses on the success side
  * @see {@link Prism} — the type this function returns
  *
- * @category Prism
+ * @category constructors
  * @since 4.0.0
  */
 export declare function failure<A, E>(): Prism<Result.Result<A, E>, E>;