Platform-Specific Usage Guide

Guide for using web-csv-toolbox across different JavaScript runtime environments.

Guides by Environment

🌐 Browser Environments

Common CSV parsing scenarios in web browsers:

• File Input Elements - Parse files from <input type="file">
• Drag and Drop - Handle dropped CSV files
• FormData - Work with form submissions
• Fetch API - Load and parse remote CSV files

🟢 Node.js Environments

Working with CSV in Node.js applications:

• Buffer - Parse Node.js Buffer objects
• File System Streams - Read CSV files with fs.ReadStream
• HTTP Requests - Fetch and parse CSV over HTTP
• stdin/stdout - Process CSV from pipes
• Stream Conversion - Convert Node.js Streams to Web Streams (Express, Fastify, etc.)

🦕 Deno Environments

CSV parsing in Deno runtime:

• Deno.readFile - Read and parse CSV files
• Deno.open - Stream large CSV files
• fetch API - Fetch remote CSV files

Quick Reference

Input Type to API Mapping

Note: parseFile() automatically includes the filename in error messages. For environments where the File constructor is unavailable (e.g., Cloudflare Workers), use parseBlob() with a manual source option: parseBlob(blob, { source: 'filename.csv' }).

Best Practices

Memory Efficiency

• ✅ Use streaming for large files - Prefer parseBinaryStream() over loading entire files
• ✅ Process incrementally - Use for await...of to handle records one at a time
• ❌ Avoid .toArray() for large datasets - Loads entire result into memory

Error Handling

• ✅ Always use try-catch - Wrap parsing operations in error handlers
• ✅ Validate inputs - Check file types and sizes before parsing
• ✅ Provide user feedback - Display clear error messages
• ✅ Use source tracking - Specify source option or use parseFile() for automatic filename tracking
• ✅ Check error types - Handle ParseError, RangeError, and DOMException appropriately

Example:

import { parseFile, ParseError } from 'web-csv-toolbox';

try {
  for await (const record of parseFile(file)) {
    await processRecord(record);
  }
} catch (error) {
  if (error instanceof ParseError) {
    // CSV format error - includes filename automatically
    console.error(`Parse error in "${error.source}":`, error.message);
  } else if (error instanceof RangeError) {
    // Security limit exceeded
    console.error('File exceeds security limits');
  } else if (error instanceof DOMException && error.name === 'AbortError') {
    // Operation cancelled
    console.log('Parsing cancelled');
  }
}
Copy

Performance

• ✅ Enable compression - Use gzip for network transfers
• ✅ Use AbortSignal - Implement timeout protection for untrusted sources
• ✅ Batch processing - Process records in batches for database operations

Example Projects

For complete, working examples on different platforms:

• Node.js:
  • node-slim - Slim entry (external WASM)
  • node-main - Main entry (embedded WASM)
  • node-worker-main - Worker pool example
  • hono-secure-api - Production API example
• Browser (Vite):
  • vite-bundle-slim / vite-bundle-main
  • vite-bundle-worker-slim / vite-bundle-worker-main
• Browser (Webpack):
  • webpack-bundle-worker-slim / webpack-bundle-worker-main

Related Documentation

• Choosing the Right API - API selection guide
• API Reference - Complete API documentation
• Security Guide - Security best practices
• Use with Bundlers - Bundler integration guide