ClassScru128Generator

Represents a SCRU128 ID generator that encapsulates the monotonic counters and other internal states.

Example

import { Scru128Generator } from "scru128";

const g = new Scru128Generator();
const x = g.generate();
console.log(String(x));
console.log(x.toBigInt());

Remarks

The generator comes with four different methods that generate a SCRU128 ID:

Flavor Timestamp On big clock rewind
generate Now Resets generator
generateOrAbort Now Returns undefined
generateOrResetCore Argument Resets generator
generateOrAbortCore Argument Returns undefined

All of the four return a monotonically increasing ID by reusing the previous timestamp even if the one provided is smaller than the immediately preceding ID's. However, when such a clock rollback is considered significant (by default, more than ten seconds):

  1. generate (OrReset) methods reset the generator and return a new ID based on the given timestamp, breaking the increasing order of IDs.
  2. OrAbort variants abort and return undefined immediately.

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

Constructors

constructor

Methods

[iterator] generate generateOrAbort generateOrAbortCore generateOrResetCore next

Constructors

constructor

  • new Scru128Generator(randomNumberGenerator?): Scru128Generator

  • Creates a generator object with the default random number generator, or with the specified one if passed as an argument. The specified random number generator should be cryptographically strong and securely seeded.

    Parameters

    • OptionalrandomNumberGenerator: {
          nextUint32(): number;
      }
      • nextUint32:function
        • nextUint32(): number

        • Returns a 32-bit random unsigned integer.

          Returns number

    Returns Scru128Generator

Methods

[iterator]

  • [iterator](): Iterator<Scru128Id, undefined, any>

  • Returns an infinite iterator object that produces a new ID for each call of next().

    Returns Iterator<Scru128Id, undefined, any>

    Example

    import { Scru128Generator } from "scru128";

    const [a, b, c] = new Scru128Generator();
    console.log(String(a)); // e.g., "038mqr9e14cjc12dh9amw7i5o"
    console.log(String(b)); // e.g., "038mqr9e14cjc12dh9dtpwfr3"
    console.log(String(c)); // e.g., "038mqr9e14cjc12dh9e6rjmqi"

generate

  • generate(): Scru128Id

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

    See the Scru128Generator class documentation for the description.

    Returns Scru128Id

generateOrAbort

  • generateOrAbort(): undefined | Scru128Id

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

    See the Scru128Generator class documentation for the description.

    Returns undefined | Scru128Id

    Example

    import { Scru128Generator } from "scru128";

    const g = new Scru128Generator();
    const x = g.generateOrAbort();
    const y = g.generateOrAbort();
    if (y === undefined) {
      throw new Error("The clock went backwards by ten seconds!");
    }
    console.assert(x.compareTo(y) < 0);

generateOrAbortCore

  • generateOrAbortCore(timestamp, rollbackAllowance): undefined | Scru128Id

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

    See the Scru128Generator class documentation for the description.

    Parameters

    • timestamp: number
    • rollbackAllowance: number

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

    Returns undefined | Scru128Id

    Throws

    RangeError if timestamp is not a 48-bit positive integer.

generateOrResetCore

  • generateOrResetCore(timestamp, rollbackAllowance): Scru128Id

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

    See the Scru128Generator class documentation for the description.

    Parameters

    • timestamp: number
    • rollbackAllowance: number

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

    Returns Scru128Id

    Throws

    RangeError if timestamp is not a 48-bit positive integer.

next

  • next(): IteratorResult<Scru128Id, undefined>

  • Returns a new SCRU128 ID object for each call, infinitely.

    This method wraps the result of generate in an IteratorResult object to use this as an infinite iterator.

    Returns IteratorResult<Scru128Id, undefined>

Settings

Member Visibility

On This Page

Constructors
Methods