@typed/fx 2.0.0-beta.3 → 2.0.0-beta.5

package/dist/RefSubject/RefHashMap.js

@@ -10,6 +10,17 @@ 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
  */
@@ -21,6 +32,17 @@ 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
  */
@@ -29,6 +51,17 @@ export const set = dual(3, function set(ref, 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
  */
@@ -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 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
  */
@@ -45,6 +89,17 @@ export const modify = dual(3, function modify(ref, 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
  */
@@ -53,6 +108,17 @@ export const modifyAt = dual(3, function modifyAt(ref, 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
  */
@@ -61,6 +127,17 @@ export const setMany = dual(2, function setMany(ref, 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
  */
@@ -69,12 +146,34 @@ export const removeMany = dual(2, function removeMany(ref, 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
  */
 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
  */
@@ -83,6 +182,16 @@ export const union = dual(2, function union(ref, 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
  */
@@ -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 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
  */
@@ -102,42 +221,119 @@ 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
  */
 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
  */
 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
  */
 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
  */
 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
  */
 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
  */
 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
  */
@@ -146,6 +342,17 @@ export const has = dual(2, function has(ref, 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
  */
@@ -154,6 +361,17 @@ export const mapValues = dual(2, function mapValues(ref, 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
  */
@@ -162,6 +380,17 @@ export const filterValues = dual(2, function filterValues(ref, 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
  */
@@ -173,6 +402,17 @@ export const filterMapValues = dual(2, function filterMapValues(ref, f) {
 });
 /**
  * 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
  */
@@ -181,6 +421,17 @@ export const reduce = dual(3, function reduce(ref, 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
  */
@@ -189,6 +440,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 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
  */
@@ -200,6 +462,17 @@ 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
  */
@@ -208,6 +481,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
  */

package/dist/RefSubject/RefHashRing.d.ts

@@ -10,6 +10,17 @@ import type * as Fx from "../Fx/index.js";
 import * as RefSubject from "./RefSubject.js";
 /**
  * A RefHashRing is a RefSubject specialized over a HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Defines hash ring state with the same current-read, pushed-update, and synchronized-write
+ * contract as RefSubject.
+ *
+ * ## Ownership and lifetime
+ *
+ * RefHashRing is a contract and performs no acquisition. Implementations retain the errors,
+ * services, interruption, and Scope requirements expressed by its members.
+ *
  * @since 1.18.0
  * @category models
  */
@@ -17,20 +28,53 @@ export interface RefHashRing<in out A extends PrimaryKey.PrimaryKey, in out E =
 }
 /**
  * Creates a new `RefHashRing` from a HashRing, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates hash ring 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
  */
-export declare function make<A extends PrimaryKey.PrimaryKey, E, R>(initial: HashRing.HashRing<A> | Effect.Effect<HashRing.HashRing<A>, E, R> | Fx.Fx<HashRing.HashRing<A>, E, R>): Effect.Effect<RefHashRing<A, E>, never, R | Scope.Scope>;
+export declare function make<A extends PrimaryKey.PrimaryKey, E = never, R = never>(initial: HashRing.HashRing<A> | Effect.Effect<HashRing.HashRing<A>, E, R> | Fx.Fx<HashRing.HashRing<A>, E, R>): Effect.Effect<RefHashRing<A, E>, never, R | Scope.Scope>;
 /**
  * Creates a new empty RefHashRing.
+ * @remarks
+ * ## Why
+ *
+ * Creates a new empty RefHashRing. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running empty performs one serialized hash ring 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 constructors
  */
-export declare function empty<A extends PrimaryKey.PrimaryKey, E, R>(options?: {
+export declare function empty<A extends PrimaryKey.PrimaryKey, E = never, R = never>(options?: {
     readonly baseWeight?: number;
 }): Effect.Effect<RefHashRing<A, E>, never, R | Scope.Scope>;
 /**
  * Add a node to the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Add a node to the HashRing. The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add performs one serialized hash ring 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
  */
@@ -44,6 +88,17 @@ export declare const add: {
 };
 /**
  * Add multiple nodes to the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Add multiple nodes to the HashRing. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add many performs one serialized hash ring 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 +112,17 @@ export declare const addMany: {
 };
 /**
  * Remove a node from the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed hash ring value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized hash ring 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
  */
@@ -66,6 +132,17 @@ export declare const remove: {
 };
 /**
  * Check if a node exists in the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Makes has a live projection of the hash ring; 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
  */
@@ -75,12 +152,34 @@ export declare const has: {
 };
 /**
  * Get the number of nodes in the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the hash ring; 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 declare const size: <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Computed<number, E, R>;
 /**
  * Check if the HashRing is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the hash ring; 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
  */
@@ -88,6 +187,17 @@ export declare const isEmpty: <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHa
 /**
  * Get the node which should handle a given input string as a Computed.
  * Returns undefined if the ring is empty.
+ * @remarks
+ * ## Why
+ *
+ * Projects the selected node for current reads and later pushes. An empty ring is represented by
+ * `undefined` inside the Computed value; it does not become Filtered or add `NoSuchElementError`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get node 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
  */
@@ -97,6 +207,18 @@ export declare const getNode: {
 };
 /**
  * Get shard distribution across nodes.
+ * @remarks
+ * ## Why
+ *
+ * Projects the shard distribution for current reads and later pushes. An empty ring is represented
+ * by `undefined` inside the Computed value; it does not become Filtered or add
+ * `NoSuchElementError`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get shards 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
  */
@@ -106,6 +228,17 @@ export declare const getShards: {
 };
 /**
  * Get all nodes as an array.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash ring 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
  */
@@ -113,6 +246,17 @@ export declare const values: <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHas
 /**
  * Get the node which should handle a given input string as a Filtered.
  * Fails if the ring is empty.
+ * @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
  */