figma-metadata-extractor 1.0.12 → 1.0.14

package/dist/__vite-browser-external-Dyvby5gX.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/__vite-browser-external-l0sNRNKZ.js

@@ -0,0 +1 @@
+

package/dist/index.cjs

@@ -265,6 +265,122 @@ function formatHeadersForCurl(headers) {
   }
   return headerArgs;
 }
+async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
+  const { pipeline } = await Promise.resolve().then(() => require("./__vite-browser-external-Dyvby5gX.cjs"));
+  const { Readable } = await Promise.resolve().then(() => require("./__vite-browser-external-Dyvby5gX.cjs"));
+  try {
+    const response = await fetch(imageUrl, {
+      method: "GET"
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to download image: ${response.status} ${response.statusText}`
+      );
+    }
+    if (!response.body) {
+      throw new Error("Response body is empty");
+    }
+    if (returnBuffer) {
+      const arrayBuffer = await response.arrayBuffer();
+      if (arrayBuffer.byteLength === 0) {
+        throw new Error("Downloaded image buffer is empty");
+      }
+      return arrayBuffer;
+    }
+    if (!fs.existsSync(localPath)) {
+      fs.mkdirSync(localPath, { recursive: true });
+    }
+    const fullPath = path.join(localPath, fileName);
+    const fileStream = fs.createWriteStream(fullPath);
+    await pipeline(Readable.fromWeb(response.body), fileStream);
+    const stats = fs.statSync(fullPath);
+    if (stats.size === 0) {
+      fs.unlinkSync(fullPath);
+      throw new Error("Downloaded file is empty (0 bytes)");
+    }
+    return fullPath;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Error downloading image: ${errorMessage}`);
+  }
+}
+function generateVarId(prefix = "var") {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  let result = "";
+  for (let i = 0; i < 6; i++) {
+    const randomIndex = Math.floor(Math.random() * chars.length);
+    result += chars[randomIndex];
+  }
+  return `${prefix}_${result}`;
+}
+function generateCSSShorthand(values, {
+  ignoreZero = true,
+  suffix = "px"
+} = {}) {
+  const { top, right, bottom, left } = values;
+  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
+    return void 0;
+  }
+  if (top === right && right === bottom && bottom === left) {
+    return `${top}${suffix}`;
+  }
+  if (right === left) {
+    if (top === bottom) {
+      return `${top}${suffix} ${right}${suffix}`;
+    }
+    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
+  }
+  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
+}
+function isVisible(element) {
+  return element.visible ?? true;
+}
+function pixelRound(num) {
+  if (isNaN(num)) {
+    throw new TypeError(`Input must be a valid number`);
+  }
+  return Number(Number(num).toFixed(2));
+}
+async function runWithConcurrency(tasks, limit) {
+  const results = new Array(tasks.length);
+  return new Promise((resolve, reject) => {
+    if (tasks.length === 0) {
+      resolve([]);
+      return;
+    }
+    let completed = 0;
+    let launched = 0;
+    let failed = false;
+    const next = () => {
+      if (failed) return;
+      if (completed === tasks.length) {
+        resolve(results);
+        return;
+      }
+      while (launched < tasks.length && launched - completed < limit) {
+        const index = launched++;
+        tasks[index]().then((result) => {
+          results[index] = result;
+          completed++;
+          next();
+        }).catch((err) => {
+          failed = true;
+          reject(err);
+        });
+      }
+    };
+    next();
+  });
+}
+const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  downloadFigmaImage,
+  generateCSSShorthand,
+  generateVarId,
+  isVisible,
+  pixelRound,
+  runWithConcurrency
+}, Symbol.toStringTag, { value: "Module" }));
 class FigmaService {
   apiKey;
   oauthToken;
@@ -372,6 +488,7 @@ class FigmaService {
   async downloadImages(fileKey, localPath, items, options = {}) {
     if (items.length === 0) return [];
     const { pngScale = 2, svgOptions, returnBuffer = false } = options;
+    const CONCURRENCY_LIMIT = 10;
     let resolvedPath = "";
     if (!returnBuffer) {
       const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
@@ -391,7 +508,7 @@ class FigmaService {
     );
     if (imageFills.length > 0) {
       const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillDownloads = imageFills.map(
+      const fillTasks = imageFills.map(
         ({
           imageRef,
           fileName,
@@ -406,7 +523,7 @@ class FigmaService {
             );
             return null;
           }
-          return downloadAndProcessImage(
+          return () => downloadAndProcessImage(
             fileName,
             resolvedPath,
             imageUrl,
@@ -417,10 +534,10 @@ class FigmaService {
           );
         }
       ).filter(
-        (promise) => promise !== null
+        (task) => task !== null
       );
-      if (fillDownloads.length > 0) {
-        downloadPromises.push(Promise.all(fillDownloads));
+      if (fillTasks.length > 0) {
+        downloadPromises.push(runWithConcurrency(fillTasks, CONCURRENCY_LIMIT));
       }
     }
     if (renderNodes.length > 0) {
@@ -437,7 +554,7 @@ class FigmaService {
           "png",
           { pngScale }
         );
-        const pngDownloads = pngNodes.map(
+        const pngTasks = pngNodes.map(
           ({
             nodeId,
             fileName,
@@ -452,7 +569,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -465,10 +582,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (pngDownloads.length > 0) {
-          downloadPromises.push(Promise.all(pngDownloads));
+        if (pngTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(pngTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
       if (svgNodes.length > 0) {
@@ -478,7 +597,7 @@ class FigmaService {
           "svg",
           { svgOptions }
         );
-        const svgDownloads = svgNodes.map(
+        const svgTasks = svgNodes.map(
           ({
             nodeId,
             fileName,
@@ -493,7 +612,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -506,10 +625,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (svgDownloads.length > 0) {
-          downloadPromises.push(Promise.all(svgDownloads));
+        if (svgTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(svgTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
     }
@@ -541,106 +662,6 @@ class FigmaService {
     return response;
   }
 }
-async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
-  try {
-    const response = await fetch(imageUrl, {
-      method: "GET"
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to download image: ${response.statusText}`);
-    }
-    if (returnBuffer) {
-      const arrayBuffer = await response.arrayBuffer();
-      return arrayBuffer;
-    }
-    if (!fs.existsSync(localPath)) {
-      fs.mkdirSync(localPath, { recursive: true });
-    }
-    const fullPath = path.join(localPath, fileName);
-    const reader = response.body?.getReader();
-    if (!reader) {
-      throw new Error("Failed to get response body");
-    }
-    const writer = fs.createWriteStream(fullPath);
-    return new Promise((resolve, reject) => {
-      const processStream = async () => {
-        try {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-              writer.end();
-              break;
-            }
-            writer.write(value);
-          }
-        } catch (err) {
-          writer.end();
-          fs.unlink(fullPath, () => {
-          });
-          reject(err);
-        }
-      };
-      writer.on("finish", () => {
-        resolve(fullPath);
-      });
-      writer.on("error", (err) => {
-        reader.cancel();
-        fs.unlink(fullPath, () => {
-        });
-        reject(new Error(`Failed to write image: ${err.message}`));
-      });
-      processStream();
-    });
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Error downloading image: ${errorMessage}`);
-  }
-}
-function generateVarId(prefix = "var") {
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
-  let result = "";
-  for (let i = 0; i < 6; i++) {
-    const randomIndex = Math.floor(Math.random() * chars.length);
-    result += chars[randomIndex];
-  }
-  return `${prefix}_${result}`;
-}
-function generateCSSShorthand(values, {
-  ignoreZero = true,
-  suffix = "px"
-} = {}) {
-  const { top, right, bottom, left } = values;
-  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
-    return void 0;
-  }
-  if (top === right && right === bottom && bottom === left) {
-    return `${top}${suffix}`;
-  }
-  if (right === left) {
-    if (top === bottom) {
-      return `${top}${suffix} ${right}${suffix}`;
-    }
-    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
-  }
-  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
-}
-function isVisible(element) {
-  return element.visible ?? true;
-}
-function pixelRound(num) {
-  if (isNaN(num)) {
-    throw new TypeError(`Input must be a valid number`);
-  }
-  return Number(Number(num).toFixed(2));
-}
-const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  downloadFigmaImage,
-  generateCSSShorthand,
-  generateVarId,
-  isVisible,
-  pixelRound
-}, Symbol.toStringTag, { value: "Module" }));
 function hasValue(key, obj, typeGuard) {
   const isObject = typeof obj === "object" && obj !== null;
   if (!isObject || !(key in obj)) return false;
@@ -1537,14 +1558,25 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     );
     let rawApiResponse;
     if (nodeId) {
-      rawApiResponse = await figmaService.getRawNode(fileKey, nodeId, depth || void 0);
+      rawApiResponse = await figmaService.getRawNode(
+        fileKey,
+        nodeId,
+        depth || void 0
+      );
     } else {
-      rawApiResponse = await figmaService.getRawFile(fileKey, depth || void 0);
+      rawApiResponse = await figmaService.getRawFile(
+        fileKey,
+        depth || void 0
+      );
     }
-    const simplifiedDesign = simplifyRawFigmaObject(rawApiResponse, allExtractors, {
-      maxDepth: depth || void 0,
-      afterChildren: collapseSvgContainers
-    });
+    const simplifiedDesign = simplifyRawFigmaObject(
+      rawApiResponse,
+      allExtractors,
+      {
+        maxDepth: depth || void 0,
+        afterChildren: collapseSvgContainers
+      }
+    );
     Logger.log(
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
@@ -1556,7 +1588,9 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     };
     if (downloadImages) {
       if (!returnBuffer && !localPath) {
-        throw new Error("localPath is required when downloadImages is true and returnBuffer is false");
+        throw new Error(
+          "localPath is required when downloadImages is true and returnBuffer is false"
+        );
       }
       Logger.log("Discovering and downloading image assets...");
       const imageAssets = findImageAssets(nodes, globalVars);
@@ -1577,10 +1611,20 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
         );
         if (returnBuffer) {
           result.images = downloadResults;
-          Logger.log(`Successfully downloaded ${downloadResults.length} images as buffers`);
+          Logger.log(
+            `Successfully downloaded ${downloadResults.length} images as buffers`
+          );
         } else {
-          result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths, localPath);
-          Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+          result.nodes = enrichNodesWithImages(
+            nodes,
+            imageAssets,
+            downloadResults,
+            useRelativePaths,
+            localPath
+          );
+          Logger.log(
+            `Successfully downloaded and enriched ${downloadResults.length} images`
+          );
         }
       }
     }
@@ -1598,7 +1642,15 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   }
 }
 async function downloadFigmaImages(figmaUrl, nodes, options) {
-  const { apiKey, oauthToken, useOAuth = false, pngScale = 2, localPath, enableLogging = false, returnBuffer = false } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    pngScale = 2,
+    localPath,
+    enableLogging = false,
+    returnBuffer = false
+  } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
@@ -1621,14 +1673,21 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
       ...node,
       nodeId: node.nodeId.replace(/-/g, ":")
     }));
-    const results = await figmaService.downloadImages(fileKey, localPath || "", processedNodes, {
-      pngScale,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      processedNodes,
+      {
+        pngScale,
+        returnBuffer
+      }
+    );
     return results;
   } catch (error) {
     Logger.error(`Error downloading images from ${fileKey}:`, error);
-    throw new Error(`Failed to download images: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download images: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 async function downloadFigmaFrameImage(figmaUrl, options) {
@@ -1648,7 +1707,9 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error("Either apiKey or oauthToken is required");
   }
   if (!returnBuffer && (!localPath || !fileName)) {
-    throw new Error("localPath and fileName are required when returnBuffer is false");
+    throw new Error(
+      "localPath and fileName are required when returnBuffer is false"
+    );
   }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
@@ -1657,13 +1718,17 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const fileKey = urlMatch[2];
   const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
   if (!nodeIdMatch) {
-    throw new Error("No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)");
+    throw new Error(
+      "No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)"
+    );
   }
   const nodeId = nodeIdMatch[1].replace(/-/g, ":");
   if (fileName) {
     const expectedExtension = `.${format}`;
     if (!fileName.toLowerCase().endsWith(expectedExtension)) {
-      throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+      throw new Error(
+        `Filename must end with ${expectedExtension} for ${format} format`
+      );
     }
   }
   const figmaService = new FigmaService({
@@ -1672,27 +1737,38 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     useOAuth: useOAuth && !!oauthToken
   });
   try {
-    Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
+    Logger.log(
+      `Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`
+    );
     const imageNode = {
       nodeId,
       fileName: fileName || `temp.${format}`
     };
-    const results = await figmaService.downloadImages(fileKey, localPath || "", [imageNode], {
-      pngScale: format === "png" ? pngScale : void 0,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      [imageNode],
+      {
+        pngScale: format === "png" ? pngScale : void 0,
+        returnBuffer
+      }
+    );
     if (results.length === 0) {
       throw new Error(`Failed to download image for frame ${nodeId}`);
     }
     if (returnBuffer) {
       Logger.log(`Successfully downloaded frame image as buffer`);
     } else {
-      Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+      Logger.log(
+        `Successfully downloaded frame image to: ${results[0].filePath}`
+      );
     }
     return results[0];
   } catch (error) {
     Logger.error(`Error downloading frame image from ${fileKey}:`, error);
-    throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 function getImageNodeInfo(metadata) {
@@ -1714,7 +1790,9 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
   let downloadResults;
   if (Array.isArray(imagePaths)) {
     if (imagePaths.length !== metadata.images.length) {
-      throw new Error(`Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`);
+      throw new Error(
+        `Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`
+      );
     }
     downloadResults = imagePaths.map((filePath, index) => ({
       filePath,
@@ -1726,16 +1804,23 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
     downloadResults = imageAssets.map((asset) => {
       const filePath = imagePaths[asset.id];
       if (!filePath) {
-        throw new Error(`No image path provided for node ID: ${asset.id}`);
+        return null;
       }
-      const imageMetadata = metadata.images.find((img) => img.nodeId === asset.id);
+      const imageMetadata = metadata.images.find(
+        (img) => img.nodeId === asset.id
+      );
       return {
         filePath,
-        finalDimensions: imageMetadata?.finalDimensions || { width: 0, height: 0 },
+        finalDimensions: imageMetadata?.finalDimensions || {
+          width: 0,
+          height: 0
+        },
         wasCropped: imageMetadata?.wasCropped || false,
         cssVariables: imageMetadata?.cssVariables
       };
-    });
+    }).filter(
+      (result) => result !== null
+    );
   }
   const enrichedNodes = enrichNodesWithImages(
     metadata.nodes,

package/dist/index.js

@@ -263,6 +263,122 @@ function formatHeadersForCurl(headers) {
   }
   return headerArgs;
 }
+async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
+  const { pipeline } = await import("./__vite-browser-external-l0sNRNKZ.js");
+  const { Readable } = await import("./__vite-browser-external-l0sNRNKZ.js");
+  try {
+    const response = await fetch(imageUrl, {
+      method: "GET"
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to download image: ${response.status} ${response.statusText}`
+      );
+    }
+    if (!response.body) {
+      throw new Error("Response body is empty");
+    }
+    if (returnBuffer) {
+      const arrayBuffer = await response.arrayBuffer();
+      if (arrayBuffer.byteLength === 0) {
+        throw new Error("Downloaded image buffer is empty");
+      }
+      return arrayBuffer;
+    }
+    if (!fs.existsSync(localPath)) {
+      fs.mkdirSync(localPath, { recursive: true });
+    }
+    const fullPath = path.join(localPath, fileName);
+    const fileStream = fs.createWriteStream(fullPath);
+    await pipeline(Readable.fromWeb(response.body), fileStream);
+    const stats = fs.statSync(fullPath);
+    if (stats.size === 0) {
+      fs.unlinkSync(fullPath);
+      throw new Error("Downloaded file is empty (0 bytes)");
+    }
+    return fullPath;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Error downloading image: ${errorMessage}`);
+  }
+}
+function generateVarId(prefix = "var") {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  let result = "";
+  for (let i = 0; i < 6; i++) {
+    const randomIndex = Math.floor(Math.random() * chars.length);
+    result += chars[randomIndex];
+  }
+  return `${prefix}_${result}`;
+}
+function generateCSSShorthand(values, {
+  ignoreZero = true,
+  suffix = "px"
+} = {}) {
+  const { top, right, bottom, left } = values;
+  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
+    return void 0;
+  }
+  if (top === right && right === bottom && bottom === left) {
+    return `${top}${suffix}`;
+  }
+  if (right === left) {
+    if (top === bottom) {
+      return `${top}${suffix} ${right}${suffix}`;
+    }
+    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
+  }
+  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
+}
+function isVisible(element) {
+  return element.visible ?? true;
+}
+function pixelRound(num) {
+  if (isNaN(num)) {
+    throw new TypeError(`Input must be a valid number`);
+  }
+  return Number(Number(num).toFixed(2));
+}
+async function runWithConcurrency(tasks, limit) {
+  const results = new Array(tasks.length);
+  return new Promise((resolve, reject) => {
+    if (tasks.length === 0) {
+      resolve([]);
+      return;
+    }
+    let completed = 0;
+    let launched = 0;
+    let failed = false;
+    const next = () => {
+      if (failed) return;
+      if (completed === tasks.length) {
+        resolve(results);
+        return;
+      }
+      while (launched < tasks.length && launched - completed < limit) {
+        const index = launched++;
+        tasks[index]().then((result) => {
+          results[index] = result;
+          completed++;
+          next();
+        }).catch((err) => {
+          failed = true;
+          reject(err);
+        });
+      }
+    };
+    next();
+  });
+}
+const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  downloadFigmaImage,
+  generateCSSShorthand,
+  generateVarId,
+  isVisible,
+  pixelRound,
+  runWithConcurrency
+}, Symbol.toStringTag, { value: "Module" }));
 class FigmaService {
   apiKey;
   oauthToken;
@@ -370,6 +486,7 @@ class FigmaService {
   async downloadImages(fileKey, localPath, items, options = {}) {
     if (items.length === 0) return [];
     const { pngScale = 2, svgOptions, returnBuffer = false } = options;
+    const CONCURRENCY_LIMIT = 10;
     let resolvedPath = "";
     if (!returnBuffer) {
       const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
@@ -389,7 +506,7 @@ class FigmaService {
     );
     if (imageFills.length > 0) {
       const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillDownloads = imageFills.map(
+      const fillTasks = imageFills.map(
         ({
           imageRef,
           fileName,
@@ -404,7 +521,7 @@ class FigmaService {
             );
             return null;
           }
-          return downloadAndProcessImage(
+          return () => downloadAndProcessImage(
             fileName,
             resolvedPath,
             imageUrl,
@@ -415,10 +532,10 @@ class FigmaService {
           );
         }
       ).filter(
-        (promise) => promise !== null
+        (task) => task !== null
       );
-      if (fillDownloads.length > 0) {
-        downloadPromises.push(Promise.all(fillDownloads));
+      if (fillTasks.length > 0) {
+        downloadPromises.push(runWithConcurrency(fillTasks, CONCURRENCY_LIMIT));
       }
     }
     if (renderNodes.length > 0) {
@@ -435,7 +552,7 @@ class FigmaService {
           "png",
           { pngScale }
         );
-        const pngDownloads = pngNodes.map(
+        const pngTasks = pngNodes.map(
           ({
             nodeId,
             fileName,
@@ -450,7 +567,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -463,10 +580,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (pngDownloads.length > 0) {
-          downloadPromises.push(Promise.all(pngDownloads));
+        if (pngTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(pngTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
       if (svgNodes.length > 0) {
@@ -476,7 +595,7 @@ class FigmaService {
           "svg",
           { svgOptions }
         );
-        const svgDownloads = svgNodes.map(
+        const svgTasks = svgNodes.map(
           ({
             nodeId,
             fileName,
@@ -491,7 +610,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -504,10 +623,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (svgDownloads.length > 0) {
-          downloadPromises.push(Promise.all(svgDownloads));
+        if (svgTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(svgTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
     }
@@ -539,106 +660,6 @@ class FigmaService {
     return response;
   }
 }
-async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
-  try {
-    const response = await fetch(imageUrl, {
-      method: "GET"
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to download image: ${response.statusText}`);
-    }
-    if (returnBuffer) {
-      const arrayBuffer = await response.arrayBuffer();
-      return arrayBuffer;
-    }
-    if (!fs.existsSync(localPath)) {
-      fs.mkdirSync(localPath, { recursive: true });
-    }
-    const fullPath = path.join(localPath, fileName);
-    const reader = response.body?.getReader();
-    if (!reader) {
-      throw new Error("Failed to get response body");
-    }
-    const writer = fs.createWriteStream(fullPath);
-    return new Promise((resolve, reject) => {
-      const processStream = async () => {
-        try {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-              writer.end();
-              break;
-            }
-            writer.write(value);
-          }
-        } catch (err) {
-          writer.end();
-          fs.unlink(fullPath, () => {
-          });
-          reject(err);
-        }
-      };
-      writer.on("finish", () => {
-        resolve(fullPath);
-      });
-      writer.on("error", (err) => {
-        reader.cancel();
-        fs.unlink(fullPath, () => {
-        });
-        reject(new Error(`Failed to write image: ${err.message}`));
-      });
-      processStream();
-    });
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Error downloading image: ${errorMessage}`);
-  }
-}
-function generateVarId(prefix = "var") {
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
-  let result = "";
-  for (let i = 0; i < 6; i++) {
-    const randomIndex = Math.floor(Math.random() * chars.length);
-    result += chars[randomIndex];
-  }
-  return `${prefix}_${result}`;
-}
-function generateCSSShorthand(values, {
-  ignoreZero = true,
-  suffix = "px"
-} = {}) {
-  const { top, right, bottom, left } = values;
-  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
-    return void 0;
-  }
-  if (top === right && right === bottom && bottom === left) {
-    return `${top}${suffix}`;
-  }
-  if (right === left) {
-    if (top === bottom) {
-      return `${top}${suffix} ${right}${suffix}`;
-    }
-    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
-  }
-  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
-}
-function isVisible(element) {
-  return element.visible ?? true;
-}
-function pixelRound(num) {
-  if (isNaN(num)) {
-    throw new TypeError(`Input must be a valid number`);
-  }
-  return Number(Number(num).toFixed(2));
-}
-const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  downloadFigmaImage,
-  generateCSSShorthand,
-  generateVarId,
-  isVisible,
-  pixelRound
-}, Symbol.toStringTag, { value: "Module" }));
 function hasValue(key, obj, typeGuard) {
   const isObject = typeof obj === "object" && obj !== null;
   if (!isObject || !(key in obj)) return false;
@@ -1535,14 +1556,25 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     );
     let rawApiResponse;
     if (nodeId) {
-      rawApiResponse = await figmaService.getRawNode(fileKey, nodeId, depth || void 0);
+      rawApiResponse = await figmaService.getRawNode(
+        fileKey,
+        nodeId,
+        depth || void 0
+      );
     } else {
-      rawApiResponse = await figmaService.getRawFile(fileKey, depth || void 0);
+      rawApiResponse = await figmaService.getRawFile(
+        fileKey,
+        depth || void 0
+      );
     }
-    const simplifiedDesign = simplifyRawFigmaObject(rawApiResponse, allExtractors, {
-      maxDepth: depth || void 0,
-      afterChildren: collapseSvgContainers
-    });
+    const simplifiedDesign = simplifyRawFigmaObject(
+      rawApiResponse,
+      allExtractors,
+      {
+        maxDepth: depth || void 0,
+        afterChildren: collapseSvgContainers
+      }
+    );
     Logger.log(
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
@@ -1554,7 +1586,9 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     };
     if (downloadImages) {
       if (!returnBuffer && !localPath) {
-        throw new Error("localPath is required when downloadImages is true and returnBuffer is false");
+        throw new Error(
+          "localPath is required when downloadImages is true and returnBuffer is false"
+        );
       }
       Logger.log("Discovering and downloading image assets...");
       const imageAssets = findImageAssets(nodes, globalVars);
@@ -1575,10 +1609,20 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
         );
         if (returnBuffer) {
           result.images = downloadResults;
-          Logger.log(`Successfully downloaded ${downloadResults.length} images as buffers`);
+          Logger.log(
+            `Successfully downloaded ${downloadResults.length} images as buffers`
+          );
         } else {
-          result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths, localPath);
-          Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+          result.nodes = enrichNodesWithImages(
+            nodes,
+            imageAssets,
+            downloadResults,
+            useRelativePaths,
+            localPath
+          );
+          Logger.log(
+            `Successfully downloaded and enriched ${downloadResults.length} images`
+          );
         }
       }
     }
@@ -1596,7 +1640,15 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   }
 }
 async function downloadFigmaImages(figmaUrl, nodes, options) {
-  const { apiKey, oauthToken, useOAuth = false, pngScale = 2, localPath, enableLogging = false, returnBuffer = false } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    pngScale = 2,
+    localPath,
+    enableLogging = false,
+    returnBuffer = false
+  } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
@@ -1619,14 +1671,21 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
       ...node,
       nodeId: node.nodeId.replace(/-/g, ":")
     }));
-    const results = await figmaService.downloadImages(fileKey, localPath || "", processedNodes, {
-      pngScale,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      processedNodes,
+      {
+        pngScale,
+        returnBuffer
+      }
+    );
     return results;
   } catch (error) {
     Logger.error(`Error downloading images from ${fileKey}:`, error);
-    throw new Error(`Failed to download images: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download images: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 async function downloadFigmaFrameImage(figmaUrl, options) {
@@ -1646,7 +1705,9 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error("Either apiKey or oauthToken is required");
   }
   if (!returnBuffer && (!localPath || !fileName)) {
-    throw new Error("localPath and fileName are required when returnBuffer is false");
+    throw new Error(
+      "localPath and fileName are required when returnBuffer is false"
+    );
   }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
@@ -1655,13 +1716,17 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const fileKey = urlMatch[2];
   const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
   if (!nodeIdMatch) {
-    throw new Error("No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)");
+    throw new Error(
+      "No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)"
+    );
   }
   const nodeId = nodeIdMatch[1].replace(/-/g, ":");
   if (fileName) {
     const expectedExtension = `.${format}`;
     if (!fileName.toLowerCase().endsWith(expectedExtension)) {
-      throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+      throw new Error(
+        `Filename must end with ${expectedExtension} for ${format} format`
+      );
     }
   }
   const figmaService = new FigmaService({
@@ -1670,27 +1735,38 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     useOAuth: useOAuth && !!oauthToken
   });
   try {
-    Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
+    Logger.log(
+      `Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`
+    );
     const imageNode = {
       nodeId,
       fileName: fileName || `temp.${format}`
     };
-    const results = await figmaService.downloadImages(fileKey, localPath || "", [imageNode], {
-      pngScale: format === "png" ? pngScale : void 0,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      [imageNode],
+      {
+        pngScale: format === "png" ? pngScale : void 0,
+        returnBuffer
+      }
+    );
     if (results.length === 0) {
       throw new Error(`Failed to download image for frame ${nodeId}`);
     }
     if (returnBuffer) {
       Logger.log(`Successfully downloaded frame image as buffer`);
     } else {
-      Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+      Logger.log(
+        `Successfully downloaded frame image to: ${results[0].filePath}`
+      );
     }
     return results[0];
   } catch (error) {
     Logger.error(`Error downloading frame image from ${fileKey}:`, error);
-    throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 function getImageNodeInfo(metadata) {
@@ -1712,7 +1788,9 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
   let downloadResults;
   if (Array.isArray(imagePaths)) {
     if (imagePaths.length !== metadata.images.length) {
-      throw new Error(`Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`);
+      throw new Error(
+        `Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`
+      );
     }
     downloadResults = imagePaths.map((filePath, index) => ({
       filePath,
@@ -1724,16 +1802,23 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
     downloadResults = imageAssets.map((asset) => {
       const filePath = imagePaths[asset.id];
       if (!filePath) {
-        throw new Error(`No image path provided for node ID: ${asset.id}`);
+        return null;
       }
-      const imageMetadata = metadata.images.find((img) => img.nodeId === asset.id);
+      const imageMetadata = metadata.images.find(
+        (img) => img.nodeId === asset.id
+      );
       return {
         filePath,
-        finalDimensions: imageMetadata?.finalDimensions || { width: 0, height: 0 },
+        finalDimensions: imageMetadata?.finalDimensions || {
+          width: 0,
+          height: 0
+        },
         wasCropped: imageMetadata?.wasCropped || false,
         cssVariables: imageMetadata?.cssVariables
       };
-    });
+    }).filter(
+      (result) => result !== null
+    );
   }
   const enrichedNodes = enrichNodesWithImages(
     metadata.nodes,

package/dist/lib.d.ts

@@ -14,7 +14,7 @@ export interface FigmaMetadataOptions {
     /** Local path for downloaded images (required if downloadImages is true) */
     localPath?: string;
     /** Image format for downloads (defaults to 'png') */
-    imageFormat?: 'png' | 'svg';
+    imageFormat?: "png" | "svg";
     /** Export scale for PNG images (defaults to 2) */
     pngScale?: number;
     /**
@@ -85,7 +85,7 @@ export interface FigmaFrameImageOptions {
     /** The filename for the downloaded image (must end with .png or .svg, optional if returnBuffer is true) */
     fileName?: string;
     /** Image format to download (defaults to 'png') */
-    format?: 'png' | 'svg';
+    format?: "png" | "svg";
     /** Enable JSON debug log files (defaults to false) */
     enableLogging?: boolean;
     /** Return image as ArrayBuffer instead of saving to disk (defaults to false) */
@@ -99,10 +99,10 @@ export interface FigmaFrameImageOptions {
  * @returns Promise resolving to the extracted metadata
  */
 export declare function getFigmaMetadata(figmaUrl: string, options: FigmaMetadataOptions & {
-    outputFormat: 'json';
+    outputFormat: "json";
 }): Promise<string>;
 export declare function getFigmaMetadata(figmaUrl: string, options: FigmaMetadataOptions & {
-    outputFormat: 'yaml';
+    outputFormat: "yaml";
 }): Promise<string>;
 export declare function getFigmaMetadata(figmaUrl: string, options?: FigmaMetadataOptions): Promise<FigmaMetadataResult>;
 /**
@@ -155,6 +155,7 @@ export declare function getImageNodeInfo(metadata: FigmaMetadataResult): Array<{
  * Enrich metadata with saved image file paths
  *
  * Use this function after saving images from buffers to disk to add file path information to the metadata.
+ * When using the object format, missing image paths for node IDs are skipped rather than throwing errors.
  *
  * @param metadata - The metadata result from getFigmaMetadata
  * @param imagePaths - Array of file paths (ordered) OR object mapping node IDs to paths/URLs
@@ -167,6 +168,7 @@ export declare function getImageNodeInfo(metadata: FigmaMetadataResult): Array<{
  * const enriched = enrichMetadataWithImages(metadata, ['/path/to/img1.png', '/path/to/img2.png']);
  *
  * // Object format (keyed by node ID) - useful after uploading to CDN
+ * // Missing node IDs are automatically skipped
  * const enriched = enrichMetadataWithImages(metadata, {
  *   '123:456': 'https://cdn.example.com/icon.png',
  *   '789:012': 'https://cdn.example.com/logo.png'

package/dist/utils/common.d.ts

@@ -68,3 +68,10 @@ export declare function isVisible(element: {
  * @throws TypeError If the input is not a valid number
  */
 export declare function pixelRound(num: number): number;
+/**
+ * Run a list of async tasks with a concurrency limit
+ * @param tasks - Array of functions that return a Promise
+ * @param limit - Maximum number of concurrent tasks
+ * @returns Promise resolving to array of results
+ */
+export declare function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, limit: number): Promise<T[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-metadata-extractor",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Extract metadata and download images from Figma files. A standalone library for accessing Figma design data and downloading frame images programmatically.",
   "type": "module",
   "main": "dist/index.cjs",