Generating and validating

To issue a pickup code as ORD-a4kp-9mxa and redeem it regardless of how a customer types it, you combine generate with a custom prefix and use validate to screen the input.

Minting a Pickup Code with a Prefix

You can make your codes more recognizable by adding a prefix like ORD-. This helps both users and staff identify the code’s purpose at a glance.

When you pass a prefix to generate, it returns the code in four fields:

const token = createToken();
 
const pickup = token.generate({ prefix: 'ORD' });
 
pickup.prefix; // -> 'ORD'
pickup.body.length; // -> 7
pickup.value.length; // -> 13
pickup.value.endsWith(pickup.check); // -> true

• value: The full code as printed (ORD-a4kp-9mxa).
• body: The random characters used as the database key.
• check: The final check character.
• prefix: The prefix you provided.

Redeeming a Prefixed Code

The validate method is designed to work on the code’s body and check character; it does not know about your custom prefixes.

If you pass ORD-a4kp-9mxa directly to validate, it will treat ORD as part of the code and refuse it (often as outside-alphabet). You must strip the prefix before validating:

const token = createToken();
 
const { value } = token.generate({ prefix: 'ORD' });
 
token.validate(value); // -> { valid: false, reason: 'outside-alphabet' }
 
/** Validates a pickup code read back with or without its `ORD` prefix. */
function validatePickupCode(readBack: string) {
  return token.validate(readBack.replace(/^ord-?/i, ''));
}
 
validatePickupCode(value).valid; // -> true
validatePickupCode(value.toLowerCase()).valid; // -> true
validatePickupCode(value.replaceAll('-', '')).valid; // -> true

In the example above, validatePickupCode handles the stripping. Because the default dictionary excludes the letter o, no valid code can start with ord. This makes it safe to strip any leading ord (case-insensitively) without risk of accidentally removing part of the actual code.

Understanding Validation Failures

validate returns valid: true and the body if the code is well-formed, or valid: false and a reason if it fails.

const token = createToken();
 
token.validate('b0zg-7kqb'); // -> { valid: true, body: 'b0zg7kq' }
token.validate('b0zg-7kq8'); // -> { valid: false, reason: 'check-failed' }
token.validate('bozg-7kqb'); // -> { valid: false, reason: 'outside-alphabet' }
token.validate('b0zg-7kq'); // -> { valid: false, reason: 'wrong-length' }

validate checks these conditions in order and reports the first failure. Since it has no side effects and never throws, you can run it on every request before performing a database lookup.

token.validate('b0zg-7kqb')

Try typing a code above. Try changing the last character, typing an o for a 0, or dropping a character.

Flexible User Input

Customers rarely type codes perfectly. They might omit hyphens, use different grouping, or type everything in capitals.

validate handles this by automatically stripping the separator and folding the case before performing its checks.

const token = createToken();
 
token.validate('a4kp9mxa').valid; // -> true
token.validate('a4-kp-9m-xa').valid; // -> true
token.validate('A4KP-9MXA'); // -> { valid: true, body: 'a4kp9mx' }

Because every variation of the spelling returns the same body, they all resolve to the same record in your database.

What the Check Character Catches

@evanion/token uses the Luhn algorithm to compute the check character. This provides a high degree of confidence in detecting common human errors:

• Single-Character Substitutions: Any single character misread or mistyped at any position is always caught.
• Adjacent Swaps: Almost every swap of two neighboring characters is caught.

const token = createToken();
 
token.validate('a4kp-9mza').valid; // -> false
token.validate('a4pk-9mxa').valid; // -> false
token.validate('b0zg-7kqb').valid; // -> true
token.validate('bz0g-7kqb').valid; // -> true

The “Blind Spot”

There is one rare exception: a swap of the first and last characters of the dictionary (by default, 0 and z). Because of the way the Luhn doubling step works, these two characters are mathematically interchangeable in the sum.

While this is a technical limitation of the Luhn algorithm, it is an acceptable trade-off for the speed and simplicity of the check.

A Longer Code for Gift Cards

Every example on this page uses the default shape: eight characters in two chunks. If you need a longer, more complex code for something like a gift card, you can customize the shape. Code shape shows how to set length, chunkSize and separator.