gtin-checksum 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marius Pahomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# gtin-checksum
+
+[![npm version](https://img.shields.io/npm/v/gtin-checksum.svg)](https://www.npmjs.com/package/gtin-checksum)
+[![license](https://img.shields.io/npm/l/gtin-checksum.svg)](./LICENSE)
+[![types](https://img.shields.io/npm/types/gtin-checksum.svg)](./src/index.ts)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/gtin-checksum)](https://bundlephobia.com/package/gtin-checksum)
+
+> GS1 modulo-10 check-digit calculator and validator for **GTIN-8**, **GTIN-12 (UPC-A)**, **GTIN-13 (EAN-13)**, and **GTIN-14 (ITF-14)**. Zero runtime dependencies, TypeScript-native, ESM-only, tested against public GS1 / Wikipedia test vectors.
+
+A correctly computed GTIN check digit is the difference between a product feed that lands in Google Merchant Center and one that gets rejected for "Invalid GTIN". This module exists because the algorithm is one short page in the [GS1 General Specifications](https://www.gs1.org/services/how-calculate-check-digit-manually) — but every e-commerce stack ends up re-implementing it, usually with a subtle bug at the weight-alternation step.
+
+## Install
+
+```sh
+npm install gtin-checksum
+```
+
+Node 18+ · ESM-only · `~1 KB` minified.
+
+## Usage
+
+```ts
+import {
+  computeCheckDigit,
+  isValidGtin,
+  appendCheckDigit,
+  gtinVariant,
+} from 'gtin-checksum';
+
+computeCheckDigit('400638133393');   // 1
+appendCheckDigit('400638133393');    // '4006381333931'
+
+isValidGtin('4006381333931');        // true   (GTIN-13)
+isValidGtin('036000291452');         // true   (GTIN-12 / UPC-A)
+isValidGtin('73513537');             // true   (GTIN-8)
+isValidGtin('00012345678905');       // true   (GTIN-14 / ITF-14)
+isValidGtin('4006381333932');        // false  (wrong check digit)
+isValidGtin('not-a-number');         // false  (no throw — returns false)
+
+gtinVariant('4006381333931');        // 13
+gtinVariant('not-a-number');         // null
+```
+
+## API
+
+### `computeCheckDigit(dataDigits: string): number`
+
+Returns the GS1 modulo-10 check digit (0-9) for the given **data digits** — i.e. the GTIN **without** its trailing check digit. Throws `RangeError` on non-digit input or a length that is not one of 7, 11, 12, 13 (corresponding to GTIN-8/12/13/14).
+
+### `isValidGtin(gtin: string): boolean`
+
+Returns `true` iff the input is a string of all digits whose length is 8, 12, 13, or 14, and whose trailing digit matches the computed check digit. **Never throws** — returns `false` for any malformed input.
+
+### `appendCheckDigit(dataDigits: string): string`
+
+Convenience wrapper. Returns the full GTIN by appending the computed check digit to the input.
+
+### `gtinVariant(gtin: string): 8 | 12 | 13 | 14 | null`
+
+Returns the GTIN length if it matches one of the four canonical variants; `null` otherwise. Does **not** verify the check digit — use `isValidGtin` for that.
+
+### `GTIN_LENGTHS`
+
+Readonly tuple `[8, 12, 13, 14]` — the four canonical GTIN lengths.
+
+## Algorithm
+
+Per [GS1 General Specifications §7.9](https://www.gs1.org/services/how-calculate-check-digit-manually):
+
+1. Starting at the **rightmost data digit** (i.e. the digit immediately to the left of the check digit position), multiply by **3**.
+2. Move left, alternating weights **1** and **3**.
+3. Sum the products.
+4. The check digit is `(10 - sum mod 10) mod 10` — i.e. the smallest non-negative value that makes the total a multiple of 10.
+
+### Worked example (GTIN-13: `4006381333931`)
+
+| Position (from left) | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Digit | 4 | 0 | 0 | 6 | 3 | 8 | 1 | 3 | 3 | 3 | 9 | 3 | **1** (check) |
+| Weight | 1 | 3 | 1 | 3 | 1 | 3 | 1 | 3 | 1 | 3 | 1 | 3 | — |
+| Product | 4 | 0 | 0 | 18 | 3 | 24 | 1 | 9 | 3 | 9 | 9 | 9 | — |
+
+Sum = 89 · `(10 − 89 mod 10) mod 10 = (10 − 9) mod 10 = 1` · check digit matches.
+
+## Why a separate package
+
+Most e-commerce projects pull a 50 KB barcode library that drags in symbology renderers, image generators, and `canvas` peer-dependencies — just to validate a check digit. This module is the opposite: 4 exported functions, zero dependencies, types-first, and an explicit test suite against named public vectors so you can audit correctness without trusting opaque vendor code.
+
+Built and maintained by [Marius Pahomi](https://www.feedarc.com/author/marius) at [FeedArc](https://www.feedarc.com) — where verifying GTINs at scale is a daily concern.
+
+## Development
+
+```sh
+npm install
+npm test         # vitest, all test vectors
+npm run build    # emits dist/ with d.ts + sourcemaps
+```
+
+## Contributing
+
+Bug reports and additional test vectors (especially edge cases — pseudo-GTINs, embedded weight/price codes, restricted ranges) are welcome via [GitHub Issues](https://github.com/marius103/gtin-checksum/issues).
+
+## License
+
+[MIT](./LICENSE) © Marius Pahomi

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * GS1 modulo-10 check-digit utilities for GTIN-8, GTIN-12 (UPC-A),
+ * GTIN-13 (EAN-13), and GTIN-14 (ITF-14).
+ *
+ * Algorithm (per GS1 General Specifications §7.9):
+ *
+ *   Starting at the rightmost data digit (position N-2, where N includes
+ *   the check digit), multiply by 3. Move left, alternating weights 1
+ *   and 3. Sum the products. The check digit is the value that, when
+ *   added to the sum, produces a multiple of 10 — equivalently:
+ *
+ *       checkDigit = (10 - (sum mod 10)) mod 10
+ *
+ * Public reference: https://www.gs1.org/services/how-calculate-check-digit-manually
+ *
+ * This implementation has zero runtime dependencies and treats all input
+ * strictly — non-digit characters and incorrect lengths throw early.
+ */
+/** Valid GTIN total lengths (including the check digit). */
+export declare const GTIN_LENGTHS: readonly [8, 12, 13, 14];
+export type GtinLength = (typeof GTIN_LENGTHS)[number];
+/**
+ * Compute the GS1 modulo-10 check digit for a string of data digits
+ * (i.e. the GTIN WITHOUT the trailing check digit).
+ *
+ * The data length must be 7, 11, 12, or 13 — producing a GTIN-8,
+ * GTIN-12, GTIN-13, or GTIN-14 respectively. Any other length throws.
+ *
+ * @param dataDigits  GTIN without the trailing check digit.
+ * @returns The check digit as a single integer 0-9.
+ * @throws RangeError if the input contains non-digits or has an
+ *   unsupported length.
+ *
+ * @example
+ *   computeCheckDigit('400638133393'); // 1  → full GTIN-13: 4006381333931
+ *   computeCheckDigit('03600029145');  // 2  → full GTIN-12: 036000291452
+ */
+export declare function computeCheckDigit(dataDigits: string): number;
+/**
+ * Validate a full GTIN by checking its embedded check digit against
+ * the GS1 modulo-10 algorithm.
+ *
+ * @param gtin  Full GTIN string (8, 12, 13, or 14 digits).
+ * @returns true iff the string is a syntactically valid GTIN with a
+ *   matching check digit. Returns false for any malformed input — does
+ *   not throw.
+ *
+ * @example
+ *   isValidGtin('4006381333931'); // true
+ *   isValidGtin('4006381333932'); // false (wrong check digit)
+ *   isValidGtin('not-a-number');  // false
+ */
+export declare function isValidGtin(gtin: string): boolean;
+/**
+ * Append the correct check digit to a string of data digits, returning
+ * the full GTIN. Convenience wrapper around `computeCheckDigit`.
+ *
+ * @param dataDigits  GTIN without the trailing check digit.
+ * @returns Full GTIN string (one digit longer than the input).
+ *
+ * @example
+ *   appendCheckDigit('400638133393'); // '4006381333931'
+ */
+export declare function appendCheckDigit(dataDigits: string): string;
+/**
+ * Infer the GTIN variant from a full GTIN's length. Returns null if the
+ * length is not a valid GTIN length.
+ */
+export declare function gtinVariant(gtin: string): GtinLength | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,YAAY,0BAA2B,CAAC;AACrD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAyB5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAK3D"}

package/dist/index.js

@@ -0,0 +1,108 @@
+/**
+ * GS1 modulo-10 check-digit utilities for GTIN-8, GTIN-12 (UPC-A),
+ * GTIN-13 (EAN-13), and GTIN-14 (ITF-14).
+ *
+ * Algorithm (per GS1 General Specifications §7.9):
+ *
+ *   Starting at the rightmost data digit (position N-2, where N includes
+ *   the check digit), multiply by 3. Move left, alternating weights 1
+ *   and 3. Sum the products. The check digit is the value that, when
+ *   added to the sum, produces a multiple of 10 — equivalently:
+ *
+ *       checkDigit = (10 - (sum mod 10)) mod 10
+ *
+ * Public reference: https://www.gs1.org/services/how-calculate-check-digit-manually
+ *
+ * This implementation has zero runtime dependencies and treats all input
+ * strictly — non-digit characters and incorrect lengths throw early.
+ */
+/** Valid GTIN total lengths (including the check digit). */
+export const GTIN_LENGTHS = [8, 12, 13, 14];
+/**
+ * Compute the GS1 modulo-10 check digit for a string of data digits
+ * (i.e. the GTIN WITHOUT the trailing check digit).
+ *
+ * The data length must be 7, 11, 12, or 13 — producing a GTIN-8,
+ * GTIN-12, GTIN-13, or GTIN-14 respectively. Any other length throws.
+ *
+ * @param dataDigits  GTIN without the trailing check digit.
+ * @returns The check digit as a single integer 0-9.
+ * @throws RangeError if the input contains non-digits or has an
+ *   unsupported length.
+ *
+ * @example
+ *   computeCheckDigit('400638133393'); // 1  → full GTIN-13: 4006381333931
+ *   computeCheckDigit('03600029145');  // 2  → full GTIN-12: 036000291452
+ */
+export function computeCheckDigit(dataDigits) {
+    if (typeof dataDigits !== 'string') {
+        throw new TypeError('dataDigits must be a string');
+    }
+    if (!/^\d+$/.test(dataDigits)) {
+        throw new RangeError(`dataDigits must contain only ASCII digits 0-9 (got: ${JSON.stringify(dataDigits)})`);
+    }
+    const validDataLengths = GTIN_LENGTHS.map((n) => n - 1);
+    if (!validDataLengths.includes(dataDigits.length)) {
+        throw new RangeError(`dataDigits length must be one of ${validDataLengths.join(', ')} ` +
+            `(for GTIN-${GTIN_LENGTHS.join('/')}); got ${dataDigits.length}`);
+    }
+    // Walk right-to-left. Rightmost data digit gets weight 3, next 1,
+    // then 3, then 1, etc.
+    let sum = 0;
+    for (let i = 0; i < dataDigits.length; i++) {
+        const digit = dataDigits.charCodeAt(dataDigits.length - 1 - i) - 48;
+        const weight = i % 2 === 0 ? 3 : 1;
+        sum += digit * weight;
+    }
+    return (10 - (sum % 10)) % 10;
+}
+/**
+ * Validate a full GTIN by checking its embedded check digit against
+ * the GS1 modulo-10 algorithm.
+ *
+ * @param gtin  Full GTIN string (8, 12, 13, or 14 digits).
+ * @returns true iff the string is a syntactically valid GTIN with a
+ *   matching check digit. Returns false for any malformed input — does
+ *   not throw.
+ *
+ * @example
+ *   isValidGtin('4006381333931'); // true
+ *   isValidGtin('4006381333932'); // false (wrong check digit)
+ *   isValidGtin('not-a-number');  // false
+ */
+export function isValidGtin(gtin) {
+    if (typeof gtin !== 'string')
+        return false;
+    if (!/^\d+$/.test(gtin))
+        return false;
+    if (!GTIN_LENGTHS.includes(gtin.length))
+        return false;
+    const data = gtin.slice(0, -1);
+    const expected = computeCheckDigit(data);
+    const actual = gtin.charCodeAt(gtin.length - 1) - 48;
+    return expected === actual;
+}
+/**
+ * Append the correct check digit to a string of data digits, returning
+ * the full GTIN. Convenience wrapper around `computeCheckDigit`.
+ *
+ * @param dataDigits  GTIN without the trailing check digit.
+ * @returns Full GTIN string (one digit longer than the input).
+ *
+ * @example
+ *   appendCheckDigit('400638133393'); // '4006381333931'
+ */
+export function appendCheckDigit(dataDigits) {
+    return `${dataDigits}${computeCheckDigit(dataDigits)}`;
+}
+/**
+ * Infer the GTIN variant from a full GTIN's length. Returns null if the
+ * length is not a valid GTIN length.
+ */
+export function gtinVariant(gtin) {
+    const n = gtin.length;
+    return GTIN_LENGTHS.includes(n)
+        ? n
+        : null;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAU,CAAC;AAGrD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IAClD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,6BAA6B,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CAClB,uDAAuD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CACrF,CAAC;IACJ,CAAC;IACD,MAAM,gBAAgB,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,UAAU,CAClB,oCAAoC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAChE,aAAa,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,UAAU,CAAC,MAAM,EAAE,CACnE,CAAC;IACJ,CAAC;IACD,kEAAkE;IAClE,uBAAuB;IACvB,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACpE,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,GAAG,IAAI,KAAK,GAAG,MAAM,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,CAAE,YAAkC,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IACrD,OAAO,QAAQ,KAAK,MAAM,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,OAAO,GAAG,UAAU,GAAG,iBAAiB,CAAC,UAAU,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,OAAQ,YAAkC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACpD,CAAC,CAAE,CAAgB;QACnB,CAAC,CAAC,IAAI,CAAC;AACX,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "gtin-checksum",
+  "version": "1.0.0",
+  "description": "GS1 modulo-10 check-digit calculator and validator for GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN-13), and GTIN-14 (ITF-14). Zero dependencies, TypeScript-native, tested against official GS1 test vectors.",
+  "keywords": [
+    "gtin",
+    "gtin-8",
+    "gtin-12",
+    "gtin-13",
+    "gtin-14",
+    "upc",
+    "upc-a",
+    "ean",
+    "ean-13",
+    "ean-8",
+    "itf-14",
+    "gs1",
+    "check-digit",
+    "checksum",
+    "modulo-10",
+    "barcode",
+    "product-feed",
+    "ecommerce"
+  ],
+  "homepage": "https://github.com/marius103/gtin-checksum#readme",
+  "bugs": {
+    "url": "https://github.com/marius103/gtin-checksum/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marius103/gtin-checksum.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Marius Pahomi",
+    "url": "https://www.feedarc.com/author/marius"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}