Getting started

In this guide, you will implement a pickup code system for a store. You’ll learn how to issue a unique, human-readable code at checkout and how to use validate to ensure that a code read back at the counter is well-formed before searching your database.

Prerequisites

To follow this guide, you will need:

• Node 20 or newer, or any modern browser. generate uses crypto.getRandomValues, which is available in both environments without additional imports.
• An ESM project: Your project must be an ES module. If you are starting in an empty folder, run npm init -y followed by npm pkg set type=module. (Note: CommonJS projects require Node 20.19 or 22.12+ to load ES modules via require()).

Install token

Run the command for your preferred package manager:

npm install @evanion/token

@evanion/token automatically installs @evanion/luhn, which handles the check-character calculations.

Configure your token instance

The first step is to create a token instance. This instance is frozen at creation, ensuring that your code length and dictionary remain consistent throughout your app’s lifecycle. It is best practice to define this at the module scope.

The generate() method returns the human-readable code as value:

import { createToken } from '@evanion/token';
 
const token = createToken();
 
token.generate().value.length; // -> 9

If you call createToken() without options, it uses the defaults: a length of 8 (including the check character) and a hyphen separator. This results in a value that is 9 characters long (e.g., a4kp-9mxa).

Implement the checkout and pickup flow

Now, let’s use the token instance to handle a real-world scenario: issuing a code at checkout and validating it at the counter.

The workflow is simple:

1. At Checkout: Call generate(). This returns both the value (which you print on the receipt) and the body (which you store in your database).
2. At Pickup: Pass the customer’s spoken or typed code to validate.

import { createToken } from '@evanion/token';
 
const token = createToken();
 
/** Stands in for the orders table, keyed on each pickup code's body. */
const orders = new Map<string, string>();
 
const { value, body } = token.generate();
orders.set(body, 'order-2026-0042');
 
function findOrder(readBack: string): string {
  const result = token.validate(readBack);
  if (!result.valid) return `refused: ${result.reason}`;
  return orders.get(result.body) ?? 'no such order';
}
 
findOrder(value); // -> 'order-2026-0042'
findOrder('a4kp-9mxa'); // -> 'no such order'
findOrder('a4kp-9nxa'); // -> 'refused: check-failed'

In this example, validate acts as a gate. If a customer mishears a character (e.g., m as n), validate refuses the code immediately. This prevents your system from performing a database lookup for a code that is mathematically impossible, allowing you to tell the customer their code is mistyped rather than simply “not found.”

Professional touch: Adding a prefix

To make your codes more recognizable, you can add a prefix like ORD-. This helps users and staff identify the code’s purpose at a glance.

You can mint prefixed codes by passing a prefix option to generate. For more advanced usage—such as redeeming codes regardless of how the user types them—see Generating and validating.