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

package/dist/RefSubject/RefChunk.js

@@ -5,157 +5,377 @@
 import * as Chunk from "effect/Chunk";
 import { equals } from "effect/Equal";
 import { dual } from "effect/Function";
+import * as Option from "effect/Option";
 import * as RefSubject from "./RefSubject.js";
+import { Result } from "effect";
 /**
  * Creates a new `RefChunk` from a Chunk, `Effect`, or `Fx`.
- * @since 1.18.0
- * @category constructors
+ * @remarks
+ * ## Why
+ *
+ * Creates chunk 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
  */
 export function make(initial, eq = equals) {
     return RefSubject.make(initial, { eq: Chunk.makeEquivalence(eq) });
 }
 /**
  * Prepend a value to the current state of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Expresses prepend as one ordered chunk transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running prepend performs one serialized chunk 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 State updates
  */
 export const prepend = dual(2, function prepend(ref, value) {
     return RefSubject.update(ref, Chunk.prepend(value));
 });
 /**
  * Prepend an iterable of values to the current state of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Expresses prepend all as one ordered chunk transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running prepend all performs one serialized chunk 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 State updates
  */
 export const prependAll = dual(2, function prependAll(ref, value) {
     return RefSubject.update(ref, Chunk.prependAll(Chunk.fromIterable(value)));
 });
 /**
  * Append a value to the current state of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Expresses append as one ordered chunk transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running append performs one serialized chunk 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 State updates
  */
 export const append = dual(2, function append(ref, value) {
     return RefSubject.update(ref, Chunk.append(value));
 });
 /**
  * Append an iterable of values to the current state of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Expresses append all as one ordered chunk transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running append all performs one serialized chunk 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 State updates
  */
 export const appendAll = dual(2, function appendAll(ref, value) {
     return RefSubject.update(ref, Chunk.appendAll(Chunk.fromIterable(value)));
 });
 /**
  * Drop the first `n` values from a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies drop to the committed chunk value and publishes only the result, preserving its element
+ * order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running drop performs one serialized chunk 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 State updates
  */
 export const drop = dual(2, function drop(ref, n) {
     return RefSubject.update(ref, Chunk.drop(n));
 });
 /**
  * Drop the last `n` values from a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies drop right to the committed chunk value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running drop right performs one serialized chunk 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 State updates
  */
 export const dropRight = dual(2, function dropRight(ref, n) {
     return RefSubject.update(ref, Chunk.dropRight(n));
 });
 /**
  * Drop values from a RefChunk while a predicate is true.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies drop while to the committed chunk value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running drop while performs one serialized chunk 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 State updates
  */
 export const dropWhile = dual(2, function dropWhile(ref, predicate) {
     return RefSubject.update(ref, Chunk.dropWhile(predicate));
 });
 /**
  * Take the first `n` values from a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies take to the committed chunk value and publishes only the result, preserving its element
+ * order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take performs one serialized chunk 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 State updates
  */
 export const take = dual(2, function take(ref, n) {
     return RefSubject.update(ref, Chunk.take(n));
 });
 /**
  * Take the last `n` values from a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies take right to the committed chunk value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take right performs one serialized chunk 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 State updates
  */
 export const takeRight = dual(2, function takeRight(ref, n) {
     return RefSubject.update(ref, Chunk.takeRight(n));
 });
 /**
  * Take values from a RefChunk while a predicate is true.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies take while to the committed chunk value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running take while performs one serialized chunk 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 State updates
  */
 export const takeWhile = dual(2, function takeWhile(ref, predicate) {
     return RefSubject.update(ref, Chunk.takeWhile(predicate));
 });
 /**
  * Modify the value at a particular index of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @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 chunk 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 State updates
  */
 export const modifyAt = dual(3, function modifyAt(ref, index, f) {
-    return RefSubject.update(ref, (chunk) => Chunk.modify(chunk, index, f) ?? chunk);
+    return RefSubject.update(ref, (chunk) => Option.getOrElse(Chunk.modify(chunk, index, f), () => chunk));
 });
 /**
  * Replace a value at a particular index of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @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 chunk 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 State updates
  */
 export const replaceAt = dual(3, function replaceAt(ref, index, a) {
-    return RefSubject.update(ref, (chunk) => Chunk.replace(chunk, index, a) ?? chunk);
+    return RefSubject.update(ref, (chunk) => Option.getOrElse(Chunk.replace(chunk, index, a), () => chunk));
 });
 /**
  * Remove a value at a particular index of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed chunk value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized chunk 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 State updates
  */
 export const remove = dual(2, function remove(ref, index) {
     return RefSubject.update(ref, Chunk.remove(index));
 });
 /**
  * Filter the values of a RefChunk (mutating).
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies filter to the committed chunk 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 chunk and retains the ref's E and R channels.
+ * @since 1.18.0
+ * @category State updates
  */
 export const filter = dual(2, function filter(ref, predicate) {
     return RefSubject.update(ref, Chunk.filter(predicate));
 });
 /**
  * Map (Endomorphic) the values of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Applies map to the committed chunk 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 chunk and retains the ref's E and R channels.
+ * @since 1.18.0
+ * @category State updates
  */
 export const map = dual(2, function map(ref, f) {
     return RefSubject.update(ref, Chunk.map(f));
 });
 /**
  * Remove duplicate values from a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered chunk through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running dedupe performs one serialized chunk 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 State updates
  */
 export const dedupe = (ref) => RefSubject.update(ref, Chunk.dedupe);
 /**
  * Remove adjacent duplicate values from a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered chunk through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running dedupe adjacent performs one serialized chunk 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 State updates
  */
 export const dedupeAdjacent = (ref) => RefSubject.update(ref, Chunk.dedupeAdjacent);
 /**
  * Reverse the values of a RefChunk.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered chunk through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running reverse performs one serialized chunk 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 State updates
  */
 export const reverse = (ref) => RefSubject.update(ref, Chunk.reverse);
 /**
  * Sort the values of a RefChunk using a provided Order.
- * @since 1.18.0
- * @category combinators
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered chunk through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running sort performs one serialized chunk 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 State updates
  */
 export const sort = dual(2, function sort(ref, order) {
     return RefSubject.update(ref, Chunk.sort(order));
@@ -165,82 +385,203 @@ export const sort = dual(2, function sort(ref, order) {
 // ========================================
 /**
  * Check if a RefChunk is empty.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the chunk; 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 State predicates
  */
 export const isEmpty = (ref) => RefSubject.map(ref, Chunk.isEmpty);
 /**
  * Check if a RefChunk is non-empty.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes is non empty a live projection of the chunk; 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 State predicates
  */
 export const isNonEmpty = (ref) => RefSubject.map(ref, Chunk.isNonEmpty);
 /**
  * Get the current size of a RefChunk.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the chunk; 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 Derived queries
  */
 export const size = (ref) => RefSubject.map(ref, Chunk.size);
 /**
  * Map the values of a RefChunk to a different type.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Projects chunk 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 Derived queries
  */
 export const mapValues = dual(2, function mapValues(ref, f) {
     return RefSubject.map(ref, Chunk.map(f));
 });
 /**
  * Filter the values of a RefChunk creating a Computed value.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Projects chunk 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 Derived queries
  */
 export const filterValues = dual(2, function filterValues(ref, predicate) {
     return RefSubject.map(ref, Chunk.filter(predicate));
 });
 /**
  * Partition the values of a RefChunk using a predicate.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Partition the values of a RefChunk 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 Derived queries
  */
 export const partition = dual(2, function partition(ref, predicate) {
-    return RefSubject.map(ref, Chunk.partition(predicate));
+    return RefSubject.map(ref, Chunk.partition(Result.liftPredicate(predicate, Result.fail)));
 });
 /**
  * Reduce the values of a RefChunk to a single value.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce a live projection of the chunk; 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 Derived queries
  */
 export const reduce = dual(3, function reduce(ref, b, f) {
     return RefSubject.map(ref, Chunk.reduce(b, f));
 });
 /**
  * Reduce the values of a RefChunk in reverse order.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce right a live projection of the chunk; 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 Derived queries
  */
 export const reduceRight = dual(3, function reduceRight(ref, b, f) {
     return RefSubject.map(ref, Chunk.reduceRight(b, f));
 });
 /**
  * Check if any value satisfies a predicate.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes some a live projection of the chunk; 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 State predicates
  */
 export const some = dual(2, function some(ref, predicate) {
     return RefSubject.map(ref, Chunk.some(predicate));
 });
 /**
  * Check if all values satisfy a predicate.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes every a live projection of the chunk; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The every 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 State predicates
  */
 export const every = dual(2, function every(ref, predicate) {
     return RefSubject.map(ref, Chunk.every(predicate));
 });
 /**
  * Check if a RefChunk contains a value.
- * @since 1.18.0
- * @category computed
+ * @remarks
+ * ## Why
+ *
+ * Makes contains a live projection of the chunk; 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 State predicates
  */
 export const contains = dual(2, function contains(ref, value) {
     return RefSubject.map(ref, Chunk.contains(value));
@@ -250,36 +591,91 @@ export const contains = dual(2, function contains(ref, value) {
 // ========================================
 /**
  * Get a value at a particular index of a RefChunk.
- * @since 1.18.0
- * @category filtered
+ * @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 Optional queries
  */
 export const getIndex = dual(2, function getIndex(ref, index) {
     return RefSubject.filterMap(ref, Chunk.get(index));
 });
 /**
  * Get the first element of a RefChunk as a Filtered.
- * @since 1.18.0
- * @category 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 Optional queries
  */
 export const head = (ref) => RefSubject.filterMap(ref, Chunk.head);
 /**
  * Get the last element of a RefChunk as a Filtered.
- * @since 1.18.0
- * @category 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.
+ *
+ * @since 1.18.0
+ * @category Optional queries
  */
 export const last = (ref) => RefSubject.filterMap(ref, Chunk.last);
 /**
  * Find the first value satisfying a predicate.
- * @since 1.18.0
- * @category filtered
+ * @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 Optional queries
  */
 export const findFirst = dual(2, function findFirst(ref, predicate) {
     return RefSubject.filterMap(ref, Chunk.findFirst(predicate));
 });
 /**
  * Find the last value satisfying a predicate.
- * @since 1.18.0
- * @category filtered
+ * @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 Optional queries
  */
 export const findLast = dual(2, function findLast(ref, predicate) {
     return RefSubject.filterMap(ref, Chunk.findLast(predicate));