effect 4.0.1 → 4.0.3

package/src/Filter.ts

@@ -8,6 +8,7 @@
  * filters for common JavaScript values and tags, helpers for combining filters,
  * and conversions to predicates, options, and results.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import type { Effect } from "./Effect.ts"
@@ -38,6 +39,7 @@ import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tag
  * positiveFilter(-3) // => Result.fail(-3)
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -79,6 +81,7 @@ export interface Filter<in Input, out Pass = Input, out Fail = Input> {
  * await Effect.runPromise(validateUser("")) // => Result.fail({ id: "", isActive: false })
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -120,6 +123,7 @@ export interface FilterEffect<
  * uppercaseFilter("ok") // => Result.succeed("OK")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -152,6 +156,7 @@ export const make = <Input, Pass, Fail>(
  * await Effect.runPromise(asyncValidate("id")) // => Result.succeed("id")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -163,6 +168,7 @@ export const makeEffect = <Input, Pass, Fail, E, R>(
  * Transforms the failure value produced by a `Filter`, leaving successful
  * results unchanged.
  *
+ * @stability stable
  * @category mapping
  * @since 4.0.0
  */
@@ -171,6 +177,7 @@ export const mapFail: {
    * Transforms the failure value produced by a `Filter`, leaving successful
    * results unchanged.
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -179,6 +186,7 @@ export const mapFail: {
    * Transforms the failure value produced by a `Filter`, leaving successful
    * results unchanged.
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -202,6 +210,7 @@ export {
    * Creates a Filter that tries to apply a function and returns `fail` on
    * error.
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -235,6 +244,7 @@ export {
  * isString("ok") // => Result.succeed("ok")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -266,6 +276,7 @@ export const fromPredicate: {
    * isString("ok") // => Result.succeed("ok")
    * ```
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -297,6 +308,7 @@ export const fromPredicate: {
    * isString("ok") // => Result.succeed("ok")
    * ```
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -308,6 +320,7 @@ export const fromPredicate: {
  * Creates a `Filter` from a function that returns an `Option`; `Some(value)`
  * passes with `value`, and `None` fails with the original input.
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -327,6 +340,7 @@ export const fromPredicateOption = <A, B>(predicate: (a: A) => Option.Option<B>)
  * @see {@link toOption} for keeping passed values and discarding failure values
  * @see {@link toResult} for preserving both pass and failure values
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -347,6 +361,7 @@ export const toPredicate = <A, Pass, Fail>(
  * Filter.string(42) // => Result.fail(42)
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -370,6 +385,7 @@ export const string: Filter<unknown, string> = fromPredicate(Predicate.isString)
  * @see {@link equals} for structural equality when distinct values with equal
  * contents should pass
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -391,6 +407,7 @@ export const equalsStrict =
  * @see {@link Predicate.hasProperty} for guarding property presence instead of
  * calling an input's `has` method
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -418,6 +435,7 @@ export const has =
  *
  * @see {@link fromPredicate} for custom predicate-based narrowing
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -438,6 +456,7 @@ export const instanceOf =
  * Filter.number("42") // => Result.fail("42")
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -459,6 +478,7 @@ export const number: Filter<unknown, number> = fromPredicate(Predicate.isNumber)
  * @see {@link Predicate.isBoolean} for the underlying guard
  * @see {@link fromPredicate} for custom predicate-based filters
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -485,6 +505,7 @@ export const boolean: Filter<unknown, boolean> = fromPredicate(Predicate.isBoole
  * @see {@link number} for JavaScript `number` values
  * @see {@link Predicate.isBigInt} for the underlying guard
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -493,6 +514,7 @@ export const bigint: Filter<unknown, bigint> = fromPredicate(Predicate.isBigInt)
 /**
  * A predefined filter that only passes through Symbol values.
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -520,6 +542,7 @@ export const symbol: Filter<unknown, symbol> = fromPredicate(Predicate.isSymbol)
  * @see {@link instanceOf} for constructor-based filtering
  * @see {@link fromPredicate} for custom date checks
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -546,6 +569,7 @@ export const date: Filter<unknown, Date> = fromPredicate(Predicate.isDate)
  * `Filter` result is not needed
  * @see {@link reason} for extracting a nested reason variant from tagged errors
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -571,6 +595,7 @@ export const tagged: {
    * `Filter` result is not needed
    * @see {@link reason} for extracting a nested reason variant from tagged errors
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -596,6 +621,7 @@ export const tagged: {
    * `Filter` result is not needed
    * @see {@link reason} for extracting a nested reason variant from tagged errors
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -621,6 +647,7 @@ export const tagged: {
    * `Filter` result is not needed
    * @see {@link reason} for extracting a nested reason variant from tagged errors
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -637,6 +664,7 @@ const taggedImpl =
 /**
  * Creates a filter that extracts a reason from a tagged error.
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -644,6 +672,7 @@ export const reason: {
   /**
    * Creates a filter that extracts a reason from a tagged error.
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -654,6 +683,7 @@ export const reason: {
   /**
    * Creates a filter that extracts a reason from a tagged error.
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -661,6 +691,7 @@ export const reason: {
   /**
    * Creates a filter that extracts a reason from a tagged error.
    *
+   * @stability stable
    * @category constructors
    * @since 4.0.0
    */
@@ -698,6 +729,7 @@ const reasonImpl =
  * equality
  * @see {@link Equal.equals} for the underlying structural equality semantics
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -708,6 +740,7 @@ export const equals =
 /**
  * Combines two filters with logical OR semantics.
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -715,6 +748,7 @@ export const or: {
   /**
    * Combines two filters with logical OR semantics.
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -722,6 +756,7 @@ export const or: {
   /**
    * Combines two filters with logical OR semantics.
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -749,6 +784,7 @@ export const or: {
  *
  * @see {@link zip} for combining two filters into a tuple
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -767,6 +803,7 @@ export const zipWith: {
    *
    * @see {@link zip} for combining two filters into a tuple
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -785,6 +822,7 @@ export const zipWith: {
    *
    * @see {@link zip} for combining two filters into a tuple
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -826,6 +864,7 @@ export const zipWith: {
  * positiveAndEven(2) // => Result.succeed([2, 2])
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -850,6 +889,7 @@ export const zip: {
    * positiveAndEven(2) // => Result.succeed([2, 2])
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -876,6 +916,7 @@ export const zip: {
    * positiveAndEven(2) // => Result.succeed([2, 2])
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -901,6 +942,7 @@ export const zip: {
  * positiveEven(2) // => Result.succeed(2)
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -920,6 +962,7 @@ export const andLeft: {
    * positiveEven(2) // => Result.succeed(2)
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -941,6 +984,7 @@ export const andLeft: {
    * positiveEven(2) // => Result.succeed(2)
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -967,6 +1011,7 @@ export const andLeft: {
  * positiveDoubled(2) // => Result.succeed(4)
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -988,6 +1033,7 @@ export const andRight: {
    * positiveDoubled(2) // => Result.succeed(4)
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1011,6 +1057,7 @@ export const andRight: {
    * positiveDoubled(2) // => Result.succeed(4)
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1037,6 +1084,7 @@ export const andRight: {
  * stringToUpper("hello") // => Result.succeed("HELLO")
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1058,6 +1106,7 @@ export const compose: {
    * stringToUpper("hello") // => Result.succeed("HELLO")
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1079,6 +1128,7 @@ export const compose: {
    * stringToUpper("hello") // => Result.succeed("HELLO")
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1102,6 +1152,7 @@ export const compose: {
  * If either filter fails, the returned filter fails with the original input
  * instead of the intermediate failure value.
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1115,6 +1166,7 @@ export const composePassthrough: {
    * If either filter fails, the returned filter fails with the original input
    * instead of the intermediate failure value.
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1128,6 +1180,7 @@ export const composePassthrough: {
    * If either filter fails, the returned filter fails with the original input
    * instead of the intermediate failure value.
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1156,6 +1209,7 @@ export const composePassthrough: {
  * @see {@link toResult} for keeping the filter failure value
  * @see {@link toPredicate} for plain boolean pass/fail checks
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -1179,6 +1233,7 @@ export const toOption = <A, Pass, Fail>(
  * @see {@link toOption} for keeping only passed values
  * @see {@link toPredicate} for plain boolean pass/fail checks
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */

package/src/Formatter.ts

@@ -7,6 +7,7 @@
  * wraps JSON formatting with redaction and circular-reference handling, and the
  * module also includes helpers for property keys, paths, and dates.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Predicate from "./Predicate.ts"
@@ -35,6 +36,7 @@ import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
  *
  * @see {@link format}
  * @see {@link formatJson}
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -102,6 +104,7 @@ export interface Formatter<in Value, out Format = string> {
  *
  * @see {@link formatJson}
  * @see {@link Formatter}
+ * @stability stable
  * @category formatting
  * @since 2.0.0
  */
@@ -298,6 +301,7 @@ function safeGet(input: object, key: PropertyKey): unknown {
  *
  * @see {@link format}
  * @see {@link Formatter}
+ * @stability stable
  * @category serialization
  * @since 4.0.0
  */
@@ -331,8 +335,45 @@ export function formatJson(input: unknown, options?: {
       if (current !== redacted) {
         ancestors.push(current)
       }
-      return current
+      // Leave boxed primitives intact so JSON.stringify can unbox them natively.
+      if (!hasGetter(current) || isJsonPrimitiveWrapper(current)) {
+        return current
+      }
+      // JSON.stringify reads a getter once, then calls toJSON on the result
+      // before the replacer sees it. Intercept that read to redact the value
+      // first, instead of re-reading the getter in the replacer, which could
+      // repeat side effects or return a different value.
+      const serialized = new Proxy(current, {
+        get(target, key) {
+          const value = Reflect.get(target, key, target)
+          return Object.getOwnPropertyDescriptor(target, key)?.get !== undefined ? redact(value) : value
+        }
+      })
+      ancestors.push(serialized)
+      return serialized
     },
     options?.space
   ) ?? "null"
 }
+
+function hasGetter(object: object): boolean {
+  for (const key of Object.getOwnPropertyNames(object)) {
+    if (Object.getOwnPropertyDescriptor(object, key)?.get !== undefined) {
+      return true
+    }
+  }
+  return false
+}
+
+function isJsonPrimitiveWrapper(object: object): boolean {
+  // Built-in valueOf checks internal slots across realms without calling user code.
+  for (const valueOf of [Number.prototype.valueOf, Boolean.prototype.valueOf, String.prototype.valueOf]) {
+    try {
+      Reflect.apply(valueOf, object, [])
+      return true
+    } catch {
+      // Try the next wrapper type.
+    }
+  }
+  return false
+}

package/src/Function.ts

@@ -6,6 +6,7 @@
  * module also contains small identity, constant, tuple, type-level, and
  * memoization helpers used across the library.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import type { TypeLambda } from "./HKT.ts"
@@ -29,6 +30,7 @@ import { pipeArguments } from "./Pipeable.ts"
  * // Equivalent to: (a: string) => number
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -96,6 +98,7 @@ export interface FunctionTypeLambda extends TypeLambda {
  * pipe(2, sum(3)) // => 5
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -160,6 +163,7 @@ export const dual: {
    * pipe(2, sum(3)) // => 5
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -224,6 +228,7 @@ export const dual: {
    * pipe(2, sum(3)) // => 5
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -297,6 +302,7 @@ export const dual: {
  *
  * @see {@link pipe} for building left-to-right pipelines
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -318,6 +324,7 @@ export const apply = <A>(a: A) => <B>(self: (a: A) => B): B => self(a)
  * constNull() // => null
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -340,6 +347,7 @@ export type LazyArg<A> = () => A
  * sum(2, 3) // => 5
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -360,6 +368,7 @@ export type FunctionN<A extends ReadonlyArray<unknown>, B> = (...args: A) => B
  * identity(5) // => 5
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -388,6 +397,7 @@ export const identity = <A>(a: A): A => a
  *
  * @see {@link cast} for changing only the static TypeScript type
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -408,6 +418,7 @@ export const satisfies = <A>() => <B extends A>(b: B) => b
  *
  * @see {@link satisfies} for checking assignability without changing the resulting type
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -432,6 +443,7 @@ export const cast: <A, B>(a: A) => B = identity as any
  * constNull() // => null
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -452,6 +464,7 @@ export const constant = <A>(value: A): LazyArg<A> => () => value
  * Function.constTrue() // => true
  * ```
  *
+ * @stability stable
  * @category constants
  * @since 2.0.0
  */
@@ -472,6 +485,7 @@ export const constTrue: LazyArg<boolean> = constant(true)
  * Function.constFalse() // => false
  * ```
  *
+ * @stability stable
  * @category constants
  * @since 2.0.0
  */
@@ -492,6 +506,7 @@ export const constFalse: LazyArg<boolean> = constant(false)
  * Function.constNull() // => null
  * ```
  *
+ * @stability stable
  * @category constants
  * @since 2.0.0
  */
@@ -512,6 +527,7 @@ export const constNull: LazyArg<null> = constant(null)
  * Function.constUndefined() // => undefined
  * ```
  *
+ * @stability stable
  * @category constants
  * @since 2.0.0
  */
@@ -533,6 +549,7 @@ export const constUndefined: LazyArg<undefined> = constant(undefined)
  * Function.constVoid() // => undefined
  * ```
  *
+ * @stability stable
  * @category constants
  * @since 2.0.0
  */
@@ -556,6 +573,7 @@ export const constVoid: LazyArg<void> = constUndefined
  * Function.flip(f)("aaa")(2) // => -1
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -587,6 +605,7 @@ export const flip = <A extends Array<unknown>, B extends Array<unknown>, C>(
  * @see {@link flow} for composing a left-to-right sequence of functions
  * @see {@link pipe} for applying a value through a left-to-right sequence immediately
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -613,6 +632,7 @@ export const compose: {
    * @see {@link flow} for composing a left-to-right sequence of functions
    * @see {@link pipe} for applying a value through a left-to-right sequence immediately
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -639,6 +659,7 @@ export const compose: {
    * @see {@link flow} for composing a left-to-right sequence of functions
    * @see {@link pipe} for applying a value through a left-to-right sequence immediately
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -669,6 +690,7 @@ export const compose: {
  * }
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -695,6 +717,7 @@ export const absurd = <A>(_: never): A => {
  *
  * @see {@link untupled} for adapting a tuple-argument function back to multiple arguments
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -719,6 +742,7 @@ export const tupled = <A extends ReadonlyArray<unknown>, B>(f: (...a: A) => B):
  *
  * @see {@link tupled} for adapting a multi-argument function to one tuple argument
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -777,6 +801,7 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * ) // => [6, 8]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1261,6 +1286,7 @@ export function pipe(a: unknown, ...args: Array<any>): unknown {
  * @see {@link pipe} for applying a value through a left-to-right sequence immediately
  * @see {@link compose} for composing exactly two functions
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1454,6 +1480,7 @@ export function flow(
  *
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -1476,6 +1503,7 @@ export const hole: <T>() => T = cast(absurd)
  * Function.SK(0, "hello") // => "hello"
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1503,6 +1531,7 @@ export const SK = <A, B>(_: A, b: B): B => b
  * mutated after its first call, later calls still return the cached result for
  * that reference.
  *
+ * @stability stable
  * @category caching
  * @since 4.0.0
  */
@@ -1539,6 +1568,7 @@ export function memoize<A extends object, O extends {} | null>(f: (a: A) => O):
  * different value, this memoization changes that behavior.
  *
  * @see {@link memoize} for memoizing functions without an idempotence requirement
+ * @stability stable
  * @category caching
  * @since 4.0.0
  */