effect 4.0.0-beta.2 → 4.0.0-beta.21

package/dist/Filter.js

@@ -3,19 +3,6 @@ import { dual } from "./Function.js";
 import * as Option from "./Option.js";
 import * as Predicate from "./Predicate.js";
 import * as Result from "./Result.js";
-/**
- * Applies a filter, predicate, or refinement to an input and returns a boxed
- * result. Extra arguments are forwarded to the function.
- *
- * @since 4.0.0
- * @category Apply
- */
-export const apply = (filter, input, ...args) => {
-  const result = filter(input, ...args);
-  if (result === true) return Result.succeed(input);
-  if (result === false) return Result.fail(input);
-  return result;
-};
 // -------------------------------------------------------------------------------------
 // Constructors
 // -------------------------------------------------------------------------------------
@@ -214,6 +201,21 @@ export const tagged = function () {
   return arguments.length === 0 ? taggedImpl : taggedImpl(arguments[0]);
 };
 const taggedImpl = tag => input => Predicate.isTagged(input, tag) ? Result.succeed(input) : Result.fail(input);
+/**
+ * Creates a filter that extracts a reason from a tagged error.
+ *
+ * @since 4.0.0
+ * @category Constructors
+ */
+export const reason = function () {
+  return arguments.length === 0 ? reasonImpl : reasonImpl(arguments[0], arguments[1]);
+};
+const reasonImpl = (tag, reasonTag) => input => {
+  if (Predicate.isTagged(input, tag) && Predicate.hasProperty(input, "reason") && Predicate.isTagged(input.reason, reasonTag)) {
+    return Result.succeed(input.reason);
+  }
+  return Result.fail(input);
+};
 /**
  * Creates a filter that only passes values equal to the specified value using structural equality.
  *

package/dist/Filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"Filter.js","names":["Equal","dual","Option","Predicate","Result","apply","filter","input","args","result","succeed","fail","make","f","makeEffect","mapFail","self","mapError","try_","try","fromPredicate","predicate","fromPredicateOption","o","_tag","value","toPredicate","isFailure","string","isString","equalsStrict","u","has","key","instanceOf","constructor","number","isNumber","boolean","isBoolean","bigint","isBigInt","symbol","isSymbol","date","isDate","tagged","arguments","length","taggedImpl","tag","isTagged","equals","or","that","selfResult","isSuccess","zipWith","left","right","leftResult","rightResult","success","zip","andLeft","andRight","_","compose","leftOut","composePassthrough","rightOut","toOption","none","some","toResult","failure"],"sources":["../src/Filter.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"Filter.js","names":["Equal","dual","Option","Predicate","Result","make","f","makeEffect","mapFail","self","input","mapError","try_","succeed","fail","try","fromPredicate","predicate","fromPredicateOption","o","_tag","value","toPredicate","isFailure","string","isString","equalsStrict","u","has","key","instanceOf","constructor","number","isNumber","boolean","isBoolean","bigint","isBigInt","symbol","isSymbol","date","isDate","tagged","arguments","length","taggedImpl","tag","isTagged","reason","reasonImpl","reasonTag","hasProperty","equals","or","that","selfResult","isSuccess","zipWith","left","right","leftResult","rightResult","success","zip","andLeft","andRight","_","compose","leftOut","composePassthrough","rightOut","toOption","result","none","some","toResult","failure"],"sources":["../src/Filter.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/Formatter.d.ts

@@ -1,4 +1,28 @@
 /**
+ * A callable interface representing a function that converts a `Value` into a
+ * `Format` (defaults to `string`).
+ *
+ * When to use:
+ * - You want to type a formatting / rendering function generically.
+ * - You are building a pipeline that accepts pluggable formatters.
+ *
+ * Behavior:
+ * - Pure callable type; carries no runtime implementation.
+ * - Contravariant in `Value`, covariant in `Format`.
+ *
+ * **Example** (Define a custom formatter)
+ *
+ * ```ts
+ * import type { Formatter } from "effect"
+ *
+ * const upper: Formatter.Formatter<string> = (s) => s.toUpperCase()
+ *
+ * console.log(upper("hello"))
+ * // HELLO
+ * ```
+ *
+ * See also: {@link format}, {@link formatJson}
+ *
  * @category Model
  * @since 4.0.0
  */
@@ -8,31 +32,71 @@ export interface Formatter<in Value, out Format = string> {
 /**
  * Converts any JavaScript value into a human-readable string.
  *
- * For objects that don't have a `toString` method, it applies redaction to
- * protect sensitive information.
- *
- * Unlike `JSON.stringify`, this formatter:
- * - Handles circular references (printed as `"[Circular]"`).
- * - Supports additional types like `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`, and
- *   objects with custom `toString` methods.
- * - Includes constructor names for class instances (e.g. `MyClass({"a":1})`).
- * - Does not guarantee valid JSON output — the result is intended for debugging and inspection.
- *
- * Formatting rules:
- * - Primitives are stringified naturally (`null`, `undefined`, `123`, `"abc"`, `true`).
- * - Strings are JSON-quoted.
- * - Arrays and objects with a single element/property are formatted inline.
- * - Larger arrays/objects are pretty-printed with optional indentation.
- * - Circular references are replaced with the literal `"[Circular]"`.
- *
- * **Options**:
- * - `space`: Indentation used when pretty-printing:
- *   - If a number, that many spaces will be used.
- *   - If a string, the string is used as the indentation unit (e.g. `"\t"`).
- *   - If `0`, empty string, or `undefined`, output is compact (no indentation).
- *   Defaults to `0`.
- * - `ignoreToString`: If `true`, the `toString` method is not called on the value.
- *   Defaults to `false`.
+ * When to use:
+ * - Pretty-printing values for debugging, logging, or error messages.
+ * - You need to handle `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`,
+ *   or class instances that `JSON.stringify` cannot represent.
+ * - You want circular references shown as `"[Circular]"` instead of
+ *   throwing.
+ *
+ * Behavior:
+ * - Does not mutate input.
+ * - Output is **not** valid JSON; use {@link formatJson} when you need
+ *   parseable JSON.
+ * - Primitives: stringified naturally (`null`, `undefined`, `123`, `true`).
+ *   Strings are JSON-quoted.
+ * - Objects with a custom `toString` (not `Object.prototype.toString`):
+ *   `toString()` is called unless `ignoreToString` is `true`.
+ * - Errors with a `cause`: formatted as `"<message> (cause: <cause>)"`.
+ * - Iterables (`Set`, `Map`, etc.): formatted as
+ *   `ClassName([...elements])`.
+ * - Class instances: wrapped as `ClassName({...})`.
+ * - `Redactable` values are automatically redacted.
+ * - Arrays/objects with 0–1 entries are inline; larger ones are
+ *   pretty-printed when `space` is set.
+ * - Circular references are replaced with `"[Circular]"`.
+ *
+ * Options:
+ * - `space` — indentation unit (number of spaces, or a string like
+ *   `"\t"`). Defaults to `0` (compact).
+ * - `ignoreToString` — skip calling `toString()`. Defaults to `false`.
+ *
+ * **Example** (Compact output)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.format({ a: 1, b: [2, 3] }))
+ * // {"a":1,"b":[2,3]}
+ * ```
+ *
+ * **Example** (Pretty-printed output)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.format({ a: 1, b: [2, 3] }, { space: 2 }))
+ * // {
+ * //   "a": 1,
+ * //   "b": [
+ * //     2,
+ * //     3
+ * //   ]
+ * // }
+ * ```
+ *
+ * **Example** (Circular reference handling)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * const obj: any = { name: "loop" }
+ * obj.self = obj
+ * console.log(Formatter.format(obj))
+ * // {"name":"loop","self":[Circular]}
+ * ```
+ *
+ * See also: {@link formatJson}, {@link Formatter}
  *
  * @since 4.0.0
  */
@@ -41,42 +105,62 @@ export declare function format(input: unknown, options?: {
     readonly ignoreToString?: boolean | undefined;
 }): string;
 /**
- * Safely stringifies objects that may contain circular references.
+ * Safely stringifies a value to JSON, silently dropping circular references.
+ *
+ * When to use:
+ * - You need valid JSON output (unlike {@link format}).
+ * - The input may contain circular references and you want them silently
+ *   omitted rather than throwing a `TypeError`.
  *
- * This function performs JSON.stringify with circular reference detection and handling.
- * It also applies redaction to sensitive values and provides a safe fallback for
- * any objects that can't be serialized normally.
+ * Behavior:
+ * - Does not mutate input.
+ * - Uses `JSON.stringify` internally with a replacer that tracks seen
+ *   objects.
+ * - Circular references are replaced with `undefined` (omitted from
+ *   output).
+ * - `Redactable` values are automatically redacted before serialization.
+ * - Types not supported by JSON (`BigInt`, `Symbol`, `undefined`,
+ *   functions) follow standard `JSON.stringify` behavior (omitted or
+ *   `null` in arrays).
  *
- * **Options**:
- * - `space`: Indentation used when pretty-printing:
- *   - If a number, that many spaces will be used.
- *   - If a string, the string is used as the indentation unit (e.g. `"\t"`).
- *   - If `0`, empty string, or `undefined`, output is compact (no indentation).
- *   Defaults to `0`.
+ * Options:
+ * - `space` — indentation unit (number of spaces, or a string like
+ *   `"\t"`). Defaults to `0` (compact).
+ *
+ * **Example** (Compact JSON)
  *
- * @example
  * ```ts
- * import { formatJson } from "effect/Formatter"
+ * import { Formatter } from "effect"
  *
- * // Normal object
- * const simple = { name: "Alice", age: 30 }
- * console.log(formatJson(simple))
+ * console.log(Formatter.formatJson({ name: "Alice", age: 30 }))
  * // {"name":"Alice","age":30}
+ * ```
+ *
+ * **Example** (Circular reference handling)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
  *
- * // Object with circular reference
- * const circular: any = { name: "test" }
- * circular.self = circular
- * console.log(formatJson(circular))
- * // {"name":"test"} (circular reference omitted)
+ * const obj: any = { name: "test" }
+ * obj.self = obj
+ * console.log(Formatter.formatJson(obj))
+ * // {"name":"test"}
+ * ```
+ *
+ * **Example** (Pretty-printed JSON)
  *
- * // With formatting
- * console.log(formatJson(simple, { space: 2 }))
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatJson({ name: "Alice", age: 30 }, { space: 2 }))
  * // {
  * //   "name": "Alice",
  * //   "age": 30
  * // }
  * ```
  *
+ * See also: {@link format}, {@link Formatter}
+ *
  * @since 4.0.0
  */
 export declare function formatJson(input: unknown, options?: {

package/dist/Formatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Formatter.d.ts","sourceRoot":"","sources":["../src/Formatter.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM;IACtD,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC9C,GAAG,MAAM,CAgFT;AA4CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC7C,GAAG,MAAM,CAcT"}
+{"version":3,"file":"Formatter.d.ts","sourceRoot":"","sources":["../src/Formatter.ts"],"names":[],"mappings":"AAyDA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM;IACtD,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC9C,GAAG,MAAM,CAgFT;AA+GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC7C,GAAG,MAAM,CAcT"}

package/dist/Formatter.js

@@ -1,4 +1,55 @@
 /**
+ * Utilities for converting arbitrary JavaScript values into human-readable
+ * strings, with support for circular references, redaction, and common JS
+ * types that `JSON.stringify` handles poorly.
+ *
+ * Mental model:
+ * - A `Formatter<Value, Format>` is a callable `(value: Value) => Format`.
+ * - {@link format} is the general-purpose pretty-printer: it handles
+ *   primitives, arrays, objects, `BigInt`, `Symbol`, `Date`, `RegExp`,
+ *   `Set`, `Map`, class instances, and circular references.
+ * - {@link formatJson} is a safe `JSON.stringify` wrapper that silently
+ *   drops circular references and applies redaction.
+ * - Both functions accept a `space` option for indentation control.
+ *
+ * Common tasks:
+ * - Pretty-print any value for debugging / logging -> {@link format}
+ * - Serialize to JSON safely (no circular throws) -> {@link formatJson}
+ * - Format a single object property key -> {@link formatPropertyKey}
+ * - Format a property path like `["a"]["b"]` -> {@link formatPath}
+ * - Format a `Date` to ISO string safely -> {@link formatDate}
+ *
+ * Gotchas:
+ * - {@link format} output is **not** valid JSON; use {@link formatJson} when
+ *   you need parseable JSON.
+ * - {@link format} calls `toString()` on objects by default; pass
+ *   `ignoreToString: true` to disable.
+ * - {@link formatJson} silently omits circular references (the key is
+ *   dropped from the output).
+ * - Values implementing the `Redactable` protocol are automatically
+ *   redacted by both {@link format} and {@link formatJson}.
+ *
+ * **Example** (Pretty-print a value)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * const obj = { name: "Alice", scores: [100, 97] }
+ * console.log(Formatter.format(obj))
+ * // {"name":"Alice","scores":[100,97]}
+ *
+ * console.log(Formatter.format(obj, { space: 2 }))
+ * // {
+ * //   "name": "Alice",
+ * //   "scores": [
+ * //     100,
+ * //     97
+ * //   ]
+ * // }
+ * ```
+ *
+ * See also: {@link Formatter}, {@link format}, {@link formatJson}
+ *
  * @since 4.0.0
  */
 import * as Predicate from "./Predicate.js";
@@ -6,31 +57,71 @@ import { getRedacted, redact, symbolRedactable } from "./Redactable.js";
 /**
  * Converts any JavaScript value into a human-readable string.
  *
- * For objects that don't have a `toString` method, it applies redaction to
- * protect sensitive information.
- *
- * Unlike `JSON.stringify`, this formatter:
- * - Handles circular references (printed as `"[Circular]"`).
- * - Supports additional types like `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`, and
- *   objects with custom `toString` methods.
- * - Includes constructor names for class instances (e.g. `MyClass({"a":1})`).
- * - Does not guarantee valid JSON output — the result is intended for debugging and inspection.
- *
- * Formatting rules:
- * - Primitives are stringified naturally (`null`, `undefined`, `123`, `"abc"`, `true`).
- * - Strings are JSON-quoted.
- * - Arrays and objects with a single element/property are formatted inline.
- * - Larger arrays/objects are pretty-printed with optional indentation.
- * - Circular references are replaced with the literal `"[Circular]"`.
- *
- * **Options**:
- * - `space`: Indentation used when pretty-printing:
- *   - If a number, that many spaces will be used.
- *   - If a string, the string is used as the indentation unit (e.g. `"\t"`).
- *   - If `0`, empty string, or `undefined`, output is compact (no indentation).
- *   Defaults to `0`.
- * - `ignoreToString`: If `true`, the `toString` method is not called on the value.
- *   Defaults to `false`.
+ * When to use:
+ * - Pretty-printing values for debugging, logging, or error messages.
+ * - You need to handle `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`,
+ *   or class instances that `JSON.stringify` cannot represent.
+ * - You want circular references shown as `"[Circular]"` instead of
+ *   throwing.
+ *
+ * Behavior:
+ * - Does not mutate input.
+ * - Output is **not** valid JSON; use {@link formatJson} when you need
+ *   parseable JSON.
+ * - Primitives: stringified naturally (`null`, `undefined`, `123`, `true`).
+ *   Strings are JSON-quoted.
+ * - Objects with a custom `toString` (not `Object.prototype.toString`):
+ *   `toString()` is called unless `ignoreToString` is `true`.
+ * - Errors with a `cause`: formatted as `"<message> (cause: <cause>)"`.
+ * - Iterables (`Set`, `Map`, etc.): formatted as
+ *   `ClassName([...elements])`.
+ * - Class instances: wrapped as `ClassName({...})`.
+ * - `Redactable` values are automatically redacted.
+ * - Arrays/objects with 0–1 entries are inline; larger ones are
+ *   pretty-printed when `space` is set.
+ * - Circular references are replaced with `"[Circular]"`.
+ *
+ * Options:
+ * - `space` — indentation unit (number of spaces, or a string like
+ *   `"\t"`). Defaults to `0` (compact).
+ * - `ignoreToString` — skip calling `toString()`. Defaults to `false`.
+ *
+ * **Example** (Compact output)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.format({ a: 1, b: [2, 3] }))
+ * // {"a":1,"b":[2,3]}
+ * ```
+ *
+ * **Example** (Pretty-printed output)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.format({ a: 1, b: [2, 3] }, { space: 2 }))
+ * // {
+ * //   "a": 1,
+ * //   "b": [
+ * //     2,
+ * //     3
+ * //   ]
+ * // }
+ * ```
+ *
+ * **Example** (Circular reference handling)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * const obj: any = { name: "loop" }
+ * obj.self = obj
+ * console.log(Formatter.format(obj))
+ * // {"name":"loop","self":[Circular]}
+ * ```
+ *
+ * See also: {@link formatJson}, {@link Formatter}
  *
  * @since 4.0.0
  */
@@ -69,7 +160,7 @@ export function format(input, options) {
     if (typeof v === "string") return JSON.stringify(v);
     if (typeof v === "number" || v == null || typeof v === "boolean" || typeof v === "symbol") return String(v);
     if (typeof v === "bigint") return String(v) + "n";
-    if (Predicate.isObject(v)) {
+    if (typeof v === "object" || typeof v === "function") {
       if (seen.has(v)) return CIRCULAR;
       seen.add(v);
       if (symbolRedactable in v) return format(getRedacted(v));
@@ -90,7 +181,29 @@ export function format(input, options) {
 }
 const CIRCULAR = "[Circular]";
 /**
- * Fast path for formatting property keys.
+ * Formats a single property key for display.
+ *
+ * When to use:
+ * - You are building a custom formatter that needs to render object keys.
+ *
+ * Behavior:
+ * - String keys are JSON-quoted (e.g. `"foo"`).
+ * - Symbol and number keys are converted with `String()`.
+ * - Pure function; does not mutate input.
+ *
+ * **Example** (Format property keys)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatPropertyKey("name"))
+ * // "name"
+ *
+ * console.log(Formatter.formatPropertyKey(Symbol.for("id")))
+ * // Symbol(id)
+ * ```
+ *
+ * See also: {@link formatPath}, {@link format}
  *
  * @internal
  */
@@ -98,7 +211,28 @@ export function formatPropertyKey(name) {
   return typeof name === "string" ? JSON.stringify(name) : String(name);
 }
 /**
- * Fast path for formatting property paths.
+ * Formats an array of property keys as a bracket-notation path string.
+ *
+ * When to use:
+ * - You need to display a path through a nested object (e.g. in error
+ *   messages or schema validation output).
+ *
+ * Behavior:
+ * - Each key is wrapped in brackets and formatted via
+ *   {@link formatPropertyKey}.
+ * - Returns an empty string for an empty path.
+ * - Pure function; does not mutate input.
+ *
+ * **Example** (Render a property path)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatPath(["users", 0, "name"]))
+ * // ["users"][0]["name"]
+ * ```
+ *
+ * See also: {@link formatPropertyKey}, {@link format}
  *
  * @internal
  */
@@ -106,7 +240,31 @@ export function formatPath(path) {
   return path.map(key => `[${formatPropertyKey(key)}]`).join("");
 }
 /**
- * Fast path for formatting dates.
+ * Formats a `Date` as an ISO 8601 string, returning `"Invalid Date"` for
+ * invalid dates instead of throwing.
+ *
+ * When to use:
+ * - You want a safe `toISOString()` that never throws.
+ *
+ * Behavior:
+ * - Returns `date.toISOString()` on success.
+ * - Returns `"Invalid Date"` if `toISOString()` throws (e.g. for
+ *   `new Date(NaN)`).
+ * - Pure function; does not mutate input.
+ *
+ * **Example** (Safe date formatting)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatDate(new Date("2024-01-15T10:30:00Z")))
+ * // 2024-01-15T10:30:00.000Z
+ *
+ * console.log(Formatter.formatDate(new Date("invalid")))
+ * // Invalid Date
+ * ```
+ *
+ * See also: {@link format}
  *
  * @internal
  */
@@ -126,42 +284,62 @@ function safeToString(input) {
   }
 }
 /**
- * Safely stringifies objects that may contain circular references.
+ * Safely stringifies a value to JSON, silently dropping circular references.
+ *
+ * When to use:
+ * - You need valid JSON output (unlike {@link format}).
+ * - The input may contain circular references and you want them silently
+ *   omitted rather than throwing a `TypeError`.
  *
- * This function performs JSON.stringify with circular reference detection and handling.
- * It also applies redaction to sensitive values and provides a safe fallback for
- * any objects that can't be serialized normally.
+ * Behavior:
+ * - Does not mutate input.
+ * - Uses `JSON.stringify` internally with a replacer that tracks seen
+ *   objects.
+ * - Circular references are replaced with `undefined` (omitted from
+ *   output).
+ * - `Redactable` values are automatically redacted before serialization.
+ * - Types not supported by JSON (`BigInt`, `Symbol`, `undefined`,
+ *   functions) follow standard `JSON.stringify` behavior (omitted or
+ *   `null` in arrays).
  *
- * **Options**:
- * - `space`: Indentation used when pretty-printing:
- *   - If a number, that many spaces will be used.
- *   - If a string, the string is used as the indentation unit (e.g. `"\t"`).
- *   - If `0`, empty string, or `undefined`, output is compact (no indentation).
- *   Defaults to `0`.
+ * Options:
+ * - `space` — indentation unit (number of spaces, or a string like
+ *   `"\t"`). Defaults to `0` (compact).
+ *
+ * **Example** (Compact JSON)
  *
- * @example
  * ```ts
- * import { formatJson } from "effect/Formatter"
+ * import { Formatter } from "effect"
  *
- * // Normal object
- * const simple = { name: "Alice", age: 30 }
- * console.log(formatJson(simple))
+ * console.log(Formatter.formatJson({ name: "Alice", age: 30 }))
  * // {"name":"Alice","age":30}
+ * ```
  *
- * // Object with circular reference
- * const circular: any = { name: "test" }
- * circular.self = circular
- * console.log(formatJson(circular))
- * // {"name":"test"} (circular reference omitted)
+ * **Example** (Circular reference handling)
  *
- * // With formatting
- * console.log(formatJson(simple, { space: 2 }))
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * const obj: any = { name: "test" }
+ * obj.self = obj
+ * console.log(Formatter.formatJson(obj))
+ * // {"name":"test"}
+ * ```
+ *
+ * **Example** (Pretty-printed JSON)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatJson({ name: "Alice", age: 30 }, { space: 2 }))
  * // {
  * //   "name": "Alice",
  * //   "age": 30
  * // }
  * ```
  *
+ * See also: {@link format}, {@link Formatter}
+ *
  * @since 4.0.0
  */
 export function formatJson(input, options) {