feat(csv): infer column names from object arrays for stringify()

csv/stringify.ts

@@ -108,9 +108,9 @@ export type StringifyOptions = {
    * column of output. This is also where you can provide an explicit header
    * name for the column.
    *
-   * @default {[]}
+   * @default {undefined}
    */
-  columns?: readonly Column[];
+  columns?: readonly Column[] | undefined;
   /**
    * Whether to add a
    * {@link https://en.wikipedia.org/wiki/Byte_order_mark | byte-order mark} to the
@@ -429,7 +429,7 @@ export function stringify(
   data: readonly DataItem[],
   options?: StringifyOptions,
 ): string {
-  const { headers = true, separator: sep = ",", columns = [], bom = false } =
+  const { headers = true, separator: sep = ",", columns, bom = false } =
     options ?? {};
 
   if (sep.includes(QUOTE) || sep.includes(CRLF)) {
@@ -441,7 +441,12 @@ export function stringify(
     throw new TypeError(message);
   }
 
-  const normalizedColumns = columns.map(normalizeColumn);
+  if (columns && !Array.isArray(columns)) {
+    throw new TypeError("Invalid type: columns can only be an array.");
+  }
+
+  const definedColumns = columns ?? inferColumns(data);
+  const normalizedColumns = definedColumns.map(normalizeColumn);
   let output = "";
 
   if (bom) {
@@ -465,3 +470,19 @@ export function stringify(
 
   return output;
 }
+
+/**
+ * Infers the columns from the first object element of the given array.
+ */
+function inferColumns(data: readonly DataItem[]) {
+  const firstElement = data.at(0);
+  if (
+    firstElement &&
+    typeof firstElement === "object" &&
+    !Array.isArray(firstElement)
+  ) {
+    return Object.keys(firstElement);
+  }
+
+  return [];
+}

csv/stringify_stream.ts

@@ -99,7 +99,7 @@ export class CsvStringifyStream<TOptions extends CsvStringifyStreamOptions>
    * @param options Options for the stream.
    */
   constructor(options?: TOptions) {
-    const { separator, columns = [] } = options ?? {};
+    const { separator, columns } = options ?? {};
 
     super(
       {

csv/stringify_stream_test.ts

@@ -64,7 +64,7 @@ Deno.test({
       await assertRejects(
         async () => await Array.fromAsync(readable),
         TypeError,
-        "No property accessor function was provided for object",
+        "Invalid type: columns can only be an array.",
       );
     });
 
@@ -90,10 +90,12 @@ Deno.test({
         { id: 3, name: "baz" },
         // @ts-expect-error `columns` option is required
       ]).pipeThrough(new CsvStringifyStream());
-      await assertRejects(
-        async () => await Array.fromAsync(readable),
-        TypeError,
-      );
+      const output = await Array.fromAsync(readable);
+      assertEquals(output, [
+        "1,foo\r\n",
+        "2,bar\r\n",
+        "3,baz\r\n",
+      ]);
     });
   },
 });

csv/stringify_test.ts

@@ -72,33 +72,6 @@ Deno.test({
         },
       },
     );
-
-    await t.step(
-      {
-        name: "Invalid data, no columns",
-        fn() {
-          const data = [{ a: 1 }, { a: 2 }];
-          assertThrows(
-            () => stringify(data),
-            TypeError,
-            "No property accessor function was provided for object",
-          );
-        },
-      },
-    );
-    await t.step(
-      {
-        name: "Invalid data, no columns",
-        fn() {
-          const data = [{ a: 1 }, { a: 2 }];
-          assertThrows(
-            () => stringify(data),
-            TypeError,
-            "No property accessor function was provided for object",
-          );
-        },
-      },
-    );
     await t.step(
       {
         name: "No data, no columns",
@@ -591,5 +564,26 @@ Deno.test({
         });
       },
     });
+    await t.step(
+      {
+        name: "Object array with no columns, should infer columns",
+        fn() {
+          const data = [{ a: 1 }, { a: 2 }, { b: 3 }];
+          const output = `a${CRLF}1${CRLF}2${CRLF}${CRLF}`;
+          assertEquals(stringify(data), output);
+        },
+      },
+    );
+    await t.step(
+      {
+        name: "Object array with columns, shouldn't infer columns",
+        fn() {
+          const data = [{ a: 1 }, { a: 2 }, { b: 3 }];
+          const columns = ["a"];
+          const output = `a${CRLF}1${CRLF}2${CRLF}${CRLF}`;
+          assertEquals(stringify(data, { columns }), output);
+        },
+      },
+    );
   },
 });