@jrrembert/luhnjs 0.0.1-rc2 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 J. Ryan Rembert
+Copyright (c) 2022-2026 J. Ryan Rembert
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1 +1,18 @@
-# luhnjs
+# luhnjs
+
+[![Node.js CI](https://github.com/jrrembert/luhnjs/actions/workflows/node.js.yml/badge.svg)](https://github.com/jrrembert/luhnjs/actions/workflows/node.js.yml)
+[![codecov](https://codecov.io/gh/jrrembert/luhnjs/graph/badge.svg)](https://codecov.io/gh/jrrembert/luhnjs)
+
+A TypeScript implementation of the Luhn algorithm for generating and validating checksums.
+
+## Documentation
+
+- [Continuous Integration](docs/CI.md) - CI/CD workflows and troubleshooting
+- [Release and Build Process](docs/RELEASE.md) - Guide for building and publishing releases
+- [Specification](docs/SPEC.md) - Cross-language port alignment and API specification
+
+## License
+
+[MIT](LICENSE)
+
+Copyright © 2022-2026 J. Ryan Rembert

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { generate, validate, random, generateModN, validateModN, checksumModN } from './src/luhn';

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checksumModN = exports.validateModN = exports.generateModN = exports.random = exports.validate = exports.generate = void 0;
+var luhn_1 = require("./src/luhn");
+Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return luhn_1.generate; } });
+Object.defineProperty(exports, "validate", { enumerable: true, get: function () { return luhn_1.validate; } });
+Object.defineProperty(exports, "random", { enumerable: true, get: function () { return luhn_1.random; } });
+Object.defineProperty(exports, "generateModN", { enumerable: true, get: function () { return luhn_1.generateModN; } });
+Object.defineProperty(exports, "validateModN", { enumerable: true, get: function () { return luhn_1.validateModN; } });
+Object.defineProperty(exports, "checksumModN", { enumerable: true, get: function () { return luhn_1.checksumModN; } });

package/dist/src/luhn.d.ts

@@ -0,0 +1,52 @@
+declare class GenerateOptions {
+    checkSumOnly: boolean;
+    constructor();
+}
+/**
+   * Calculate and append Luhn algorithm checksum to a given value
+   *
+   * @param value string of digits to generate checksum for
+   * @param options.checkSumOnly if true, returns only the checksum digit; if false, returns value with checksum appended
+   * @returns string containing either the checksum digit alone or the input value with checksum appended
+   */
+export declare function generate(value: string, options?: GenerateOptions): string;
+/**
+   * Determine if the Luhn checksum for a given number is correct
+   *
+   * @param value string containing digits with a Luhn checksum as the last digit
+   * @returns boolean indicating whether the checksum is valid
+   */
+export declare function validate(value: string): boolean;
+/**
+ * Generate a random number with valid Luhn checksum
+ *
+ * @param length string containing the desired length of the generated number
+ * @returns string containing random digits with valid Luhn checksum
+ */
+export declare function random(length: string): string;
+/**
+ * Calculate and append a Luhn mod-N checksum to a numeric string
+ *
+ * @param value - Numeric string to generate checksum for
+ * @param n - Modulus (base) between 1 and 36
+ * @param options.checkSumOnly - If true, returns only the checksum character
+ * @returns String containing either the checksum character alone or input with checksum appended
+ */
+export declare function generateModN(value: string, n: number, options?: GenerateOptions): string;
+/**
+ * Determine if the Luhn mod-N checksum for a given value is correct
+ *
+ * @param value - Numeric string where the last character is the check character
+ * @param n - Modulus (base) between 1 and 36
+ * @returns boolean indicating whether the checksum is valid
+ */
+export declare function validateModN(value: string, n: number): boolean;
+/**
+ * Calculate Luhn mod-N check digit for an alphanumeric string
+ *
+ * @param value - Alphanumeric string to calculate check digit for
+ * @param n - Modulus (base) to use for the algorithm
+ * @returns Check digit as a number
+ */
+export declare function checksumModN(value: string, n: number): number;
+export {};

package/dist/src/luhn.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checksumModN = exports.validateModN = exports.generateModN = exports.random = exports.validate = exports.generate = void 0;
+const CODE_POINTS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+class GenerateOptions {
+    constructor() {
+        this.checkSumOnly = false;
+    }
+}
+/**
+   * Validates that input is a non-empty string that can be converted to a number
+   *
+   * @param value - String to validate
+   * @throws {Error} If value is not a string, is empty, or cannot be converted to a number
+   */
+function handleErrors(value) {
+    if (typeof value !== 'string') {
+        throw new Error(`value must be a string - received ${value}`);
+    }
+    if (!value.length) {
+        throw new Error('string cannot be empty');
+    }
+    if (value.includes(' ')) {
+        throw new Error('string cannot contain spaces');
+    }
+    if (value.includes('-')) {
+        throw new Error('negative numbers are not allowed');
+    }
+    if (value.includes('.')) {
+        throw new Error('floating point numbers are not allowed');
+    }
+    if (isNaN(+value)) {
+        throw new Error('string must be convertible to a number');
+    }
+}
+/**
+ * Generates a Luhn algorithm checksum digit for a string of numbers
+ *
+ * @param value - String of digits to generate checksum for
+ * @returns Single digit checksum value (0-9)
+ */
+function generateCheckSum(value) {
+    // convert to array
+    const toArray = Array.from(value);
+    // if double is `true`, multiply digit by 2
+    let double = true;
+    // starting from right, iterate through each value multiplying every 2nd digit by 2
+    const sum = toArray.reduceRight((prev, current) => {
+        if (double) {
+            double = false;
+            const temp = parseInt(current) * 2;
+            // if value is greater than or equal to 10, sum each digit of value ie. if value is 15, use 1 + 5 to get value
+            if (temp >= 10) {
+                return prev + Array.from(temp.toString()).reduce((prev, current) => {
+                    return prev + parseInt(current);
+                }, 0);
+            }
+            return prev + parseInt(current) * 2;
+        }
+        double = true;
+        return prev + parseInt(current);
+    }, 0);
+    return (10 - (sum % 10)) % 10;
+}
+/**
+   * Calculate and append Luhn algorithm checksum to a given value
+   *
+   * @param value string of digits to generate checksum for
+   * @param options.checkSumOnly if true, returns only the checksum digit; if false, returns value with checksum appended
+   * @returns string containing either the checksum digit alone or the input value with checksum appended
+   */
+function generate(value, options) {
+    handleErrors(value);
+    const checkSum = generateCheckSum(value).toString();
+    return (options === null || options === void 0 ? void 0 : options.checkSumOnly) ? checkSum : value.concat(checkSum);
+}
+exports.generate = generate;
+/**
+   * Determine if the Luhn checksum for a given number is correct
+   *
+   * @param value string containing digits with a Luhn checksum as the last digit
+   * @returns boolean indicating whether the checksum is valid
+   */
+function validate(value) {
+    handleErrors(value);
+    if (value.length === 1) {
+        throw new Error('string must be longer than 1 character');
+    }
+    const valueWithoutCheckSum = value.substring(0, value.length - 1);
+    return value === generate(valueWithoutCheckSum);
+}
+exports.validate = validate;
+/**
+ * Generate a random number with valid Luhn checksum
+ *
+ * @param length string containing the desired length of the generated number
+ * @returns string containing random digits with valid Luhn checksum
+ */
+function random(length) {
+    handleErrors(length);
+    const lengthAsInteger = parseInt(length);
+    if (lengthAsInteger > 100) {
+        throw new Error('string must be less than 100 characters');
+    }
+    if (lengthAsInteger < 2) {
+        throw new Error('string must be greater than 1');
+    }
+    const random = Array.from({ length: lengthAsInteger - 1 }, (_, index) => {
+        // Ensure the first digit is not zero
+        if (index === 0) {
+            return Math.floor(Math.random() * 9) + 1; // 1 to 9
+        }
+        return Math.floor(Math.random() * 10);
+    }).join('');
+    return generate(random);
+}
+exports.random = random;
+/**
+ * Calculate and append a Luhn mod-N checksum to a numeric string
+ *
+ * @param value - Numeric string to generate checksum for
+ * @param n - Modulus (base) between 1 and 36
+ * @param options.checkSumOnly - If true, returns only the checksum character
+ * @returns String containing either the checksum character alone or input with checksum appended
+ */
+function generateModN(value, n, options) {
+    handleErrors(value);
+    if (n < 1 || n > 36) {
+        throw new Error('n must be between 1 and 36');
+    }
+    const checkSum = checksumModN(value, n);
+    const checkChar = CODE_POINTS[checkSum];
+    return (options === null || options === void 0 ? void 0 : options.checkSumOnly) ? checkChar : value.concat(checkChar);
+}
+exports.generateModN = generateModN;
+/**
+ * Determine if the Luhn mod-N checksum for a given value is correct
+ *
+ * @param value - Numeric string where the last character is the check character
+ * @param n - Modulus (base) between 1 and 36
+ * @returns boolean indicating whether the checksum is valid
+ */
+function validateModN(value, n) {
+    if (typeof value !== 'string') {
+        throw new Error(`value must be a string - received ${value}`);
+    }
+    if (!value.length) {
+        throw new Error('string cannot be empty');
+    }
+    if (value.length === 1) {
+        throw new Error('string must be longer than 1 character');
+    }
+    if (n < 1 || n > 36) {
+        throw new Error('n must be between 1 and 36');
+    }
+    const valueWithoutCheckSum = value.substring(0, value.length - 1);
+    return value === generateModN(valueWithoutCheckSum, n);
+}
+exports.validateModN = validateModN;
+/**
+ * Convert a character to its code point index (0-9, A-Z, case-insensitive)
+ */
+function charToInt(char) {
+    const index = CODE_POINTS.indexOf(char.toUpperCase());
+    if (index === -1) {
+        throw new Error(`Invalid character: ${char}`);
+    }
+    return index;
+}
+/**
+ * Calculate Luhn mod-N check digit for an alphanumeric string
+ *
+ * @param value - Alphanumeric string to calculate check digit for
+ * @param n - Modulus (base) to use for the algorithm
+ * @returns Check digit as a number
+ */
+function checksumModN(value, n) {
+    if (typeof value !== 'string') {
+        throw new Error(`value must be a string - received ${value}`);
+    }
+    if (!value.length) {
+        throw new Error('string cannot be empty');
+    }
+    if (n < 1 || n > 36) {
+        throw new Error('n must be between 1 and 36');
+    }
+    const chars = Array.from(value);
+    let factor = 2;
+    let sum = 0;
+    for (let i = chars.length - 1; i >= 0; i--) {
+        let addend = charToInt(chars[i]) * factor;
+        addend = Math.floor(addend / n) + (addend % n);
+        sum += addend;
+        factor = factor === 2 ? 1 : 2;
+    }
+    return (n - (sum % n)) % n;
+}
+exports.checksumModN = checksumModN;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrrembert/luhnjs",
-  "version": "0.0.1-rc2",
+  "version": "1.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -12,16 +12,18 @@
   "scripts": {
     "build": "tsc && node dist/index.js",
     "lint": "eslint .",
-    "test": "jest"
+    "test": "jest",
+    "prepublishOnly": "yarn lint && yarn test && yarn build"
   },
   "devDependencies": {
     "@types/jest": "^29.2.3",
     "@typescript-eslint/eslint-plugin": "^5.44.0",
-    "@typescript-eslint/parser": "^5.44.0",
+    "@typescript-eslint/parser": "^5.62.0",
     "eslint": "^8.28.0",
     "jest": "^29.3.1",
-    "ts-jest": "^29.0.3",
-    "ts-node": "^10.9.1",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "semantic-release": "^24.0.0",
     "typescript": "^4.9.3"
   }
 }