Harden CSV export API

Author: Recoveredd

README.md

@@ -110,6 +110,8 @@ jsonToCsv(rows, {
 });
 ```
 
+The generic API accepts normal TypeScript interfaces; your row type does not need an index signature.
+
 ## CSV safety
 
 Values are escaped according to normal CSV rules:
@@ -128,7 +130,7 @@ name,note
 ""Line 2"""
 ```
 
-When exporting to spreadsheets, use `escapeFormulae` to reduce formula-injection risk:
+When exporting to spreadsheets, use `escapeFormulae` to reduce formula-injection risk. Values that start with a formula marker, even after leading whitespace, are prefixed before CSV escaping:
 
 ```ts
 jsonToCsv([{ value: '=SUM(A1:A2)' }], {

src/escape.ts

@@ -23,5 +23,5 @@ export function escapeCsvCell(value: string, options: EscapeCsvCellOptions = {})
 }
 
 function startsLikeFormula(value: string): boolean {
-  return /^[=+\-@\t\r]/.test(value);
+  return /^\s*[=+\-@]/.test(value) || /^[\t\r]/.test(value);
 }

src/flatten.ts

@@ -1,6 +1,6 @@
 import type { CsvRecord } from './types.js';
 
-export function flattenRecord(record: CsvRecord, separator = '.'): CsvRecord {
+export function flattenRecord(record: object, separator = '.'): CsvRecord {
   const output: CsvRecord = {};
   flattenInto(record, '', output, separator, new WeakSet<object>());
   return output;

src/index.ts

@@ -3,7 +3,6 @@ import { flattenRecord, isPlainObject } from './flatten.js';
 import type {
   CsvColumnInput,
   CsvPrimitive,
-  CsvRecord,
   JsonToCsvOptions,
   ResolvedCsvColumn,
   ResolvedJsonToCsvOptions
@@ -15,13 +14,14 @@ export type {
   CsvColumnInput,
   CsvPrimitive,
   CsvRecord,
-  JsonToCsvOptions
+  JsonToCsvOptions,
+  ResolvedCsvColumn
 } from './types.js';
 
 export { escapeCsvCell } from './escape.js';
 export { flattenRecord } from './flatten.js';
 
-export function jsonToCsv<TRecord extends CsvRecord>(
+export function jsonToCsv<TRecord extends object>(
   records: readonly TRecord[],
   options: JsonToCsvOptions<TRecord> = {}
 ): string {
@@ -60,15 +60,15 @@ export function jsonToCsv<TRecord extends CsvRecord>(
 
 export const toCsv = jsonToCsv;
 
-export function inferCsvColumns<TRecord extends CsvRecord>(
+export function inferCsvColumns<TRecord extends object>(
   records: readonly TRecord[],
   options: Pick<JsonToCsvOptions<TRecord>, 'flatten' | 'sortColumns'> = {}
 ): Array<ResolvedCsvColumn<TRecord>> {
   const resolved = resolveOptions(options);
   return resolveColumns(assertRecords(records), resolved);
 }
 
-function resolveOptions<TRecord extends CsvRecord>(
+function resolveOptions<TRecord extends object>(
   options: JsonToCsvOptions<TRecord>
 ): ResolvedJsonToCsvOptions<TRecord> {
   const delimiter = options.delimiter ?? ',';
@@ -111,7 +111,7 @@ function resolveOptions<TRecord extends CsvRecord>(
   };
 }
 
-function assertRecords<TRecord extends CsvRecord>(records: readonly TRecord[]): readonly TRecord[] {
+function assertRecords<TRecord extends object>(records: readonly TRecord[]): readonly TRecord[] {
   if (!Array.isArray(records)) {
     throw new TypeError('json-csv-kit expects an array of records.');
   }
@@ -125,7 +125,7 @@ function assertRecords<TRecord extends CsvRecord>(records: readonly TRecord[]):
   return records;
 }
 
-function resolveColumns<TRecord extends CsvRecord>(
+function resolveColumns<TRecord extends object>(
   records: readonly TRecord[],
   options: ResolvedJsonToCsvOptions<TRecord>
 ): Array<ResolvedCsvColumn<TRecord>> {
@@ -136,7 +136,7 @@ function resolveColumns<TRecord extends CsvRecord>(
   const keys = new Set<string>();
 
   for (const record of records) {
-    const source = options.flatten ? flattenRecord(record) : record;
+    const source: object = options.flatten ? flattenRecord(record) : record;
 
     for (const key of Object.keys(source)) {
       keys.add(key);
@@ -156,7 +156,7 @@ function resolveColumns<TRecord extends CsvRecord>(
   }));
 }
 
-function resolveColumn<TRecord extends CsvRecord>(
+function resolveColumn<TRecord extends object>(
   column: CsvColumnInput<TRecord>
 ): ResolvedCsvColumn<TRecord> {
   if (typeof column === 'string') {
@@ -176,7 +176,7 @@ function resolveColumn<TRecord extends CsvRecord>(
   };
 }
 
-function readColumnValue<TRecord extends CsvRecord>(
+function readColumnValue<TRecord extends object>(
   record: TRecord,
   column: ResolvedCsvColumn<TRecord>,
   index: number
@@ -188,9 +188,9 @@ function readColumnValue<TRecord extends CsvRecord>(
   return getPath(record, column.path);
 }
 
-function getPath(record: CsvRecord, path: string): unknown {
+function getPath(record: object, path: string): unknown {
   if (Object.hasOwn(record, path)) {
-    return record[path];
+    return (record as Record<string, unknown>)[path];
   }
 
   const segments = path.split('.');
@@ -201,13 +201,13 @@ function getPath(record: CsvRecord, path: string): unknown {
       return undefined;
     }
 
-    current = (current as CsvRecord)[segment];
+    current = (current as Record<string, unknown>)[segment];
   }
 
   return current;
 }
 
-function formatRow<TRecord extends CsvRecord>(
+function formatRow<TRecord extends object>(
   values: readonly string[],
   options: ResolvedJsonToCsvOptions<TRecord>
 ): string {
@@ -222,7 +222,7 @@ function formatRow<TRecord extends CsvRecord>(
     .join(options.delimiter);
 }
 
-function formatValue<TRecord extends CsvRecord>(
+function formatValue<TRecord extends object>(
   value: unknown,
   options: ResolvedJsonToCsvOptions<TRecord>
 ): string {
@@ -254,21 +254,40 @@ function formatValue<TRecord extends CsvRecord>(
 }
 
 function safeJsonStringify(value: unknown): string {
-  const seen = new WeakSet<object>();
+  return JSON.stringify(toJsonSafe(value, new WeakSet<object>())) ?? '';
+}
 
-  return JSON.stringify(value, (_key, child) => {
-    if (typeof child === 'bigint') {
-      return String(child);
-    }
+function toJsonSafe(value: unknown, seen: WeakSet<object>): unknown {
+  if (typeof value === 'bigint') {
+    return String(value);
+  }
 
-    if (child && typeof child === 'object') {
-      if (seen.has(child)) {
-        return '[Circular]';
-      }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
 
-      seen.add(child);
-    }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (seen.has(value)) {
+    return '[Circular]';
+  }
+
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    const output = value.map((item) => toJsonSafe(item, seen));
+    seen.delete(value);
+    return output;
+  }
+
+  const output: Record<string, unknown> = {};
+
+  for (const [key, child] of Object.entries(value)) {
+    output[key] = toJsonSafe(child, seen);
+  }
 
-    return child;
-  }) ?? '';
+  seen.delete(value);
+  return output;
 }

src/types.ts

@@ -4,7 +4,7 @@ export type CsvRecord = Record<string, unknown>;
 
 export type ArrayValueMode = 'json' | 'join' | 'empty';
 
-export interface CsvColumn<TRecord extends CsvRecord = CsvRecord> {
+export interface CsvColumn<TRecord extends object = CsvRecord> {
   /**
    * Stable column id and default source path.
    */
@@ -35,11 +35,11 @@ export interface CsvColumn<TRecord extends CsvRecord = CsvRecord> {
   formatter?: (value: unknown, record: TRecord, index: number) => CsvPrimitive;
 }
 
-export type CsvColumnInput<TRecord extends CsvRecord = CsvRecord> =
+export type CsvColumnInput<TRecord extends object = CsvRecord> =
   | string
   | CsvColumn<TRecord>;
 
-export interface JsonToCsvOptions<TRecord extends CsvRecord = CsvRecord> {
+export interface JsonToCsvOptions<TRecord extends object = CsvRecord> {
   /**
    * Explicit columns. When omitted, columns are inferred from records.
    */
@@ -123,7 +123,7 @@ export interface JsonToCsvOptions<TRecord extends CsvRecord = CsvRecord> {
   dateFormatter?: (date: Date) => string;
 }
 
-export interface ResolvedJsonToCsvOptions<TRecord extends CsvRecord = CsvRecord> {
+export interface ResolvedJsonToCsvOptions<TRecord extends object = CsvRecord> {
   columns?: Array<CsvColumnInput<TRecord>>;
   includeHeaders: boolean;
   flatten: boolean;
@@ -138,7 +138,7 @@ export interface ResolvedJsonToCsvOptions<TRecord extends CsvRecord = CsvRecord>
   dateFormatter: (date: Date) => string;
 }
 
-export interface ResolvedCsvColumn<TRecord extends CsvRecord = CsvRecord> {
+export interface ResolvedCsvColumn<TRecord extends object = CsvRecord> {
   key: string;
   header: string;
   path: string;

tests/index.test.ts

@@ -56,6 +56,30 @@ describe('json-csv-kit', () => {
     expect(csv).toBe('total\n$12.34');
   });
 
+  test('accepts typed interfaces without an index signature', () => {
+    interface Order {
+      customer: {
+        name: string;
+      };
+      totalCents: number;
+    }
+
+    const orders: Order[] = [{ customer: { name: 'Ada' }, totalCents: 1234 }];
+
+    expect(
+      jsonToCsv(orders, {
+        columns: [
+          { key: 'customer', path: 'customer.name' },
+          {
+            key: 'total',
+            accessor: (row) => row.totalCents,
+            formatter: (value) => `$${Number(value) / 100}`
+          }
+        ]
+      })
+    ).toBe('customer,total\nAda,$12.34');
+  });
+
   test('flattens nested plain objects by default', () => {
     expect(jsonToCsv([{ user: { name: 'Ada' } }])).toBe('user.name\nAda');
   });
@@ -85,6 +109,16 @@ describe('json-csv-kit', () => {
     expect(jsonToCsv([record])).toBe('id,self\n1,[Circular]');
   });
 
+  test('does not mark shared nested references as circular', () => {
+    const shared = { name: 'Ada' };
+
+    expect(
+      jsonToCsv([{ payload: { primary: shared, secondary: shared } }], {
+        flatten: false
+      })
+    ).toBe('payload\n"{""primary"":{""name"":""Ada""},""secondary"":{""name"":""Ada""}}"');
+  });
+
   test('can join arrays', () => {
     expect(jsonToCsv([{ tags: ['admin', 'ops'] }], { arrayMode: 'join' })).toBe(
       'tags\n"admin, ops"'
@@ -119,6 +153,12 @@ describe('json-csv-kit', () => {
     );
   });
 
+  test('escapes spreadsheet formula values after leading whitespace', () => {
+    expect(jsonToCsv([{ value: '  =SUM(A1:A2)' }], { escapeFormulae: true })).toBe(
+      "value\n'  =SUM(A1:A2)"
+    );
+  });
+
   test('sorts inferred columns when requested', () => {
     expect(jsonToCsv([{ b: 2, a: 1 }], { sortColumns: true })).toBe('a,b\n1,2');
   });