@jrrembert/luhnjs 1.0.1 → 1.1.0

package/README.md

@@ -5,14 +5,83 @@
 
 A TypeScript implementation of the Luhn algorithm for generating and validating checksums.
 
+Published as [`@jrrembert/luhnjs`](https://www.npmjs.com/package/@jrrembert/luhnjs) on npm.
+
+## Getting Started
+
+### Prerequisites
+
+Install [Node.js](https://nodejs.org/) (>=20.x) and [Yarn](https://yarnpkg.com/).
+
+### Installation
+
+```bash
+# npm
+$ npm install @jrrembert/luhnjs
+
+# yarn
+$ yarn add @jrrembert/luhnjs
+```
+
+### Usage
+
+```typescript
+import {
+  generate,
+  validate,
+  random,
+  generateModN,
+  validateModN,
+  checksumModN,
+} from '@jrrembert/luhnjs';
+
+// Generate a checksum
+generate('7992739871');               // '79927398713'
+generate('7992739871', { checkSumOnly: true }); // '3'
+
+// Validate a checksum
+validate('79927398713');              // true
+
+// Generate a random number with valid checksum
+random('16');                         // e.g. '4539148803436467'
+
+// Mod-N variants (base 2–36, supports alphanumeric)
+generateModN('1', 16);               // '1E'
+validateModN('1E', 16);              // true
+checksumModN('12345', 10);           // 5
+```
+
+## Commands
+
+```bash
+# Install dependencies
+$ yarn
+
+# Run tests
+$ yarn test
+
+# Lint
+$ yarn lint
+
+# Build
+$ yarn build
+```
+
 ## 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
+<!-- TODO: Add link to API reference when published -->
+- [Specification](docs/SPEC.md) - API specification
+- [Release Process](docs/RELEASE.md) - Automated releases via semantic-release
+- [CI/CD](docs/CI.md) - Workflows and troubleshooting
+- [Contributing](CONTRIBUTING.md) - How to contribute
+- [Security](SECURITY.md) - Reporting vulnerabilities
+
+## Contact
+
+Email: [J. Ryan Rembert](mailto:j.ryan.rembert@gmail.com)
 
 ## License
 
 [MIT](LICENSE)
 
-Copyright © 2022-2026 J. Ryan Rembert
+Copyright © 2022-2026 J. Ryan Rembert

package/dist/src/luhn.d.ts

@@ -1,6 +1,5 @@
-declare class GenerateOptions {
+interface GenerateOptions {
     checkSumOnly: boolean;
-    constructor();
 }
 /**
    * Calculate and append Luhn algorithm checksum to a given value

package/dist/src/luhn.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checksumModN = exports.validateModN = exports.generateModN = exports.random = exports.validate = exports.generate = void 0;
+exports.generate = generate;
+exports.validate = validate;
+exports.random = random;
+exports.generateModN = generateModN;
+exports.validateModN = validateModN;
+exports.checksumModN = checksumModN;
 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
    *
@@ -33,6 +33,30 @@ function handleErrors(value) {
         throw new Error('string must be convertible to a number');
     }
 }
+/**
+   * Validates that input is a non-empty string with valid characters for the given modulus
+   *
+   * @param value - String to validate
+   * @param n - Modulus (determines valid character set)
+   * @throws {Error} If value is not a string, is empty, contains spaces, or has invalid characters
+   */
+function handleModNErrors(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.includes(' ')) {
+        throw new Error('string cannot contain spaces');
+    }
+    const validChars = CODE_POINTS.slice(0, n);
+    for (const char of value) {
+        if (!validChars.includes(char.toUpperCase())) {
+            throw new Error(`invalid character: <${char}>`);
+        }
+    }
+}
 /**
  * Generates a Luhn algorithm checksum digit for a string of numbers
  *
@@ -74,7 +98,6 @@ function generate(value, options) {
     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
    *
@@ -89,7 +112,6 @@ function validate(value) {
     const valueWithoutCheckSum = value.substring(0, value.length - 1);
     return value === generate(valueWithoutCheckSum);
 }
-exports.validate = validate;
 /**
  * Generate a random number with valid Luhn checksum
  *
@@ -100,10 +122,10 @@ function random(length) {
     handleErrors(length);
     const lengthAsInteger = parseInt(length);
     if (lengthAsInteger > 100) {
-        throw new Error('length must be less than or equal to 100');
+        throw new Error('string must be less than 100 characters');
     }
     if (lengthAsInteger < 2) {
-        throw new Error('length must be greater than or equal to 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
@@ -114,7 +136,6 @@ function random(length) {
     }).join('');
     return generate(random);
 }
-exports.random = random;
 /**
  * Calculate and append a Luhn mod-N checksum to a numeric string
  *
@@ -124,15 +145,14 @@ exports.random = random;
  * @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');
     }
+    handleModNErrors(value, n);
     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
  *
@@ -141,29 +161,23 @@ exports.generateModN = generateModN;
  * @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 (n < 1 || n > 36) {
+        throw new Error('n must be between 1 and 36');
     }
+    handleModNErrors(value, n);
     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}`);
+        throw new Error(`invalid character: <${char}>`);
     }
     return index;
 }
@@ -175,15 +189,10 @@ function charToInt(char) {
  * @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');
     }
+    handleModNErrors(value, n);
     const chars = Array.from(value);
     let factor = 2;
     let sum = 0;
@@ -195,4 +204,3 @@ function checksumModN(value, n) {
     }
     return (n - (sum % n)) % n;
 }
-exports.checksumModN = checksumModN;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrrembert/luhnjs",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -9,6 +9,9 @@
   "repository": "https://github.com/jrrembert/luhnjs.git",
   "license": "MIT",
   "private": false,
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "tsc && node dist/index.js",
     "lint": "eslint .",
@@ -16,14 +19,15 @@
     "prepublishOnly": "yarn lint && yarn test && yarn build"
   },
   "devDependencies": {
-    "@types/jest": "^29.2.3",
+    "@types/jest": "^30.0.0",
     "@typescript-eslint/eslint-plugin": "^5.44.0",
     "@typescript-eslint/parser": "^5.62.0",
     "eslint": "^8.28.0",
-    "jest": "^29.3.1",
+    "jest": "^30.0.0",
+    "semantic-release": "^25.0.0",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
-    "semantic-release": "^24.0.0",
-    "typescript": "^4.9.3"
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.2"
   }
 }