@classytic/primitives 0.26.4 → 0.27.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.27.0
+
+### Added — `./csv` subpath: one CSV cell escaper for the whole fleet
+
+`escapeCsvCell(value)` and `neutralizeCsvFormula(value)`. Six CSV producers
+across ledger, the spine and the hosts each hand-rolled RFC 4180 quoting, and
+not one neutralized a leading `= + - @ \t \r` — so a customer-supplied payment
+reference or party name reached the accountant's spreadsheet as a live formula.
+Quoting does not help: a spreadsheet strips the quotes and evaluates what is
+left, which is why the two defences ship as one module.
+
+The two functions are separable on purpose. A consumer holding a real CSV
+writer (`csv-stringify`) takes `neutralizeCsvFormula` only, so its quoting is
+not done twice; a hand-rolled `rows.map(...).join(',')` takes `escapeCsvCell`.
+
+**Well-formed numbers are exempt.** Prefixing `-1500` would make every negative
+amount text and break `SUM` in every finance export — a fix that quietly
+corrupts the product is worse than the hole. The exemption requires the WHOLE
+cell to be a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+
+Not for a machine-to-machine upload contract with a fixed column spec (a
+courier's bulk-import CSV): there the receiver is a parser, not a spreadsheet,
+and an added `'` corrupts the payload.
+
 ## 0.26.4
 
 ### Added — `./price-basis` subpath: measured pricing across physical dimensions

package/dist/csv.d.mts

@@ -0,0 +1,36 @@
+//#region src/serialization/csv.d.ts
+/**
+ * `@classytic/primitives/csv` — make one value safe to put in a CSV cell.
+ *
+ * Two defences, deliberately separable because a consumer that already has a
+ * real CSV writer must NOT get its quoting done twice:
+ *
+ *   - `neutralizeCsvFormula` — stops the cell being executed as a formula when
+ *     the file is opened in Excel / Sheets / LibreOffice. Use this when a
+ *     library (`csv-stringify`, `papaparse`, …) is doing the quoting.
+ *   - `escapeCsvCell` — neutralize + RFC 4180 quoting. Use this in a
+ *     hand-rolled `rows.map(...).join(',')` serializer.
+ *
+ * WHY quoting is not enough: a spreadsheet strips the quotes first and
+ * evaluates what is left, so `"=cmd|'/c calc'!A1"` still executes. Only
+ * changing the LEADING character stops it, which is why these are one module
+ * and not a quoting helper someone can use alone.
+ *
+ * Well-formed numbers are exempt. Prefixing `-1500` would make every negative
+ * amount text and break the reader's `SUM` — a fix that quietly corrupts every
+ * finance export is worse than the hole. The exemption is the WHOLE cell
+ * matching a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+ *
+ * NOT for a machine-to-machine upload contract with a fixed column spec (a
+ * courier's bulk-import CSV, say) — there the receiver is a parser, not a
+ * spreadsheet, and an added `'` corrupts the payload.
+ */
+/**
+ * Prefix `'` when the cell would otherwise be evaluated as a formula.
+ * `null`/`undefined` become `''`. Numbers are returned unchanged.
+ */
+declare function neutralizeCsvFormula(value: unknown): string;
+/** `neutralizeCsvFormula` + RFC 4180 quoting. The one-call form. */
+declare function escapeCsvCell(value: unknown): string;
+//#endregion
+export { escapeCsvCell, neutralizeCsvFormula };

package/dist/csv.mjs

@@ -0,0 +1,50 @@
+//#region src/serialization/csv.ts
+/**
+* `@classytic/primitives/csv` — make one value safe to put in a CSV cell.
+*
+* Two defences, deliberately separable because a consumer that already has a
+* real CSV writer must NOT get its quoting done twice:
+*
+*   - `neutralizeCsvFormula` — stops the cell being executed as a formula when
+*     the file is opened in Excel / Sheets / LibreOffice. Use this when a
+*     library (`csv-stringify`, `papaparse`, …) is doing the quoting.
+*   - `escapeCsvCell` — neutralize + RFC 4180 quoting. Use this in a
+*     hand-rolled `rows.map(...).join(',')` serializer.
+*
+* WHY quoting is not enough: a spreadsheet strips the quotes first and
+* evaluates what is left, so `"=cmd|'/c calc'!A1"` still executes. Only
+* changing the LEADING character stops it, which is why these are one module
+* and not a quoting helper someone can use alone.
+*
+* Well-formed numbers are exempt. Prefixing `-1500` would make every negative
+* amount text and break the reader's `SUM` — a fix that quietly corrupts every
+* finance export is worse than the hole. The exemption is the WHOLE cell
+* matching a number, so `-2+3+cmd|'/c calc'!A0` is still neutralized.
+*
+* NOT for a machine-to-machine upload contract with a fixed column spec (a
+* courier's bulk-import CSV, say) — there the receiver is a parser, not a
+* spreadsheet, and an added `'` corrupts the payload.
+*/
+/** Leading characters a spreadsheet may treat as the start of a formula or DDE call. */
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+/** The WHOLE cell is a plain number — no separators, no currency symbol. */
+const WHOLE_NUMBER = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+/** Characters that force RFC 4180 quoting. */
+const NEEDS_QUOTING = /[",\r\n]/;
+/**
+* Prefix `'` when the cell would otherwise be evaluated as a formula.
+* `null`/`undefined` become `''`. Numbers are returned unchanged.
+*/
+function neutralizeCsvFormula(value) {
+	const text = value == null ? "" : String(value);
+	if (!FORMULA_LEAD.test(text)) return text;
+	if (WHOLE_NUMBER.test(text)) return text;
+	return `'${text}`;
+}
+/** `neutralizeCsvFormula` + RFC 4180 quoting. The one-call form. */
+function escapeCsvCell(value) {
+	const text = neutralizeCsvFormula(value);
+	return NEEDS_QUOTING.test(text) ? `"${text.replace(/"/g, "\"\"")}"` : text;
+}
+//#endregion
+export { escapeCsvCell, neutralizeCsvFormula };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.26.4",
+  "version": "0.27.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -205,6 +205,10 @@
       "types": "./dist/canonical.d.mts",
       "default": "./dist/canonical.mjs"
     },
+    "./csv": {
+      "types": "./dist/csv.d.mts",
+      "default": "./dist/csv.mjs"
+    },
     "./package.json": "./package.json",
     "./state-diagram": {
       "types": "./dist/state-diagram.d.mts",