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

package/dist/RefSubject/RefChunk.d.ts

@@ -11,6 +11,17 @@ import type * as Fx from "../Fx/index.js";
 import * as RefSubject from "./RefSubject.js";
 /**
  * A RefChunk is a RefSubject specialized over a Chunk of values.
+ * @remarks
+ * ## Why
+ *
+ * Defines chunk state with the same current-read, pushed-update, and synchronized-write contract
+ * as RefSubject.
+ *
+ * ## Ownership and lifetime
+ *
+ * RefChunk is a contract and performs no acquisition. Implementations retain the errors, services,
+ * interruption, and Scope requirements expressed by its members.
+ *
  * @since 1.18.0
  * @category models
  */
@@ -18,12 +29,34 @@ export interface RefChunk<in out A, in out E = never, out R = never> extends Ref
 }
 /**
  * Creates a new `RefChunk` from a Chunk, `Effect`, or `Fx`.
+ * @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 declare function make<A, E, R>(initial: Chunk.Chunk<A> | Effect.Effect<Chunk.Chunk<A>, E, R> | Fx.Fx<Chunk.Chunk<A>, E, R>, eq?: Equivalence<A>): Effect.Effect<RefChunk<A, E>, never, R | Scope.Scope>;
+export declare function make<A, E = never, R = never>(initial: Chunk.Chunk<A> | Effect.Effect<Chunk.Chunk<A>, E, R> | Fx.Fx<Chunk.Chunk<A>, E, R>, eq?: Equivalence<A>): Effect.Effect<RefChunk<A, E>, never, R | Scope.Scope>;
 /**
  * Prepend a value to the current state of a RefChunk.
+ * @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 combinators
  */
@@ -33,6 +66,17 @@ export declare const prepend: {
 };
 /**
  * Prepend an iterable of values to the current state of a RefChunk.
+ * @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 combinators
  */
@@ -42,6 +86,17 @@ export declare const prependAll: {
 };
 /**
  * Append a value to the current state of a RefChunk.
+ * @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 combinators
  */
@@ -51,6 +106,17 @@ export declare const append: {
 };
 /**
  * Append an iterable of values to the current state of a RefChunk.
+ * @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 combinators
  */
@@ -60,6 +126,17 @@ export declare const appendAll: {
 };
 /**
  * Drop the first `n` values from a RefChunk.
+ * @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 combinators
  */
@@ -69,6 +146,17 @@ export declare const drop: {
 };
 /**
  * Drop the last `n` values from a RefChunk.
+ * @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 combinators
  */
@@ -78,6 +166,17 @@ export declare const dropRight: {
 };
 /**
  * Drop values from a RefChunk while a predicate is true.
+ * @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 combinators
  */
@@ -87,6 +186,17 @@ export declare const dropWhile: {
 };
 /**
  * Take the first `n` values from a RefChunk.
+ * @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 combinators
  */
@@ -96,6 +206,17 @@ export declare const take: {
 };
 /**
  * Take the last `n` values from a RefChunk.
+ * @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 combinators
  */
@@ -105,6 +226,17 @@ export declare const takeRight: {
 };
 /**
  * Take values from a RefChunk while a predicate is true.
+ * @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 combinators
  */
@@ -114,6 +246,17 @@ export declare const takeWhile: {
 };
 /**
  * Modify the value at a particular index of a RefChunk.
+ * @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 combinators
  */
@@ -123,6 +266,17 @@ export declare const modifyAt: {
 };
 /**
  * Replace a value at a particular index of a RefChunk.
+ * @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 combinators
  */
@@ -132,6 +286,17 @@ export declare const replaceAt: {
 };
 /**
  * Remove a value at a particular index of a RefChunk.
+ * @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 combinators
  */
@@ -141,6 +306,16 @@ export declare const remove: {
 };
 /**
  * Filter the values of a RefChunk (mutating).
+ * @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 combinators
  */
@@ -150,6 +325,16 @@ export declare const filter: {
 };
 /**
  * Map (Endomorphic) the values of a RefChunk.
+ * @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 combinators
  */
@@ -159,24 +344,68 @@ export declare const map: {
 };
 /**
  * Remove duplicate values from a RefChunk.
+ * @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 combinators
  */
 export declare const dedupe: <A, E, R>(ref: RefChunk<A, E, R>) => Effect.Effect<Chunk.Chunk<A>, E, R>;
 /**
  * Remove adjacent duplicate values from a RefChunk.
+ * @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 combinators
  */
 export declare const dedupeAdjacent: <A, E, R>(ref: RefChunk<A, E, R>) => Effect.Effect<Chunk.Chunk<A>, E, R>;
 /**
  * Reverse the values of a RefChunk.
+ * @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 combinators
  */
 export declare const reverse: <A, E, R>(ref: RefChunk<A, E, R>) => Effect.Effect<Chunk.Chunk<A>, E, R>;
 /**
  * Sort the values of a RefChunk using a provided Order.
+ * @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 combinators
  */
@@ -186,24 +415,68 @@ export declare const sort: {
 };
 /**
  * Check if a RefChunk is empty.
+ * @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 computed
  */
 export declare const isEmpty: <A, E, R>(ref: RefChunk<A, E, R>) => RefSubject.Computed<boolean, E, R>;
 /**
  * Check if a RefChunk is non-empty.
+ * @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 computed
  */
 export declare const isNonEmpty: <A, E, R>(ref: RefChunk<A, E, R>) => RefSubject.Computed<boolean, E, R>;
 /**
  * Get the current size of a RefChunk.
+ * @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 computed
  */
 export declare const size: <A, E, R>(ref: RefChunk<A, E, R>) => RefSubject.Computed<number, E, R>;
 /**
  * Map the values of a RefChunk to a different type.
+ * @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 computed
  */
@@ -213,6 +486,17 @@ export declare const mapValues: {
 };
 /**
  * Filter the values of a RefChunk creating a Computed value.
+ * @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 computed
  */
@@ -222,6 +506,17 @@ export declare const filterValues: {
 };
 /**
  * Partition the values of a RefChunk using a predicate.
+ * @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 computed
  */
@@ -231,6 +526,17 @@ export declare const partition: {
 };
 /**
  * Reduce the values of a RefChunk to a single value.
+ * @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 computed
  */
@@ -240,6 +546,17 @@ export declare const reduce: {
 };
 /**
  * Reduce the values of a RefChunk in reverse order.
+ * @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 computed
  */
@@ -249,6 +566,17 @@ export declare const reduceRight: {
 };
 /**
  * Check if any value satisfies a predicate.
+ * @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 computed
  */
@@ -258,6 +586,17 @@ export declare const some: {
 };
 /**
  * Check if all values satisfy a predicate.
+ * @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 computed
  */
@@ -267,6 +606,17 @@ export declare const every: {
 };
 /**
  * Check if a RefChunk contains a value.
+ * @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 computed
  */
@@ -276,6 +626,17 @@ export declare const contains: {
 };
 /**
  * Get a value at a particular index of a RefChunk.
+ * @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
  */
@@ -285,18 +646,51 @@ export declare const getIndex: {
 };
 /**
  * Get the first element of a RefChunk 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 declare const head: <A, E, R>(ref: RefChunk<A, E, R>) => RefSubject.Filtered<A, E, R>;
 /**
  * Get the last element of a RefChunk 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.
+ *
  * @since 1.18.0
  * @category filtered
  */
 export declare const last: <A, E, R>(ref: RefChunk<A, E, R>) => RefSubject.Filtered<A, E, R>;
 /**
  * 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
  */
@@ -306,6 +700,17 @@ export declare const findFirst: {
 };
 /**
  * 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
  */