effect 4.0.0-beta.4 → 4.0.0-beta.41

package/src/Graph.ts

@@ -11,6 +11,7 @@ import { NodeInspectSymbol } from "./Inspectable.ts"
 import * as Option from "./Option.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import { pipeArguments } from "./Pipeable.ts"
+import { hasProperty } from "./Predicate.ts"
 import type { Mutable } from "./Types.ts"
 
 const TypeId = "~effect/collections/Graph"
@@ -65,7 +66,7 @@ export interface Proto<out N, out E> extends Iterable<readonly [NodeIndex, N]>,
   readonly reverseAdjacency: Map<NodeIndex, Array<EdgeIndex>>
   nextNodeIndex: NodeIndex
   nextEdgeIndex: EdgeIndex
-  acyclic: boolean | undefined
+  acyclic: Option.Option<boolean>
 }
 
 /**
@@ -222,7 +223,7 @@ const missingNode = (node: number) => new GraphError({ message: `Node ${node} do
  * @since 4.0.0
  * @category Guards
  */
-export const isGraph = (u: unknown): u is Graph<unknown, unknown> => typeof u === "object" && u !== null && TypeId in u
+export const isGraph = (u: unknown): u is Graph<unknown, unknown> => hasProperty(u, TypeId)
 
 /**
  * Creates a directed graph, optionally with initial mutations.
@@ -253,7 +254,7 @@ export const directed = <N, E>(mutate?: (mutable: MutableDirectedGraph<N, E>) =>
   graph.reverseAdjacency = new Map()
   graph.nextNodeIndex = 0
   graph.nextEdgeIndex = 0
-  graph.acyclic = true
+  graph.acyclic = Option.some(true)
   graph.mutable = false
 
   if (mutate) {
@@ -294,7 +295,7 @@ export const undirected = <N, E>(mutate?: (mutable: MutableUndirectedGraph<N, E>
   graph.reverseAdjacency = new Map()
   graph.nextNodeIndex = 0
   graph.nextEdgeIndex = 0
-  graph.acyclic = true
+  graph.acyclic = Option.some(true)
   graph.mutable = false
 
   if (mutate) {
@@ -685,10 +686,10 @@ export const nodeCount = <N, E, T extends Kind = "directed">(
  * })
  *
  * const result = Graph.findNode(graph, (data) => data.startsWith("Node B"))
- * console.log(result) // 1
+ * console.log(result) // Option.some(1)
  *
  * const notFound = Graph.findNode(graph, (data) => data === "Node D")
- * console.log(notFound) // undefined
+ * console.log(notFound) // Option.none()
  * ```
  *
  * @since 4.0.0
@@ -709,16 +710,16 @@ export const findNode: {
    * })
    *
    * const result = Graph.findNode(graph, (data) => data.startsWith("Node B"))
-   * console.log(result) // 1
+   * console.log(result) // Option.some(1)
    *
    * const notFound = Graph.findNode(graph, (data) => data === "Node D")
-   * console.log(notFound) // undefined
+   * console.log(notFound) // Option.none()
    * ```
    *
    * @since 4.0.0
    * @category getters
    */
-  <N>(predicate: (data: N) => boolean): <E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => NodeIndex | undefined
+  <N>(predicate: (data: N) => boolean): <E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<NodeIndex>
   /**
    * Finds the first node that matches the given predicate.
    *
@@ -733,10 +734,10 @@ export const findNode: {
    * })
    *
    * const result = Graph.findNode(graph, (data) => data.startsWith("Node B"))
-   * console.log(result) // 1
+   * console.log(result) // Option.some(1)
    *
    * const notFound = Graph.findNode(graph, (data) => data === "Node D")
-   * console.log(notFound) // undefined
+   * console.log(notFound) // Option.none()
    * ```
    *
    * @since 4.0.0
@@ -745,16 +746,17 @@ export const findNode: {
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
     predicate: (data: N) => boolean
-  ): NodeIndex | undefined
+  ): Option.Option<NodeIndex>
 } = dual(2, <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>,
   predicate: (data: N) => boolean
-): NodeIndex | undefined => {
+): Option.Option<NodeIndex> => {
   for (const [index, data] of graph.nodes) {
     if (predicate(data)) {
-      return index
+      return Option.some(index)
     }
   }
+  return Option.none()
 })
 
 /**
@@ -861,10 +863,10 @@ export const findNodes: {
  * })
  *
  * const result = Graph.findEdge(graph, (data) => data > 15)
- * console.log(result) // 1
+ * console.log(result) // Option.some(1)
  *
  * const notFound = Graph.findEdge(graph, (data) => data > 100)
- * console.log(notFound) // undefined
+ * console.log(notFound) // Option.none()
  * ```
  *
  * @since 4.0.0
@@ -887,16 +889,16 @@ export const findEdge: {
    * })
    *
    * const result = Graph.findEdge(graph, (data) => data > 15)
-   * console.log(result) // 1
+   * console.log(result) // Option.some(1)
    *
    * const notFound = Graph.findEdge(graph, (data) => data > 100)
-   * console.log(notFound) // undefined
+   * console.log(notFound) // Option.none()
    * ```
    *
    * @since 4.0.0
    * @category getters
    */
-  <E>(predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => EdgeIndex | undefined
+  <E>(predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<EdgeIndex>
   /**
    * Finds the first edge that matches the given predicate.
    *
@@ -913,10 +915,10 @@ export const findEdge: {
    * })
    *
    * const result = Graph.findEdge(graph, (data) => data > 15)
-   * console.log(result) // 1
+   * console.log(result) // Option.some(1)
    *
    * const notFound = Graph.findEdge(graph, (data) => data > 100)
-   * console.log(notFound) // undefined
+   * console.log(notFound) // Option.none()
    * ```
    *
    * @since 4.0.0
@@ -925,16 +927,17 @@ export const findEdge: {
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
     predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean
-  ): EdgeIndex | undefined
+  ): Option.Option<EdgeIndex>
 } = dual(2, <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>,
   predicate: (data: E, source: NodeIndex, target: NodeIndex) => boolean
-): EdgeIndex | undefined => {
+): Option.Option<EdgeIndex> => {
   for (const [edgeIndex, edgeData] of graph.edges) {
     if (predicate(edgeData.data, edgeData.source, edgeData.target)) {
-      return edgeIndex
+      return Option.some(edgeIndex)
     }
   }
+  return Option.none()
 })
 
 /**
@@ -1200,11 +1203,14 @@ export const reverse = <N, E, T extends Kind = "directed">(
 ): void => {
   // Reverse all edges by swapping source and target
   for (const [index, edgeData] of mutable.edges) {
-    mutable.edges.set(index, {
-      source: edgeData.target,
-      target: edgeData.source,
-      data: edgeData.data
-    })
+    mutable.edges.set(
+      index,
+      new Edge({
+        source: edgeData.target,
+        target: edgeData.source,
+        data: edgeData.data
+      })
+    )
   }
 
   // Clear and rebuild adjacency lists with reversed directions
@@ -1225,7 +1231,7 @@ export const reverse = <N, E, T extends Kind = "directed">(
   }
 
   // Invalidate cycle flag since edge directions changed
-  mutable.acyclic = undefined
+  mutable.acyclic = Option.none()
 }
 
 /**
@@ -1436,10 +1442,9 @@ export const filterEdges = <N, E, T extends Kind = "directed">(
 const invalidateCycleFlagOnRemoval = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>
 ): void => {
-  // Only invalidate if the graph had cycles (removing edges/nodes cannot introduce cycles in acyclic graphs)
-  // If already unknown (null) or acyclic (true), no need to change
-  if (mutable.acyclic === false) {
-    mutable.acyclic = undefined
+  // Only invalidate if the graph had cycles (removing edges/nodes cannot introduce cycles in acyclic graphs).
+  if (mutable.acyclic._tag === "Some" && mutable.acyclic.value === false) {
+    mutable.acyclic = Option.none()
   }
 }
 
@@ -1447,10 +1452,9 @@ const invalidateCycleFlagOnRemoval = <N, E, T extends Kind = "directed">(
 const invalidateCycleFlagOnAddition = <N, E, T extends Kind = "directed">(
   mutable: MutableGraph<N, E, T>
 ): void => {
-  // Only invalidate if the graph was acyclic (adding edges cannot remove cycles from cyclic graphs)
-  // If already unknown (null) or cyclic (false), no need to change
-  if (mutable.acyclic === true) {
-    mutable.acyclic = undefined
+  // Only invalidate if the graph was acyclic (adding edges cannot remove cycles from cyclic graphs).
+  if (mutable.acyclic._tag === "Some" && mutable.acyclic.value === true) {
+    mutable.acyclic = Option.none()
   }
 }
 
@@ -1701,10 +1705,10 @@ const removeEdgeInternal = <N, E, T extends Kind = "directed">(
  * const edgeIndex = 0
  * const edgeData = Graph.getEdge(graph, edgeIndex)
  *
- * if (edgeData !== undefined) {
- *   console.log(edgeData.data) // 42
- *   console.log(edgeData.source) // NodeIndex(0)
- *   console.log(edgeData.target) // NodeIndex(1)
+ * if (edgeData._tag === "Some") {
+ *   console.log(edgeData.value.data) // 42
+ *   console.log(edgeData.value.source) // NodeIndex(0)
+ *   console.log(edgeData.value.target) // NodeIndex(1)
  * }
  * ```
  *
@@ -1732,17 +1736,17 @@ export const getEdge: {
    * const edgeIndex = 0
    * const edgeData = Graph.getEdge(graph, edgeIndex)
    *
-   * if (edgeData !== undefined) {
-   *   console.log(edgeData.data) // 42
-   *   console.log(edgeData.source) // NodeIndex(0)
-   *   console.log(edgeData.target) // NodeIndex(1)
+   * if (edgeData._tag === "Some") {
+   *   console.log(edgeData.value.data) // 42
+   *   console.log(edgeData.value.source) // NodeIndex(0)
+   *   console.log(edgeData.value.target) // NodeIndex(1)
    * }
    * ```
    *
    * @since 4.0.0
    * @category getters
    */
-  <E>(edgeIndex: EdgeIndex): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Edge<E> | undefined
+  <E>(edgeIndex: EdgeIndex): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<Edge<E>>
   // =============================================================================
   // Edge Query Operations
   // =============================================================================
@@ -1763,21 +1767,21 @@ export const getEdge: {
    * const edgeIndex = 0
    * const edgeData = Graph.getEdge(graph, edgeIndex)
    *
-   * if (edgeData !== undefined) {
-   *   console.log(edgeData.data) // 42
-   *   console.log(edgeData.source) // NodeIndex(0)
-   *   console.log(edgeData.target) // NodeIndex(1)
+   * if (edgeData._tag === "Some") {
+   *   console.log(edgeData.value.data) // 42
+   *   console.log(edgeData.value.source) // NodeIndex(0)
+   *   console.log(edgeData.value.target) // NodeIndex(1)
    * }
    * ```
    *
    * @since 4.0.0
    * @category getters
    */
-  <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, edgeIndex: EdgeIndex): Edge<E> | undefined
+  <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, edgeIndex: EdgeIndex): Option.Option<Edge<E>>
 } = dual(2, <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>,
   edgeIndex: EdgeIndex
-): Edge<E> | undefined => graph.edges.get(edgeIndex))
+): Option.Option<Edge<E>> => Option.fromUndefinedOr(graph.edges.get(edgeIndex)))
 
 /**
  * Checks if an edge exists between two nodes in the graph.
@@ -2526,13 +2530,23 @@ export interface MermaidOptions<N, E> {
  * Escapes special characters in labels for Mermaid syntax compatibility.
  */
 const escapeMermaidLabel = (label: string): string => {
+  // Escape special characters for Mermaid using HTML entity codes
+  // According to: https://mermaid.js.org/syntax/flowchart.html#special-characters-that-break-syntax
   return label
-    .replace(/\\/g, "\\\\") // Escape backslashes first
-    .replace(/"/g, "\\\"") // Escape quotes
-    .replace(/\[/g, "\\[") // Escape square brackets
-    .replace(/\]/g, "\\]") // Escape square brackets
-    .replace(/\|/g, "\\|") // Escape pipes
-    .replace(/\n/g, "<br/>"); // Convert newlines to HTML breaks
+    .replace(/#/g, "#35;")
+    .replace(/"/g, "#quot;")
+    .replace(/</g, "#lt;")
+    .replace(/>/g, "#gt;")
+    .replace(/&/g, "#amp;")
+    .replace(/\[/g, "#91;")
+    .replace(/\]/g, "#93;")
+    .replace(/\{/g, "#123;")
+    .replace(/\}/g, "#125;")
+    .replace(/\(/g, "#40;")
+    .replace(/\)/g, "#41;")
+    .replace(/\|/g, "#124;")
+    .replace(/\\/g, "#92;")
+    .replace(/\n/g, "<br/>");
 }
 
 /**
@@ -3224,8 +3238,8 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>
 ): boolean => {
   // Use existing cycle flag if available
-  if (graph.acyclic !== undefined) {
-    return graph.acyclic
+  if (Option.isSome(graph.acyclic)) {
+    return graph.acyclic.value
   }
 
   // Stack-safe DFS cycle detection using iterative approach
@@ -3251,7 +3265,7 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
       if (isFirstVisit) {
         if (recursionStack.has(node)) {
           // Back edge found - cycle detected
-          graph.acyclic = false
+          graph.acyclic = Option.some(false)
           return false
         }
 
@@ -3276,7 +3290,7 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
 
         if (recursionStack.has(neighbor)) {
           // Back edge found - cycle detected
-          graph.acyclic = false
+          graph.acyclic = Option.some(false)
           return false
         }
 
@@ -3292,7 +3306,7 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
   }
 
   // Cache the result
-  graph.acyclic = true
+  graph.acyclic = Option.some(true)
   return true
 }
 
@@ -3636,9 +3650,9 @@ export interface DijkstraConfig<E> {
  *   cost: (edgeData) => edgeData
  * })
  *
- * if (result !== undefined) {
- *   console.log(result.path) // [0, 1, 2] - shortest path A->B->C
- *   console.log(result.distance) // 7 - total distance
+ * if (result._tag === "Some") {
+ *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
+ *   console.log(result.value.distance) // 7 - total distance
  * }
  * ```
  *
@@ -3671,16 +3685,16 @@ export const dijkstra: {
    *   cost: (edgeData) => edgeData
    * })
    *
-   * if (result !== undefined) {
-   *   console.log(result.path) // [0, 1, 2] - shortest path A->B->C
-   *   console.log(result.distance) // 7 - total distance
+   * if (result._tag === "Some") {
+   *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
+   *   console.log(result.value.distance) // 7 - total distance
    * }
    * ```
    *
    * @since 4.0.0
    * @category algorithms
    */
-  <E>(config: DijkstraConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => PathResult<E> | undefined
+  <E>(config: DijkstraConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>
   /**
    * Find the shortest path between two nodes using Dijkstra's algorithm.
    *
@@ -3706,20 +3720,20 @@ export const dijkstra: {
    *   cost: (edgeData) => edgeData
    * })
    *
-   * if (result !== undefined) {
-   *   console.log(result.path) // [0, 1, 2] - shortest path A->B->C
-   *   console.log(result.distance) // 7 - total distance
+   * if (result._tag === "Some") {
+   *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
+   *   console.log(result.value.distance) // 7 - total distance
    * }
    * ```
    *
    * @since 4.0.0
    * @category algorithms
    */
-  <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: DijkstraConfig<E>): PathResult<E> | undefined
+  <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: DijkstraConfig<E>): Option.Option<PathResult<E>>
 } = dual(2, <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>,
   config: DijkstraConfig<E>
-): PathResult<E> | undefined => {
+): Option.Option<PathResult<E>> => {
   // Validate that source and target nodes exist
   if (!graph.nodes.has(config.source)) {
     throw missingNode(config.source)
@@ -3730,11 +3744,11 @@ export const dijkstra: {
 
   // Early return if source equals target
   if (config.source === config.target) {
-    return {
+    return Option.some({
       path: [config.source],
       distance: 0,
       costs: []
-    }
+    })
   }
 
   // Distance tracking and priority queue simulation
@@ -3816,7 +3830,7 @@ export const dijkstra: {
   // Check if target is reachable
   const distance = distances.get(config.target)!
   if (distance === Infinity) {
-    return undefined // No path exists
+    return Option.none() // No path exists
   }
 
   // Reconstruct path
@@ -3835,11 +3849,11 @@ export const dijkstra: {
     }
   }
 
-  return {
+  return Option.some({
     path,
     distance,
     costs
-  }
+  })
 })
 
 /**
@@ -4103,9 +4117,9 @@ export interface AstarConfig<E, N> {
  *   heuristic
  * })
  *
- * if (result !== undefined) {
- *   console.log(result.path) // [0, 1, 2] - shortest path
- *   console.log(result.distance) // 2 - total distance
+ * if (result._tag === "Some") {
+ *   console.log(result.value.path) // [0, 1, 2] - shortest path
+ *   console.log(result.value.distance) // 2 - total distance
  * }
  * ```
  *
@@ -4145,16 +4159,16 @@ export const astar: {
    *   heuristic
    * })
    *
-   * if (result !== undefined) {
-   *   console.log(result.path) // [0, 1, 2] - shortest path
-   *   console.log(result.distance) // 2 - total distance
+   * if (result._tag === "Some") {
+   *   console.log(result.value.path) // [0, 1, 2] - shortest path
+   *   console.log(result.value.distance) // 2 - total distance
    * }
    * ```
    *
    * @since 4.0.0
    * @category algorithms
    */
-  <E, N>(config: AstarConfig<E, N>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => PathResult<E> | undefined
+  <E, N>(config: AstarConfig<E, N>): <T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>
   /**
    * Find the shortest path between two nodes using A* pathfinding algorithm.
    *
@@ -4187,20 +4201,20 @@ export const astar: {
    *   heuristic
    * })
    *
-   * if (result !== undefined) {
-   *   console.log(result.path) // [0, 1, 2] - shortest path
-   *   console.log(result.distance) // 2 - total distance
+   * if (result._tag === "Some") {
+   *   console.log(result.value.path) // [0, 1, 2] - shortest path
+   *   console.log(result.value.distance) // 2 - total distance
    * }
    * ```
    *
    * @since 4.0.0
    * @category algorithms
    */
-  <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: AstarConfig<E, N>): PathResult<E> | undefined
+  <N, E, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>, config: AstarConfig<E, N>): Option.Option<PathResult<E>>
 } = dual(2, <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>,
   config: AstarConfig<E, N>
-): PathResult<E> | undefined => {
+): Option.Option<PathResult<E>> => {
   // Validate that source and target nodes exist
   if (!graph.nodes.has(config.source)) {
     throw missingNode(config.source)
@@ -4211,11 +4225,11 @@ export const astar: {
 
   // Early return if source equals target
   if (config.source === config.target) {
-    return {
+    return Option.some({
       path: [config.source],
       distance: 0,
       costs: []
-    }
+    })
   }
 
   // Get target node data for heuristic calculations
@@ -4321,7 +4335,7 @@ export const astar: {
   // Check if target is reachable
   const distance = gScore.get(config.target)!
   if (distance === Infinity) {
-    return undefined // No path exists
+    return Option.none() // No path exists
   }
 
   // Reconstruct path
@@ -4340,11 +4354,11 @@ export const astar: {
     }
   }
 
-  return {
+  return Option.some({
     path,
     distance,
     costs
-  }
+  })
 })
 
 /**
@@ -4385,9 +4399,9 @@ export interface BellmanFordConfig<E> {
  *   cost: (edgeData) => edgeData
  * })
  *
- * if (result !== undefined) {
- *   console.log(result.path) // [0, 1, 2] - shortest path A->B->C
- *   console.log(result.distance) // 2 - total distance
+ * if (result._tag === "Some") {
+ *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
+ *   console.log(result.value.distance) // 2 - total distance
  * }
  * ```
  *
@@ -4421,16 +4435,16 @@ export const bellmanFord: {
    *   cost: (edgeData) => edgeData
    * })
    *
-   * if (result !== undefined) {
-   *   console.log(result.path) // [0, 1, 2] - shortest path A->B->C
-   *   console.log(result.distance) // 2 - total distance
+   * if (result._tag === "Some") {
+   *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
+   *   console.log(result.value.distance) // 2 - total distance
    * }
    * ```
    *
    * @since 4.0.0
    * @category algorithms
    */
-  <E>(config: BellmanFordConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => PathResult<E> | undefined
+  <E>(config: BellmanFordConfig<E>): <N, T extends Kind = "directed">(graph: Graph<N, E, T> | MutableGraph<N, E, T>) => Option.Option<PathResult<E>>
   /**
    * Find the shortest path between two nodes using Bellman-Ford algorithm.
    *
@@ -4457,9 +4471,9 @@ export const bellmanFord: {
    *   cost: (edgeData) => edgeData
    * })
    *
-   * if (result !== undefined) {
-   *   console.log(result.path) // [0, 1, 2] - shortest path A->B->C
-   *   console.log(result.distance) // 2 - total distance
+   * if (result._tag === "Some") {
+   *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
+   *   console.log(result.value.distance) // 2 - total distance
    * }
    * ```
    *
@@ -4469,11 +4483,11 @@ export const bellmanFord: {
   <N, E, T extends Kind = "directed">(
     graph: Graph<N, E, T> | MutableGraph<N, E, T>,
     config: BellmanFordConfig<E>
-  ): PathResult<E> | undefined
+  ): Option.Option<PathResult<E>>
 } = dual(2, <N, E, T extends Kind = "directed">(
   graph: Graph<N, E, T> | MutableGraph<N, E, T>,
   config: BellmanFordConfig<E>
-): PathResult<E> | undefined => {
+): Option.Option<PathResult<E>> => {
   // Validate that source and target nodes exist
   if (!graph.nodes.has(config.source)) {
     throw missingNode(config.source)
@@ -4484,11 +4498,11 @@ export const bellmanFord: {
 
   // Early return if source equals target
   if (config.source === config.target) {
-    return {
+    return Option.some({
       path: [config.source],
       distance: 0,
       costs: []
-    }
+    })
   }
 
   // Initialize distances and predecessors
@@ -4563,9 +4577,9 @@ export const bellmanFord: {
         }
       }
 
-      // If target is affected by negative cycle, return null
+      // If target is affected by a negative cycle, no shortest path exists.
       if (affectedNodes.has(config.target)) {
-        return undefined
+        return Option.none()
       }
     }
   }
@@ -4573,7 +4587,7 @@ export const bellmanFord: {
   // Check if target is reachable
   const distance = distances.get(config.target)!
   if (distance === Infinity) {
-    return undefined // No path exists
+    return Option.none() // No path exists
   }
 
   // Reconstruct path
@@ -4592,11 +4606,11 @@ export const bellmanFord: {
     }
   }
 
-  return {
+  return Option.some({
     path,
     distance,
     costs
-  }
+  })
 })
 
 /**