The alphabet

To mint codes from your own set of characters, pass a dictionary string to createToken. However, not every string of characters makes for a reliable token. To prevent user frustration and mathematical bias, @evanion/token enforces strict rules on any custom alphabet.

The Problem: Confusable Characters and Mathematical Bias

When a code is read aloud or typed from a printed receipt, certain characters are easily confused. A 1 can be mistaken for an l or an i, and a 0 for an o. If your token dictionary includes these, your error-detection system’s effectiveness drops significantly because the user’s “typo” might be a character that is actually valid in your dictionary.

Furthermore, the way random characters are drawn from a dictionary can introduce “bias.” If the dictionary size doesn’t divide evenly into the range of the random number generator, some characters will appear more often than others, making the codes slightly more predictable.

The Default Dictionary

By default, @evanion/token uses DEFAULT_DICTIONARY, which consists of lowercase alphanumerics minus the confusable characters: i, l, o, and w.

import { CONFUSABLE_CHARACTERS, DEFAULT_DICTIONARY } from '@evanion/token';
 
DEFAULT_DICTIONARY; // -> '0123456789abcdefghjkmnpqrstuvxyz'
DEFAULT_DICTIONARY.length; // -> 32
CONFUSABLE_CHARACTERS; // -> 'ilow'

Why these four?

• i, l, and o are visually similar to 1 and 0.
• w is phonetically similar to u (“double-u”), which leads to transcription errors when codes are dictated over the phone.

This leaves exactly 32 characters. This is an ideal number because it is even (required for the Luhn algorithm) and it divides 256 evenly (preventing random bias).

Dictionary Constraints

When you provide a custom dictionary to createToken, the library validates it against several constraints. If any are broken, it throws either an InvalidAlphabetError or an InvalidDictionaryError.

import { InvalidAlphabetError, createToken } from '@evanion/token';
 
/** The alphabet error `createToken` throws for `dictionary`, if it throws one. */
function dictionaryRefusal(
  dictionary: string,
): InvalidAlphabetError | undefined {
  try {
    createToken({ dictionary });
  } catch (error) {
    if (error instanceof InvalidAlphabetError) return error;
    throw error;
  }
  return undefined;
}
 
const everything = '0123456789abcdefghijklmnopqrstuvwxyz';
 
dictionaryRefusal(everything)?.reason; // -> 'confusable'
dictionaryRefusal(everything)?.offending; // -> ['i', 'l', 'o', 'w']
dictionaryRefusal('0123456789abcdefghjkmnpqrstuvx')?.reason; // -> 'non-uniform'
dictionaryRefusal('0123456789ABCDEFGHJKMNPQRSTUVXYZ')?.reason; // -> 'unfolded'
dictionaryRefusal('0123456789abcdef'); // -> undefined

Why the Dictionary Size Must Divide 256

The generate method draws characters using the formula byte % n, where the byte is a random value from 0 to 255.

If n (the dictionary size) is 32, the division is exact: $256 / 32 = 8$. Every character appears exactly 8 times in the range.

If n were 36, $256 / 36 = 7$ with a remainder of $4$. The first four characters in the dictionary would appear 8 times, while the others appear only 7 times. This 14.3% bias makes the codes mathematically non-uniform. To avoid “rejection sampling” (which takes variable time), @evanion/token simply requires that n divides 256.

Handling Alphabet Errors

Because @evanion/token relies on @evanion/luhn for its checksum logic, you may encounter errors from both packages.

import { InvalidDictionaryError } from '@evanion/luhn';
import { TokenError, createToken } from '@evanion/token';
 
/** The name of the error `createToken` throws for `dictionary`. */
function rejectedBy(dictionary: string): string {
  try {
    createToken({ dictionary });
  } catch (error) {
    if (error instanceof TokenError) return error.name;
    if (error instanceof InvalidDictionaryError) return error.name;
    throw error;
  }
  return 'accepted';
}
 
rejectedBy('0123456789abcdefghijklmnopqrstuvwxyz'); // -> 'InvalidAlphabetError'
rejectedBy('0123456789abcdefghjkmnpqrstuvxy'); // -> 'InvalidDictionaryError'
rejectedBy('0123456789abcdef'); // -> 'accepted'

Pro Tip: If you use a strict package manager like pnpm, ensure you add @evanion/luhn to your own package.json at the exact version pinned by @evanion/token. This ensures instanceof checks against InvalidDictionaryError work correctly across different versions of the library.

Hexadecimal Gift Cards

Hexadecimal (0123456789abcdef) is a perfect alternative dictionary. It is even, lowercase, free of confusables, and 16 divides 256.

const hexCard = createToken({ dictionary: '0123456789abcdef', length: 16 });
 
hexCard.n; // -> 16
hexCard.entropyBits; // -> 60
hexCard.generate().value.length; // -> 19

Note that since a hex character carries only 4 bits of entropy (compared to 5 bits for the default 32-character set), you will need a longer code to achieve the same level of collision resistance.