@verifyhash/csv-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# csv-lite
+
+<!-- publish-prep -->
+> **TODO (owner): pick the final npm name/scope before publishing.**
+> The npm name is **not** finalized. `package.json` uses the placeholder
+> `PLACEHOLDER-csv-lite` — replace it with the real published name/scope
+> before any `npm publish`. Graduation to a package registry is a
+> **needs-human** decision, not something this project does on its own.
+
+A tiny, **zero-dependency, zero-network** Node.js library for **RFC 4180** CSV:
+parse a CSV string into rows (or objects), and turn rows back into CSV text with
+minimal, correct quoting. One CommonJS file (`index.js`), no install step, no
+I/O — drop it into any project and `require` it.
+
+Spec reference: <https://www.rfc-editor.org/rfc/rfc4180>
+
+## Who it's for
+
+JavaScript/Node developers who need to read or write CSV correctly — quoted
+fields, commas and newlines inside quotes, `""` escapes, `;`/tab delimiters,
+CRLF vs LF — **without** pulling in a larger parser like
+[`csv-parse`](https://www.npmjs.com/package/csv-parse) or
+[`papaparse`](https://www.npmjs.com/package/papaparse) and their footprint.
+Good for build scripts, CLIs, small ETL glue, tests, config import/export, and
+anywhere you want auditable, single-file CSV handling.
+
+If you need to stream gigabyte files, sniff the delimiter automatically, coerce
+types, or handle malformed-quote recovery, use one of the full packages above.
+This library deliberately covers the well-formed RFC 4180 common case.
+
+## Install / use
+
+No install — copy `index.js`, or `require` it directly:
+
+```js
+const csv = require('./index.js');
+
+// parse -> 2D array of strings
+csv.parse('a,"b,c",d');
+// [['a', 'b,c', 'd']]
+
+// parse with header -> array of objects keyed by the first row
+csv.parse('name,age\nAlice,30\nBob,25', { header: true });
+// [{ name: 'Alice', age: '30' }, { name: 'Bob', age: '25' }]
+
+// stringify a 2D array (quotes only where required)
+csv.stringify([['x', 'y,z', 'q"1']]);
+// 'x,"y,z","q""1"'
+
+// stringify array-of-objects with an explicit column order
+csv.stringify(
+  [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }],
+  { columns: ['name', 'age'] }
+);
+// 'name,age\nAlice,30\nBob,25'
+
+// custom delimiter (semicolon, tab, pipe, ...)
+csv.parse('a;b;c', { delimiter: ';' });   // [['a', 'b', 'c']]
+```
+
+Complements the browser-based [/csv-to-json/](https://polyatic.com/csv-to-json/)
+hub tool: same RFC 4180 rules, but as a reusable Node module.
+
+## API
+
+### `parse(text, options) → string[][] | object[]`
+
+Parse CSV text into rows. Every value is returned as a **string** — no type
+coercion.
+
+Options:
+
+| option      | default | meaning                                                        |
+| ----------- | ------- | -------------------------------------------------------------- |
+| `delimiter` | `','`   | Single-character field separator (e.g. `';'`, `'\t'`, `'\|'`). |
+| `header`    | `false` | When `true`, use the first row as keys and return objects.     |
+
+What it handles per RFC 4180:
+
+- **Quoted fields** — a field wrapped in `"..."`; the delimiter, `CR`, `LF`, and
+  `CRLF` are literal data inside the quotes.
+- **Embedded delimiters** — `a,"b,c",d` → `['a', 'b,c', 'd']`.
+- **Embedded newlines** — `"line1\nline2"` stays one field; the row is not split.
+- **Doubled-quote escapes** — `""` inside a quoted field is one literal `"`.
+- **CRLF and LF** record separators, including mixed within one document.
+- **A single trailing newline** is ignored — it does not produce an extra empty
+  record. (A blank line *in the middle* of the data is a real one-field row `['']`.)
+- **Empty input** (`''`) returns `[]`.
+
+With `header: true`, the first row becomes the object keys and the remaining
+rows become objects. A header-only document returns `[]`.
+
+### `stringify(rows, options) → string`
+
+Serialize rows to CSV text. Output uses `LF` (`\n`) record separators and has
+**no trailing newline**.
+
+Options:
+
+| option      | default | meaning                                                                   |
+| ----------- | ------- | ------------------------------------------------------------------------- |
+| `delimiter` | `','`   | Single-character field separator.                                         |
+| `columns`   | —       | When given, `rows` is an **array of objects**; emits a header row of these names first, then projects each object onto them in order. |
+
+Quoting rule: a field is quoted **only when it must be** — it contains the
+delimiter, a double-quote, `CR`, or `LF`. Embedded double-quotes are escaped by
+doubling (`"` → `""`). Non-string values are coerced with `String()`;
+`null`/`undefined` become an empty, unquoted field.
+
+`parse` and `stringify` are exact inverses for well-formed data — see the
+`parse -> stringify -> parse` stability test in `test/index.test.js`.
+
+## Limits (please read)
+
+This is an honest, deliberately small library. It does **not** do everything a
+full CSV package does:
+
+- **No streaming.** `parse(text)` takes a complete string and returns the fully
+  materialized result in memory; `stringify(rows)` builds the whole output
+  string. This is explicitly **out of scope** — for files too large to fit in
+  memory, use a streaming parser such as `csv-parse`. As a rough guide, keep
+  inputs to something comfortably under available RAM (tens of MB is fine; multi-
+  gigabyte files are not what this is for).
+- **RFC 4180 subset.** It targets well-formed RFC 4180. It does **not** attempt
+  recovery from malformed quoting (e.g. a `"` in the middle of an unquoted
+  field, or an unterminated quote — an unterminated quoted field simply runs to
+  end-of-input). There is no automatic delimiter detection, no comment-line
+  (`#`) skipping, no BOM stripping, and no quote/escape-character customization
+  (the quote character is always `"`).
+- **Ragged rows are preserved, not normalized, in array mode.** `parse` in the
+  default (non-header) mode returns each row exactly as many fields as it had —
+  it does **not** pad or truncate rows to a uniform width, so different rows may
+  have different lengths. Only in `header: true` mode are objects shaped by the
+  header: rows with **fewer** cells than the header get `''` for the missing
+  keys, and any **extra** cells beyond the header width are dropped.
+- **Strings only, no type coercion.** `"30"` stays the string `"30"`; there is
+  no number/boolean/date inference. Convert types yourself after parsing.
+
+## Running the tests
+
+One command, Node's built-in `assert` only — no test runner, no dependencies:
+
+```sh
+node test/index.test.js
+```
+
+It prints `csv-lite: all N tests passed.` and exits `0` on success. Fixtures
+cover embedded delimiters, embedded newlines inside quotes, doubled-quote
+escapes, header-mode object round-trip, custom delimiters (`;` and tab), CRLF vs
+LF, and a `parse -> stringify -> parse` round-trip that is byte-stable.
+
+## License
+
+MIT — see `LICENSE`.

package/index.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * csv-lite — a zero-dependency, zero-network RFC 4180 CSV parser and
+ * stringifier for Node.js.
+ *
+ * No I/O, no streaming, no dependencies. Two pure functions over strings:
+ *   parse(text, options)      -> 2D array of strings, or array of objects
+ *   stringify(rows, options)  -> CSV text
+ *
+ * Spec reference: https://www.rfc-editor.org/rfc/rfc4180
+ *
+ * Streaming is explicitly OUT OF SCOPE: parse() takes a complete string and
+ * returns the fully materialized result. For multi-gigabyte files that will
+ * not fit in memory, use a streaming parser such as `csv-parse`.
+ */
+
+// ---------------------------------------------------------------------------
+// parse
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CSV text into rows.
+ *
+ * @param {string} text        The CSV document.
+ * @param {object} [options]
+ * @param {string} [options.delimiter=','] Single-character field delimiter.
+ * @param {boolean} [options.header=false] When true, treat the first row as a
+ *        header and return an array of objects keyed by the header names.
+ * @returns {string[][] | Object<string,string>[]}
+ *
+ * Behavior (RFC 4180):
+ *  - Fields may be wrapped in double quotes. Inside a quoted field, the
+ *    delimiter, CR, LF and CRLF are literal data.
+ *  - A double-quote inside a quoted field is written as two double-quotes ("").
+ *  - Records are separated by CRLF or LF (both accepted, mixed is fine).
+ *  - A single trailing newline at the end of the document is ignored (it does
+ *    not produce an extra empty record).
+ *  - Every value is returned as a string; no type coercion is performed.
+ *  - Empty input ("") yields an empty array ([]).
+ */
+function parse(text, options) {
+  options = options || {};
+  const delimiter = options.delimiter == null ? ',' : options.delimiter;
+  const header = !!options.header;
+
+  if (typeof text !== 'string') {
+    throw new TypeError('csv-lite: parse(text) expects a string');
+  }
+  if (typeof delimiter !== 'string' || delimiter.length !== 1) {
+    throw new TypeError('csv-lite: delimiter must be a single character');
+  }
+  if (delimiter === '"' || delimiter === '\r' || delimiter === '\n') {
+    throw new TypeError('csv-lite: delimiter may not be a quote or newline');
+  }
+
+  const rows = [];
+  let field = '';
+  let row = [];
+  let inQuotes = false;
+  // Tracks whether the current record has produced any content at all, so we
+  // can distinguish a genuine empty trailing record from the ignorable
+  // trailing newline.
+  let sawAnyChar = false;
+  const len = text.length;
+
+  for (let i = 0; i < len; i++) {
+    const ch = text[i];
+
+    if (inQuotes) {
+      if (ch === '"') {
+        // Either an escaped quote ("") or the closing quote.
+        if (i + 1 < len && text[i + 1] === '"') {
+          field += '"';
+          i++; // consume the second quote of the pair
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += ch;
+      }
+      continue;
+    }
+
+    if (ch === '"') {
+      inQuotes = true;
+      sawAnyChar = true;
+      continue;
+    }
+
+    if (ch === delimiter) {
+      row.push(field);
+      field = '';
+      sawAnyChar = true;
+      continue;
+    }
+
+    if (ch === '\r') {
+      // Handle CRLF as a single record separator; a lone CR also ends a record.
+      if (i + 1 < len && text[i + 1] === '\n') i++;
+      row.push(field);
+      rows.push(row);
+      field = '';
+      row = [];
+      sawAnyChar = false;
+      continue;
+    }
+
+    if (ch === '\n') {
+      row.push(field);
+      rows.push(row);
+      field = '';
+      row = [];
+      sawAnyChar = false;
+      continue;
+    }
+
+    field += ch;
+    sawAnyChar = true;
+  }
+
+  // Flush the final record. We emit it unless the document ended exactly on a
+  // record separator (trailing newline) with nothing after it.
+  if (sawAnyChar || field !== '' || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+
+  if (!header) return rows;
+
+  // header:true -> array of objects keyed by the first row.
+  if (rows.length === 0) return [];
+  const keys = rows[0];
+  const out = [];
+  for (let r = 1; r < rows.length; r++) {
+    const src = rows[r];
+    const obj = {};
+    for (let c = 0; c < keys.length; c++) {
+      // Ragged rows: missing trailing cells become '' (empty string); this
+      // keeps every object shaped by the header rather than by the data row.
+      obj[keys[c]] = c < src.length ? src[c] : '';
+    }
+    out.push(obj);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// stringify
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize rows to CSV text.
+ *
+ * @param {Array} rows  A 2D array of cell values, OR an array of objects when
+ *        `columns` is provided.
+ * @param {object} [options]
+ * @param {string} [options.delimiter=','] Single-character field delimiter.
+ * @param {string[]} [options.columns] When given, `rows` is treated as an
+ *        array of objects; a header row of these column names is emitted first
+ *        and each object is projected onto them in order.
+ * @returns {string} CSV text with LF (\n) record separators and no trailing
+ *        newline.
+ *
+ * Quoting: a field is quoted ONLY when it must be — it contains the delimiter,
+ * a double-quote, CR, or LF. Embedded double-quotes are escaped by doubling.
+ * Non-string values are coerced with String(); null/undefined become '' (an
+ * empty, unquoted field).
+ */
+function stringify(rows, options) {
+  options = options || {};
+  const delimiter = options.delimiter == null ? ',' : options.delimiter;
+  const columns = options.columns;
+
+  if (!Array.isArray(rows)) {
+    throw new TypeError('csv-lite: stringify(rows) expects an array');
+  }
+  if (typeof delimiter !== 'string' || delimiter.length !== 1) {
+    throw new TypeError('csv-lite: delimiter must be a single character');
+  }
+  if (delimiter === '"' || delimiter === '\r' || delimiter === '\n') {
+    throw new TypeError('csv-lite: delimiter may not be a quote or newline');
+  }
+
+  const needsQuote = (s) =>
+    s.indexOf(delimiter) !== -1 ||
+    s.indexOf('"') !== -1 ||
+    s.indexOf('\n') !== -1 ||
+    s.indexOf('\r') !== -1;
+
+  const cell = (value) => {
+    let s;
+    if (value == null) s = '';
+    else s = String(value);
+    if (needsQuote(s)) {
+      return '"' + s.replace(/"/g, '""') + '"';
+    }
+    return s;
+  };
+
+  const lines = [];
+
+  if (columns) {
+    if (!Array.isArray(columns)) {
+      throw new TypeError('csv-lite: columns must be an array of names');
+    }
+    // Header row.
+    lines.push(columns.map(cell).join(delimiter));
+    // Object rows projected onto columns.
+    for (const obj of rows) {
+      const src = obj || {};
+      lines.push(columns.map((key) => cell(src[key])).join(delimiter));
+    }
+  } else {
+    for (const row of rows) {
+      if (!Array.isArray(row)) {
+        throw new TypeError(
+          'csv-lite: without `columns`, each row must be an array'
+        );
+      }
+      lines.push(row.map(cell).join(delimiter));
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { parse, stringify };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@verifyhash/csv-lite",
+  "version": "0.1.0",
+  "description": "Zero-dependency RFC 4180 CSV parser and stringifier for Node.js: quoted fields, embedded delimiters/newlines, doubled-quote escapes, header-object mode, custom delimiters.",
+  "keywords": [
+    "csv",
+    "rfc4180",
+    "parse",
+    "stringify",
+    "delimiter",
+    "quote",
+    "tsv",
+    "header",
+    "zero-dependency"
+  ],
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "csv-lite"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/csv-lite#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}