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

package/dist/RefSubject/RefHashSet.js

@@ -8,8 +8,19 @@ import * as HashSet from "effect/HashSet";
 import * as RefSubject from "./RefSubject.js";
 /**
  * Creates a new `RefHashSet` from a HashSet, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates hash set 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,62 +30,148 @@ export function make(initial) {
 // ========================================
 /**
  * Add a value to the RefHashSet.
+ * @remarks
+ * ## Why
+ *
+ * Add a value to the RefHashSet. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add performs one serialized hash set 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 add = dual(2, function add(ref, value) {
     return RefSubject.update(ref, HashSet.add(value));
 });
 /**
  * Remove a value from the RefHashSet.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed hash set value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized hash set 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, value) {
     return RefSubject.update(ref, HashSet.remove(value));
 });
 /**
  * Clear all values from the RefHashSet.
+ * @remarks
+ * ## Why
+ *
+ * Applies clear to the committed hash set value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running clear performs one serialized hash set 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, () => HashSet.empty());
 /**
  * Compute the union with another HashSet.
+ * @remarks
+ * ## Why
+ *
+ * Combines bulk hash set 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 set 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, HashSet.union(that));
 });
 /**
  * Compute the intersection with another HashSet.
+ * @remarks
+ * ## Why
+ *
+ * Compute the intersection with another HashSet. The operation remains attached to the
+ * RefSubject's versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running intersection performs one serialized hash set 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 intersection = dual(2, function intersection(ref, that) {
     return RefSubject.update(ref, HashSet.intersection(that));
 });
 /**
  * Compute the difference with another HashSet.
+ * @remarks
+ * ## Why
+ *
+ * Compute the difference with another HashSet. The operation remains attached to the RefSubject's
+ * versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running difference performs one serialized hash set 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 difference = dual(2, function difference(ref, that) {
     return RefSubject.update(ref, HashSet.difference(that));
 });
 /**
  * Filter values in place.
+ * @remarks
+ * ## Why
+ *
+ * Applies filter to the committed HashSet 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 HashSet 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, HashSet.filter(predicate));
 });
 /**
  * Map values in place (endomorphic).
+ * @remarks
+ * ## Why
+ *
+ * Applies map to the committed HashSet 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 HashSet 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, HashSet.map(f));
@@ -84,81 +181,202 @@ export const map = dual(2, function map(ref, f) {
 // ========================================
 /**
  * Get the current size of the RefHashSet.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the hash set; 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, HashSet.size);
 /**
  * Check if the RefHashSet is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the hash set; 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, HashSet.isEmpty);
 /**
  * Check if the RefHashSet is non-empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is non empty a live projection of the hash set; 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, (s) => !HashSet.isEmpty(s));
 /**
  * Check if a value exists in the RefHashSet.
+ * @remarks
+ * ## Why
+ *
+ * Makes has a live projection of the hash set; 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, value) {
     return RefSubject.map(ref, HashSet.has(value));
 });
 /**
  * Check if any value satisfies a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes some a live projection of the hash set; 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, HashSet.some(predicate));
 });
 /**
  * Check if all values satisfy a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Makes every a live projection of the hash set; 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, HashSet.every(predicate));
 });
 /**
  * Check if this set is a subset of another.
+ * @remarks
+ * ## Why
+ *
+ * Check if this set is a subset of another. The operation remains attached to the RefSubject's
+ * versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is subset 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 isSubset = dual(2, function isSubset(ref, that) {
     return RefSubject.map(ref, HashSet.isSubset(that));
 });
 /**
  * Map values to a different type.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash set 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, HashSet.map(f));
 });
 /**
  * Filter values creating a Computed value.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash set 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, HashSet.filter(predicate));
 });
 /**
  * Reduce the values to a single value.
+ * @remarks
+ * ## Why
+ *
+ * Makes reduce a live projection of the hash set; 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, HashSet.reduce(b, f));
 });
 /**
  * Get all values as an array.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash set 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, (s) => Array.from(s));