web-csv-toolbox
    Preparing search index...

    Interface EngineConfig

    Engine configuration for CSV parsing.

    All parsing engine settings are unified in this interface.

    interface EngineConfig {
        onFallback?: (info: EngineFallbackInfo) => void;
        strict?: boolean;
        wasm?: boolean;
        worker?: boolean;
        workerPool?: WorkerPool;
        workerStrategy?: WorkerCommunicationStrategy;
        workerURL?: string | URL;
    }
    Index

    Properties

    onFallback? strict? wasm? worker? workerPool? workerStrategy? workerURL?

    Properties

    onFallback?: (info: EngineFallbackInfo) => void

    Callback when engine configuration fallback occurs.

    Called when the requested configuration fails and falls back to a safer configuration. Not called if strict: true (throws error instead).

    Common fallback scenario:

    • workerStrategy: "stream-transfer" → "message-streaming" (Safari)
    parse(csv, {
      engine: {
        worker: true,
        workerStrategy: "stream-transfer",
        onFallback: (info) => {
          console.warn(`Fallback occurred: ${info.reason}`);
          analytics.track('engine-fallback', {
            reason: info.reason,
            userAgent: navigator.userAgent
          });
        }
      }
    })
    strict?: boolean

    Strict mode: disable automatic fallback. Only applicable when workerStrategy: "stream-transfer".

    When enabled:

    • Throws error immediately if stream transfer fails
    • Does not fallback to message-streaming
    • onFallback is never called

    When disabled (default):

    • Automatically falls back to message-streaming on failure
    • Calls onFallback if provided
    false

    try {
      parse(csv, {
        engine: {
          worker: true,
          workerStrategy: "stream-transfer",
          strict: true
        }
      })
    } catch (error) {
      // Safari will throw error here
      console.error('Stream transfer not supported:', error);
    }
    wasm?: boolean

    Use WASM implementation.

    Requires prior initialization with loadWASM.

    false

    import { loadWASM, parse } from 'web-csv-toolbox';

    await loadWASM();
    parse(csv, { engine: { wasm: true } })

    await loadWASM();
    parse(csv, { engine: { worker: true, wasm: true } })
    worker?: boolean

    Execute in Worker thread.

    false

    parse(csv, { engine: { worker: true } })
    workerPool?: WorkerPool

    Worker pool for managing worker lifecycle. Only applicable when worker: true.

    When provided, the parsing function will use this pool's worker instance instead of creating/reusing a module-level singleton worker.

    Use WorkerPool with the using syntax for automatic cleanup.

    import { ReusableWorkerPool, parseString } from 'web-csv-toolbox';

    async function processCSV(csv: string) {
      using pool = new ReusableWorkerPool();

      const records = [];
      for await (const record of parseString(csv, {
        engine: { worker: true, workerPool: pool }
      })) {
        records.push(record);
      }

      return records;
      // Worker is automatically terminated when leaving this scope
    }

    import { ReusableWorkerPool, parseString } from 'web-csv-toolbox';

    using pool = new ReusableWorkerPool();

    await parseString(csv1, { engine: { worker: true, workerPool: pool } });
    await parseString(csv2, { engine: { worker: true, workerPool: pool } });
    // Worker is reused for both operations
    workerStrategy?: WorkerCommunicationStrategy

    Worker communication strategy. Only applicable when worker: true.

    • "message-streaming" (default): Message-based streaming

      • ✅ All browsers including Safari
      • ✅ Stable and reliable
      • Records are sent one-by-one via postMessage

    • "stream-transfer": TransferableStreams

      • ✅ Chrome 87+, Firefox 103+, Edge 87+
      • ❌ Safari (not supported, will fallback unless strict mode)
      • ⚡ Zero-copy transfer, more efficient
      • Uses ReadableStream transfer
    "message-streaming"

    https://caniuse.com/mdn-api_readablestream_transferable

    parse(csv, { engine: { worker: true } })
    // or explicitly
    parse(csv, { engine: { worker: true, workerStrategy: "message-streaming" } })

    parse(csv, {
      engine: {
        worker: true,
        workerStrategy: "stream-transfer",
        onFallback: (info) => {
          console.warn(`Fallback to message-streaming: ${info.reason}`);
        }
      }
    })
    workerURL?: string | URL

    Custom Worker URL. Only applicable when worker: true.

    If not provided, uses the bundled worker.

    The custom worker must implement the same message protocol as the bundled worker.

    parse(csv, {
      engine: {
        worker: true,
        workerURL: new URL('./custom-worker.js', import.meta.url)
      }
    })

    Settings

    Member Visibility

    On This Page

    Properties