Class Scru64Generator

Represents a SCRU64 ID generator.

The generator comes with several different methods that generate a SCRU64 ID:

Flavor Timestamp On big clock rewind
generate Now Returns undefined
generateOrReset Now Resets generator
generateOrSleep Now Sleeps (blocking)
generateOrAwait Now Sleeps (async)
generateOrAbortCore Argument Returns undefined
generateOrResetCore Argument Resets generator

All of these methods return a monotonically increasing ID by reusing the previous timestamp even if the one provided is smaller than the immediately preceding ID's, unless such a clock rollback is considered significant (by default, approx. 10 seconds). A clock rollback may also be detected when a generator has generated too many IDs within a certain unit of time, because this implementation increments the previous timestamp when counter reaches the limit to continue instant monotonic generation. When a significant clock rollback is detected:

  1. generate (OrAbort) methods abort and return undefined immediately.
  2. OrReset variants reset the generator and return a new ID based on the given timestamp, breaking the increasing order of IDs.
  3. OrSleep and OrAwait methods sleep and wait for the next timestamp tick.

The Core functions offer low-level primitives to customize the behavior.

Constructors

constructor

Properties

counterMode counterSize prevNodeCtr prevTimestamp

Methods

generate generateOrAbortCore generateOrAwait generateOrReset generateOrResetCore generateOrSleep getNodeId getNodeIdSize getNodePrev getNodeSpec renewNodeCtr

Constructors

constructor

  • new Scru64Generator(nodeSpec, counterMode?): Scru64Generator

  • Creates a new generator with the given node configuration and counter mode.

    Parameters

    Returns Scru64Generator

    Throws

    SyntaxError if an invalid string nodeSpec is passed or RangeError if an invalid object nodeSpec is passed.

Properties

Private Readonly counterMode

counterMode: CounterMode

Private Readonly counterSize

counterSize: number

Private prevNodeCtr

prevNodeCtr: number

Private prevTimestamp

prevTimestamp: number

Methods

generate

  • generate(): undefined | Scru64Id

  • Generates a new SCRU64 ID object from the current timestamp, or returns undefined upon significant timestamp rollback.

    See the Scru64Generator class documentation for the description.

    Returns undefined | Scru64Id

generateOrAbortCore

  • generateOrAbortCore(unixTsMs, rollbackAllowance): undefined | Scru64Id

  • Generates a new SCRU64 ID object from a Unix timestamp in milliseconds, or returns undefined upon significant timestamp rollback.

    See the Scru64Generator class documentation for the description.

    Parameters

    • unixTsMs: number
    • rollbackAllowance: number

      The amount of unixTsMs rollback that is considered significant. A suggested value is 10_000 (milliseconds).

    Returns undefined | Scru64Id

    Throws

    RangeError if unixTsMs is not a positive integer within the valid range.

generateOrAwait

  • generateOrAwait(): Promise<Scru64Id>

  • Returns a new SCRU64 ID object, or asynchronously sleeps and waits for one if not immediately available.

    See the Scru64Generator class documentation for the description.

    Returns Promise<Scru64Id>

generateOrReset

  • generateOrReset(): Scru64Id

  • Generates a new SCRU64 ID object from the current timestamp, or resets the generator upon significant timestamp rollback.

    See the Scru64Generator class documentation for the description.

    Note that this mode of generation is not recommended because rewinding timestamp without changing nodeId considerably increases the risk of duplicate results.

    Returns Scru64Id

generateOrResetCore

  • generateOrResetCore(unixTsMs, rollbackAllowance): Scru64Id

  • Generates a new SCRU64 ID object from a Unix timestamp in milliseconds, or resets the generator upon significant timestamp rollback.

    See the Scru64Generator class documentation for the description.

    Note that this mode of generation is not recommended because rewinding timestamp without changing nodeId considerably increases the risk of duplicate results.

    Parameters

    • unixTsMs: number
    • rollbackAllowance: number

      The amount of unixTsMs rollback that is considered significant. A suggested value is 10_000 (milliseconds).

    Returns Scru64Id

    Throws

    RangeError if unixTsMs is not a positive integer within the valid range.

generateOrSleep

  • generateOrSleep(): Scru64Id

  • Returns a new SCRU64 ID object, or synchronously sleeps and waits for one if not immediately available.

    See the Scru64Generator class documentation for the description.

    This method uses a blocking busy loop to wait for the next timestamp tick. Use generateOrAwait where possible.

    Returns Scru64Id

getNodeId

  • getNodeId(): number

  • Returns the nodeId of the generator.

    Returns number

getNodeIdSize

  • getNodeIdSize(): number

  • Returns the size in bits of the nodeId adopted by the generator.

    Returns number

getNodePrev

  • getNodePrev(): undefined | Scru64Id

  • Returns the nodePrev value if the generator is constructed with one or undefined otherwise.

    Returns undefined | Scru64Id

getNodeSpec

  • getNodeSpec(): string

  • Returns the node configuration specifier describing the generator state.

    Returns string

Private renewNodeCtr

  • renewNodeCtr(timestamp): number

  • Calculates the combined nodeCtr field value for the next timestamp tick.

    Parameters

    • timestamp: number

    Returns number

Settings

Member Visibility

Theme

On This Page

constructorcounterModecounterSizeprevNodeCtrprevTimestampgenerategenerateOrAbortCoregenerateOrAwaitgenerateOrResetgenerateOrResetCoregenerateOrSleepgetNodeIdgetNodeIdSizegetNodePrevgetNodeSpecrenewNodeCtr