effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/MutableRef.js

@@ -1,34 +1,37 @@
 /**
- * @fileoverview
- * MutableRef provides a mutable reference container that allows safe mutation of values
- * in functional programming contexts. It serves as a bridge between functional and imperative
- * programming paradigms, offering atomic operations for state management.
- *
- * Unlike regular variables, MutableRef encapsulates mutable state and provides controlled
- * access through a standardized API. It supports atomic compare-and-set operations for
- * thread-safe updates and integrates seamlessly with Effect's ecosystem.
- *
- * Key Features:
- * - Mutable reference semantics with functional API
- * - Atomic compare-and-set operations for safe concurrent updates
- * - Specialized operations for numeric and boolean values
- * - Chainable operations that return the reference or the value
- * - Integration with Effect's Equal interface for value comparison
- *
- * Common Use Cases:
- * - State containers in functional applications
- * - Counters and accumulators
- * - Configuration that needs to be updated at runtime
- * - Caching and memoization scenarios
- * - Inter-module communication via shared references
- *
- * Performance Characteristics:
- * - Get/Set: O(1)
- * - Compare-and-set: O(1)
- * - All operations: O(1)
+ * The `MutableRef` module provides a small synchronous container for mutable
+ * state. A `MutableRef<A>` stores one current value of type `A`, exposes that
+ * value through `.current`, and offers pipeable helpers for reading, replacing,
+ * and transforming the value in place.
+ *
+ * **Mental model**
+ *
+ * - `MutableRef<A>` is a stable reference whose `.current` field may change over time
+ * - Reads and writes are synchronous and return immediately
+ * - `set`, `update`, `increment`, `decrement`, and `toggle` mutate the same reference in place
+ * - `getAnd*` helpers return the previous value, while `*AndGet` helpers return the new value
+ * - `compareAndSet` updates only when the current value is equal to the expected value using `Equal.equals`
+ * - A `MutableRef` is useful for local mutable state, but it does not make updates transactional or effectful
+ *
+ * **Common tasks**
+ *
+ * - Create a reference: {@link make}
+ * - Read the current value: {@link get} or `.current`
+ * - Replace the current value: {@link set}, {@link setAndGet}, {@link getAndSet}
+ * - Transform the current value: {@link update}, {@link updateAndGet}, {@link getAndUpdate}
+ * - Coordinate conditional replacement: {@link compareAndSet}
+ * - Work with counters: {@link increment}, {@link decrement}, {@link incrementAndGet}, {@link decrementAndGet}
+ * - Work with boolean flags: {@link toggle}
+ *
+ * **Gotchas**
+ *
+ * - All updates are imperative mutations; aliases to the same `MutableRef` observe the same changing value
+ * - Updating object or array values does not clone them unless the update function creates a new value
+ * - `compareAndSet` compares with Effect equality semantics, not only JavaScript reference equality
+ * - For state that must participate in `Effect` workflows, interruption, or fiber coordination, prefer higher-level Effect data types
  *
- * @since 2.0.0
  * @category data-structures
+ * @since 2.0.0
  */
 import * as Equal from "./Equal.js";
 import * as Dual from "./Function.js";
@@ -48,7 +51,8 @@ const MutableRefProto = {
 /**
  * Creates a new MutableRef with the specified initial value.
  *
- * @example
+ * **Example** (Creating mutable refs)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -66,8 +70,8 @@ const MutableRefProto = {
  * console.log(MutableRef.get(status)) // "running"
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = value => {
   const ref = Object.create(MutableRefProto);
@@ -79,7 +83,8 @@ export const make = value => {
  * Returns true if the value was updated, false otherwise.
  * Uses Effect's Equal interface for value comparison.
  *
- * @example
+ * **Example** (Comparing and setting values)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -107,8 +112,8 @@ export const make = value => {
  * console.log(casUpdate(ref)) // true
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const compareAndSet = /*#__PURE__*/Dual.dual(3, (self, oldValue, newValue) => {
   if (Equal.equals(oldValue, self.current)) {
@@ -120,7 +125,8 @@ export const compareAndSet = /*#__PURE__*/Dual.dual(3, (self, oldValue, newValue
 /**
  * Decrements a numeric MutableRef by 1 and returns the reference.
  *
- * @example
+ * **Example** (Decrementing numeric refs)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -143,14 +149,15 @@ export const compareAndSet = /*#__PURE__*/Dual.dual(3, (self, oldValue, newValue
  * }
  * ```
  *
- * @since 2.0.0
  * @category numeric
+ * @since 2.0.0
  */
 export const decrement = self => update(self, n => n - 1);
 /**
  * Decrements a numeric MutableRef by 1 and returns the new value.
  *
- * @example
+ * **Example** (Decrementing and reading refs)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -173,14 +180,15 @@ export const decrement = self => update(self, n => n - 1);
  * }
  * ```
  *
- * @since 2.0.0
  * @category numeric
+ * @since 2.0.0
  */
 export const decrementAndGet = self => updateAndGet(self, n => n - 1);
 /**
  * Gets the current value of the MutableRef.
  *
- * @example
+ * **Example** (Reading current values)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -201,14 +209,15 @@ export const decrementAndGet = self => updateAndGet(self, n => n - 1);
  * console.log(value1 === value2) // true
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const get = self => self.current;
 /**
  * Decrements a numeric MutableRef by 1 and returns the previous value.
  *
- * @example
+ * **Example** (Reading before decrementing)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -232,14 +241,15 @@ export const get = self => self.current;
  * console.log(`Current: ${currentIndex}, Next: ${MutableRef.get(index)}`) // "Current: 3, Next: 2"
  * ```
  *
- * @since 2.0.0
  * @category numeric
+ * @since 2.0.0
  */
 export const getAndDecrement = self => getAndUpdate(self, n => n - 1);
 /**
  * Increments a numeric MutableRef by 1 and returns the previous value.
  *
- * @example
+ * **Example** (Reading before incrementing)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -271,14 +281,15 @@ export const getAndDecrement = self => getAndUpdate(self, n => n - 1);
  * }
  * ```
  *
- * @since 2.0.0
  * @category numeric
+ * @since 2.0.0
  */
 export const getAndIncrement = self => getAndUpdate(self, n => n + 1);
 /**
  * Sets the MutableRef to a new value and returns the previous value.
  *
- * @example
+ * **Example** (Reading before setting)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -306,8 +317,8 @@ export const getAndIncrement = self => getAndUpdate(self, n => n + 1);
  * console.log(MutableRef.get(buffer)) // []
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const getAndSet = /*#__PURE__*/Dual.dual(2, (self, value) => {
   const ret = self.current;
@@ -318,7 +329,8 @@ export const getAndSet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the previous value.
  *
- * @example
+ * **Example** (Reading before updating)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -352,14 +364,15 @@ export const getAndSet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  * console.log(MutableRef.get(list)) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const getAndUpdate = /*#__PURE__*/Dual.dual(2, (self, f) => getAndSet(self, f(get(self))));
 /**
  * Increments a numeric MutableRef by 1 and returns the reference.
  *
- * @example
+ * **Example** (Incrementing numeric refs)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -385,14 +398,15 @@ export const getAndUpdate = /*#__PURE__*/Dual.dual(2, (self, f) => getAndSet(sel
  * console.log(result === counter) // true
  * ```
  *
- * @since 2.0.0
  * @category numeric
+ * @since 2.0.0
  */
 export const increment = self => update(self, n => n + 1);
 /**
  * Increments a numeric MutableRef by 1 and returns the new value.
  *
- * @example
+ * **Example** (Incrementing and reading refs)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -419,14 +433,15 @@ export const increment = self => update(self, n => n + 1);
  * }
  * ```
  *
- * @since 2.0.0
  * @category numeric
+ * @since 2.0.0
  */
 export const incrementAndGet = self => updateAndGet(self, n => n + 1);
 /**
  * Sets the MutableRef to a new value and returns the reference.
  *
- * @example
+ * **Example** (Setting values)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -458,8 +473,8 @@ export const incrementAndGet = self => updateAndGet(self, n => n + 1);
  * MutableRef.set(state, "success")
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const set = /*#__PURE__*/Dual.dual(2, (self, value) => {
   self.current = value;
@@ -468,7 +483,8 @@ export const set = /*#__PURE__*/Dual.dual(2, (self, value) => {
 /**
  * Sets the MutableRef to a new value and returns the new value.
  *
- * @example
+ * **Example** (Setting and reading values)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -496,8 +512,8 @@ export const set = /*#__PURE__*/Dual.dual(2, (self, value) => {
  * console.log(returnedValue) // 3
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const setAndGet = /*#__PURE__*/Dual.dual(2, (self, value) => {
   self.current = value;
@@ -507,7 +523,8 @@ export const setAndGet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the reference.
  *
- * @example
+ * **Example** (Updating values)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -543,15 +560,16 @@ export const setAndGet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  * console.log(MutableRef.get(list)) // [1, 2, 3, 4]
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const update = /*#__PURE__*/Dual.dual(2, (self, f) => set(self, f(get(self))));
 /**
  * Updates the MutableRef with the result of applying a function to its current value,
  * and returns the new value.
  *
- * @example
+ * **Example** (Updating and reading values)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -589,14 +607,15 @@ export const update = /*#__PURE__*/Dual.dual(2, (self, f) => set(self, f(get(sel
  * console.log(MutableRef.get(list)) // [2, 4, 6]
  * ```
  *
- * @since 2.0.0
  * @category general
+ * @since 2.0.0
  */
 export const updateAndGet = /*#__PURE__*/Dual.dual(2, (self, f) => setAndGet(self, f(get(self))));
 /**
  * Toggles a boolean MutableRef (true becomes false, false becomes true) and returns the reference.
  *
- * @example
+ * **Example** (Toggling boolean refs)
+ *
  * ```ts
  * import { MutableRef } from "effect"
  *
@@ -630,8 +649,8 @@ export const updateAndGet = /*#__PURE__*/Dual.dual(2, (self, f) => setAndGet(sel
  * console.log(result === flag) // true
  * ```
  *
- * @since 2.0.0
  * @category boolean
+ * @since 2.0.0
  */
 export const toggle = self => update(self, _ => !_);
 //# sourceMappingURL=MutableRef.js.map

package/dist/MutableRef.js.map

@@ -1 +1 @@
-{"version":3,"file":"MutableRef.js","names":["Equal","Dual","toJson","PipeInspectableProto","TypeId","MutableRefProto","toJSON","_id","current","make","value","ref","Object","create","compareAndSet","dual","self","oldValue","newValue","equals","decrement","update","n","decrementAndGet","updateAndGet","get","getAndDecrement","getAndUpdate","getAndIncrement","getAndSet","ret","f","increment","incrementAndGet","set","setAndGet","toggle","_"],"sources":["../src/MutableRef.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,KAAKA,KAAK,MAAM,YAAY;AACnC,OAAO,KAAKC,IAAI,MAAM,eAAe;AACrC,SAA2BC,MAAM,QAAQ,kBAAkB;AAC3D,SAASC,oBAAoB,QAAQ,oBAAoB;AAGzD,MAAMC,MAAM,GAAG,oBAAoB;AA0CnC,MAAMC,eAAe,GAAyC;EAC5D,CAACD,MAAM,GAAGA,MAAM;EAChB,GAAGD,oBAAoB;EACvBG,MAAMA,CAAA;IACJ,OAAO;MACLC,GAAG,EAAE,YAAY;MACjBC,OAAO,EAAEN,MAAM,CAAC,IAAI,CAACM,OAAO;KAC7B;EACH;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAMC,IAAI,GAAOC,KAAQ,IAAmB;EACjD,MAAMC,GAAG,GAAGC,MAAM,CAACC,MAAM,CAACR,eAAe,CAAC;EAC1CM,GAAG,CAACH,OAAO,GAAGE,KAAK;EACnB,OAAOC,GAAG;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAO,MAAMG,aAAa,gBA2EtBb,IAAI,CAACc,IAAI,CAGX,CAAC,EAAE,CAACC,IAAI,EAAEC,QAAQ,EAAEC,QAAQ,KAAI;EAChC,IAAIlB,KAAK,CAACmB,MAAM,CAACF,QAAQ,EAAED,IAAI,CAACR,OAAO,CAAC,EAAE;IACxCQ,IAAI,CAACR,OAAO,GAAGU,QAAQ;IACvB,OAAO,IAAI;EACb;EACA,OAAO,KAAK;AACd,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,MAAME,SAAS,GAAIJ,IAAwB,IAAyBK,MAAM,CAACL,IAAI,EAAGM,CAAC,IAAKA,CAAC,GAAG,CAAC,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,MAAMC,eAAe,GAAIP,IAAwB,IAAaQ,YAAY,CAACR,IAAI,EAAGM,CAAC,IAAKA,CAAC,GAAG,CAAC,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAMG,GAAG,GAAOT,IAAmB,IAAQA,IAAI,CAACR,OAAO;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMkB,eAAe,GAAIV,IAAwB,IAAaW,YAAY,CAACX,IAAI,EAAGM,CAAC,IAAKA,CAAC,GAAG,CAAC,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,OAAO,MAAMM,eAAe,GAAIZ,IAAwB,IAAaW,YAAY,CAACX,IAAI,EAAGM,CAAC,IAAKA,CAAC,GAAG,CAAC,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMO,SAAS,gBAuElB5B,IAAI,CAACc,IAAI,CAGX,CAAC,EAAE,CAACC,IAAI,EAAEN,KAAK,KAAI;EACnB,MAAMoB,GAAG,GAAGd,IAAI,CAACR,OAAO;EACxBQ,IAAI,CAACR,OAAO,GAAGE,KAAK;EACpB,OAAOoB,GAAG;AACZ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,OAAO,MAAMH,YAAY,gBAqFrB1B,IAAI,CAACc,IAAI,CAGX,CAAC,EAAE,CAACC,IAAI,EAAEe,CAAC,KAAKF,SAAS,CAACb,IAAI,EAAEe,CAAC,CAACN,GAAG,CAACT,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,MAAMgB,SAAS,GAAIhB,IAAwB,IAAyBK,MAAM,CAACL,IAAI,EAAGM,CAAC,IAAKA,CAAC,GAAG,CAAC,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,OAAO,MAAMW,eAAe,GAAIjB,IAAwB,IAAaQ,YAAY,CAACR,IAAI,EAAGM,CAAC,IAAKA,CAAC,GAAG,CAAC,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,OAAO,MAAMY,GAAG,gBA+EZjC,IAAI,CAACc,IAAI,CAGX,CAAC,EAAE,CAACC,IAAI,EAAEN,KAAK,KAAI;EACnBM,IAAI,CAACR,OAAO,GAAGE,KAAK;EACpB,OAAOM,IAAI;AACb,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMmB,SAAS,gBAuElBlC,IAAI,CAACc,IAAI,CAGX,CAAC,EAAE,CAACC,IAAI,EAAEN,KAAK,KAAI;EACnBM,IAAI,CAACR,OAAO,GAAGE,KAAK;EACpB,OAAOM,IAAI,CAACR,OAAO;AACrB,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,OAAO,MAAMa,MAAM,gBAyFfpB,IAAI,CAACc,IAAI,CAGX,CAAC,EAAE,CAACC,IAAI,EAAEe,CAAC,KAAKG,GAAG,CAAClB,IAAI,EAAEe,CAAC,CAACN,GAAG,CAACT,IAAI,CAAC,CAAC,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,OAAO,MAAMQ,YAAY,gBA6FrBvB,IAAI,CAACc,IAAI,CAGX,CAAC,EAAE,CAACC,IAAI,EAAEe,CAAC,KAAKI,SAAS,CAACnB,IAAI,EAAEe,CAAC,CAACN,GAAG,CAACT,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,OAAO,MAAMoB,MAAM,GAAIpB,IAAyB,IAA0BK,MAAM,CAACL,IAAI,EAAGqB,CAAC,IAAK,CAACA,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"MutableRef.js","names":["Equal","Dual","toJson","PipeInspectableProto","TypeId","MutableRefProto","toJSON","_id","current","make","value","ref","Object","create","compareAndSet","dual","self","oldValue","newValue","equals","decrement","update","n","decrementAndGet","updateAndGet","get","getAndDecrement","getAndUpdate","getAndIncrement","getAndSet","ret","f","increment","incrementAndGet","set","setAndGet","toggle","_"],"sources":["../src/MutableRef.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/Newtype.d.ts

@@ -103,6 +103,9 @@ export interface Newtype<in out Key extends string, out Carrier> {
     };
 }
 /**
+ * Namespace containing type-level helpers for `Newtype` values, including
+ * constraints and utilities for extracting a newtype's key and carrier type.
+ *
  * @since 4.0.0
  */
 export declare namespace Newtype {

package/dist/Newtype.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Newtype.d.ts","sourceRoot":"","sources":["../src/Newtype.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Newtype.d.ts","sourceRoot":"","sources":["../src/Newtype.ts"],"names":[],"mappings":"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"}

package/dist/Newtype.js.map

@@ -1 +1 @@
-{"version":3,"file":"Newtype.js","names":["cast","Optic","TypeId","value","makeIso","makeEquivalence","makeOrder","makeCombiner","makeReducer"],"sources":["../src/Newtype.ts"],"sourcesContent":[null],"mappings":"AAmEA,SAASA,IAAI,QAAQ,eAAe;AACpC,OAAO,KAAKC,KAAK,MAAM,YAAY;AAInC,MAAMC,MAAM,GAAG,iBAAiB;AAqEhC;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,KAAK,GAA8DH,IAAI;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAM,SAAUI,OAAOA,CAAA;EACrB,OAAOH,KAAK,CAACG,OAAO,CAACD,KAAK,EAAEH,IAAI,CAAC;AACnC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAO,MAAMK,eAAe,GAEML,IAAI;AAEtC;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMM,SAAS,GAAsFN,IAAI;AAEhH;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMO,YAAY,GAEGP,IAAI;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMQ,WAAW,GACtBR,IAAI","ignoreList":[]}
+{"version":3,"file":"Newtype.js","names":["cast","Optic","TypeId","value","makeIso","makeEquivalence","makeOrder","makeCombiner","makeReducer"],"sources":["../src/Newtype.ts"],"sourcesContent":[null],"mappings":"AAmEA,SAASA,IAAI,QAAQ,eAAe;AACpC,OAAO,KAAKC,KAAK,MAAM,YAAY;AAInC,MAAMC,MAAM,GAAG,iBAAiB;AAwEhC;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,KAAK,GAA8DH,IAAI;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAM,SAAUI,OAAOA,CAAA;EACrB,OAAOH,KAAK,CAACG,OAAO,CAACD,KAAK,EAAEH,IAAI,CAAC;AACnC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAO,MAAMK,eAAe,GAEML,IAAI;AAEtC;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMM,SAAS,GAAsFN,IAAI;AAEhH;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMO,YAAY,GAEGP,IAAI;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMQ,WAAW,GACtBR,IAAI","ignoreList":[]}

package/dist/NonEmptyIterable.d.ts

@@ -1,26 +1,34 @@
 /**
- * @since 2.0.0
+ * The `NonEmptyIterable` module provides a type-level representation of any
+ * JavaScript `Iterable` that is known to contain at least one element. A
+ * `NonEmptyIterable<A>` can be consumed anywhere an `Iterable<A>` is expected,
+ * while also carrying the guarantee that reading the first element is safe.
+ *
+ * **Mental model**
+ *
+ * - `NonEmptyIterable<A>` is an `Iterable<A>` branded with a non-empty guarantee
+ * - The guarantee is static: values should only be typed this way when construction or validation proves at least one element exists
+ * - The iterable can be an array, string, set, map, generator, or any custom iterable
+ * - `unprepend` safely separates the first element from an iterator for the remaining elements
+ * - Operations that may remove elements, such as filtering, usually return ordinary collections because they can become empty
  *
- * The `NonEmptyIterable` module provides types and utilities for working with iterables
- * that are guaranteed to contain at least one element. This provides compile-time
- * safety when working with collections that must not be empty.
+ * **Common tasks**
  *
- * ## Key Features
+ * - Accept inputs that must contain at least one value
+ * - Extract a head element and process the remaining iterator with {@link unprepend}
+ * - Model APIs such as reductions, comparisons, or aggregation that are undefined for empty inputs
+ * - Preserve compatibility with the JavaScript iteration protocol while documenting the stronger invariant
  *
- * - **Type Safety**: Compile-time guarantee that the iterable contains at least one element
- * - **Iterator Protocol**: Fully compatible with JavaScript's built-in iteration protocol
- * - **Functional Operations**: Safe operations that preserve the non-empty property
- * - **Lightweight**: Minimal overhead with maximum type safety
+ * **Gotchas**
  *
- * ## Why NonEmptyIterable?
+ * - A type assertion does not make an empty iterable non-empty; only assert after a trusted check or constructor
+ * - Iterators are stateful, so calling {@link unprepend} consumes the first yielded value from that iterator
+ * - The order of the first element follows the source iterable's iteration order, for example insertion order for `Map` and `Set`
+ * - Some transformations preserve non-emptiness, but transformations that can discard elements must account for the empty case
  *
- * Many operations require non-empty collections to be meaningful:
- * - Finding the maximum or minimum value
- * - Getting the first or last element
- * - Reducing without an initial value
- * - Operations that would otherwise need runtime checks
+ * **Quickstart**
  *
- * ## Basic Usage
+ * **Example** (Requiring a non-empty iterable)
  *
  * ```ts
  * import * as NonEmptyIterable from "effect/NonEmptyIterable"
@@ -58,6 +66,8 @@
  *
  * ## Working with Different Iterable Types
  *
+ * **Example** (Adapting iterable inputs)
+ *
  * ```ts
  * import { Array } from "effect"
  *
@@ -103,10 +113,11 @@
  *
  * ## Integration with Effect Arrays
  *
+ * **Example** (Processing non-empty iterables with Array)
+ *
  * ```ts
  * import { Array, pipe } from "effect"
  * import type * as NonEmptyIterable from "effect/NonEmptyIterable"
- * import type * as NonEmptyIterable from "effect/NonEmptyIterable"
  *
  * // Many Array functions work with NonEmptyIterable
  * declare const nonEmptyData: NonEmptyIterable.NonEmptyIterable<number>
@@ -127,6 +138,8 @@
  *   // This would still be non-empty if the source was non-empty
  * )
  * ```
+ *
+ * @since 2.0.0
  */
 /**
  * A unique symbol used to brand the `NonEmptyIterable` type.
@@ -135,24 +148,6 @@
  * `Iterable<A>`, providing compile-time guarantees about non-emptiness while
  * maintaining full compatibility with the JavaScript iteration protocol.
  *
- * @example
- * ```ts
- * import type * as NonEmptyIterable from "effect/NonEmptyIterable"
- *
- * // The symbol is used internally for type branding
- * declare const data: NonEmptyIterable.NonEmptyIterable<number>
- *
- * // This has the nonEmpty symbol property (not accessible at runtime)
- * // but is still a regular Iterable for all practical purposes
- * for (const item of data) {
- *   console.log(item) // Works normally
- * }
- *
- * // Can be used with any function expecting an Iterable
- * const array = Array.from(data)
- * const set = new Set(data)
- * ```
- *
  * @category symbol
  * @since 2.0.0
  */
@@ -167,7 +162,8 @@ export declare const nonEmpty: unique symbol;
  * The type is branded with a unique symbol to ensure type safety while maintaining
  * full compatibility with JavaScript's iteration protocol.
  *
- * @example
+ * **Example** (Working with non-empty iterables)
+ *
  * ```ts
  * import { Array } from "effect"
  * import * as Chunk from "effect/Chunk"
@@ -223,10 +219,8 @@ export interface NonEmptyIterable<out A> extends Iterable<A> {
  * head (first element) and tail (remaining elements as an iterator). Since the
  * iterable is guaranteed to be non-empty, the first element is always available.
  *
- * @param self - The non-empty iterable to deconstruct
- * @returns A tuple containing the first element and an iterator for the remaining elements
+ * **Example** (Extracting first and remaining elements)
  *
- * @example
  * ```ts
  * import { Array } from "effect"
  * import * as Chunk from "effect/Chunk"
@@ -326,6 +320,9 @@ export interface NonEmptyIterable<out A> extends Iterable<A> {
  * const sum = reduceNonEmpty(data, (acc, x) => acc + x, 0) // 10
  * ```
  *
+ * @param self - The non-empty iterable to deconstruct
+ * @returns A tuple containing the first element and an iterator for the remaining elements
+ *
  * @category getters
  * @since 2.0.0
  */

package/dist/NonEmptyIterable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NonEmptyIterable.d.ts","sourceRoot":"","sources":["../src/NonEmptyIterable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,QAAQ,EAAE,OAAO,MAAM,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,MAAM,gBAAgB,CAAC,CAAC,CAAC,KAAG,CAAC,YAAY,EAAE,CAAC,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC,CAAC,CASxG,CAAA"}
+{"version":3,"file":"NonEmptyIterable.d.ts","sourceRoot":"","sources":["../src/NonEmptyIterable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8IG;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,QAAQ,EAAE,OAAO,MAAM,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiHG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,MAAM,gBAAgB,CAAC,CAAC,CAAC,KAAG,CAAC,YAAY,EAAE,CAAC,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC,CAAC,CASxG,CAAA"}

package/dist/NonEmptyIterable.js

@@ -1,26 +1,34 @@
 /**
- * @since 2.0.0
+ * The `NonEmptyIterable` module provides a type-level representation of any
+ * JavaScript `Iterable` that is known to contain at least one element. A
+ * `NonEmptyIterable<A>` can be consumed anywhere an `Iterable<A>` is expected,
+ * while also carrying the guarantee that reading the first element is safe.
+ *
+ * **Mental model**
  *
- * The `NonEmptyIterable` module provides types and utilities for working with iterables
- * that are guaranteed to contain at least one element. This provides compile-time
- * safety when working with collections that must not be empty.
+ * - `NonEmptyIterable<A>` is an `Iterable<A>` branded with a non-empty guarantee
+ * - The guarantee is static: values should only be typed this way when construction or validation proves at least one element exists
+ * - The iterable can be an array, string, set, map, generator, or any custom iterable
+ * - `unprepend` safely separates the first element from an iterator for the remaining elements
+ * - Operations that may remove elements, such as filtering, usually return ordinary collections because they can become empty
  *
- * ## Key Features
+ * **Common tasks**
  *
- * - **Type Safety**: Compile-time guarantee that the iterable contains at least one element
- * - **Iterator Protocol**: Fully compatible with JavaScript's built-in iteration protocol
- * - **Functional Operations**: Safe operations that preserve the non-empty property
- * - **Lightweight**: Minimal overhead with maximum type safety
+ * - Accept inputs that must contain at least one value
+ * - Extract a head element and process the remaining iterator with {@link unprepend}
+ * - Model APIs such as reductions, comparisons, or aggregation that are undefined for empty inputs
+ * - Preserve compatibility with the JavaScript iteration protocol while documenting the stronger invariant
  *
- * ## Why NonEmptyIterable?
+ * **Gotchas**
  *
- * Many operations require non-empty collections to be meaningful:
- * - Finding the maximum or minimum value
- * - Getting the first or last element
- * - Reducing without an initial value
- * - Operations that would otherwise need runtime checks
+ * - A type assertion does not make an empty iterable non-empty; only assert after a trusted check or constructor
+ * - Iterators are stateful, so calling {@link unprepend} consumes the first yielded value from that iterator
+ * - The order of the first element follows the source iterable's iteration order, for example insertion order for `Map` and `Set`
+ * - Some transformations preserve non-emptiness, but transformations that can discard elements must account for the empty case
  *
- * ## Basic Usage
+ * **Quickstart**
+ *
+ * **Example** (Requiring a non-empty iterable)
  *
  * ```ts
  * import * as NonEmptyIterable from "effect/NonEmptyIterable"
@@ -58,6 +66,8 @@
  *
  * ## Working with Different Iterable Types
  *
+ * **Example** (Adapting iterable inputs)
+ *
  * ```ts
  * import { Array } from "effect"
  *
@@ -103,10 +113,11 @@
  *
  * ## Integration with Effect Arrays
  *
+ * **Example** (Processing non-empty iterables with Array)
+ *
  * ```ts
  * import { Array, pipe } from "effect"
  * import type * as NonEmptyIterable from "effect/NonEmptyIterable"
- * import type * as NonEmptyIterable from "effect/NonEmptyIterable"
  *
  * // Many Array functions work with NonEmptyIterable
  * declare const nonEmptyData: NonEmptyIterable.NonEmptyIterable<number>
@@ -127,6 +138,8 @@
  *   // This would still be non-empty if the source was non-empty
  * )
  * ```
+ *
+ * @since 2.0.0
  */
 /**
  * Safely extracts the first element and remaining elements from a non-empty iterable.
@@ -135,10 +148,8 @@
  * head (first element) and tail (remaining elements as an iterator). Since the
  * iterable is guaranteed to be non-empty, the first element is always available.
  *
- * @param self - The non-empty iterable to deconstruct
- * @returns A tuple containing the first element and an iterator for the remaining elements
+ * **Example** (Extracting first and remaining elements)
  *
- * @example
  * ```ts
  * import { Array } from "effect"
  * import * as Chunk from "effect/Chunk"
@@ -238,6 +249,9 @@
  * const sum = reduceNonEmpty(data, (acc, x) => acc + x, 0) // 10
  * ```
  *
+ * @param self - The non-empty iterable to deconstruct
+ * @returns A tuple containing the first element and an iterator for the remaining elements
+ *
  * @category getters
  * @since 2.0.0
  */

package/dist/NonEmptyIterable.js.map

@@ -1 +1 @@
-{"version":3,"file":"NonEmptyIterable.js","names":["unprepend","self","iterator","Symbol","next","done","Error","value"],"sources":["../src/NonEmptyIterable.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6NA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiHA,OAAO,MAAMA,SAAS,GAAOC,IAAyB,IAAuD;EAC3G,MAAMC,QAAQ,GAAGD,IAAI,CAACE,MAAM,CAACD,QAAQ,CAAC,EAAE;EACxC,MAAME,IAAI,GAAGF,QAAQ,CAACE,IAAI,EAAE;EAC5B,IAAIA,IAAI,CAACC,IAAI,EAAE;IACb,MAAM,IAAIC,KAAK,CACb,kHAAkH,CACnH;EACH;EACA,OAAO,CAACF,IAAI,CAACG,KAAK,EAAEL,QAAQ,CAAC;AAC/B,CAAC","ignoreList":[]}
+{"version":3,"file":"NonEmptyIterable.js","names":["unprepend","self","iterator","Symbol","next","done","Error","value"],"sources":["../src/NonEmptyIterable.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyNA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkHA,OAAO,MAAMA,SAAS,GAAOC,IAAyB,IAAuD;EAC3G,MAAMC,QAAQ,GAAGD,IAAI,CAACE,MAAM,CAACD,QAAQ,CAAC,EAAE;EACxC,MAAME,IAAI,GAAGF,QAAQ,CAACE,IAAI,EAAE;EAC5B,IAAIA,IAAI,CAACC,IAAI,EAAE;IACb,MAAM,IAAIC,KAAK,CACb,kHAAkH,CACnH;EACH;EACA,OAAO,CAACF,IAAI,CAACG,KAAK,EAAEL,QAAQ,CAAC;AAC/B,CAAC","ignoreList":[]}