Merge pull request #4725 from xyflow/feat/use-handle-connection

add `useNodeConnections`, deprecate `useHandleConnections`

packages/svelte/src/lib/components/Handle/Handle.svelte

@@ -116,7 +116,7 @@
   $: if (onconnect || ondisconnect) {
     // connectionLookup is not reactive, so we use edges to get notified about updates
     $edges;
-    connections = $connectionLookup.get(`${nodeId}-${type}-${id || null}`);
+    connections = $connectionLookup.get(`${nodeId}-${type}${id ? `-${id}` : ''}`);
   }
 
   $: {

packages/svelte/src/lib/hooks/useHandleConnections.ts

@@ -16,14 +16,19 @@ const initialConnections: HandleConnection[] = [];
  *  Hook to check if a <Handle /> is connected to another <Handle /> and get the connections.
  *
  * @public
+ * @deprecated Use `useNodeConnections` instead.
  * @param param.nodeId
  * @param param.type - handle type 'source' or 'target'
  * @param param.id - the handle id (this is only needed if the node has multiple handles of the same type)
  * @returns an array with connections
  */
-export function useHandleConnections({ type, nodeId, id = null }: useHandleConnectionsParams) {
+export function useHandleConnections({ type, nodeId, id }: useHandleConnectionsParams) {
   const { edges, connectionLookup } = useStore();
 
+  console.warn(
+    '[DEPRECATED] `useHandleConnections` is deprecated. Instead use `useNodeConnections` https://svelteflow.dev/api-reference/hooks/useNodeConnections'
+  );
+
   const _nodeId = getContext<string>('svelteflow__node_id');
   const currentNodeId = nodeId ?? _nodeId;
 
@@ -32,7 +37,7 @@ export function useHandleConnections({ type, nodeId, id = null }: useHandleConne
   return derived(
     [edges, connectionLookup],
     ([, connectionLookup], set) => {
-      const nextConnections = connectionLookup.get(`${currentNodeId}-${type}-${id || null}`);
+      const nextConnections = connectionLookup.get(`${currentNodeId}-${type}${id ? `-${id}` : ''}`);
 
       if (!areConnectionMapsEqual(nextConnections, prevConnections)) {
         prevConnections = nextConnections;

packages/svelte/src/lib/hooks/useNodeConnections.ts

@@ -0,0 +1,62 @@
+import { derived } from 'svelte/store';
+import {
+  areConnectionMapsEqual,
+  errorMessages,
+  type NodeConnection,
+  type HandleType
+} from '@xyflow/system';
+
+import { useStore } from '$lib/store';
+import { getContext } from 'svelte';
+
+const error014 = errorMessages['error014']();
+
+type UseNodeConnectionsParams = {
+  type?: HandleType;
+  handleId?: string;
+  nodeId?: string;
+  // TODO: Svelte 5
+  //   onConnect?: (connections: Connection[]) => void;
+  //   onDisconnect?: (connections: Connection[]) => void;
+};
+
+const initialConnections: NodeConnection[] = [];
+
+/**
+ * Hook to retrieve all edges connected to a node. Can be filtered by handle type and id.
+ *
+ * @public
+ * @param param.nodeId - node id - optional if called inside a custom node
+ * @param param.type - filter by handle type 'source' or 'target'
+ * @param param.handleId - filter by handle id (this is only needed if the node has multiple handles of the same type)
+ * @todo @param param.onConnect - gets called when a connection is established
+ * @todo @param param.onDisconnect - gets called when a connection is removed
+ * @returns an array with connections
+ */
+export function useNodeConnections({ type, nodeId, handleId }: UseNodeConnectionsParams = {}) {
+  const { edges, connectionLookup } = useStore();
+
+  const _nodeId = getContext<string>('svelteflow__node_id');
+  const currentNodeId = nodeId ?? _nodeId;
+
+  if (!currentNodeId) {
+    throw new Error(error014);
+  }
+
+  let prevConnections: Map<string, NodeConnection> | undefined = undefined;
+
+  return derived(
+    [edges, connectionLookup],
+    ([, connectionLookup], set) => {
+      const nextConnections = connectionLookup.get(
+        `${currentNodeId}${type ? (handleId ? `-${type}-${handleId}` : `-${type}`) : ''}`
+      );
+
+      if (!areConnectionMapsEqual(nextConnections, prevConnections)) {
+        prevConnections = nextConnections;
+        set(Array.from(prevConnections?.values() || []));
+      }
+    },
+    initialConnections
+  );
+}

packages/svelte/src/lib/index.ts

@@ -31,6 +31,7 @@ export * from '$lib/hooks/useUpdateNodeInternals';
 export * from '$lib/hooks/useConnection';
 export * from '$lib/hooks/useNodesEdges';
 export * from '$lib/hooks/useHandleConnections';
+export * from '$lib/hooks/useNodeConnections';
 export * from '$lib/hooks/useNodesData';
 export * from '$lib/hooks/useInternalNode';
 export { useInitialized, useNodesInitialized } from '$lib/hooks/useInitialized';