deepline 0.3.273 → 0.3.275

package/dist/bundling-sources/shared_libs/plays/table-csv.ts

@@ -0,0 +1,152 @@
+/**
+ * The one CSV writer for a Play table export, shared by the dashboard download
+ * (`GET /api/v2/plays/{name}/sheet/export`) and the CLI
+ * (`deepline runs export`), so the same table reads the same in either file.
+ * Pure: it runs on the server, in the browser (clipboard copy) and in the CLI.
+ *
+ * Cell rules: an empty value is an empty field, booleans are `true`/`false`,
+ * objects and arrays are compact JSON, and a field is quoted only when it has
+ * to be (RFC 4180).
+ *
+ * A failed row exports as written, and says why it failed: when any row of the
+ * export failed, every record ends with an `_error` column holding the row's
+ * failure reason (empty on a row that did not fail).
+ */
+
+/** The trailing column carrying a failed row's reason. */
+export const TABLE_EXPORT_ERROR_COLUMN = '_error';
+
+/** Legacy settled-sheet columns retained for existing CSV consumers. */
+export const TABLE_EXPORT_STATUS_COLUMN = 'row_status';
+export const TABLE_EXPORT_ROW_ERROR_COLUMN = 'row_error';
+
+/** What a failed row says when its writer recorded no reason. */
+const UNRECORDED_FAILURE_REASON = 'Row failed without a recorded reason.';
+
+/** A cell's raw value as text: objects as JSON, empty as ''. */
+export function tableCellText(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (
+    typeof value === 'number' ||
+    typeof value === 'bigint' ||
+    typeof value === 'boolean'
+  )
+    return String(value);
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'symbol' || typeof value === 'function') return '';
+  try {
+    return (
+      JSON.stringify(value, (_key, nested: unknown) =>
+        typeof nested === 'bigint' ? nested.toString() : nested,
+      ) ?? ''
+    );
+  } catch {
+    return String(value);
+  }
+}
+
+/** One RFC 4180 field: quoted (quotes doubled) when it holds `,` `"` or a newline. */
+export function csvField(value: unknown): string {
+  const text = tableCellText(value);
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+/** One CSV record, newline-terminated. */
+export function csvRecord(values: readonly unknown[]): string {
+  return `${values.map(csvField).join(',')}\n`;
+}
+
+/** A sheet row as an export reads it: its data, its status, its error. */
+export type TableExportRow = {
+  data: Record<string, unknown>;
+  status?: unknown;
+  error?: unknown;
+};
+
+function isFailedRow(row: { status?: unknown }): boolean {
+  return row.status === 'failed';
+}
+
+/** Whether any of these rows failed, so the export carries `_error`. */
+export function tableExportHasFailedRows(
+  rows: Iterable<{ status?: unknown }>,
+): boolean {
+  for (const row of rows) if (isFailedRow(row)) return true;
+  return false;
+}
+
+/** The `_error` cell of one row: its failure reason, or '' when it did not fail. */
+export function tableExportErrorCell(row: {
+  status?: unknown;
+  error?: unknown;
+}): string {
+  if (!isFailedRow(row)) return '';
+  const reason = typeof row.error === 'string' ? row.error.trim() : '';
+  return reason || UNRECORDED_FAILURE_REASON;
+}
+
+/** The export header: the table's columns, then `_error` when a row failed. */
+export function tableExportColumns(
+  columns: readonly string[],
+  withError: boolean,
+): string[] {
+  if (!withError) return [...columns];
+  return [
+    ...columns.filter((column) => column !== TABLE_EXPORT_ERROR_COLUMN),
+    TABLE_EXPORT_ERROR_COLUMN,
+  ];
+}
+
+/** One row's cells, in `tableExportColumns(columns, withError)` order. */
+export function tableExportCells(
+  row: TableExportRow,
+  columns: readonly string[],
+  withError: boolean,
+): unknown[] {
+  return tableExportColumns(columns, withError).map((column) =>
+    column === TABLE_EXPORT_ERROR_COLUMN && withError
+      ? tableExportErrorCell(row)
+      : Object.hasOwn(row.data, column)
+        ? row.data[column]
+        : undefined,
+  );
+}
+
+/**
+ * Settled dashboard downloads keep their established status/reason columns.
+ * The CLI's newer `_error` projection is separate; both use this module's CSV
+ * encoding so spreadsheet escaping and cell formatting stay consistent.
+ */
+export function tableExportSettledColumns(
+  columns: readonly string[],
+  withFailureDetails: boolean,
+): string[] {
+  return withFailureDetails
+    ? [...columns, TABLE_EXPORT_STATUS_COLUMN, TABLE_EXPORT_ROW_ERROR_COLUMN]
+    : [...columns];
+}
+
+/** A settled dashboard row, preserving the public `row_status,row_error` contract. */
+export function tableExportSettledCells(
+  row: TableExportRow,
+  columns: readonly string[],
+  withFailureDetails: boolean,
+): unknown[] {
+  const values = columns.map((column) =>
+    Object.hasOwn(row.data, column) ? row.data[column] : undefined,
+  );
+  return withFailureDetails
+    ? [...values, row.status, row.status === 'failed' ? (row.error ?? '') : '']
+    : values;
+}
+
+/** A whole table as CSV text: the header record, then one record per row. */
+export function tableCsvText(
+  header: readonly string[],
+  records: Iterable<readonly unknown[]>,
+): string {
+  let text = csvRecord(header);
+  for (const record of records) text += csvRecord(record);
+  return text;
+}