effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Redactable.js

@@ -1,12 +1,12 @@
 import { pipeArguments } from "./Pipeable.js";
 import { hasProperty } from "./Predicate.js";
 /**
- * Symbol used to identify objects that implement the {@link Redactable}
+ * Defines the symbol used to identify objects that implement the {@link Redactable}
  * protocol.
  *
  * **When to use**
  *
- * Use this symbol as the property key when implementing {@link Redactable}.
+ * Use as the property key when implementing the `Redactable` protocol.
  *
  * **Details**
  *
@@ -29,9 +29,9 @@ import { hasProperty } from "./Predicate.js";
  * }
  * ```
  *
- * @see {@link Redactable} - the interface this symbol belongs to
- * @see {@link isRedactable} - check whether a value has this symbol
- * @category symbol
+ * @see {@link Redactable} for the interface this symbol belongs to
+ * @see {@link isRedactable} to check whether a value has this symbol
+ * @category symbols
  * @since 3.10.0
  */
 export const symbolRedactable = /*#__PURE__*/Symbol.for("~effect/Redactable");
@@ -39,33 +39,37 @@ export const symbolRedactable = /*#__PURE__*/Symbol.for("~effect/Redactable");
  * Type guard that checks whether a value implements the {@link Redactable}
  * interface.
  *
- * @see {@link Redactable} - the interface being checked
- * @see {@link redact} - applies redaction if the value is redactable
+ * **When to use**
+ *
+ * Use to narrow an unknown value before calling redaction-specific helpers.
+ *
+ * @see {@link Redactable} for the interface being checked
+ * @see {@link redact} to apply redaction if the value is redactable
  * @category guards
  * @since 3.10.0
  */
 export const isRedactable = u => hasProperty(u, symbolRedactable);
 /**
- * Redacts a value if it implements {@link Redactable}, otherwise returns it
+ * Returns a redacted value if it implements {@link Redactable}, otherwise returns it
  * unchanged.
  *
  * **When to use**
  *
- * Use this as the general-purpose entry point for redaction when the input may
+ * Use as the general-purpose entry point for redaction when the input may
  * or may not implement the redaction protocol.
  *
  * **Details**
  *
  * This function calls {@link isRedactable} and, when it returns `true`,
- * delegates to {@link getRedacted}. It does not mutate the input.
+ * delegates to {@link getRedacted}.
  *
  * **Gotchas**
  *
  * Redaction is not recursive. Nested redactable values inside the returned
  * object are not automatically redacted.
  *
- * @see {@link isRedactable} - check before redacting
- * @see {@link getRedacted} - lower-level variant for known redactables
+ * @see {@link isRedactable} to check before redacting
+ * @see {@link getRedacted} for the lower-level variant for known redactables
  * @category destructors
  * @since 3.10.0
  */
@@ -74,25 +78,25 @@ export function redact(u) {
   return u;
 }
 /**
- * Calls `[symbolRedactable]` on a value that is already known to be
- * {@link Redactable} and returns the result.
+ * Returns the result of calling `[symbolRedactable]` on a value that is
+ * already known to be {@link Redactable}.
  *
  * **When to use**
  *
- * Use this when you have already verified the value is `Redactable`, for
+ * Use when you have already verified the value is `Redactable`, for
  * example with {@link isRedactable}, and want to avoid a second check.
  *
  * **Details**
  *
  * This function reads the current fiber's `Context` from the global fiber
- * reference and passes it to the redaction method. It does not mutate the input.
+ * reference and passes it to the redaction method.
  *
  * **Gotchas**
  *
  * If no fiber is active, an empty `Context` is passed to the redaction method.
  *
- * @see {@link redact} - higher-level variant that handles non-redactable values
- * @see {@link isRedactable} - type guard to verify before calling this
+ * @see {@link redact} for the higher-level variant that handles non-redactable values
+ * @see {@link isRedactable} for the type guard to verify before calling this
  * @category destructors
  * @since 4.0.0
  */

package/dist/Redactable.js.map

@@ -1 +1 @@
-{"version":3,"file":"Redactable.js","names":["pipeArguments","hasProperty","symbolRedactable","Symbol","for","isRedactable","u","redact","getRedacted","redactable","globalThis","currentFiberTypeId","context","emptyContext","mapUnsafe","Map","pipe","arguments"],"sources":["../src/Redactable.ts"],"sourcesContent":[null],"mappings":"AAqEA,SAASA,aAAa,QAAQ,eAAe;AAC7C,SAASC,WAAW,QAAQ,gBAAgB;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMC,gBAAgB,gBAAkBC,MAAM,CAACC,GAAG,CAAC,oBAAoB,CAAC;AAuC/E;;;;;;;;;AASA,OAAO,MAAMC,YAAY,GAAIC,CAAU,IAAsBL,WAAW,CAACK,CAAC,EAAEJ,gBAAgB,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAM,SAAUK,MAAMA,CAACD,CAAU;EAC/B,IAAID,YAAY,CAACC,CAAC,CAAC,EAAE,OAAOE,WAAW,CAACF,CAAC,CAAC;EAC1C,OAAOA,CAAC;AACV;AAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAM,SAAUE,WAAWA,CAACC,UAAsB;EAChD,OAAOA,UAAU,CAACP,gBAAgB,CAAC,CAAEQ,UAAkB,CAACC,kBAAkB,CAAC,EAAEC,OAAO,IAAIC,YAAY,CAAC;AACvG;AAEA;AACA,OAAO,MAAMF,kBAAkB,GAAG,4BAA4B;AAE9D,MAAME,YAAY,GAA2B;EAC3C,iBAAiB,EAAE,EAAS;EAC5BC,SAAS,eAAE,IAAIC,GAAG,EAAE;EACpBC,IAAIA,CAAA;IACF,OAAOhB,aAAa,CAAC,IAAI,EAAEiB,SAAS,CAAC;EACvC;CACM","ignoreList":[]}
+{"version":3,"file":"Redactable.js","names":["pipeArguments","hasProperty","symbolRedactable","Symbol","for","isRedactable","u","redact","getRedacted","redactable","globalThis","currentFiberTypeId","context","emptyContext","mapUnsafe","Map","pipe","arguments"],"sources":["../src/Redactable.ts"],"sourcesContent":[null],"mappings":"AAqEA,SAASA,aAAa,QAAQ,eAAe;AAC7C,SAASC,WAAW,QAAQ,gBAAgB;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMC,gBAAgB,gBAAkBC,MAAM,CAACC,GAAG,CAAC,oBAAoB,CAAC;AAuC/E;;;;;;;;;;;;;AAaA,OAAO,MAAMC,YAAY,GAAIC,CAAU,IAAsBL,WAAW,CAACK,CAAC,EAAEJ,gBAAgB,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAM,SAAUK,MAAMA,CAACD,CAAU;EAC/B,IAAID,YAAY,CAACC,CAAC,CAAC,EAAE,OAAOE,WAAW,CAACF,CAAC,CAAC;EAC1C,OAAOA,CAAC;AACV;AAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAM,SAAUE,WAAWA,CAACC,UAAsB;EAChD,OAAOA,UAAU,CAACP,gBAAgB,CAAC,CAAEQ,UAAkB,CAACC,kBAAkB,CAAC,EAAEC,OAAO,IAAIC,YAAY,CAAC;AACvG;AAEA;AACA,OAAO,MAAMF,kBAAkB,GAAG,4BAA4B;AAE9D,MAAME,YAAY,GAA2B;EAC3C,iBAAiB,EAAE,EAAS;EAC5BC,SAAS,eAAE,IAAIC,GAAG,EAAE;EACpBC,IAAIA,CAAA;IACF,OAAOhB,aAAa,CAAC,IAAI,EAAEiB,SAAS,CAAC;EACvC;CACM","ignoreList":[]}

package/dist/Redacted.d.ts

@@ -1,8 +1,45 @@
 /**
- * The Redacted module provides functionality for handling sensitive information
- * securely within your application. By using the `Redacted` data type, you can
- * ensure that sensitive values are not accidentally exposed in logs or error
- * messages.
+ * The `Redacted` module wraps sensitive values so normal rendering paths show
+ * a placeholder instead of the underlying value. It is designed to reduce
+ * accidental disclosure in logs, error messages, JSON output, and inspection
+ * output while still allowing trusted code to recover the original value.
+ *
+ * **Mental model**
+ *
+ * - A `Redacted<A>` carries an underlying value of type `A` behind a wrapper
+ * - String, JSON, and inspection output render as `<redacted>` or
+ *   `<redacted:label>` when a label is provided
+ * - {@link value} retrieves the underlying value and should be used only at
+ *   trusted boundaries
+ * - Equality and hashing are based on the underlying value, not the redacted
+ *   placeholder
+ *
+ * **Common tasks**
+ *
+ * - Wrap a secret with {@link make}
+ * - Check unknown input with {@link isRedacted}
+ * - Recover the secret at a trusted boundary with {@link value}
+ * - Remove the stored association with {@link wipeUnsafe}
+ * - Compare redacted values with an underlying equivalence via
+ *   {@link makeEquivalence}
+ *
+ * **Gotchas**
+ *
+ * - `Redacted` is not encryption and does not zero memory; it reduces
+ *   accidental display of sensitive values
+ * - Labels are visible in rendered output, so labels must not contain secrets
+ * - After {@link wipeUnsafe}, calling {@link value} on the same wrapper fails
+ *
+ * **Example** (Rendering a redacted value)
+ *
+ * ```ts
+ * import { Redacted } from "effect"
+ *
+ * const token = Redacted.make("secret-token", { label: "api-token" })
+ *
+ * String(token) // "<redacted:api-token>"
+ * Redacted.value(token) // "secret-token"
+ * ```
  *
  * @since 3.3.0
  */
@@ -15,6 +52,11 @@ declare const TypeId = "~effect/data/Redacted";
  * A wrapper for sensitive values whose string, JSON, and inspection output is
  * redacted.
  *
+ * **When to use**
+ *
+ * Use to carry sensitive values while reducing accidental exposure in string,
+ * JSON, and inspection output.
+ *
  * **Gotchas**
  *
  * The underlying value is still stored in memory and can be recovered with
@@ -43,6 +85,10 @@ export interface Redacted<out A = string> extends Redacted.Variance<A>, Equal.Eq
 /**
  * Namespace containing type-level members associated with `Redacted` values.
  *
+ * **When to use**
+ *
+ * Use to access type-level helpers associated with `Redacted`.
+ *
  * **Example** (Using namespace utilities)
  *
  * ```ts
@@ -61,6 +107,11 @@ export declare namespace Redacted {
     /**
      * Type-level variance marker for `Redacted`.
      *
+     * **When to use**
+     *
+     * Use when defining internals that need to preserve the covariant value type
+     * carried by `Redacted`.
+     *
      * **Details**
      *
      * This interface records the covariant value type carried by a `Redacted`
@@ -77,6 +128,10 @@ export declare namespace Redacted {
     /**
      * Extracts the underlying value type from a `Redacted` type.
      *
+     * **When to use**
+     *
+     * Use to infer the sensitive value type from an existing `Redacted` type.
+     *
      * **Example** (Extracting the redacted value type)
      *
      * ```ts
@@ -100,6 +155,10 @@ export declare namespace Redacted {
 /**
  * Returns `true` if a value is a `Redacted` wrapper.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `Redacted`.
+ *
  * **Details**
  *
  * When this function returns `true`, TypeScript narrows the value to
@@ -124,6 +183,11 @@ export declare const isRedacted: (u: unknown) => u is Redacted<unknown>;
 /**
  * Creates a `Redacted` wrapper for a sensitive value.
  *
+ * **When to use**
+ *
+ * Use to wrap a sensitive value so normal string, JSON, and inspection output
+ * is redacted.
+ *
  * **Details**
  *
  * The wrapper redacts string, JSON, and inspection output to reduce accidental
@@ -148,6 +212,10 @@ export declare const make: <T>(value: T, options?: {
  * Retrieves the original value from a `Redacted` instance. Use this function
  * with caution, as it exposes the sensitive data.
  *
+ * **When to use**
+ *
+ * Use when the underlying sensitive value is required at a trusted boundary.
+ *
  * **Example** (Retrieving a redacted value)
  *
  * ```ts
@@ -167,6 +235,11 @@ export declare const value: <T>(self: Redacted<T>) => T;
  * Deletes the stored value for a `Redacted` wrapper, making future
  * `Redacted.value` calls on that wrapper fail.
  *
+ * **When to use**
+ *
+ * Use when a `Redacted` wrapper should no longer be able to reveal its stored
+ * value.
+ *
  * **Gotchas**
  *
  * This unsafe operation does not zero memory and does not affect other
@@ -200,6 +273,11 @@ export declare const wipeUnsafe: <T>(self: Redacted<T>) => boolean;
  * equivalence relation for the underlying values `A`. This function is useful
  * for comparing `Redacted` instances without exposing their contents.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` for `Redacted` values based on their
+ * underlying values.
+ *
  * **Example** (Comparing redacted values)
  *
  * ```ts

package/dist/Redacted.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Redacted.d.ts","sourceRoot":"","sources":["../src/Redacted.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAI/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,QAAA,MAAM,MAAM,0BAA0B,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC;;;;;;;;;;OAUG;IACH,UAAiB,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7B,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;YACjB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;SAC1B,CAAA;KACF;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAY,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,CAAA;CAC3F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,QAAQ,CAAC,OAAO,CAA2B,CAAA;AAExF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC,KAAG,QAAQ,CAAC,CAAC,CAOb,CAAA;AA4BD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAkB,CAAA;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAG,OAAiD,CAAA;AAEnG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,cAAc,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,KAAG,WAAW,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CACnD,CAAA"}
+{"version":3,"file":"Redacted.d.ts","sourceRoot":"","sources":["../src/Redacted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAI/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,QAAA,MAAM,MAAM,0BAA0B,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC;;;;;;;;;;;;;;;OAeG;IACH,UAAiB,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7B,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;YACjB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;SAC1B,CAAA;KACF;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAY,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,CAAA;CAC3F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,QAAQ,CAAC,OAAO,CAA2B,CAAA;AAExF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC,KAAG,QAAQ,CAAC,CAAC,CAOb,CAAA;AA4BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAkB,CAAA;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAG,OAAiD,CAAA;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,cAAc,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,KAAG,WAAW,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CACnD,CAAA"}

package/dist/Redacted.js

@@ -1,8 +1,45 @@
 /**
- * The Redacted module provides functionality for handling sensitive information
- * securely within your application. By using the `Redacted` data type, you can
- * ensure that sensitive values are not accidentally exposed in logs or error
- * messages.
+ * The `Redacted` module wraps sensitive values so normal rendering paths show
+ * a placeholder instead of the underlying value. It is designed to reduce
+ * accidental disclosure in logs, error messages, JSON output, and inspection
+ * output while still allowing trusted code to recover the original value.
+ *
+ * **Mental model**
+ *
+ * - A `Redacted<A>` carries an underlying value of type `A` behind a wrapper
+ * - String, JSON, and inspection output render as `<redacted>` or
+ *   `<redacted:label>` when a label is provided
+ * - {@link value} retrieves the underlying value and should be used only at
+ *   trusted boundaries
+ * - Equality and hashing are based on the underlying value, not the redacted
+ *   placeholder
+ *
+ * **Common tasks**
+ *
+ * - Wrap a secret with {@link make}
+ * - Check unknown input with {@link isRedacted}
+ * - Recover the secret at a trusted boundary with {@link value}
+ * - Remove the stored association with {@link wipeUnsafe}
+ * - Compare redacted values with an underlying equivalence via
+ *   {@link makeEquivalence}
+ *
+ * **Gotchas**
+ *
+ * - `Redacted` is not encryption and does not zero memory; it reduces
+ *   accidental display of sensitive values
+ * - Labels are visible in rendered output, so labels must not contain secrets
+ * - After {@link wipeUnsafe}, calling {@link value} on the same wrapper fails
+ *
+ * **Example** (Rendering a redacted value)
+ *
+ * ```ts
+ * import { Redacted } from "effect"
+ *
+ * const token = Redacted.make("secret-token", { label: "api-token" })
+ *
+ * String(token) // "<redacted:api-token>"
+ * Redacted.value(token) // "secret-token"
+ * ```
  *
  * @since 3.3.0
  */
@@ -16,6 +53,10 @@ const TypeId = "~effect/data/Redacted";
 /**
  * Returns `true` if a value is a `Redacted` wrapper.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `Redacted`.
+ *
  * **Details**
  *
  * When this function returns `true`, TypeScript narrows the value to
@@ -40,6 +81,11 @@ export const isRedacted = u => hasProperty(u, TypeId);
 /**
  * Creates a `Redacted` wrapper for a sensitive value.
  *
+ * **When to use**
+ *
+ * Use to wrap a sensitive value so normal string, JSON, and inspection output
+ * is redacted.
+ *
  * **Details**
  *
  * The wrapper redacts string, JSON, and inspection output to reduce accidental
@@ -88,6 +134,10 @@ const Proto = {
  * Retrieves the original value from a `Redacted` instance. Use this function
  * with caution, as it exposes the sensitive data.
  *
+ * **When to use**
+ *
+ * Use when the underlying sensitive value is required at a trusted boundary.
+ *
  * **Example** (Retrieving a redacted value)
  *
  * ```ts
@@ -107,6 +157,11 @@ export const value = redacted.value;
  * Deletes the stored value for a `Redacted` wrapper, making future
  * `Redacted.value` calls on that wrapper fail.
  *
+ * **When to use**
+ *
+ * Use when a `Redacted` wrapper should no longer be able to reveal its stored
+ * value.
+ *
  * **Gotchas**
  *
  * This unsafe operation does not zero memory and does not affect other
@@ -140,6 +195,11 @@ export const wipeUnsafe = self => redacted.redactedRegistry.delete(self);
  * equivalence relation for the underlying values `A`. This function is useful
  * for comparing `Redacted` instances without exposing their contents.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` for `Redacted` values based on their
+ * underlying values.
+ *
  * **Example** (Comparing redacted values)
  *
  * ```ts

package/dist/Redacted.js.map

@@ -1 +1 @@
-{"version":3,"file":"Redacted.js","names":["Equal","Equivalence","Hash","PipeInspectableProto","redacted","hasProperty","isString","TypeId","isRedacted","u","make","value","options","self","Object","create","Proto","label","redactedRegistry","set","_A","_","undefined","toJSON","toString","symbol","hash","get","that","equals","wipeUnsafe","delete","makeEquivalence","isEquivalent","x","y"],"sources":["../src/Redacted.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;AAQA,OAAO,KAAKA,KAAK,MAAM,YAAY;AACnC,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAC/C,OAAO,KAAKC,IAAI,MAAM,WAAW;AACjC,SAASC,oBAAoB,QAAQ,oBAAoB;AACzD,OAAO,KAAKC,QAAQ,MAAM,wBAAwB;AAElD,SAASC,WAAW,EAAEC,QAAQ,QAAQ,gBAAgB;AAGtD,MAAMC,MAAM,GAAG,uBAAuB;AA2FtC;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,UAAU,GAAIC,CAAU,IAA6BJ,WAAW,CAACI,CAAC,EAAEF,MAAM,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMG,IAAI,GAAGA,CAAIC,KAAQ,EAAEC,OAEjC,KAAiB;EAChB,MAAMC,IAAI,GAAGC,MAAM,CAACC,MAAM,CAACC,KAAK,CAAC;EACjC,IAAIJ,OAAO,EAAEK,KAAK,EAAE;IAClBJ,IAAI,CAACI,KAAK,GAAGL,OAAO,CAACK,KAAK;EAC5B;EACAb,QAAQ,CAACc,gBAAgB,CAACC,GAAG,CAACN,IAAI,EAAEF,KAAK,CAAC;EAC1C,OAAOE,IAAI;AACb,CAAC;AAED,MAAMG,KAAK,GAAG;EACZ,CAACT,MAAM,GAAG;IACRa,EAAE,EAAGC,CAAQ,IAAKA;GACnB;EACDJ,KAAK,EAAEK,SAAS;EAChB,GAAGnB,oBAAoB;EACvBoB,MAAMA,CAAA;IACJ,OAAO,IAAI,CAACC,QAAQ,EAAE;EACxB,CAAC;EACDA,QAAQA,CAAA;IACN,OAAO,YAAYlB,QAAQ,CAAC,IAAI,CAACW,KAAK,CAAC,GAAG,GAAG,GAAG,IAAI,CAACA,KAAK,GAAG,EAAE,GAAG;EACpE,CAAC;EACD,CAACf,IAAI,CAACuB,MAAM,IAAC;IACX,OAAOvB,IAAI,CAACwB,IAAI,CAACtB,QAAQ,CAACc,gBAAgB,CAACS,GAAG,CAAC,IAAI,CAAC,CAAC;EACvD,CAAC;EACD,CAAC3B,KAAK,CAACyB,MAAM,EAAwBG,IAAa;IAChD,OACEpB,UAAU,CAACoB,IAAI,CAAC,IAChB5B,KAAK,CAAC6B,MAAM,CACVzB,QAAQ,CAACc,gBAAgB,CAACS,GAAG,CAAC,IAAI,CAAC,EACnCvB,QAAQ,CAACc,gBAAgB,CAACS,GAAG,CAACC,IAAI,CAAC,CACpC;EAEL;CACD;AAED;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMjB,KAAK,GAAgCP,QAAQ,CAACO,KAAK;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAO,MAAMmB,UAAU,GAAOjB,IAAiB,IAAcT,QAAQ,CAACc,gBAAgB,CAACa,MAAM,CAAClB,IAAI,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAMmB,eAAe,GAAOC,YAAwC,IACzEhC,WAAW,CAACS,IAAI,CAAC,CAACwB,CAAC,EAAEC,CAAC,KAAKF,YAAY,CAACtB,KAAK,CAACuB,CAAC,CAAC,EAAEvB,KAAK,CAACwB,CAAC,CAAC,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"Redacted.js","names":["Equal","Equivalence","Hash","PipeInspectableProto","redacted","hasProperty","isString","TypeId","isRedacted","u","make","value","options","self","Object","create","Proto","label","redactedRegistry","set","_A","_","undefined","toJSON","toString","symbol","hash","get","that","equals","wipeUnsafe","delete","makeEquivalence","isEquivalent","x","y"],"sources":["../src/Redacted.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,OAAO,KAAKA,KAAK,MAAM,YAAY;AACnC,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAC/C,OAAO,KAAKC,IAAI,MAAM,WAAW;AACjC,SAASC,oBAAoB,QAAQ,oBAAoB;AACzD,OAAO,KAAKC,QAAQ,MAAM,wBAAwB;AAElD,SAASC,WAAW,EAAEC,QAAQ,QAAQ,gBAAgB;AAGtD,MAAMC,MAAM,GAAG,uBAAuB;AA6GtC;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMC,UAAU,GAAIC,CAAU,IAA6BJ,WAAW,CAACI,CAAC,EAAEF,MAAM,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMG,IAAI,GAAGA,CAAIC,KAAQ,EAAEC,OAEjC,KAAiB;EAChB,MAAMC,IAAI,GAAGC,MAAM,CAACC,MAAM,CAACC,KAAK,CAAC;EACjC,IAAIJ,OAAO,EAAEK,KAAK,EAAE;IAClBJ,IAAI,CAACI,KAAK,GAAGL,OAAO,CAACK,KAAK;EAC5B;EACAb,QAAQ,CAACc,gBAAgB,CAACC,GAAG,CAACN,IAAI,EAAEF,KAAK,CAAC;EAC1C,OAAOE,IAAI;AACb,CAAC;AAED,MAAMG,KAAK,GAAG;EACZ,CAACT,MAAM,GAAG;IACRa,EAAE,EAAGC,CAAQ,IAAKA;GACnB;EACDJ,KAAK,EAAEK,SAAS;EAChB,GAAGnB,oBAAoB;EACvBoB,MAAMA,CAAA;IACJ,OAAO,IAAI,CAACC,QAAQ,EAAE;EACxB,CAAC;EACDA,QAAQA,CAAA;IACN,OAAO,YAAYlB,QAAQ,CAAC,IAAI,CAACW,KAAK,CAAC,GAAG,GAAG,GAAG,IAAI,CAACA,KAAK,GAAG,EAAE,GAAG;EACpE,CAAC;EACD,CAACf,IAAI,CAACuB,MAAM,IAAC;IACX,OAAOvB,IAAI,CAACwB,IAAI,CAACtB,QAAQ,CAACc,gBAAgB,CAACS,GAAG,CAAC,IAAI,CAAC,CAAC;EACvD,CAAC;EACD,CAAC3B,KAAK,CAACyB,MAAM,EAAwBG,IAAa;IAChD,OACEpB,UAAU,CAACoB,IAAI,CAAC,IAChB5B,KAAK,CAAC6B,MAAM,CACVzB,QAAQ,CAACc,gBAAgB,CAACS,GAAG,CAAC,IAAI,CAAC,EACnCvB,QAAQ,CAACc,gBAAgB,CAACS,GAAG,CAACC,IAAI,CAAC,CACpC;EAEL;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMjB,KAAK,GAAgCP,QAAQ,CAACO,KAAK;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAO,MAAMmB,UAAU,GAAOjB,IAAiB,IAAcT,QAAQ,CAACc,gBAAgB,CAACa,MAAM,CAAClB,IAAI,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,MAAMmB,eAAe,GAAOC,YAAwC,IACzEhC,WAAW,CAACS,IAAI,CAAC,CAACwB,CAAC,EAAEC,CAAC,KAAKF,YAAY,CAACtB,KAAK,CAACuB,CAAC,CAAC,EAAEvB,KAAK,CAACwB,CAAC,CAAC,CAAC,CAAC","ignoreList":[]}

package/dist/Reducer.d.ts

@@ -73,7 +73,7 @@ import type * as Combiner from "./Combiner.ts";
  *
  * **When to use**
  *
- * - You need to fold/reduce a collection into a single value.
+ * Use when you need to fold/reduce a collection into a single value.
  * - You want a reusable reducing strategy that can be passed to library
  *   functions like `Struct.makeReducer`, `Option.makeReducer`, or
  *   `Record.makeReducerUnion`.
@@ -110,9 +110,21 @@ import type * as Combiner from "./Combiner.ts";
  * @since 4.0.0
  */
 export interface Reducer<A> extends Combiner.Combiner<A> {
-    /** Neutral starting value (combining with this changes nothing). */
+    /**
+     * Neutral starting value (combining with this changes nothing).
+     *
+     * **When to use**
+     *
+     * Use to seed a reduction and represent the result of reducing an empty collection.
+     */
     readonly initialValue: A;
-    /** Combines all values in the collection, starting from `initialValue`. */
+    /**
+     * Combines all values in the collection, starting from `initialValue`.
+     *
+     * **When to use**
+     *
+     * Use to reduce an iterable with this reducer's initial value and combining operation.
+     */
     readonly combineAll: (collection: Iterable<A>) => A;
 }
 /**
@@ -120,7 +132,7 @@ export interface Reducer<A> extends Combiner.Combiner<A> {
  *
  * **When to use**
  *
- * - You have a custom reducing operation not covered by a pre-built reducer.
+ * Use when you have a custom reducing operation not covered by a pre-built reducer.
  * - You want to provide an optimized `combineAll` (e.g. short-circuiting on
  *   a known absorbing element like `0` for multiplication).
  *
@@ -129,7 +141,6 @@ export interface Reducer<A> extends Combiner.Combiner<A> {
  * - If `combineAll` is omitted, a default left-to-right fold starting from
  *   `initialValue` is used.
  * - If `combineAll` is provided, it completely replaces the default fold.
- * - Pure – the returned reducer does not mutate its arguments.
  *
  * **Example** (Multiplication with short-circuit)
  *
@@ -168,7 +179,7 @@ export declare function make<A>(combine: (self: A, that: A) => A, initialValue:
  *
  * **When to use**
  *
- * - You need the "right" value to act as the accumulator side.
+ * Use when you need the "right" value to act as the accumulator side.
  * - You want to reverse the natural direction of a non-commutative reducer
  *   (e.g. string concatenation becomes prepend).
  *
@@ -179,7 +190,6 @@ export declare function make<A>(combine: (self: A, that: A) => A, initialValue:
  * - The `initialValue` is preserved from the original reducer.
  * - The `combineAll` is re-derived from the flipped `combine` (using the
  *   default left-to-right fold), not carried over from the original.
- * - Does not mutate the input reducer.
  *
  * **Example** (Reversing string concatenation)
  *

package/dist/Reducer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Reducer.d.ts","sourceRoot":"","sources":["../src/Reducer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtD,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAA;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAChC,YAAY,EAAE,CAAC,EACf,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvD"}
+{"version":3,"file":"Reducer.d.ts","sourceRoot":"","sources":["../src/Reducer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtD;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAA;IAExB;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAChC,YAAY,EAAE,CAAC,EACf,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvD"}

package/dist/Reducer.js

@@ -71,7 +71,7 @@
  *
  * **When to use**
  *
- * - You have a custom reducing operation not covered by a pre-built reducer.
+ * Use when you have a custom reducing operation not covered by a pre-built reducer.
  * - You want to provide an optimized `combineAll` (e.g. short-circuiting on
  *   a known absorbing element like `0` for multiplication).
  *
@@ -80,7 +80,6 @@
  * - If `combineAll` is omitted, a default left-to-right fold starting from
  *   `initialValue` is used.
  * - If `combineAll` is provided, it completely replaces the default fold.
- * - Pure – the returned reducer does not mutate its arguments.
  *
  * **Example** (Multiplication with short-circuit)
  *
@@ -131,7 +130,7 @@ export function make(combine, initialValue, combineAll) {
  *
  * **When to use**
  *
- * - You need the "right" value to act as the accumulator side.
+ * Use when you need the "right" value to act as the accumulator side.
  * - You want to reverse the natural direction of a non-commutative reducer
  *   (e.g. string concatenation becomes prepend).
  *
@@ -142,7 +141,6 @@ export function make(combine, initialValue, combineAll) {
  * - The `initialValue` is preserved from the original reducer.
  * - The `combineAll` is re-derived from the flipped `combine` (using the
  *   default left-to-right fold), not carried over from the original.
- * - Does not mutate the input reducer.
  *
  * **Example** (Reversing string concatenation)
  *

package/dist/Reducer.js.map

@@ -1 +1 @@
-{"version":3,"file":"Reducer.js","names":["make","combine","initialValue","combineAll","collection","out","value","flip","reducer","self","that"],"sources":["../src/Reducer.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,OAAM,SAAUA,IAAIA,CAClBC,OAAgC,EAChCC,YAAe,EACfC,UAA2C;EAE3C,OAAO;IACLF,OAAO;IACPC,YAAY;IACZC,UAAU,EAAEA,UAAU,KAClBC,UAAU,IAAI;MACd,IAAIC,GAAG,GAAGH,YAAY;MACtB,KAAK,MAAMI,KAAK,IAAIF,UAAU,EAAE;QAC9BC,GAAG,GAAGJ,OAAO,CAACI,GAAG,EAAEC,KAAK,CAAC;MAC3B;MACA,OAAOD,GAAG;IACZ,CAAC;GACJ;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,OAAM,SAAUE,IAAIA,CAAIC,OAAmB;EACzC,OAAOR,IAAI,CAAC,CAACS,IAAI,EAAEC,IAAI,KAAKF,OAAO,CAACP,OAAO,CAACS,IAAI,EAAED,IAAI,CAAC,EAAED,OAAO,CAACN,YAAY,CAAC;AAChF","ignoreList":[]}
+{"version":3,"file":"Reducer.js","names":["make","combine","initialValue","combineAll","collection","out","value","flip","reducer","self","that"],"sources":["../src/Reducer.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,OAAM,SAAUA,IAAIA,CAClBC,OAAgC,EAChCC,YAAe,EACfC,UAA2C;EAE3C,OAAO;IACLF,OAAO;IACPC,YAAY;IACZC,UAAU,EAAEA,UAAU,KAClBC,UAAU,IAAI;MACd,IAAIC,GAAG,GAAGH,YAAY;MACtB,KAAK,MAAMI,KAAK,IAAIF,UAAU,EAAE;QAC9BC,GAAG,GAAGJ,OAAO,CAACI,GAAG,EAAEC,KAAK,CAAC;MAC3B;MACA,OAAOD,GAAG;IACZ,CAAC;GACJ;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,OAAM,SAAUE,IAAIA,CAAIC,OAAmB;EACzC,OAAOR,IAAI,CAAC,CAACS,IAAI,EAAEC,IAAI,KAAKF,OAAO,CAACP,OAAO,CAACS,IAAI,EAAED,IAAI,CAAC,EAAED,OAAO,CAACN,YAAY,CAAC;AAChF","ignoreList":[]}