@typed/fx 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/RefSubject/RefArray.js

@@ -8,13 +8,25 @@ import * as Equivalence_ from "effect/Equivalence";
 import { dual } from "effect/Function";
 import * as Option from "effect/Option";
 import * as RefSubject from "./RefSubject.js";
+import { Result } from "effect";
 /**
  * Creates a new `RefArray` from an array, `Effect`, or `Fx`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Creates array state with equality suited to that Effect data type, so unchanged values do not
+ * produce redundant pushed updates.
+ *
+ * ## Ownership and lifetime
+ *
+ * The creation Effect requires Scope. It owns initializer acquisition, live source subscriptions,
+ * and cleanup; source failures and services stay on reads and pushes.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
- * import * as RefArray from "@typed/fx/RefSubject/RefArray"
+ * import * as RefArray from "@typed/fx/RefArray"
  *
  * // From a plain array
  * const program1 = Effect.gen(function* () {
@@ -34,229 +46,540 @@ import * as RefSubject from "./RefSubject.js";
  * ```
  *
  * @since 1.18.0
- * @category constructors
+ * @category Constructors
  */
 export function make(initial, eq = equals) {
     return RefSubject.make(initial, { eq: Equivalence_.Array(eq) });
 }
 /**
  * Prepend a value to the current state of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Expresses prepend as one ordered array transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running prepend performs one serialized array transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const prepend = dual(2, function prepend(ref, value) {
     return RefSubject.update(ref, ReadonlyArray.prepend(value));
 });
 /**
  * Prepend an iterable of values to the current state of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Expresses prepend all as one ordered array transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running prepend all performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const prependAll = dual(2, function prependAll(ref, value) {
     return RefSubject.update(ref, ReadonlyArray.prependAll(value));
 });
 /**
  * Append a value to the current state of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Expresses append as one ordered array transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running append performs one serialized array transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const append = dual(2, function append(ref, value) {
     return RefSubject.update(ref, ReadonlyArray.append(value));
 });
 /**
  * Append an iterable of values to the current state of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Expresses append all as one ordered array transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running append all performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const appendAll = dual(2, function appendAll(ref, value) {
     return RefSubject.update(ref, ReadonlyArray.appendAll(value));
 });
 /**
  * Drop the first `n` values from a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Applies drop to the committed array value and publishes only the result, preserving its element
+ * order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running drop performs one serialized array transition and resolves with its committed value. It
+ * acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const drop = dual(2, function drop(ref, n) {
     return RefSubject.update(ref, ReadonlyArray.drop(n));
 });
 /**
  * Drop the last `n` values from a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Applies drop right to the committed array value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running drop right performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const dropRight = dual(2, function dropRight(ref, n) {
     return RefSubject.update(ref, ReadonlyArray.dropRight(n));
 });
 /**
  * Drop values from a RefArray while a predicate is true.
+ * @remarks
+ * ## Why
+ *
+ * Applies drop while to the committed array value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running drop while performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const dropWhile = dual(2, function dropWhile(ref, predicate) {
     return RefSubject.update(ref, ReadonlyArray.dropWhile(predicate));
 });
 /**
  * Filter the values of a RefArray using a predicate creating a Computed value.
+ * @remarks
+ * ## Why
+ *
+ * Projects array state with filter values for both current reads and future pushes, avoiding a
+ * second mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The filter values view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const filterValues = dual(2, function filterValues(ref, predicate) {
     return RefSubject.map(ref, ReadonlyArray.filter(predicate));
 });
 /**
  * Get a value contained a particular index of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of get index as Filtered state, so absence stays explicit
+ * while later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get index view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @since 1.18.0
- * @category filtered
+ * @category Optional queries
  */
 export const getIndex = dual(2, function getIndex(ref, index) {
     return RefSubject.filterMap(ref, ReadonlyArray.get(index));
 });
 /**
  * Group the values of a RefArray by a key.
+ * @remarks
+ * ## Why
+ *
+ * Projects array state with group by for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The group by view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const groupBy = dual(2, function groupBy(ref, f) {
     return RefSubject.map(ref, ReadonlyArray.groupBy(f));
 });
 /**
  * Insert a value at a particular index of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Expresses insert at as one ordered array transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running insert at performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const insertAt = dual(3, function insertAt(ref, index, a) {
-    return RefSubject.update(ref, (as) => Option.getOrElse(Option.fromUndefinedOr(ReadonlyArray.insertAt(as, index, a)), () => [
-        ...as,
-        a,
-    ]));
+    return RefSubject.update(ref, (as) => Option.getOrElse(ReadonlyArray.insertAt(as, index, a), () => [...as, a]));
 });
 /**
  * Check to see if a RefArray is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the array; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is empty view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const isEmpty = (ref) => RefSubject.map(ref, ReadonlyArray.isReadonlyArrayEmpty);
 /**
  * Check to see if a RefArray is non-empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is non empty a live projection of the array; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is non empty view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const isNonEmpty = (ref) => RefSubject.map(ref, ReadonlyArray.isReadonlyArrayNonEmpty);
 /**
  * Get the current length of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Makes length a live projection of the array; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The length view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const length = (ref) => RefSubject.map(ref, ReadonlyArray.length);
 /**
  * Map (Endomorphic) the values of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * The implementation applies the endomorphic map through `RefSubject.update`, replacing the
+ * writable RefArray in one serialized transition. The published Computed return type does not
+ * describe that runtime behavior.
+ *
+ * ## Ownership and lifetime
+ *
+ * The Effect starts when run, participates in the source ref's serialized update boundary, and
+ * acquires no resource. It returns the committed array and retains the ref's E and R channels.
+ * ## Known API defect
+ *
+ * The public overloads currently declare `Computed<ReadonlyArray<A>, E, R>`, but the implementation
+ * returns the update Effect from `RefSubject.update`. This documentation reports the shipped mismatch;
+ * changing that signature or runtime behavior requires a separate compatibility decision.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const map = dual(2, function mapValues(ref, f) {
     return RefSubject.update(ref, ReadonlyArray.map(f));
 });
 /**
  * Map the values with their indexes of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Projects array state with map values for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The map values view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const mapValues = dual(2, function mapValues(ref, f) {
     return RefSubject.map(ref, ReadonlyArray.map(f));
 });
 /**
  * Modify the value at a particular index of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Keeps modify at atomic with respect to competing RefSubject writes instead of splitting the read
+ * and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running modify at performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const modifyAt = dual(3, function modifyAt(ref, index, f) {
-    return RefSubject.update(ref, (values) => ReadonlyArray.modify(values, index, f) || values);
+    return RefSubject.update(ref, (values) => Option.getOrElse(ReadonlyArray.modify(values, index, f), () => values));
 });
 /**
  * Partition the values of a RefArray using a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Partition the values of a RefArray using a predicate. The operation remains attached to the
+ * RefSubject's versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The partition view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const partition = dual(2, function partition(ref, predicate) {
-    return RefSubject.map(ref, ReadonlyArray.partition(predicate));
+    return RefSubject.map(ref, (array) => ReadonlyArray.partition(array, Result.liftPredicate(predicate, Result.fail)));
 });
 /**
  * Reduce the values of a RefArray to a single value.
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce a live projection of the array; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The reduce view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const reduce = dual(3, function reduce(ref, b, f) {
     return RefSubject.map(ref, ReadonlyArray.reduce(b, f));
 });
 /**
  * Reduce the values of a RefArray to a single value in reverse order.
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce right a live projection of the array; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The reduce right view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const reduceRight = dual(3, function reduceRight(ref, b, f) {
     return RefSubject.map(ref, ReadonlyArray.reduceRight(b, f));
 });
 /**
  * Replace a value at a particular index of a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Keeps replace at atomic with respect to competing RefSubject writes instead of splitting the
+ * read and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running replace at performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const replaceAt = dual(3, function replaceAt(ref, index, a) {
-    return RefSubject.update(ref, (values) => ReadonlyArray.replace(values, index, a) || values);
+    return RefSubject.update(ref, (values) => Option.getOrElse(ReadonlyArray.replace(values, index, a), () => values));
 });
 /**
  * Rotate the values of a RefArray by `n` places. Helpful for things like carousels.
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered array through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running rotate performs one serialized array transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const rotate = dual(2, function rotate(ref, n) {
     return RefSubject.update(ref, ReadonlyArray.rotate(n));
 });
 /**
  * Sort the values of a RefArray using a provided Order.
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered array through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running sort by performs one serialized array transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const sortBy = dual(2, function sortBy(ref, orders) {
     return RefSubject.update(ref, ReadonlyArray.sortBy(...orders));
 });
 /**
  * Take the first `n` values from a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Applies take to the committed array value and publishes only the result, preserving its element
+ * order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take performs one serialized array transition and resolves with its committed value. It
+ * acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const take = dual(2, function take(ref, n) {
     return RefSubject.update(ref, ReadonlyArray.take(n));
 });
 /**
  * Take the last `n` values from a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Applies take right to the committed array value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take right performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const takeRight = dual(2, function takeRight(ref, n) {
     return RefSubject.update(ref, ReadonlyArray.takeRight(n));
 });
 /**
  * Take values from a RefArray while a predicate is true.
+ * @remarks
+ * ## Why
+ *
+ * Applies take while to the committed array value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take while performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const takeWhile = dual(2, function takeWhile(ref, predicate) {
     return RefSubject.update(ref, ReadonlyArray.takeWhile(predicate));
 });
 /**
  * Remove any duplicate values from a RefArray.
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered array through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running dedupe with performs one serialized array transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const dedupeWith = (valueEq) => (ref) => RefSubject.update(ref, ReadonlyArray.dedupeWith(valueEq));
 /**
  * Gets the last element of a `RefArray` as a `Filtered`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of last as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The last view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
- * import * as RefArray from "@typed/fx/RefSubject/RefArray"
+ * import * as RefArray from "@typed/fx/RefArray"
  *
  * const program = Effect.gen(function* () {
  *   const items = yield* RefArray.make([1, 2, 3, 4, 5])
@@ -272,16 +595,27 @@ export const dedupeWith = (valueEq) => (ref) => RefSubject.update(ref, ReadonlyA
  * ```
  *
  * @since 1.18.0
- * @category filtered
+ * @category Optional queries
  */
 export const last = (ref) => RefSubject.filterMap(ref, ReadonlyArray.last);
 /**
  * Gets the first element of a `RefArray` as a `Filtered`.
  *
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of head as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The head view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
- * import * as RefArray from "@typed/fx/RefSubject/RefArray"
+ * import * as RefArray from "@typed/fx/RefArray"
  *
  * const program = Effect.gen(function* () {
  *   const items = yield* RefArray.make([1, 2, 3, 4, 5])
@@ -297,6 +631,6 @@ export const last = (ref) => RefSubject.filterMap(ref, ReadonlyArray.last);
  * ```
  *
  * @since 1.18.0
- * @category filtered
+ * @category Optional queries
  */
 export const head = (ref) => RefSubject.filterMap(ref, ReadonlyArray.head);