Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
Add import CSV format helpers (#2413)
Leendert de Borst50a3bd1f89ae
diff --git a/core/client/src/importexport/csv/CsvImport.ts b/core/client/src/importexport/csv/CsvImport.tsnew file mode 100644index 000000000..de7a4e81c--- /dev/null+++ b/core/client/src/importexport/csv/CsvImport.ts@@ -0,0 +1,45 @@+import { readCsvRecords, type CsvColumns, type CsvRecord } from './CsvRecordMapper';++/**+ * Decode uploaded file bytes into text.+ * @param fileBytes - The raw bytes of the uploaded file+ * @returns The decoded file content+ */+export function decodeFileContent(fileBytes: Uint8Array): string {+ if (fileBytes[0] === 0xFF && fileBytes[1] === 0xFE) {+ return new TextDecoder('utf-16le').decode(fileBytes);+ }+ if (fileBytes[0] === 0xFE && fileBytes[1] === 0xFF) {+ return new TextDecoder('utf-16be').decode(fileBytes);+ }+ return new TextDecoder('utf-8').decode(fileBytes);+}++/**+ * Read the records of a password manager's CSV export. Headers match ignoring case and spaces, and every+ * non-empty text field is passed through the optional field decoder.+ * @param fileContent - The CSV file content+ * @param columns - The columns to read+ * @param decodeField - Decodes one text field, for exports with their own escaping on top of CSV+ * @returns The records+ * @throws {Error} When the file holds no records.+ */+export function readImportCsv<C extends CsvColumns>(fileContent: string, columns: C, decodeField?: (value: string) => string): CsvRecord<C>[] {+ const records = readCsvRecords(fileContent, columns, header => header.toLowerCase().trim().replace(/ /g, ''));+ if (records.length === 0) {+ throw new Error('No records found in the CSV file.');+ }+ if (!decodeField) {+ return records;+ }++ for (const record of records) {+ const fields = record as Record<string, unknown>;+ for (const [key, value] of Object.entries(fields)) {+ if (typeof value === 'string' && value.length > 0) {+ fields[key] = decodeField(value);+ }+ }+ }+ return records;+}diff --git a/core/client/src/importexport/csv/CsvParser.ts b/core/client/src/importexport/csv/CsvParser.tsnew file mode 100644index 000000000..d841eff72--- /dev/null+++ b/core/client/src/importexport/csv/CsvParser.ts@@ -0,0 +1,58 @@+/*+ * CSV parser utility.+ */++/**+ * Split CSV text into rows of fields. Blank lines are skipped, a byte order mark is ignored.+ * @param content - The CSV text+ * @returns The rows, each an array of field values+ */+export function parseCsvRows(content: string): string[][] {+ const text = content.charCodeAt(0) === 0xFEFF ? content.substring(1) : content;+ const rows: string[][] = [];+ let row: string[] = [];+ let field = '';+ let i = 0;++ while (i < text.length) {+ const c = text[i];+ if (c === '"' && field === '') {+ i++;+ while (i < text.length && !(text[i] === '"' && isFieldEnd(text, i + 1))) {+ field += text[i];+ i += text[i] === '"' && text[i + 1] === '"' ? 2 : 1;+ }+ i++;+ } else if (c === ',') {+ row.push(field);+ field = '';+ i++;+ } else if (c === '\r' || c === '\n') {+ i += c === '\r' && text[i + 1] === '\n' ? 2 : 1;+ if (row.length > 0 || field !== '') {+ row.push(field);+ rows.push(row);+ }+ row = [];+ field = '';+ } else {+ field += c;+ i++;+ }+ }+ if (row.length > 0 || field !== '') {+ row.push(field);+ rows.push(row);+ }+ return rows;+}++/**+ * Whether the field ends at `i`: a delimiter, a line break or the end of the text.+ * @param text - The CSV text+ * @param i - The index to check+ * @returns True when a field ends there+ */+function isFieldEnd(text: string, i: number): boolean {+ return i >= text.length || text[i] === ',' || text[i] === '\r' || text[i] === '\n';+}diff --git a/core/client/src/importexport/csv/CsvRecordMapper.ts b/core/client/src/importexport/csv/CsvRecordMapper.tsnew file mode 100644index 000000000..28c817934--- /dev/null+++ b/core/client/src/importexport/csv/CsvRecordMapper.ts@@ -0,0 +1,71 @@+import { parseDateTime } from '../utils/DateTimeUtils';++import { parseCsvRows } from './CsvParser';++/**+ * Reads one column's text into a value; the text is undefined when the file lacks the column.+ */+export type CsvColumn<T> = (raw: string | undefined) => T;++/**+ * The columns of a record, keyed by their header.+ */+export type CsvColumns = Record<string, CsvColumn<unknown>>;++/**+ * The record type the columns read into.+ */+export type CsvRecord<C extends CsvColumns> = { [K in keyof C]: ReturnType<C[K]> };++/**+ * A text column; the empty string when the file lacks it.+ * @param raw - The column text+ * @returns The text+ */+export const text: CsvColumn<string> = (raw: string | undefined): string => raw ?? '';++/**+ * A text column; null when the file lacks it.+ * @param raw - The column text+ * @returns The text, or null+ */+export const optionalText: CsvColumn<string | null> = (raw: string | undefined): string | null => raw ?? null;++/**+ * A date/time column; null when absent, blank or unparseable.+ * @param raw - The column text+ * @returns The date, or null+ */+export const dateTime: CsvColumn<Date | null> = (raw: string | undefined): Date | null => parseDateTime(raw);++/**+ * Read typed records from CSV text with a header row. Each column is found by its key; columns the file lacks read+ * as undefined, extra columns are ignored and the first of two columns with the same header wins.+ * @param content - The CSV text+ * @param columns - The columns to read, keyed by header+ * @param normalizeHeader - Applied to both sides before headers are matched; exact matching by default+ * @returns The records, one per data row+ */+export function readCsvRecords<C extends CsvColumns>(content: string, columns: C, normalizeHeader: (header: string) => string = (header): string => header): CsvRecord<C>[] {+ const [headerRow, ...dataRows] = parseCsvRows(content);+ if (!headerRow) {+ return [];+ }++ const headerIndexes = new Map<string, number>();+ headerRow.forEach((header, index) => {+ const key = normalizeHeader(header);+ if (!headerIndexes.has(key)) {+ headerIndexes.set(key, index);+ }+ });++ const indexedColumns = Object.entries(columns).map(([key, read]) => ({ key, read, index: headerIndexes.get(normalizeHeader(key)) }));+ return dataRows.map(row => {+ const record: Record<string, unknown> = {};+ for (const { key, read, index } of indexedColumns) {+ record[key] = read(index === undefined ? undefined : row[index]);+ }+ return record as CsvRecord<C>;+ });+}diff --git a/core/client/src/importexport/csv/CsvWriter.ts b/core/client/src/importexport/csv/CsvWriter.tsnew file mode 100644index 000000000..4a920c81f--- /dev/null+++ b/core/client/src/importexport/csv/CsvWriter.ts@@ -0,0 +1,21 @@+/**+ * Quote a field when needed: it contains a quote, the delimiter or a line break, or starts or ends with+ * a space.+ * @param value - The field value+ * @returns The field as it appears in the file+ */+export function escapeCsvField(value: string): string {+ const needsQuotes = value.includes('"') || value.includes(',') || value.includes('\r') || value.includes('\n') || value.startsWith(' ') || value.endsWith(' ');+ return needsQuotes ? `"${value.replace(/"/g, '""')}"` : value;+}++/**+ * Write rows as CSV text with CRLF line endings.+ * @param headers - The header row+ * @param rows - The data rows, each in header order+ * @returns The CSV text+ */+export function writeCsv(headers: string[], rows: string[][]): string {+ const lines = [headers, ...rows].map(row => row.map(escapeCsvField).join(','));+ return `${lines.join('\r\n')}\r\n`;+}