effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/Filter.ts

@@ -28,14 +28,14 @@ import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tag
  *
  * **Example** (Defining a positive number filter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Filter, Result } from "effect"
  *
  * // A filter that only passes positive numbers
  * const positiveFilter: Filter.Filter<number> = (n) => n > 0 ? Result.succeed(n) : Result.fail(n)
  *
- * console.log(positiveFilter(5)) // Result.succeed(5)
- * console.log(positiveFilter(-3)) // Result.fail(-3)
+ * positiveFilter(5) // => Result.succeed(5)
+ * positiveFilter(-3) // => Result.fail(-3)
  * ```
  *
  * @category models
@@ -56,7 +56,7 @@ export interface Filter<in Input, out Pass = Input, out Fail = Input> {
  *
  * **Example** (Defining an effectful user filter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Filter, Result } from "effect"
  *
  * // An effectful filter that validates user data
@@ -74,6 +74,9 @@ export interface Filter<in Input, out Pass = Input, out Fail = Input> {
  *     const user: User = { id, isActive: id.length > 0 }
  *     return user.isActive ? Result.succeed(user) : Result.fail(user)
  *   })
+ *
+ * await Effect.runPromise(validateUser("alice")) // => Result.succeed({ id: "alice", isActive: true })
+ * await Effect.runPromise(validateUser("")) // => Result.fail({ id: "", isActive: false })
  * ```
  *
  * @category models
@@ -103,7 +106,7 @@ export interface FilterEffect<
  *
  * **Example** (Creating custom filters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Filter, Result } from "effect"
  *
  * // Create a filter for positive numbers
@@ -113,6 +116,8 @@ export interface FilterEffect<
  * const uppercaseFilter = Filter.make((s: string) =>
  *   s.length > 0 ? Result.succeed(s.toUpperCase()) : Result.fail(s)
  * )
+ * positiveFilter(1) // => Result.succeed(1)
+ * uppercaseFilter("ok") // => Result.succeed("OK")
  * ```
  *
  * @category constructors
@@ -133,7 +138,7 @@ export const make = <Input, Pass, Fail>(
  *
  * **Example** (Creating effectful filters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Filter, Result } from "effect"
  *
  * // Create an effectful filter that validates async
@@ -143,6 +148,8 @@ export const make = <Input, Pass, Fail>(
  *     return isValid ? Result.succeed(id) : Result.fail(id)
  *   })
  * )
+ *
+ * await Effect.runPromise(asyncValidate("id")) // => Result.succeed("id")
  * ```
  *
  * @category constructors
@@ -212,7 +219,7 @@ export {
  *
  * **Example** (Creating filters from predicates)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Filter, Result } from "effect"
  *
  * // Create filter from predicate
@@ -223,6 +230,9 @@ export {
  * const isString = Filter.fromPredicate((x: unknown): x is string =>
  *   typeof x === "string"
  * )
+ * positiveNumbers(1) // => Result.succeed(1)
+ * nonEmptyStrings("") // => Result.fail("")
+ * isString("ok") // => Result.succeed("ok")
  * ```
  *
  * @category constructors
@@ -240,7 +250,7 @@ export const fromPredicate: {
    *
    * **Example** (Creating filters from predicates)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Filter, Result } from "effect"
    *
    * // Create filter from predicate
@@ -251,6 +261,9 @@ export const fromPredicate: {
    * const isString = Filter.fromPredicate((x: unknown): x is string =>
    *   typeof x === "string"
    * )
+   * positiveNumbers(1) // => Result.succeed(1)
+   * nonEmptyStrings("") // => Result.fail("")
+   * isString("ok") // => Result.succeed("ok")
    * ```
    *
    * @category constructors
@@ -268,7 +281,7 @@ export const fromPredicate: {
    *
    * **Example** (Creating filters from predicates)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Filter, Result } from "effect"
    *
    * // Create filter from predicate
@@ -279,6 +292,9 @@ export const fromPredicate: {
    * const isString = Filter.fromPredicate((x: unknown): x is string =>
    *   typeof x === "string"
    * )
+   * positiveNumbers(1) // => Result.succeed(1)
+   * nonEmptyStrings("") // => Result.fail("")
+   * isString("ok") // => Result.succeed("ok")
    * ```
    *
    * @category constructors
@@ -324,11 +340,11 @@ export const toPredicate = <A, Pass, Fail>(
  *
  * **Example** (Filtering strings)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Filter, Result } from "effect"
  *
- * console.log(Filter.string("hello")) // Result.succeed("hello")
- * console.log(Filter.string(42)) // fail
+ * Filter.string("hello") // => Result.succeed("hello")
+ * Filter.string(42) // => Result.fail(42)
  * ```
  *
  * @category constructors
@@ -415,11 +431,11 @@ export const instanceOf =
  *
  * **Example** (Filtering numbers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Filter, Result } from "effect"
  *
- * console.log(Filter.number(42)) // Result.succeed(42)
- * console.log(Filter.number("42")) // fail
+ * Filter.number(42) // => Result.succeed(42)
+ * Filter.number("42") // => Result.fail("42")
  * ```
  *
  * @category constructors
@@ -800,13 +816,14 @@ export const zipWith: {
  *
  * **Example** (Zipping filters)
  *
- * ```ts
- * import { Filter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Filter, Result } from "effect"
  *
  * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
  * const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)
  *
  * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
+ * positiveAndEven(2) // => Result.succeed([2, 2])
  * ```
  *
  * @category combinators
@@ -823,13 +840,14 @@ export const zip: {
    *
    * **Example** (Zipping filters)
    *
-   * ```ts
-   * import { Filter } from "effect"
+   * ```ts import.meta.vitest
+   * import { Filter, Result } from "effect"
    *
    * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
    * const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)
    *
    * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
+   * positiveAndEven(2) // => Result.succeed([2, 2])
    * ```
    *
    * @category combinators
@@ -848,13 +866,14 @@ export const zip: {
    *
    * **Example** (Zipping filters)
    *
-   * ```ts
-   * import { Filter } from "effect"
+   * ```ts import.meta.vitest
+   * import { Filter, Result } from "effect"
    *
    * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
    * const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)
    *
    * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
+   * positiveAndEven(2) // => Result.succeed([2, 2])
    * ```
    *
    * @category combinators
@@ -872,13 +891,14 @@ export const zip: {
  *
  * **Example** (Keeping the left filter result)
  *
- * ```ts
- * import { Filter } from "effect"
+ * ```ts import.meta.vitest
+ * import { Filter, Result } from "effect"
  *
  * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
  * const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)
  *
  * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
+ * positiveEven(2) // => Result.succeed(2)
  * ```
  *
  * @category combinators
@@ -890,13 +910,14 @@ export const andLeft: {
    *
    * **Example** (Keeping the left filter result)
    *
-   * ```ts
-   * import { Filter } from "effect"
+   * ```ts import.meta.vitest
+   * import { Filter, Result } from "effect"
    *
    * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
    * const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)
    *
    * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
+   * positiveEven(2) // => Result.succeed(2)
    * ```
    *
    * @category combinators
@@ -910,13 +931,14 @@ export const andLeft: {
    *
    * **Example** (Keeping the left filter result)
    *
-   * ```ts
-   * import { Filter } from "effect"
+   * ```ts import.meta.vitest
+   * import { Filter, Result } from "effect"
    *
    * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
    * const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)
    *
    * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
+   * positiveEven(2) // => Result.succeed(2)
    * ```
    *
    * @category combinators
@@ -933,7 +955,7 @@ export const andLeft: {
  *
  * **Example** (Keeping the right filter result)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Filter, Result } from "effect"
  *
  * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
@@ -942,6 +964,7 @@ export const andLeft: {
  * )
  *
  * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
+ * positiveDoubled(2) // => Result.succeed(4)
  * ```
  *
  * @category combinators
@@ -953,7 +976,7 @@ export const andRight: {
    *
    * **Example** (Keeping the right filter result)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Filter, Result } from "effect"
    *
    * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
@@ -962,6 +985,7 @@ export const andRight: {
    * )
    *
    * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
+   * positiveDoubled(2) // => Result.succeed(4)
    * ```
    *
    * @category combinators
@@ -975,7 +999,7 @@ export const andRight: {
    *
    * **Example** (Keeping the right filter result)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Filter, Result } from "effect"
    *
    * const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
@@ -984,6 +1008,7 @@ export const andRight: {
    * )
    *
    * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
+   * positiveDoubled(2) // => Result.succeed(4)
    * ```
    *
    * @category combinators
@@ -1000,7 +1025,7 @@ export const andRight: {
  *
  * **Example** (Composing filters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Filter, Result } from "effect"
  *
  * const stringFilter = Filter.string
@@ -1009,6 +1034,7 @@ export const andRight: {
  * )
  *
  * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
+ * stringToUpper("hello") // => Result.succeed("HELLO")
  * ```
  *
  * @category combinators
@@ -1020,7 +1046,7 @@ export const compose: {
    *
    * **Example** (Composing filters)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Filter, Result } from "effect"
    *
    * const stringFilter = Filter.string
@@ -1029,6 +1055,7 @@ export const compose: {
    * )
    *
    * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
+   * stringToUpper("hello") // => Result.succeed("HELLO")
    * ```
    *
    * @category combinators
@@ -1040,7 +1067,7 @@ export const compose: {
    *
    * **Example** (Composing filters)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Filter, Result } from "effect"
    *
    * const stringFilter = Filter.string
@@ -1049,6 +1076,7 @@ export const compose: {
    * )
    *
    * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
+   * stringToUpper("hello") // => Result.succeed("HELLO")
    * ```
    *
    * @category combinators

package/src/Formatter.ts

@@ -25,13 +25,12 @@ import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
  *
  * **Example** (Defining a custom formatter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Formatter } from "effect"
  *
  * const upper: Formatter.Formatter<string> = (s) => s.toUpperCase()
  *
- * console.log(upper("hello"))
- * // HELLO
+ * upper("hello") // => "HELLO"
  * ```
  *
  * @see {@link format}
@@ -75,37 +74,29 @@ export interface Formatter<in Value, out Format = string> {
  *
  * **Example** (Formatting compact output)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Formatter } from "effect"
  *
- * console.log(Formatter.format({ a: 1, b: [2, 3] }))
- * // {"a":1,"b":[2,3]}
+ * Formatter.format({ a: 1, b: [2, 3] }) // => "{\"a\":1,\"b\":[2,3]}"
  * ```
  *
  * **Example** (Pretty-printed output)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Formatter } from "effect"
  *
- * console.log(Formatter.format({ a: 1, b: [2, 3] }, { space: 2 }))
- * // {
- * //   "a": 1,
- * //   "b": [
- * //     2,
- * //     3
- * //   ]
- * // }
+ * const output = Formatter.format({ a: 1, b: [2, 3] }, { space: 2 })
+ * output // => "{\n  \"a\": 1,\n  \"b\": [\n    2,\n    3\n  ]\n}"
  * ```
  *
  * **Example** (Handling circular references)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Formatter } from "effect"
  *
  * const obj: any = { name: "loop" }
  * obj.self = obj
- * console.log(Formatter.format(obj))
- * // {"name":"loop","self":[Circular]}
+ * Formatter.format(obj) // => "{\"name\":\"loop\",\"self\":[Circular]}"
  * ```
  *
  * @see {@link formatJson}
@@ -118,7 +109,7 @@ export function format(input: unknown, options?: {
   readonly ignoreToString?: boolean | undefined
 }): string {
   const space = options?.space ?? 0
-  const seen = new WeakSet<object>()
+  const ancestors = new WeakSet<object>()
   const gap = !space ? "" : (typeof space === "number" ? " ".repeat(space) : space)
   const ind = (d: number) => gap.repeat(d)
 
@@ -137,11 +128,13 @@ export function format(input: unknown, options?: {
 
   function recur(v: unknown, d = 0): string {
     if (Array.isArray(v)) {
-      if (seen.has(v)) return CIRCULAR
-      seen.add(v)
-      if (!gap || v.length <= 1) return `[${v.map((x) => recur(x, d)).join(",")}]`
-      const inner = v.map((x) => recur(x, d + 1)).join(",\n" + ind(d + 1))
-      return `[\n${ind(d + 1)}${inner}\n${ind(d)}]`
+      if (ancestors.has(v)) return CIRCULAR
+      ancestors.add(v)
+      const output = !gap || v.length <= 1
+        ? `[${v.map((x) => recur(x, d)).join(",")}]`
+        : `[\n${ind(d + 1)}${v.map((x) => recur(x, d + 1)).join(",\n" + ind(d + 1))}\n${ind(d)}]`
+      ancestors.delete(v)
+      return output
     }
 
     if (v instanceof Date) return formatDate(v)
@@ -172,24 +165,28 @@ export function format(input: unknown, options?: {
     if (typeof v === "bigint") return String(v) + "n"
 
     if (typeof v === "object" || typeof v === "function") {
-      if (seen.has(v)) return CIRCULAR
-      seen.add(v)
+      if (ancestors.has(v)) return CIRCULAR
+      ancestors.add(v)
 
-      if (symbolRedactable in v) return format(getRedacted(v as any))
-
-      if (Symbol.iterator in v) {
-        return `${v.constructor.name}(${recur(Array.from(v as any), d)})`
-      }
-
-      const keys = ownKeys(v)
-      if (!gap || keys.length <= 1) {
-        const body = `{${keys.map((k) => `${formatPropertyKey(k)}:${recur((v as any)[k], d)}`).join(",")}}`
-        return wrap(v, body)
+      let output: string
+      if (symbolRedactable in v) {
+        output = format(getRedacted(v as any))
+      } else if (Symbol.iterator in v) {
+        output = `${v.constructor.name}(${recur(Array.from(v as any), d)})`
+      } else {
+        const keys = ownKeys(v)
+        if (!gap || keys.length <= 1) {
+          const body = `{${keys.map((k) => `${formatPropertyKey(k)}:${recur((v as any)[k], d)}`).join(",")}}`
+          output = wrap(v, body)
+        } else {
+          const body = `{\n${
+            keys.map((k) => `${ind(d + 1)}${formatPropertyKey(k)}: ${recur((v as any)[k], d + 1)}`).join(",\n")
+          }\n${ind(d)}}`
+          output = wrap(v, body)
+        }
       }
-      const body = `{\n${
-        keys.map((k) => `${ind(d + 1)}${formatPropertyKey(k)}: ${recur((v as any)[k], d + 1)}`).join(",\n")
-      }\n${ind(d)}}`
-      return wrap(v, body)
+      ancestors.delete(v)
+      return output
     }
 
     return String(v)
@@ -253,40 +250,41 @@ function safeToString(input: any): string {
  * Uses `JSON.stringify` internally with a replacer that tracks the current
  * object ancestry. Circular references are replaced with `undefined`, which
  * omits them from object output. `Redactable` values are automatically redacted
- * before serialization. Values not supported by JSON, such as `BigInt`,
- * `Symbol`, `undefined`, and functions, follow standard `JSON.stringify`
- * behavior. The `space` parameter controls indentation and defaults to `0`.
+ * before serialization. Values not supported by JSON otherwise follow standard
+ * `JSON.stringify` behavior. The `space` parameter controls indentation and
+ * defaults to `0`.
+ *
+ * **Gotchas**
+ *
+ * When the root input is `undefined`, a symbol, or a function, `formatJson`
+ * returns `"null"` instead of the `undefined` returned by `JSON.stringify`.
+ * Nested values retain standard `JSON.stringify` behavior.
  *
  * **Example** (Formatting compact JSON)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Formatter } from "effect"
  *
- * console.log(Formatter.formatJson({ name: "Alice", age: 30 }))
- * // {"name":"Alice","age":30}
+ * Formatter.formatJson({ name: "Alice", age: 30 }) // => "{\"name\":\"Alice\",\"age\":30}"
  * ```
  *
  * **Example** (Handling circular references)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Formatter } from "effect"
  *
  * const obj: any = { name: "test" }
  * obj.self = obj
- * console.log(Formatter.formatJson(obj))
- * // {"name":"test"}
+ * Formatter.formatJson(obj) // => "{\"name\":\"test\"}"
  * ```
  *
  * **Example** (Pretty-printed JSON)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Formatter } from "effect"
  *
- * console.log(Formatter.formatJson({ name: "Alice", age: 30 }, { space: 2 }))
- * // {
- * //   "name": "Alice",
- * //   "age": 30
- * // }
+ * const output = Formatter.formatJson({ name: "Alice", age: 30 }, { space: 2 })
+ * output // => "{\n  \"name\": \"Alice\",\n  \"age\": 30\n}"
  * ```
  *
  * @see {@link format}
@@ -315,5 +313,5 @@ export function formatJson(input: unknown, options?: {
       return redacted
     },
     options?.space
-  )
+  ) ?? "null"
 }