convert-buddy-js 0.10.18 → 0.11.1

package/dist/index.d.ts

@@ -1,271 +1 @@
-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;
-    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 Coerce, ConvertBuddy, type ConvertBuddyOptions, ConvertBuddyTransformStream, type ConvertOptions, Converter, type CsvConfig, type CsvDetection, type DetectInput, type DetectOptions, type FieldMap, type Format, type JsonDetection, type NdjsonDetection, type ProgressCallback, type Stats, type StructureDetection, type TransformConfig, type TransformMode, type XmlConfig, type XmlDetection, autoDetectConfig, convert, convertAny, convertAnyToString, convertToString, detectCsvFieldsAndDelimiter, detectFormat, detectStructure, detectXmlElements, getExtension, getFileTypeConfig, getMimeType, getOptimalThreadCount, getSuggestedFilename, getThreadingInfo, isWasmThreadingSupported };
+export { f as Coerce, j as ConvertBuddy, a as ConvertBuddyOptions, p as ConvertBuddyTransformStream, C as ConvertOptions, z as Converter, d as CsvConfig, b as CsvDetection, D as DetectInput, c as DetectOptions, g as FieldMap, F as Format, J as JsonDetection, N as NdjsonDetection, B as ParsedRecord, P as ProgressCallback, i as Stats, A as StreamControllerOptions, S as StructureDetection, h as TransformConfig, T as TransformMode, e as XmlConfig, X as XmlDetection, o as autoDetectConfig, L as convert, q as convertAny, r as convertAnyToString, M as convertToString, m as detectCsvFieldsAndDelimiter, k as detectFormat, l as detectStructure, n as detectXmlElements, t as getExtension, v as getFileTypeConfig, s as getMimeType, x as getOptimalThreadCount, u as getSuggestedFilename, y as getThreadingInfo, w as isWasmThreadingSupported } from './index-BpUN6Tdz.js';

package/dist/index.js

@@ -604,6 +604,40 @@ class ConvertBuddy {
     }
     return output;
   }
+  /**
+   * 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, includeRecords = true) {
+    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] pushWithRecords", chunk.byteLength, "includeRecords:", includeRecords);
+    if (typeof this.converter.pushWithRecords === "function") {
+      const result = this.converter.pushWithRecords(chunk, includeRecords);
+      if (this.onProgress) {
+        const stats = this.stats();
+        if (stats.bytesIn - this.lastProgressBytes >= this.progressIntervalBytes) {
+          this.onProgress(stats);
+          this.lastProgressBytes = stats.bytesIn;
+        }
+      }
+      return result;
+    } else {
+      const output = this.push(chunk);
+      if (includeRecords) {
+        return { output, records: [] };
+      }
+      return output;
+    }
+  }
   finish() {
     if (this.aborted) {
       throw new Error("Conversion has been aborted");