# luhn

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Implements the Luhn algorithm for credit-card number validation. The Luhn
check is a widely-used checksum formula that can quickly determine whether a
sequence of digits is plausibly a valid credit-card number, and is used here
to reduce false-positive detections in the `credit-card` pattern module.

## Features

- Strips non-digit characters before validating, accepting space- or
  dash-separated card number formats.
- O(n) implementation with no allocations beyond the cleaned digit string.
- Returns `false` immediately for inputs shorter than 2 digits.

## Usage: Basic Example

```ts
import { luhnCheck } from '@suaveplan/security-codes/utils/luhn';

luhnCheck('4532015112830366'); // true  — valid Visa test number
luhnCheck('1234567890123456'); // false — fails Luhn
```

## Usage: Advanced Example

```ts
import { luhnCheck } from '@suaveplan/security-codes/utils/luhn';

// Space-separated card numbers are handled transparently
luhnCheck('4532 0151 1283 0366'); // true

// Short or empty strings are safely rejected
luhnCheck('');  // false
luhnCheck('4'); // false
```

## API Reference

### `luhnCheck(digits: string): boolean`

| Parameter | Type | Description |
|---|---|---|
| `digits` | `string` | Raw digit string; non-digit chars are stripped before validation |

Returns `true` when `digits` passes the Luhn checksum and contains at least
two digit characters, `false` otherwise. Does not throw.

## Implementation Notes

The algorithm doubles every second digit from the right (starting at index
`length - 2`). When doubling produces a value greater than 9, 9 is subtracted.
All digits are summed; a total divisible by 10 indicates a valid number.

This implementation intentionally avoids any dependency on built-in crypto or
external libraries so that it can be used in both Node.js and browser
environments without a polyfill.

The Luhn check is used by the `credit-card` pattern module as a secondary gate
after the initial regex match. A 16-digit string matching the card-number
pattern but failing the Luhn check is discarded rather than reported, which
significantly reduces false positives in documents containing order IDs,
tracking numbers, or other long numeric strings. Note that Luhn validation
confirms mathematical plausibility only — it does not verify that the card
number has ever been issued or is currently active.