TidyID

English | 简体中文 | 日本語 | 한국어 | Русский

A tiny, secure, and human-friendly ID generator for JavaScript.

• Tiny 506 bytes for tidyid() (minified and Brotli-compressed). Zero runtime dependencies.
• Secure Uses the platform CSPRNG with unbiased sampling and no weak fallback. Generate independently across threads, processes, and cluster nodes; enforce absolute uniqueness with a database constraint.
• Human-friendly Creates letter-first, lowercase-alphanumeric IDs by default with a fixed LLD rhythm—no accidental long words, punctuation, or ambiguous characters. Easy to read, type, and transcribe; ready for URLs, filenames, database/cache/object-storage keys, DOM/CSS IDs, command lines, logs, and more.

import { tidyid } from 'tidyid'

const id1 = tidyid(32)       // ag8dw2tx7qx6qw4ck2mf4cc3xb8gd9vc (length = 32)
const id2 = tidyid(16)       // mh4dx8tq3bd2rz7h (length = 16)
const id3 = tidyid(10)       // td7et3cv6w (length = 10)
const id4 = tidyid(10, true) // rN9gK6cM2w (length = 10, allowUppercase = true)

Explicitly passing the length in application code is strongly recommended, even when using the default of 32.

Install

npm i tidyid

or

pnpm add tidyid

CLI

Install TidyID globally:

npm i -g tidyid

Then generate an ID:

tidyid
# wq3cc5gt9gj8nc7kh4fq2mq3yf6gk2wx (length = 32)

tidyid -s 16
# bq7th2vj6xn4zk9b (length = 16)

tidyid -s 10 -u
# Av2Mr4Aw3Y (length = 10, allowUppercase = true)

Use --size or -s to set the length. Use --allow-uppercase or -u to allow uppercase letters.

Format

By default, IDs repeat two lowercase letters followed by one digit (LLD):

xr3 fc9 xy2

| Characters | Positions | Alphabet | | --- | --- | --- | | Letters | First two of each group | abcdefghjkmnpqrtuvwxyz | | Digits | Every third character | 23456789 |

• Every ID starts with a letter.
• i, l, o, s, 0, and 1 are excluded to reduce visual and handwritten ambiguity.
• The pattern prevents long letter sequences and needs no escaping in URL paths, filenames, or HTML/CSS IDs.
• In default mode, typing needs no Shift key, _, -, or other punctuation.

allowUppercase defaults to false. Set it to true to sample letter positions from the combined uppercase and lowercase alphabet.

API

| API | Description | | --- | --- | | tidyid(length = 32, allowUppercase = false) | Generate a 3–256 character ID; defaults to 32. | | isValidId(value, length?, allowUppercase = false) | Check format and optional exact length. | | ensureValidId(value, length?, allowUppercase = false) | Throw InvalidIdLengthError or InvalidIdFormatError. | | getIdCapacity(length = 32, allowUppercase = false) | Return the exact ID space as bigint. | | getIdEntropy(length = 32, allowUppercase = false) | Return entropy in bits. |

Constants: LETTERS, LETTERS_WITH_UPPERCASE, DIGITS, DEFAULT_LENGTH, MIN_LENGTH, MAX_LENGTH.

Errors: InvalidIdLengthError, InvalidIdFormatError.

Security

• Unpredictability Node.js uses node:crypto.randomFillSync; browsers use crypto.getRandomValues. Both use the platform cryptographically secure random number generator, never Math.random().

• Uniformity Letter positions use rejection sampling, while digit positions use an exact eight-way mapping. Both avoid modulo bias, so every valid ID of the same length and mode has equal probability.

  Default mode (allowUppercase = false): observed frequencies from 10,000,000 generated 3-character IDs stay close to the expected uniform distribution.

  Uppercase-enabled mode (allowUppercase = true): observed letter and digit frequencies from 10,000,000 generated 3-character IDs stay close to the expected uniform distribution.

• Fail closed Random-source failures are propagated. TidyID never falls back to predictable randomness.

• Collision-aware Choose a length for your scale to make collisions extremely unlikely. Use a database PRIMARY KEY or UNIQUE constraint when absolute uniqueness must be enforced.

  Default mode (allowUppercase = false)

  | Length | Capacity | Entropy | | ---: | ---: | ---: | | 8 | 7,256,313,856 | 32.76 bits | | 10 | 1,277,111,238,656 | 40.22 bits | | 12 | 224,771,578,003,456 | 47.68 bits | | 16 | 19,146,942,100,646,395,904 | 64.05 bits | | 23 | 6,315,282,784,770,463,143,393,492,992 | 92.35 bits | | 32 | 366,605,391,805,505,419,895,548,144,464,707,977,216 | 128.11 bits |

  Uppercase allowed (allowUppercase = true)

  | Length | Capacity | Entropy | | ---: | ---: | ---: | | 8 | 464,404,086,784 | 38.76 bits | | 10 | 163,470,238,547,968 | 47.22 bits | | 12 | 57,541,523,968,884,736 | 55.68 bits | | 16 | 39,212,937,422,123,818,811,392 | 75.05 bits | | 23 | 413,878,372,582,717,072,565,435,956,723,712 | 108.35 bits | | 32 | 1,537,654,461,271,398,604,689,577,164,520,902,527,668,977,664 | 150.11 bits |

  Use 16 or more characters for large public datasets. For security tokens, choose the length based on your threat model. A 32-character TidyID provides 128.11 bits of entropy by default, or 150.11 bits with allowUppercase = true.

Database uniqueness

Use a primary key or unique constraint. Insert first and retry only an ID conflict—never query before inserting:

for (let attempt = 0; attempt < 128; attempt += 1) {
  const id = tidyid(16)
  const { rowCount } = await db.query(
    `INSERT INTO resources (id) VALUES ($1)
     ON CONFLICT (id) DO NOTHING RETURNING id`,
    [id],
  )
  if (rowCount === 1) return id
}
throw new Error('unable to insert a resource with a unique TidyID')

Propagate network, permission, transaction, and non-ID constraint errors.

Requirements

• Node.js >=22.12
• Modern browsers with Web Crypto and TextDecoder
• Condition-aware bundlers select the browser entry automatically

License

MIT