convert-buddy-js 0.10.18 → 0.11.1

package/README.md

@@ -111,9 +111,9 @@ const json = await convertToString("input.csv", {
 
 ## API Overview
 
-Convert Buddy offers four layers of control, from one-liners to fully manual streaming.
+Convert Buddy offers multiple layers of control, from one-liners to fully manual streaming.
 
-1. Ultra-simple API
+### 1. Ultra-simple API
 
 ```ts
 import { convert, convertToString } from "convert-buddy-js";
@@ -130,7 +130,52 @@ Supported input types
 - `ReadableStream<Uint8Array>`
 - Node file paths
 
-2. Instance-based API
+### 2. StreamController API (NEW! 🎉)
+
+**Per-record processing with backpressure management**
+
+```ts
+import { NodeStreamController } from "convert-buddy-js/node";
+
+const controller = new NodeStreamController({
+  inputFormat: "csv",
+  outputFormat: "ndjson",
+  onRecord: async (record, index) => {
+    // Process each record as it's converted
+    await saveToDatabase(record);
+  },
+  onStreamProgress: (stats, recordCount) => {
+    console.log(`Processed ${recordCount} records`);
+  },
+  progressBatchSize: 1000,
+});
+
+// Option 1: Await (wait for completion)
+await controller.process("large-file.csv");
+
+// Option 2: Fire-and-forget (non-blocking, runs in background)
+controller.process("large-file.csv").then(() => {
+  console.log("Done!");
+});
+```
+
+**Browser version**
+
+```ts
+import { BrowserStreamController } from "convert-buddy-js/browser";
+
+const controller = new BrowserStreamController({
+  inputFormat: "csv",
+  outputFormat: "ndjson",
+  onRecord: (record) => displayRecord(record),
+});
+
+await controller.process(fileInput.files[0]);
+```
+
+📚 **[See Full StreamController Documentation](./STREAM_CONTROLLER_GUIDE.md)**
+
+### 3. Instance-based API
 
 ```ts
 import { ConvertBuddy } from "convert-buddy-js";
@@ -144,7 +189,7 @@ const buddy = new ConvertBuddy({
 const out = await buddy.convert(file, { outputFormat: "ndjson" });
 ```
 
-3. High-level helpers
+### 4. High-level helpers
 
 **Browser helpers**
 

package/dist/browser-stream-controller.d.ts

@@ -0,0 +1,107 @@
+import { A as StreamControllerOptions, i as Stats } from './index-BpUN6Tdz.js';
+
+/**
+ * Browser-specific StreamController implementation
+ *
+ * Provides high-level streaming API for browser environments with ReadableStream support.
+ */
+
+type BrowserStreamInput = ReadableStream<Uint8Array> | string | Blob | File;
+/**
+ * BrowserStreamController - High-level streaming API for browser environments
+ *
+ * Features:
+ * - Per-record callbacks with backpressure management
+ * - Pause/resume/abort controls
+ * - Progress tracking
+ * - Automatic NDJSON/CSV/JSON/XML splitting and parsing
+ *
+ * @example
+ * ```ts
+ * const controller = new BrowserStreamController({
+ *   inputFormat: "csv",
+ *   outputFormat: "ndjson",
+ *   onRecord: async (record, index) => {
+ *     await processRecord(record);
+ *   },
+ *   onProgress: (stats, recordCount) => {
+ *     console.log(`Processed ${recordCount} records`);
+ *   }
+ * });
+ *
+ * await controller.process(fetch('/data.csv').then(r => r.body!));
+ * ```
+ */
+declare class BrowserStreamController {
+    private options;
+    private buddy;
+    private reader;
+    private aborted;
+    private paused;
+    private recordCount;
+    private splitter;
+    constructor(options: StreamControllerOptions);
+    /**
+     * Process a stream/URL/File/Blob and invoke callbacks for each record
+     */
+    process(input: BrowserStreamInput): Promise<void>;
+    /**
+     * Convert various input types to ReadableStream
+     */
+    private inputToStream;
+    /**
+     * Process the stream chunk by chunk
+     */
+    private processStream;
+    /**
+     * Process output bytes and split into records
+     */
+    private processOutput;
+    /**
+     * Invoke the onRecord callback with proper backpressure handling
+     */
+    private invokeRecordCallback;
+    /**
+     * Pause the stream processing
+     */
+    pause(): void;
+    /**
+     * Resume the stream processing
+     */
+    resume(): void;
+    /**
+     * Abort the stream processing
+     */
+    abort(): void;
+    /**
+     * Get current statistics
+     */
+    stats(): Stats | null;
+    /**
+     * Get current record count
+     */
+    getRecordCount(): number;
+    /**
+     * Check if processing is paused
+     */
+    isPaused(): boolean;
+    /**
+     * Check if processing is aborted
+     */
+    isAborted(): boolean;
+}
+/**
+ * Convenience function to process a stream with a simple callback
+ *
+ * @example
+ * ```ts
+ * await processStream('/data.csv', {
+ *   inputFormat: 'csv',
+ *   outputFormat: 'ndjson',
+ *   onRecord: (record) => console.log(record),
+ * });
+ * ```
+ */
+declare function processStream(input: BrowserStreamInput, options: StreamControllerOptions): Promise<void>;
+
+export { BrowserStreamController, type BrowserStreamInput, processStream };

package/dist/browser-stream-controller.js

@@ -0,0 +1,226 @@
+import { ConvertBuddy } from "./index.js";
+import { createSplitter } from "./stream-controller.js";
+class BrowserStreamController {
+  options;
+  buddy = null;
+  reader = null;
+  aborted = false;
+  paused = false;
+  recordCount = 0;
+  splitter;
+  constructor(options) {
+    this.options = {
+      outputFormat: "ndjson",
+      progressBatchSize: 1e3,
+      autoPause: true,
+      ...options
+    };
+    this.splitter = createSplitter(this.options.outputFormat, this.options);
+  }
+  /**
+   * Process a stream/URL/File/Blob and invoke callbacks for each record
+   */
+  async process(input) {
+    try {
+      const stream = await this.inputToStream(input);
+      this.buddy = await ConvertBuddy.create({
+        ...this.options,
+        profile: true
+        // Enable stats for progress tracking
+      });
+      this.reader = stream.getReader();
+      await this.processStream();
+    } finally {
+      if (this.reader) {
+        try {
+          await this.reader.cancel();
+        } catch (e) {
+        }
+        this.reader = null;
+      }
+      this.buddy = null;
+    }
+  }
+  /**
+   * Convert various input types to ReadableStream
+   */
+  async inputToStream(input) {
+    if (typeof input === "string") {
+      if (input.startsWith("http://") || input.startsWith("https://")) {
+        const response = await fetch(input);
+        if (!response.ok) {
+          throw new Error(`Failed to fetch ${input}: ${response.statusText}`);
+        }
+        if (!response.body) {
+          throw new Error("Response body is null");
+        }
+        return response.body;
+      } else {
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(input);
+        return new ReadableStream({
+          start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+          }
+        });
+      }
+    } else if (typeof ReadableStream !== "undefined" && input instanceof ReadableStream) {
+      return input;
+    } else if (typeof Blob !== "undefined" && input instanceof Blob || typeof File !== "undefined" && input instanceof File) {
+      return input.stream();
+    } else {
+      throw new Error("Unsupported input type for BrowserStreamController");
+    }
+  }
+  /**
+   * Process the stream chunk by chunk
+   */
+  async processStream() {
+    if (!this.buddy || !this.reader) {
+      throw new Error("Stream not initialized");
+    }
+    try {
+      while (true) {
+        if (this.aborted) {
+          this.buddy.abort();
+          break;
+        }
+        while (this.paused && !this.aborted) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        const { done, value } = await this.reader.read();
+        if (done) {
+          const finalOutput = this.buddy.finish();
+          if (finalOutput.length > 0) {
+            await this.processOutput(finalOutput);
+          }
+          const finalRecords = this.splitter.flush();
+          for (const record of finalRecords) {
+            await this.invokeRecordCallback(record);
+          }
+          break;
+        }
+        const needsRecords = !!this.options.onRecord;
+        const result = this.buddy.pushWithRecords(value, needsRecords);
+        if (typeof result === "object" && "output" in result) {
+          if (result.output.length > 0) {
+            await this.processOutput(result.output, result.records);
+          }
+        } else if (result.length > 0) {
+          await this.processOutput(result);
+        }
+      }
+    } catch (error) {
+      if (this.aborted) {
+        return;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Process output bytes and split into records
+   */
+  async processOutput(output, wasmRecords) {
+    if (this.options.onData) {
+      this.options.onData(output);
+    }
+    const records = wasmRecords && wasmRecords.length > 0 ? wasmRecords : this.splitter.push(output);
+    for (const record of records) {
+      if (this.aborted) break;
+      await this.invokeRecordCallback(record);
+      if (this.options.onStreamProgress && this.recordCount % (this.options.progressBatchSize || 1e3) === 0) {
+        const stats = this.buddy.stats();
+        this.options.onStreamProgress(stats, this.recordCount);
+      }
+    }
+  }
+  /**
+   * Invoke the onRecord callback with proper backpressure handling
+   */
+  async invokeRecordCallback(record) {
+    if (!this.options.onRecord) {
+      this.recordCount++;
+      return;
+    }
+    try {
+      const result = this.options.onRecord(record, this.recordCount);
+      if (this.options.autoPause && result instanceof Promise) {
+        const shouldContinue = await result;
+        if (shouldContinue === false) {
+          this.pause();
+        }
+      } else if (result === false) {
+        this.pause();
+      }
+      this.recordCount++;
+    } catch (error) {
+      console.error("[BrowserStreamController] Error in onRecord callback:", error);
+      throw error;
+    }
+  }
+  /**
+   * Pause the stream processing
+   */
+  pause() {
+    this.paused = true;
+    if (this.buddy) {
+      this.buddy.pause();
+    }
+  }
+  /**
+   * Resume the stream processing
+   */
+  resume() {
+    this.paused = false;
+    if (this.buddy) {
+      this.buddy.resume();
+    }
+  }
+  /**
+   * Abort the stream processing
+   */
+  abort() {
+    this.aborted = true;
+    if (this.buddy) {
+      this.buddy.abort();
+    }
+    if (this.reader) {
+      this.reader.cancel().catch(() => {
+      });
+    }
+  }
+  /**
+   * Get current statistics
+   */
+  stats() {
+    return this.buddy ? this.buddy.stats() : null;
+  }
+  /**
+   * Get current record count
+   */
+  getRecordCount() {
+    return this.recordCount;
+  }
+  /**
+   * Check if processing is paused
+   */
+  isPaused() {
+    return this.paused;
+  }
+  /**
+   * Check if processing is aborted
+   */
+  isAborted() {
+    return this.aborted;
+  }
+}
+async function processStream(input, options) {
+  const controller = new BrowserStreamController(options);
+  await controller.process(input);
+}
+export {
+  BrowserStreamController,
+  processStream
+};
+//# sourceMappingURL=browser-stream-controller.js.map

package/dist/browser-stream-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser-stream-controller.ts"],"sourcesContent":["/**\r\n * Browser-specific StreamController implementation\r\n * \r\n * Provides high-level streaming API for browser environments with ReadableStream support.\r\n */\r\n\r\nimport { ConvertBuddy } from \"./index.js\";\r\nimport type { Stats } from \"./index.js\";\r\nimport { StreamControllerOptions, createSplitter } from \"./stream-controller.js\";\r\n\r\nexport type BrowserStreamInput = ReadableStream<Uint8Array> | string | Blob | File;\r\n\r\n/**\r\n * BrowserStreamController - High-level streaming API for browser environments\r\n * \r\n * Features:\r\n * - Per-record callbacks with backpressure management\r\n * - Pause/resume/abort controls\r\n * - Progress tracking\r\n * - Automatic NDJSON/CSV/JSON/XML splitting and parsing\r\n * \r\n * @example\r\n * ```ts\r\n * const controller = new BrowserStreamController({\r\n *   inputFormat: \"csv\",\r\n *   outputFormat: \"ndjson\",\r\n *   onRecord: async (record, index) => {\r\n *     await processRecord(record);\r\n *   },\r\n *   onProgress: (stats, recordCount) => {\r\n *     console.log(`Processed ${recordCount} records`);\r\n *   }\r\n * });\r\n * \r\n * await controller.process(fetch('/data.csv').then(r => r.body!));\r\n * ```\r\n */\r\nexport class BrowserStreamController {\r\n  private options: StreamControllerOptions;\r\n  private buddy: ConvertBuddy | null = null;\r\n  private reader: ReadableStreamDefaultReader<Uint8Array> | null = null;\r\n  private aborted = false;\r\n  private paused = false;\r\n  private recordCount = 0;\r\n  private splitter: any;\r\n\r\n  constructor(options: StreamControllerOptions) {\r\n    this.options = {\r\n      outputFormat: \"ndjson\",\r\n      progressBatchSize: 1000,\r\n      autoPause: true,\r\n      ...options,\r\n    };\r\n\r\n    // Create appropriate splitter for output format\r\n    this.splitter = createSplitter(this.options.outputFormat!, this.options);\r\n  }\r\n\r\n  /**\r\n   * Process a stream/URL/File/Blob and invoke callbacks for each record\r\n   */\r\n  async process(input: BrowserStreamInput): Promise<void> {\r\n    try {\r\n      // Convert input to ReadableStream\r\n      const stream = await this.inputToStream(input);\r\n\r\n      // Create ConvertBuddy instance\r\n      this.buddy = await ConvertBuddy.create({\r\n        ...this.options,\r\n        profile: true, // Enable stats for progress tracking\r\n      });\r\n\r\n      // Get reader\r\n      this.reader = stream.getReader();\r\n\r\n      // Process stream\r\n      await this.processStream();\r\n\r\n    } finally {\r\n      // Cleanup\r\n      if (this.reader) {\r\n        try {\r\n          await this.reader.cancel();\r\n        } catch (e) {\r\n          // Ignore cancel errors\r\n        }\r\n        this.reader = null;\r\n      }\r\n      this.buddy = null;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Convert various input types to ReadableStream\r\n   */\r\n  private async inputToStream(input: BrowserStreamInput): Promise<ReadableStream<Uint8Array>> {\r\n    if (typeof input === \"string\") {\r\n      // URL\r\n      if (input.startsWith(\"http://\") || input.startsWith(\"https://\")) {\r\n        const response = await fetch(input);\r\n        if (!response.ok) {\r\n          throw new Error(`Failed to fetch ${input}: ${response.statusText}`);\r\n        }\r\n        if (!response.body) {\r\n          throw new Error(\"Response body is null\");\r\n        }\r\n        return response.body;\r\n      } else {\r\n        // Raw string data\r\n        const encoder = new TextEncoder();\r\n        const bytes = encoder.encode(input);\r\n        return new ReadableStream({\r\n          start(controller) {\r\n            controller.enqueue(bytes);\r\n            controller.close();\r\n          },\r\n        });\r\n      }\r\n    } else if (typeof ReadableStream !== \"undefined\" && input instanceof ReadableStream) {\r\n      return input;\r\n    } else if ((typeof Blob !== \"undefined\" && input instanceof Blob) || \r\n               (typeof File !== \"undefined\" && input instanceof File)) {\r\n      return (input as Blob | File).stream() as ReadableStream<Uint8Array>;\r\n    } else {\r\n      throw new Error(\"Unsupported input type for BrowserStreamController\");\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Process the stream chunk by chunk\r\n   */\r\n  private async processStream(): Promise<void> {\r\n    if (!this.buddy || !this.reader) {\r\n      throw new Error(\"Stream not initialized\");\r\n    }\r\n\r\n    try {\r\n      while (true) {\r\n        // Check if aborted\r\n        if (this.aborted) {\r\n          this.buddy.abort();\r\n          break;\r\n        }\r\n\r\n        // Wait while paused\r\n        while (this.paused && !this.aborted) {\r\n          await new Promise((resolve) => setTimeout(resolve, 100));\r\n        }\r\n\r\n        // Read next chunk\r\n        const { done, value } = await this.reader!.read();\r\n\r\n        if (done) {\r\n          // Finish conversion and process final output\r\n          const finalOutput = this.buddy.finish();\r\n          if (finalOutput.length > 0) {\r\n            await this.processOutput(finalOutput);\r\n          }\r\n\r\n          // Flush splitter\r\n          const finalRecords = this.splitter.flush();\r\n          for (const record of finalRecords) {\r\n            await this.invokeRecordCallback(record);\r\n          }\r\n\r\n          break;\r\n        }\r\n\r\n        // Push chunk to ConvertBuddy with record parsing\r\n        const needsRecords = !!this.options.onRecord;\r\n        const result = this.buddy.pushWithRecords(value, needsRecords);\r\n\r\n        // Process output if any\r\n        if (typeof result === 'object' && 'output' in result) {\r\n          // Dual output with records\r\n          if (result.output.length > 0) {\r\n            await this.processOutput(result.output, result.records);\r\n          }\r\n        } else if (result.length > 0) {\r\n          // Fallback: just bytes\r\n          await this.processOutput(result);\r\n        }\r\n      }\r\n    } catch (error) {\r\n      if (this.aborted) {\r\n        // Ignore errors after abort\r\n        return;\r\n      }\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Process output bytes and split into records\r\n   */\r\n  private async processOutput(output: Uint8Array, wasmRecords?: any[]): Promise<void> {\r\n    // Call onData callback with raw bytes if provided\r\n    if (this.options.onData) {\r\n      this.options.onData(output);\r\n    }\r\n\r\n    // Use WASM-parsed records if available, otherwise use TypeScript splitter\r\n    const records = wasmRecords && wasmRecords.length > 0 ? wasmRecords : this.splitter.push(output);\r\n\r\n    // Process each record\r\n    for (const record of records) {\r\n      if (this.aborted) break;\r\n\r\n      await this.invokeRecordCallback(record);\r\n\r\n      // Check progress callback\r\n      if (\r\n        this.options.onStreamProgress &&\r\n        this.recordCount % (this.options.progressBatchSize || 1000) === 0\r\n      ) {\r\n        const stats = this.buddy!.stats();\r\n        this.options.onStreamProgress(stats, this.recordCount);\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Invoke the onRecord callback with proper backpressure handling\r\n   */\r\n  private async invokeRecordCallback(record: any): Promise<void> {\r\n    if (!this.options.onRecord) {\r\n      this.recordCount++;\r\n      return;\r\n    }\r\n\r\n    try {\r\n      // Call the callback\r\n      const result = this.options.onRecord(record, this.recordCount);\r\n\r\n      // If autoPause is enabled and callback returns a Promise, wait for it\r\n      if (this.options.autoPause && result instanceof Promise) {\r\n        const shouldContinue = await result;\r\n        \r\n        // If callback returns false, pause\r\n        if (shouldContinue === false) {\r\n          this.pause();\r\n        }\r\n      } else if (result === false) {\r\n        // If callback returns false synchronously, pause\r\n        this.pause();\r\n      }\r\n\r\n      this.recordCount++;\r\n    } catch (error) {\r\n      console.error(\"[BrowserStreamController] Error in onRecord callback:\", error);\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Pause the stream processing\r\n   */\r\n  pause(): void {\r\n    this.paused = true;\r\n    if (this.buddy) {\r\n      this.buddy.pause();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Resume the stream processing\r\n   */\r\n  resume(): void {\r\n    this.paused = false;\r\n    if (this.buddy) {\r\n      this.buddy.resume();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Abort the stream processing\r\n   */\r\n  abort(): void {\r\n    this.aborted = true;\r\n    if (this.buddy) {\r\n      this.buddy.abort();\r\n    }\r\n    if (this.reader) {\r\n      this.reader.cancel().catch(() => {\r\n        // Ignore cancel errors\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get current statistics\r\n   */\r\n  stats(): Stats | null {\r\n    return this.buddy ? this.buddy.stats() : null;\r\n  }\r\n\r\n  /**\r\n   * Get current record count\r\n   */\r\n  getRecordCount(): number {\r\n    return this.recordCount;\r\n  }\r\n\r\n  /**\r\n   * Check if processing is paused\r\n   */\r\n  isPaused(): boolean {\r\n    return this.paused;\r\n  }\r\n\r\n  /**\r\n   * Check if processing is aborted\r\n   */\r\n  isAborted(): boolean {\r\n    return this.aborted;\r\n  }\r\n}\r\n\r\n/**\r\n * Convenience function to process a stream with a simple callback\r\n * \r\n * @example\r\n * ```ts\r\n * await processStream('/data.csv', {\r\n *   inputFormat: 'csv',\r\n *   outputFormat: 'ndjson',\r\n *   onRecord: (record) => console.log(record),\r\n * });\r\n * ```\r\n */\r\nexport async function processStream(\r\n  input: BrowserStreamInput,\r\n  options: StreamControllerOptions\r\n): Promise<void> {\r\n  const controller = new BrowserStreamController(options);\r\n  await controller.process(input);\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/browser.d.ts

@@ -1,209 +1,30 @@
-import { ConvertBuddyOptions, ConvertOptions, Format } from './browser-core.js';
-export { Coerce, ConvertBuddy, ConvertBuddyTransformStream, Converter, CsvConfig, CsvDetection, DetectInput, DetectOptions, FieldMap, JsonDetection, NdjsonDetection, ProgressCallback, Stats, StructureDetection, TransformConfig, TransformMode, XmlConfig, XmlDetection, autoDetectConfig, convertAny, convertAnyToString, detectCsvFieldsAndDelimiter, detectFormat, detectStructure, detectXmlElements, getExtension, getFileTypeConfig, getMimeType, getSuggestedFilename } from './browser-core.js';
+import { C as ConvertOptions, F as Format } from './index-BpUN6Tdz.js';
+export { G as CSVSplitter, f as Coerce, j as ConvertBuddy, a as ConvertBuddyOptions, p as ConvertBuddyTransformStream, j as Converter, d as CsvConfig, b as CsvDetection, D as DetectInput, c as DetectOptions, g as FieldMap, H as JSONSplitter, J as JsonDetection, E as NDJSONSplitter, N as NdjsonDetection, B as ParsedRecord, P as ProgressCallback, i as Stats, A as StreamControllerOptions, S as StructureDetection, h as TransformConfig, T as TransformMode, I as XMLSplitter, e as XmlConfig, X as XmlDetection, o as autoDetectConfig, q as convertAny, r as convertAnyToString, K as createSplitter, m as detectCsvFieldsAndDelimiter, k as detectFormat, l as detectStructure, n as detectXmlElements, t as getExtension, s as getMimeType, x as getOptimalThreadCount, u as getSuggestedFilename, y as getThreadingInfo, w as isWasmThreadingSupported } from './index-BpUN6Tdz.js';
+export { BrowserStreamController, BrowserStreamInput, processStream } from './browser-stream-controller.js';
 
 /**
- * Browser-only entry point for convert-buddy-js
- * This module is designed to work in any browser environment, including StackBlitz
- * WITHOUT requiring WebContainers or special worker thread support.
- *
- * Key differences from the main entry point:
- * - No Node.js code paths (no worker_threads, no fs, no path)
- * - Browser-optimized WASM loading
- * - Web Worker functionality is optional and gracefully degrades
+ * Browser entry point for convert-buddy-js
+ * Re-exports the main API but optimized for browser environments
  */
 
-type BrowserConvertOptions = ConvertBuddyOptions & {};
 /**
- * Ultra-simple convert function for browser.
- * Auto-detects input type (File, URL, string, etc.) and format.
- *
- * @example
- * // From File
- * const file = fileInput.files[0];
- * const result = await convert(file, { outputFormat: "json" });
- *
- * @example
- * // From URL
- * const result = await convert("https://example.com/data.csv", { outputFormat: "json" });
- *
- * @example
- * // From string
- * const result = await convert(csvString, { outputFormat: "json" });
- */
-declare function convert(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<Uint8Array>;
-/**
- * Ultra-simple convert function that returns a string.
- *
- * @example
- * const json = await convertToString(file, { outputFormat: "json" });
- * console.log(JSON.parse(json));
+ * Browser-optimized convert function for strings
  */
 declare function convertToString(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<string>;
 /**
- * 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));
- * }
+ * Browser-optimized convert function for bytes
  */
-declare function convertFileStream(file: File | Blob, opts?: BrowserConvertOptions): Promise<ReadableStream<Uint8Array>>;
-/**
- * Auto-detect format and create a ReadableStream for conversion.
- * This is a convenience helper that combines format detection with streaming conversion.
- *
- * @example
- * const file = fileInput.files[0];
- * const stream = await autoConvertStream(file, { outputFormat: "json" });
- *
- * // Pipe to response
- * return new Response(stream);
- */
-declare function autoConvertStream(file: File | Blob, opts: Omit<BrowserConvertOptions, "inputFormat"> & {
-    outputFormat: Format;
-}): Promise<ReadableStream<Uint8Array>>;
-/**
- * Stream a file conversion directly to a writable destination.
- * This is useful for streaming large conversions to disk using File System Access API
- * or to other writable streams.
- *
- * @example
- * // Using File System Access API
- * const fileInput = document.querySelector('input[type="file"]');
- * const file = fileInput.files[0];
- *
- * const fileHandle = await window.showSaveFilePicker({
- *   suggestedName: "output.json",
- *   types: [{ description: "JSON", accept: { "application/json": [".json"] } }]
- * });
- * const writable = await fileHandle.createWritable();
- *
- * await convertStreamToWritable(file, writable, {
- *   inputFormat: "csv",
- *   outputFormat: "json",
- *   onProgress: (stats) => console.log(`${stats.bytesIn} bytes processed`)
- * });
- */
-declare function convertStreamToWritable(file: File | Blob, writable: WritableStream<Uint8Array> | FileSystemWritableFileStream, opts?: BrowserConvertOptions): Promise<void>;
-/**
- * Check if File System Access API is supported in the current browser.
- * Use this to determine if you can use File System Access API features.
- *
- * @example
- * if (isFileSystemAccessSupported()) {
- *   // Use File System Access API
- *   const handle = await window.showSaveFilePicker();
- * } else {
- *   // Fall back to download link
- *   await convertFileToFile(file, "output.json", opts);
- * }
- */
-declare function isFileSystemAccessSupported(): boolean;
-/**
- * Convert a file and save it using File System Access API with a user-selected location.
- * This provides a better UX than automatic downloads by letting users choose where to save.
- * Falls back to regular download if File System Access API is not supported.
- *
- * @example
- * const file = fileInput.files[0];
- * await convertAndSave(file, {
- *   inputFormat: "csv",
- *   outputFormat: "json",
- *   suggestedName: "output.json"
- * });
- */
-declare function convertAndSave(file: File | Blob, opts?: BrowserConvertOptions & {
-    suggestedName?: string;
-}): Promise<void>;
+declare function convert(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<Uint8Array>;
 /**
- * Stream a File/Blob conversion in a Web Worker with progress updates.
- *
- * NOTE: This function requires Web Worker support and may not work in all environments
- * (e.g., StackBlitz without WebContainers). For maximum compatibility, use the
- * non-worker versions: convertFile(), convertFileStream(), etc.
- *
- * @param file File or Blob to convert
- * @param opts Convert options (inputFormat, outputFormat, etc)
- * @param onProgress Callback for progress updates
- * @returns Promise<Uint8Array> with the converted result
+ * Convert a browser File or Blob and trigger download of the result
  */
-declare function streamProcessFileInWorker(file: File | Blob, opts?: BrowserConvertOptions, onProgress?: (progress: {
-    bytesRead: number;
-    bytesWritten: number;
-    percentComplete: number;
-    recordsProcessed: number;
-}) => void): Promise<Uint8Array>;
+declare function convertFileToFile(inputFile: File | Blob, outputFilename: string, opts: ConvertOptions): Promise<void>;
 /**
- * Stream a File/Blob conversion in a Web Worker and pipe output to a Writable.
- * This is useful for saving directly to disk using File System Access API.
- *
- * NOTE: This function requires Web Worker support and may not work in all environments.
- * For maximum compatibility, use convertStreamToWritable() instead.
+ * Get file type configuration for browser file pickers
  */
-declare function streamProcessFileInWorkerToWritable(file: File | Blob, writable: WritableStream<Uint8Array> | FileSystemWritableFileStream, opts?: BrowserConvertOptions, onProgress?: (progress: {
-    bytesRead: number;
-    bytesWritten: number;
-    percentComplete: number;
-    recordsProcessed: number;
-}) => void): Promise<void>;
+declare function getFileTypeConfig(format: Format): Array<{
+    description: string;
+    accept: Record<string, string[]>;
+}>;
 
-export { type BrowserConvertOptions, ConvertBuddyOptions, ConvertOptions, Format, autoConvertStream, convert, convertAndSave, convertFile, convertFileStream, convertFileToFile, convertFileToString, convertStreamToWritable, convertToString, isFileSystemAccessSupported, streamProcessFileInWorker, streamProcessFileInWorkerToWritable };
+export { ConvertOptions, Format, convert, convertFileToFile, convertToString, getFileTypeConfig };