High-performance RFC 4180 compliant CSV parser with lazy mode for Bun. Parse 10M rows in 5s with minimal memory.
A high-performance, RFC 4180 compliant CSV parser written in Odin with Bun FFI support.
Platform Support:
Key Advantages:
Install OCSV as an npm package for easy integration with your Bun projects:
# Using Bun
bun add ocsv
# Using npm
npm install ocsv
Then use it in your project:
import { parseCSV } from 'ocsv';
// Parse CSV string
const result = parseCSV('name,age\nJohn,30\nJane,25', { hasHeader: true });
console.log(result.headers); // ['name', 'age']
console.log(result.rows); // [['John', '30'], ['Jane', '25']]
// Parse CSV file
import { parseCSVFile } from 'ocsv';
const data = await parseCSVFile('./data.csv', { hasHeader: true });
console.log(`Parsed ${data.rowCount} rows`);
For building from source or contributing:
git clone https://github.com/dvrd/ocsv.git
cd ocsv
Current Support: macOS ARM64 (cross-platform support in progress)
# Using Task (recommended)
task build # Build release library
task build-dev # Build debug library
task test # Run all tests
task info # Show platform info
# Manual build
odin build src -build-mode:shared -out:libocsv.dylib -o:speed
package main
import "core:fmt"
import ocsv "src"
main :: proc() {
// Create parser
parser := ocsv.parser_create()
defer ocsv.parser_destroy(parser)
// Parse CSV data
csv_data := "name,age,city\nAlice,30,NYC\nBob,25,SF\n"
ok := ocsv.parse_csv(parser, csv_data)
if ok {
// Access parsed data
fmt.printfln("Parsed %d rows", len(parser.all_rows))
for row in parser.all_rows {
for field in row {
fmt.printf("%s ", field)
}
fmt.printf("\n")
}
}
}
import { parseCSV } from 'ocsv';
// Parse CSV with headers
const result = parseCSV('name,age,city\nAlice,30,NYC\nBob,25,SF', {
hasHeader: true
});
console.log(result.headers); // ['name', 'age', 'city']
console.log(result.rows); // [['Alice', '30', 'NYC'], ['Bob', '25', 'SF']]
console.log(result.rowCount); // 2
import { parseCSVFile } from 'ocsv';
// Parse CSV file with headers
const data = await parseCSVFile('./sales.csv', {
hasHeader: true,
delimiter: ',',
});
console.log(`Parsed ${data.rowCount} rows`);
console.log(`Columns: ${data.headers.join(', ')}`);
// Process rows
for (const row of data.rows) {
console.log(row);
}
import { parseCSV } from 'ocsv';
// Parse TSV (tab-separated)
const tsvData = parseCSV('col1\tcol2\trow1\tdata', {
delimiter: '\t',
hasHeader: true,
});
// Parse with semicolon delimiter (European CSV)
const europeanData = parseCSV('name;age;city\nJohn;30;Paris', {
delimiter: ';',
hasHeader: true,
});
// Relaxed mode (allows some RFC violations)
const relaxedData = parseCSV('messy,csv,"data', {
relaxed: true,
});
For more control, use the Parser class directly:
import { Parser } from 'ocsv';
const parser = new Parser();
try {
const result = parser.parse('a,b,c\n1,2,3');
console.log(result.rows);
} finally {
parser.destroy(); // Important: free memory
}
OCSV offers two access modes to optimize for different use cases:
| Feature | Eager Mode (default) | Lazy Mode |
|---|---|---|
| Performance | ~8 MB/s throughput | ≥180 MB/s (22x faster) |
| Memory Usage | High (all data in JS) | Low (<200 MB for 10M rows) |
| Parse Time (10M rows) | ~150s | <7s (21x faster) |
| Access Pattern | Random access, arrays | Random access, on-demand |
| Memory Management | Automatic (GC) | Manual (destroy() required) |
| Best For | Small files, full iteration | Large files, selective access |
| TypeScript Support | Full | Full (discriminated unions) |
Best for: Small to medium files (<100k rows), full dataset iteration, simple workflows
All rows are materialized into JavaScript arrays immediately. Easy to use, no cleanup required.
import { parseCSV } from 'ocsv';
// Default: eager mode
const result = parseCSV(data, { hasHeader: true });
console.log(result.headers); // ['name', 'age', 'city']
console.log(result.rows); // [['Alice', '30', 'NYC'], ...]
console.log(result.rowCount); // 2
// Arrays: standard JavaScript operations
result.rows.forEach(row => console.log(row));
result.rows.map(row => row[0]);
result.rows.filter(row => row[1] > '25');
Pros:
Cons:
Best for: Large files (>1M rows), selective access, memory-constrained environments
Rows stay in native Odin memory and are accessed on-demand. Achieves near-FFI performance with minimal memory footprint.
import { parseCSV } from 'ocsv';
// Lazy mode: high performance
const result = parseCSV(data, {
mode: 'lazy',
hasHeader: true
});
try {
console.log(result.headers); // ['name', 'age', 'city']
console.log(result.rowCount); // 10000000
// On-demand row access
const row = result.getRow(5000000);
console.log(row.get(0)); // 'Alice'
console.log(row.get(1)); // '30'
// Iterate fields
for (const field of row) {
console.log(field);
}
// Materialize row to array (when needed)
const arr = row.toArray(); // ['Alice', '30', 'NYC']
// Efficient slicing (generator)
for (const row of result.slice(1000, 2000)) {
console.log(row.get(0));
}
// Full iteration (if needed)
for (const row of result) {
console.log(row.get(0));
}
} finally {
// CRITICAL: Must cleanup native memory
result.destroy();
}
Pros:
Cons:
destroy() must be called).get(i) or .toArray()) Start
|
Is file size > 100MB or > 1M rows?
/ \
Yes No
| |
Do you need to Use Eager Mode
access all rows? (simple, safe)
/ \
No Yes
| |
Lazy Mode Memory constrained?
(fast, low / \
memory) Yes No
| |
Lazy Mode Try Eager first
(streaming) (measure, switch if slow)
Use Lazy Mode when:
Use Eager Mode when:
Test Setup: 10M rows, 4 columns, 1.2 GB CSV file
Mode Parse Time Throughput Memory Usage
────────────────────────────────────────────────────────
FFI Direct 6.2s 193 MB/s 50 MB (baseline)
Lazy Mode 6.8s 176 MB/s <200 MB
Eager Mode 151.7s 7.9 MB/s ~8 GB
Key Metrics:
For advanced users who need maximum FFI throughput, OCSV offers an optimized packed buffer mode that achieves 61.25 MB/s (56% of native Odin performance).
Performance Comparison (100K rows, 13.80 MB file):
Mode Throughput ns/row vs Native
──────────────────────────────────────────────────────
Native Odin 109.28 MB/s 915 100%
Packed Buffer 61.25 MB/s 2,253 56%
Bulk JSON 40.68 MB/s 2,878 37%
Field-by-Field 29.58 MB/s 3,957 27%
Optimizations:
Usage:
import { parseCSVPacked } from 'ocsv/bindings/simple';
// Optimized packed buffer mode (highest FFI performance)
const rows = parseCSVPacked(csvData);
// Returns string[][] with minimal FFI overhead
When to use Packed Buffer:
Note: The 44% overhead compared to native Odin is inherent to the FFI serialization boundary. This is the practical limit for JavaScript-based FFI approaches.
// Automatic cleanup via garbage collector
const result = parseCSV(data);
// ... use result.rows ...
// Memory freed automatically when result goes out of scope
// Manual cleanup required
const result = parseCSV(data, { mode: 'lazy' });
try {
// ... use result ...
} finally {
// CRITICAL: Always call destroy()
result.destroy();
}
Common Pitfalls:
❌ Forgetting to destroy:
const result = parseCSV(data, { mode: 'lazy' });
console.log(result.getRow(0));
// Memory leak! Parser not cleaned up
❌ Use after destroy:
const result = parseCSV(data, { mode: 'lazy' });
result.destroy();
result.getRow(0); // Error: LazyResult has been destroyed
✅ Correct pattern:
const result = parseCSV(data, { mode: 'lazy' });
try {
const row = result.getRow(0);
console.log(row.toArray());
} finally {
result.destroy();
}
OCSV provides discriminated union types for type-safe mode selection:
import { parseCSV } from 'ocsv';
// Type: ParseResult (array-based)
const eager = parseCSV(data);
console.log(eager.rows[0]); // Type: string[]
// Type: LazyResult (on-demand)
const lazy = parseCSV(data, { mode: 'lazy' });
console.log(lazy.getRow(0)); // Type: LazyRow
// Compiler error: mode mismatch
const wrong = parseCSV(data, { mode: 'lazy' });
console.log(wrong.rows); // Error: Property 'rows' does not exist
// Create parser with custom configuration
parser := ocsv.parser_create()
defer ocsv.parser_destroy(parser)
// TSV (Tab-Separated Values)
parser.config.delimiter = '\t'
// European CSV (semicolon)
parser.config.delimiter = ';'
// Comments (skip lines starting with #)
parser.config.comment = '#'
// Relaxed mode (handle malformed CSV)
parser.config.relaxed = true
// Custom quote character
parser.config.quote = '\''
OCSV fully implements RFC 4180 with support for:
"field, with, commas")"field with ""quotes""" → field with "quotes")a,,c)a,b, → 3 fields, last is empty),a,b → 3 fields, first is empty)#)Example:
# Sales data for Q1 2024
product,price,description,quantity
"Widget A",19.99,"A great widget, now with more features!",100
"Gadget B",29.99,"Essential gadget
Multi-line description",50
~201 tests, 100% pass rate, 0 memory leaks
# Run all tests (standard)
odin test tests
# Run with memory tracking
odin test tests -debug
The project includes comprehensive test coverage across multiple suites:
ocsv/
├── src/
│ ├── ocsv.odin # Main module
│ ├── parser.odin # RFC 4180 state machine parser
│ ├── parser_simd.odin # SIMD-optimized parser
│ ├── parser_error.odin # Error-aware parser
│ ├── streaming.odin # Streaming API
│ ├── parallel.odin # Parallel processing
│ ├── transform.odin # Transform system
│ ├── plugin.odin # Plugin architecture
│ ├── simd.odin # SIMD search functions
│ ├── error.odin # Error handling system
│ ├── schema.odin # Schema validation & type system
│ ├── config.odin # Configuration types
│ └── ffi_bindings.odin # Bun FFI exports
├── tests/ # Comprehensive test suite
├── plugins/ # Example plugins
├── bindings/ # Bun/TypeScript bindings
├── benchmarks/ # Performance benchmarks
├── examples/ # Usage examples
└── README.md # This file
This project uses automated releases via semantic-release. Releases are triggered automatically when changes are pushed to the main branch.
All commits must follow Conventional Commits:
<type>(<scope>): <subject>
<body>
<footer>
Examples:
git commit -m "feat: add streaming parser API"
git commit -m "fix: handle empty fields correctly"
git commit -m "docs: update installation instructions"
git commit -m "feat!: remove deprecated parseFile method
BREAKING CHANGE: parseFile has been removed, use parseCSVFile instead"
Commit Types:
feat: New feature (triggers minor version bump)fix: Bug fix (triggers patch version bump)perf: Performance improvement (triggers patch version bump)docs: Documentation changes (no release)chore: Maintenance tasks (no release)refactor: Code refactoring (no release)test: Test changes (no release)ci: CI/CD changes (no release)fix:, perf:feat:BREAKING CHANGE: in footer or ! after typemain branchManual Release (Emergency Only):
npm run release:dry # Test what would be released
git push origin main # Trigger automated release
Contributions are welcome! Please read CONTRIBUTING.md for detailed guidelines on commit messages and pull request process.
Development Workflow:
odin test tests)MIT License - see LICENSE for details.
Built with ❤️ using Odin + Bun
Version: 1.3.0
Last Updated: 2025-11-09
FAQs
High-performance RFC 4180 compliant CSV parser with lazy mode for Bun. Parse 10M rows in 5s with minimal memory.
We found that ocsv demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Malicious packages published to npm, PyPI, Go Modules, crates.io, and Packagist impersonate developer tooling to fetch staged malware, steal credentials and wallets, and enable remote access.
Security News
Microsoft has released an open source toolkit for enforcing runtime security policies on AI agents as adoption accelerates faster than governance controls.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.