@typed/fx 2.0.0-beta.3 → 2.0.0-beta.5

package/dist/RefSubject/RefArray.js

@@ -12,10 +12,21 @@ 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* () {
@@ -42,6 +53,17 @@ export function make(initial, eq = equals) {
 }
 /**
  * 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
  */
@@ -50,6 +72,17 @@ export const prepend = dual(2, function prepend(ref, 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
  */
@@ -58,6 +91,17 @@ export const prependAll = dual(2, function prependAll(ref, 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
  */
@@ -66,6 +110,17 @@ export const append = dual(2, function append(ref, 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
  */
@@ -74,6 +129,17 @@ export const appendAll = dual(2, function appendAll(ref, 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
  */
@@ -82,6 +148,17 @@ export const drop = dual(2, function drop(ref, 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
  */
@@ -90,6 +167,17 @@ export const dropRight = dual(2, function dropRight(ref, 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
  */
@@ -98,6 +186,17 @@ export const dropWhile = dual(2, function dropWhile(ref, 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
  */
@@ -106,6 +205,17 @@ export const filterValues = dual(2, function filterValues(ref, 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
  */
@@ -114,6 +224,17 @@ export const getIndex = dual(2, function getIndex(ref, 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
  */
@@ -122,6 +243,17 @@ export const groupBy = dual(2, function groupBy(ref, 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
  */
@@ -130,24 +262,74 @@ export const insertAt = dual(3, function insertAt(ref, index, 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
  */
 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
  */
 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
  */
 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
  */
@@ -156,6 +338,17 @@ export const map = dual(2, function mapValues(ref, 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
  */
@@ -164,6 +357,17 @@ export const mapValues = dual(2, function mapValues(ref, 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
  */
@@ -172,6 +376,17 @@ export const modifyAt = dual(3, function modifyAt(ref, index, f) {
 });
 /**
  * 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
  */
@@ -180,6 +395,17 @@ export const partition = dual(2, function partition(ref, predicate) {
 });
 /**
  * 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
  */
@@ -188,6 +414,17 @@ export const reduce = dual(3, function reduce(ref, 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
  */
@@ -196,6 +433,17 @@ export const reduceRight = dual(3, function reduceRight(ref, 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
  */
@@ -204,6 +452,17 @@ export const replaceAt = dual(3, function replaceAt(ref, index, a) {
 });
 /**
  * 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
  */
@@ -212,6 +471,17 @@ export const rotate = dual(2, function rotate(ref, 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
  */
@@ -220,6 +490,17 @@ export const sortBy = dual(2, function sortBy(ref, 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
  */
@@ -228,6 +509,17 @@ export const take = dual(2, function take(ref, 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
  */
@@ -236,6 +528,17 @@ export const takeRight = dual(2, function takeRight(ref, 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
  */
@@ -244,6 +547,17 @@ export const takeWhile = dual(2, function takeWhile(ref, 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
  */
@@ -251,10 +565,21 @@ export const dedupeWith = (valueEq) => (ref) => RefSubject.update(ref, ReadonlyA
 /**
  * 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])
@@ -276,10 +601,21 @@ 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])