convert-buddy-js 0.10.18 → 0.11.1

package/dist/index-BpUN6Tdz.d.ts

@@ -0,0 +1,440 @@
+/**
+ * StreamController: High-level streaming API for ConvertBuddy
+ *
+ * Provides per-record callbacks, backpressure management, and pause/resume/abort
+ * controls for both browser and Node.js environments.
+ */
+
+/**
+ * Options for StreamController
+ */
+interface StreamControllerOptions extends Omit<ConvertBuddyOptions, 'onProgress'> {
+    /**
+     * Called with raw converted bytes before parsing into records.
+     * Useful for capturing the actual output format (CSV, XML, etc.)
+     */
+    onData?: (bytes: Uint8Array) => void;
+    /**
+     * Called for each parsed record (object) from the output stream.
+     * If the callback returns a Promise, the controller will await it before processing the next record.
+     * Return false to pause the stream (can resume later with resume()).
+     */
+    onRecord?: (record: any, index: number) => void | Promise<void> | boolean | Promise<boolean>;
+    /**
+     * Called periodically with statistics and record count.
+     * Use progressBatchSize to control how often this is called (every N records).
+     * This is different from ConvertBuddyOptions.onProgress which only provides stats.
+     */
+    onStreamProgress?: (stats: Stats, recordCount: number) => void;
+    /**
+     * Number of records to process before triggering onStreamProgress callback.
+     * Default: 1000
+     */
+    progressBatchSize?: number;
+    /**
+     * Auto-pause the stream while onRecord callback is executing.
+     * Default: true
+     */
+    autoPause?: boolean;
+    /**
+     * Output format for conversion. Recommended: "ndjson" for per-record streaming.
+     * Default: "ndjson"
+     */
+    outputFormat?: Format;
+}
+/**
+ * Represents a parsed record with metadata
+ */
+interface ParsedRecord {
+    record: any;
+    index: number;
+}
+/**
+ * NDJSONSplitter - Splits a stream of bytes into complete NDJSON lines
+ *
+ * Handles partial lines across chunk boundaries and yields complete JSON objects.
+ * Optimized with pre-allocated growing buffer to avoid O(n²) allocations.
+ */
+declare class NDJSONSplitter {
+    private buffer;
+    private bufferUsed;
+    private bufferCapacity;
+    private decoder;
+    constructor(initialCapacity?: number);
+    /**
+     * Push a chunk of bytes and get complete records
+     * @param chunk - Chunk of bytes to process
+     * @returns Array of parsed records
+     */
+    push(chunk: Uint8Array): any[];
+    /**
+     * Flush remaining buffer and get final records
+     * @returns Array of parsed records from remaining buffer
+     */
+    flush(): any[];
+    /**
+     * Reset the splitter state
+     */
+    reset(): void;
+}
+/**
+ * CSVSplitter - Splits CSV output into lines
+ *
+ * For CSV output, we yield each line as a string (header + data rows).
+ */
+declare class CSVSplitter {
+    private buffer;
+    private decoder;
+    /**
+     * Push a chunk of bytes and get complete CSV lines
+     */
+    push(chunk: Uint8Array): string[];
+    /**
+     * Flush remaining buffer and get final lines
+     */
+    flush(): string[];
+    /**
+     * Reset the splitter state
+     */
+    reset(): void;
+}
+/**
+ * JSONSplitter - Handles JSON array output
+ *
+ * For JSON output, we expect an array of objects. We'll parse the complete
+ * JSON once and yield all records.
+ */
+declare class JSONSplitter {
+    private buffer;
+    private decoder;
+    private yielded;
+    /**
+     * Push a chunk of bytes and accumulate
+     */
+    push(chunk: Uint8Array): any[];
+    /**
+     * Flush and parse complete JSON
+     */
+    flush(): any[];
+    /**
+     * Reset the splitter state
+     */
+    reset(): void;
+}
+/**
+ * XMLSplitter - Handles XML output by splitting on record elements
+ *
+ * This is a simplified splitter that looks for complete XML elements.
+ * For more robust XML parsing, consider using a proper XML parser.
+ */
+declare class XMLSplitter {
+    private buffer;
+    private decoder;
+    private recordElement;
+    constructor(recordElement?: string);
+    /**
+     * Push a chunk of bytes and extract complete XML elements
+     */
+    push(chunk: Uint8Array): any[];
+    /**
+     * Very basic XML to JSON converter (for demonstration)
+     * In production, use a proper XML parser library
+     */
+    private xmlToJson;
+    /**
+     * Flush remaining buffer
+     */
+    flush(): any[];
+    /**
+     * Reset the splitter state
+     */
+    reset(): void;
+}
+/**
+ * Factory function to create appropriate splitter based on output format
+ */
+declare function createSplitter(outputFormat: Format, config?: any): NDJSONSplitter | CSVSplitter | JSONSplitter | XMLSplitter;
+
+type Format = "csv" | "ndjson" | "json" | "xml";
+type DetectInput = Uint8Array | ArrayBuffer | string | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+type CsvDetection = {
+    delimiter: string;
+    fields: string[];
+};
+type XmlDetection = {
+    elements: string[];
+    recordElement?: string;
+};
+type JsonDetection = {
+    fields: string[];
+};
+type NdjsonDetection = {
+    fields: string[];
+};
+type StructureDetection = {
+    format: Format;
+    fields: string[];
+    delimiter?: string;
+    recordElement?: string;
+};
+type DetectOptions = {
+    maxBytes?: number;
+    debug?: boolean;
+};
+type ProgressCallback = (stats: Stats) => void;
+type ConvertBuddyOptions = {
+    debug?: boolean;
+    profile?: boolean;
+    inputFormat?: Format | "auto";
+    outputFormat?: Format;
+    chunkTargetBytes?: number;
+    parallelism?: number;
+    maxMemoryMB?: number;
+    csvConfig?: CsvConfig;
+    xmlConfig?: XmlConfig;
+    transform?: TransformConfig;
+    onProgress?: ProgressCallback;
+    progressIntervalBytes?: number;
+};
+type ConvertOptions = {
+    inputFormat?: Format | "auto";
+    outputFormat: Format;
+    csvConfig?: CsvConfig;
+    xmlConfig?: XmlConfig;
+    transform?: TransformConfig;
+    onProgress?: ProgressCallback;
+};
+type CsvConfig = {
+    delimiter?: string;
+    quote?: string;
+    hasHeaders?: boolean;
+    trimWhitespace?: boolean;
+};
+type XmlConfig = {
+    recordElement?: string;
+    trimText?: boolean;
+    includeAttributes?: boolean;
+    expandEntities?: boolean;
+};
+type TransformMode = "replace" | "augment";
+type Coerce = {
+    type: "string";
+} | {
+    type: "i64";
+} | {
+    type: "f64";
+} | {
+    type: "bool";
+} | {
+    type: "timestamp_ms";
+    format?: "iso8601" | "unix_ms" | "unix_s";
+};
+type FieldMap = {
+    targetFieldName: string;
+    originFieldName?: string;
+    required?: boolean;
+    defaultValue?: string | number | boolean | null;
+    coerce?: Coerce;
+    compute?: string;
+};
+type TransformConfig = {
+    mode?: TransformMode;
+    fields: FieldMap[];
+    onMissingField?: "error" | "null" | "drop";
+    onMissingRequired?: "error" | "abort";
+    onCoerceError?: "error" | "null" | "dropRecord";
+};
+type Stats = {
+    bytesIn: number;
+    bytesOut: number;
+    chunksIn: number;
+    recordsProcessed: number;
+    parseTimeMs: number;
+    transformTimeMs: number;
+    writeTimeMs: number;
+    maxBufferSize: number;
+    currentPartialSize: number;
+    throughputMbPerSec: number;
+};
+declare class ConvertBuddy {
+    private converter;
+    private debug;
+    private profile;
+    private aborted;
+    private paused;
+    private onProgress?;
+    private progressIntervalBytes;
+    private lastProgressBytes;
+    private globalConfig;
+    private initialized;
+    simd: boolean;
+    /**
+     * Create a new ConvertBuddy instance with global configuration.
+     * This is useful when you want to set memory limits, debug mode, or other global settings.
+     *
+     * @example
+     * const buddy = new ConvertBuddy({ maxMemoryMB: 512, debug: true });
+     * const result = await buddy.convert(input, { outputFormat: "json" });
+     */
+    constructor(opts?: ConvertBuddyOptions);
+    /**
+     * Convert input (string, Buffer, File, URL, etc.) to the desired output format.
+     * This is the main method for the new simplified API.
+     *
+     * @example
+     * // Auto-detect everything
+     * const buddy = new ConvertBuddy();
+     * const result = await buddy.convert("https://example.com/data.csv", { outputFormat: "json" });
+     *
+     * @example
+     * // With configuration
+     * const buddy = new ConvertBuddy({ maxMemoryMB: 512 });
+     * const result = await buddy.convert(file, { inputFormat: "csv", outputFormat: "json" });
+     */
+    convert(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<Uint8Array>;
+    private convertFromUrl;
+    private convertFromString;
+    private convertFromBuffer;
+    private convertFromBufferParallel;
+    private convertUsingNodejsThreadPool;
+    private convertUsingWasmThreadPool;
+    private convertUsingJsParallelism;
+    private splitIntoChunks;
+    private convertFromFile;
+    private convertFromBlob;
+    private convertFromStream;
+    /**
+     * Legacy create method for backward compatibility.
+     * Prefer using the constructor: new ConvertBuddy(opts)
+     */
+    static create(opts?: ConvertBuddyOptions): Promise<ConvertBuddy>;
+    push(chunk: Uint8Array): Uint8Array;
+    /**
+     * Push a chunk and optionally get pre-parsed records.
+     * This is more efficient than parsing the output yourself.
+     *
+     * @param chunk - Input chunk to process
+     * @param includeRecords - If true, returns { output, records }, otherwise just output bytes
+     * @returns Either Uint8Array or { output: Uint8Array, records: any[] }
+     */
+    pushWithRecords(chunk: Uint8Array, includeRecords?: boolean): Uint8Array | {
+        output: Uint8Array;
+        records: any[];
+    };
+    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 detectStructure(input: DetectInput, formatHint?: Format, opts?: DetectOptions): Promise<StructureDetection | null>;
+declare function detectCsvFieldsAndDelimiter(input: DetectInput, opts?: DetectOptions): Promise<CsvDetection | null>;
+declare function detectXmlElements(input: DetectInput, opts?: DetectOptions): Promise<XmlDetection | null>;
+declare function autoDetectConfig(input: DetectInput, opts?: DetectOptions): Promise<{
+    format: Format | "unknown";
+    csvConfig?: CsvConfig;
+    xmlConfig?: XmlConfig;
+}>;
+declare class ConvertBuddyTransformStream extends TransformStream<Uint8Array, Uint8Array> {
+    constructor(opts?: ConvertBuddyOptions);
+}
+declare function convert(input: Uint8Array | string, opts?: ConvertBuddyOptions): Promise<Uint8Array>;
+declare function convertToString(input: Uint8Array | string, opts?: ConvertBuddyOptions): Promise<string>;
+/**
+ * Ultra-simple standalone convert function with auto-detection.
+ * Accepts any input type (URL, File, Buffer, string, stream) and automatically detects format.
+ *
+ * @example
+ * // From URL
+ * import { convertAny } from "convert-buddy-js";
+ * const result = await convertAny("https://example.com/data.csv", { outputFormat: "json" });
+ *
+ * @example
+ * // From File (browser)
+ * const file = fileInput.files[0];
+ * const result = await convertAny(file, { outputFormat: "ndjson" });
+ *
+ * @example
+ * // From string data
+ * const result = await convertAny('{"name":"Ada"}', { outputFormat: "csv" });
+ */
+declare function convertAny(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<Uint8Array>;
+/**
+ * Ultra-simple standalone convert function that returns a string.
+ * Same as convertAny but decodes the output to a string.
+ *
+ * @example
+ * import { convertAnyToString } from "convert-buddy-js";
+ * const json = await convertAnyToString("https://example.com/data.csv", { outputFormat: "json" });
+ * console.log(JSON.parse(json));
+ */
+declare function convertAnyToString(input: string | Uint8Array | File | Blob | ReadableStream<Uint8Array>, opts: ConvertOptions): Promise<string>;
+/**
+ * Get MIME type for a given format
+ *
+ * @example
+ * const mimeType = getMimeType("json"); // "application/json"
+ */
+declare function getMimeType(format: Format): string;
+/**
+ * Get file extension for a given format (without the dot)
+ *
+ * @example
+ * const ext = getExtension("json"); // "json"
+ */
+declare function getExtension(format: Format): string;
+/**
+ * Get suggested filename for a converted file
+ *
+ * @param originalName - Original filename
+ * @param outputFormat - Target format
+ * @param includeTimestamp - Whether to include a timestamp (default: false)
+ *
+ * @example
+ * const name = getSuggestedFilename("data.csv", "json"); // "data.json"
+ * const name = getSuggestedFilename("data.csv", "json", true); // "data_converted_1234567890.json"
+ */
+declare function getSuggestedFilename(originalName: string, outputFormat: Format, includeTimestamp?: boolean): string;
+/**
+ * Get File System Access API file type configuration for showSaveFilePicker
+ *
+ * @example
+ * const types = getFileTypeConfig("json");
+ * const handle = await showSaveFilePicker({ types });
+ */
+declare function getFileTypeConfig(format: Format): Array<{
+    description: string;
+    accept: Record<string, string[]>;
+}>;
+/**
+ * Check if WASM threading is supported in the current environment
+ * @returns true if SharedArrayBuffer and Atomics are available (required for WASM threads)
+ */
+declare function isWasmThreadingSupported(): boolean;
+/**
+ * Get the optimal number of worker threads based on CPU cores and WASM capabilities
+ * @returns Recommended thread count for optimal performance
+ */
+declare function getOptimalThreadCount(): number;
+/**
+ * Get current threading capabilities and configuration
+ * @returns Object with threading information
+ */
+declare function getThreadingInfo(): {
+    wasmThreadingSupported: boolean;
+    customThreadPoolAvailable: boolean;
+    nodejsWasmThreading: boolean;
+    recommendedThreads: number;
+    currentThreads: number;
+    approach: string;
+};
+/**
+ * Backward compatibility alias for ConvertBuddy
+ * @deprecated Use ConvertBuddy instead
+ */
+declare const Converter: typeof ConvertBuddy;
+
+export { type StreamControllerOptions as A, type ParsedRecord as B, type ConvertOptions as C, type DetectInput as D, NDJSONSplitter as E, type Format as F, CSVSplitter as G, JSONSplitter as H, XMLSplitter as I, type JsonDetection as J, createSplitter as K, convert as L, convertToString as M, type NdjsonDetection as N, type ProgressCallback as P, type StructureDetection as S, type TransformMode as T, type XmlDetection as X, type ConvertBuddyOptions as a, type CsvDetection as b, type DetectOptions as c, type CsvConfig as d, type XmlConfig as e, type Coerce as f, type FieldMap as g, type TransformConfig as h, type Stats as i, ConvertBuddy as j, detectFormat as k, detectStructure as l, detectCsvFieldsAndDelimiter as m, detectXmlElements as n, autoDetectConfig as o, ConvertBuddyTransformStream as p, convertAny as q, convertAnyToString as r, getMimeType as s, getExtension as t, getSuggestedFilename as u, getFileTypeConfig as v, isWasmThreadingSupported as w, getOptimalThreadCount as x, getThreadingInfo as y, Converter as z };