Registry / serialization / fixed-width-parser

fixed-width-parser

library3.0.0jsnpmunverified

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.

serialization data

npm install fixed-width-parser

github ↗package ↗

INSTALL

IMPORT

SIG · FIXED-WIDTH-PARSER

fixed-width-parser

serializationjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FixedWidthParser

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

✗ const { FixedWidthParser } = require('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)

✓ const parser = new FixedWidthParser(configArray);

✗ const parser = FixedWidthParser(configArray);

The `FixedWidthParser` is a class and must be instantiated with the `new` keyword.

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);

Debug

Known issues

gotchaThe `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.

affects: >=1.0.0

gotchaWhen 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 }`.

affects: >=1.0.0

gotchaThe `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.

affects: >=2.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: FixedWidthParser is not a constructor

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

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.

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.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/keawade/fixed-width-parser ↗

packagehttps://www.npmjs.com/package/fixed-width-parser ↗