web-csv-toolbox - v0.14.0
    Preparing search index...

    Interface WorkerEngineConfig

    Engine configuration for worker thread execution.

    interface WorkerEngineConfig {
        arrayBufferThreshold?: number;
        backpressureCheckInterval?: BackpressureCheckInterval;
        onFallback?: (info: EngineFallbackInfo) => void;
        queuingStrategy?: QueuingStrategyConfig;
        strict?: boolean;
        wasm?: boolean;
        worker: true;
        workerPool?: WorkerPool;
        workerStrategy?: WorkerCommunicationStrategy;
        workerURL?: string | URL;
    }

    Hierarchy

    • BaseEngineConfig
      • WorkerEngineConfig
    Index

    Properties

    arrayBufferThreshold? backpressureCheckInterval? onFallback? queuingStrategy? strict? wasm? worker workerPool? workerStrategy? workerURL?

    Properties

    arrayBufferThreshold?: number

    Blob reading strategy threshold (in bytes). Only applicable for parseBlob() and parseFile().

    Determines when to use blob.arrayBuffer() vs blob.stream():

    • Files smaller than threshold: Use blob.arrayBuffer() + parseBinary()
      • ✅ Faster for small files
      • ❌ Loads entire file into memory
    • Files equal to or larger than threshold: Use blob.stream() + parseBinaryStream()
      • ✅ Memory-efficient for large files
      • ❌ Slight streaming overhead
    1_048_576 (1MB)
    backpressureCheckInterval?: BackpressureCheckInterval

    Backpressure monitoring intervals (count-based: number of tokens/records processed).

    { lexer: 100, assembler: 10 }
    @experimental
    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
          });
        }
      }
    })
    queuingStrategy?: QueuingStrategyConfig

    Internal streaming queuing strategies.

    strict?: boolean

    Strict mode: disable automatic fallback.

    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.

    WASM module is automatically initialized on first use. However, it is recommended to call loadWASM beforehand for better performance.

    false

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

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

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

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

    Execute in Worker thread.

    workerPool?: WorkerPool

    Worker pool for managing worker lifecycle.

    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.

    • "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.

    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