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 : }
|