OKID

Using okengine/okid gives you an id for any primary key, request trace, or event that is short (okid() is 21 characters), URL-safe, and random from a cryptographic source. Turn to it when a plain UUID string is more than you need; your app already generates them wherever defaultFn(id) is used.

Quick start

import { okid } from "okengine/okid";

const userId = okid();
const requestId = okid(16);
const typedId = okid({ prefix: "usr_" });
const eventKey = okid({ sortable: true });
const inviteCode = okid({ lookAlikes: false, uppercase: false });

// field.id() is shorthand for "default generation id" — currently OK ID.
field.id().primaryKey();
// Or pin OK ID explicitly:
field.okid().primaryKey();

Reference

Options

Exported constants

Collision resistance

Every character is drawn uniformly from the alphabet with crypto.getRandomValues(). Because it uses an unbiased character selection (never modulo), each character carries exactly log2(alphabet) bits of entropy. At the default 21 characters over 64 symbols, that is 126 bits — the birthday-bound collision probability across one billion ids is on the order of 10⁻²¹. You do not need a UUID for collision resistance; this is where a UUID is stronger only because it is a different format, not a different amount of randomness.

Consequence: two ids minted at the same millisecond are still distinct — the timestamp prefix never replaces entropy, it prefixes it.

Semantic prefixes

prefix is a fixed label ("usr_", "evt_", "inst-") prepended to the generated body. Characters must belong to OKID_ALPHABET (max 32). length stays the body size; the returned string is prefix + body.

Consequence: okid({ prefix: "usr_", sortable: true }) yields usr_ + 8-char timestamp + random tail — the label sorts first, then time.

Sortable ids

sortable: true prepends 48 bits of Date.now() encoded in exactly 8 characters, in an alphabet whose sort order matches time order. Sorting a batch of these ids reproduces the creation order across milliseconds.

Consequence: a sortable id embeds its creation time (millisecond precision), so keep them out of public, enumerable surfaces. Clock skew distorts order but can never produce a duplicate — the tail stays random.

Alphabet control

Turning groups off shrinks the alphabet. With a non-power-of-two alphabet, OKID uses rejection sampling instead of modulo, so every remaining character stays equally likely — the output never becomes measurably biased.

Consequence: smaller alphabets mean fewer bits per character. lookAlikes: false alone drops the default entropy only slightly (126 → ~120 bits); dropping whole groups costs more. Choose the smallest alphabet that fits the human-transcription use case.

Under the hood

The generator is a pure function: no counters, no process or machine fingerprint, no shared mutable state. It is safe to call concurrently from any number of workers, and every body uses only the bytes it needs — no hidden timestamp unless sortable is on.

Troubleshooting

Learn more

• Store — defaultFn(id) in table declarations delegates to okid()
• fx — fx.id() returns an OKID; options live here
• Clock — process instanceId (inst-<okid>) is an OKID

Next