{"_id":"@digitaldefiance/luhn-mod-n","name":"@digitaldefiance/luhn-mod-n","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@digitaldefiance/luhn-mod-n","version":"1.0.0","description":"Enterprise-grade LUHN Modulo N algorithm implementation for TypeScript with support for bases 2-16","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","build":"tsc","prepublishOnly":"yarn test && yarn build","publish:public":"npm publish --access public"},"keywords":["luhn","checksum","check-digit","validation","mod-n","credit-card","typescript","algorithm","base-conversion","error-detection"],"author":{"name":"Digital Defiance, Jessica Mulein","email":"jessica@digitaldefiance.org"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Digital-Defiance/Luhn-mod-n-ts.git"},"bugs":{"url":"https://github.com/Digital-Defiance/Luhn-mod-n-ts/issues"},"homepage":"https://github.com/Digital-Defiance/Luhn-mod-n-ts#readme","devDependencies":{"@types/jest":"^29.5.11","@types/node":"^20.10.6","jest":"^29.7.0","ts-jest":"^29.1.1","typescript":"^5.3.3"},"engines":{"node":">=14.0.0"},"_id":"@digitaldefiance/luhn-mod-n@1.0.0","gitHead":"f7de55de7229d0e512cc81e83184fba8e1249831","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-iDAkh9mRMXNGnRKMympG/6hEodEfY22a8RMHURuOg71iwfnNUdB/3q44vunO6chXiP+srvrxlvA4IfmKvt9A8A==","shasum":"5fd0016ea78ace03b7af4bb7d6024e0e8f627b8b","tarball":"https://registry.npmjs.org/@digitaldefiance/luhn-mod-n/-/luhn-mod-n-1.0.0.tgz","fileCount":39,"unpackedSize":36854,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCN2aozSS/cpiRGQ2k/WITDvUq/1umhNuZoG66Td6yWnAIhALy+RRDxPpdumSvbJNJESvuoYBq4UR5tnvNbscwSLrHW"}]},"_npmUser":{"name":"jessica-mulein","email":"jessica@mulein.com"},"directories":{},"maintainers":[{"name":"jessica-mulein","email":"jessica@mulein.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/luhn-mod-n_1.0.0_1768412847115_0.6827353569985735"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-14T17:47:27.027Z","1.0.0":"2026-01-14T17:47:27.236Z","modified":"2026-01-14T17:47:27.433Z"},"maintainers":[{"name":"jessica-mulein","email":"jessica@mulein.com"}],"description":"Enterprise-grade LUHN Modulo N algorithm implementation for TypeScript with support for bases 2-16","homepage":"https://github.com/Digital-Defiance/Luhn-mod-n-ts#readme","keywords":["luhn","checksum","check-digit","validation","mod-n","credit-card","typescript","algorithm","base-conversion","error-detection"],"repository":{"type":"git","url":"git+https://github.com/Digital-Defiance/Luhn-mod-n-ts.git"},"author":{"name":"Digital Defiance, Jessica Mulein","email":"jessica@digitaldefiance.org"},"bugs":{"url":"https://github.com/Digital-Defiance/Luhn-mod-n-ts/issues"},"license":"MIT","readme":"# Luhn Mod N - TypeScript\n\nEnterprise-grade LUHN Modulo N algorithm implementation for TypeScript with support for bases 2-16.\n\nImproved from [https://github.com/Digital-Defiance/Luhn-mod-n](https://github.com/Digital-Defiance/Luhn-mod-n) which is itself improved from [https://stackoverflow.com/a/23640453](https://stackoverflow.com/a/23640453).\n\n## Features\n\n- ✅ **Multiple Input Types**: Array, String, Number, and BigInt support\n- ✅ **Flexible Base Support**: Works with bases 2 through 16\n- ✅ **Type-Safe**: Full TypeScript support with interfaces and generics\n- ✅ **Enterprise Architecture**: SOLID principles, dependency injection, factory pattern\n- ✅ **Comprehensive Testing**: 100% test coverage with unit and integration tests\n- ✅ **Error Detection**: Detects single-digit errors and transposition errors\n- ✅ **Zero Dependencies**: No external runtime dependencies\n\n## Installation\n\n```bash\nyarn install\n```\n\n## Quick Start\n\n```typescript\nimport { LuhnServiceFactory } from 'luhn-mod-n-ts';\n\n// Create a service for your data type\nconst service = LuhnServiceFactory.createStringService();\n\n// Calculate check digit\nconst checkDigit = service.calculate('123'); // Returns: 0\n\n// Append check digit\nconst withCheck = service.append('123'); // Returns: '1230'\n\n// Validate\nconst isValid = service.validate('1230'); // Returns: true\n```\n\n## Usage\n\n### Array Service\n\n```typescript\nimport { LuhnServiceFactory } from 'luhn-mod-n-ts';\n\nconst arrayService = LuhnServiceFactory.createArrayService();\n\n// Base 10 (default)\narrayService.calculate([1, 2, 3]); // 0\narrayService.append([1, 2, 3]); // [1, 2, 3, 0]\narrayService.validate([1, 2, 3, 0]); // true\n\n// Base 16\narrayService.calculate([15, 14, 13], 16); // 14\narrayService.append([15, 14, 13], 16); // [15, 14, 13, 14]\narrayService.validate([15, 14, 13, 14], 16); // true\n```\n\n### String Service\n\n```typescript\nimport { LuhnServiceFactory } from 'luhn-mod-n-ts';\n\nconst stringService = LuhnServiceFactory.createStringService();\n\n// Base 10\nstringService.calculate('123'); // 0\nstringService.append('123'); // '1230'\nstringService.validate('1230'); // true\n\n// Base 16 (hexadecimal)\nstringService.calculate('abc', 16); // 2\nstringService.append('abc', 16); // 'abc2'\nstringService.validate('abc2', 16); // true\n```\n\n### Number Service\n\n```typescript\nimport { LuhnServiceFactory } from 'luhn-mod-n-ts';\n\nconst numberService = LuhnServiceFactory.createNumberService();\n\nnumberService.calculate(123); // 0\nnumberService.append(123); // 1230\nnumberService.validate(1230); // true\n```\n\n### BigInt Service\n\n```typescript\nimport { LuhnServiceFactory } from 'luhn-mod-n-ts';\n\nconst bigIntService = LuhnServiceFactory.createBigIntService();\n\n// Handle very large numbers\nconst largeNumber = 123456789012345678901234567890n;\nconst withCheck = bigIntService.append(largeNumber);\nbigIntService.validate(withCheck); // true\n```\n\n## Real-World Examples\n\n### Credit Card Validation\n\n```typescript\nconst service = LuhnServiceFactory.createStringService();\n\n// Add check digit to card number\nconst cardNumber = '7992739871';\nconst withCheck = service.append(cardNumber);\nconsole.log(withCheck); // '79927398713'\n\n// Validate card number\nif (service.validate(withCheck)) {\n  console.log('Valid card number');\n}\n```\n\n### Serial Number Generation\n\n```typescript\nconst service = LuhnServiceFactory.createNumberService();\n\n// Generate serial with check digit\nconst serial = 987654321;\nconst validSerial = service.append(serial);\nconsole.log(validSerial); // 9876543217\n```\n\n### Hexadecimal Identifiers\n\n```typescript\nconst service = LuhnServiceFactory.createStringService();\n\n// Create hex ID with check digit\nconst hexId = 'deadbeef';\nconst validId = service.append(hexId, 16);\nconsole.log(validId); // 'deadbeef3'\n```\n\n## Architecture\n\nThe library follows enterprise design patterns:\n\n```\nluhn-mod-n-ts/\n├── core/\n│   └── luhn-algorithm.ts       # Core Luhn algorithm\n├── services/\n│   └── check-digit-service.ts  # Generic service layer\n├── converters/\n│   └── digit-converters.ts     # Type conversion strategies\n├── validators/\n│   └── base-validator.ts       # Input validation\n├── factories/\n│   └── luhn-service-factory.ts # Service creation\n├── interfaces.ts               # TypeScript interfaces\n├── errors.ts                   # Custom error types\n└── index.ts                    # Public API\n```\n\n### Key Components\n\n- **LuhnAlgorithm**: Core algorithm implementation\n- **CheckDigitService**: Generic service for any type\n- **DigitConverters**: Strategy pattern for type conversions\n- **BaseValidator**: Input validation with custom ranges\n- **LuhnServiceFactory**: Factory for creating type-specific services\n\n## Advanced Usage\n\n### Custom Service Creation\n\n```typescript\nimport { \n  CheckDigitService, \n  LuhnAlgorithm, \n  BaseValidator,\n  StringDigitConverter \n} from 'luhn-mod-n-ts';\n\n// Create custom service with base 16 default\nconst validator = new BaseValidator();\nconst algorithm = new LuhnAlgorithm(validator);\nconst converter = new StringDigitConverter();\nconst service = new CheckDigitService(algorithm, converter, 16);\n\n// Now base 16 is default\nservice.append('abc'); // 'abc2' (no need to specify base)\n```\n\n### Custom Base Range\n\n```typescript\nimport { BaseValidator, LuhnAlgorithm } from 'luhn-mod-n-ts';\n\n// Only allow bases 8-12\nconst validator = new BaseValidator(8, 12);\nconst algorithm = new LuhnAlgorithm(validator);\n```\n\n## API Reference\n\n### LuhnServiceFactory\n\nStatic factory for creating services:\n\n- `createArrayService()`: Returns `CheckDigitService<number[]>`\n- `createStringService()`: Returns `CheckDigitService<string>`\n- `createNumberService()`: Returns `CheckDigitService<number>`\n- `createBigIntService()`: Returns `CheckDigitService<bigint>`\n\n### CheckDigitService<T>\n\nGeneric service with three methods:\n\n- `calculate(value: T, base?: number): number` - Calculate check digit\n- `append(value: T, base?: number): T` - Append check digit to value\n- `validate(value: T, base?: number): boolean` - Validate value with check digit\n\n### Error Types\n\n- `InvalidBaseError`: Thrown when base is outside valid range\n- `InvalidInputError`: Thrown for invalid input (e.g., empty string)\n\n## Testing\n\n```bash\n# Run all tests\nyarn test\n\n# Watch mode\nyarn test:watch\n\n# Coverage report\nyarn test:coverage\n```\n\n### Test Coverage\n\n- ✅ Core algorithm (all bases 2-16)\n- ✅ All converters (Array, String, Number, BigInt)\n- ✅ Service layer\n- ✅ Validators\n- ✅ Factory\n- ✅ Integration tests\n- ✅ Error detection\n- ✅ Edge cases\n\n## Building\n\n```bash\nyarn build\n```\n\nOutput in `dist/` directory with TypeScript declarations.\n\n## How It Works\n\nThe Luhn Mod N algorithm:\n\n1. Creates a lookup table based on the base\n2. Processes digits from right to left\n3. Alternates between using the digit directly and using the lookup value\n4. Sums all values\n5. Calculates check digit: `(sum * (base - 1)) % base`\n\nThis algorithm detects:\n- Single digit errors\n- Most transposition errors (swapping adjacent digits)\n\n## Supported Bases\n\n- Base 2 (Binary)\n- Base 8 (Octal)\n- Base 10 (Decimal) - Default\n- Base 16 (Hexadecimal)\n- Any base from 2 to 16\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please ensure:\n- All tests pass\n- Code follows existing patterns\n- New features include tests\n- TypeScript types are properly defined\n\n## Credits\n\nBased on the Luhn Mod N algorithm:\n- Original: https://stackoverflow.com/a/23640453\n- Converted from: https://github.com/Digital-Defiance/Luhn-mod-n\n","readmeFilename":"README.md","_rev":"1-aae53b9be6b0da3d3f73e5703b955ef0"}