dcflake

Parse, create, validate, and format Discord Snowflakes with zero runtime dependencies and first-class TypeScript support.

Install

npm install dcflake

Why dcflake?

Discord Snowflakes are 64-bit IDs that encode when an object was created, plus a worker ID, process ID, and increment. dcflake gives you safe, typed utilities for both decoding and creating them.

• Works with decimal strings, bigint, and safe JavaScript numbers
• Never loses precision by converting IDs to number
• Validates malformed, negative, and out-of-range IDs
• Includes ESM and CommonJS builds with declarations
• No runtime dependencies

Usage

import {
  parse,
  getDate,
  create,
  toDiscordTimestamp,
} from 'dcflake';

const id = '90339695967350784';

getDate(id); // Date: 2015-09-07T06:57:41.949Z
toDiscordTimestamp(id, 'R'); // "<t:1441609061:R>"

parse(id);
// {
//   id: '90339695967350784',
//   timestamp: 1441609061949,
//   date: 2015-09-07T06:57:41.949Z,
//   workerId: 0,
//   processId: 3,
//   increment: 0
// }

API

Validation and parsing

isSnowflake(value);             // boolean type guard
isValid(value);                 // alias for isSnowflake
normalize(123n);                // "123"
parse(id);                      // all decoded fields
tryParse(value);                // parts or null, never throws

isSnowflake accepts canonical unsigned decimal strings representing an unsigned 64-bit value. parse and the field helpers also accept bigint and safe integer numbers. IDs are kept as strings so large values remain exact.

Decoding

getTimestamp(id);       // Unix milliseconds
getUnix(id);            // Unix seconds
getDate(id);            // JavaScript Date
getWorkerId(id);        // 0–31
getProcessId(id);       // 0–31
getIncrement(id);       // 0–4095
timestamp(id);           // alias for getTimestamp
date(id);                // alias for getDate

Creating

create({
  timestamp: Date.now(),
  workerId: 1,
  processId: 2,
  increment: 3,
});

fromDate(new Date(), { workerId: 1 });
fromTimestamp(Date.now(), { processId: 2 });

timestamp is Unix milliseconds and defaults to the current time. Discord's Snowflake timestamp field starts at 2015-01-01T00:00:00.000Z.

Time and comparison helpers

age(id);                              // age in milliseconds
toDiscordTimestamp(id, 'F');          // "<t:...:F>"
compare(first, second);               // -1, 0, or 1
isBefore(id, Date.now());             // boolean
isAfter(id, new Date());              // boolean

Discord Snowflake layout

63                    22 21       17 16       12 11             0
+-----------------------+-----------+-----------+----------------+
| milliseconds since    | worker ID | process ID|   increment    |
| Discord epoch (42)    |   (5)     |   (5)     |      (12)       |
+-----------------------+-----------+-----------+----------------+

License

MIT