effect 4.0.0-beta.31 → 4.0.0-beta.32

package/src/Graph.ts

@@ -65,7 +65,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>
 }
 
 /**
@@ -253,7 +253,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 +294,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 +685,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 +709,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 +733,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 +745,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 +862,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 +888,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 +914,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 +926,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()
 })
 
 /**
@@ -1228,7 +1230,7 @@ export const reverse = <N, E, T extends Kind = "directed">(
   }
 
   // Invalidate cycle flag since edge directions changed
-  mutable.acyclic = undefined
+  mutable.acyclic = Option.none()
 }
 
 /**
@@ -1439,10 +1441,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()
   }
 }
 
@@ -1450,10 +1451,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()
   }
 }
 
@@ -1704,10 +1704,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)
  * }
  * ```
  *
@@ -1735,17 +1735,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
   // =============================================================================
@@ -1766,21 +1766,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.
@@ -3237,8 +3237,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
@@ -3264,7 +3264,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
         }
 
@@ -3289,7 +3289,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
         }
 
@@ -3305,7 +3305,7 @@ export const isAcyclic = <N, E, T extends Kind = "directed">(
   }
 
   // Cache the result
-  graph.acyclic = true
+  graph.acyclic = Option.some(true)
   return true
 }
 
@@ -3649,9 +3649,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
  * }
  * ```
  *
@@ -3684,16 +3684,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.
    *
@@ -3719,20 +3719,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)
@@ -3743,11 +3743,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
@@ -3829,7 +3829,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
@@ -3848,11 +3848,11 @@ export const dijkstra: {
     }
   }
 
-  return {
+  return Option.some({
     path,
     distance,
     costs
-  }
+  })
 })
 
 /**
@@ -4116,9 +4116,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
  * }
  * ```
  *
@@ -4158,16 +4158,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.
    *
@@ -4200,20 +4200,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)
@@ -4224,11 +4224,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
@@ -4334,7 +4334,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
@@ -4353,11 +4353,11 @@ export const astar: {
     }
   }
 
-  return {
+  return Option.some({
     path,
     distance,
     costs
-  }
+  })
 })
 
 /**
@@ -4398,9 +4398,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
  * }
  * ```
  *
@@ -4434,16 +4434,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.
    *
@@ -4470,9 +4470,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
    * }
    * ```
    *
@@ -4482,11 +4482,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)
@@ -4497,11 +4497,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
@@ -4576,9 +4576,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()
       }
     }
   }
@@ -4586,7 +4586,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
@@ -4605,11 +4605,11 @@ export const bellmanFord: {
     }
   }
 
-  return {
+  return Option.some({
     path,
     distance,
     costs
-  }
+  })
 })
 
 /**

package/src/HashMap.ts

@@ -2092,10 +2092,12 @@ export const filterMap: {
  * @example
  * ```ts
  * import * as HashMap from "effect/HashMap"
+ * import * as Option from "effect/Option"
  *
  * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
  * const result = HashMap.findFirst(map, (value) => value > 1)
- * console.log(result) // [ 'c', 3 ]
+ * console.log(result) // Option.some(["c", 3])
+ * console.log(Option.getOrElse(result, () => ["", 0])) // ["c", 3]
  * ```
  *
  * @category elements
@@ -2109,16 +2111,18 @@ export const findFirst: {
    * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
+   * import * as Option from "effect/Option"
    *
    * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
    * const result = HashMap.findFirst(map, (value) => value > 1)
-   * console.log(result) // [ 'c', 3 ]
+   * console.log(result) // Option.some(["c", 3])
+   * console.log(Option.getOrElse(result, () => ["", 0])) // ["c", 3]
    * ```
    *
    * @category elements
    * @since 2.0.0
    */
-  <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => [K, A] | undefined
+  <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean): (self: HashMap<K, A>) => Option<[K, A]>
   /**
    * Returns the first element that satisfies the specified
    * predicate, or `None` if no such element exists.
@@ -2126,16 +2130,18 @@ export const findFirst: {
    * @example
    * ```ts
    * import * as HashMap from "effect/HashMap"
+   * import * as Option from "effect/Option"
    *
    * const map = HashMap.make(["a", 1], ["b", 2], ["c", 3])
    * const result = HashMap.findFirst(map, (value) => value > 1)
-   * console.log(result) // [ 'c', 3 ]
+   * console.log(result) // Option.some(["c", 3])
+   * console.log(Option.getOrElse(result, () => ["", 0])) // ["c", 3]
    * ```
    *
    * @category elements
    * @since 2.0.0
    */
-  <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): [K, A] | undefined
+  <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean): Option<[K, A]>
 } = internal.findFirst
 
 /**