@typed/fx 2.0.0-beta.4 → 2.0.0-beta.6

package/dist/RefSubject/RefIterable.js

@@ -10,6 +10,17 @@ import * as Option from "effect/Option";
 import * as RefSubject from "./RefSubject.js";
 /**
  * Creates a new `RefIterable` from an Iterable, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates iterable 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.
+ *
  * @since 1.18.0
  * @category constructors
  */
@@ -21,6 +32,17 @@ export function make(initial) {
 // ========================================
 /**
  * Prepend a value to the current state of a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Expresses prepend as one ordered iterable transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running prepend performs one serialized iterable 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
  */
@@ -29,6 +51,17 @@ export const prepend = dual(2, function prepend(ref, value) {
 });
 /**
  * Prepend an iterable of values to the current state of a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Expresses prepend all as one ordered iterable transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running prepend all performs one serialized iterable 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
  */
@@ -37,6 +70,17 @@ export const prependAll = dual(2, function prependAll(ref, value) {
 });
 /**
  * Append a value to the current state of a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Expresses append as one ordered iterable transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running append performs one serialized iterable 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
  */
@@ -45,6 +89,17 @@ export const append = dual(2, function append(ref, value) {
 });
 /**
  * Append an iterable of values to the current state of a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Expresses append all as one ordered iterable transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running append all performs one serialized iterable 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
  */
@@ -53,6 +108,17 @@ export const appendAll = dual(2, function appendAll(ref, value) {
 });
 /**
  * Drop the first `n` values from a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Applies drop to the committed iterable value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running drop performs one serialized iterable 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
  */
@@ -61,6 +127,17 @@ export const drop = dual(2, function drop(ref, n) {
 });
 /**
  * Take the first `n` values from a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Applies take to the committed iterable value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take performs one serialized iterable 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
  */
@@ -69,6 +146,17 @@ export const take = dual(2, function take(ref, n) {
 });
 /**
  * Take values from a RefIterable while a predicate is true.
+ * @remarks
+ * ## Why
+ *
+ * Applies take while to the committed iterable value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take while performs one serialized iterable 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
  */
@@ -77,6 +165,16 @@ export const takeWhile = dual(2, function takeWhile(ref, predicate) {
 });
 /**
  * Filter the values of a RefIterable (mutating).
+ * @remarks
+ * ## Why
+ *
+ * Applies filter to the committed Iterable through `RefSubject.update` and publishes one coherent
+ * replacement; this is a mutation, not a read-only Computed projection.
+ *
+ * ## 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 Iterable and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -85,6 +183,16 @@ export const filter = dual(2, function filter(ref, predicate) {
 });
 /**
  * Map (Endomorphic) the values of a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Applies map to the committed Iterable through `RefSubject.update` and publishes one coherent
+ * replacement; this is a mutation, not a read-only Computed projection.
+ *
+ * ## 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 Iterable and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -93,12 +201,34 @@ export const map = dual(2, function map(ref, f) {
 });
 /**
  * Remove adjacent duplicate values from a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered iterable through its Effect collection operation while retaining
+ * RefSubject equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running dedupe adjacent performs one serialized iterable 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
  */
 export const dedupeAdjacent = (ref) => RefSubject.update(ref, Iterable.dedupeAdjacent);
 /**
  * Intersperse a separator between elements.
+ * @remarks
+ * ## Why
+ *
+ * Intersperse a separator between elements. The operation remains attached to the RefSubject's
+ * versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running intersperse performs one serialized iterable 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
  */
@@ -107,6 +237,17 @@ export const intersperse = dual(2, function intersperse(ref, middle) {
 });
 /**
  * Repeat the iterable n times.
+ * @remarks
+ * ## Why
+ *
+ * Repeat the iterable n times. The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running repeat performs one serialized iterable 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
  */
@@ -115,6 +256,17 @@ export const repeat = dual(2, function repeat(ref, n) {
 });
 /**
  * FlatMap (endomorphic).
+ * @remarks
+ * ## Why
+ *
+ * FlatMap (endomorphic). The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running flat map performs one serialized iterable 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
  */
@@ -123,6 +275,16 @@ export const flatMap = dual(2, function flatMap(ref, f) {
 });
 /**
  * Filter and map values in place.
+ * @remarks
+ * ## Why
+ *
+ * Applies `filterMap` to the committed Iterable through `RefSubject.update` and publishes one
+ * coherent replacement; this is a mutation, not a read-only Computed projection.
+ *
+ * ## 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 Iterable and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -134,6 +296,16 @@ export const filterMap = dual(2, function filterMap(ref, f) {
 });
 /**
  * Extract Some values from Option iterable.
+ * @remarks
+ * ## Why
+ *
+ * Applies `getSomes` to the committed Iterable through `RefSubject.update` and publishes one
+ * coherent replacement; this is a mutation, not a read-only Computed projection.
+ *
+ * ## 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 Iterable and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -143,18 +315,51 @@ export const getSomes = (ref) => RefSubject.update(ref, (iter) => Iterable.getSo
 // ========================================
 /**
  * Check if a RefIterable is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the iterable; 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, Iterable.isEmpty);
 /**
  * Get the current size of a RefIterable.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the iterable; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The size 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 size = (ref) => RefSubject.map(ref, Iterable.size);
 /**
  * Map the values of a RefIterable to a different type.
+ * @remarks
+ * ## Why
+ *
+ * Projects iterable 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
  */
@@ -163,6 +368,17 @@ export const mapValues = dual(2, function mapValues(ref, f) {
 });
 /**
  * Filter the values of a RefIterable creating a Computed value.
+ * @remarks
+ * ## Why
+ *
+ * Projects iterable 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
  */
@@ -171,6 +387,17 @@ export const filterValues = dual(2, function filterValues(ref, predicate) {
 });
 /**
  * Group the values of a RefIterable by a key.
+ * @remarks
+ * ## Why
+ *
+ * Projects iterable 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
  */
@@ -179,6 +406,17 @@ export const groupBy = dual(2, function groupBy(ref, f) {
 });
 /**
  * Reduce the values of a RefIterable to a single value.
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce a live projection of the iterable; 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
  */
@@ -187,6 +425,17 @@ export const reduce = dual(3, function reduce(ref, b, f) {
 });
 /**
  * Check if any value satisfies a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes some a live projection of the iterable; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The some 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
  */
@@ -195,6 +444,17 @@ export const some = dual(2, function some(ref, predicate) {
 });
 /**
  * Check if a RefIterable contains a value.
+ * @remarks
+ * ## Why
+ *
+ * Makes contains a live projection of the iterable; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The contains 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
  */
@@ -203,6 +463,17 @@ export const contains = dual(2, function contains(ref, value) {
 });
 /**
  * Count elements satisfying a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes count by a live projection of the iterable; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The count 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
  */
@@ -211,6 +482,17 @@ export const countBy = dual(2, function countBy(ref, predicate) {
 });
 /**
  * Convert to array.
+ * @remarks
+ * ## Why
+ *
+ * Projects iterable state with to array for both current reads and future pushes, avoiding a
+ * second mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The to array 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
  */
@@ -220,12 +502,34 @@ export const toArray = (ref) => RefSubject.map(ref, (iter) => Array.from(iter));
 // ========================================
 /**
  * Get the first element of a RefIterable 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.
+ *
  * @since 1.18.0
  * @category filtered
  */
 export const head = (ref) => RefSubject.filterMap(ref, Iterable.head);
 /**
  * Find the first value satisfying a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of find first as Filtered state, so absence stays explicit
+ * while later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The find first 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
  */
@@ -234,6 +538,17 @@ export const findFirst = dual(2, function findFirst(ref, predicate) {
 });
 /**
  * Find the last value satisfying a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of find last as Filtered state, so absence stays explicit
+ * while later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The find last 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
  */