convert-buddy-js 0.9.5 → 0.9.6

package/README.md

@@ -1,3 +1,5 @@
+> ⚠️ **In Development** - This project is currently under active development and subject to breaking changes. Experimental state, could change heavily.
+
 # convert-buddy-js
 
 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.
@@ -18,6 +20,51 @@ npm install convert-buddy-js
 
 ## Quick Start
 
+### The Simplest Way - Auto-Detect Everything
+
+```ts
+import { convert, convertToString } from "convert-buddy-js";
+
+// From URL (auto-detects format)
+const result = await convertToString("https://example.com/data.csv", {
+  outputFormat: "json"
+});
+
+// From File (browser)
+const file = fileInput.files[0];
+const json = await convertToString(file, { outputFormat: "json" });
+
+// From string data
+const csv = "name,age\nAda,36";
+const ndjson = await convertToString(csv, { outputFormat: "ndjson" });
+
+// Returns Uint8Array instead of string
+const bytes = await convert(file, { outputFormat: "json" });
+```
+
+### Instance-Based API with Global Config
+
+```ts
+import { ConvertBuddy } from "convert-buddy-js";
+
+// Create a buddy with global settings
+const buddy = new ConvertBuddy({
+  maxMemoryMB: 512,
+  debug: true,
+  onProgress: (stats) => console.log(`${stats.recordsProcessed} records`)
+});
+
+// Convert anything - URL, File, Buffer, string, stream
+const result = await buddy.convert("https://example.com/data.csv", {
+  outputFormat: "json"
+});
+
+const result2 = await buddy.convert(file, {
+  inputFormat: "csv", // optional, auto-detected if omitted
+  outputFormat: "ndjson"
+});
+```
+
 ### Browser - Convert File Input
 
 ```ts
@@ -37,18 +84,98 @@ fileInput.addEventListener('change', async (e) => {
 ### Node.js - Convert File
 
 ```ts
-import { convertFileToString } from "convert-buddy-js/node";
+import { convert } from "convert-buddy-js/node";
 
-const result = await convertFileToString("input.csv", {
-  inputFormat: "auto",
+// From file path (auto-detects format)
+const result = await convert("input.csv", {
   outputFormat: "json"
 });
-console.log(result);
+
+// From URL
+const result2 = await convert("https://api.example.com/data.csv", {
+  outputFormat: "ndjson"
+});
 ```
 
 ## Usage
 
-### High-Level API (Recommended)
+Convert Buddy offers three API styles, from simplest to most powerful:
+
+### 1. Ultra-Simple API (Recommended for Most Use Cases)
+
+The easiest way to convert data. Just pass anything and specify the output format:
+
+```ts
+import { convert, convertToString } from "convert-buddy-js";
+// Or platform-specific: "convert-buddy-js/browser" or "convert-buddy-js/node"
+
+// Auto-detects input type AND format
+const json = await convertToString(input, { outputFormat: "json" });
+
+// Works with:
+// - URLs: "https://example.com/data.csv"
+// - Files: file from <input type="file">
+// - Buffers: Uint8Array or Buffer
+// - Strings: raw CSV, JSON, XML, NDJSON data
+// - Streams: ReadableStream<Uint8Array>
+// - File paths (Node.js): "path/to/data.csv"
+```
+
+**Examples:**
+
+```ts
+// From URL
+const json = await convertToString("https://example.com/data.csv", {
+  outputFormat: "json"
+});
+
+// From file upload (browser)
+const file = document.querySelector('input[type="file"]').files[0];
+const ndjson = await convertToString(file, { outputFormat: "ndjson" });
+
+// From file path (Node.js)
+import { convertToString } from "convert-buddy-js/node";
+const result = await convertToString("./data.csv", { outputFormat: "json" });
+
+// From string data
+const csvString = "name,age\nAda,36\nLinus,54";
+const json = await convertToString(csvString, { outputFormat: "json" });
+```
+
+### 2. Instance-Based API (For Reusable Configuration)
+
+Create a ConvertBuddy instance with global settings, then convert multiple inputs:
+
+```ts
+import { ConvertBuddy } from "convert-buddy-js";
+
+const buddy = new ConvertBuddy({
+  maxMemoryMB: 512,        // Future: memory limits
+  debug: true,             // Enable debug logging
+  profile: true,           // Show performance stats
+  onProgress: (stats) => {
+    console.log(`${stats.recordsProcessed} records processed`);
+    console.log(`${stats.throughputMbPerSec.toFixed(2)} MB/s`);
+  }
+});
+
+// Convert different inputs with the same config
+const result1 = await buddy.convert("https://example.com/data.csv", {
+  outputFormat: "json"
+});
+
+const result2 = await buddy.convert(file, {
+  outputFormat: "ndjson",
+  csvConfig: { delimiter: ";" } // Override per-conversion
+});
+
+// Decode to string
+const jsonString = new TextDecoder().decode(result1);
+```
+
+### 3. High-Level API (Platform-Specific Helpers)
+
+Platform-specific helpers for common use cases:
 
 #### Browser Helpers
 
@@ -59,7 +186,14 @@ import {
   convertFileToString,
   convertFile,
   convertFileToFile,
-  convertFileStream
+  convertFileStream,
+  convertAndSave,
+  convertStreamToWritable,
+  autoConvertStream,
+  isFileSystemAccessSupported,
+  getMimeType,
+  getExtension,
+  getSuggestedFilename
 } from "convert-buddy-js/browser";
 
 // Convert to string
@@ -68,17 +202,50 @@ const json = await convertFileToString(file, {
   outputFormat: "json"
 });
 
-// Convert and download
+// Convert and download (legacy browser support)
 await convertFileToFile(file, "output.json", {
   inputFormat: "csv",
   outputFormat: "json"
 });
 
+// Convert and save with File System Access API (better UX)
+// User chooses save location, no automatic downloads
+await convertAndSave(file, {
+  inputFormat: "csv",
+  outputFormat: "json",
+  suggestedName: "output.json"
+});
+
+// Auto-detect format and convert
+const stream = await autoConvertStream(file, {
+  outputFormat: "json"
+});
+
+// Stream to File System Access API writable
+if (isFileSystemAccessSupported()) {
+  const handle = await window.showSaveFilePicker({
+    suggestedName: "output.json"
+  });
+  const writable = await handle.createWritable();
+  
+  await convertStreamToWritable(file, writable, {
+    inputFormat: "csv",
+    outputFormat: "json",
+    onProgress: (stats) => console.log(`${stats.bytesIn} bytes processed`)
+  });
+}
+
 // Get streaming API
 const stream = await convertFileStream(file, {
   inputFormat: "csv",
   outputFormat: "ndjson"
 });
+
+// Format helpers
+const mimeType = getMimeType("json"); // "application/json"
+const extension = getExtension("csv"); // "csv"
+const filename = getSuggestedFilename("data.csv", "json"); // "data.json"
+
 ```
 
 #### Node.js Helpers
@@ -112,55 +279,9 @@ const result = await convertStream(inputStream, {
 });
 ```
 
-#### 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
+### 4. Low-Level API (Advanced Use Cases)
 
-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";
-
-const csv = `name,age\nAda,36\nLinus,54`;
-
-const output = await convertToString(csv, {
-  inputFormat: "csv",
-  outputFormat: "ndjson",
-});
-
-console.log(output);
-```
+For maximum control over the conversion process:
 
 #### Manual streaming (chunked)
 
@@ -213,6 +334,155 @@ const response = await fetch("/data.csv");
 const outputStream = response.body?.pipeThrough(transform);
 ```
 
+---
+
+### Additional Features
+
+#### Progress Tracking & Control
+
+Monitor long-running conversions and allow cancellation:
+
+```ts
+import { ConvertBuddy } from "convert-buddy-js";
+
+const buddy = new ConvertBuddy({
+  onProgress: (stats) => {
+    console.log(`${stats.recordsProcessed} records processed`);
+    console.log(`${stats.throughputMbPerSec.toFixed(2)} MB/s`);
+  },
+  progressIntervalBytes: 1024 * 1024 // Every 1MB
+});
+
+const result = await buddy.convert(largeFile, { outputFormat: "json" });
+
+// Or with the low-level API
+const converter = 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
+});
+
+// User cancels
+cancelButton.addEventListener('click', () => converter.abort());
+```
+
+#### Format Utilities
+
+Helper functions for working with file formats, MIME types, and extensions:
+
+```ts
+import { 
+  getMimeType, 
+  getExtension, 
+  getSuggestedFilename,
+  getFileTypeConfig 
+} from "convert-buddy-js";
+
+// Get MIME type for a format
+const mimeType = getMimeType("json"); // "application/json"
+
+// Get file extension
+const ext = getExtension("ndjson"); // "ndjson"
+
+// Generate output filename
+const filename = getSuggestedFilename("data.csv", "json"); 
+// "data.json"
+
+const timestamped = getSuggestedFilename("data.csv", "json", true);
+// "data_converted_1234567890.json"
+
+// Get File System Access API config
+const types = getFileTypeConfig("json");
+// [{ description: "JSON Files", accept: { "application/json": [".json"] } }]
+
+const handle = await window.showSaveFilePicker({
+  suggestedName: "output.json",
+  types
+});
+```
+
+#### Advanced Browser Streaming
+
+For maximum efficiency with large files, use streaming APIs to avoid loading entire files into memory:
+
+```ts
+import { 
+  convertStreamToWritable,
+  autoConvertStream,
+  isFileSystemAccessSupported 
+} from "convert-buddy-js/browser";
+
+// Auto-detect and stream conversion
+const outputStream = await autoConvertStream(file, {
+  outputFormat: "json",
+  onProgress: (stats) => {
+    console.log(`Progress: ${stats.bytesIn} bytes in, ${stats.bytesOut} bytes out`);
+    console.log(`Throughput: ${stats.throughputMbPerSec.toFixed(2)} MB/s`);
+  }
+});
+
+// Stream directly to File System Access API writable
+if (isFileSystemAccessSupported()) {
+  const fileHandle = await window.showSaveFilePicker({
+    suggestedName: "output.json",
+    types: [{ 
+      description: "JSON Files", 
+      accept: { "application/json": [".json"] } 
+    }]
+  });
+  
+  const writable = await fileHandle.createWritable();
+  
+  await convertStreamToWritable(file, writable, {
+    inputFormat: "csv",
+    outputFormat: "json"
+  });
+  
+  console.log("Conversion complete!");
+}
+
+// Or pipe to any WritableStream
+const customWritable = new WritableStream({
+  write(chunk) {
+    // Process each output chunk
+    console.log("Received chunk:", chunk);
+  }
+});
+
+await convertStreamToWritable(file, customWritable, {
+  inputFormat: "auto",
+  outputFormat: "ndjson"
+});
+```
+
+#### Auto-Detection
+
+Auto-detection is enabled by default with the new API. You can also use it explicitly:
+
+```ts
+import { convert } from "convert-buddy-js";
+
+// Automatic (default)
+const result = await convert(input, { outputFormat: "json" });
+
+// Explicit auto-detection
+const result2 = await convert(input, {
+  inputFormat: "auto",
+  outputFormat: "json",
+  csvConfig: { delimiter: "," } // Optional: still apply config
+});
+
+// Or specify the format
+const result3 = await convert(input, {
+  inputFormat: "csv",
+  outputFormat: "json"
+});
+```
+
 #### Detect format and CSV fields/delimiter
 
 Use streaming inputs to keep detection fast on large files.

package/dist/src/browser.d.ts

@@ -1,7 +1,33 @@
-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';
+import { ConvertBuddyOptions, ConvertOptions, Format } from './index.js';
+export { ConvertBuddy, ConvertBuddyTransformStream, CsvConfig, CsvDetection, DetectInput, DetectOptions, ProgressCallback, Stats, XmlConfig, XmlDetection, autoDetectConfig, convertAny, convertAnyToString, detectCsvFieldsAndDelimiter, detectFormat, detectXmlElements, getExtension, getFileTypeConfig, getMimeType, getSuggestedFilename } from './index.js';
 
 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));
+ */
+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.
@@ -70,5 +96,79 @@ declare function convertFileToFile(inputFile: File | Blob, outputFilename: strin
  * }
  */
 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`)
+ * });
+ *
+ * @example
+ * // With auto-detection
+ * await convertStreamToWritable(file, writable, {
+ *   inputFormat: "auto",
+ *   outputFormat: "ndjson"
+ * });
+ */
+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>;
 
-export { type BrowserConvertOptions, ConvertBuddyOptions, convertFile, convertFileStream, convertFileToFile, convertFileToString };
+export { type BrowserConvertOptions, ConvertBuddyOptions, ConvertOptions, Format, autoConvertStream, convert, convertAndSave, convertFile, convertFileStream, convertFileToFile, convertFileToString, convertStreamToWritable, convertToString, isFileSystemAccessSupported };

package/dist/src/browser.js

@@ -1,5 +1,11 @@
-import { ConvertBuddy, autoDetectConfig } from "./index.js";
+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);
@@ -27,6 +33,22 @@ async function convertFile(file, opts = {}) {
       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();
@@ -131,10 +153,52 @@ async function convertFileStream(file, opts = {}) {
     }
   });
 }
+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
+  convertFileToString,
+  convertStreamToWritable,
+  convertToString,
+  isFileSystemAccessSupported
 };
 //# sourceMappingURL=browser.js.map