Fluid

Friendly Labeled Unique Identifiers

Generate time-ordered prefixed IDs like user_1BjQ7hVBYfRnTyNiGfX3z and order_2CkR8iWCZgSoUzOjHgY4A using UUIDv7 and Base62 encoding.

import { build, generate, parse, timestamp, validate } from "@wadefletch/fluid";

// Generate time-ordered IDs with meaningful prefixes
const userId = generate("user"); // user_1BjQ7hVBYfRnTyNiGfX3z
const orderId = generate("order"); // order_2CkR8iWCZgSoUzOjHgY4A

// Parse to extract components
const { prefix, uuid } = parse(userId);
console.log(prefix); // "user"
console.log(uuid); // "018a1234-5678-7abc-9def-0123456789ab"

// Build ID from prefix and UUID (useful when reading from database)
const rebuiltId = build("user", uuid); // user_1BjQ7hVBYfRnTyNiGfX3z

// Extract timestamp from ID
const createdAt = timestamp(userId); // Date object

// Validate format and prefix
validate(userId, "user"); // true
validate(userId, "order"); // false

Installation

npm install @wadefletch/fluid

Usage

Generating IDs

import { build, generate, parse, timestamp, validate } from "@wadefletch/fluid";

// Generate IDs with meaningful prefixes
const userId = generate("user"); // user_1BjQ7hVBYfRnTyNiGfX3z
const orderId = generate("order"); // order_2CkR8iWCZgSoUzOjHgY4A
const apiKey = generate("api_key"); // api_key_3ElT0kYEbiVqWbQlJiA6C

Parsing IDs

const id = "user_1BjQ7hVBYfRnTyNiGfX3z";
const { prefix, uuid } = parse(id);

console.log(prefix); // "user"
console.log(uuid); // "018a1234-5678-7abc-9def-0123456789ab"

Building IDs from Components

// Build ID from prefix and UUID (useful when reading from database)
const uuid = "018a1234-5678-7abc-9def-0123456789ab";
const userId = build("user", uuid); // user_1BjQ7hVBYfRnTyNiGfX3z

Extracting Timestamps

// Get the creation timestamp from any ID
const userId = generate("user");
const createdAt = timestamp(userId); // Date object
console.log(createdAt); // 2024-01-15T10:30:45.123Z

// Works with any valid prefixed ID
const orderTime = timestamp("order_1BjQ7hVBYfRnTyNiGfX3z");

Validation

const userId = generate("user");

// Validate format only
validate(userId); // true

// Validate format and prefix
validate(userId, "user"); // true
validate(userId, "admin"); // false

// Invalid IDs return false
validate("not-an-id"); // false

Features

• Time-ordered: IDs sort chronologically using UUIDv7
• Compact: Base62 encoding for shorter, cleaner IDs
• Type-safe: Full TypeScript support with strict typing
• Cross-platform: Works in browsers, Node.js, Deno, and edge runtimes
• Zero dependencies: No external dependencies
• Prefix validation: Enforces consistent naming conventions

Should I Use This?

Fluid is designed for applications that need:

• Human-readable IDs that can be easily identified by type
• Sortable identifiers that maintain chronological order
• URL-safe strings without special characters
• Database-friendly primary keys that index efficiently

Consider alternatives if you need:

• Maximum performance (raw UUIDs are faster)
• Shorter IDs (consider nanoid or similar)
• Custom encoding schemes
• Cryptographic guarantees beyond standard UUIDv7

Database Integration

Storage Strategy

// Generate ID for new user
const userId = generate("user"); // user_1BjQ7hVBYfRnTyNiGfX3z
const { uuid } = parse(userId); // Extract UUID for database

// Store UUID in database, use prefixed ID in APIs
await db.users.create({
  id: uuid, // Store raw UUID: 018a1234-5678-7abc-9def-0123456789ab
  email: "[email protected]",
});

// When reading from database, rebuild the prefixed ID
const dbUser = await db.users.findUnique({ where: { id: uuid } });
const publicId = build("user", dbUser.id); // user_1BjQ7hVBYfRnTyNiGfX3z

// Return prefixed ID in API responses
return { id: publicId, email: dbUser.email };

Database Schema

-- Store UUIDs for efficient indexing
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

-- For polymorphic relationships, store full prefixed IDs
CREATE TABLE activities (
  id UUID PRIMARY KEY,
  subject_id VARCHAR(255), -- "user_1BjQ7hVBYfRnTyNiGfX3z"
  action VARCHAR(50),
  created_at TIMESTAMP DEFAULT NOW()
);

References

• ui7
• UUIDv7 in 33 languages
• Designing APIs for humans: Object IDs
• Stripe keys and IDs