GS1 Barcode Parser

1.0.7 · active · verified Sun Apr 19

The `gs1-barcode-parser-mod` library is an active fork designed for parsing the complex data structures found within GS1 barcodes. It provides a single function to decompose the raw string content of a GS1 barcode into an array of structured data elements, each identified by its Application Identifier (AI). This enables JavaScript applications to easily extract specific information such as GTIN, batch/lot numbers, expiration dates, and weights. The current stable version is 1.0.7. It's particularly useful in scenarios where barcode scanning devices provide a raw string, and the application needs to process this data for inventory management, point-of-sale, or logistics. Its key differentiator is its focused utility for GS1 standards, though it's important to note it's based on the GS1 'Version 14, Issue 1, Jan 2014' specification, which might not cover the absolute latest revisions.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'ai')
```
cause Attempting to access properties of a parsed data element that was not found by `find()` or similar array methods, indicating the expected Application Identifier (AI) was not present in the barcode string.

fix Always check if the result of `find()` is defined before accessing its properties, e.g., `const gtin = parsedData.find(item => item.ai === '01'); if (gtin) { console.log(gtin.content); }`
```
Error parsing barcode: Input string does not start with a valid symbology identifier or contains invalid characters.
```
cause The input string passed to `parseGS1Barcode` does not conform to the expected starting characters or overall structure of a GS1 barcode string, or contains characters not typically found in a barcode payload.

fix Ensure the input string is a clean, raw GS1 barcode payload obtained directly from a scanner, usually starting with `]C1` for GS1 DataMatrix or similar symbology identifiers, and contains only valid barcode characters (digits, letters, FNC1).
```
SyntaxError: Unexpected token '{'
```
cause This error often indicates that you are trying to use ES module import syntax (`import`) in a CommonJS (`require`) environment (e.g., an older Node.js version or a non-transpiled script).

fix Ensure your environment supports ES modules (Node.js 12+ with `"type": "module"` in `package.json` or by using `.mjs` files), or switch to CommonJS `require` syntax if available, although this library primarily uses named ES module exports.

Warnings

gotcha This package is an active fork (`gs1-barcode-parser-mod`) of the original `BarcodeParser` by Peter Brockfeld. Ensure you are installing the correct package if you have existing dependencies or expect a specific maintainer.
Fix: Verify the package name in your `package.json` to ensure you are using the intended fork or the original.
gotcha The parser is based on 'GS1 General Specifications Version 14, Issue 1, Jan 2014'. Newer GS1 specifications or recently introduced Application Identifiers (AIs) might not be fully supported or correctly parsed.
Fix: For critical applications, cross-reference parsed data with the official GS1 specification relevant to your use case. If newer AIs are required, consider contributing to the project or using an alternative library.
gotcha The library is explicitly stated as an independent interpretation of the GS1 specification and is not endorsed, supported, or approved by GS1. Official compliance cannot be guaranteed.
Fix: Exercise due diligence when deploying in environments requiring strict GS1 compliance. Perform thorough testing with real-world barcodes relevant to your domain.
gotcha The README mentions 'Limitations' but the details are truncated. There may be specific edge cases or complex barcode structures that the parser does not handle as expected.
Fix: Thoroughly test with a wide variety of GS1 barcode strings from your specific operational context to identify any unhandled cases or parsing inaccuracies.

Install

npm install gs1-barcode-parser-mod npm
yarn add gs1-barcode-parser-mod yarn
pnpm add gs1-barcode-parser-mod pnpm

Imports

parseGS1Barcode

wrong:

const parseGS1Barcode = require('gs1-barcode-parser-mod');

correct:

import { parseGS1Barcode } from 'gs1-barcode-parser-mod';

The library primarily uses named exports for its single parsing function.

Quickstart

Demonstrates parsing a sample GS1 barcode string and iterating through the extracted data elements, including accessing specific AIs like GTIN and Lot/Batch number.

import { parseGS1Barcode } from 'gs1-barcode-parser-mod';

const scannedBarcodeString = ']C101040123456789011715012910ABC123 39329784711 310300052539224711 42127649716';

try {
  const parsedData = parseGS1Barcode(scannedBarcodeString);

  console.log('Parsed GS1 Barcode Data:');
  parsedData.forEach(item => {
    console.log(`AI: ${item.ai}, Title: ${item.title}, Contents: ${item.content}, Unit: ${item.unit || 'N/A'}`);
  });

  // Example of accessing specific data:
  const gtin = parsedData.find(item => item.ai === '01');
  if (gtin) {
    console.log(`\nGTIN: ${gtin.content}`);
  }

  const lotBatch = parsedData.find(item => item.ai === '10');
  if (lotBatch) {
    console.log(`Lot/Batch Number: ${lotBatch.content}`);
  }

} catch (error) {
  console.error('Error parsing barcode:', error.message);
}

view raw JSON →