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

package/dist/RefSubject/RefIterable.js

@@ -2,14 +2,27 @@
  * Extensions to RefSubject for working with Iterable values
  * @since 1.18.0
  */
+import { Result } from "effect";
 import { equals } from "effect/Equal";
 import { dual } from "effect/Function";
 import * as Iterable from "effect/Iterable";
+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
+ * @category Constructors
  */
 export function make(initial) {
     return RefSubject.make(initial, { eq: equals });
@@ -19,118 +32,282 @@ 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
+ * @category State updates
  */
 export const prepend = dual(2, function prepend(ref, value) {
     return RefSubject.update(ref, Iterable.prepend(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
+ * @category State updates
  */
 export const prependAll = dual(2, function prependAll(ref, value) {
     return RefSubject.update(ref, Iterable.prependAll(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
+ * @category State updates
  */
 export const append = dual(2, function append(ref, value) {
     return RefSubject.update(ref, Iterable.append(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
+ * @category State updates
  */
 export const appendAll = dual(2, function appendAll(ref, value) {
     return RefSubject.update(ref, Iterable.appendAll(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
+ * @category State updates
  */
 export const drop = dual(2, function drop(ref, n) {
     return RefSubject.update(ref, Iterable.drop(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
+ * @category State updates
  */
 export const take = dual(2, function take(ref, n) {
     return RefSubject.update(ref, Iterable.take(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
+ * @category State updates
  */
 export const takeWhile = dual(2, function takeWhile(ref, predicate) {
     return RefSubject.update(ref, Iterable.takeWhile(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
+ * @category State updates
  */
 export const filter = dual(2, function filter(ref, predicate) {
     return RefSubject.update(ref, Iterable.filter(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
+ * @category State updates
  */
 export const map = dual(2, function map(ref, f) {
     return RefSubject.update(ref, Iterable.map(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
+ * @category State updates
  */
 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
+ * @category State updates
  */
 export const intersperse = dual(2, function intersperse(ref, middle) {
     return RefSubject.update(ref, Iterable.intersperse(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
+ * @category State updates
  */
 export const repeat = dual(2, function repeat(ref, n) {
     return RefSubject.update(ref, Iterable.repeat(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
+ * @category State updates
  */
 export const flatMap = dual(2, function flatMap(ref, f) {
     return RefSubject.update(ref, Iterable.flatMap(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
+ * @category State updates
  */
 export const filterMap = dual(2, function filterMap(ref, f) {
-    return RefSubject.update(ref, Iterable.filterMap(f));
+    return RefSubject.update(ref, Iterable.filterMap((a, index) => Option.match(f(a, index), {
+        onNone: () => Result.failVoid,
+        onSome: (b) => Result.succeed(b),
+    })));
 });
 /**
  * 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
+ * @category State updates
  */
 export const getSomes = (ref) => RefSubject.update(ref, (iter) => Iterable.getSomes(iter));
 // ========================================
@@ -138,76 +315,186 @@ 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
+ * @category State predicates
  */
 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
+ * @category Derived queries
  */
 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
+ * @category Derived queries
  */
 export const mapValues = dual(2, function mapValues(ref, f) {
     return RefSubject.map(ref, Iterable.map(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
+ * @category Derived queries
  */
 export const filterValues = dual(2, function filterValues(ref, predicate) {
     return RefSubject.map(ref, Iterable.filter(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
+ * @category Derived queries
  */
 export const groupBy = dual(2, function groupBy(ref, f) {
     return RefSubject.map(ref, Iterable.groupBy(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
+ * @category Derived queries
  */
 export const reduce = dual(3, function reduce(ref, b, f) {
     return RefSubject.map(ref, Iterable.reduce(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
+ * @category State predicates
  */
 export const some = dual(2, function some(ref, predicate) {
     return RefSubject.map(ref, Iterable.some(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
+ * @category State predicates
  */
 export const contains = dual(2, function contains(ref, value) {
     return RefSubject.map(ref, Iterable.contains(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
+ * @category Derived queries
  */
 export const countBy = dual(2, function countBy(ref, predicate) {
     return RefSubject.map(ref, Iterable.countBy(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
+ * @category Derived queries
  */
 export const toArray = (ref) => RefSubject.map(ref, (iter) => Array.from(iter));
 // ========================================
@@ -215,22 +502,55 @@ 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
+ * @category Optional queries
  */
 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
+ * @category Optional queries
  */
 export const findFirst = dual(2, function findFirst(ref, predicate) {
     return RefSubject.filterMap(ref, Iterable.findFirst(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
+ * @category Optional queries
  */
 export const findLast = dual(2, function findLast(ref, predicate) {
     return RefSubject.filterMap(ref, Iterable.findLast(predicate));