foxid

Compact unique ID generator with support for both ordered timestamp-based and completely random IDs. Similar to nanoid.

• Timestamp-based, reversible back to Date, ordered
• URL-friendly
• Cryptographic randomness
• Simple implementation
• Good performance
• Node.js/Deno/Bun and browser support

Now for the nitty-gritty:

This library now (v2) supports two types of IDs: timestamp-based and completely random. Random number generation is done using Node.js's crypto.randomFillSync or the browser's Crypto.getRandomValues depending on the environment.

Timestamp-based IDs are always 13 characters long, while completely random IDs can be any length.

Timestamp-based IDs are encoded as 64 bit unsigned integers, with the most significant 48 bits representing the current timestamp in milliseconds starting from 2000-01-01T00:00:00.000Z, and the remaining 16 bits being completely random.

This provides reasonable BUT not perfect collision resistance. It is reasonably possible to get a collision if you're generating thousands of IDs per millisecond. If you want better collision resistance, it's easy! Just do foxid() + foxid.random() to add 80 extra bits of randomness to your ID.

Also, obviously, you can't represent dates before 2000, or after 10,600.

Finally, timestamp-based IDs are ordered and reversible! Your database's BTree will be so happy. If you stick a bunch of them in an array and call sort() they'll come out in order of generation (as long as they weren't all generated in the same millisecond). And of course, you can reverse them back to Date objects using foxid.reverse().

Here's a few examples:

var foxid = require('foxid');

// Generate a 13 character timestamp-based ID
var id = foxid();
console.log(id); // "02zxqcyyb2tmp"

// Reverse the timestamp-based ID back to Date
console.log(foxid.reverse(id).toISOString()); // "2026-02-10T07:45:51.704Z"

// Generate another timestamp ID with a specific date
var specificID = foxid(new Date('2023-01-01'));
console.log(specificID); // "02mfzm8w01k66"

// Generate a completely random ID, defaults to 16 characters long
var randomID = foxid.random();
console.log(randomID); // "4mwer8wwb7je023t"

// Generate another random ID, 10 characters this time
console.log(foxid(10)); // "7mh99xt5y3"

And of course, here's the full API:

// Generates a random ID with the given length, defaults to 16 characters long
foxid.random = (length?: number) => string;

// Generates a timestamp-based ID with the given date, defaults to current date
foxid.timestamp = (date?: Date) => string;

// Reverses a timestamp-based ID back to Date, explodes if invalid
foxid.reverse = (id: string) => Date;

// Performs either foxid.random(length) or foxid.timestamp(date) based on the option type
// Defaults to foxid.timestamp(new Date())
foxid = (option?: Date | number) => string;

// Note the following aliases, just for fun: foxid.foxid = foxid, foxid.timestamp.reverse = foxid.reverse

License

Licensed under the MIT License.

Made with ❤ by Lua (foxgirl.dev).