csv-stream-lite 0.1.0

package/EXAMPLES.md

@@ -0,0 +1,197 @@
+# csv-stream-Lite Examples
+
+This directory contains example scripts demonstrating how to use the csv-stream-Lite library.
+
+## Basic CSV streaming example
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const csvData = `name,age,city
+Alice,30,New York
+Bob,25,Los Angeles
+Charlie,35,Chicago`
+
+for await (const row of new Csv(csvData).streamObjectsAsync()) {
+    console.log(row)
+}
+
+// Output:
+// { name: 'Alice', age: '30', city: 'New York' }
+// { name: 'Bob', age: '25', city: 'Los Angeles' }
+// { name: 'Charlie', age: '35', city: 'Chicago' }
+```
+
+## Low-level CSV streaming example
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const csvData = `name,age,city
+Alice,30,New York
+Bob,25,Los Angeles
+Charlie,35,Chicago`
+
+let i = 0
+
+const csvStream = new Csv(csvData)
+for await (const row of csvStream) {
+    for await (const cell of row) {
+        if (i++ % 2 === 0) {
+            continue
+        }
+        for await (const char of cell) {
+            // Write each character to stdout as we read it
+            process.stdout.write(char)
+        }
+        process.stdout.write('\n')
+    }
+}
+
+// Output:
+// age
+// Alice
+// New York
+// 25
+// Charlie
+// Chicago
+
+// Note: There are no delimiters or newlines in the output because we are
+// writing each cell directly as we read it.
+```
+
+## Type Coercion Example
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const csvData = `name,age,city
+Alice,30,New York
+Bob,25,Los Angeles
+Charlie,35,Chicago`
+
+// Define a schema for type coercion
+const schema = {
+    name: String,
+    age: Number,
+    city: String,
+}
+
+for await (const row of new Csv(csvData, {
+    shape: schema,
+}).streamObjectsAsync()) {
+    console.log(row)
+    // TypeScript infers the type of `row` as:
+    // {
+    //     name: string;
+    //     age: number;
+    //     city: string;
+    // }
+}
+
+// Output:
+// { name: 'Alice', age: 30, city: 'New York' }
+// { name: 'Bob', age: 25, city: 'Los Angeles' }
+// { name: 'Charlie', age: 35, city: 'Chicago' }
+```
+
+## Object to CSV stringification example
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const data = [
+    { name: 'Alice', age: 30, city: 'New York' },
+    { name: 'Bob', age: 25, city: 'Los Angeles' },
+    { name: 'Charlie', age: 35, city: 'Chicago' },
+]
+
+const csvString = Csv.stringifier(data).toString()
+console.log(csvString)
+
+// Output:
+// name,age,city
+// Alice,30,New York
+// Bob,25,Los Angeles
+// Charlie,35,Chicago
+```
+
+## Object to CSV stringification streaming example
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const data = [
+    { name: 'Alice', age: 30, city: 'New York' },
+    { name: 'Bob', age: 25, city: 'Los Angeles' },
+    { name: 'Charlie', age: 35, city: 'Chicago' },
+]
+
+const csvStream = Csv.stringify(data)
+for (const chunk of csvStream) {
+    process.stdout.write(chunk)
+}
+
+process.stdout.write('\n')
+
+// Output:
+// name,age,city
+// Alice,30,New York
+// Bob,25,Los Angeles
+// Charlie,35,Chicago
+```
+
+## Transforming parsed CSV data before further processing
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const csvData = `first_name,last_name,age
+Alice,Smith,30
+Bob,Johnson,25`
+
+const csvStream = new Csv(csvData, {
+    transform: (record: {
+        first_name: string
+        last_name: string
+        age: string
+    }) => ({
+        fullName: `${record.first_name} ${record.last_name}`,
+        age: Number(record.age),
+    }),
+})
+
+for await (const row of csvStream.streamObjectsAsync()) {
+    console.log(row)
+}
+
+// Output:
+// { fullName: 'Alice Smith', age: 30 }
+// { fullName: 'Bob Johnson', age: 25 }
+```
+
+## Transform CSV data during stringification
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const data = [
+    { name: 'Alice', age: 30, city: 'New York' },
+    { name: 'Bob', age: 25, city: 'Los Angeles' },
+]
+
+const csvStringifier = Csv.stringifier(data, {
+    transform: (row) => ({
+        fullName: row.name.toUpperCase(),
+        ageInFiveYears: row.age + 5,
+        city: row.city,
+        cityWithCountry: `${row.city}, USA`,
+    }),
+})
+
+console.log(csvStringifier.toString())
+// Expected output:
+// fullName,ageInFiveYears,city,cityWithCountry
+// ALICE,35,New York,"New York, USA"
+// BOB,30,Los Angeles,"Los Angeles, USA"
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacob Shirley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+**[Examples](./EXAMPLES.md)** | **[Documentation](https://jacobshirley.github.io/csv-stream-lite/v1)**
+
+# csv-stream-lite
+
+A lightweight, memory-efficient, zero-dependency streaming CSV parser and stringifier written in TypeScript. Process large CSV files without loading them entirely into memory.
+
+[![npm version](https://img.shields.io/npm/v/csv-stream-lite.svg)](https://www.npmjs.com/package/csv-stream-lite)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🚀 **Zero Dependencies** - No external dependencies
+- 💪 **TypeScript First** - Written in TypeScript with full type safety
+- 🌊 **Streaming Support** - Process large CSV files without loading them into memory
+- ⚡ **High Performance** - Efficient byte-level parsing
+- 🔄 **Dual Mode** - Both synchronous and asynchronous APIs
+- 🌐 **Universal** - Works in Node.js and browser environments
+- 📝 **Flexible** - Support for custom delimiters, escape characters, and transformers
+- ✅ **Well Tested** - Comprehensive test coverage
+
+## Installation
+
+```bash
+npm install csv-stream-lite
+```
+
+```bash
+yarn add csv-stream-lite
+```
+
+```bash
+pnpm add csv-stream-lite
+```
+
+## Quick Start
+
+### Parsing CSV
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+// Parse CSV string
+const csvData = `name,age,city
+Alice,30,New York
+Bob,25,Los Angeles`
+
+const csv = new Csv(csvData, { readHeaders: true })
+
+// Sync streaming
+for (const row of csv.streamObjects()) {
+    console.log(row) // { name: 'Alice', age: '30', city: 'New York' }
+}
+
+// Async streaming (for large files)
+for await (const row of csv.streamObjectsAsync()) {
+    console.log(row)
+}
+```
+
+### Parsing with Type Transformers
+
+```typescript
+import { Csv, CsvObjectShape } from 'csv-stream-lite'
+
+interface User {
+    name: string
+    age: number
+    active: boolean
+}
+
+const shape: CsvObjectShape<User> = {
+    name: String,
+    age: Number,
+    active: Boolean,
+}
+
+const csv = new Csv<User>(fileStream, { shape })
+
+for await (const user of csv.streamObjectsAsync()) {
+    console.log(user.age) // Typed as number
+}
+```
+
+### Stringifying to CSV
+
+```typescript
+import { Csv } from 'csv-stream-lite'
+
+const data = [
+    { name: 'Alice', age: 30, city: 'New York' },
+    { name: 'Bob', age: 25, city: 'Los Angeles' },
+]
+
+// Sync
+for (const chunk of Csv.stringify(data, { headers: ['name', 'age', 'city'] })) {
+    process.stdout.write(chunk)
+}
+
+// Async
+for await (const chunk of Csv.stringifyAsync(data)) {
+    process.stdout.write(chunk)
+}
+
+// Or get complete string
+const csvString = new CsvStringify(data).toString()
+```
+
+## API Documentation
+
+Full API documentation is available at [https://jacobshirley.github.io/csv-stream-lite/v1](https://jacobshirley.github.io/csv-stream-lite/v1)
+
+## Advanced Usage
+
+### Reading from File Stream (Node.js)
+
+```typescript
+import { createReadStream } from 'fs'
+import { Csv } from 'csv-stream-lite'
+
+const fileStream = createReadStream('large-file.csv')
+
+const csv = new Csv(fileStream, { readHeaders: true })
+
+for await (const row of csv.streamObjectsAsync()) {
+    // Process each row without loading entire file into memory
+    console.log(row)
+}
+```
+
+### Custom Delimiters
+
+```typescript
+// Tab-separated values
+const csv = new Csv(tsvData, {
+    separator: '\t',
+    readHeaders: true,
+})
+
+// Semicolon-separated values
+const csv = new Csv(csvData, {
+    separator: ';',
+    readHeaders: true,
+})
+```
+
+### Strict Column Validation
+
+```typescript
+import { Csv, TooManyColumnsError, TooFewColumnsError } from 'csv-stream-lite'
+
+const csvData = `name,age,city
+Alice,30,New York
+Bob,25,Los Angeles,ExtraColumn`
+
+const csv = new Csv(csvData, {
+    headers: ['name', 'age', 'city'],
+    strictColumns: true, // Throws error if column count doesn't match
+})
+
+try {
+    for await (const row of csv.streamObjectsAsync()) {
+        console.log(row)
+    }
+} catch (error) {
+    if (error instanceof TooManyColumnsError) {
+        console.error('Row has too many columns')
+    } else if (error instanceof TooFewColumnsError) {
+        console.error('Row has too few columns')
+    }
+}
+```
+
+### Row Transformation
+
+```typescript
+const csv = new Csv(csvData, {
+    readHeaders: true,
+    transform: (row) => ({
+        ...row,
+        fullName: `${row.firstName} ${row.lastName}`,
+        age: Number(row.age),
+    }),
+})
+```
+
+### Writing to File Stream (Node.js)
+
+```typescript
+import { createWriteStream } from 'fs'
+import { CsvStringify } from 'csv-stream-lite'
+
+const writeStream = createWriteStream('output.csv')
+
+const data = [
+    { name: 'Alice', age: 30 },
+    { name: 'Bob', age: 25 },
+]
+
+const stringifier = new CsvStringify(data, {
+    headers: ['name', 'age'],
+})
+
+for await (const chunk of stringifier) {
+    writeStream.write(chunk)
+}
+
+writeStream.end()
+```
+
+## Error Handling
+
+The library provides specific error types for different scenarios:
+
+- `CsvStreamLiteError` - Base error class
+- `NoMoreTokensError` - Buffer is empty and more input is needed
+- `EofReachedError` - End of file reached
+- `BufferSizeExceededError` - Buffer size limit exceeded
+- `TooManyColumnsError` - Row has more columns than expected (when `strictColumns: true`)
+- `TooFewColumnsError` - Row has fewer columns than expected (when `strictColumns: true`)
+
+## Performance
+
+csv-stream-lite is designed for memory efficiency and high performance:
+
+- **Streaming Architecture**: Process files of any size with constant memory usage
+- **Lazy Evaluation**: Data is only parsed as it's consumed
+- **Byte-Level Parsing**: Efficient low-level parsing without intermediate string allocations
+- **Chunked Processing**: Configurable chunk sizes for optimal performance
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import { Csv, CsvObjectShape } from 'csv-stream-lite'
+
+interface User {
+    id: number
+    name: string
+    email: string
+    active: boolean
+}
+
+const shape: CsvObjectShape<User> = {
+    id: Number,
+    name: String,
+    email: String,
+    active: Boolean,
+}
+
+const csv = new Csv<User>(data, { shape })
+
+// Type-safe iteration
+for await (const user of csv.streamObjectsAsync()) {
+    console.log(user.id) // TypeScript knows this is a number
+}
+```
+
+## Browser Support
+
+csv-stream-lite works in modern browsers with support for:
+
+- `ReadableStream` API
+- `AsyncIterable` protocol
+- ES2018+ features
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [Jacob Shirley](https://github.com/jacobshirley)

package/dist/byte-buffer.d.ts

@@ -0,0 +1,112 @@
+import type { ByteStream, StreamInput } from './types.js';
+/**
+ * A buffer for managing byte-level input with support for async streams.
+ * Provides lookahead, consumption tracking, and buffer compaction capabilities.
+ */
+export declare class ByteBuffer {
+    /** Maximum size of the buffer before compaction */
+    maxBufferSize: number;
+    /** Whether end of file has been signaled */
+    eof: boolean;
+    /** Current position in the buffer */
+    bufferIndex: number;
+    /** Whether the buffer is locked against compaction */
+    locked: boolean;
+    /** Whether to allow exceeding the buffer size temporarily */
+    allowBufferToBeExceeded: boolean;
+    /** Current position in the input stream */
+    protected inputOffset: number;
+    /** Number of outputs generated */
+    protected outputOffset: number;
+    /** Buffer holding input items */
+    protected buffer: number[];
+    /** Optional async iterable input source */
+    protected asyncIterable?: ByteStream;
+    /**
+     * Creates a new ByteBuffer instance.
+     *
+     * @param asyncIterable - Optional async iterable source for streaming input
+     */
+    constructor(asyncIterable?: ByteStream);
+    /**
+     * Reads data from the stream into the buffer.
+     * Reads up to maxBufferSize bytes at a time.
+     */
+    readStream(): boolean;
+    /**
+     * Reads data from the sync or async stream into the buffer.
+     * Reads up to maxBufferSize bytes at a time.
+     */
+    readStreamAsync(): Promise<void>;
+    /**
+     * Gets the current length of the buffer.
+     *
+     * @returns The number of bytes in the buffer
+     */
+    get length(): number;
+    /**
+     * Feeds input items into the parser buffer.
+     *
+     * @param input - Input items to add to the buffer
+     */
+    feed(...input: StreamInput[]): void;
+    push(byte: number): void;
+    /**
+     * Checks if end of file has been reached and buffer is exhausted.
+     *
+     * @returns True if no more input is available
+     */
+    atEof(): boolean;
+    /**
+     * Peeks at an item in the buffer without consuming it.
+     *
+     * @param ahead - Number of positions to look ahead (default: 0)
+     * @returns The item at the peek position, or null if at EOF
+     * @throws NoMoreTokensError if more input is needed and EOF not signaled
+     */
+    peek(ahead?: number): number | null;
+    /**
+     * Consumes and returns the next item from the buffer.
+     *
+     * @returns The next item
+     * @throws NoMoreTokensError if more input is needed and EOF not signaled
+     * @throws EofReachedError if at EOF and no more items available
+     */
+    next(): number;
+    /**
+     * Consumes and validates the next item against an expected type or value.
+     *
+     * @typeParam T - The expected item type
+     * @param itemType - Constructor or value to match against
+     * @returns The consumed item cast to the expected type
+     * @throws Error if the item doesn't match the expected type/value
+     */
+    expect<T extends number>(itemType: T): T;
+    /**
+     * Compacts the buffer by removing consumed items
+     */
+    compact(): void;
+    /**
+     * Override to customize when to compact the buffer
+     * By default, compacts when more than maxBufferSize bytes have been consumed
+     *
+     * @returns boolean indicating whether to compact the buffer
+     */
+    canCompact(): boolean;
+    /**
+     * Attempts to execute a function, resetting buffer position on failure.
+     * Useful for speculative parsing attempts that may need to be retried.
+     *
+     * @typeParam T - The return type of the try function
+     * @param tryFn - Function to attempt execution
+     * @param onFail - Optional callback invoked on failure
+     * @returns The result of tryFn if successful, undefined if NoMoreTokensError thrown
+     */
+    resetOnFail<T>(tryFn: () => T, onFail?: (e: Error) => void): T | undefined;
+    /**
+     * Returns a string representation of the buffer state for debugging.
+     *
+     * @returns A formatted string showing buffer contents and state
+     */
+    toString(): string;
+}