@cerios/csv-nested-json - npm Package Compare versions

Comparing version 1.3.0 to 1.3.1

dist/index.d.mts

@@ -366,2 +366,21 @@ import * as node_stream from 'node:stream';
     /**
+     * Preserve unquoted empty cells as empty strings in nested output.
+     *
+     * @remarks
+     * This option only applies to unquoted empty columns such as `,,`.
+     * Explicit quoted empty strings are controlled by `preserveEmptyString`.
+     *
+     * @default false
+     */
+    preserveEmptyColumnAsEmptyString?: boolean;
+    /**
+     * Preserve explicitly quoted empty strings as empty strings in nested output.
+     *
+     * @remarks
+     * This option applies to values such as `""` (or the configured quote character equivalent).
+     *
+     * @default true
+     */
+    preserveEmptyString?: boolean;
+    /**
      * Maximum number of records to parse.
@@ -641,2 +660,6 @@ * Parsing stops after this limit is reached.
 
+declare const QUOTED_EMPTY_CELL: unique symbol;
+type InternalCsvCellValue = string | typeof QUOTED_EMPTY_CELL;
+type InternalCsvRecord = Record<string, InternalCsvCellValue>;
+
 /**
@@ -677,2 +700,11 @@ * Low-level CSV parsing utilities.
     /**
+     * Parse CSV content with internal quoted-empty provenance tracking.
+     *
+     * @internal
+     */
+    static parseWithQuotedEmptyProvenance(content: string, options?: CsvParserOptions): InternalCsvRecord[];
+    private static parseInternal;
+    private static createRecord;
+    private static toPublicRecord;
+    /**
      * Strip BOM (Byte Order Mark) from the beginning of content.
@@ -724,2 +756,4 @@ * Handles UTF-8 and UTF-16 BOMs.
     static parseLine(line: string, delimiter?: string, quote?: string): string[];
+    static parseLine(line: string, delimiter: string, quote: string, preserveQuotedEmpty: boolean): InternalCsvCellValue[];
+    private static finalizeParsedCellValue;
     /**
@@ -960,2 +994,3 @@ * Detect duplicate headers and process them according to the strategy.
     private bufferGroupedRecord;
+    private hasIdentifierValue;
     /**
@@ -973,2 +1008,3 @@ * Flush buffered grouped records through NestedJsonConverter.
     private parseLine;
+    private finalizeParsedCellValue;
     /**
@@ -978,2 +1014,3 @@ * Create a record object from values array.
     private createRecord;
+    private toPublicRecord;
     /**
@@ -1273,2 +1310,3 @@ * Apply value transformations to a record.
 
+type ConvertibleCsvRecord = CsvRecord | InternalCsvRecord;
 /**
@@ -1322,3 +1360,4 @@ * Nested JSON conversion utilities.
      */
-    static convert(records: CsvRecord[], options?: CsvParserOptions): NestedObject[];
+    static convert(records: ConvertibleCsvRecord[], options?: CsvParserOptions): NestedObject[];
+    private static hasIdentifierValue;
     /**
@@ -1421,2 +1460,3 @@ * Apply value transformations (null detection, auto-parse numbers, booleans, dates, custom transformer).
     private static unflatten;
+    private static isEffectivelyEmptyValue;
     private static deepMerge;
@@ -1423,0 +1463,0 @@ private static checkIfAllKeysCollide;

dist/index.d.ts

@@ -366,2 +366,21 @@ import * as node_stream from 'node:stream';
     /**
+     * Preserve unquoted empty cells as empty strings in nested output.
+     *
+     * @remarks
+     * This option only applies to unquoted empty columns such as `,,`.
+     * Explicit quoted empty strings are controlled by `preserveEmptyString`.
+     *
+     * @default false
+     */
+    preserveEmptyColumnAsEmptyString?: boolean;
+    /**
+     * Preserve explicitly quoted empty strings as empty strings in nested output.
+     *
+     * @remarks
+     * This option applies to values such as `""` (or the configured quote character equivalent).
+     *
+     * @default true
+     */
+    preserveEmptyString?: boolean;
+    /**
      * Maximum number of records to parse.
@@ -641,2 +660,6 @@ * Parsing stops after this limit is reached.
 
+declare const QUOTED_EMPTY_CELL: unique symbol;
+type InternalCsvCellValue = string | typeof QUOTED_EMPTY_CELL;
+type InternalCsvRecord = Record<string, InternalCsvCellValue>;
+
 /**
@@ -677,2 +700,11 @@ * Low-level CSV parsing utilities.
     /**
+     * Parse CSV content with internal quoted-empty provenance tracking.
+     *
+     * @internal
+     */
+    static parseWithQuotedEmptyProvenance(content: string, options?: CsvParserOptions): InternalCsvRecord[];
+    private static parseInternal;
+    private static createRecord;
+    private static toPublicRecord;
+    /**
      * Strip BOM (Byte Order Mark) from the beginning of content.
@@ -724,2 +756,4 @@ * Handles UTF-8 and UTF-16 BOMs.
     static parseLine(line: string, delimiter?: string, quote?: string): string[];
+    static parseLine(line: string, delimiter: string, quote: string, preserveQuotedEmpty: boolean): InternalCsvCellValue[];
+    private static finalizeParsedCellValue;
     /**
@@ -960,2 +994,3 @@ * Detect duplicate headers and process them according to the strategy.
     private bufferGroupedRecord;
+    private hasIdentifierValue;
     /**
@@ -973,2 +1008,3 @@ * Flush buffered grouped records through NestedJsonConverter.
     private parseLine;
+    private finalizeParsedCellValue;
     /**
@@ -978,2 +1014,3 @@ * Create a record object from values array.
     private createRecord;
+    private toPublicRecord;
     /**
@@ -1273,2 +1310,3 @@ * Apply value transformations to a record.
 
+type ConvertibleCsvRecord = CsvRecord | InternalCsvRecord;
 /**
@@ -1322,3 +1360,4 @@ * Nested JSON conversion utilities.
      */
-    static convert(records: CsvRecord[], options?: CsvParserOptions): NestedObject[];
+    static convert(records: ConvertibleCsvRecord[], options?: CsvParserOptions): NestedObject[];
+    private static hasIdentifierValue;
     /**
@@ -1421,2 +1460,3 @@ * Apply value transformations (null detection, auto-parse numbers, booleans, dates, custom transformer).
     private static unflatten;
+    private static isEffectivelyEmptyValue;
     private static deepMerge;
@@ -1423,0 +1463,0 @@ private static checkIfAllKeysCollide;

package.json

 {
 	"name": "@cerios/csv-nested-json",
-	"version": "1.3.0",
+	"version": "1.3.1",
 	"author": "Ronald Veth - Cerios",
@@ -5,0 +5,0 @@ "description": "Parse CSV files into nested JSON objects with support for dot notation, arrays, and complex data structures",

README.md

@@ -639,2 +639,38 @@ # @cerios/csv-nested-json
 
+### Empty Value Preservation
+
+By default, unquoted empty values are omitted and explicitly quoted empty values are preserved. You can control each case independently.
+
+```typescript
+const csvContent = `id,emptyColumn,emptyQuoted
+1,,""`;
+
+// Preserve only unquoted empties: ,, -> ''
+const preserveColumns = CsvParser.parseString(csvContent, {
+  preserveEmptyColumnAsEmptyString: true,
+  preserveEmptyString: false
+});
+// [{ id: "1", emptyColumn: "" }]
+
+// Preserve only quoted empties: "" -> ''
+const preserveQuoted = CsvParser.parseString(csvContent, {
+  preserveEmptyString: true
+});
+// [{ id: "1", emptyQuoted: "" }]
+
+// Preserve both
+const preserveBoth = CsvParser.parseString(csvContent, {
+  preserveEmptyColumnAsEmptyString: true,
+  preserveEmptyString: true
+});
+// [{ id: "1", emptyColumn: "", emptyQuoted: "" }]
+```
+
+When multiple options apply, precedence is:
+
+1. `defaultValues`
+2. `nullValues` + `nullRepresentation`
+3. `preserveEmptyColumnAsEmptyString` / `preserveEmptyString`
+4. Omit
+
 ### Null Value Handling
@@ -933,2 +969,6 @@
 
+  // Empty value preservation
+  preserveEmptyColumnAsEmptyString?: boolean;     // Preserve unquoted empties: ,,
+  preserveEmptyString?: boolean;                  // Preserve quoted empties: ""
+
   // Row grouping
@@ -1144,2 +1184,16 @@ identifierColumn?: string;                      // Column for grouping continuation rows
 
+#### `preserveEmptyColumnAsEmptyString`
+
+Preserve unquoted empty columns (for example `,,`) as `''` in nested output.
+
+- Default: `false`
+
+#### `preserveEmptyString`
+
+Preserve explicitly quoted empty strings (for example `""` with the default quote character) as `''` in nested output.
+
+- Default: `true`
+
+Both options work for `CsvParser` and `CsvStreamParser`. Set `preserveEmptyString: false` if you want quoted empties omitted.
+
 ### Complete Example with All Options
@@ -1194,3 +1248,7 @@
   // Defaults
-  defaultValues: { status: 'pending' }
+  defaultValues: { status: 'pending' },
+
+  // Empty value preservation
+  preserveEmptyColumnAsEmptyString: true,
+  preserveEmptyString: true
 });
@@ -1197,0 +1255,0 @@ ```

No alert changes

Improved metrics

Total package byte prevSize

660119

5.21%

Lines of code

6415

4.11%

Number of lines in readme file

1684

3.57%

No dependency changes