Skip to content

BREAKING(csv): honour fieldsPerRecord when mapping rows to objects#7141

Open
fibibot wants to merge 1 commit into
mainfrom
orch/issue-88
Open

BREAKING(csv): honour fieldsPerRecord when mapping rows to objects#7141
fibibot wants to merge 1 commit into
mainfrom
orch/issue-88

Conversation

@fibibot
Copy link
Copy Markdown

@fibibot fibibot commented May 14, 2026

Summary

Fixes #6434.

CsvParseStream and parse() document fieldsPerRecord: -1 (or undefined,
the default) as allowing variable-length records, and that worked when
emitting string[][]. Once skipFirstRow: true or columns: [...] was set,
parsing threw Syntax error on line N: The record has X fields, but the header has Y fields even with fieldsPerRecord: -1, because
convertRowToObject threw unconditionally on length mismatch, ignoring the
fieldsPerRecord setting.

This change makes convertRowToObject accept an allowVariableLength flag
that both call sites compute from the active fieldsPerRecord mode (the
stream's #fieldsPerRecord === "ANY"; for the sync parse(),
options.fieldsPerRecord === undefined || options.fieldsPerRecord < 0).

Runtime behaviour:

  • Variable-length mode (fieldsPerRecord undefined or negative): short rows
    yield undefined for missing header keys, extra fields are dropped.
  • Strict modes (fieldsPerRecord >= 0): unchanged. The existing
    expected N fields but got M check still fires before
    convertRowToObject, and the residual length-vs-header check still throws
    when columns differs in length from a positive fieldsPerRecord.

Type widening (BREAKING)

The mapped-row value type widens from Record<string, string> to
Record<string, string | undefined> (and the same shift inside
RecordWithColumn) so callers see the runtime possibility of undefined.
This is a TS-level breaking change for callers reading values cookie-style
without noUncheckedIndexedAccess. The issue calls this out; widening
unconditionally was preferred over gating on fieldsPerRecord because the
default mode (no fieldsPerRecord set) is variable-length, so any caller
using skipFirstRow or columns with the default fieldsPerRecord can now
observe undefined and the type should reflect that.

Test plan

Closes bartlomieju/orchid-inbox#88

…parse()` and `CsvParseStream`

When `skipFirstRow` or `columns` is set together with `fieldsPerRecord: -1`
(or `fieldsPerRecord` left undefined, which is the same variable-length mode),
`convertRowToObject` previously threw "The record has X fields, but the header
has Y fields" unconditionally on length mismatch, ignoring the
`fieldsPerRecord` setting.

It now respects the mode: when variable-length records are permitted, short
rows yield `undefined` for missing header keys and extra fields beyond the
header list are dropped. Strict modes (`fieldsPerRecord >= 0`) keep the
existing length check.

The mapped-row value type widens from `Record<string, string>` to
`Record<string, string | undefined>` (and the same shift in `RecordWithColumn`)
so the static type reflects the runtime behaviour. This is a TS-level breaking
change for callers reading values cookie-style without
`noUncheckedIndexedAccess`.

Fixes #6434.
@CLAassistant
Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@github-actions github-actions Bot added the csv label May 14, 2026
@codecov
Copy link
Copy Markdown

codecov Bot commented May 14, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.61%. Comparing base (5ea9159) to head (1b7ffac).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #7141   +/-   ##
=======================================
  Coverage   94.61%   94.61%           
=======================================
  Files         634      634           
  Lines       51830    51838    +8     
  Branches     9341     9342    +1     
=======================================
+ Hits        49037    49045    +8     
  Misses       2218     2218           
  Partials      575      575           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CsvParseStream: negative fieldsPerRecord doesn't work with skipFirstRow or columns

2 participants