convert-buddy-js 0.9.4 → 0.9.6

package/README.md

@@ -1,31 +1,289 @@
+> ⚠️ **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.
 
+## 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
+
+### 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
+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 { convert } from "convert-buddy-js/node";
+
+// From file path (auto-detects format)
+const result = await convert("input.csv", {
+  outputFormat: "json"
+});
+
+// From URL
+const result2 = await convert("https://api.example.com/data.csv", {
+  outputFormat: "ndjson"
+});
+```
+
 ## Usage
 
-### Convert a full string or buffer
+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 { convertToString } from "convert-buddy-js";
+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"
+```
 
-const csv = `name,age\nAda,36\nLinus,54`;
+**Examples:**
 
-const output = await convertToString(csv, {
-  inputFormat: "csv",
+```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
 });
 
-console.log(output);
+// Decode to string
+const jsonString = new TextDecoder().decode(result1);
 ```
 
-### Manual streaming (chunked)
+### 3. High-Level API (Platform-Specific Helpers)
+
+Platform-specific helpers for common use cases:
+
+#### Browser Helpers
+
+Simple file conversion without manual buffer handling:
+
+```ts
+import { 
+  convertFileToString,
+  convertFile,
+  convertFileToFile,
+  convertFileStream,
+  convertAndSave,
+  convertStreamToWritable,
+  autoConvertStream,
+  isFileSystemAccessSupported,
+  getMimeType,
+  getExtension,
+  getSuggestedFilename
+} from "convert-buddy-js/browser";
+
+// Convert to string
+const json = await convertFileToString(file, {
+  inputFormat: "csv",
+  outputFormat: "json"
+});
+
+// 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
+
+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"
+});
+```
+
+### 4. Low-Level API (Advanced Use Cases)
+
+For maximum control over the conversion process:
+
+#### Manual streaming (chunked)
 
 ```ts
 import { ConvertBuddy } from "convert-buddy-js";
@@ -42,7 +300,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 +320,7 @@ createReadStream("input.csv")
   .pipe(createWriteStream("output.ndjson"));
 ```
 
-### Web Streams
+#### Web Streams
 
 ```ts
 import { ConvertBuddyTransformStream } from "convert-buddy-js";
@@ -76,7 +334,156 @@ const response = await fetch("/data.csv");
 const outputStream = response.body?.pipeThrough(transform);
 ```
 
-### Detect format and CSV fields/delimiter
+---
+
+### 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

@@ -0,0 +1,174 @@
+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.
+ *
+ * @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>>;
+/**
+ * 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, ConvertOptions, Format, autoConvertStream, convert, convertAndSave, convertFile, convertFileStream, convertFileToFile, convertFileToString, convertStreamToWritable, convertToString, isFileSystemAccessSupported };