simpleflakes

Features

Table of Contents

What is Simpleflake?

References

Installation

npm install simpleflakes

Quick Start

JavaScript (CommonJS)

const { simpleflake } = require('simpleflakes');
// Generate a unique ID
const id = simpleflake();
console.log(id); // 4234673179811182512n (BigInt)
// Convert to different formats
console.log(id.toString()); // "4234673179811182512"
console.log(id.toString(16)); // "3ac494d21e84f7b0" (hex)
console.log(id.toString(36)); // "w68acyhy50hc" (base36 - shortest)

TypeScript / ES Modules

import { simpleflake, parseSimpleflake, type SimpleflakeStruct } from 'simpleflakes';
// Generate with full type safety
const id: bigint = simpleflake();
// Parse the ID to extract timestamp and random bits
const parsed: SimpleflakeStruct = parseSimpleflake(id);
console.log(parsed.timestamp); // "1693244847123" (Unix timestamp as string)
console.log(parsed.randomBits); // "4567234" (Random component as string)

Advanced Usage

Custom Parameters

// Generate with custom timestamp and random bits
const customId = simpleflake(
 Date.now(), // timestamp (default: Date.now())
 12345, // random bits (default: 23-bit random)
 Date.UTC(2000, 0, 1) // epoch (default: Year 2000)
);

Working with Binary Data

import { binary, extractBits } from 'simpleflakes';
const id = simpleflake();
// View binary representation
console.log(binary(id));
// Output: "0011101011000100100100110100001000011110100001001111011110110000"
// Extract specific bit ranges
const timestampBits = extractBits(id, 23n, 41n); // Extract 41 bits starting at position 23
const randomBits = extractBits(id, 0n, 23n); // Extract first 23 bits

Batch Generation

// Generate multiple IDs efficiently
function generateBatch(count) {
 const ids = [];
 for (let i = 0; i < count; i++) {
 ids.push(simpleflake());
 }
 return ids;
}
const batch = generateBatch(1000);
console.log(`Generated ${batch.length} unique IDs`);

ID Structure

Performance

// Benchmark results (operations per second)
simpleflake() // ~8.8M+ ops/sec
parseSimpleflake() // ~3.9M+ ops/sec
binary() // ~26M+ ops/sec

Architecture

Why 64-bit IDs?

Distributed Generation

Use Cases

Database Primary Keys

// Perfect for database IDs - time-ordered and unique
const userId = simpleflake();
await db.users.create({ id: userId.toString(), name: "John" });

Distributed System IDs

// Each service can generate IDs independently
const serviceAId = simpleflake(); // Service A
const serviceBId = simpleflake(); // Service B
// No coordination needed, guaranteed unique across services

Short URLs

// Generate compact URL identifiers
const shortId = simpleflake().toString(36); // "w68acyhy50hc"
const url = `https://short.ly/${shortId}`;

Event Tracking

// Time-ordered event IDs for chronological processing
const eventId = simpleflake();
await analytics.track({ eventId, userId, action: "click" });

API Reference

Core Functions

simpleflake(timestamp?, randomBits?, epoch?): bigint

const id = simpleflake();
const customId = simpleflake(Date.now(), 12345, Date.UTC(2000, 0, 1));

parseSimpleflake(flake): SimpleflakeStruct

const parsed = parseSimpleflake(4234673179811182512n);
console.log(parsed.timestamp); // "1693244847123"
console.log(parsed.randomBits); // "4567234"

binary(value, padding?): string

console.log(binary(42n)); // "0000000000000000000000000000000000000000000000000000000000101010"
console.log(binary(42n, false)); // "101010"

extractBits(data, shift, length): bigint

const bits = extractBits(0b11110000n, 4n, 4n); // Extract 4 bits starting at position 4
console.log(bits); // 15n (0b1111)

Constants

SIMPLEFLAKE_EPOCH: number

import { SIMPLEFLAKE_EPOCH } from 'simpleflakes';
console.log(SIMPLEFLAKE_EPOCH); // 946684800000

TypeScript Types

interface SimpleflakeStruct {
 timestamp: bigint; // Unix timestamp as bigint (since 2000)
 randomBits: bigint; // Random component as bigint
}

Migration Guide

From UUID

// Before (UUID v4)
import { v4 as uuidv4 } from 'uuid';
const id = uuidv4(); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
// After (Simpleflake)
import { simpleflake } from 'simpleflakes';
const id = simpleflake().toString(36); // "w68acyhy50hc" (shorter!)

From Twitter Snowflake

// Simpleflake is backwards compatible with Snowflake structure
// Just different bit allocation:
// - Snowflake: 41 bits timestamp + 10 bits machine + 12 bits sequence
// - Simpleflake: 41 bits timestamp + 23 bits random
//
// *double-check epoch

Comparison

Core Characteristics

Technical Features

Contributing

License

Credits