web-csv-toolbox 0.13.0-next-bd865d6ddb1cf9691d7b9a83d0790651f074dd47 → 0.13.0-next-b21b6d89a7a3f18dcbf79ec04ffefde0d7ff4c4c

package/dist/common/types.d.ts

@@ -184,7 +184,7 @@ export interface BinaryOptions {
      *
      * See {@link https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream#browser_compatibility | DecompressionStream Compatibility}.
      */
-    decomposition?: CompressionFormat;
+    decompression?: CompressionFormat;
     /**
      * You can specify the character encoding of the binary.
      *
@@ -236,15 +236,34 @@ export interface BinaryOptions {
      */
     fatal?: boolean;
     /**
-     * Allow experimental or future compression formats not explicitly supported by this library.
+     * Allow experimental or non-standard compression formats not explicitly supported by this library.
      *
      * @remarks
-     * When `true`, unknown compression formats from Content-Encoding headers will be passed
-     * to the runtime's DecompressionStream without validation. This allows using newer
-     * compression formats (like Brotli) if your runtime supports them, even before this
-     * library is updated to explicitly support them.
+     * When `true`, compression formats from Content-Encoding headers that are not in the
+     * default supported list will be passed to the runtime's DecompressionStream without
+     * validation. This allows using compression formats that may not be universally supported
+     * across all browsers.
      *
-     * When `false` (default), only known formats are allowed: gzip, deflate, deflate-raw.
+     * ### Default Supported Formats (cross-browser compatible)
+     *
+     * When `false` (default), only universally supported formats are allowed:
+     * - **Node.js**: `gzip`, `deflate`, `br` (Brotli)
+     * - **Browsers**: `gzip`, `deflate`
+     *
+     * ### Experimental Formats (require this flag)
+     *
+     * Some compression formats are only supported in specific environments:
+     * - **`deflate-raw`**: Supported in Chromium-based browsers (Chrome, Edge) but may not work
+     *   in Firefox or Safari
+     * - **`br` (Brotli)**: Future browser support may vary
+     * - Other formats: Depends on runtime implementation
+     *
+     * ### Browser Compatibility Notes
+     *
+     * If you enable this option and use `deflate-raw`:
+     * - ✅ Works in Chrome, Edge (Chromium-based)
+     * - ❌ May fail in Firefox, Safari
+     * - Consider implementing fallback logic or detecting browser support at runtime
      *
      * **Use with caution**: Enabling this bypasses library validation and relies entirely
      * on runtime error handling. If the runtime doesn't support the format, you'll get
@@ -254,14 +273,21 @@ export interface BinaryOptions {
      *
      * @example
      * ```ts
-     * // Safe mode (default): Only known formats
+     * // Safe mode (default): Only universally supported formats
      * const response = await fetch('data.csv.gz');
-     * await parse(response); // ✓ Works
+     * await parse(response); // ✓ Works in all browsers
      *
-     * // Experimental mode: Allow future formats
-     * const response = await fetch('data.csv.br'); // Brotli
+     * // Experimental mode: Allow deflate-raw (Chromium-only)
+     * const response = await fetch('data.csv'); // Content-Encoding: deflate-raw
      * await parse(response, { allowExperimentalCompressions: true });
-     * // Works if runtime supports Brotli, otherwise throws runtime error
+     * // ✓ Works in Chrome/Edge
+     * // ✗ May fail in Firefox/Safari
+     *
+     * // Browser-aware usage
+     * const isChromium = navigator.userAgent.includes('Chrome');
+     * await parse(response, {
+     *   allowExperimentalCompressions: isChromium
+     * });
      * ```
      */
     allowExperimentalCompressions?: boolean;
@@ -318,17 +344,288 @@ export interface CSVRecordAssemblerOptions<Header extends ReadonlyArray<string>>
      */
     skipEmptyLines?: boolean;
 }
+/**
+ * Worker communication strategy.
+ *
+ * Defines how data is communicated between the main thread and worker threads.
+ *
+ * @category Types
+ */
+export type WorkerCommunicationStrategy = "message-streaming" | "stream-transfer";
+/**
+ * Engine fallback information.
+ *
+ * Provided when the requested engine configuration fails and falls back to a safer configuration.
+ *
+ * @category Types
+ */
+export interface EngineFallbackInfo {
+    /**
+     * Original requested configuration.
+     */
+    requestedConfig: EngineConfig;
+    /**
+     * Actual configuration after fallback.
+     */
+    actualConfig: EngineConfig;
+    /**
+     * Reason for fallback.
+     */
+    reason: string;
+    /**
+     * Original error if any.
+     */
+    error?: Error;
+}
+/**
+ * Engine configuration for CSV parsing.
+ *
+ * All parsing engine settings are unified in this interface.
+ *
+ * @category Types
+ */
+export interface EngineConfig {
+    /**
+     * Execute in Worker thread.
+     *
+     * @default false
+     *
+     * @example Worker execution
+     * ```ts
+     * parse(csv, { engine: { worker: true } })
+     * ```
+     */
+    worker?: boolean;
+    /**
+     * Custom Worker URL.
+     * Only applicable when `worker: true`.
+     *
+     * If not provided, uses the bundled worker.
+     *
+     * @remarks
+     * The custom worker must implement the same message protocol as the bundled worker.
+     *
+     * @example Custom worker
+     * ```ts
+     * parse(csv, {
+     *   engine: {
+     *     worker: true,
+     *     workerURL: new URL('./custom-worker.js', import.meta.url)
+     *   }
+     * })
+     * ```
+     */
+    workerURL?: string | URL;
+    /**
+     * 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 {@link WorkerPool} with the `using` syntax for automatic cleanup.
+     *
+     * @example Using ReusableWorkerPool with automatic cleanup
+     * ```ts
+     * 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
+     * }
+     * ```
+     *
+     * @example Multiple operations with same pool
+     * ```ts
+     * 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
+     * ```
+     */
+    workerPool?: import('../execution/worker/helpers/WorkerPool.ts').WorkerPool;
+    /**
+     * Use WASM implementation.
+     *
+     * Requires prior initialization with {@link loadWASM}.
+     *
+     * @default false
+     *
+     * @example Main thread + WASM
+     * ```ts
+     * import { loadWASM, parse } from 'web-csv-toolbox';
+     *
+     * await loadWASM();
+     * parse(csv, { engine: { wasm: true } })
+     * ```
+     *
+     * @example Worker + WASM
+     * ```ts
+     * await loadWASM();
+     * parse(csv, { engine: { worker: true, wasm: true } })
+     * ```
+     */
+    wasm?: boolean;
+    /**
+     * 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
+     *
+     * @default "message-streaming"
+     *
+     * @see https://caniuse.com/mdn-api_readablestream_transferable
+     *
+     * @example Message streaming (default, safe)
+     * ```ts
+     * parse(csv, { engine: { worker: true } })
+     * // or explicitly
+     * parse(csv, { engine: { worker: true, workerStrategy: "message-streaming" } })
+     * ```
+     *
+     * @example Stream transfer (Chrome/Firefox/Edge, auto-fallback on Safari)
+     * ```ts
+     * parse(csv, {
+     *   engine: {
+     *     worker: true,
+     *     workerStrategy: "stream-transfer",
+     *     onFallback: (info) => {
+     *       console.warn(`Fallback to message-streaming: ${info.reason}`);
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    workerStrategy?: WorkerCommunicationStrategy;
+    /**
+     * 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
+     *
+     * @default false
+     *
+     * @example Strict mode (Chrome/Firefox/Edge only)
+     * ```ts
+     * 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);
+     * }
+     * ```
+     */
+    strict?: boolean;
+    /**
+     * 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)
+     *
+     * @example Track fallback in analytics
+     * ```ts
+     * 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
+     *       });
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    onFallback?: (info: EngineFallbackInfo) => void;
+}
+/**
+ * Engine configuration options.
+ *
+ * @category Types
+ */
+export interface EngineOptions {
+    /**
+     * Engine configuration for CSV parsing.
+     *
+     * @example Default (main thread)
+     * ```ts
+     * parse(csv)
+     * ```
+     *
+     * @example Worker
+     * ```ts
+     * parse(csv, { engine: { worker: true } })
+     * ```
+     *
+     * @example Worker + WASM
+     * ```ts
+     * await loadWASM();
+     * parse(csv, { engine: { worker: true, wasm: true } })
+     * ```
+     *
+     * @example Worker + Stream transfer
+     * ```ts
+     * parse(csv, {
+     *   engine: {
+     *     worker: true,
+     *     workerStrategy: "stream-transfer"
+     *   }
+     * })
+     * ```
+     */
+    engine?: EngineConfig;
+}
 /**
  * Parse options for CSV string.
  * @category Types
  */
-export interface ParseOptions<Header extends ReadonlyArray<string> = ReadonlyArray<string>, Delimiter extends string = DEFAULT_DELIMITER, Quotation extends string = DEFAULT_QUOTATION> extends CommonOptions<Delimiter, Quotation>, CSVRecordAssemblerOptions<Header>, AbortSignalOptions {
+export interface ParseOptions<Header extends ReadonlyArray<string> = ReadonlyArray<string>, Delimiter extends string = DEFAULT_DELIMITER, Quotation extends string = DEFAULT_QUOTATION> extends CommonOptions<Delimiter, Quotation>, CSVRecordAssemblerOptions<Header>, EngineOptions, AbortSignalOptions {
 }
 /**
  * Parse options for CSV binary.
  * @category Types
  */
-export interface ParseBinaryOptions<Header extends ReadonlyArray<string>> extends ParseOptions<Header>, BinaryOptions {
+export interface ParseBinaryOptions<Header extends ReadonlyArray<string> = ReadonlyArray<string>, Delimiter extends string = DEFAULT_DELIMITER, Quotation extends string = DEFAULT_QUOTATION> extends ParseOptions<Header, Delimiter, Quotation>, BinaryOptions {
 }
 /**
  * CSV Record.
@@ -356,6 +653,31 @@ export type CSVString<Header extends ReadonlyArray<string> = [], Delimiter exten
  * @category Types
  */
 export type CSVBinary = ReadableStream<Uint8Array> | Response | ArrayBuffer | Uint8Array;
+/**
+ * Backpressure monitoring options.
+ *
+ * @category Types
+ */
+export interface BackpressureOptions {
+    /**
+     * How often to check for backpressure (in number of items processed).
+     *
+     * Lower values = more responsive to backpressure but slight performance overhead.
+     * Higher values = less overhead but slower backpressure response.
+     *
+     * Default:
+     * - CSVLexerTransformer: 100 tokens
+     * - CSVRecordAssemblerTransformer: 10 records
+     */
+    checkInterval?: number;
+}
+/**
+ * Extended queuing strategy with backpressure monitoring options.
+ *
+ * @category Types
+ */
+export interface ExtendedQueuingStrategy<T> extends QueuingStrategy<T>, BackpressureOptions {
+}
 /**
  * CSV.
  *

package/dist/commonParseErrorHandling.js.map

@@ -1 +1 @@
-{"version":3,"file":"commonParseErrorHandling.js","sources":["../src/commonParseErrorHandling.ts"],"sourcesContent":["import { ParseError } from \"./common/errors\";\n\n/**\n * Common error handling for parsing CSV data.\n *\n * @param error - The error to handle.\n * @throws {ParseError} When an error occurs while parsing the CSV data.\n * @throws {RangeError} When an invalid option is provided.\n * @throws {TypeError} When an invalid option is provided.\n */\n\nexport function commonParseErrorHandling(error: unknown): never {\n  if (\n    error instanceof ParseError ||\n    error instanceof RangeError ||\n    error instanceof TypeError\n  ) {\n    throw error;\n  }\n  throw new ParseError(\"An error occurred while parsing the CSV data.\", {\n    cause: error,\n  });\n}\n"],"names":[],"mappings":";;AAWO,SAAS,yBAAyB,KAAuB,EAAA;AAC9D,EAAA,IACE,KAAiB,YAAA,UAAA,IACjB,KAAiB,YAAA,UAAA,IACjB,iBAAiB,SACjB,EAAA;AACA,IAAM,MAAA,KAAA;AAAA;AAER,EAAM,MAAA,IAAI,WAAW,+CAAiD,EAAA;AAAA,IACpE,KAAO,EAAA;AAAA,GACR,CAAA;AACH;;;;"}
+{"version":3,"file":"commonParseErrorHandling.js","sources":["../src/commonParseErrorHandling.ts"],"sourcesContent":["import { ParseError } from \"./common/errors\";\n\n/**\n * Common error handling for parsing CSV data.\n *\n * @param error - The error to handle.\n * @throws {ParseError} When an error occurs while parsing the CSV data.\n * @throws {RangeError} When an invalid option is provided.\n * @throws {TypeError} When an invalid option is provided.\n */\n\nexport function commonParseErrorHandling(error: unknown): never {\n  if (\n    error instanceof ParseError ||\n    error instanceof RangeError ||\n    error instanceof TypeError\n  ) {\n    throw error;\n  }\n  throw new ParseError(\"An error occurred while parsing the CSV data.\", {\n    cause: error,\n  });\n}\n"],"names":[],"mappings":";;AAWO,SAAS,yBAAyB,KAAA,EAAuB;AAC9D,EAAA,IACE,KAAA,YAAiB,UAAA,IACjB,KAAA,YAAiB,UAAA,IACjB,iBAAiB,SAAA,EACjB;AACA,IAAA,MAAM,KAAA;AAAA,EACR;AACA,EAAA,MAAM,IAAI,WAAW,+CAAA,EAAiD;AAAA,IACpE,KAAA,EAAO;AAAA,GACR,CAAA;AACH;;;;"}

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["export const CR = \"\\r\";\nexport type CR = typeof CR;\n\nexport const CRLF = \"\\r\\n\";\nexport type CRLF = typeof CRLF;\n\nexport const LF = \"\\n\";\nexport type LF = typeof LF;\n\nexport type Newline = CRLF | CR | LF;\n\n/**\n * COMMA is a symbol for comma(,).\n */\nexport const COMMA = \",\";\n\n/**\n * DOUBLE_QUOTE is a symbol for double quote(\").\n */\nexport const DOUBLE_QUOTE = '\"';\n\nexport const DEFAULT_DELIMITER = COMMA;\nexport type DEFAULT_DELIMITER = typeof DEFAULT_DELIMITER;\n\nexport const DEFAULT_QUOTATION = DOUBLE_QUOTE;\nexport type DEFAULT_QUOTATION = typeof DEFAULT_QUOTATION;\n"],"names":[],"mappings":"AAAO,MAAM,EAAK,GAAA;AAGX,MAAM,IAAO,GAAA;AAGb,MAAM,EAAK,GAAA;AAQX,MAAM,KAAQ,GAAA;AAKd,MAAM,YAAe,GAAA;AAErB,MAAM,iBAAoB,GAAA;AAG1B,MAAM,iBAAoB,GAAA;;;;"}
+{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["export const CR = \"\\r\";\nexport type CR = typeof CR;\n\nexport const CRLF = \"\\r\\n\";\nexport type CRLF = typeof CRLF;\n\nexport const LF = \"\\n\";\nexport type LF = typeof LF;\n\nexport type Newline = CRLF | CR | LF;\n\n/**\n * COMMA is a symbol for comma(,).\n */\nexport const COMMA = \",\";\n\n/**\n * DOUBLE_QUOTE is a symbol for double quote(\").\n */\nexport const DOUBLE_QUOTE = '\"';\n\nexport const DEFAULT_DELIMITER = COMMA;\nexport type DEFAULT_DELIMITER = typeof DEFAULT_DELIMITER;\n\nexport const DEFAULT_QUOTATION = DOUBLE_QUOTE;\nexport type DEFAULT_QUOTATION = typeof DEFAULT_QUOTATION;\n"],"names":[],"mappings":"AAAO,MAAM,EAAA,GAAK;AAGX,MAAM,IAAA,GAAO;AAGb,MAAM,EAAA,GAAK;AAQX,MAAM,KAAA,GAAQ;AAKd,MAAM,YAAA,GAAe;AAErB,MAAM,iBAAA,GAAoB;AAG1B,MAAM,iBAAA,GAAoB;;;;"}

package/dist/createWorker.node.d.ts

@@ -0,0 +1,2 @@
+export * from './execution/worker/helpers/createWorker.node'
+export {}

package/dist/createWorker.web.d.ts

@@ -0,0 +1,2 @@
+export * from './execution/worker/helpers/createWorker.web'
+export {}

package/dist/execution/EnginePresets.d.ts

@@ -0,0 +1,143 @@
+import { EngineConfig, EngineFallbackInfo } from '../common/types.ts';
+import { WorkerPool } from './worker/helpers/WorkerPool.ts';
+/**
+ * Options for customizing engine presets.
+ */
+export interface EnginePresetOptions {
+    /**
+     * Worker pool for managing worker lifecycle.
+     * Reuse workers across multiple parse operations.
+     */
+    workerPool?: WorkerPool;
+    /**
+     * Custom worker URL.
+     * Use a custom worker script instead of the bundled worker.
+     */
+    workerURL?: string | URL;
+    /**
+     * Callback for fallback notifications.
+     * Called when the engine falls back to a less optimal strategy.
+     */
+    onFallback?: (info: EngineFallbackInfo) => void;
+}
+/**
+ * Predefined engine configuration presets for common use cases.
+ *
+ * All presets are functions that optionally accept configuration options.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { parseString, EnginePresets } from 'web-csv-toolbox';
+ *
+ * // Use fastest available execution method
+ * for await (const record of parseString(csv, {
+ *   engine: EnginePresets.fastest()
+ * })) {
+ *   console.log(record);
+ * }
+ * ```
+ *
+ * @example With WorkerPool
+ * ```ts
+ * import { parseString, EnginePresets, WorkerPool } from 'web-csv-toolbox';
+ *
+ * const pool = new WorkerPool({ maxWorkers: 4 });
+ *
+ * for await (const record of parseString(csv, {
+ *   engine: EnginePresets.fastest({ workerPool: pool })
+ * })) {
+ *   console.log(record);
+ * }
+ * ```
+ */
+export declare const EnginePresets: Readonly<{
+    /**
+     * Main thread execution (default).
+     * - No worker overhead
+     * - Synchronous execution on main thread
+     * - Best for small files (< 1MB)
+     *
+     * @param options - Configuration options (not used for main thread)
+     * @returns Engine configuration
+     */
+    readonly mainThread: (options?: EnginePresetOptions) => EngineConfig;
+    /**
+     * Worker execution with message streaming.
+     * - Offloads parsing to worker thread
+     * - Records sent via postMessage
+     * - Works on all browsers including Safari
+     * - Best for medium files (1-10MB)
+     *
+     * @param options - Configuration options
+     * @returns Engine configuration
+     */
+    readonly worker: (options?: EnginePresetOptions) => EngineConfig;
+    /**
+     * Worker execution with stream transfer (zero-copy).
+     * - Offloads parsing to worker thread
+     * - Streams transferred directly (zero-copy)
+     * - Only works on Chrome, Firefox, Edge (not Safari)
+     * - Best for large streaming files (> 10MB)
+     * - Automatically falls back to message-streaming if not supported
+     *
+     * @param options - Configuration options
+     * @returns Engine configuration
+     */
+    readonly workerStreamTransfer: (options?: EnginePresetOptions) => EngineConfig;
+    /**
+     * WebAssembly execution on main thread.
+     * - Fast parsing with WASM
+     * - Runs on main thread
+     * - Limited to UTF-8 encoding and double-quote (")
+     * - Best for medium-sized UTF-8 files (1-10MB)
+     *
+     * @param options - Configuration options
+     * @returns Engine configuration
+     */
+    readonly wasm: (options?: EnginePresetOptions) => EngineConfig;
+    /**
+     * Worker + WASM execution.
+     * - Combines worker offloading with WASM speed
+     * - Best for large UTF-8 files (> 10MB)
+     * - Limited to UTF-8 encoding and double-quote (")
+     *
+     * @param options - Configuration options
+     * @returns Engine configuration
+     */
+    readonly workerWasm: (options?: EnginePresetOptions) => EngineConfig;
+    /**
+     * Fastest available method.
+     * Automatically selects the best execution strategy:
+     * - For streams: Worker with stream-transfer (falls back to message-streaming)
+     * - For strings/binary: Worker + WASM
+     * - For all inputs: Offloads to worker for better performance
+     *
+     * @param options - Configuration options
+     * @returns Engine configuration
+     */
+    readonly fastest: (options?: EnginePresetOptions) => EngineConfig;
+    /**
+     * Balanced configuration for production use.
+     * - Worker execution for offloading
+     * - No WASM (broader encoding support)
+     * - Stream-transfer with automatic fallback
+     * - Works with all encodings
+     *
+     * @param options - Configuration options
+     * @returns Engine configuration
+     */
+    readonly balanced: (options?: EnginePresetOptions) => EngineConfig;
+    /**
+     * Strict mode: no automatic fallbacks.
+     * - Throws errors instead of falling back to main thread
+     * - Useful for testing or when you need guaranteed execution mode
+     *
+     * @param options - Configuration options
+     * @returns Engine configuration
+     */
+    readonly strict: (options?: EnginePresetOptions) => EngineConfig;
+}>;
+/**
+ * Type for engine preset names.
+ */
+export type EnginePresetName = keyof typeof EnginePresets;

package/dist/execution/EnginePresets.js

@@ -0,0 +1,129 @@
+const EnginePresets = Object.freeze({
+  /**
+   * Main thread execution (default).
+   * - No worker overhead
+   * - Synchronous execution on main thread
+   * - Best for small files (< 1MB)
+   *
+   * @param options - Configuration options (not used for main thread)
+   * @returns Engine configuration
+   */
+  mainThread: (options) => ({
+    worker: false,
+    wasm: false,
+    ...options
+  }),
+  /**
+   * Worker execution with message streaming.
+   * - Offloads parsing to worker thread
+   * - Records sent via postMessage
+   * - Works on all browsers including Safari
+   * - Best for medium files (1-10MB)
+   *
+   * @param options - Configuration options
+   * @returns Engine configuration
+   */
+  worker: (options) => ({
+    worker: true,
+    wasm: false,
+    workerStrategy: "message-streaming",
+    ...options
+  }),
+  /**
+   * Worker execution with stream transfer (zero-copy).
+   * - Offloads parsing to worker thread
+   * - Streams transferred directly (zero-copy)
+   * - Only works on Chrome, Firefox, Edge (not Safari)
+   * - Best for large streaming files (> 10MB)
+   * - Automatically falls back to message-streaming if not supported
+   *
+   * @param options - Configuration options
+   * @returns Engine configuration
+   */
+  workerStreamTransfer: (options) => ({
+    worker: true,
+    wasm: false,
+    workerStrategy: "stream-transfer",
+    ...options
+  }),
+  /**
+   * WebAssembly execution on main thread.
+   * - Fast parsing with WASM
+   * - Runs on main thread
+   * - Limited to UTF-8 encoding and double-quote (")
+   * - Best for medium-sized UTF-8 files (1-10MB)
+   *
+   * @param options - Configuration options
+   * @returns Engine configuration
+   */
+  wasm: (options) => ({
+    worker: false,
+    wasm: true,
+    ...options
+  }),
+  /**
+   * Worker + WASM execution.
+   * - Combines worker offloading with WASM speed
+   * - Best for large UTF-8 files (> 10MB)
+   * - Limited to UTF-8 encoding and double-quote (")
+   *
+   * @param options - Configuration options
+   * @returns Engine configuration
+   */
+  workerWasm: (options) => ({
+    worker: true,
+    wasm: true,
+    workerStrategy: "message-streaming",
+    ...options
+  }),
+  /**
+   * Fastest available method.
+   * Automatically selects the best execution strategy:
+   * - For streams: Worker with stream-transfer (falls back to message-streaming)
+   * - For strings/binary: Worker + WASM
+   * - For all inputs: Offloads to worker for better performance
+   *
+   * @param options - Configuration options
+   * @returns Engine configuration
+   */
+  fastest: (options) => ({
+    worker: true,
+    wasm: true,
+    workerStrategy: "stream-transfer",
+    ...options
+  }),
+  /**
+   * Balanced configuration for production use.
+   * - Worker execution for offloading
+   * - No WASM (broader encoding support)
+   * - Stream-transfer with automatic fallback
+   * - Works with all encodings
+   *
+   * @param options - Configuration options
+   * @returns Engine configuration
+   */
+  balanced: (options) => ({
+    worker: true,
+    wasm: false,
+    workerStrategy: "stream-transfer",
+    ...options
+  }),
+  /**
+   * Strict mode: no automatic fallbacks.
+   * - Throws errors instead of falling back to main thread
+   * - Useful for testing or when you need guaranteed execution mode
+   *
+   * @param options - Configuration options
+   * @returns Engine configuration
+   */
+  strict: (options) => ({
+    worker: true,
+    wasm: false,
+    workerStrategy: "stream-transfer",
+    strict: true,
+    ...options
+  })
+});
+
+export { EnginePresets };
+//# sourceMappingURL=EnginePresets.js.map