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

package/dist/RefSubject/RefGraph.js

@@ -8,6 +8,17 @@ import * as Graph from "effect/Graph";
 import * as RefSubject from "./RefSubject.js";
 /**
  * Creates a new `RefGraph` from a Graph, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates graph 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
  */
@@ -16,6 +27,17 @@ export function make(initial) {
 }
 /**
  * Creates a new empty directed RefGraph.
+ * @remarks
+ * ## Why
+ *
+ * Creates a new empty directed RefGraph. The operation remains attached to the RefSubject's
+ * versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running directed performs one serialized graph 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
  */
@@ -24,6 +46,17 @@ export function directed() {
 }
 /**
  * Creates a new empty undirected RefGraph.
+ * @remarks
+ * ## Why
+ *
+ * Creates a new empty undirected RefGraph. The operation remains attached to the RefSubject's
+ * versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running undirected performs one serialized graph 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
  */
@@ -35,6 +68,17 @@ export function undirected() {
 // ========================================
 /**
  * Add a node to the graph.
+ * @remarks
+ * ## Why
+ *
+ * Add a node to the graph. The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add node performs one serialized graph 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
  */
@@ -47,6 +91,17 @@ export const addNode = dual(2, function addNode(ref, data) {
 });
 /**
  * Remove a node from the graph.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove node to the committed graph value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove node performs one serialized graph 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
  */
@@ -59,6 +114,17 @@ export const removeNode = dual(2, function removeNode(ref, nodeIndex) {
 });
 /**
  * Update a node's data.
+ * @remarks
+ * ## Why
+ *
+ * Keeps update node atomic with respect to competing RefSubject writes instead of splitting the
+ * read and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running update node performs one serialized graph 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
  */
@@ -71,6 +137,17 @@ export const updateNode = dual(3, function updateNode(ref, nodeIndex, f) {
 });
 /**
  * Add an edge to the graph.
+ * @remarks
+ * ## Why
+ *
+ * Add an edge to the graph. The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add edge performs one serialized graph 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 +160,17 @@ export const addEdge = dual(4, function addEdge(ref, source, target, data) {
 });
 /**
  * Remove an edge from the graph.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove edge to the committed graph value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove edge performs one serialized graph 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
  */
@@ -95,6 +183,17 @@ export const removeEdge = dual(2, function removeEdge(ref, edgeIndex) {
 });
 /**
  * Update an edge's data.
+ * @remarks
+ * ## Why
+ *
+ * Keeps update edge atomic with respect to competing RefSubject writes instead of splitting the
+ * read and replacement into separate effects.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running update edge performs one serialized graph 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
  */
@@ -107,6 +206,16 @@ export const updateEdge = dual(3, function updateEdge(ref, edgeIndex, f) {
 });
 /**
  * Map all node data.
+ * @remarks
+ * ## Why
+ *
+ * Applies `mapNodes` through `RefSubject.update` and publishes one coherent graph 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 graph and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -119,6 +228,16 @@ export const mapNodes = dual(2, function mapNodes(ref, f) {
 });
 /**
  * Map all edge data.
+ * @remarks
+ * ## Why
+ *
+ * Applies `mapEdges` through `RefSubject.update` and publishes one coherent graph 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 graph and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -131,6 +250,16 @@ export const mapEdges = dual(2, function mapEdges(ref, f) {
 });
 /**
  * Filter nodes.
+ * @remarks
+ * ## Why
+ *
+ * Applies `filterNodes` through `RefSubject.update` and publishes one coherent graph 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 graph and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -143,6 +272,16 @@ export const filterNodes = dual(2, function filterNodes(ref, predicate) {
 });
 /**
  * Filter edges.
+ * @remarks
+ * ## Why
+ *
+ * Applies `filterEdges` through `RefSubject.update` and publishes one coherent graph 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 graph and retains the ref's E and R channels.
  * @since 1.18.0
  * @category combinators
  */
@@ -155,6 +294,17 @@ export const filterEdges = dual(2, function filterEdges(ref, predicate) {
 });
 /**
  * Reverse all edge directions.
+ * @remarks
+ * ## Why
+ *
+ * Derives the reordered graph through its Effect collection operation while retaining RefSubject
+ * equality and version tracking.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running reverse performs one serialized graph 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
  */
@@ -168,18 +318,49 @@ export const reverse = (ref) => RefSubject.update(ref, (g) => {
 // ========================================
 /**
  * Get the node count.
+ * @remarks
+ * ## Why
+ *
+ * Get the node count. The operation remains attached to the RefSubject's versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The node count 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 nodeCount = (ref) => RefSubject.map(ref, Graph.nodeCount);
 /**
  * Get the edge count.
+ * @remarks
+ * ## Why
+ *
+ * Get the edge count. The operation remains attached to the RefSubject's versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The edge count 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 edgeCount = (ref) => RefSubject.map(ref, Graph.edgeCount);
 /**
  * Check if a node exists.
+ * @remarks
+ * ## Why
+ *
+ * Makes has node a live projection of the graph; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has 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
  */
@@ -188,6 +369,17 @@ export const hasNode = dual(2, function hasNode(ref, nodeIndex) {
 });
 /**
  * Check if an edge exists.
+ * @remarks
+ * ## Why
+ *
+ * Makes has edge a live projection of the graph; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has edge 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
  */
@@ -196,6 +388,17 @@ export const hasEdge = dual(3, function hasEdge(ref, source, target) {
 });
 /**
  * Get neighbors of a node.
+ * @remarks
+ * ## Why
+ *
+ * Get neighbors of a node. The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The neighbors 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
  */
@@ -204,6 +407,17 @@ export const neighbors = dual(2, function neighbors(ref, nodeIndex) {
 });
 /**
  * Get directed neighbors of a node.
+ * @remarks
+ * ## Why
+ *
+ * Get directed neighbors of a node. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The neighbors directed 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
  */
@@ -212,24 +426,69 @@ export const neighborsDirected = dual(3, function neighborsDirected(ref, nodeInd
 });
 /**
  * Check if the graph is acyclic.
+ * @remarks
+ * ## Why
+ *
+ * Check if the graph is acyclic. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is acyclic 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 isAcyclic = (ref) => RefSubject.map(ref, Graph.isAcyclic);
 /**
  * Check if the graph is bipartite (undirected only).
+ * @remarks
+ * ## Why
+ *
+ * Check if the graph is bipartite (undirected only). The operation remains attached to the
+ * RefSubject's versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is bipartite 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 isBipartite = (ref) => RefSubject.map(ref, Graph.isBipartite);
 /**
  * Get connected components (undirected only).
+ * @remarks
+ * ## Why
+ *
+ * Get connected components (undirected only). The operation remains attached to the RefSubject's
+ * versioned state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The connected components 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 connectedComponents = (ref) => RefSubject.map(ref, Graph.connectedComponents);
 /**
  * Get strongly connected components.
+ * @remarks
+ * ## Why
+ *
+ * Get strongly connected components. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * The strongly connected components 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
  */
@@ -239,6 +498,17 @@ export const stronglyConnectedComponents = (ref) => RefSubject.map(ref, Graph.st
 // ========================================
 /**
  * Get a node's data.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of get node as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get node 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
  */
@@ -247,6 +517,17 @@ export const getNode = dual(2, function getNode(ref, nodeIndex) {
 });
 /**
  * Get an edge's data.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of get edge as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get edge 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
  */
@@ -255,6 +536,17 @@ export const getEdge = dual(2, function getEdge(ref, edgeIndex) {
 });
 /**
  * Find a node matching a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of find node as Filtered state, so absence stays explicit
+ * while later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The find node 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
  */
@@ -263,6 +555,17 @@ export const findNode = dual(2, function findNode(ref, predicate) {
 });
 /**
  * Find an edge matching a predicate.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of find edge as Filtered state, so absence stays explicit
+ * while later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The find edge 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
  */