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

package/dist/RefSubject/RefArray.d.ts

@@ -10,18 +10,40 @@ import type * as Fx from "../Fx/index.js";
 import * as RefSubject from "./RefSubject.js";
 /**
  * A RefArray is a RefSubject that is specialized over an array of values.
+ * @remarks
+ * ## Why
+ *
+ * Defines array state with the same current-read, pushed-update, and synchronized-write contract
+ * as RefSubject.
+ *
+ * ## Ownership and lifetime
+ *
+ * RefArray 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
+ * @category State models
  */
 export interface RefArray<in out A, in out E = never, out R = never> extends RefSubject.RefSubject<ReadonlyArray<A>, E, R> {
 }
 /**
  * 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* () {
@@ -41,13 +63,24 @@ export interface RefArray<in out A, in out E = never, out R = never> extends Ref
  * ```
  *
  * @since 1.18.0
- * @category constructors
+ * @category Constructors
  */
-export declare function make<A, E, R>(initial: ReadonlyArray<A> | Effect.Effect<ReadonlyArray<A>, E, R> | Fx.Fx<ReadonlyArray<A>, E, R>, eq?: Equivalence<A>): Effect.Effect<RefArray<A, E>, never, R | Scope.Scope>;
+export declare function make<A, E = never, R = never>(initial: ReadonlyArray<A> | Effect.Effect<ReadonlyArray<A>, E, R> | Fx.Fx<ReadonlyArray<A>, E, R>, eq?: Equivalence<A>): Effect.Effect<RefArray<A, E>, never, R | Scope.Scope>;
 /**
  * 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
+ * @category State updates
  */
 export declare const prepend: {
     <A>(value: A): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -55,8 +88,19 @@ export declare const prepend: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const prependAll: {
     <A>(value: Iterable<A>): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -64,8 +108,19 @@ export declare const prependAll: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const append: {
     <A>(value: A): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -73,8 +128,19 @@ export declare const append: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const appendAll: {
     <A>(value: Iterable<A>): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -82,8 +148,19 @@ export declare const appendAll: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const drop: {
     (n: number): <A, E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -91,8 +168,19 @@ export declare const drop: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const dropRight: {
     (n: number): <A, E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -100,8 +188,19 @@ export declare const dropRight: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const dropWhile: {
     <A>(predicate: (a: A) => boolean): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -109,8 +208,19 @@ export declare const dropWhile: {
 };
 /**
  * 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
+ * @category Derived queries
  */
 export declare const filterValues: {
     <A>(predicate: (a: A) => boolean): <E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<ReadonlyArray<A>, E, R>;
@@ -118,8 +228,19 @@ export declare const filterValues: {
 };
 /**
  * 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
+ * @category Optional queries
  */
 export declare const getIndex: {
     (index: number): <A, E, R>(ref: RefArray<A, E, R>) => RefSubject.Filtered<A, E, R>;
@@ -127,8 +248,19 @@ export declare const getIndex: {
 };
 /**
  * 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
+ * @category Derived queries
  */
 export declare const groupBy: {
     <A>(f: (a: A) => string): <E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<R, E, Record<string, ReadonlyArray<A>>>;
@@ -136,8 +268,19 @@ export declare const groupBy: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const insertAt: {
     <A>(index: number, a: A): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -145,26 +288,76 @@ export declare const insertAt: {
 };
 /**
  * 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
+ * @category State predicates
  */
 export declare const isEmpty: <A, E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<boolean, E, R>;
 /**
  * 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
+ * @category State predicates
  */
 export declare const isNonEmpty: <A, E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<boolean, E, R>;
 /**
  * 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
+ * @category Derived queries
  */
 export declare const length: <A, E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<number, E, R>;
 /**
  * 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
+ * @category State updates
  */
 export declare const map: {
     <A>(f: (a: A, index: number) => A): <E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<ReadonlyArray<A>, E, R>;
@@ -172,8 +365,19 @@ export declare const map: {
 };
 /**
  * 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
+ * @category Derived queries
  */
 export declare const mapValues: {
     <A, B>(f: (a: A, index: number) => B): <E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<ReadonlyArray<B>, E, R>;
@@ -181,8 +385,19 @@ export declare const mapValues: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const modifyAt: {
     <A>(index: number, f: (a: A) => A): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -190,8 +405,19 @@ export declare const modifyAt: {
 };
 /**
  * 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
+ * @category Derived queries
  */
 export declare const partition: {
     <A, B extends A>(predicate: (a: A) => a is B): <E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<R, E, readonly [ReadonlyArray<B>, ReadonlyArray<A>]>;
@@ -199,8 +425,19 @@ export declare const partition: {
 };
 /**
  * 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
+ * @category Derived queries
  */
 export declare const reduce: {
     <A, B>(b: B, f: (b: B, a: A, index: number) => B): <E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<B, E, R>;
@@ -208,8 +445,19 @@ export declare const reduce: {
 };
 /**
  * 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
+ * @category Derived queries
  */
 export declare const reduceRight: {
     <A, B>(b: B, f: (b: B, a: A, index: number) => B): <E, R>(ref: RefArray<A, E, R>) => RefSubject.Computed<B, E, R>;
@@ -217,8 +465,19 @@ export declare const reduceRight: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const replaceAt: {
     <A>(index: number, a: A): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -226,8 +485,19 @@ export declare const replaceAt: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const rotate: {
     (n: number): <A, E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -235,8 +505,19 @@ export declare const rotate: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const sortBy: {
     <A>(orders: Iterable<Order.Order<A>>): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -244,8 +525,19 @@ export declare const sortBy: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const take: {
     (n: number): <A, E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -253,8 +545,19 @@ export declare const take: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const takeRight: {
     (n: number): <A, E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -262,8 +565,19 @@ export declare const takeRight: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const takeWhile: {
     <A>(predicate: (a: A) => boolean): <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
@@ -271,17 +585,39 @@ export declare const takeWhile: {
 };
 /**
  * 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
+ * @category State updates
  */
 export declare const dedupeWith: <A>(valueEq: Equivalence<A>) => <E, R>(ref: RefArray<A, E, R>) => Effect.Effect<ReadonlyArray<A>, E, R>;
 /**
  * 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])
@@ -297,16 +633,27 @@ export declare const dedupeWith: <A>(valueEq: Equivalence<A>) => <E, R>(ref: Ref
  * ```
  *
  * @since 1.18.0
- * @category filtered
+ * @category Optional queries
  */
 export declare const last: <A, E, R>(ref: RefArray<A, E, R>) => RefSubject.Filtered<A, E, R>;
 /**
  * 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])
@@ -322,7 +669,7 @@ export declare const last: <A, E, R>(ref: RefArray<A, E, R>) => RefSubject.Filte
  * ```
  *
  * @since 1.18.0
- * @category filtered
+ * @category Optional queries
  */
 export declare const head: <A, E, R>(ref: RefArray<A, E, R>) => RefSubject.Filtered<A, E, R>;
 //# sourceMappingURL=RefArray.d.ts.map