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

package/dist/RefSubject/RefGraph.js

@@ -5,28 +5,60 @@
 import { equals } from "effect/Equal";
 import { dual } from "effect/Function";
 import * as Graph from "effect/Graph";
-import * as Option from "effect/Option";
 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
+ * @category Constructors
  */
 export function make(initial) {
     return RefSubject.make(initial, { eq: equals });
 }
 /**
  * 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
+ * @category Constructors
  */
 export function directed() {
     return RefSubject.make(Graph.directed(), { eq: equals });
 }
 /**
  * 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
+ * @category Constructors
  */
 export function undirected() {
     return RefSubject.make(Graph.undirected(), { eq: equals });
@@ -36,8 +68,19 @@ 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
+ * @category State updates
  */
 export const addNode = dual(2, function addNode(ref, data) {
     return RefSubject.update(ref, (g) => {
@@ -48,8 +91,19 @@ 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
+ * @category State updates
  */
 export const removeNode = dual(2, function removeNode(ref, nodeIndex) {
     return RefSubject.update(ref, (g) => {
@@ -60,8 +114,19 @@ 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
+ * @category State updates
  */
 export const updateNode = dual(3, function updateNode(ref, nodeIndex, f) {
     return RefSubject.update(ref, (g) => {
@@ -72,8 +137,19 @@ 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
+ * @category State updates
  */
 export const addEdge = dual(4, function addEdge(ref, source, target, data) {
     return RefSubject.update(ref, (g) => {
@@ -84,8 +160,19 @@ 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
+ * @category State updates
  */
 export const removeEdge = dual(2, function removeEdge(ref, edgeIndex) {
     return RefSubject.update(ref, (g) => {
@@ -96,8 +183,19 @@ 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
+ * @category State updates
  */
 export const updateEdge = dual(3, function updateEdge(ref, edgeIndex, f) {
     return RefSubject.update(ref, (g) => {
@@ -108,8 +206,18 @@ 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
+ * @category State updates
  */
 export const mapNodes = dual(2, function mapNodes(ref, f) {
     return RefSubject.update(ref, (g) => {
@@ -120,8 +228,18 @@ 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
+ * @category State updates
  */
 export const mapEdges = dual(2, function mapEdges(ref, f) {
     return RefSubject.update(ref, (g) => {
@@ -132,8 +250,18 @@ 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
+ * @category State updates
  */
 export const filterNodes = dual(2, function filterNodes(ref, predicate) {
     return RefSubject.update(ref, (g) => {
@@ -144,8 +272,18 @@ 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
+ * @category State updates
  */
 export const filterEdges = dual(2, function filterEdges(ref, predicate) {
     return RefSubject.update(ref, (g) => {
@@ -156,8 +294,19 @@ 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
+ * @category State updates
  */
 export const reverse = (ref) => RefSubject.update(ref, (g) => {
     const mutable = Graph.beginMutation(g);
@@ -169,70 +318,179 @@ 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
+ * @category Derived queries
  */
 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
+ * @category Derived queries
  */
 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
+ * @category State predicates
  */
 export const hasNode = dual(2, function hasNode(ref, nodeIndex) {
     return RefSubject.map(ref, Graph.hasNode(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
+ * @category State predicates
  */
 export const hasEdge = dual(3, function hasEdge(ref, source, target) {
     return RefSubject.map(ref, Graph.hasEdge(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
+ * @category Derived queries
  */
 export const neighbors = dual(2, function neighbors(ref, nodeIndex) {
     return RefSubject.map(ref, Graph.neighbors(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
+ * @category Derived queries
  */
 export const neighborsDirected = dual(3, function neighborsDirected(ref, nodeIndex, direction) {
     return RefSubject.map(ref, Graph.neighborsDirected(nodeIndex, direction));
 });
 /**
  * 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
+ * @category State predicates
  */
 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
+ * @category State predicates
  */
 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
+ * @category Derived queries
  */
 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
+ * @category Derived queries
  */
 export const stronglyConnectedComponents = (ref) => RefSubject.map(ref, Graph.stronglyConnectedComponents);
 // ========================================
@@ -240,33 +498,77 @@ 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
+ * @category Optional queries
  */
 export const getNode = dual(2, function getNode(ref, nodeIndex) {
     return RefSubject.filterMap(ref, Graph.getNode(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
+ * @category Optional queries
  */
 export const getEdge = dual(2, function getEdge(ref, edgeIndex) {
-    return RefSubject.filterMap(ref, (g) => Option.fromUndefinedOr(Graph.getEdge(g, edgeIndex)));
+    return RefSubject.filterMap(ref, (g) => Graph.getEdge(g, 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
+ * @category Optional queries
  */
 export const findNode = dual(2, function findNode(ref, predicate) {
-    return RefSubject.filterMap(ref, (g) => Option.fromUndefinedOr(Graph.findNode(g, predicate)));
+    return RefSubject.filterMap(ref, (g) => Graph.findNode(g, 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
+ * @category Optional queries
  */
 export const findEdge = dual(2, function findEdge(ref, predicate) {
-    return RefSubject.filterMap(ref, (g) => Option.fromUndefinedOr(Graph.findEdge(g, predicate)));
+    return RefSubject.filterMap(ref, (g) => Graph.findEdge(g, predicate));
 });