convert-buddy-js 0.9.4 → 0.9.6

package/dist/src/browser.js

@@ -0,0 +1,204 @@
+import { ConvertBuddy, autoDetectConfig, getFileTypeConfig, convertAny as convertAnyCore, convertAnyToString as convertAnyToStringCore } from "./index.js";
+export * from "./index.js";
+async function convert(input, opts) {
+  return convertAnyCore(input, opts);
+}
+async function convertToString(input, opts) {
+  return convertAnyToStringCore(input, opts);
+}
+async function convertFileToString(file, opts = {}) {
+  const bytes = await convertFile(file, opts);
+  return new TextDecoder().decode(bytes);
+}
+async function convertFile(file, opts = {}) {
+  let actualOpts = { ...opts };
+  if (opts.inputFormat === "auto") {
+    const sampleSize = 256 * 1024;
+    const sampleBlob = file.slice(0, sampleSize);
+    const sampleBuffer = await sampleBlob.arrayBuffer();
+    const sample = new Uint8Array(sampleBuffer);
+    const detected = await autoDetectConfig(sample, { debug: opts.debug });
+    if (detected.format !== "unknown") {
+      actualOpts.inputFormat = detected.format;
+      if (detected.csvConfig) {
+        actualOpts.csvConfig = opts.csvConfig ? { ...detected.csvConfig, ...opts.csvConfig } : detected.csvConfig;
+      }
+      if (detected.xmlConfig) {
+        actualOpts.xmlConfig = opts.xmlConfig ? { ...detected.xmlConfig, ...opts.xmlConfig } : detected.xmlConfig;
+      }
+      if (opts.debug) {
+        console.log("[convert-buddy] Auto-detected format:", detected.format);
+      }
+    } else {
+      throw new Error("Could not auto-detect input format. Please specify inputFormat explicitly.");
+    }
+  }
+  if (!actualOpts.chunkTargetBytes) {
+    const fileSize = file.size;
+    actualOpts.chunkTargetBytes = Math.max(
+      512 * 1024,
+      // minimum: 512KB
+      Math.min(
+        1 * 1024 * 1024,
+        // maximum: 1MB (conservative for memory)
+        Math.floor(fileSize / 16)
+        // 1/16 of file size
+      )
+    );
+    if (opts.debug) {
+      console.log(`[convert-buddy] Adaptive chunk sizing: ${fileSize} bytes \u2192 ${actualOpts.chunkTargetBytes} byte chunks`);
+    }
+  }
+  const buddy = await ConvertBuddy.create(actualOpts);
+  const stream = file.stream();
+  const reader = stream.getReader();
+  const chunks = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (buddy.isAborted()) {
+        throw new Error("Conversion aborted");
+      }
+      const output = buddy.push(value);
+      if (output.length > 0) {
+        chunks.push(output);
+      }
+    }
+    const final = buddy.finish();
+    if (final.length > 0) {
+      chunks.push(final);
+    }
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    if (opts.profile) {
+      console.log("[convert-buddy] Performance Stats:", buddy.stats());
+    }
+    return result;
+  } catch (error) {
+    reader.releaseLock();
+    throw error;
+  }
+}
+async function convertFileToFile(inputFile, outputFilename, opts = {}) {
+  const result = await convertFile(inputFile, opts);
+  const blob = new Blob([new Uint8Array(result)], { type: "application/octet-stream" });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = outputFilename;
+  link.style.display = "none";
+  document.body.appendChild(link);
+  link.click();
+  setTimeout(() => {
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+  }, 100);
+}
+async function convertFileStream(file, opts = {}) {
+  let actualOpts = { ...opts };
+  if (opts.inputFormat === "auto") {
+    const sampleSize = 256 * 1024;
+    const sampleBlob = file.slice(0, sampleSize);
+    const sampleBuffer = await sampleBlob.arrayBuffer();
+    const sample = new Uint8Array(sampleBuffer);
+    const detected = await autoDetectConfig(sample, { debug: opts.debug });
+    if (detected.format !== "unknown") {
+      actualOpts.inputFormat = detected.format;
+      if (detected.csvConfig) {
+        actualOpts.csvConfig = opts.csvConfig ? { ...detected.csvConfig, ...opts.csvConfig } : detected.csvConfig;
+      }
+      if (detected.xmlConfig) {
+        actualOpts.xmlConfig = opts.xmlConfig ? { ...detected.xmlConfig, ...opts.xmlConfig } : detected.xmlConfig;
+      }
+    } else {
+      throw new Error("Could not auto-detect input format.");
+    }
+  }
+  const buddy = await ConvertBuddy.create(actualOpts);
+  const inputStream = file.stream();
+  return new ReadableStream({
+    async start(controller) {
+      const reader = inputStream.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) {
+            const final = buddy.finish();
+            if (final.length > 0) {
+              controller.enqueue(final);
+            }
+            controller.close();
+            break;
+          }
+          if (buddy.isAborted()) {
+            controller.error(new Error("Conversion aborted"));
+            break;
+          }
+          const output = buddy.push(value);
+          if (output.length > 0) {
+            controller.enqueue(output);
+          }
+        }
+      } catch (error) {
+        controller.error(error);
+      } finally {
+        reader.releaseLock();
+      }
+    }
+  });
+}
+async function autoConvertStream(file, opts) {
+  return convertFileStream(file, {
+    ...opts,
+    inputFormat: "auto"
+  });
+}
+async function convertStreamToWritable(file, writable, opts = {}) {
+  const outputStream = await convertFileStream(file, opts);
+  await outputStream.pipeTo(writable);
+}
+function isFileSystemAccessSupported() {
+  return typeof window !== "undefined" && "showSaveFilePicker" in window && "showOpenFilePicker" in window;
+}
+async function convertAndSave(file, opts = {}) {
+  if (!isFileSystemAccessSupported()) {
+    const filename = opts.suggestedName || "converted";
+    await convertFileToFile(file, filename, opts);
+    return;
+  }
+  const outputFormat = opts.outputFormat || "json";
+  const suggestedName = opts.suggestedName || `converted.${outputFormat}`;
+  const types = getFileTypeConfig(outputFormat);
+  try {
+    const fileHandle = await window.showSaveFilePicker({
+      suggestedName,
+      types
+    });
+    const writable = await fileHandle.createWritable();
+    await convertStreamToWritable(file, writable, opts);
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      return;
+    }
+    throw error;
+  }
+}
+export {
+  autoConvertStream,
+  convert,
+  convertAndSave,
+  convertFile,
+  convertFileStream,
+  convertFileToFile,
+  convertFileToString,
+  convertStreamToWritable,
+  convertToString,
+  isFileSystemAccessSupported
+};
+//# sourceMappingURL=browser.js.map

package/dist/src/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/browser.ts"],"sourcesContent":["import { ConvertBuddy, type ConvertBuddyOptions, type ConvertOptions, type Format, autoDetectConfig, detectFormat, getMimeType, getFileTypeConfig, convertAny as convertAnyCore, convertAnyToString as convertAnyToStringCore } from \"./index.js\";\r\n\r\nexport * from \"./index.js\";\r\n\r\nexport type BrowserConvertOptions = ConvertBuddyOptions & {\r\n  // Additional browser-specific options can go here\r\n};\r\n\r\n/**\r\n * Ultra-simple convert function for browser.\r\n * Auto-detects input type (File, URL, string, etc.) and format.\r\n * \r\n * @example\r\n * // From File\r\n * const file = fileInput.files[0];\r\n * const result = await convert(file, { outputFormat: \"json\" });\r\n * \r\n * @example\r\n * // From URL\r\n * const result = await convert(\"https://example.com/data.csv\", { outputFormat: \"json\" });\r\n * \r\n * @example\r\n * // From string\r\n * const result = await convert(csvString, { outputFormat: \"json\" });\r\n */\r\nexport async function convert(\r\n  input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>,\r\n  opts: ConvertOptions\r\n): Promise<Uint8Array> {\r\n  return convertAnyCore(input, opts);\r\n}\r\n\r\n/**\r\n * Ultra-simple convert function that returns a string.\r\n * \r\n * @example\r\n * const json = await convertToString(file, { outputFormat: \"json\" });\r\n * console.log(JSON.parse(json));\r\n */\r\nexport async function convertToString(\r\n  input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>,\r\n  opts: ConvertOptions\r\n): Promise<string> {\r\n  return convertAnyToStringCore(input, opts);\r\n}\r\n\r\n/**\r\n * Convert a browser File or Blob object to a string.\r\n * Handles streaming internally using FileReader and web streams.\r\n * \r\n * @example\r\n * // From file input\r\n * const fileInput = document.querySelector('input[type=\"file\"]');\r\n * const file = fileInput.files[0];\r\n * const result = await convertFileToString(file, {\r\n *   inputFormat: \"csv\",\r\n *   outputFormat: \"json\"\r\n * });\r\n * \r\n * @example\r\n * // With auto-detection\r\n * const result = await convertFileToString(file, {\r\n *   inputFormat: \"auto\",\r\n *   outputFormat: \"ndjson\"\r\n * });\r\n */\r\nexport async function convertFileToString(\r\n  file: File | Blob,\r\n  opts: BrowserConvertOptions = {}\r\n): Promise<string> {\r\n  const bytes = await convertFile(file, opts);\r\n  return new TextDecoder().decode(bytes);\r\n}\r\n\r\n/**\r\n * Convert a browser File or Blob object to a Uint8Array.\r\n * Handles streaming internally using FileReader and web streams.\r\n * \r\n * @example\r\n * const file = fileInput.files[0];\r\n * const result = await convertFile(file, {\r\n *   inputFormat: \"csv\",\r\n *   outputFormat: \"json\",\r\n *   onProgress: (stats) => {\r\n *     console.log(`Progress: ${stats.bytesIn} bytes processed`);\r\n *   }\r\n * });\r\n */\r\nexport async function convertFile(\r\n  file: File | Blob,\r\n  opts: BrowserConvertOptions = {}\r\n): Promise<Uint8Array> {\r\n  // Handle auto-detection\r\n  let actualOpts = { ...opts };\r\n  \r\n  if (opts.inputFormat === \"auto\") {\r\n    // Read a sample for auto-detection\r\n    const sampleSize = 256 * 1024; // 256KB\r\n    const sampleBlob = file.slice(0, sampleSize);\r\n    const sampleBuffer = await sampleBlob.arrayBuffer();\r\n    const sample = new Uint8Array(sampleBuffer as ArrayBuffer);\r\n    \r\n    const detected = await autoDetectConfig(sample, { debug: opts.debug });\r\n    \r\n    if (detected.format !== \"unknown\") {\r\n      actualOpts.inputFormat = detected.format as Format;\r\n      \r\n      if (detected.csvConfig) {\r\n        actualOpts.csvConfig = opts.csvConfig ? { ...detected.csvConfig, ...opts.csvConfig } : detected.csvConfig;\r\n      }\r\n      \r\n      if (detected.xmlConfig) {\r\n        actualOpts.xmlConfig = opts.xmlConfig ? { ...detected.xmlConfig, ...opts.xmlConfig } : detected.xmlConfig;\r\n      }\r\n      \r\n      if (opts.debug) {\r\n        console.log(\"[convert-buddy] Auto-detected format:\", detected.format);\r\n      }\r\n    } else {\r\n      throw new Error(\"Could not auto-detect input format. Please specify inputFormat explicitly.\");\r\n    }\r\n  }\r\n  \r\n  // Adaptive chunk sizing based on file size\r\n  // Tuned to balance WASM boundary crossing reduction with memory efficiency\r\n  if (!actualOpts.chunkTargetBytes) {\r\n    const fileSize = file.size;\r\n    actualOpts.chunkTargetBytes = Math.max(\r\n      512 * 1024,      // minimum: 512KB\r\n      Math.min(\r\n        1 * 1024 * 1024,   // maximum: 1MB (conservative for memory)\r\n        Math.floor(fileSize / 16)  // 1/16 of file size\r\n      )\r\n    );\r\n    if (opts.debug) {\r\n      console.log(`[convert-buddy] Adaptive chunk sizing: ${fileSize} bytes → ${actualOpts.chunkTargetBytes} byte chunks`);\r\n    }\r\n  }\r\n  \r\n  const buddy = await ConvertBuddy.create(actualOpts);\r\n  \r\n  // Use streams API for efficient processing\r\n  const stream = file.stream();\r\n  const reader = stream.getReader();\r\n  \r\n  const chunks: Uint8Array[] = [];\r\n  \r\n  try {\r\n    while (true) {\r\n      const { done, value } = await reader.read();\r\n      \r\n      if (done) break;\r\n      \r\n      if (buddy.isAborted()) {\r\n        throw new Error(\"Conversion aborted\");\r\n      }\r\n      \r\n      const output = buddy.push(value);\r\n      if (output.length > 0) {\r\n        chunks.push(output);\r\n      }\r\n    }\r\n    \r\n    const final = buddy.finish();\r\n    if (final.length > 0) {\r\n      chunks.push(final);\r\n    }\r\n    \r\n    // Combine all chunks\r\n    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);\r\n    const result = new Uint8Array(totalLength);\r\n    let offset = 0;\r\n    for (const chunk of chunks) {\r\n      result.set(chunk, offset);\r\n      offset += chunk.length;\r\n    }\r\n    \r\n    if (opts.profile) {\r\n      console.log(\"[convert-buddy] Performance Stats:\", buddy.stats());\r\n    }\r\n    \r\n    return result;\r\n  } catch (error) {\r\n    reader.releaseLock();\r\n    throw error;\r\n  }\r\n}\r\n\r\n/**\r\n * Convert a browser File or Blob and download the result as a file.\r\n * \r\n * @example\r\n * const fileInput = document.querySelector('input[type=\"file\"]');\r\n * const file = fileInput.files[0];\r\n * await convertFileToFile(file, \"output.json\", {\r\n *   inputFormat: \"csv\",\r\n *   outputFormat: \"json\"\r\n * });\r\n */\r\nexport async function convertFileToFile(\r\n  inputFile: File | Blob,\r\n  outputFilename: string,\r\n  opts: BrowserConvertOptions = {}\r\n): Promise<void> {\r\n  const result = await convertFile(inputFile, opts);\r\n  \r\n  // Create a download link\r\n  const blob = new Blob([new Uint8Array(result)], { type: \"application/octet-stream\" });\r\n  const url = URL.createObjectURL(blob);\r\n  \r\n  const link = document.createElement(\"a\");\r\n  link.href = url;\r\n  link.download = outputFilename;\r\n  link.style.display = \"none\";\r\n  \r\n  document.body.appendChild(link);\r\n  link.click();\r\n  \r\n  // Cleanup\r\n  setTimeout(() => {\r\n    document.body.removeChild(link);\r\n    URL.revokeObjectURL(url);\r\n  }, 100);\r\n}\r\n\r\n/**\r\n * Create a ReadableStream that converts data on-the-fly from a File or Blob.\r\n * Useful for piping through other stream processors.\r\n * \r\n * @example\r\n * const file = fileInput.files[0];\r\n * const stream = convertFileStream(file, {\r\n *   inputFormat: \"csv\",\r\n *   outputFormat: \"ndjson\"\r\n * });\r\n * \r\n * const reader = stream.getReader();\r\n * while (true) {\r\n *   const { done, value } = await reader.read();\r\n *   if (done) break;\r\n *   // Process each chunk as it's converted\r\n *   console.log(new TextDecoder().decode(value));\r\n * }\r\n */\r\nexport async function convertFileStream(\r\n  file: File | Blob,\r\n  opts: BrowserConvertOptions = {}\r\n): Promise<ReadableStream<Uint8Array>> {\r\n  // Handle auto-detection\r\n  let actualOpts = { ...opts };\r\n  \r\n  if (opts.inputFormat === \"auto\") {\r\n    const sampleSize = 256 * 1024;\r\n    const sampleBlob = file.slice(0, sampleSize);\r\n    const sampleBuffer = await sampleBlob.arrayBuffer();\r\n    const sample = new Uint8Array(sampleBuffer);\r\n    \r\n    const detected = await autoDetectConfig(sample, { debug: opts.debug });\r\n    \r\n    if (detected.format !== \"unknown\") {\r\n      actualOpts.inputFormat = detected.format as Format;\r\n      if (detected.csvConfig) {\r\n        actualOpts.csvConfig = opts.csvConfig ? { ...detected.csvConfig, ...opts.csvConfig } : detected.csvConfig;\r\n      }\r\n      if (detected.xmlConfig) {\r\n        actualOpts.xmlConfig = opts.xmlConfig ? { ...detected.xmlConfig, ...opts.xmlConfig } : detected.xmlConfig;\r\n      }\r\n    } else {\r\n      throw new Error(\"Could not auto-detect input format.\");\r\n    }\r\n  }\r\n  \r\n  const buddy = await ConvertBuddy.create(actualOpts);\r\n  const inputStream = file.stream();\r\n  \r\n  return new ReadableStream<Uint8Array>({\r\n    async start(controller) {\r\n      const reader = inputStream.getReader();\r\n      \r\n      try {\r\n        while (true) {\r\n          const { done, value } = await reader.read();\r\n          \r\n          if (done) {\r\n            const final = buddy.finish();\r\n            if (final.length > 0) {\r\n              controller.enqueue(final);\r\n            }\r\n            controller.close();\r\n            break;\r\n          }\r\n          \r\n          if (buddy.isAborted()) {\r\n            controller.error(new Error(\"Conversion aborted\"));\r\n            break;\r\n          }\r\n          \r\n          const output = buddy.push(value);\r\n          if (output.length > 0) {\r\n            controller.enqueue(output);\r\n          }\r\n        }\r\n      } catch (error) {\r\n        controller.error(error);\r\n      } finally {\r\n        reader.releaseLock();\r\n      }\r\n    },\r\n  });\r\n}\r\n/**\r\n * Auto-detect format and create a ReadableStream for conversion.\r\n * This is a convenience helper that combines format detection with streaming conversion.\r\n * \r\n * @example\r\n * const file = fileInput.files[0];\r\n * const stream = await autoConvertStream(file, { outputFormat: \"json\" });\r\n * \r\n * // Pipe to response\r\n * return new Response(stream);\r\n */\r\nexport async function autoConvertStream(\r\n  file: File | Blob,\r\n  opts: Omit<BrowserConvertOptions, \"inputFormat\"> & { outputFormat: Format }\r\n): Promise<ReadableStream<Uint8Array>> {\r\n  return convertFileStream(file, {\r\n    ...opts,\r\n    inputFormat: \"auto\",\r\n  });\r\n}\r\n\r\n/**\r\n * Stream a file conversion directly to a writable destination.\r\n * This is useful for streaming large conversions to disk using File System Access API\r\n * or to other writable streams.\r\n * \r\n * @example\r\n * // Using File System Access API\r\n * const fileInput = document.querySelector('input[type=\"file\"]');\r\n * const file = fileInput.files[0];\r\n * \r\n * const fileHandle = await window.showSaveFilePicker({\r\n *   suggestedName: \"output.json\",\r\n *   types: [{ description: \"JSON\", accept: { \"application/json\": [\".json\"] } }]\r\n * });\r\n * const writable = await fileHandle.createWritable();\r\n * \r\n * await convertStreamToWritable(file, writable, {\r\n *   inputFormat: \"csv\",\r\n *   outputFormat: \"json\",\r\n *   onProgress: (stats) => console.log(`${stats.bytesIn} bytes processed`)\r\n * });\r\n * \r\n * @example\r\n * // With auto-detection\r\n * await convertStreamToWritable(file, writable, {\r\n *   inputFormat: \"auto\",\r\n *   outputFormat: \"ndjson\"\r\n * });\r\n */\r\nexport async function convertStreamToWritable(\r\n  file: File | Blob,\r\n  writable: WritableStream<Uint8Array> | FileSystemWritableFileStream,\r\n  opts: BrowserConvertOptions = {}\r\n): Promise<void> {\r\n  const outputStream = await convertFileStream(file, opts);\r\n  await outputStream.pipeTo(writable);\r\n}\r\n\r\n/**\r\n * Check if File System Access API is supported in the current browser.\r\n * Use this to determine if you can use File System Access API features.\r\n * \r\n * @example\r\n * if (isFileSystemAccessSupported()) {\r\n *   // Use File System Access API\r\n *   const handle = await window.showSaveFilePicker();\r\n * } else {\r\n *   // Fall back to download link\r\n *   await convertFileToFile(file, \"output.json\", opts);\r\n * }\r\n */\r\nexport function isFileSystemAccessSupported(): boolean {\r\n  return (\r\n    typeof window !== \"undefined\" &&\r\n    \"showSaveFilePicker\" in window &&\r\n    \"showOpenFilePicker\" in window\r\n  );\r\n}\r\n\r\n/**\r\n * Convert a file and save it using File System Access API with a user-selected location.\r\n * This provides a better UX than automatic downloads by letting users choose where to save.\r\n * Falls back to regular download if File System Access API is not supported.\r\n * \r\n * @example\r\n * const file = fileInput.files[0];\r\n * await convertAndSave(file, {\r\n *   inputFormat: \"csv\",\r\n *   outputFormat: \"json\",\r\n *   suggestedName: \"output.json\"\r\n * });\r\n */\r\nexport async function convertAndSave(\r\n  file: File | Blob,\r\n  opts: BrowserConvertOptions & {\r\n    suggestedName?: string;\r\n  } = {}\r\n): Promise<void> {\r\n  if (!isFileSystemAccessSupported()) {\r\n    // Fall back to regular download\r\n    const filename = opts.suggestedName || \"converted\";\r\n    await convertFileToFile(file, filename, opts);\r\n    return;\r\n  }\r\n\r\n  const outputFormat = opts.outputFormat || \"json\";\r\n  const suggestedName = opts.suggestedName || `converted.${outputFormat}`;\r\n  const types = getFileTypeConfig(outputFormat);\r\n\r\n  try {\r\n    const fileHandle = await (window as any).showSaveFilePicker({\r\n      suggestedName,\r\n      types,\r\n    });\r\n\r\n    const writable = await fileHandle.createWritable();\r\n    await convertStreamToWritable(file, writable, opts);\r\n  } catch (error: any) {\r\n    // User cancelled or error occurred\r\n    if (error?.name === \"AbortError\") {\r\n      // User cancelled - this is fine, just return\r\n      return;\r\n    }\r\n    // Re-throw other errors\r\n    throw error;\r\n  }\r\n}"],"mappings":"AAAA,SAAS,cAA0E,kBAA6C,mBAAmB,cAAc,gBAAgB,sBAAsB,8BAA8B;AAErO,cAAc;AAuBd,eAAsB,QACpB,OACA,MACqB;AACrB,SAAO,eAAe,OAAO,IAAI;AACnC;AASA,eAAsB,gBACpB,OACA,MACiB;AACjB,SAAO,uBAAuB,OAAO,IAAI;AAC3C;AAsBA,eAAsB,oBACpB,MACA,OAA8B,CAAC,GACd;AACjB,QAAM,QAAQ,MAAM,YAAY,MAAM,IAAI;AAC1C,SAAO,IAAI,YAAY,EAAE,OAAO,KAAK;AACvC;AAgBA,eAAsB,YACpB,MACA,OAA8B,CAAC,GACV;AAErB,MAAI,aAAa,EAAE,GAAG,KAAK;AAE3B,MAAI,KAAK,gBAAgB,QAAQ;AAE/B,UAAM,aAAa,MAAM;AACzB,UAAM,aAAa,KAAK,MAAM,GAAG,UAAU;AAC3C,UAAM,eAAe,MAAM,WAAW,YAAY;AAClD,UAAM,SAAS,IAAI,WAAW,YAA2B;AAEzD,UAAM,WAAW,MAAM,iBAAiB,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC;AAErE,QAAI,SAAS,WAAW,WAAW;AACjC,iBAAW,cAAc,SAAS;AAElC,UAAI,SAAS,WAAW;AACtB,mBAAW,YAAY,KAAK,YAAY,EAAE,GAAG,SAAS,WAAW,GAAG,KAAK,UAAU,IAAI,SAAS;AAAA,MAClG;AAEA,UAAI,SAAS,WAAW;AACtB,mBAAW,YAAY,KAAK,YAAY,EAAE,GAAG,SAAS,WAAW,GAAG,KAAK,UAAU,IAAI,SAAS;AAAA,MAClG;AAEA,UAAI,KAAK,OAAO;AACd,gBAAQ,IAAI,yCAAyC,SAAS,MAAM;AAAA,MACtE;AAAA,IACF,OAAO;AACL,YAAM,IAAI,MAAM,4EAA4E;AAAA,IAC9F;AAAA,EACF;AAIA,MAAI,CAAC,WAAW,kBAAkB;AAChC,UAAM,WAAW,KAAK;AACtB,eAAW,mBAAmB,KAAK;AAAA,MACjC,MAAM;AAAA;AAAA,MACN,KAAK;AAAA,QACH,IAAI,OAAO;AAAA;AAAA,QACX,KAAK,MAAM,WAAW,EAAE;AAAA;AAAA,MAC1B;AAAA,IACF;AACA,QAAI,KAAK,OAAO;AACd,cAAQ,IAAI,0CAA0C,QAAQ,iBAAY,WAAW,gBAAgB,cAAc;AAAA,IACrH;AAAA,EACF;AAEA,QAAM,QAAQ,MAAM,aAAa,OAAO,UAAU;AAGlD,QAAM,SAAS,KAAK,OAAO;AAC3B,QAAM,SAAS,OAAO,UAAU;AAEhC,QAAM,SAAuB,CAAC;AAE9B,MAAI;AACF,WAAO,MAAM;AACX,YAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK;AAE1C,UAAI,KAAM;AAEV,UAAI,MAAM,UAAU,GAAG;AACrB,cAAM,IAAI,MAAM,oBAAoB;AAAA,MACtC;AAEA,YAAM,SAAS,MAAM,KAAK,KAAK;AAC/B,UAAI,OAAO,SAAS,GAAG;AACrB,eAAO,KAAK,MAAM;AAAA,MACpB;AAAA,IACF;AAEA,UAAM,QAAQ,MAAM,OAAO;AAC3B,QAAI,MAAM,SAAS,GAAG;AACpB,aAAO,KAAK,KAAK;AAAA,IACnB;AAGA,UAAM,cAAc,OAAO,OAAO,CAAC,KAAK,UAAU,MAAM,MAAM,QAAQ,CAAC;AACvE,UAAM,SAAS,IAAI,WAAW,WAAW;AACzC,QAAI,SAAS;AACb,eAAW,SAAS,QAAQ;AAC1B,aAAO,IAAI,OAAO,MAAM;AACxB,gBAAU,MAAM;AAAA,IAClB;AAEA,QAAI,KAAK,SAAS;AAChB,cAAQ,IAAI,sCAAsC,MAAM,MAAM,CAAC;AAAA,IACjE;AAEA,WAAO;AAAA,EACT,SAAS,OAAO;AACd,WAAO,YAAY;AACnB,UAAM;AAAA,EACR;AACF;AAaA,eAAsB,kBACpB,WACA,gBACA,OAA8B,CAAC,GAChB;AACf,QAAM,SAAS,MAAM,YAAY,WAAW,IAAI;AAGhD,QAAM,OAAO,IAAI,KAAK,CAAC,IAAI,WAAW,MAAM,CAAC,GAAG,EAAE,MAAM,2BAA2B,CAAC;AACpF,QAAM,MAAM,IAAI,gBAAgB,IAAI;AAEpC,QAAM,OAAO,SAAS,cAAc,GAAG;AACvC,OAAK,OAAO;AACZ,OAAK,WAAW;AAChB,OAAK,MAAM,UAAU;AAErB,WAAS,KAAK,YAAY,IAAI;AAC9B,OAAK,MAAM;AAGX,aAAW,MAAM;AACf,aAAS,KAAK,YAAY,IAAI;AAC9B,QAAI,gBAAgB,GAAG;AAAA,EACzB,GAAG,GAAG;AACR;AAqBA,eAAsB,kBACpB,MACA,OAA8B,CAAC,GACM;AAErC,MAAI,aAAa,EAAE,GAAG,KAAK;AAE3B,MAAI,KAAK,gBAAgB,QAAQ;AAC/B,UAAM,aAAa,MAAM;AACzB,UAAM,aAAa,KAAK,MAAM,GAAG,UAAU;AAC3C,UAAM,eAAe,MAAM,WAAW,YAAY;AAClD,UAAM,SAAS,IAAI,WAAW,YAAY;AAE1C,UAAM,WAAW,MAAM,iBAAiB,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC;AAErE,QAAI,SAAS,WAAW,WAAW;AACjC,iBAAW,cAAc,SAAS;AAClC,UAAI,SAAS,WAAW;AACtB,mBAAW,YAAY,KAAK,YAAY,EAAE,GAAG,SAAS,WAAW,GAAG,KAAK,UAAU,IAAI,SAAS;AAAA,MAClG;AACA,UAAI,SAAS,WAAW;AACtB,mBAAW,YAAY,KAAK,YAAY,EAAE,GAAG,SAAS,WAAW,GAAG,KAAK,UAAU,IAAI,SAAS;AAAA,MAClG;AAAA,IACF,OAAO;AACL,YAAM,IAAI,MAAM,qCAAqC;AAAA,IACvD;AAAA,EACF;AAEA,QAAM,QAAQ,MAAM,aAAa,OAAO,UAAU;AAClD,QAAM,cAAc,KAAK,OAAO;AAEhC,SAAO,IAAI,eAA2B;AAAA,IACpC,MAAM,MAAM,YAAY;AACtB,YAAM,SAAS,YAAY,UAAU;AAErC,UAAI;AACF,eAAO,MAAM;AACX,gBAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,KAAK;AAE1C,cAAI,MAAM;AACR,kBAAM,QAAQ,MAAM,OAAO;AAC3B,gBAAI,MAAM,SAAS,GAAG;AACpB,yBAAW,QAAQ,KAAK;AAAA,YAC1B;AACA,uBAAW,MAAM;AACjB;AAAA,UACF;AAEA,cAAI,MAAM,UAAU,GAAG;AACrB,uBAAW,MAAM,IAAI,MAAM,oBAAoB,CAAC;AAChD;AAAA,UACF;AAEA,gBAAM,SAAS,MAAM,KAAK,KAAK;AAC/B,cAAI,OAAO,SAAS,GAAG;AACrB,uBAAW,QAAQ,MAAM;AAAA,UAC3B;AAAA,QACF;AAAA,MACF,SAAS,OAAO;AACd,mBAAW,MAAM,KAAK;AAAA,MACxB,UAAE;AACA,eAAO,YAAY;AAAA,MACrB;AAAA,IACF;AAAA,EACF,CAAC;AACH;AAYA,eAAsB,kBACpB,MACA,MACqC;AACrC,SAAO,kBAAkB,MAAM;AAAA,IAC7B,GAAG;AAAA,IACH,aAAa;AAAA,EACf,CAAC;AACH;AA+BA,eAAsB,wBACpB,MACA,UACA,OAA8B,CAAC,GAChB;AACf,QAAM,eAAe,MAAM,kBAAkB,MAAM,IAAI;AACvD,QAAM,aAAa,OAAO,QAAQ;AACpC;AAeO,SAAS,8BAAuC;AACrD,SACE,OAAO,WAAW,eAClB,wBAAwB,UACxB,wBAAwB;AAE5B;AAeA,eAAsB,eACpB,MACA,OAEI,CAAC,GACU;AACf,MAAI,CAAC,4BAA4B,GAAG;AAElC,UAAM,WAAW,KAAK,iBAAiB;AACvC,UAAM,kBAAkB,MAAM,UAAU,IAAI;AAC5C;AAAA,EACF;AAEA,QAAM,eAAe,KAAK,gBAAgB;AAC1C,QAAM,gBAAgB,KAAK,iBAAiB,aAAa,YAAY;AACrE,QAAM,QAAQ,kBAAkB,YAAY;AAE5C,MAAI;AACF,UAAM,aAAa,MAAO,OAAe,mBAAmB;AAAA,MAC1D;AAAA,MACA;AAAA,IACF,CAAC;AAED,UAAM,WAAW,MAAM,WAAW,eAAe;AACjD,UAAM,wBAAwB,MAAM,UAAU,IAAI;AAAA,EACpD,SAAS,OAAY;AAEnB,QAAI,OAAO,SAAS,cAAc;AAEhC;AAAA,IACF;AAEA,UAAM;AAAA,EACR;AACF;","names":[]}

package/dist/src/index.d.ts

@@ -12,15 +12,26 @@ type DetectOptions = {
     maxBytes?: number;
     debug?: boolean;
 };
+type ProgressCallback = (stats: Stats) => void;
 type ConvertBuddyOptions = {
     debug?: boolean;
     profile?: boolean;
-    inputFormat?: Format;
+    inputFormat?: Format | "auto";
     outputFormat?: Format;
     chunkTargetBytes?: number;
     parallelism?: number;
+    maxMemoryMB?: number;
     csvConfig?: CsvConfig;
     xmlConfig?: XmlConfig;
+    onProgress?: ProgressCallback;
+    progressIntervalBytes?: number;
+};
+type ConvertOptions = {
+    inputFormat?: Format | "auto";
+    outputFormat: Format;
+    csvConfig?: CsvConfig;
+    xmlConfig?: XmlConfig;
+    onProgress?: ProgressCallback;
 };
 type CsvConfig = {
     delimiter?: string;
@@ -50,19 +61,138 @@ declare class ConvertBuddy {
     private converter;
     private debug;
     private profile;
-    private constructor();
+    private aborted;
+    private paused;
+    private onProgress?;
+    private progressIntervalBytes;
+    private lastProgressBytes;
+    private globalConfig;
+    private initialized;
+    simd: boolean;
+    /**
+     * Create a new ConvertBuddy instance with global configuration.
+     * This is useful when you want to set memory limits, debug mode, or other global settings.
+     *
+     * @example
+     * const buddy = new ConvertBuddy({ maxMemoryMB: 512, debug: true });
+     * const result = await buddy.convert(input, { outputFormat: "json" });
+     */
+    constructor(opts?: ConvertBuddyOptions);
+    /**
+     * Convert input (string, Buffer, File, URL, etc.) to the desired output format.
+     * This is the main method for the new simplified API.
+     *
+     * @example
+     * // Auto-detect everything
+     * const buddy = new ConvertBuddy();
+     * const result = await buddy.convert("https://example.com/data.csv", { outputFormat: "json" });
+     *
+     * @example
+     * // With configuration
+     * const buddy = new ConvertBuddy({ maxMemoryMB: 512 });
+     * const result = await buddy.convert(file, { inputFormat: "csv", outputFormat: "json" });
+     */
+    convert(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<Uint8Array>;
+    private convertFromUrl;
+    private convertFromString;
+    private convertFromBuffer;
+    private convertFromFile;
+    private convertFromBlob;
+    private convertFromStream;
+    /**
+     * Legacy create method for backward compatibility.
+     * Prefer using the constructor: new ConvertBuddy(opts)
+     */
     static create(opts?: ConvertBuddyOptions): Promise<ConvertBuddy>;
     push(chunk: Uint8Array): Uint8Array;
     finish(): Uint8Array;
     stats(): Stats;
+    abort(): void;
+    pause(): void;
+    resume(): void;
+    isAborted(): boolean;
+    isPaused(): boolean;
 }
 declare function detectFormat(input: DetectInput, opts?: DetectOptions): Promise<Format | "unknown">;
 declare function detectCsvFieldsAndDelimiter(input: DetectInput, opts?: DetectOptions): Promise<CsvDetection | null>;
 declare function detectXmlElements(input: DetectInput, opts?: DetectOptions): Promise<XmlDetection | null>;
+declare function autoDetectConfig(sample: Uint8Array, opts?: {
+    debug?: boolean;
+}): Promise<{
+    format: Format | "unknown";
+    csvConfig?: CsvConfig;
+    xmlConfig?: XmlConfig;
+}>;
 declare class ConvertBuddyTransformStream extends TransformStream<Uint8Array, Uint8Array> {
     constructor(opts?: ConvertBuddyOptions);
 }
 declare function convert(input: Uint8Array | string, opts?: ConvertBuddyOptions): Promise<Uint8Array>;
 declare function convertToString(input: Uint8Array | string, opts?: ConvertBuddyOptions): Promise<string>;
+/**
+ * Ultra-simple standalone convert function with auto-detection.
+ * Accepts any input type (URL, File, Buffer, string, stream) and automatically detects format.
+ *
+ * @example
+ * // From URL
+ * import { convertAny } from "convert-buddy-js";
+ * const result = await convertAny("https://example.com/data.csv", { outputFormat: "json" });
+ *
+ * @example
+ * // From File (browser)
+ * const file = fileInput.files[0];
+ * const result = await convertAny(file, { outputFormat: "ndjson" });
+ *
+ * @example
+ * // From string data
+ * const result = await convertAny('{"name":"Ada"}', { outputFormat: "csv" });
+ */
+declare function convertAny(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<Uint8Array>;
+/**
+ * Ultra-simple standalone convert function that returns a string.
+ * Same as convertAny but decodes the output to a string.
+ *
+ * @example
+ * import { convertAnyToString } from "convert-buddy-js";
+ * const json = await convertAnyToString("https://example.com/data.csv", { outputFormat: "json" });
+ * console.log(JSON.parse(json));
+ */
+declare function convertAnyToString(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<string>;
+/**
+ * Get MIME type for a given format
+ *
+ * @example
+ * const mimeType = getMimeType("json"); // "application/json"
+ */
+declare function getMimeType(format: Format): string;
+/**
+ * Get file extension for a given format (without the dot)
+ *
+ * @example
+ * const ext = getExtension("json"); // "json"
+ */
+declare function getExtension(format: Format): string;
+/**
+ * Get suggested filename for a converted file
+ *
+ * @param originalName - Original filename
+ * @param outputFormat - Target format
+ * @param includeTimestamp - Whether to include a timestamp (default: false)
+ *
+ * @example
+ * const name = getSuggestedFilename("data.csv", "json"); // "data.json"
+ * const name = getSuggestedFilename("data.csv", "json", true); // "data_converted_1234567890.json"
+ */
+declare function getSuggestedFilename(originalName: string, outputFormat: Format, includeTimestamp?: boolean): string;
+/**
+ * Get File System Access API file type configuration for showSaveFilePicker
+ *
+ * @example
+ * const types = getFileTypeConfig("json");
+ * const handle = await showSaveFilePicker({ types });
+ */
+declare function getFileTypeConfig(format: Format): Array<{
+    description: string;
+    accept: Record<string, string[]>;
+}>;
 
-export { ConvertBuddy, type ConvertBuddyOptions, ConvertBuddyTransformStream, type CsvConfig, type CsvDetection, type DetectInput, type DetectOptions, type Format, type Stats, type XmlConfig, type XmlDetection, convert, convertToString, detectCsvFieldsAndDelimiter, detectFormat, detectXmlElements };
+export { ConvertBuddy, type ConvertBuddyOptions, ConvertBuddyTransformStream, type ConvertOptions, type CsvConfig, type CsvDetection, type DetectInput, type DetectOptions, type Format, type ProgressCallback, type Stats, type XmlConfig, type XmlDetection, autoDetectConfig, convert, convertAny, convertAnyToString, convertToString, detectCsvFieldsAndDelimiter, detectFormat, detectXmlElements, getExtension, getFileTypeConfig, getMimeType, getSuggestedFilename };