fast-csv 5.0.5: parse

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify parse in pkg:npm/fast-csv@5.0.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fast-csv@5.0.5
Demonstrate these symbols/APIs:
  - parse

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:93dfd83b05d6fdcbb7a81209f190a3f3cb3da40af6d18eef564781ee74bdb2dc","contract":["parse parses CSV rows into arrays of string fields by default","parse maps the first row to object keys when headers is true","parse applies custom header names when headers is an array","parse transforms header names when headers is a transform function","parse parses custom delimiters such as semicolon","parse trims whitespace from fields when trim is true and ignores comments","parse limits the number of parsed rows when maxRows is specified","parse applies row transform function via transform method","parse validates rows and emits data-invalid for invalid rows via validate method","parse emits error event on unclosed quotes","parse throws error on column header count mismatch when headers is true"],"goal":"verify parse in pkg:npm/fast-csv@5.0.5","kind":"HOW","packages":["pkg:npm/fast-csv@5.0.5"],"schemaVersion":1,"symbols":["parse"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/fast-csv@5.0.5"],"schemaVersion":1,"subject":"pkg:npm/fast-csv@5.0.5","symbols":["parse"],"verifierAdapter":"node-typescript@1"}

'use strict';

const { parse } = require('fast-csv');

/**
 * Creates a CSV parser transform stream configured with the provided options.
 *
 * @param {import('fast-csv').ParserOptionsArgs} [options] - Options for parsing CSV data.
 * @returns {import('fast-csv').CsvParserStream} A transform stream for parsing CSV records.
 */
function createCsvParser(options) {
  return parse(options);
}

module.exports = {
  parse,
  createCsvParser,
};

{
  "name": "sample-fast-csv-parse",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fast-csv-parse",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "fast-csv": "5.0.5"
      }
    },
    "node_modules/@fast-csv/format": {
      "version": "5.0.5",
      "resolved": "https://registry.npmjs.org/@fast-csv/format/-/format-5.0.5.tgz",
      "integrity": "sha512-0P9SJXXnqKdmuWlLaTelqbrfdgN37Mvrb369J6eNmqL41IEIZQmV4sNM4GgAK2Dz3aH04J0HKGDMJFkYObThTw==",
      "license": "MIT",
      "dependencies": {
        "lodash.escaperegexp": "^4.1.2",
        "lodash.isboolean": "^3.0.3",
        "lodash.isfunction": "^3.0.9",
        "lodash.isnil": "^4.0.0"
      }
    },
    "node_modules/@fast-csv/parse": {
      "version": "5.0.5",
      "resolved": "https://registry.npmjs.org/@fast-csv/parse/-/parse-5.0.5.tgz",
      "integrity": "sha512-M0IbaXZDbxfOnpVE5Kps/a6FGlILLhtLsvWd9qNH3d2TxNnpbNkFf3KD26OmJX6MHq7PdQAl5htStDwnuwHx6w==",
      "license": "MIT",
      "dependencies": {
        "lodash.escaperegexp": "^4.1.2",
        "lodash.groupby": "^4.6.0",
        "lodash.isfunction": "^3.0.9",
        "lodash.isnil": "^4.0.0",
        "lodash.isundefined": "^3.0.1",
        "lodash.uniq": "^4.5.0"
      }
    },
    "node_modules/fast-csv": {
      "version": "5.0.5",
      "resolved": "https://registry.npmjs.org/fast-csv/-/fast-csv-5.0.5.tgz",
      "integrity": "sha512-9//QpogDIPln5Dc8e3Q3vbSSLXlTeU7z1JqsUOXZYOln8EIn/OOO8+NS2c3ukR6oYngDd3+P1HXSkby3kNV9KA==",
      "license": "MIT",
      "dependencies": {
        "@fast-csv/format": "5.0.5",
        "@fast-csv/parse": "5.0.5"
      },
      "engines": {
        "node": ">=10.0.0"
      }
    },
    "node_modules/lodash.escaperegexp": {
      "version": "4.1.2",
      "resolved": "https://registry.npmjs.org/lodash.escaperegexp/-/lodash.escaperegexp-4.1.2.tgz",
      "integrity": "sha512-TM9YBvyC84ZxE3rgfefxUWiQKLilstD6k7PTGt6wfbtXF8ixIJLOL3VYyV/z+ZiPLsVxAsKAFVwWlWeb2Y8Yyw==",
      "license": "MIT"
    },
    "node_modules/lodash.groupby": {
      "version": "4.6.0",
      "resolved": "https://registry.npmjs.org/lodash.groupby/-/lodash.groupby-4.6.0.tgz",
      "integrity": "sha512-5dcWxm23+VAoz+awKmBaiBvzox8+RqMgFhi7UvX9DHZr2HdxHXM/Wrf8cfKpsW37RNrvtPn6hSwNqurSILbmJw==",
      "license": "MIT"
    },
    "node_modules/lodash.isboolean": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/lodash.isboolean/-/lodash.isboolean-3.0.3.tgz",
      "integrity": "sha512-Bz5mupy2SVbPHURB98VAcw+aHh4vRV5IPNhILUCsOzRmsTmSQ17jIuqopAentWoehktxGd9e/hbIXq980/1QJg==",
      "license": "MIT"
    },
    "node_modules/lodash.isfunction": {
      "version": "3.0.9",
      "resolved": "https://registry.npmjs.org/lodash.isfunction/-/lodash.isfunction-3.0.9.tgz",
      "integrity": "sha512-AirXNj15uRIMMPihnkInB4i3NHeb4iBtNg9WRWuK2o31S+ePwwNmDPaTL3o7dTJ+VXNZim7rFs4rxN4YU1oUJw==",
      "license": "MIT"
    },
    "node_modules/lodash.isnil": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/lodash.isnil/-/lodash.isnil-4.0.0.tgz",
      "integrity": "sha512-up2Mzq3545mwVnMhTDMdfoG1OurpA/s5t88JmQX809eH3C8491iu2sfKhTfhQtKY78oPNhiaHJUpT/dUDAAtng==",
      "license": "MIT"
    },
    "node_modules/lodash.isundefined": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/lodash.isundefined/-/lodash.isundefined-3.0.1.tgz",
      "integrity": "sha512-MXB1is3s899/cD8jheYYE2V9qTHwKvt+npCwpD+1Sxm3Q3cECXCiYHjeHWXNwr6Q0SOBPrYUDxendrO6goVTEA==",
      "license": "MIT"
    },
    "node_modules/lodash.uniq": {
      "version": "4.5.0",
      "resolved": "https://registry.npmjs.org/lodash.uniq/-/lodash.uniq-4.5.0.tgz",
      "integrity": "sha512-xfBaXQd9ryd9dlSDvnvI0lvxfLJlYAZzXomUYzLKtUeOQvOP5piqAWuGtrhWeqaXK9hhoM/iyJc5AV+XfsX3HQ==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-fast-csv-parse",
  "version": "1.0.0",
  "description": "Minimal sample verifying parse in fast-csv@5.0.5",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "license": "MIT-0",
  "dependencies": {
    "fast-csv": "5.0.5"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify parse in pkg:npm/fast-csv@5.0.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/fast-csv@5.0.5"
  ],
  "symbols": [
    "parse"
  ]
}

'use strict';

const assert = require('assert');
const { Readable } = require('stream');
const fastCsv = require('fast-csv');
const { parse, createCsvParser } = require('../index.js');

// Module export equivalence
assert.strictEqual(typeof parse, 'function');
assert.strictEqual(typeof fastCsv.parse, 'function');
assert.strictEqual(parse, fastCsv.parse);
assert.strictEqual(typeof createCsvParser, 'function');

function parseStreamAsync(csvContent, options = {}, configure) {
  return new Promise((resolve, reject) => {
    const rows = [];
    const invalidRows = [];
    const parser = parse(options);
    if (configure) {
      configure(parser, invalidRows);
    }
    Readable.from([csvContent])
      .pipe(parser)
      .on('data', (row) => rows.push(row))
      .on('error', reject)
      .on('end', () => resolve({ rows, invalidRows }));
  });
}

async function runContractTests() {
  // 1. parse parses CSV rows into arrays of string fields by default
  {
    const { rows } = await parseStreamAsync('a,b,c\n1,2,3\n4,5,6\n');
    assert.deepStrictEqual(rows, [
      ['a', 'b', 'c'],
      ['1', '2', '3'],
      ['4', '5', '6']
    ]);
  }

  // 2. parse maps the first row to object keys when headers is true
  {
    const { rows } = await parseStreamAsync('id,name,role\n1,Alice,Admin\n2,Bob,User\n', { headers: true });
    assert.deepStrictEqual(rows, [
      { id: '1', name: 'Alice', role: 'Admin' },
      { id: '2', name: 'Bob', role: 'User' }
    ]);
  }

  // 3. parse applies custom header names when headers is an array
  {
    const { rows } = await parseStreamAsync('10,20\n30,40\n', { headers: ['x', 'y'] });
    assert.deepStrictEqual(rows, [
      { x: '10', y: '20' },
      { x: '30', y: '40' }
    ]);
  }

  // 4. parse transforms header names when headers is a transform function
  {
    const { rows } = await parseStreamAsync('first_name,last_name\njohn,doe\n', {
      headers: (headers) => headers.map((h) => h.toUpperCase())
    });
    assert.deepStrictEqual(rows, [
      { FIRST_NAME: 'john', LAST_NAME: 'doe' }
    ]);
  }

  // 5. parse parses custom delimiters such as semicolon
  {
    const { rows } = await parseStreamAsync('item;qty;price\napple;10;1.5\n', { delimiter: ';', headers: true });
    assert.deepStrictEqual(rows, [
      { item: 'apple', qty: '10', price: '1.5' }
    ]);
  }

  // 6. parse trims whitespace from fields when trim is true and ignores comments
  {
    const { rows } = await parseStreamAsync('# header comment\n  alpha  ,  beta  \n# row comment\n  gamma  ,  delta  \n', {
      comment: '#',
      trim: true
    });
    assert.deepStrictEqual(rows, [
      ['alpha', 'beta'],
      ['gamma', 'delta']
    ]);
  }

  // 7. parse limits the number of parsed rows when maxRows is specified
  {
    const { rows } = await parseStreamAsync('row1\nrow2\nrow3\nrow4\n', { maxRows: 2 });
    assert.deepStrictEqual(rows, [
      ['row1'],
      ['row2']
    ]);
  }

  // 8. parse applies row transform function via transform method
  {
    const { rows } = await parseStreamAsync('val\n10\n20\n', { headers: true }, (parser) => {
      parser.transform((row) => ({ val: Number(row.val) * 2 }));
    });
    assert.deepStrictEqual(rows, [
      { val: 20 },
      { val: 40 }
    ]);
  }

  // 9. parse validates rows and emits data-invalid for invalid rows via validate method
  {
    const { rows, invalidRows } = await parseStreamAsync(
      'name,age\nAlice,25\nBob,15\nCharlie,30\n',
      { headers: true },
      (parser, invalid) => {
        parser.validate((row) => Number(row.age) >= 18)
          .on('data-invalid', (row, rowNumber, reason) => invalid.push({ row, rowNumber }));
      }
    );
    assert.deepStrictEqual(rows, [
      { name: 'Alice', age: '25' },
      { name: 'Charlie', age: '30' }
    ]);
    assert.deepStrictEqual(invalidRows, [
      { row: { name: 'Bob', age: '15' }, rowNumber: 2 }
    ]);
  }

  // 10. parse emits error event on unclosed quotes
  {
    let errCaught = null;
    try {
      await parseStreamAsync('header\n"unclosed quote\n');
    } catch (err) {
      errCaught = err;
    }
    assert(errCaught !== null, 'Should emit error on unclosed quote');
    assert(/missing closing/i.test(errCaught.message));
  }

  // 11. parse throws error on column header count mismatch when headers is true
  {
    let errCaught = null;
    try {
      await parseStreamAsync('col1,col2\nval1,val2,val3\n', { headers: true });
    } catch (err) {
      errCaught = err;
    }
    assert(errCaught !== null, 'Should emit error on column count mismatch');
    assert(/column header mismatch/i.test(errCaught.message));
  }

  console.log('Contract test passed successfully.');
}

runContractTests();