leodutra/simpleflakes

Fast and test-driven distributed 64-bit ID generation, using pure JavaScript, for Node.js.

simpleflakes

Simpleflake is the smartest way to generate a 64-bit + time-ordered + snowflake based ID. See the presentation!

Test-driven, pure JavaScript

This port is test-driven and no release goes out without tests.
Also, this library does not rely on low-level bindings, with OpenSSL, libgmp or anything beyond pure JavaScript.

Assumes original Python implementation as reference and fixes epoch (starts on 2000-01-01T00:00:00.000Z (UTC) while Python API v0.1.5 epoch starts on 2000-01-01T05:00:00.000Z).

simpleflakes uses the TC39 BigInt implementation when running on newer versions of Node.js. When BigInt is not available, Fedor Indutny's big number library (bn.js) is used as the fastest fallback for big number calculations.

How to Install:

npm install simpleflakes --save

Usage:

const { simpleflake } = require('simpleflakes');

const flakeBigInt = simpleflake()

// simpleflake(
//    timestamp = Date.now(), 
//    random_bits = 23-bit random, 
//     epoch = Date.UTC(2000, 0, 1)
// )
// returns BigInt on newer Node.js or bn.js BigNum on older engines.

flakeBigInt.toString();       // 4234673179811182512
flakeBigInt.toString(16);     // 3ac494d21e84f7b0
flakeBigInt.toString(2);      // 11101011000100...
flakeBigInt.toString(36);     // 20rfh5

You can check the original Python API 0.1.5 documentation for more info.

Reference

// Main flake function and its defaults
simpleflake(
    timestamp = Date.now(), 
    random_bits = 23-bit random, 
    epoch = Date.UTC(2000, 0, 1)
)

// Static constant epoch for simpleflake timestamps, starts at the year 2000  
simpleflake.SIMPLEFLAKE_EPOCH // const = 946702800

// Show binary digits of a number, pads to 64 bits unless specified.
simpleflake.binary(number, padding=true)

// Extract a portion of a bit string. Similar to substr().
simpleflake.extractBits(data, shift, length)

// Parses a simpleflake and returns a named tuple with the parts.
simpleflake.parseSimpleflake(flake)

// original API alias for SimpleFlake class, from the Python API
simpleflake.simpleflakeStruct

// same as simpleflake.simpleflakeStruct
SimpleFlake.SimpleFlakeStruct

License:

MIT

simpleflakes's Issues

feature request: typescript types

Seems like a great library. Any chance of providing typescript types?

minor readme correction?

In the example showing the function signature for simpleflake I see this: ,random_bits=23-bit random,.

Is that supposed to be 32-bit?