convert-buddy-js 0.9.2 → 0.9.5

package/README.md

@@ -2,15 +2,152 @@
 
 A high-performance, streaming-first parser and converter for CSV, XML, NDJSON, and JSON. `convert-buddy-js` is a TypeScript wrapper around a Rust/WASM core, offering fast parsing and multiple usage styles for Node.js and browsers.
 
+## Status & Quality
+
+[![Known Vulnerabilities](https://snyk.io/test/github/brunohanss/convert-buddy/badge.svg)](https://snyk.io/test/github/brunohanss/convert-buddy)
+[![CI/CD Pipeline](https://github.com/brunohanss/convert-buddy/actions/workflows/test.yml/badge.svg)](https://github.com/brunohanss/convert-buddy/actions)
+[![Coverage Status](https://img.shields.io/codecov/c/github/brunohanss/convert-buddy?label=coverage)](https://codecov.io/gh/brunohanss/convert-buddy)
+[![npm version](https://img.shields.io/npm/v/convert-buddy-js.svg)](https://www.npmjs.com/package/convert-buddy-js)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/convert-buddy-js.svg)](https://bundlephobia.com/package/convert-buddy-js)
+
 ## Install
 
 ```bash
 npm install convert-buddy-js
 ```
 
+## Quick Start
+
+### Browser - Convert File Input
+
+```ts
+import { convertFileToString } from "convert-buddy-js/browser";
+
+const fileInput = document.querySelector('input[type="file"]');
+fileInput.addEventListener('change', async (e) => {
+  const file = e.target.files[0];
+  const result = await convertFileToString(file, {
+    inputFormat: "auto",
+    outputFormat: "json"
+  });
+  console.log(result);
+});
+```
+
+### Node.js - Convert File
+
+```ts
+import { convertFileToString } from "convert-buddy-js/node";
+
+const result = await convertFileToString("input.csv", {
+  inputFormat: "auto",
+  outputFormat: "json"
+});
+console.log(result);
+```
+
 ## Usage
 
-### Convert a full string or buffer
+### High-Level API (Recommended)
+
+#### Browser Helpers
+
+Simple file conversion without manual buffer handling:
+
+```ts
+import { 
+  convertFileToString,
+  convertFile,
+  convertFileToFile,
+  convertFileStream
+} from "convert-buddy-js/browser";
+
+// Convert to string
+const json = await convertFileToString(file, {
+  inputFormat: "csv",
+  outputFormat: "json"
+});
+
+// Convert and download
+await convertFileToFile(file, "output.json", {
+  inputFormat: "csv",
+  outputFormat: "json"
+});
+
+// Get streaming API
+const stream = await convertFileStream(file, {
+  inputFormat: "csv",
+  outputFormat: "ndjson"
+});
+```
+
+#### Node.js Helpers
+
+Convenient file path and stream conversions:
+
+```ts
+import { 
+  convertFileToString,
+  convertFileToFile,
+  convertBuffer,
+  convertStream
+} from "convert-buddy-js/node";
+
+// File to string
+const json = await convertFileToString("input.csv", {
+  inputFormat: "csv",
+  outputFormat: "json"
+});
+
+// File to file
+await convertFileToFile("input.csv", "output.json", {
+  inputFormat: "csv",
+  outputFormat: "json"
+});
+
+// From stream (HTTP, stdin, etc.)
+const result = await convertStream(inputStream, {
+  inputFormat: "auto",
+  outputFormat: "json"
+});
+```
+
+#### Progress Tracking & Control
+
+Monitor long-running conversions and allow cancellation:
+
+```ts
+const buddy = await ConvertBuddy.create({
+  inputFormat: "csv",
+  outputFormat: "json",
+  onProgress: (stats) => {
+    console.log(`${stats.recordsProcessed} records processed`);
+    console.log(`${stats.throughputMbPerSec.toFixed(2)} MB/s`);
+  },
+  progressIntervalBytes: 1024 * 1024 // Every 1MB
+});
+
+// User cancels
+cancelButton.addEventListener('click', () => buddy.abort());
+```
+
+#### Auto-Detection
+
+Let the library detect format automatically:
+
+```ts
+const result = await convertFileToString(file, {
+  inputFormat: "auto",    // Auto-detect CSV, JSON, NDJSON, XML
+  outputFormat: "json",
+  csvConfig: {            // Optional: still apply config
+    delimiter: ","
+  }
+});
+```
+
+### Low-Level API
+
+#### Convert a full string or buffer
 
 ```ts
 import { convertToString } from "convert-buddy-js";
@@ -25,7 +162,7 @@ const output = await convertToString(csv, {
 console.log(output);
 ```
 
-### Manual streaming (chunked)
+#### Manual streaming (chunked)
 
 ```ts
 import { ConvertBuddy } from "convert-buddy-js";
@@ -42,7 +179,7 @@ const finalOutput = buddy.finish();
 console.log(buddy.stats());
 ```
 
-### Node.js Transform stream
+#### Node.js Transform stream
 
 Use the Node-specific entrypoint so bundlers keep `node:stream` out of the browser bundle.
 
@@ -62,7 +199,7 @@ createReadStream("input.csv")
   .pipe(createWriteStream("output.ndjson"));
 ```
 
-### Web Streams
+#### Web Streams
 
 ```ts
 import { ConvertBuddyTransformStream } from "convert-buddy-js";
@@ -76,7 +213,7 @@ const response = await fetch("/data.csv");
 const outputStream = response.body?.pipeThrough(transform);
 ```
 
-### Detect format and CSV fields/delimiter
+#### Detect format and CSV fields/delimiter
 
 Use streaming inputs to keep detection fast on large files.
 

package/dist/src/browser.d.ts

@@ -0,0 +1,74 @@
+import { ConvertBuddyOptions } from './index.js';
+export { ConvertBuddy, ConvertBuddyTransformStream, CsvConfig, CsvDetection, DetectInput, DetectOptions, Format, ProgressCallback, Stats, XmlConfig, XmlDetection, autoDetectConfig, convert, convertToString, detectCsvFieldsAndDelimiter, detectFormat, detectXmlElements } from './index.js';
+
+type BrowserConvertOptions = ConvertBuddyOptions & {};
+/**
+ * Convert a browser File or Blob object to a string.
+ * Handles streaming internally using FileReader and web streams.
+ *
+ * @example
+ * // From file input
+ * const fileInput = document.querySelector('input[type="file"]');
+ * const file = fileInput.files[0];
+ * const result = await convertFileToString(file, {
+ *   inputFormat: "csv",
+ *   outputFormat: "json"
+ * });
+ *
+ * @example
+ * // With auto-detection
+ * const result = await convertFileToString(file, {
+ *   inputFormat: "auto",
+ *   outputFormat: "ndjson"
+ * });
+ */
+declare function convertFileToString(file: File | Blob, opts?: BrowserConvertOptions): Promise<string>;
+/**
+ * Convert a browser File or Blob object to a Uint8Array.
+ * Handles streaming internally using FileReader and web streams.
+ *
+ * @example
+ * const file = fileInput.files[0];
+ * const result = await convertFile(file, {
+ *   inputFormat: "csv",
+ *   outputFormat: "json",
+ *   onProgress: (stats) => {
+ *     console.log(`Progress: ${stats.bytesIn} bytes processed`);
+ *   }
+ * });
+ */
+declare function convertFile(file: File | Blob, opts?: BrowserConvertOptions): Promise<Uint8Array>;
+/**
+ * Convert a browser File or Blob and download the result as a file.
+ *
+ * @example
+ * const fileInput = document.querySelector('input[type="file"]');
+ * const file = fileInput.files[0];
+ * await convertFileToFile(file, "output.json", {
+ *   inputFormat: "csv",
+ *   outputFormat: "json"
+ * });
+ */
+declare function convertFileToFile(inputFile: File | Blob, outputFilename: string, opts?: BrowserConvertOptions): Promise<void>;
+/**
+ * Create a ReadableStream that converts data on-the-fly from a File or Blob.
+ * Useful for piping through other stream processors.
+ *
+ * @example
+ * const file = fileInput.files[0];
+ * const stream = convertFileStream(file, {
+ *   inputFormat: "csv",
+ *   outputFormat: "ndjson"
+ * });
+ *
+ * const reader = stream.getReader();
+ * while (true) {
+ *   const { done, value } = await reader.read();
+ *   if (done) break;
+ *   // Process each chunk as it's converted
+ *   console.log(new TextDecoder().decode(value));
+ * }
+ */
+declare function convertFileStream(file: File | Blob, opts?: BrowserConvertOptions): Promise<ReadableStream<Uint8Array>>;
+
+export { type BrowserConvertOptions, ConvertBuddyOptions, convertFile, convertFileStream, convertFileToFile, convertFileToString };

package/dist/src/browser.js

@@ -0,0 +1,140 @@
+import { ConvertBuddy, autoDetectConfig } from "./index.js";
+export * from "./index.js";
+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.");
+    }
+  }
+  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();
+      }
+    }
+  });
+}
+export {
+  convertFile,
+  convertFileStream,
+  convertFileToFile,
+  convertFileToString
+};
+//# 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 Format, autoDetectConfig } 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 * 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);\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  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"],"mappings":"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","names":[]}

package/dist/src/index.d.ts

@@ -6,20 +6,24 @@ type CsvDetection = {
 };
 type XmlDetection = {
     elements: string[];
+    recordElement?: string;
 };
 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;
     csvConfig?: CsvConfig;
     xmlConfig?: XmlConfig;
+    onProgress?: ProgressCallback;
+    progressIntervalBytes?: number;
 };
 type CsvConfig = {
     delimiter?: string;
@@ -49,19 +53,36 @@ declare class ConvertBuddy {
     private converter;
     private debug;
     private profile;
+    private aborted;
+    private paused;
+    private onProgress?;
+    private progressIntervalBytes;
+    private lastProgressBytes;
     private constructor();
     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>;
 
-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 CsvConfig, type CsvDetection, type DetectInput, type DetectOptions, type Format, type ProgressCallback, type Stats, type XmlConfig, type XmlDetection, autoDetectConfig, convert, convertToString, detectCsvFieldsAndDelimiter, detectFormat, detectXmlElements };

package/dist/src/index.js

@@ -14,10 +14,17 @@ class ConvertBuddy {
   converter;
   debug;
   profile;
-  constructor(converter, debug, profile) {
+  aborted = false;
+  paused = false;
+  onProgress;
+  progressIntervalBytes;
+  lastProgressBytes = 0;
+  constructor(converter, debug, profile, opts = {}) {
     this.converter = converter;
     this.debug = debug;
     this.profile = profile;
+    this.onProgress = opts.onProgress;
+    this.progressIntervalBytes = opts.progressIntervalBytes || 1024 * 1024;
   }
   static async create(opts = {}) {
     const debug = !!opts.debug;
@@ -27,35 +34,79 @@ class ConvertBuddy {
       await wasmModule.default();
     }
     wasmModule.init(debug);
+    let inputFormat = opts.inputFormat;
+    let csvConfig = opts.csvConfig;
+    if (inputFormat === "auto") {
+      inputFormat = void 0;
+    }
     let converter;
-    if (opts.inputFormat && opts.outputFormat) {
+    if (inputFormat && opts.outputFormat) {
       const Converter = wasmModule.Converter;
       converter = Converter.withConfig(
         debug,
-        opts.inputFormat,
+        inputFormat,
         opts.outputFormat,
         opts.chunkTargetBytes || 1024 * 1024,
         profile,
-        opts.csvConfig,
-        opts.xmlConfig
+        csvConfig || null,
+        opts.xmlConfig || null
       );
     } else {
       converter = new wasmModule.Converter(debug);
     }
     if (debug) console.log("[convert-buddy-js] initialized", opts);
-    return new ConvertBuddy(converter, debug, profile);
+    return new ConvertBuddy(converter, debug, profile, opts);
   }
   push(chunk) {
+    if (this.aborted) {
+      throw new Error("Conversion has been aborted");
+    }
+    if (this.paused) {
+      throw new Error("Conversion is paused. Call resume() before pushing more data.");
+    }
     if (this.debug) console.log("[convert-buddy-js] push", chunk.byteLength);
-    return this.converter.push(chunk);
+    const output = this.converter.push(chunk);
+    if (this.onProgress) {
+      const stats = this.stats();
+      if (stats.bytesIn - this.lastProgressBytes >= this.progressIntervalBytes) {
+        this.onProgress(stats);
+        this.lastProgressBytes = stats.bytesIn;
+      }
+    }
+    return output;
   }
   finish() {
+    if (this.aborted) {
+      throw new Error("Conversion has been aborted");
+    }
     if (this.debug) console.log("[convert-buddy-js] finish");
-    return this.converter.finish();
+    const output = this.converter.finish();
+    if (this.onProgress) {
+      this.onProgress(this.stats());
+    }
+    return output;
   }
   stats() {
     return this.converter.getStats();
   }
+  abort() {
+    this.aborted = true;
+    if (this.debug) console.log("[convert-buddy-js] aborted");
+  }
+  pause() {
+    this.paused = true;
+    if (this.debug) console.log("[convert-buddy-js] paused");
+  }
+  resume() {
+    this.paused = false;
+    if (this.debug) console.log("[convert-buddy-js] resumed");
+  }
+  isAborted() {
+    return this.aborted;
+  }
+  isPaused() {
+    return this.paused;
+  }
 }
 async function readSample(input, maxBytes = 256 * 1024) {
   if (typeof input === "string") {
@@ -136,6 +187,28 @@ async function detectXmlElements(input, opts = {}) {
   const result = wasmModule.detectXmlElements?.(sample);
   return result ?? null;
 }
+async function autoDetectConfig(sample, opts = {}) {
+  const wasmModule = await loadDetectionWasm(!!opts.debug);
+  const format = wasmModule.detectFormat?.(sample) ?? "unknown";
+  const result = { format };
+  if (format === "csv") {
+    const csvDetection = wasmModule.detectCsvFields?.(sample);
+    if (csvDetection) {
+      result.csvConfig = {
+        delimiter: csvDetection.delimiter,
+        hasHeaders: csvDetection.fields.length > 0
+      };
+    }
+  } else if (format === "xml") {
+    const xmlDetection = wasmModule.detectXmlElements?.(sample);
+    if (xmlDetection?.recordElement) {
+      result.xmlConfig = {
+        recordElement: xmlDetection.recordElement
+      };
+    }
+  }
+  return result;
+}
 class ConvertBuddyTransformStream extends TransformStream {
   constructor(opts = {}) {
     let buddy = null;
@@ -189,6 +262,7 @@ async function convertToString(input, opts = {}) {
 export {
   ConvertBuddy,
   ConvertBuddyTransformStream,
+  autoDetectConfig,
   convert,
   convertToString,
   detectCsvFieldsAndDelimiter,