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

package/dist/RefSubject/RefTrie.js

@@ -4,12 +4,25 @@
  */
 import { equals } from "effect/Equal";
 import { dual } from "effect/Function";
+import * as Option from "effect/Option";
 import * as Trie from "effect/Trie";
 import * as RefSubject from "./RefSubject.js";
+import { Result } from "effect";
 /**
  * Creates a new `RefTrie` from a Trie, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates trie 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,171 +32,427 @@ export function make(initial) {
 // ========================================
 /**
  * Insert a key-value pair into the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Expresses insert as one ordered trie transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running insert performs one serialized trie 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 insert = dual(3, function insert(ref, key, value) {
     return RefSubject.update(ref, Trie.insert(key, value));
 });
 /**
  * Insert multiple key-value pairs into the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Expresses insert many as one ordered trie transition; readers never observe the intermediate
+ * collection used to build the result.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running insert many performs one serialized trie 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 insertMany = dual(2, function insertMany(ref, entries) {
     return RefSubject.update(ref, Trie.insertMany(entries));
 });
 /**
  * Remove a key from the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed trie value and publishes only the result, preserving its element
+ * order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized trie 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 remove = dual(2, function remove(ref, key) {
     return RefSubject.update(ref, Trie.remove(key));
 });
 /**
  * Remove multiple keys from the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove many to the committed trie value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove many performs one serialized trie 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 removeMany = dual(2, function removeMany(ref, keys) {
     return RefSubject.update(ref, Trie.removeMany(keys));
 });
 /**
  * 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 trie 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 modify = dual(3, function modify(ref, key, f) {
     return RefSubject.update(ref, Trie.modify(key, f));
 });
 /**
  * Clear all entries from the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Applies clear to the committed trie value and publishes only the result, preserving its element
+ * order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running clear performs one serialized trie 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 clear = (ref) => RefSubject.update(ref, () => Trie.empty());
 /**
- * Map values in place (endomorphic).
+ * Map values into a read-only derived trie.
+ * @remarks
+ * ## Why
+ *
+ * Creates a read-only Computed trie whose values are mapped for current reads and every later
+ * source push; it does not modify the RefTrie.
+ *
+ * ## Ownership and lifetime
+ *
+ * The map 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 combinators
+ * @category State updates
  */
 export const map = dual(2, function map(ref, f) {
-    return RefSubject.update(ref, Trie.map(f));
+    return RefSubject.map(ref, Trie.map(f));
 });
 /**
- * Filter entries in place.
+ * Filter entries into a read-only derived trie.
+ * @remarks
+ * ## Why
+ *
+ * Creates a read-only Computed trie containing matching entries for current reads and every later
+ * source push; it does not modify the RefTrie.
+ *
+ * ## Ownership and lifetime
+ *
+ * The filter 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 combinators
+ * @category State updates
  */
 export const filter = dual(2, function filter(ref, predicate) {
-    return RefSubject.update(ref, Trie.filter(predicate));
+    return RefSubject.map(ref, Trie.filter(predicate));
 });
 /**
- * Filter and map entries in place.
+ * Filter and map entries into a read-only derived trie.
+ * @remarks
+ * ## Why
+ *
+ * Creates a read-only Computed trie that can transform or omit each entry; it leaves the writable
+ * source trie unchanged.
+ *
+ * ## Ownership and lifetime
+ *
+ * The filter map 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 combinators
+ * @category State updates
  */
 export const filterMap = dual(2, function filterMap(ref, f) {
-    return RefSubject.update(ref, Trie.filterMap(f));
+    return RefSubject.map(ref, Trie.filterMap((value, key) => Option.match(f(value, key), {
+        onNone: () => Result.failVoid,
+        onSome: (b) => Result.succeed(b),
+    })));
 });
 // ========================================
 // Computed
 // ========================================
 /**
  * Compact Option values.
+ * @remarks
+ * ## Why
+ *
+ * Creates a read-only Computed trie by removing None values and unwrapping Some values on each
+ * source version; the result is never absent as a whole.
+ *
+ * ## Ownership and lifetime
+ *
+ * This declaration performs no acquisition and retains no resources. Implementations preserve
+ * source errors, services, and lifetime.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const compact = (ref) => RefSubject.map(ref, Trie.compact);
 /**
  * Get the current size of the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the trie; 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, Trie.size);
 /**
  * Check if the Trie is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the trie; 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, Trie.isEmpty);
 /**
  * Check if the Trie is non-empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is non empty a live projection of the trie; 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 const isNonEmpty = (ref) => RefSubject.map(ref, (t) => !Trie.isEmpty(t));
 /**
  * Check if a key exists in the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Makes has a live projection of the trie; 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
+ * @category State predicates
  */
 export const has = dual(2, function has(ref, key) {
     return RefSubject.map(ref, Trie.has(key));
 });
 /**
  * Get all keys from the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Projects trie 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
+ * @category Derived queries
  */
 export const keys = (ref) => RefSubject.map(ref, (t) => Array.from(Trie.keys(t)));
 /**
  * Get all values from the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Projects trie 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
+ * @category Derived queries
  */
 export const values = (ref) => RefSubject.map(ref, (t) => Array.from(Trie.values(t)));
 /**
  * Get all entries from the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Projects trie 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
+ * @category Derived queries
  */
 export const entries = (ref) => RefSubject.map(ref, Trie.toEntries);
 /**
  * Get all keys with a given prefix.
+ * @remarks
+ * ## Why
+ *
+ * Projects trie state with keys with prefix for both current reads and future pushes, avoiding a
+ * second mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The keys with prefix 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 keysWithPrefix = dual(2, function keysWithPrefix(ref, prefix) {
     return RefSubject.map(ref, (t) => Array.from(Trie.keysWithPrefix(t, prefix)));
 });
 /**
  * Get all values with a given prefix.
+ * @remarks
+ * ## Why
+ *
+ * Projects trie state with values with prefix for both current reads and future pushes, avoiding a
+ * second mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The values with prefix 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 valuesWithPrefix = dual(2, function valuesWithPrefix(ref, prefix) {
     return RefSubject.map(ref, (t) => Array.from(Trie.valuesWithPrefix(t, prefix)));
 });
 /**
  * Get all entries with a given prefix.
+ * @remarks
+ * ## Why
+ *
+ * Projects trie state with entries with prefix for both current reads and future pushes, avoiding
+ * a second mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The entries with prefix 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 entriesWithPrefix = dual(2, function entriesWithPrefix(ref, prefix) {
     return RefSubject.map(ref, Trie.toEntriesWithPrefix(prefix));
 });
 /**
  * Get the longest prefix of a key that exists in the Trie.
+ * @remarks
+ * ## Why
+ *
+ * Models a longest-prefix lookup as Filtered state: an absent match fails an Effect read with
+ * `NoSuchElementError`, while later pushes can make a match available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The longest prefix of 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 longestPrefixOf = dual(2, function longestPrefixOf(ref, key) {
     return RefSubject.map(ref, Trie.longestPrefixOf(key));
 });
 /**
  * Map values to a different type.
+ * @remarks
+ * ## Why
+ *
+ * Projects trie 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, Trie.map(f));
 });
 /**
  * Reduce the entries to a single value.
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce a live projection of the trie; 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, Trie.reduce(b, f));
@@ -193,8 +462,19 @@ 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
+ * @category Optional queries
  */
 export const get = dual(2, function get(ref, key) {
     return RefSubject.filterMap(ref, Trie.get(key));