Generate Unique, URL-Safe IDs with Timestamp Tracking – NFUID

Preview:

Description:

NFUID is a lightweight JavaScript library that transforms timestamps, seed, and random entropy into compact, decodable unique identifiers.

It provides a simple way to generate IDs that are shorter than typical UUIDs, which can be sorted roughly by time, and are safe for use in URLs or filenames.

More Features:

• Supports a customizable base alphabet (default is alphanumeric, excluding ambiguous characters like ‘0OIl’).
• Allows configuration of timestamp and entropy bit lengths.
• Decodes generated IDs back into their constituent timestamp, seed, random components, and a JavaScript Date object.
• Works in both browser and Node.js environments.

How to use it:

1. Install NFUID and import it in your project.

# NPM
$ npm install nfuid

// Node.js
const NFUID = require('nfuid');

<!-- Browser -->
<script src="dist/nfuid.min.js"></script>

2. Initialize NFUID with default settings:

const idGen = new NFUID();

3. Generate a new ID:

const id = idGen.generate();
console.log("Generated ID:", id);

4. Decode an ID:

const decoded = idGen.decode(id);
console.log("Created at:", decoded.date);
console.log("Timestamp:", decoded.timestamp);
console.log("Seed:", decoded.seed);

5. Configuration Options:

• baseAlphabet: A string of unique characters used for encoding the ID. The default is a 57-character set designed to be URL-safe and avoid visually similar characters (e.g., ‘0’ and ‘O’, ‘I’ and ‘l’).
• timestampLength: Number of bits allocated to store the Unix timestamp (in seconds). Default is 32 bits, which covers dates roughly from 1970 to 2106. Increasing this extends the date range or precision if you modify the timestamp source.
• entropyLength: Number of bits for the purely random part of the ID. Default is 96 bits. More bits mean a lower chance of collision.

const idGen = new NFUID({
  // Custom alphabet (no ambiguous characters like 0/O, 1/l/I)
  baseAlphabet: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
  
  // Timestamp portion size in bits
  timestampLength: 32,
  
  // Random entropy portion size in bits
  entropyLength: 96
});

Comparison with Alternatives

NFUID vs UUID: Standard UUIDs (v4) are randomly generated with no inherent timestamp, making them harder to sort chronologically. NFUID embeds timestamps directly, allowing natural time-based sorting.

NFUID vs MongoDB ObjectID: MongoDB’s ObjectID similarly encodes timestamps but uses a 24-character hexadecimal format. NFUID offers more flexibility with its customizable alphabet and entropy size, potentially creating shorter IDs.

NFUID vs Nano ID: Nano ID focuses on pure randomness and compact output but lacks the built-in timestamp decoding of NFUID. Choose Nano ID for pure uniqueness, NFUID when you need to extract creation time later.

FAQs

Q: How unique are NFUIDs? What’s the collision risk?
A: The uniqueness comes from three parts: the timestamp (unique per second), the seed (random bits, same length as timestamp bits), and the random entropy bits. With default settings (32-bit timestamp, 32-bit seed, 96-bit random entropy), you have 32 + 96 = 128 bits of randomness combined with a timestamp that changes every second. The seed XORed with the timestamp effectively randomizes the timestamp portion too. Collisions within the same second depend on the seed + random entropy. 128 bits of randomness is substantial (comparable to UUID v4’s random part). For most web application purposes, the collision risk is extremely low. It’s not designed for cryptographic secrets where collision resistance needs formal proofs, but for general application IDs, it’s very robust.

Q: Can I use NFUIDs as primary keys in my database?
A: Yes, for many applications, they are suitable as primary keys. They are unique enough, and their relative sortability by time (due to the timestamp) can be a minor plus for some queries or for quickly understanding data chronology. Keep in mind the timestamp is second-resolution. If you have extremely high insertion rates (many records per second) and rely on IDs for strict ordering, you might need a solution with higher time precision or a different strategy.

Q: What happens if I change the baseAlphabet, timestampLength, or entropyLength after generating IDs?
A: You will not be able to decode IDs generated with the old configuration using an NFUID instance with the new configuration. The decoding process relies on these parameters to correctly interpret the bit structure of the ID. If you anticipate needing to change configurations, you should version your IDs or store the configuration alongside the IDs, though the latter is often impractical. Best practice: pick a configuration and stick with it for a given ID set.

Q: Is the timestamp component secure from tampering or discovery?
A: The timestamp is obfuscated by XORing it with a random seed, but it’s not cryptographically encrypted. Anyone with the ID and the NFUID library (or knowledge of its algorithm) can decode it and retrieve the original timestamp, seed, and random components. NFUID is not meant for scenarios where the ID itself needs to be a secure token or hide its creation time from determined analysis.