docs(csv): more examples for stringify and CsvStringifyStream (#5606)

csv/stringify.ts

@@ -219,23 +219,99 @@ function getValuesFromItem(
 /**
  * Converts an array of objects into a CSV string.
  *
- * @example Usage
+ * @example Default options
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [
+ *   ["Rick", 70],
+ *   ["Morty", 14],
+ * ];
+ *
+ * assertEquals(stringify(data), `Rick,70\r\nMorty,14\r\n`);
+ * ```
+ *
+ * @example Give an array of objects and specify columns
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [
+ *   { name: "Rick", age: 70 },
+ *   { name: "Morty", age: 14 },
+ * ];
+ *
+ * const columns = ["name", "age"];
+ *
+ * assertEquals(stringify(data, { columns }), `name,age\r\nRick,70\r\nMorty,14\r\n`);
+ * ```
+ *
+ * @example Give an array of objects without specifying columns
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertThrows } from "@std/assert/throws";
+ *
+ * const data = [
+ *   { name: "Rick", age: 70 },
+ *   { name: "Morty", age: 14 },
+ * ];
+ *
+ * assertThrows(
+ *   () => stringify(data),
+ *   TypeError,
+ *   "No property accessor function was provided for object",
+ * );
+ * ```
+ *
+ * @example Give an array of objects and specify columns with `headers: false`
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [
+ *   { name: "Rick", age: 70 },
+ *   { name: "Morty", age: 14 },
+ * ];
+ *
+ * const columns = ["name", "age"];
+ *
+ * assertEquals(
+ *   stringify(data, { columns, headers: false }),
+ *  `Rick,70\r\nMorty,14\r\n`,
+ * );
+ * ```
+ *
+ * @example Give an array of objects and specify columns with renaming
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [
+ *   { name: "Rick", age: 70 },
+ *   { name: "Morty", age: 14 },
+ * ];
+ *
+ * const columns = [
+ *   { prop: "name", header: "user name" },
+ *   "age",
+ * ];
+ *
+ * assertEquals(
+ *   stringify(data, { columns }),
+ *  `user name,age\r\nRick,70\r\nMorty,14\r\n`,
+ * );
+ * ```
+ *
+ * @example Give an array of objects with nested property and specify columns
  * ```ts
  * import {
  *   Column,
  *   stringify,
  * } from "@std/csv/stringify";
- * import { assertEquals } from "@std/assert";
+ * import { assertEquals } from "@std/assert/equals";
  *
- * type Character = {
- *   age: number;
- *   name: {
- *     first: string;
- *     last: string;
- *   };
- * };
- *
- * const data: Character[] = [
+ * const data = [
  *   {
  *     age: 70,
  *     name: {
@@ -252,12 +328,96 @@ function getValuesFromItem(
  *   },
  * ];
  *
- * let columns: Column[] = [
+ * const columns: Column[] = [
  *   ["name", "first"],
  *   "age",
  * ];
  *
- * assertEquals(stringify(data, { columns }), `first,age\r\nRick,70\r\nMorty,14\r\n`);
+ * assertEquals(
+ *   stringify(data, { columns }),
+ *  `first,age\r\nRick,70\r\nMorty,14\r\n`,
+ * );
+ * ```
+ *
+ * @example Give an array of objects with nested property and specify columns
+ * with renaming
+ * ```ts
+ * import {
+ *   Column,
+ *   stringify,
+ * } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [
+ *   {
+ *     age: 70,
+ *     name: {
+ *       first: "Rick",
+ *       last: "Sanchez",
+ *     },
+ *   },
+ *   {
+ *     age: 14,
+ *     name: {
+ *       first: "Morty",
+ *       last: "Smith",
+ *     },
+ *   },
+ * ];
+ *
+ * const columns: Column[] = [
+ *   { prop: ["name", "first"], header: "first name" },
+ *   "age",
+ * ];
+ *
+ * assertEquals(
+ *   stringify(data, { columns }),
+ *  `first name,age\r\nRick,70\r\nMorty,14\r\n`,
+ * );
+ * ```
+ *
+ * @example Give an array of string arrays and specify columns with renaming
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [
+ *   ["Rick", 70],
+ *   ["Morty", 14],
+ * ];
+ *
+ * const columns = [
+ *   { prop: 0, header: "name" },
+ *   { prop: 1, header: "age" },
+ * ];
+ *
+ * assertEquals(
+ *   stringify(data, { columns }),
+ *  `name,age\r\nRick,70\r\nMorty,14\r\n`,
+ * );
+ * ```
+ *
+ * @example Emit TSV (tab-separated values) with `separator: "\t"`
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [
+ *   ["Rick", 70],
+ *   ["Morty", 14],
+ * ];
+ *
+ * assertEquals(stringify(data, { separator: "\t" }), `Rick\t70\r\nMorty\t14\r\n`);
+ * ```
+ *
+ * @example Prepend a byte-order mark with `bom: true`
+ * ```ts
+ * import { stringify } from "@std/csv/stringify";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const data = [["Rick", 70]];
+ *
+ * assertEquals(stringify(data, { bom: true }), "\ufeffRick,70\r\n");
  * ```
  *
  * @param data The source data to stringify. It's an array of items which are

csv/stringify_stream.ts

@@ -24,23 +24,65 @@ export interface CsvStringifyStreamOptions {
 /**
  * Convert each chunk to a CSV record.
  *
- * @example Usage
- * ```ts no-assert
+ * @example Write CSV to a file
+ * ```ts
  * import { CsvStringifyStream } from "@std/csv/stringify-stream";
+ * import { assertEquals } from "@std/assert/equals";
  *
- * const path = await Deno.makeTempFile();
+ * async function writeCsvToTempFile(): Promise<string> {
+ *   const path = await Deno.makeTempFile();
+ *   using file = await Deno.open(path, { write: true });
  *
- * const file = await Deno.open(path, { create: true, write: true });
- * const readable = ReadableStream.from([
- *   { id: 1, name: "one" },
- *   { id: 2, name: "two" },
- *   { id: 3, name: "three" },
- * ]);
+ *   const readable = ReadableStream.from([
+ *     { id: 1, name: "one" },
+ *     { id: 2, name: "two" },
+ *     { id: 3, name: "three" },
+ *   ]);
  *
- * await readable
- *   .pipeThrough(new CsvStringifyStream({ columns: ["id", "name"] }))
- *   .pipeThrough(new TextEncoderStream())
- *   .pipeTo(file.writable);
+ *   await readable
+ *     .pipeThrough(new CsvStringifyStream({ columns: ["id", "name"] }))
+ *     .pipeThrough(new TextEncoderStream())
+ *     .pipeTo(file.writable);
+ *
+ *   return path;
+ * }
+ *
+ * const path = await writeCsvToTempFile();
+ * const content = await Deno.readTextFile(path);
+ * assertEquals(content, "id,name\r\n1,one\r\n2,two\r\n3,three\r\n");
+ * ```
+ *
+ * @example Write TSV to a file
+ * ```ts
+ * import { CsvStringifyStream } from "@std/csv/stringify-stream";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * async function writeTsvToTempFile(): Promise<string> {
+ *   const path = await Deno.makeTempFile();
+ *   using file = await Deno.open(path, { write: true });
+ *
+ *   const readable = ReadableStream.from([
+ *     { id: 1, name: "one" },
+ *     { id: 2, name: "two" },
+ *     { id: 3, name: "three" },
+ *   ]);
+ *
+ *   await readable
+ *     .pipeThrough(
+ *       new CsvStringifyStream({
+ *         columns: ["id", "name"],
+ *         separator: "\t",
+ *       }),
+ *     )
+ *     .pipeThrough(new TextEncoderStream())
+ *     .pipeTo(file.writable);
+ *
+ *   return path;
+ * }
+ *
+ * const path = await writeTsvToTempFile();
+ * const content = await Deno.readTextFile(path);
+ * assertEquals(content, "id\tname\r\n1\tone\r\n2\ttwo\r\n3\tthree\r\n");
  * ```
  *
  * @typeParam TOptions The type of options for the stream.