{"record":{"id":"4311874061ddc3bb","repo":"heygen-com/hyperframes","slug":"parsefigmaref-empty-input","errorCode":null,"errorMessage":"parseFigmaRef: empty input","messagePattern":"parseFigmaRef: empty input","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/figma/parseFigmaRef.ts","lineNumber":11,"sourceCode":"import type { FigmaRef } from \"./types\";\n\nconst FILE_KEY_RE = /\\/(?:design|file|proto)\\/([A-Za-z0-9]+)/;\n\nfunction normalizeNodeId(raw: string): string {\n  return raw.replaceAll(\"-\", \":\");\n}\n\nexport function parseFigmaRef(input: string): FigmaRef {\n  const trimmed = input.trim();\n  if (trimmed.length === 0) throw new Error(\"parseFigmaRef: empty input\");\n\n  if (!trimmed.includes(\"/\")) {\n    const colon = trimmed.indexOf(\":\");\n    if (colon === -1) return { fileKey: trimmed };\n    const fileKey = trimmed.slice(0, colon);\n    const node = trimmed.slice(colon + 1);\n    if (fileKey.length === 0) throw new Error(`parseFigmaRef: invalid ref \"${input}\"`);\n    return node.length > 0 ? { fileKey, nodeId: normalizeNodeId(node) } : { fileKey };\n  }\n\n  const keyMatch = trimmed.match(FILE_KEY_RE);\n  const fileKey = keyMatch?.[1];\n  if (fileKey === undefined) throw new Error(`parseFigmaRef: no fileKey in \"${input}\"`);\n\n  const q = trimmed.indexOf(\"?\");\n  if (q !== -1) {\n    const raw = new URLSearchParams(trimmed.slice(q + 1)).get(\"node-id\");\n    if (raw !== null && raw.length > 0) return { fileKey, nodeId: normalizeNodeId(raw) };","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/core/src/figma/parseFigmaRef.ts#L1-L29","documentation":"Thrown by parseFigmaRef when input.trim() is the empty string — the ref contained no usable characters. parseFigmaRef is the entry point that turns a pasted figma URL or a bare 'fileKey:nodeId' token into a FigmaRef, and an empty input yields neither fileKey nor nodeId, so it fails immediately rather than producing an empty-keyed ref that would cause a confusing downstream 404.","triggerScenarios":"Calling parseFigmaRef(''); calling parseFigmaRef('   ') (whitespace only); a CLI arg that was not supplied and defaulted to empty; reading a ref from a config field that was left blank.","commonSituations":"User pressed enter without pasting a URL; a script reads process.argv[2] which is undefined and gets coerced to ''; an empty .env variable feeding the ref; a UI input field that was never filled.","solutions":["Supply a non-empty figma URL or 'fileKey:nodeId' string.","If reading from argv/env, default-check before calling: if (!input) throw a clearer caller-side error.","Trim user input in the UI layer and reject empty submissions before they reach parseFigmaRef."],"exampleFix":"// before — argv missing, coerced to empty\nconst ref = parseFigmaRef(process.argv[2] ?? '');\n\n// after — guard at the caller with a helpful message\nconst raw = process.argv[2];\nif (!raw?.trim()) throw new Error('usage: import <figma-url-or-ref>');\nconst ref = parseFigmaRef(raw);","handlingStrategy":"validation","validationCode":"export function parseFigmaRefSafe(input: unknown) {\n  if (typeof input !== 'string' || input.trim().length === 0) {\n    throw new Error('a figma URL or fileKey is required');\n  }\n  return parseFigmaRef(input);\n}","typeGuard":"export function isNonEmptyRefInput(input: unknown): input is string {\n  return typeof input === 'string' && input.trim().length > 0;\n}","tryCatchPattern":null,"preventionTips":["Validate CLI args/env at the edge, before parseFigmaRef, with a user-friendly message.","Trim and reject empty inputs in the UI layer.","Default optional inputs to undefined and assert presence, never to ''."],"tags":["figma","parsing","validation","input"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}