Fixed-Width Data Parser

3.0.0 · active · verified Tue Apr 21

The `fixed-width-parser` package provides a robust Node.js module for parsing and unparsing data from and to fixed-width string formats. Currently stable at version `3.0.0`, it offers a flexible configuration API where developers define field mappings using an array of objects, specifying `name`, `type` (e.g., 'string', 'int'), `start` index, and `width`. The library handles common parsing challenges such as padding, truncation, default values for undefined fields, and explicit `falsyFallback` options for parsed values. It ships with TypeScript type definitions, making it well-suited for modern TypeScript and JavaScript projects, and primarily targets server-side data processing due to its Node.js engine requirement. While a strict release cadence isn't published, major versions are released to introduce significant features or API adjustments, maintaining a focus on stability and clear API design.

Common errors

```
TypeError: FixedWidthParser is not a constructor
```
cause Attempting to call `FixedWidthParser` as a function instead of instantiating it as a class using the `new` keyword.

fix Always use `new FixedWidthParser(...)` to create an instance of the parser.
```
RangeError: Invalid radix-10 digit
```
cause The input string for a field configured as `type: 'int'` contains characters that are not valid digits for the specified (or default) radix.

fix Ensure the input string contains only valid digits for the `radix` set in the field config. For decimal (base 10), this means only '0'-'9'. Consider using `type: 'string'` if the field may contain non-numeric characters.
```
Error: Value '...' exceeds field width 'X' and truncation is disabled.
```
cause During unparsing, a value provided for a field exceeds its defined `width`, and the `truncate` option for that field (or globally) is set to `false`.

fix Either adjust the field's `width` to accommodate the value, or explicitly set `truncate: true` in the field's configuration to allow the value to be truncated during unparsing.

Warnings

gotcha The `start` and `width` properties in the parse configuration are both required and zero-based. Incorrectly defining these can lead to parsing errors or misaligned data.
Fix: Carefully define `start` as the zero-based index of the first character and `width` as the total character length for each field.
gotcha When parsing 'int' types, the `radix` defaults to 10. If your integer strings are in a different base (e.g., hexadecimal), you must explicitly set the `radix` property in the config, otherwise parsing will yield incorrect or `NaN` values.
Fix: For non-decimal integers, add `radix: <base_value>` to the integer field's configuration, e.g., `{ type: 'int', name: 'id', start: 0, width: 4, radix: 16 }`.
gotcha The `falsyFallback` option in parse options and individual field configs dictates how falsy parsed values (like empty strings or zero) are handled. The default behavior is 'passthrough', meaning falsy values are returned as-is, which might not be desired for all use cases.
Fix: Set `falsyFallback: 'undefined'` or `falsyFallback: 'null'` in `IParseOptions` or specific field configurations to ensure consistent handling of empty or falsy data points.
gotcha The `truncate` option (defaulting based on `FixedWidthParser.defaults.truncate`) controls whether data exceeding a field's `width` is truncated during unparsing. If not explicitly set, long strings might get silently truncated, leading to data loss.
Fix: Explicitly set `truncate: false` in your field configurations if you want unparsing to throw an error for values exceeding the defined `width`, or `truncate: true` if silent truncation is acceptable.

Install

npm install fixed-width-parser npm
yarn add fixed-width-parser yarn
pnpm add fixed-width-parser pnpm

Imports

FixedWidthParser
wrong:
```
const { FixedWidthParser } = require('fixed-width-parser');
```
correct:
```
import { FixedWidthParser } from 'fixed-width-parser';
```
While v3 supports CommonJS `require()`, modern Node.js applications typically use ES Modules. Use the `import` syntax in ESM contexts. The `require` syntax is valid for CJS modules.
IParseOptions
```
import type { IParseOptions } from 'fixed-width-parser';
```
Import TypeScript interfaces using `import type` for clarity and to ensure they are stripped from the JavaScript output.
FixedWidthParser (instantiation)
wrong:
```
const parser = FixedWidthParser(configArray);
```
correct:
```
const parser = new FixedWidthParser(configArray);
```
The `FixedWidthParser` is a class and must be instantiated with the `new` keyword.

Quickstart

This quickstart demonstrates how to instantiate FixedWidthParser with a schema, parse a multi-line fixed-width string into an array of objects, and then unparse an array of objects back into a fixed-width string.

import { FixedWidthParser } from 'fixed-width-parser';

// Define the schema for your fixed-width data
const schema = [
  {
    type: 'int',
    name: 'age',
    start: 0,
    width: 2,
  },
  {
    name: 'name',
    start: 2,
    width: 12,
  },
];

const fixedWidthParser = new FixedWidthParser(schema);

const inputString = `42         bob
21       alice
33        jeff`;

const parsedResult = fixedWidthParser.parse(inputString);
console.log('Parsed Data:', parsedResult);

const dataToUnparse = [
  { age: 55, name: 'charlie' },
  { age: 18, name: 'diana' }
];

const unparsedString = fixedWidthParser.unparse(dataToUnparse);
console.log('Unparsed String:\n', unparsedString);

view raw JSON →