csv-stream-lite 0.1.0

package/dist/stringify.js

@@ -0,0 +1,186 @@
+const UTF_8_BOM = '\uFEFF';
+/**
+ * CSV stringifier class for converting JavaScript objects into CSV format.
+ * Supports both synchronous and asynchronous streaming of CSV output.
+ *
+ * @typeParam T - The input object type
+ * @typeParam O - The output object type after optional transformation (defaults to T)
+ *
+ * @example
+ * ```typescript
+ * const data = [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]
+ * const stringifier = new CsvStringify(data, { headers: ['name', 'age'] })
+ * const csvString = stringifier.toString()
+ * ```
+ */
+export class CsvStringify {
+    values;
+    headers;
+    delimiter;
+    escapeChar;
+    quoteChar;
+    newline;
+    writeBom;
+    alwaysWriteHeaders;
+    transform;
+    /**
+     * Creates a new CSV stringifier.
+     *
+     * @param values - Iterable or async iterable of objects to stringify
+     * @param options - Optional configuration for CSV stringification
+     */
+    constructor(values, options) {
+        this.values = values;
+        this.headers = options?.headers
+            ? Array.isArray(options.headers)
+                ? options.headers
+                : Object.keys(options.headers)
+            : undefined;
+        this.delimiter = options?.delimiter ?? ',';
+        this.escapeChar = options?.escapeChar ?? '"';
+        this.quoteChar = options?.quoteChar ?? '"';
+        this.newline = options?.newline ?? '\n';
+        this.writeBom = options?.writeBom ?? false;
+        this.alwaysWriteHeaders = options?.alwaysWriteHeaders ?? false;
+        this.transform = options?.transform;
+    }
+    formatField(field) {
+        const needsQuoting = field.includes(this.delimiter) ||
+            field.includes('\n') ||
+            field.includes('\r') ||
+            field.includes(this.quoteChar);
+        if (needsQuoting) {
+            field = field.replace(new RegExp(this.quoteChar, 'g'), this.escapeChar + this.quoteChar);
+            field = this.quoteChar + field + this.quoteChar;
+        }
+        return field;
+    }
+    *recordToString(record, firstRecord) {
+        let index = 0;
+        if (this.transform) {
+            record = this.transform(record);
+        }
+        const recordKeys = Object.keys(record);
+        const headers = this.headers ?? recordKeys;
+        if (firstRecord) {
+            // Output header row
+            for (const header of headers) {
+                const fieldStr = this.formatField(header);
+                if (index > 0) {
+                    yield this.delimiter;
+                }
+                yield fieldStr;
+                index++;
+            }
+            yield this.newline;
+            index = 0;
+        }
+        for (let i = 0; i < headers.length; i++) {
+            const fieldStr = this.formatField(String(record[recordKeys[i]] ?? ''));
+            if (index > 0) {
+                yield this.delimiter;
+            }
+            yield fieldStr;
+            index++;
+        }
+    }
+    *forceWriteHeaders() {
+        if (this.headers) {
+            let index = 0;
+            for (const header of this.headers) {
+                const fieldStr = this.formatField(header);
+                if (index > 0) {
+                    yield this.delimiter;
+                }
+                yield fieldStr;
+                index++;
+            }
+        }
+    }
+    /**
+     * Returns a synchronous generator that yields CSV string chunks.
+     *
+     * @returns A generator that yields CSV strings
+     * @throws {Error} If values is not iterable
+     */
+    *toStream() {
+        if (!(Symbol.iterator in this.values)) {
+            throw new Error('Values is not iterable');
+        }
+        if (this.writeBom) {
+            yield UTF_8_BOM;
+        }
+        let firstRecord = true;
+        for (const record of this.values) {
+            if (!firstRecord) {
+                yield this.newline;
+            }
+            yield* this.recordToString(record, firstRecord);
+            firstRecord = false;
+        }
+        if (firstRecord && this.alwaysWriteHeaders) {
+            yield* this.forceWriteHeaders();
+        }
+    }
+    /**
+     * Returns an asynchronous generator that yields CSV string chunks.
+     *
+     * @returns An async generator that yields CSV strings
+     */
+    async *toStreamAsync() {
+        if (this.writeBom) {
+            yield UTF_8_BOM;
+        }
+        let firstRecord = true;
+        for await (const record of this.values) {
+            if (!firstRecord) {
+                yield this.newline;
+            }
+            yield* this.recordToString(record, firstRecord);
+            firstRecord = false;
+        }
+        if (firstRecord && this.alwaysWriteHeaders) {
+            yield* this.forceWriteHeaders();
+        }
+    }
+    /**
+     * Converts all values to a single CSV string synchronously.
+     *
+     * @returns The complete CSV string
+     */
+    toString() {
+        let result = '';
+        for (const chunk of this) {
+            result += chunk;
+        }
+        return result;
+    }
+    /**
+     * Converts all values to a single CSV string asynchronously.
+     *
+     * @returns A promise that resolves to the complete CSV string
+     */
+    async toStringAsync() {
+        let result = '';
+        for await (const chunk of this) {
+            result += chunk;
+        }
+        return result;
+    }
+    /**
+     * Makes this stringifier iterable using the synchronous stream.
+     *
+     * @returns A generator that yields CSV strings
+     */
+    [Symbol.iterator]() {
+        return this.toStream();
+    }
+    /**
+     * Makes this stringifier async iterable using the asynchronous stream.
+     *
+     * @returns An async generator that yields CSV strings
+     */
+    [Symbol.asyncIterator]() {
+        return this.toStreamAsync();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A utility type to prevent TypeScript from inferring a type parameter.
+ */
+export type CsvString<T = unknown> = string & {
+    __csvStringBrand?: T;
+};
+/**
+ * Union type representing valid stream input formats.
+ */
+export type StreamInput<T = unknown> = CsvString<T> | number | number[] | Uint8Array;
+/**
+ * An async iterable stream of JSON input that can be consumed incrementally.
+ * Supports strings, numbers, arrays of numbers, or Uint8Arrays as stream items.
+ */
+export type ByteStream<T = unknown> = AsyncIterable<StreamInput<T>> | Iterable<StreamInput<T>> | ReadableStream<StreamInput<T>>;
+/**
+ * Defines the shape of a CSV object by mapping each property key to a transformer function.
+ * The transformer function converts a cell string into the appropriate type for that property.
+ *
+ * @typeParam T - The object type being defined
+ *
+ * @example
+ * ```typescript
+ * const shape: CsvObjectShape<User> = {
+ *   name: String,
+ *   age: Number,
+ *   active: Boolean
+ * }
+ * ```
+ */
+export type CsvObjectShape<T extends object> = {
+    [key in keyof T]: (cell: string) => T[key];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Converts a string to a Uint8Array of UTF-8 encoded bytes.
+ *
+ * @param str - The string to convert
+ * @returns A Uint8Array containing the UTF-8 encoded bytes
+ */
+export declare function stringToBytes(str: string): Uint8Array;
+/**
+ * Converts a Uint8Array of UTF-8 encoded bytes to a string.
+ *
+ * @param bytes - The Uint8Array to decode
+ * @returns The decoded string
+ */
+export declare function bytesToString(bytes: Uint8Array): string;

package/dist/utils.js

@@ -0,0 +1,20 @@
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/**
+ * Converts a string to a Uint8Array of UTF-8 encoded bytes.
+ *
+ * @param str - The string to convert
+ * @returns A Uint8Array containing the UTF-8 encoded bytes
+ */
+export function stringToBytes(str) {
+    return textEncoder.encode(str);
+}
+/**
+ * Converts a Uint8Array of UTF-8 encoded bytes to a string.
+ *
+ * @param bytes - The Uint8Array to decode
+ * @returns The decoded string
+ */
+export function bytesToString(bytes) {
+    return textDecoder.decode(bytes);
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "csv-stream-lite",
+  "version": "0.1.0",
+  "description": "A lightweight, memory-efficient, zero-dependency streaming JSON parser and stringifier for JavaScript and TypeScript. It works in both Node.js and browser environments.",
+  "main": "dist/index.js",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/jacobshirley/csv-stream-lite.git"
+  },
+  "homepage": "https://jacobshirley.github.io/csv-stream-lite/v1",
+  "bugs": {
+    "url": "https://github.com/jacobshirley/csv-stream-lite/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*"
+    }
+  },
+  "keywords": [
+    "json",
+    "stream",
+    "streaming",
+    "parser",
+    "stringify",
+    "parse",
+    "incremental",
+    "async",
+    "memory-efficient",
+    "low-memory",
+    "large-files",
+    "json-parser",
+    "csv-stream",
+    "streaming-json",
+    "lightweight",
+    "zero-dependencies",
+    "typescript",
+    "browser",
+    "nodejs"
+  ],
+  "author": "Jacob Shirley",
+  "license": "MIT",
+  "devDependencies": {
+    "@vitest/browser": "^4.0.16",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitest/coverage-v8": "^4.0.16",
+    "playwright": "^1.57.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo",
+    "EXAMPLES.md"
+  ],
+  "scripts": {
+    "test:unit": "vitest run test/unit",
+    "test": "vitest run",
+    "compile": "pnpm compile:validate && tsc -p tsconfig.prod.json",
+    "compile:validate": "tsc -p tsconfig.json --noEmit",
+    "watch": "tsc -watch -p tsconfig.prod.json",
+    "watch:all": "tsc -watch -p tsconfig.json"
+  }
+}