@cj-tech-master/excelts 5.1.18 → 6.0.0-beta.1

package/dist/browser/modules/archive/zip-spec/zip-records.js

@@ -3,6 +3,8 @@
  *
  * Shared by streaming zip writer and buffer zip builder.
  */
+import { EMPTY_UINT8ARRAY } from "../shared/bytes.js";
+import { concatUint8Arrays } from "../../../utils/binary.js";
 // =============================================================================
 // ZIP format constants (PKWARE APPNOTE)
 // =============================================================================
@@ -16,18 +18,68 @@ export const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIG = 0x07064b50;
 // Versions
 export const VERSION_NEEDED = 20; // 2.0 - supports DEFLATE
 export const VERSION_MADE_BY = 20; // 2.0
+export const VERSION_ZIP64 = 45; // 4.5 - supports ZIP64
 // Compression methods
 export const COMPRESSION_STORE = 0;
 export const COMPRESSION_DEFLATE = 8;
+export const COMPRESSION_AES = 99;
 // General purpose bit flags
+export const FLAG_ENCRYPTED = 0x0001;
 export const FLAG_UTF8 = 0x0800;
 export const FLAG_DATA_DESCRIPTOR = 0x0008;
+// =============================================================================
+// Unix file type constants (from stat.h)
+// =============================================================================
+/** Unix file type mask */
+export const S_IFMT = 0o170000;
+/** Unix symbolic link type */
+export const S_IFLNK = 0o120000;
+/** Unix directory type */
+export const S_IFDIR = 0o040000;
+/** Unix regular file type */
+export const S_IFREG = 0o100000;
+// ZIP "version made by" OS codes
+/** MS-DOS / Windows OS code */
+export const ZIP_OS_MSDOS = 0;
+/** Unix OS code */
+export const ZIP_OS_UNIX = 3;
+// =============================================================================
+// Unix mode helpers
+// =============================================================================
+/**
+ * Extract Unix mode from ZIP external attributes.
+ * Returns 0 if no Unix mode information is available.
+ */
+export function getUnixModeFromExternalAttributes(externalAttributes) {
+    return (externalAttributes >> 16) & 0xffff;
+}
+/**
+ * Get the OS code from versionMadeBy field.
+ */
+export function getOsFromVersionMadeBy(versionMadeBy) {
+    return versionMadeBy !== undefined ? (versionMadeBy >> 8) & 0xff : ZIP_OS_MSDOS;
+}
+/**
+ * Check if Unix mode indicates a symbolic link.
+ */
+export function isSymlinkMode(mode) {
+    return (mode & S_IFMT) === S_IFLNK;
+}
+/**
+ * Check if Unix mode indicates a directory.
+ */
+export function isDirectoryMode(mode) {
+    return (mode & S_IFMT) === S_IFDIR;
+}
 // ZIP64 / sentinel sizes
 export const UINT16_MAX = 0xffff;
 export const UINT32_MAX = 0xffffffff;
 export const ZIP_LOCAL_FILE_HEADER_FIXED_SIZE = 30;
 export const ZIP_CENTRAL_DIR_HEADER_FIXED_SIZE = 46;
 export const ZIP_END_OF_CENTRAL_DIR_FIXED_SIZE = 22;
+export const ZIP64_END_OF_CENTRAL_DIR_FIXED_SIZE = 56;
+export const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_FIXED_SIZE = 20;
+export const ZIP64_EXTRA_FIELD_ID = 0x0001;
 export function writeLocalFileHeaderInto(out, view, offset, input) {
     const versionNeeded = input.versionNeeded ?? VERSION_NEEDED;
     view.setUint32(offset + 0, LOCAL_FILE_HEADER_SIG, true);
@@ -124,3 +176,105 @@ export function buildDataDescriptor(crc32, compressedSize, uncompressedSize) {
     view.setUint32(12, uncompressedSize, true);
     return descriptor;
 }
+function writeUint64LE(view, offset, value) {
+    // ZIP64 values fit within JS safe integer for our use cases (<= 2^53-1).
+    const lo = value >>> 0;
+    const hi = Math.floor(value / 0x100000000) >>> 0;
+    view.setUint32(offset, lo, true);
+    view.setUint32(offset + 4, hi, true);
+}
+export function buildDataDescriptorZip64(crc32, compressedSize, uncompressedSize) {
+    // Signature(4) + CRC32(4) + compressedSize(8) + uncompressedSize(8)
+    const descriptor = new Uint8Array(24);
+    const view = new DataView(descriptor.buffer, descriptor.byteOffset, descriptor.byteLength);
+    view.setUint32(0, DATA_DESCRIPTOR_SIG, true);
+    view.setUint32(4, crc32, true);
+    writeUint64LE(view, 8, compressedSize);
+    writeUint64LE(view, 16, uncompressedSize);
+    return descriptor;
+}
+export function buildZip64ExtraField(input) {
+    const includeUncompressed = input.uncompressedSize !== undefined;
+    const includeCompressed = input.compressedSize !== undefined;
+    const includeOffset = input.localHeaderOffset !== undefined;
+    const includeDisk = input.diskNumberStart !== undefined;
+    let dataLen = 0;
+    if (includeUncompressed) {
+        dataLen += 8;
+    }
+    if (includeCompressed) {
+        dataLen += 8;
+    }
+    if (includeOffset) {
+        dataLen += 8;
+    }
+    if (includeDisk) {
+        dataLen += 4;
+    }
+    if (dataLen === 0) {
+        return EMPTY_UINT8ARRAY;
+    }
+    const out = new Uint8Array(4 + dataLen);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    view.setUint16(0, ZIP64_EXTRA_FIELD_ID, true);
+    view.setUint16(2, dataLen, true);
+    let off = 4;
+    if (includeUncompressed) {
+        writeUint64LE(view, off, input.uncompressedSize);
+        off += 8;
+    }
+    if (includeCompressed) {
+        writeUint64LE(view, off, input.compressedSize);
+        off += 8;
+    }
+    if (includeOffset) {
+        writeUint64LE(view, off, input.localHeaderOffset);
+        off += 8;
+    }
+    if (includeDisk) {
+        view.setUint32(off, input.diskNumberStart, true);
+    }
+    return out;
+}
+export function concatExtraFields(a, b) {
+    return concatUint8Arrays([a, b]);
+}
+export function writeZip64EndOfCentralDirectoryInto(out, view, offset, input) {
+    const versionMadeBy = input.versionMadeBy ?? VERSION_MADE_BY;
+    const versionNeeded = input.versionNeeded ?? VERSION_ZIP64;
+    const diskNumber = input.diskNumber ?? 0;
+    const centralDirectoryDiskNumber = input.centralDirectoryDiskNumber ?? 0;
+    view.setUint32(offset + 0, ZIP64_END_OF_CENTRAL_DIR_SIG, true);
+    // Size of ZIP64 EOCD record (excluding signature + this 8-byte field)
+    writeUint64LE(view, offset + 4, 44);
+    view.setUint16(offset + 12, versionMadeBy, true);
+    view.setUint16(offset + 14, versionNeeded, true);
+    view.setUint32(offset + 16, diskNumber, true);
+    view.setUint32(offset + 20, centralDirectoryDiskNumber, true);
+    writeUint64LE(view, offset + 24, input.entryCountOnDisk);
+    writeUint64LE(view, offset + 32, input.entryCountTotal);
+    writeUint64LE(view, offset + 40, input.centralDirSize);
+    writeUint64LE(view, offset + 48, input.centralDirOffset);
+    return ZIP64_END_OF_CENTRAL_DIR_FIXED_SIZE;
+}
+export function buildZip64EndOfCentralDirectory(input) {
+    const out = new Uint8Array(ZIP64_END_OF_CENTRAL_DIR_FIXED_SIZE);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    writeZip64EndOfCentralDirectoryInto(out, view, 0, input);
+    return out;
+}
+export function writeZip64EndOfCentralDirectoryLocatorInto(out, view, offset, input) {
+    const zip64EndOfCentralDirectoryDiskNumber = input.zip64EndOfCentralDirectoryDiskNumber ?? 0;
+    const totalDisks = input.totalDisks ?? 1;
+    view.setUint32(offset + 0, ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIG, true);
+    view.setUint32(offset + 4, zip64EndOfCentralDirectoryDiskNumber, true);
+    writeUint64LE(view, offset + 8, input.zip64EndOfCentralDirectoryOffset);
+    view.setUint32(offset + 16, totalDisks, true);
+    return ZIP64_END_OF_CENTRAL_DIR_LOCATOR_FIXED_SIZE;
+}
+export function buildZip64EndOfCentralDirectoryLocator(input) {
+    const out = new Uint8Array(ZIP64_END_OF_CENTRAL_DIR_LOCATOR_FIXED_SIZE);
+    const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+    writeZip64EndOfCentralDirectoryLocatorInto(out, view, 0, input);
+    return out;
+}

package/dist/browser/modules/csv/constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CSV Module Constants
+ *
+ * Shared constants used across the CSV module.
+ * Extracted to avoid circular dependencies between parse-core and utils/parse.
+ */
+/**
+ * Pre-compiled regex for line splitting (matches CR, LF, or CRLF)
+ */
+export declare const DEFAULT_LINEBREAK_REGEX: RegExp;
+/**
+ * Get UTF-8 byte length of a string efficiently.
+ * Uses fast path for ASCII-only strings and encodeInto for mixed content.
+ *
+ * @param text - String to measure
+ * @returns UTF-8 byte length
+ */
+export declare function getUtf8ByteLength(text: string): number;

package/dist/browser/modules/csv/constants.js

@@ -0,0 +1,66 @@
+/**
+ * CSV Module Constants
+ *
+ * Shared constants used across the CSV module.
+ * Extracted to avoid circular dependencies between parse-core and utils/parse.
+ */
+/**
+ * Pre-compiled regex for line splitting (matches CR, LF, or CRLF)
+ */
+export const DEFAULT_LINEBREAK_REGEX = /\r\n|\r|\n/;
+/**
+ * Lazily initialized TextEncoder + buffers for byte length calculations.
+ * Avoids eager allocation at module load time.
+ */
+let sharedTextEncoder = null;
+let singleCharBuffer = null;
+let encodeBuffer = null;
+function getEncoder() {
+    if (!sharedTextEncoder) {
+        sharedTextEncoder = new TextEncoder();
+        singleCharBuffer = new Uint8Array(4);
+        encodeBuffer = new Uint8Array(4096);
+    }
+    return sharedTextEncoder;
+}
+/**
+ * Get UTF-8 byte length of a string efficiently.
+ * Uses fast path for ASCII-only strings and encodeInto for mixed content.
+ *
+ * @param text - String to measure
+ * @returns UTF-8 byte length
+ */
+export function getUtf8ByteLength(text) {
+    const len = text.length;
+    if (len === 0) {
+        return 0;
+    }
+    // Fast path for single character
+    if (len === 1) {
+        const code = text.charCodeAt(0);
+        if (code < 128) {
+            return 1;
+        } // ASCII
+        // Use encodeInto with reusable buffer to avoid allocation
+        const encoder = getEncoder();
+        return encoder.encodeInto(text, singleCharBuffer).written;
+    }
+    // For longer strings, check if all ASCII first (very common for CSV)
+    let isAllAscii = true;
+    for (let i = 0; i < len; i++) {
+        if (text.charCodeAt(i) >= 128) {
+            isAllAscii = false;
+            break;
+        }
+    }
+    if (isAllAscii) {
+        return len; // ASCII: 1 byte per char
+    }
+    // Mixed content: must encode to get accurate byte count
+    // Use encodeInto with a reusable buffer to avoid per-call allocation
+    const encoder = getEncoder();
+    if (len * 3 > encodeBuffer.length) {
+        encodeBuffer = new Uint8Array(len * 3);
+    }
+    return encoder.encodeInto(text, encodeBuffer).written;
+}

package/dist/browser/modules/csv/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CSV module error types.
+ */
+import { BaseError } from "../../utils/errors.js";
+/**
+ * Base class for all CSV-related errors.
+ */
+export declare class CsvError extends BaseError {
+    name: string;
+}
+/**
+ * Error thrown when CSV worker operations fail.
+ */
+export declare class CsvWorkerError extends CsvError {
+    name: string;
+}

package/dist/browser/modules/csv/errors.js

@@ -0,0 +1,22 @@
+/**
+ * CSV module error types.
+ */
+import { BaseError } from "../../utils/errors.js";
+/**
+ * Base class for all CSV-related errors.
+ */
+export class CsvError extends BaseError {
+    constructor() {
+        super(...arguments);
+        this.name = "CsvError";
+    }
+}
+/**
+ * Error thrown when CSV worker operations fail.
+ */
+export class CsvWorkerError extends CsvError {
+    constructor() {
+        super(...arguments);
+        this.name = "CsvWorkerError";
+    }
+}

package/dist/browser/modules/csv/format/config.d.ts

@@ -0,0 +1,121 @@
+/**
+ * CSV Format Configuration
+ *
+ * Pre-compiled configuration for CSV formatting performance.
+ * Creates regex patterns, quote lookup functions, and format settings.
+ */
+import type { CsvFormatOptions, TypeTransformMap } from "../types.js";
+import type { DecimalSeparator } from "../utils/number.js";
+/**
+ * Configuration for quoting specific columns
+ */
+export type QuoteColumnConfig = boolean | boolean[] | Record<string, boolean>;
+/**
+ * Pre-compiled regex patterns for CSV formatting performance
+ */
+export interface CsvFormatRegex {
+    /** Regex to check if a field needs quoting (contains delimiter, quote, or newline) */
+    needsQuoteRegex: RegExp | null;
+    /** Regex to find quote/escape characters for escaping */
+    escapeQuoteRegex: RegExp | null;
+    /** The escaped quote sequence (escape + quote) */
+    escapedQuote: string;
+    /** Whether quoting is enabled */
+    quoteEnabled: boolean;
+    /** The quote character */
+    quote: string;
+    /** The escape character */
+    escape: string;
+    /** The delimiter character (for fast path) */
+    delimiter: string;
+    /** Whether we can use fast string.includes() check */
+    useFastCheck: boolean;
+}
+/**
+ * Options for creating format regex patterns
+ */
+export interface FormatRegexOptions {
+    /** The quote character (false/null to disable quoting) */
+    quote: string | false | null;
+    /** The delimiter character */
+    delimiter: string;
+    /** The escape character (defaults to quote if not provided) */
+    escape?: string | false | null;
+}
+/**
+ * Context for formatting a single field
+ */
+export interface FormatFieldContext {
+    /** Column index */
+    index: number;
+    /** Header name for this column (if known) */
+    header?: string;
+    /** Whether this is a header row */
+    isHeader: boolean;
+    /** Current output row index (for transform context) */
+    outputRowIndex: number;
+    /** Force quote this field */
+    forceQuote: boolean;
+    /** Quote all fields (when quoteColumns: true) */
+    quoteAll: boolean;
+    /** Escape formulae (CSV injection protection) */
+    escapeFormulae: boolean;
+    /** Decimal separator for number formatting */
+    decimalSeparator: DecimalSeparator;
+    /** Type transform map */
+    transform?: TypeTransformMap;
+}
+/**
+ * Options for formatting a row
+ */
+export interface FormatRowOptions {
+    /** Pre-computed quote lookup function */
+    quoteLookup: QuoteLookupFn;
+    /** Field delimiter */
+    delimiter: string;
+    /** Header names for columns (used for transform context) */
+    headers?: string[];
+    /** Whether this row is a header row */
+    isHeader: boolean;
+    /** Current output row index (0-based) */
+    outputRowIndex: number;
+    /** Quote all fields (when quoteColumns: true) */
+    quoteAll: boolean;
+    /** Escape formulae (CSV injection protection) */
+    escapeFormulae: boolean;
+    /** Decimal separator for number formatting */
+    decimalSeparator: DecimalSeparator;
+    /** Type transform map */
+    transform?: TypeTransformMap;
+}
+/**
+ * Complete format configuration (shared by batch formatter and CsvFormatterStream)
+ */
+export interface FormatConfig {
+    delimiter: string;
+    lineEnding: string;
+    quoteAll: boolean;
+    escapeFormulae: boolean;
+    decimalSeparator: DecimalSeparator;
+    writeHeaders: boolean;
+    bom: boolean;
+    trailingNewline: boolean;
+    typeTransform?: TypeTransformMap;
+    regex: CsvFormatRegex;
+    shouldQuoteColumn: QuoteLookupFn;
+    shouldQuoteHeader: QuoteLookupFn;
+}
+/**
+ * Create pre-compiled regex patterns for CSV formatting
+ */
+export declare function createFormatRegex(options: FormatRegexOptions): CsvFormatRegex;
+/**
+ * Pre-compute a quote lookup function for better performance.
+ * Avoids repeated type checks on quoteConfig during formatting.
+ */
+export type QuoteLookupFn = (index: number, header: string | undefined) => boolean;
+export declare function createQuoteLookup(quoteConfig: QuoteColumnConfig | undefined): QuoteLookupFn;
+/**
+ * Create complete format configuration from options
+ */
+export declare function createFormatConfig(options: CsvFormatOptions): FormatConfig;

package/dist/browser/modules/csv/format/config.js

@@ -0,0 +1,106 @@
+/**
+ * CSV Format Configuration
+ *
+ * Pre-compiled configuration for CSV formatting performance.
+ * Creates regex patterns, quote lookup functions, and format settings.
+ */
+import { escapeRegex, normalizeQuoteOption, normalizeEscapeOption } from "../utils/detect.js";
+import { CsvError } from "../errors.js";
+// =============================================================================
+// Regex Factory
+// =============================================================================
+/**
+ * Create pre-compiled regex patterns for CSV formatting
+ */
+export function createFormatRegex(options) {
+    const { quote: quoteOption, delimiter, escape: escapeOption } = options;
+    // Use centralized normalization utilities
+    const { enabled: quoteEnabled, char: quote } = normalizeQuoteOption(quoteOption);
+    const escapeNormalized = normalizeEscapeOption(escapeOption, quote);
+    if (!quoteEnabled) {
+        return {
+            needsQuoteRegex: null,
+            escapeQuoteRegex: null,
+            escapedQuote: "",
+            quoteEnabled: false,
+            quote: "",
+            escape: "",
+            delimiter,
+            useFastCheck: false
+        };
+    }
+    // When quoting is enabled, we must have a valid escape character to produce valid CSV.
+    // If escape was explicitly disabled (escape: false/null), fall back to quote char (RFC 4180 standard).
+    // This ensures internal quotes are always properly escaped as "" rather than producing invalid CSV.
+    const escape = escapeNormalized.char || quote;
+    // Use fast string.includes() check for single-char delimiter, quote, and escape
+    const useFastCheck = delimiter.length === 1 && quote.length === 1 && escape.length === 1;
+    return {
+        needsQuoteRegex: useFastCheck
+            ? null // Will use fast check instead
+            : (() => {
+                // Build character class content, ensuring '-' is escaped for use inside [...]
+                const classContent = `${escapeRegex(delimiter)}${escapeRegex(quote)}${escape !== quote ? escapeRegex(escape) : ""}\r\n`.replace(/-/g, "\\-");
+                return new RegExp(`[${classContent}]`);
+            })(),
+        escapeQuoteRegex: escape !== quote
+            ? new RegExp(`${escapeRegex(quote)}|${escapeRegex(escape)}`, "g")
+            : new RegExp(escapeRegex(quote), "g"),
+        escapedQuote: escape + quote,
+        quoteEnabled: true,
+        quote,
+        escape,
+        delimiter,
+        useFastCheck
+    };
+}
+export function createQuoteLookup(quoteConfig) {
+    if (quoteConfig === true) {
+        return () => true;
+    }
+    if (quoteConfig === false || quoteConfig === undefined) {
+        return () => false;
+    }
+    if (Array.isArray(quoteConfig)) {
+        return (index) => quoteConfig[index] === true;
+    }
+    // Record<string, boolean>
+    return (_index, header) => header ? quoteConfig[header] === true : false;
+}
+// =============================================================================
+// Config Factory
+// =============================================================================
+/**
+ * Create complete format configuration from options
+ */
+export function createFormatConfig(options) {
+    const { delimiter = ",", lineEnding = "\n", quote: quoteOption = '"', escape: escapeOption, quoteColumns = false, quoteHeaders = false, writeHeaders: writeHeadersOption, bom = false, trailingNewline = false, escapeFormulae = false, decimalSeparator = ".", typeTransform } = options;
+    // Validate decimalSeparator - only "." or "," are valid
+    if (decimalSeparator !== "." && decimalSeparator !== ",") {
+        throw new CsvError(`Invalid decimalSeparator: "${decimalSeparator}". Must be "." or ",".`);
+    }
+    // Prevent silent data corruption when decimalSeparator matches delimiter
+    if (decimalSeparator === delimiter) {
+        throw new CsvError("decimalSeparator cannot be the same as delimiter");
+    }
+    const regex = createFormatRegex({
+        quote: quoteOption,
+        delimiter,
+        escape: escapeOption
+    });
+    const quoteAll = quoteColumns === true;
+    return {
+        delimiter,
+        lineEnding,
+        quoteAll,
+        escapeFormulae,
+        decimalSeparator,
+        writeHeaders: writeHeadersOption ?? true,
+        bom,
+        trailingNewline,
+        typeTransform,
+        regex,
+        shouldQuoteColumn: createQuoteLookup(quoteColumns),
+        shouldQuoteHeader: createQuoteLookup(quoteHeaders)
+    };
+}

package/dist/browser/modules/csv/format/formatted-value.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Formatted value wrapper for controlling field-level quoting in CSV output.
+ *
+ * This module provides helper functions to override the global quoting behavior
+ * for individual field values during CSV formatting.
+ *
+ * @module
+ */
+/**
+ * Symbol to identify FormattedValue instances.
+ * Using Symbol.for ensures reliable detection across module boundaries.
+ */
+declare const FORMATTED_VALUE_SYMBOL: unique symbol;
+/**
+ * Wrapper type for CSV field values with explicit quoting control.
+ * Created via `quoted()` and `unquoted()` helper functions.
+ */
+export interface FormattedValue {
+    readonly [FORMATTED_VALUE_SYMBOL]: true;
+    /** The string value to output */
+    readonly value: string;
+    /** Quoting control: true = force quote, false = prevent quote */
+    readonly quote: boolean;
+}
+/**
+ * Check if a value is a FormattedValue instance.
+ */
+export declare function isFormattedValue(value: unknown): value is FormattedValue;
+/**
+ * Mark a value to be output with quotes.
+ *
+ * Use this in a transform function to force quoting for specific fields,
+ * regardless of the global `quoteColumns` setting.
+ *
+ * @param value - The string value to output
+ * @returns A FormattedValue that will be quoted in the CSV output
+ *
+ * @example
+ * ```ts
+ * import { quoted } from '@cj-tech-master/excelts';
+ *
+ * formatCsv(data, {
+ *   transform: {
+ *     // Force quoting for code-like fields, and quote empty strings
+ *     string: (v, ctx) => {
+ *       if (ctx.column === 'code') return quoted(v);
+ *       if (v === '') return quoted(v);
+ *       return v;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function quoted(value: string): FormattedValue;
+/**
+ * Mark a value to be output without quotes.
+ *
+ * Use this in a transform function to prevent quoting for specific fields,
+ * even when the value would normally be quoted (e.g., contains delimiter).
+ *
+ * WARNING: Using unquoted() with values containing delimiters or newlines
+ * will produce invalid CSV. Use only when you need raw output like Excel formulas.
+ *
+ * @param value - The string value to output (will not be quoted or escaped)
+ * @returns A FormattedValue that will NOT be quoted in the CSV output
+ *
+ * @example
+ * ```ts
+ * import { unquoted } from '@cj-tech-master/excelts';
+ *
+ * formatCsv(data, {
+ *   transform: {
+ *     // Output Excel formula without outer quotes
+ *     number: (v, ctx) => ctx.column === 'id'
+ *       ? unquoted(`="${v}"`)  // Outputs: ="7"
+ *       : String(v)
+ *   }
+ * });
+ * ```
+ */
+export declare function unquoted(value: string): FormattedValue;
+export {};

package/dist/browser/modules/csv/format/formatted-value.js

@@ -0,0 +1,76 @@
+/**
+ * Formatted value wrapper for controlling field-level quoting in CSV output.
+ *
+ * This module provides helper functions to override the global quoting behavior
+ * for individual field values during CSV formatting.
+ *
+ * @module
+ */
+/**
+ * Symbol to identify FormattedValue instances.
+ * Using Symbol.for ensures reliable detection across module boundaries.
+ */
+const FORMATTED_VALUE_SYMBOL = Symbol.for("csv.FormattedValue");
+/**
+ * Check if a value is a FormattedValue instance.
+ */
+export function isFormattedValue(value) {
+    return (value !== null && typeof value === "object" && value[FORMATTED_VALUE_SYMBOL] === true);
+}
+/**
+ * Mark a value to be output with quotes.
+ *
+ * Use this in a transform function to force quoting for specific fields,
+ * regardless of the global `quoteColumns` setting.
+ *
+ * @param value - The string value to output
+ * @returns A FormattedValue that will be quoted in the CSV output
+ *
+ * @example
+ * ```ts
+ * import { quoted } from '@cj-tech-master/excelts';
+ *
+ * formatCsv(data, {
+ *   transform: {
+ *     // Force quoting for code-like fields, and quote empty strings
+ *     string: (v, ctx) => {
+ *       if (ctx.column === 'code') return quoted(v);
+ *       if (v === '') return quoted(v);
+ *       return v;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function quoted(value) {
+    return { [FORMATTED_VALUE_SYMBOL]: true, value, quote: true };
+}
+/**
+ * Mark a value to be output without quotes.
+ *
+ * Use this in a transform function to prevent quoting for specific fields,
+ * even when the value would normally be quoted (e.g., contains delimiter).
+ *
+ * WARNING: Using unquoted() with values containing delimiters or newlines
+ * will produce invalid CSV. Use only when you need raw output like Excel formulas.
+ *
+ * @param value - The string value to output (will not be quoted or escaped)
+ * @returns A FormattedValue that will NOT be quoted in the CSV output
+ *
+ * @example
+ * ```ts
+ * import { unquoted } from '@cj-tech-master/excelts';
+ *
+ * formatCsv(data, {
+ *   transform: {
+ *     // Output Excel formula without outer quotes
+ *     number: (v, ctx) => ctx.column === 'id'
+ *       ? unquoted(`="${v}"`)  // Outputs: ="7"
+ *       : String(v)
+ *   }
+ * });
+ * ```
+ */
+export function unquoted(value) {
+    return { [FORMATTED_VALUE_SYMBOL]: true, value, quote: false };
+}