@valentynb/gs1-parser 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2025 Valentyn Blaha
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Valentyn Blaha
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,247 +1,226 @@
1
- # GS1 Barcode Parser
2
-
3
- [![NPM version](https://img.shields.io/npm/v/gs1-barcode-parser-ts.svg?style=flat-square)](https://www.npmjs.com/package/gs1-barcode-parser-ts)
4
- [![NPM downloads](https://img.shields.io/npm/dm/gs1-barcode-parser-ts.svg?style=flat-square)](https://www.npmjs.com/package/gs1-barcode-parser-ts)
5
- [![Build Status](https://img.shields.io/github/actions/workflow/status/YOUR_GITHUB_REPO/build.yml?style=flat-square)](https://github.com/YOUR_GITHUB_REPO/actions)
6
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
7
- [![Types Included](https://img.shields.io/badge/types-TypeScript-blue.svg?style=flat-square)](#)
8
-
9
- A modern TypeScript library for parsing GS1 barcodes, supporting both ESModule and CommonJS formats.
10
-
11
- ### Based on work from: https://github.com/PeterBrockfeld/BarcodeParser
12
-
13
- ## Table of Contents
14
-
15
- * [Purpose](#purpose)
16
- * [Installation](#installation)
17
- * [Disclaimer](#disclaimer)
18
- * [The Specification](#the-specification)
19
- * [About GS1 Barcodes](#about-gs1-barcodes)
20
- * [About the Structure of GS1 Barcodes](#about-the-structure-of-gs1-barcodes)
21
- * [Use Case](#use-case)
22
- * [How to Use It](#how-to-use-it)
23
- * [ESModule Usage](#esmodule-usage)
24
- * [CommonJS Usage](#commonjs-usage)
25
- * [TypeScript Usage](#typescript-usage)
26
- * [Limitations](#limitations)
27
- * [API Reference](#api-reference)
28
- * [About Barcode Scanning Devices](#about-barcode-scanning-devices)
29
- * [The FNC1 Character](#the-fnc1-character)
30
- * [Key Press Detecting](#key-press-detecting)
31
- * [Examples](#examples)
32
- * [What's New](#whats-new)
33
- * [License](#license)
34
-
35
- ## Purpose
36
-
37
- The barcode parser is a TypeScript library for handling the contents of GS1 barcodes. GS1 barcodes are used for various purposes, from simple product barcodes to complex codes describing the contents of an entire pallet. Two-dimensional barcodes can hold a significant amount of information, and this library makes it easier to access and process that data.
38
-
39
- The barcode parser contains functions for parsing GS1 barcodes, yielding individual elements in a format easily processable by JavaScript and TypeScript applications.
40
-
41
- The barcode parser is meant to be used in applications which:
42
-
43
- * Take data from a barcode scanning device or barcode reading application
44
- * Process the data
45
- * Perform actions based on the barcode contents
46
-
47
- ## Installation (not available yet)
48
-
49
- ```bash
50
- npm install @valentynb/gs1-parser
51
- # or
52
- yarn add @valentynb/gs1-parser
53
- # or
54
- pnpm add @valentynb/gs1-parser
55
- ```
56
-
57
- ## Disclaimer
58
-
59
- This library is an independent interpretation of the GS1 specification. It is neither endorsed, supported, approved, nor recommended by GS1, and there are no affiliations with GS1.
60
-
61
- ## The Specification
62
-
63
- The full "GS1 General Specifications" can be found at [http://www.gs1.org/standards/genspecs](https://ref.gs1.org/standards/genspecs/). This library has been updated to comply with the **2025 version** of the GS1 specification.
64
-
65
- ## About GS1 Barcodes
66
-
67
- GS1 barcodes can contain comprehensive product information including:
68
-
69
- * GTIN (Global Trade Item Number, formerly UPC or EAN)
70
- * Weight or dimensions
71
- * Price
72
- * Lot/batch code
73
- * Manufacturing date
74
- * Expiration date
75
- * And much more
76
-
77
- ### About the Structure of GS1 Barcodes
78
-
79
- A GS1 barcode is a concatenation of *data elements*. Each element starts with an *application identifier* (AI), a two to four digit number, followed by the actual information.
80
-
81
- A *data element* is delimited by:
82
-
83
- * The end of the barcode
84
- * A fixed character count specification
85
- * A special FNC1 character
86
-
87
- The *application identifiers* and their properties are described in the third chapter of the GS1 General Specifications.
88
-
89
- The GS1 barcode begins with a *symbology identifier* (a three-character sequence denoting the barcode type), followed by an arbitrary number of *data elements*. The parser decomposes this string into its individual elements.
90
-
91
- ## Use Case
92
-
93
- Your application receives a GS1 barcode as a string from a scanning device:
94
-
95
- ```
96
- ]C101040123456789011715012910ABC1233932978471131030005253922471142127649716
97
- ```
98
-
99
- The library extracts and parses the data into structured elements:
100
-
101
- | AI | Title | Contents | Unit/Currency |
102
- |:---|:------|:---------|:--------------|
103
- | 01 | GTIN | 04012345678901 | |
104
- | 17 | USE BY OR EXPIRY | 2015-01-29 | |
105
- | 10 | BATCH/LOT | ABC123 | |
106
- | 3932 | PRICE | 47.11 | 978 |
107
- | 3103 | NET WEIGHT (kg) | 0.525 | KGM |
108
- | 3922 | PRICE | 47.11 | |
109
- | 421 | SHIP TO POST | 49716 | 276 |
110
-
111
- ## How to Use It
112
-
113
- ### ESModule Usage
114
-
115
- ```typescript
116
- import { GS1Parser } from '@valentynb/gs1-parser';
117
-
118
- const gs1Parser = new GS1Parser(
119
- {
120
- lotMaxLength: 20 // If not specified, no limit is applied, except the one in the GS1 specs
121
- fncChar: String.fromCodePoint(29); // If not specified, the GS char is used
122
- }
123
- );
124
-
125
- try {
126
- const barcodeString = document.getElementById("barcode").value;
127
- // returns a DecodeResult object or throws an Error in case of parsing errors
128
- const result = gs1Parser.decode(barcodeString);
129
-
130
- console.log(result.codeName); // e.g., "GS1-128"
131
- console.log(result.denormalized); // Full barcode with parentheses
132
- console.log(result.data); // Dictionary of parsed elements
133
- } catch (error) {
134
- console.error('Barcode parsing failed:', error);
135
- }
136
- ```
137
-
138
- ### CommonJS Usage
139
-
140
- ```javascript
141
- const { parseBarcode } = require('@valentynb/gs1-parser');
142
-
143
- try {
144
- const result = parseBarcode(barcodeString);
145
- // Process result...
146
- } catch (error) {
147
- console.error('Barcode parsing failed:', error);
148
- }
149
- ```
150
-
151
- ### TypeScript Usage
152
-
153
- The library is written in TypeScript and includes full type definitions:
154
-
155
- ```typescript
156
- import { GS1Parser, BarcodeResult, ParsedElement } from '@valentynb/gs1-parser';
157
-
158
- const gs1Parser = new GS1Parser(
159
- {
160
- lotMaxLength: 20 // If not specified, no limit is applied, except the one in the GS1 specs
161
- fncChar: String.fromCodePoint(29); // If not specified, the GS char is used
162
- }
163
- );
164
-
165
- try {
166
- const result: BarcodeResult = gs1Parser.decode(barcodeString);
167
-
168
- result.data.values().forEach((item: ParsedElement) => {
169
- console.log(`AI: ${item.ai}`);
170
- console.log(`Title: ${item.dataTitle}`);
171
- console.log(`Data: ${item.data}`);
172
- console.log(`Unit: ${item.unit || 'N/A'}`);
173
- });
174
- } catch (error) {
175
- console.error('Error:', error);
176
- }
177
- ```
178
-
179
- ### Limitations
180
-
181
- The `decode()` method does not perform plausibility checks (as of now). If the barcode contains invalid data (e.g., an invalid GTIN or ISO code), the function will return this invalid content without validation.
182
-
183
- ## API Reference
184
-
185
- ### `GS1Parser.decode(barcode: string): BarcodeResult`
186
-
187
- Parses a GS1 barcode string and returns structured data.
188
-
189
- **Parameters:**
190
- - `barcode` (string): The barcode string to parse
191
-
192
- **Returns:** `BarcodeResult` object containing:
193
- - `codeName` (string): Barcode type identifier (e.g., "GS1-128", "GS1-DataMatrix")
194
- - `parsedCodeItems` (ParsedCodeItem[]): Array of parsed data elements
195
-
196
- **ParsedCodeItem structure:**
197
- - `ai` (string): Application identifier
198
- - `title` (string): Description of the data element
199
- - `data` (string | number | Date): The actual content
200
- - `unit` (string | undefined): Unit of measurement, country code, or currency (ISO codes)
201
-
202
- ## About Barcode Scanning Devices
203
-
204
- GS1 barcodes are typically scanned using hardware barcode scanners configured as HID (Human Interface Device) keyboards. This works well for most characters but presents challenges with the FNC1 character.
205
-
206
- ### The FNC1 Character
207
-
208
- The FNC1 is a non-printable control character used to delimit GS1 Element Strings of variable length.
209
-
210
- GS1 DataMatrix and GS1 QR Code use ASCII Group Separator (GS, ASCII 29, 0x1D, Unicode U+001D) as FNC1.
211
-
212
- Since this character isn't on standard keyboards, scanners send control sequences as replacements. The canonical sequence is `Ctrl + ]`.
213
-
214
- **Important:** Keyboard layout matters! A scanner emulating a German keyboard may send `Ctrl + +` instead of `Ctrl + ]`, which can trigger browser zoom. You'll need to:
215
-
216
- 1. Identify the sequence your scanner sends
217
- 2. Catch and transform these keyboard events into proper group separators
218
-
219
- ### Key Press Detecting
220
-
221
- To determine what control sequence your scanner sends, create a simple test page that logs keyboard events (`keyCode`, `charCode`, `which`) to the console when scanning test barcodes containing the GS character.
222
-
223
- ## Examples
224
-
225
- Example usage and test barcodes are included in the repository, demonstrating:
226
-
227
- * Basic parsing operations
228
- * Handling different barcode formats (GS1-128, DataMatrix, QR Code)
229
- * Working with FNC1 characters
230
- * Building scanning applications
231
-
232
- ## What's New
233
-
234
- This modernized version includes:
235
-
236
- * **TypeScript**: Full TypeScript rewrite with complete type definitions
237
- * **Dual Module Support**: Works with both ESModule (`import`) and CommonJS (`require`)
238
- * **Updated Specification**: Complies with 2025 GS1 General Specifications
239
- * **Reorganized Code**: Improved code structure and maintainability
240
- * **Modern Build System**: Compatible with current JavaScript tooling
241
-
242
- ## License
243
-
244
- Copyright (c) 2014-2015 Peter Brockfeld (original version)
245
- Copyright (c) 2025 Valentyn Blaha (This version)
246
-
247
- See the LICENSE.md file for license rights and limitations (MIT).
1
+ # GS1 Barcode Parser
2
+
3
+ [![NPM version](https://img.shields.io/npm/v/%40valentynb%2Fgs1-parser)](https://www.npmjs.com/package/@valentynb/gs1-parser)
4
+ [![NPM downloads](https://img.shields.io/npm/dm/%40valentynb%2Fgs1-parser)](https://www.npmjs.com/package/@valentynb/gs1-parser)
5
+ [![Build Status](https://img.shields.io/github/actions/workflow/status/valentynblaha/gs1-parser/publish.yml)](https://github.com/valentynblaha/gs1-parser/actions)
6
+ [![Types Included](https://img.shields.io/badge/types-TypeScript-blue.svg?style=flat-square)](#)
7
+ [![Docs](https://img.shields.io/badge/docs-online-success)](https://valentynblaha.github.io/gs1-parser/)
8
+ [![Deploy Docs](https://github.com/valentynblaha/gs1-parser/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/valentynblaha/gs1-parser/actions/workflows/deploy-docs.yml)
9
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
10
+
11
+
12
+ A modern TypeScript library for parsing GS1 barcodes, supporting both ESModule and CommonJS formats.
13
+
14
+ #### Based on work from: https://github.com/PeterBrockfeld/BarcodeParser
15
+
16
+ ## Table of Contents
17
+
18
+ * [Purpose](#purpose)
19
+ * [Installation](#installation)
20
+ * [Disclaimer](#disclaimer)
21
+ * [The Specification](#the-specification)
22
+ * [About GS1 Barcodes](#about-gs1-barcodes)
23
+ * [About the Structure of GS1 Barcodes](#about-the-structure-of-gs1-barcodes)
24
+ * [Use Case](#use-case)
25
+ * [How to Use It](#how-to-use-it)
26
+ * [ESModule Usage](#esmodule-usage)
27
+ * [CommonJS Usage](#commonjs-usage)
28
+ * [TypeScript Usage](#typescript-usage)
29
+ * [Limitations](#limitations)
30
+ * [API Reference](#api-reference)
31
+ * [About Barcode Scanning Devices](#about-barcode-scanning-devices)
32
+ * [The FNC1 Character](#the-fnc1-character)
33
+ * [Key Press Detecting](#key-press-detecting)
34
+ * [What's New](#whats-new)
35
+ * [License](#license)
36
+
37
+ ## Purpose
38
+
39
+ The barcode parser is a TypeScript library for handling the contents of GS1 barcodes. GS1 barcodes are used for various purposes, from simple product barcodes to complex codes describing the contents of an entire pallet. Two-dimensional barcodes can hold a significant amount of information, and this library makes it easier to access and process that data.
40
+
41
+ The barcode parser contains functions for parsing GS1 barcodes, yielding individual elements in a format easily processable by JavaScript and TypeScript applications.
42
+
43
+ The barcode parser is meant to be used in applications which:
44
+
45
+ * Take data from a barcode scanning device or barcode reading application
46
+ * Process the data
47
+ * Perform actions based on the barcode contents
48
+
49
+ ## Installation
50
+
51
+ ```bash
52
+ npm install @valentynb/gs1-parser
53
+ # or
54
+ yarn add @valentynb/gs1-parser
55
+ # or
56
+ pnpm add @valentynb/gs1-parser
57
+ ```
58
+
59
+ ## Disclaimer
60
+
61
+ This library is an independent interpretation of the GS1 specification. It is neither endorsed, supported, approved, nor recommended by GS1, and there are no affiliations with GS1.
62
+
63
+ ## The Specification
64
+
65
+ The full "GS1 General Specifications" can be found at [http://www.gs1.org/standards/genspecs](https://ref.gs1.org/standards/genspecs/). This library has been updated to comply with the **2025 version** of the GS1 specification.
66
+
67
+ ## About GS1 Barcodes
68
+
69
+ GS1 barcodes can contain comprehensive product information including:
70
+
71
+ * GTIN (Global Trade Item Number, formerly UPC or EAN)
72
+ * Weight or dimensions
73
+ * Price
74
+ * Lot/batch code
75
+ * Manufacturing date
76
+ * Expiration date
77
+ * And much more
78
+
79
+ ### About the Structure of GS1 Barcodes
80
+
81
+ A GS1 barcode is a concatenation of *data elements*. Each element starts with an *application identifier* (AI), a two to four digit number, followed by the actual information.
82
+
83
+ A *data element* is delimited by:
84
+
85
+ * The end of the barcode
86
+ * A fixed character count specification
87
+ * A special FNC1 character
88
+
89
+ The *application identifiers* and their properties are described in the third chapter of the GS1 General Specifications.
90
+
91
+ The GS1 barcode begins with a *symbology identifier* (a three-character sequence denoting the barcode type), followed by an arbitrary number of *data elements*. The parser decomposes this string into its individual elements.
92
+
93
+ ## Use Case
94
+
95
+ Your application receives a GS1 barcode as a string from a scanning device:
96
+
97
+ ```
98
+ ]C101040123456789011715012910ABC1233932978471131030005253922471142127649716
99
+ ```
100
+
101
+ The library extracts and parses the data into structured elements:
102
+
103
+ | AI | Title | Contents | Unit/Currency |
104
+ |:---|:------|:---------|:--------------|
105
+ | 01 | GTIN | 04012345678901 | |
106
+ | 17 | USE BY OR EXPIRY | 2015-01-29 | |
107
+ | 10 | BATCH/LOT | ABC123 | |
108
+ | 3932 | PRICE | 47.11 | 978 |
109
+ | 3103 | NET WEIGHT (kg) | 0.525 | KGM |
110
+ | 3922 | PRICE | 47.11 | |
111
+ | 421 | SHIP TO POST | 49716 | 276 |
112
+
113
+ ## How to Use It
114
+
115
+ ### ESModule Usage
116
+
117
+ ```typescript
118
+ import { GS1Parser } from '@valentynb/gs1-parser';
119
+
120
+ const gs1Parser = new GS1Parser(
121
+ {
122
+ // If not specified, no limit is applied, except the one in the GS1 specs
123
+ lotMaxLength: 20
124
+
125
+ // If not specified, the GS char is used
126
+ fncChar: String.fromCodePoint(29);
127
+ }
128
+ );
129
+
130
+ try {
131
+ const barcodeString = document.getElementById("barcode").value;
132
+ // returns a DecodeResult object or throws an Error in case of parsing errors
133
+ const result = gs1Parser.decode(barcodeString);
134
+
135
+ console.log(result.codeName); // e.g., "GS1-128"
136
+ console.log(result.denormalized); // Full barcode with parentheses
137
+ console.log(result.data); // Dictionary of parsed elements
138
+ } catch (error) {
139
+ console.error('Barcode parsing failed:', error);
140
+ }
141
+ ```
142
+
143
+ ### CommonJS Usage
144
+
145
+ ```javascript
146
+ const { GS1Parser } = require('@valentynb/gs1-parser');
147
+
148
+ const gs1Parser = new GS1Parser();
149
+
150
+ try {
151
+ const result = gs1Parser.decode(barcodeString);
152
+ // Process result...
153
+ } catch (error) {
154
+ console.error('Barcode parsing failed:', error);
155
+ }
156
+ ```
157
+
158
+ ### TypeScript Usage
159
+
160
+ The library is written in TypeScript and includes full type definitions:
161
+
162
+ ```typescript
163
+ import { GS1Parser, DecodeResult, ParsedElement } from '@valentynb/gs1-parser';
164
+
165
+ const gs1Parser = new GS1Parser();
166
+
167
+ try {
168
+ const result: DecodeResult = gs1Parser.decode(barcodeString);
169
+
170
+ result.data.values().forEach((item: ParsedElement) => {
171
+ console.log(`AI: ${item.ai}`);
172
+ console.log(`Title: ${item.dataTitle}`);
173
+ console.log(`Data: ${item.data}`);
174
+ console.log(`Unit: ${item.unit || 'N/A'}`);
175
+ });
176
+ } catch (error) {
177
+ console.error('Error:', error);
178
+ }
179
+ ```
180
+
181
+ ### Limitations
182
+
183
+ The `decode()` method does not perform plausibility checks (as of now). If the barcode contains invalid data (e.g., an invalid GTIN or ISO code), the function will return this invalid content without validation.
184
+
185
+ ## API Reference
186
+
187
+ Check out the documentation at:
188
+ #### [valentynblaha.github.io/gs1-parser](https://valentynblaha.github.io/gs1-parser)
189
+
190
+ ## About Barcode Scanning Devices
191
+
192
+ GS1 barcodes are typically scanned using hardware barcode scanners configured as HID (Human Interface Device) keyboards. This works well for most characters but presents challenges with the FNC1 character.
193
+
194
+ ### The FNC1 Character
195
+
196
+ The FNC1 is a non-printable control character used to delimit GS1 Element Strings of variable length.
197
+
198
+ GS1 DataMatrix and GS1 QR Code use ASCII Group Separator (GS, ASCII 29, 0x1D, Unicode U+001D) as FNC1.
199
+
200
+ Since this character isn't on standard keyboards, scanners send control sequences as replacements. The canonical sequence is `Ctrl + ]`.
201
+
202
+ **Important:** Keyboard layout matters! A scanner emulating a German keyboard may send `Ctrl + +` instead of `Ctrl + ]`, which can trigger browser zoom. You'll need to:
203
+
204
+ 1. Identify the sequence your scanner sends
205
+ 2. Catch and transform these keyboard events into proper group separators
206
+
207
+ ### Key Press Detecting
208
+
209
+ To determine what control sequence your scanner sends, create a simple test page that logs keyboard events (`keyCode`, `charCode`, `which`) to the console when scanning test barcodes containing the GS character.
210
+
211
+ ## What's New
212
+
213
+ This modernized version includes:
214
+
215
+ * **TypeScript**: Full TypeScript rewrite with complete type definitions
216
+ * **Dual Module Support**: Works with both ESModule (`import`) and CommonJS (`require`)
217
+ * **Updated Specification**: Complies with 2025 GS1 General Specifications
218
+ * **Reorganized Code**: Improved code structure and maintainability
219
+ * **Modern Build System**: Compatible with current JavaScript tooling
220
+
221
+ ## License
222
+
223
+ Copyright © 2014-2015 Peter Brockfeld (original version)
224
+ Copyright © 2025 Valentyn Blaha (This version)
225
+
226
+ See the LICENSE.md file for license rights and limitations (MIT).