LCOV - code coverage report
Current view: top level - packages/graph-model/src - nodeIdentification.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 87.4 % 87 76
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : import { parseNodeId, toNodeId } from './nodeId'
       2              : import type { NodeId, SerializedNodeId } from './nodeId'
       3              : 
       4         2356 : const UUID_PATTERN =
       5              :   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
       6         2356 : const ENCODED_ROOT_LOCATOR_PREFIX = '~root:'
       7         2356 : const ENCODED_SUBGRAPH_LOCATOR_PREFIX = '~subgraph:'
       8              : 
       9              : interface ParsedNodeLocatorId {
      10              :   subgraphUuid: string | null
      11              :   localNodeId: NodeId
      12              : }
      13              : 
      14           18 : function decodeNodeId(value: string): NodeId | null {
      15           18 :   try {
      16           18 :     const decoded = decodeURIComponent(value)
      17           18 :     return encodeURIComponent(decoded) === value ? toNodeId(decoded) : null
      18              :   } catch {
      19            0 :     return null
      20              :   }
      21              : }
      22              : 
      23            5 : function parseEncodedSubgraphLocator(id: string): ParsedNodeLocatorId | null {
      24            5 :   const encodedLocator = id.slice(ENCODED_SUBGRAPH_LOCATOR_PREFIX.length)
      25            5 :   const separatorIndex = encodedLocator.indexOf(':')
      26            5 :   if (separatorIndex === -1) return null
      27              : 
      28            5 :   const subgraphUuid = encodedLocator.slice(0, separatorIndex)
      29            5 :   if (!UUID_PATTERN.test(subgraphUuid)) return null
      30              : 
      31            5 :   const localNodeId = decodeNodeId(encodedLocator.slice(separatorIndex + 1))
      32            5 :   return localNodeId !== null ? { subgraphUuid, localNodeId } : null
      33              : }
      34              : 
      35              : /**
      36              :  * A globally unique identifier for nodes that maintains consistency across
      37              :  * multiple instances of the same subgraph.
      38              :  *
      39              :  * Format:
      40              :  * - For subgraph nodes: `<immediate-contained-subgraph-uuid>:<local-node-id>`
      41              :  * - For root graph nodes: `<local-node-id>`
      42              :  *
      43              :  * Examples:
      44              :  * - "a1b2c3d4-e5f6-7890-abcd-ef1234567890:123" (node in subgraph)
      45              :  * - "456" (node in root graph)
      46              :  *
      47              :  * Unlike execution IDs which change based on the instance path,
      48              :  * NodeLocatorId remains the same for all instances of a particular node.
      49              :  */
      50              : export type NodeLocatorId = string & { readonly __brand: 'NodeLocatorId' }
      51              : 
      52              : /**
      53              :  * An execution identifier representing a node's position in nested subgraphs.
      54              :  * Also known as ExecutionId in some contexts.
      55              :  *
      56              :  * Format: Colon-separated path of node IDs
      57              :  * Example: "123:456:789" (node 789 in subgraph 456 in subgraph 123)
      58              :  */
      59              : export type NodeExecutionId = string & { readonly __brand: 'NodeExecutionId' }
      60              : 
      61      1253991 : function requireNodeIdSegment(value: unknown): NodeId | null {
      62      1253991 :   const nodeId = parseNodeId(value)
      63      1253991 :   if (!nodeId || nodeId.includes(':')) return null
      64      1253899 :   return nodeId
      65              : }
      66              : 
      67       684821 : function parseNodeIdSegments(values: readonly unknown[]): NodeId[] | null {
      68       684821 :   const nodeIds = values.map(requireNodeIdSegment)
      69       684821 :   return nodeIds.every((nodeId): nodeId is NodeId => nodeId !== null)
      70              :     ? nodeIds
      71              :     : null
      72              : }
      73              : 
      74       342759 : function nodeExecutionIdFromString(value: string): NodeExecutionId | null {
      75       342759 :   return parseNodeIdSegments(value.split(':'))
      76              :     ? (value as NodeExecutionId)
      77              :     : null
      78              : }
      79              : 
      80              : /**
      81              :  * Type guard to check if a value is a NodeLocatorId
      82              :  */
      83            3 : export function isNodeLocatorId(value: unknown): value is NodeLocatorId {
      84            3 :   return typeof value === 'string' && parseNodeLocatorId(value) !== null
      85              : }
      86              : 
      87              : /**
      88              :  * Type guard to check if a value is a NodeExecutionId
      89              :  */
      90              : export function isNodeExecutionId(value: unknown): value is NodeExecutionId {
      91              :   return typeof value === 'string' && nodeExecutionIdFromString(value) !== null
      92              : }
      93              : 
      94              : /**
      95              :  * Parse a NodeLocatorId into its components
      96              :  * @param id The NodeLocatorId to parse
      97              :  * @returns The subgraph UUID and local node ID, or null if invalid
      98              :  */
      99        69234 : export function parseNodeLocatorId(id: string): ParsedNodeLocatorId | null {
     100        69234 :   if (id.startsWith(ENCODED_ROOT_LOCATOR_PREFIX)) {
     101           13 :     const localNodeId = decodeNodeId(
     102              :       id.slice(ENCODED_ROOT_LOCATOR_PREFIX.length)
     103              :     )
     104           13 :     return localNodeId !== null ? { subgraphUuid: null, localNodeId } : null
     105              :   }
     106              : 
     107        69234 :   if (id.startsWith(ENCODED_SUBGRAPH_LOCATOR_PREFIX)) {
     108            5 :     return parseEncodedSubgraphLocator(id)
     109              :   }
     110              : 
     111        69216 :   const parts = id.split(':')
     112              : 
     113        69216 :   if (parts.length === 1) {
     114        68541 :     const localNodeId = requireNodeIdSegment(id)
     115        68541 :     if (!localNodeId) return null
     116              : 
     117        68541 :     return { subgraphUuid: null, localNodeId }
     118              :   }
     119              : 
     120         6491 :   if (parts.length !== 2) return null
     121              : 
     122          675 :   const [subgraphUuid, localNodeIdPart] = parts
     123         6491 :   if (!UUID_PATTERN.test(subgraphUuid)) return null
     124              : 
     125          675 :   const localNodeId = requireNodeIdSegment(localNodeIdPart)
     126         6491 :   if (!localNodeId) return null
     127              : 
     128          675 :   return { subgraphUuid, localNodeId }
     129              : }
     130              : 
     131              : /**
     132              :  * Create a NodeLocatorId from components
     133              :  * @param subgraphUuid The UUID of the immediate containing subgraph
     134              :  * @param localNodeId The local node ID within that subgraph
     135              :  * @returns A locator that encodes local IDs that are not plain segments, or
     136              :  * `null` when the containing subgraph ID is not a UUID
     137              :  */
     138              : export function createNodeLocatorId(
     139              :   subgraphUuid: string | null,
     140              :   localNodeId: SerializedNodeId
     141              : ): NodeLocatorId
     142       454663 : export function createNodeLocatorId(
     143              :   subgraphUuid: string | null,
     144              :   localNodeId: SerializedNodeId
     145              : ): NodeLocatorId | null {
     146       454663 :   const nodeId = requireNodeIdSegment(localNodeId)
     147       454663 :   if (subgraphUuid && !UUID_PATTERN.test(subgraphUuid)) return null
     148              : 
     149       454663 :   if (nodeId) {
     150       454602 :     if (!subgraphUuid) return String(nodeId) as NodeLocatorId
     151              : 
     152        10157 :     return `${subgraphUuid}:${nodeId}` as NodeLocatorId
     153              :   }
     154              : 
     155           61 :   const encodedNodeId = encodeURIComponent(String(localNodeId))
     156       454663 :   return subgraphUuid
     157              :     ? (`${ENCODED_SUBGRAPH_LOCATOR_PREFIX}${subgraphUuid}:${encodedNodeId}` as NodeLocatorId)
     158              :     : (`${ENCODED_ROOT_LOCATOR_PREFIX}${encodedNodeId}` as NodeLocatorId)
     159              : }
     160              : 
     161              : /**
     162              :  * Parse a NodeExecutionId into its component node IDs
     163              :  * @param id The NodeExecutionId to parse
     164              :  * @returns Array of node IDs from root to target, or null if not an execution ID
     165              :  */
     166        40268 : export function parseNodeExecutionId(id: string): NodeId[] | null {
     167        40268 :   const executionId = tryNormalizeNodeExecutionId(id)
     168        40268 :   if (!executionId) return null
     169              : 
     170        40268 :   return parseNodeIdSegments(executionId.split(':'))
     171              : }
     172              : 
     173              : /**
     174              :  * Create a NodeExecutionId from an array of node IDs
     175              :  * @param nodeIds Array of node IDs from root to target
     176              :  * @returns A properly formatted NodeExecutionId, or null when any segment is invalid
     177              :  */
     178              : export function createNodeExecutionId(
     179              :   nodeIds: readonly [SerializedNodeId, ...SerializedNodeId[]]
     180              : ): NodeExecutionId
     181              : export function createNodeExecutionId(
     182              :   nodeIds: readonly SerializedNodeId[]
     183              : ): NodeExecutionId | null
     184       301794 : export function createNodeExecutionId(
     185              :   nodeIds: readonly SerializedNodeId[]
     186              : ): NodeExecutionId | null {
     187       301794 :   if (nodeIds.length === 0) return null
     188              : 
     189       301794 :   const nodeIdSegments = parseNodeIdSegments(nodeIds)
     190       301794 :   return nodeIdSegments
     191              :     ? nodeExecutionIdFromString(nodeIdSegments.join(':'))
     192              :     : null
     193              : }
     194              : 
     195              : /**
     196              :  * Create a `NodeExecutionId` for a single, already-local node id, tolerating
     197              :  * a colon inside it.
     198              :  *
     199              :  * `createNodeExecutionId` treats every array element as one path SEGMENT and
     200              :  * rejects a colon inside any of them, because colon is the separator between
     201              :  * segments once they are joined. That is the right contract for a real
     202              :  * multi-segment path, but it is too strict for the single-id, no-ancestor
     203              :  * case some callers hit: a node materialized at the root graph can have a
     204              :  * raw id that itself contains colons for reasons that have nothing to do
     205              :  * with subgraph-path encoding (comfy-multi-player's `insert_workflow`
     206              :  * remapped ids, e.g. `insert:<opId>:root:node:<originalId>`, PM-1580).
     207              :  * There is no ancestor segment to disambiguate such an id from, so nothing
     208              :  * is lost by keeping it whole rather than rejecting it outright.
     209              :  */
     210        59717 : export function createLeafNodeExecutionId(
     211              :   nodeId: SerializedNodeId
     212              : ): NodeExecutionId | null {
     213        59717 :   const strict = createNodeExecutionId([nodeId])
     214        59717 :   if (strict) return strict
     215            8 :   const bare = parseNodeId(nodeId)
     216        59717 :   return bare ? (bare as unknown as NodeExecutionId) : null
     217              : }
     218              : 
     219        40996 : export function tryNormalizeNodeExecutionId(
     220              :   value: string | number
     221              : ): NodeExecutionId | null {
     222        40996 :   return nodeExecutionIdFromString(String(value))
     223              : }
     224              : 
     225              : export function appendNodeExecutionId(
     226              :   parentExecutionId: NodeExecutionId,
     227              :   childNodeId: NodeId
     228              : ): NodeExecutionId
     229              : export function appendNodeExecutionId(
     230              :   parentExecutionId: string,
     231              :   childNodeId: NodeId
     232              : ): NodeExecutionId | null
     233          181 : export function appendNodeExecutionId(
     234              :   parentExecutionId: string,
     235              :   childNodeId: NodeId
     236              : ): NodeExecutionId | null {
     237          181 :   const parentNodeIds = parseNodeExecutionId(parentExecutionId)
     238          181 :   if (!parentNodeIds) return null
     239              : 
     240          181 :   return createNodeExecutionId([...parentNodeIds, childNodeId])
     241              : }
     242              : 
     243              : /**
     244              :  * Returns all ancestor execution IDs for a given execution ID, including itself.
     245              :  *
     246              :  * Example: "65:70:63" → ["65", "65:70", "65:70:63"]
     247              :  */
     248        40087 : export function getAncestorExecutionIds(
     249              :   executionId: string
     250              : ): NodeExecutionId[] {
     251        40087 :   const nodeIds = parseNodeExecutionId(executionId)
     252        40087 :   if (!nodeIds) return []
     253              : 
     254        40087 :   return nodeIds
     255              :     .map((_, index) => createNodeExecutionId(nodeIds.slice(0, index + 1)))
     256              :     .filter((id): id is NodeExecutionId => id !== null)
     257              : }
     258              : 
     259              : /**
     260              :  * Returns all ancestor execution IDs for a given execution ID, excluding itself.
     261              :  *
     262              :  * Example: "65:70:63" → ["65", "65:70"]
     263              :  */
     264        37722 : export function getParentExecutionIds(executionId: string): NodeExecutionId[] {
     265        37722 :   return getAncestorExecutionIds(executionId).slice(0, -1)
     266              : }
     267              : 
     268              : /**
     269              :  * Compare two NodeExecutionIds for ascending numeric sort order.
     270              :  * Splits each ID by ":" and compares segments numerically left to right.
     271              :  *
     272              :  * Example order: "1" < "1:20" < "2" < "10:11:12"
     273              :  */
     274            0 : export function compareExecutionId(
     275              :   a: string | undefined,
     276              :   b: string | undefined
     277              : ): number {
     278            0 :   const parse = (id: string | undefined) => (id ?? '').split(':').map(Number)
     279            0 :   const idA = parse(a)
     280            0 :   const idB = parse(b)
     281            0 :   for (let i = 0; i < Math.max(idA.length, idB.length); i++) {
     282            0 :     const segA = idA[i] ?? 0
     283            0 :     const segB = idB[i] ?? 0
     284            0 :     const diff =
     285              :       (Number.isNaN(segA) ? 0 : segA) - (Number.isNaN(segB) ? 0 : segB)
     286            0 :     if (diff !== 0) return diff
     287              :   }
     288            0 :   return 0
     289              : }
        

Generated by: LCOV version 2.0-1