Code shape

To mint an @evanion/token code longer or shorter than a pickup code, or grouped differently, you pass length, chunkSize and separator to createToken.

The Problem: One Size Doesn’t Fit All

A short, 8-character code is perfect for a pickup order—it’s easy to read and type. But for a high-value gift card, an 8-character code is too easy to guess or collide. You need a longer, more secure identifier that still feels “human-readable” through proper chunking.

Conversely, a “counter code” meant to be spoken aloud might need a very specific shape—perhaps two short words separated by a space—to reduce miscommunication.

Solution: Custom Token Shapes

createToken allows you to define the exact geometry of your codes. By adjusting the length and chunking, you can balance security (entropy) with usability.

For a gift card, you might want more characters to reduce the risk of collisions:

const giftCard = createToken({ length: 16, chunkSize: 4 });
 
giftCard.generate().value.length; // -> 19
giftCard.entropyBits; // -> 75

In this example, giftCard draws 15 random characters and appends a check character. With the default 32-character dictionary, this provides significant entropy (75 bits). Using a chunkSize of 4 creates a visually organized code with three hyphens, resulting in a 19-character value.

Shape Options Reference

createToken validates these options once during instance creation. Every code minted by that instance is guaranteed to match this shape.

Creating “Spoken” Codes

If you need a code that is easy to call out across a room, you can use a space as a separator and a smaller chunk size. This turns a string of characters into something that reads like two short words:

const counterCode = createToken({ length: 6, chunkSize: 3, separator: ' ' });
const { value } = counterCode.generate();
 
value.length; // -> 7
value.charAt(3); // -> ' '
counterCode.validate(value).valid; // -> true
counterCode.validate(value.replace(' ', '-')).valid; // -> false

Because validate is tied to the instance that created the code, counterCode.validate knows to strip spaces rather than hyphens.

Invalid Shapes and InvalidShapeError

Not every combination of options is mathematically possible. createToken will throw an InvalidShapeError if the shape is invalid. This is designed to stop your application at start-up rather than failing silently at runtime.

import { InvalidShapeError, createToken } from '@evanion/token';
import type { TokenOptions } from '@evanion/token';
 
/** The shape error `createToken` throws for `options`, if it throws one. */
function refusal(options: TokenOptions): InvalidShapeError | undefined {
  try {
    createToken(options);
  } catch (error) {
    if (error instanceof InvalidShapeError) return error;
    throw error;
  }
  return undefined;
}
 
refusal({ length: 10, chunkSize: 5 }); // -> undefined
refusal({ length: 10, chunkSize: 4 })?.reason; // -> 'chunk-size-indivisible'
refusal({ length: 10, chunkSize: 4 })?.message; // -> 'Token chunkSize must divide length, or the last chunk is shorter than the rest; 4 does not divide 10.'
refusal({ length: 12, chunkSize: 4 }); // -> undefined
refusal({ dictionary: '0123456789abcde-' })?.reason; // -> 'separator-in-dictionary'
refusal({ separator: 'a' })?.reason; // -> 'separator-in-dictionary'
refusal({ separator: 'a' })?.length; // -> 8

Common Shape Errors

If the separator is also in the dictionary, validate would be unable to strip it without accidentally removing part of the code’s body, which is why this is forbidden.

Try a Token Shape

You can experiment with different shapes and dictionaries using the interactive tool below.

The interactive example this release showed here runs against the current source, so it is on the same page under /next/ and not on this one. Adjust the length, chunking, and alphabet to see how it affects the code’s entropy and collision probability.

Draw Codes from Another Dictionary

Every example so far has used the default 32-character alphabet. The alphabet shows how to provide your own dictionary to createToken and the rules that a custom alphabet must follow.