{"id":16033,"library":"fixed-width-parser","title":"Fixed-Width Data Parser","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/keawade/fixed-width-parser","tags":["javascript","fixed","fixed width","format","parser","typescript"],"install":[{"cmd":"npm install fixed-width-parser","lang":"bash","label":"npm"},{"cmd":"yarn add fixed-width-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add fixed-width-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { FixedWidthParser } = require('fixed-width-parser');","symbol":"FixedWidthParser","correct":"import { FixedWidthParser } from 'fixed-width-parser';"},{"note":"Import TypeScript interfaces using `import type` for clarity and to ensure they are stripped from the JavaScript output.","symbol":"IParseOptions","correct":"import type { IParseOptions } from 'fixed-width-parser';"},{"note":"The `FixedWidthParser` is a class and must be instantiated with the `new` keyword.","wrong":"const parser = FixedWidthParser(configArray);","symbol":"FixedWidthParser (instantiation)","correct":"const parser = new FixedWidthParser(configArray);"}],"quickstart":{"code":"import { FixedWidthParser } from 'fixed-width-parser';\n\n// Define the schema for your fixed-width data\nconst schema = [\n  {\n    type: 'int',\n    name: 'age',\n    start: 0,\n    width: 2,\n  },\n  {\n    name: 'name',\n    start: 2,\n    width: 12,\n  },\n];\n\nconst fixedWidthParser = new FixedWidthParser(schema);\n\nconst inputString = `42         bob\n21       alice\n33        jeff`;\n\nconst parsedResult = fixedWidthParser.parse(inputString);\nconsole.log('Parsed Data:', parsedResult);\n\nconst dataToUnparse = [\n  { age: 55, name: 'charlie' },\n  { age: 18, name: 'diana' }\n];\n\nconst unparsedString = fixedWidthParser.unparse(dataToUnparse);\nconsole.log('Unparsed String:\\n', unparsedString);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Carefully define `start` as the zero-based index of the first character and `width` as the total character length for each field.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 }`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `falsyFallback: 'undefined'` or `falsyFallback: 'null'` in `IParseOptions` or specific field configurations to ensure consistent handling of empty or falsy data points.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Always use `new FixedWidthParser(...)` to create an instance of the parser.","cause":"Attempting to call `FixedWidthParser` as a function instead of instantiating it as a class using the `new` keyword.","error":"TypeError: FixedWidthParser is not a constructor"},{"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.","cause":"The input string for a field configured as `type: 'int'` contains characters that are not valid digits for the specified (or default) radix.","error":"RangeError: Invalid radix-10 digit"},{"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.","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`.","error":"Error: Value '...' exceeds field width 'X' and truncation is disabled."}],"ecosystem":"npm"}