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

package/dist/RefSubject/RefRecord.js

@@ -10,6 +10,17 @@ import * as Record from "effect/Record";
 import * as RefSubject from "./RefSubject.js";
 /**
  * Creates a new `RefRecord` from a Record, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates record 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) {
 // ========================================
 /**
  * Set a key-value pair in the Record.
+ * @remarks
+ * ## Why
+ *
+ * Keeps set atomic with respect to competing RefSubject writes instead of splitting the read and
+ * replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running set performs one serialized record 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 set = dual(3, function set(ref, key, value) {
 });
 /**
  * Remove a key from the Record.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed record value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized record 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 remove = dual(2, function remove(ref, key) {
 });
 /**
  * Modify the value at a key if it exists.
+ * @remarks
+ * ## Why
+ *
+ * Keeps modify atomic with respect to competing RefSubject writes instead of splitting the read
+ * and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running modify performs one serialized record 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 modify = dual(3, function modify(ref, key, f) {
 });
 /**
  * Replace the value at a key if it exists.
+ * @remarks
+ * ## Why
+ *
+ * Keeps replace atomic with respect to competing RefSubject writes instead of splitting the read
+ * and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running replace performs one serialized record 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,12 +108,34 @@ export const replace = dual(3, function replace(ref, key, value) {
 });
 /**
  * Clear all entries from the Record.
+ * @remarks
+ * ## Why
+ *
+ * Applies clear to the committed record value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running clear performs one serialized record 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 clear = (ref) => RefSubject.update(ref, () => Record.empty());
 /**
  * Union with another record.
+ * @remarks
+ * ## Why
+ *
+ * Combines bulk record changes in one committed value, giving subscribers one coherent update
+ * rather than a partially applied sequence.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running union performs one serialized record 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
  */
@@ -67,6 +144,17 @@ export const union = dual((args) => RefSubject.isRefSubject(args[0]), function u
 });
 /**
  * Intersection with another record.
+ * @remarks
+ * ## Why
+ *
+ * Intersection with another record. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running intersection performs one serialized record 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
  */
@@ -75,6 +163,17 @@ export const intersection = dual((args) => RefSubject.isRefSubject(args[0]), fun
 });
 /**
  * Difference with another record.
+ * @remarks
+ * ## Why
+ *
+ * Difference with another record. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running difference performs one serialized record 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
  */
@@ -83,6 +182,16 @@ export const difference = dual(2, function difference(ref, that) {
 });
 /**
  * Filter entries in place.
+ * @remarks
+ * ## Why
+ *
+ * Applies filter to the committed Record 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 Record and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -91,6 +200,16 @@ export const filter = dual(2, function filter(ref, predicate) {
 });
 /**
  * Map values in place (endomorphic).
+ * @remarks
+ * ## Why
+ *
+ * Applies map to the committed Record 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 Record and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -102,24 +221,68 @@ export const map = dual(2, function map(ref, f) {
 // ========================================
 /**
  * Get the current size of the Record.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the record; 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, Record.size);
 /**
  * Check if the Record is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the record; 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, Record.isEmptyRecord);
 /**
  * Check if the Record is non-empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is non empty a live projection of the record; 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 const isNonEmpty = (ref) => RefSubject.map(ref, (r) => !Record.isEmptyRecord(r));
 /**
  * Check if a key exists in the Record.
+ * @remarks
+ * ## Why
+ *
+ * Makes has a live projection of the record; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has 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
  */
@@ -128,24 +291,68 @@ export const has = dual(2, function has(ref, key) {
 });
 /**
  * Get all keys from the Record.
+ * @remarks
+ * ## Why
+ *
+ * Projects record state with keys for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The keys 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 keys = (ref) => RefSubject.map(ref, Record.keys);
 /**
  * Get all values from the Record.
+ * @remarks
+ * ## Why
+ *
+ * Projects record state with values for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The 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
  */
 export const values = (ref) => RefSubject.map(ref, Record.values);
 /**
  * Get all entries from the Record.
+ * @remarks
+ * ## Why
+ *
+ * Projects record state with entries for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The entries 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 entries = (ref) => RefSubject.map(ref, Record.toEntries);
 /**
  * Map values to a different type.
+ * @remarks
+ * ## Why
+ *
+ * Projects record 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
  */
@@ -154,6 +361,17 @@ export const mapValues = dual(2, function mapValues(ref, f) {
 });
 /**
  * Map keys to different keys.
+ * @remarks
+ * ## Why
+ *
+ * Projects record state with map keys for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The map keys 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
  */
@@ -162,6 +380,17 @@ export const mapKeys = dual(2, function mapKeys(ref, f) {
 });
 /**
  * Map entries to new key-value pairs.
+ * @remarks
+ * ## Why
+ *
+ * Projects record state with map entries for both current reads and future pushes, avoiding a
+ * second mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The map entries 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
  */
@@ -170,6 +399,17 @@ export const mapEntries = dual(2, function mapEntries(ref, f) {
 });
 /**
  * Filter entries creating a Computed value.
+ * @remarks
+ * ## Why
+ *
+ * Projects record 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
  */
@@ -178,6 +418,17 @@ export const filterValues = dual(2, function filterValues(ref, predicate) {
 });
 /**
  * Filter and map values.
+ * @remarks
+ * ## Why
+ *
+ * Projects record state with filter map values for both current reads and future pushes, avoiding
+ * a second mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The filter 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
  */
@@ -186,6 +437,16 @@ export const filterMapValues = dual(2, function filterMapValues(ref, f) {
 });
 /**
  * Partition entries.
+ * @remarks
+ * ## Why
+ *
+ * Partition entries. 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
  */
@@ -194,6 +455,17 @@ export const partition = dual(2, function partition(ref, predicate) {
 });
 /**
  * Check if any entry satisfies a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes some a live projection of the record; 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
  */
@@ -202,6 +474,17 @@ export const some = dual(2, function some(ref, predicate) {
 });
 /**
  * Check if all entries satisfy a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes every a live projection of the record; 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
  */
@@ -210,6 +493,17 @@ export const every = dual(2, function every(ref, predicate) {
 });
 /**
  * Reduce the entries to a single value.
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce a live projection of the record; 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
  */
@@ -221,6 +515,17 @@ export const reduce = dual(3, function reduce(ref, b, f) {
 // ========================================
 /**
  * Get the value at a key as a Filtered.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of get as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get 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
  */
@@ -229,6 +534,17 @@ export const get = dual(2, function get(ref, key) {
 });
 /**
  * Find the first entry 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
  */
@@ -237,6 +553,17 @@ export const findFirst = dual(2, function findFirst(ref, predicate) {
 });
 /**
  * Pop a value at a key as a Filtered.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of pop as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The pop 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
  */