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

package/dist/RefSubject/RefHashSet.js

@@ -8,6 +8,17 @@ 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
  */
@@ -19,6 +30,17 @@ 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
  */
@@ -27,6 +49,17 @@ export const add = dual(2, function add(ref, 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
  */
@@ -35,12 +68,34 @@ export const remove = dual(2, function remove(ref, 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
  */
 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
  */
@@ -49,6 +104,17 @@ export const union = dual(2, function union(ref, 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
  */
@@ -57,6 +123,17 @@ export const intersection = dual(2, function intersection(ref, 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
  */
@@ -65,6 +142,16 @@ export const difference = dual(2, function difference(ref, 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
  */
@@ -73,6 +160,16 @@ export const filter = dual(2, function filter(ref, 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
  */
@@ -84,24 +181,68 @@ 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
  */
 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
  */
 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
  */
 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
  */
@@ -110,6 +251,17 @@ export const has = dual(2, function has(ref, 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
  */
@@ -118,6 +270,17 @@ export const some = dual(2, function some(ref, 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
  */
@@ -126,6 +289,17 @@ export const every = dual(2, function every(ref, 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
  */
@@ -134,6 +308,17 @@ export const isSubset = dual(2, function isSubset(ref, 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
  */
@@ -142,6 +327,17 @@ export const mapValues = dual(2, function mapValues(ref, 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
  */
@@ -150,6 +346,17 @@ export const filterValues = dual(2, function filterValues(ref, 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
  */
@@ -158,6 +365,17 @@ export const reduce = dual(3, function reduce(ref, 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
  */