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

package/dist/RefSubject/RefHashMap.js

@@ -3,14 +3,26 @@
  * @since 1.18.0
  */
 import { equals } from "effect/Equal";
-import { dual, flow } from "effect/Function";
+import { dual } from "effect/Function";
 import * as HashMap from "effect/HashMap";
 import * as Option from "effect/Option";
 import * as RefSubject from "./RefSubject.js";
+import { Result } from "effect";
 /**
  * Creates a new `RefHashMap` from a HashMap, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates hash map 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 });
@@ -20,78 +32,186 @@ export function make(initial) {
 // ========================================
 /**
  * Set a key-value pair in the RefHashMap.
+ * @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 hash map 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 set = dual(3, function set(ref, key, value) {
     return RefSubject.update(ref, HashMap.set(key, value));
 });
 /**
  * Remove a key from the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed hash map value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized hash map 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, HashMap.remove(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 hash map 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, HashMap.modify(key, f));
 });
 /**
  * Modify the value at a key using an Option-based update function.
+ * @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 hash map 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 modifyAt = dual(3, function modifyAt(ref, key, f) {
     return RefSubject.update(ref, HashMap.modifyAt(key, f));
 });
 /**
  * Set multiple key-value pairs in the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Keeps set many atomic with respect to competing RefSubject writes instead of splitting the read
+ * and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running set many performs one serialized hash map 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 setMany = dual(2, function setMany(ref, entries) {
     return RefSubject.update(ref, HashMap.setMany(entries));
 });
 /**
  * Remove multiple keys from the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove many to the committed hash map value and publishes only the result, preserving
+ * its element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove many performs one serialized hash map 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, HashMap.removeMany(keys));
 });
 /**
  * Clear all entries from the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Applies clear to the committed hash map value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running clear performs one serialized hash map 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, () => HashMap.empty());
 /**
  * Merge another HashMap into this one.
+ * @remarks
+ * ## Why
+ *
+ * Combines bulk hash map changes in one committed value, giving subscribers one coherent update
+ * rather than a partially applied sequence.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running union performs one serialized hash map 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 union = dual(2, function union(ref, that) {
     return RefSubject.update(ref, HashMap.union(that));
 });
 /**
  * Filter entries in place.
+ * @remarks
+ * ## Why
+ *
+ * Applies filter to the committed HashMap 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 HashMap and retains the ref's E and R channels.
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const filter = dual(2, function filter(ref, predicate) {
     return RefSubject.update(ref, HashMap.filter(predicate));
 });
 /**
  * Map values in place (endomorphic).
+ * @remarks
+ * ## Why
+ *
+ * Applies map to the committed HashMap 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 HashMap and retains the ref's E and R channels.
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const map = dual(2, function map(ref, f) {
     return RefSubject.update(ref, HashMap.map(f));
@@ -101,92 +221,238 @@ export const map = dual(2, function map(ref, f) {
 // ========================================
 /**
  * Get the current size of the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the hash map; 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, HashMap.size);
 /**
  * Check if the RefHashMap is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the hash map; 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, HashMap.isEmpty);
 /**
  * Check if the RefHashMap is non-empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is non empty a live projection of the hash map; 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, (m) => !HashMap.isEmpty(m));
 /**
  * Get all keys from the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash map 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, (m) => Array.from(HashMap.keys(m)));
 /**
  * Get all values from the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash map 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, HashMap.toValues);
 /**
  * Get all entries from the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash map 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, HashMap.toEntries);
 /**
  * Check if a key exists in the RefHashMap.
+ * @remarks
+ * ## Why
+ *
+ * Makes has a live projection of the hash map; 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, HashMap.has(key));
 });
 /**
  * Map values to a different type.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash map 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, HashMap.map(f));
 });
 /**
  * Filter entries creating a Computed value.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash map 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 const filterValues = dual(2, function filterValues(ref, predicate) {
     return RefSubject.map(ref, HashMap.filter(predicate));
 });
 /**
  * Filter and map values.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash map 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
+ * @category Derived queries
  */
 export const filterMapValues = dual(2, function filterMapValues(ref, f) {
-    return RefSubject.map(ref, HashMap.filterMap(f));
+    return RefSubject.map(ref, HashMap.filterMap((value, key) => Option.match(f(value, key), {
+        onNone: () => Result.failVoid,
+        onSome: (b) => Result.succeed(b),
+    })));
 });
 /**
  * Reduce the entries to a single value.
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce a live projection of the hash map; 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, HashMap.reduce(b, f));
 });
 /**
  * Check if any entry satisfies a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes some a live projection of the hash map; 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
+ * @category State predicates
  */
 export const some = dual(2, function some(ref, predicate) {
     return RefSubject.map(ref, HashMap.some(predicate));
 });
 /**
  * Check if all entries satisfy a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes every a live projection of the hash map; 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
+ * @category State predicates
  */
 export const every = dual(2, function every(ref, predicate) {
     return RefSubject.map(ref, HashMap.every(predicate));
@@ -196,17 +462,39 @@ export const every = dual(2, function every(ref, predicate) {
 // ========================================
 /**
  * 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, HashMap.get(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
+ * @category Optional queries
  */
 export const findFirst = dual(2, function findFirst(ref, predicate) {
-    return RefSubject.filterMap(ref, flow(HashMap.findFirst(predicate), Option.fromUndefinedOr));
+    return RefSubject.filterMap(ref, (g) => HashMap.findFirst(g, predicate));
 });