Stamp (stamp v0.1.0)

Copy Markdown View Source

Stamp is a fast and flexible Snowflake-flavored ID generator based on 8-byte integers with optional encoding.

Summary

Types

t()
value()

Functions

datetime(id, config)

Returns UTC DateTime stored in the id. This function is for non-Ecto uses. For Ecto fields use datetime/3. Raises ArgumentError on errors.

datetime(id, schema, field)

Returns UTC DateTime stored in the field. Raises ArgumentError on errors.

next_field_id(schema, field, opts \\ [])

Generates next id for the field. Raises ArgumentError on errors.

next_id(sequence_id, config, opts \\ [])

Generates next id using provided sequence_id and configuration. This function is for non-Ecto uses. For Ecto fields use next_field_id/3.

partition(id, config)

Returns partition stored in the id, or nil if the stamp is not partitioned. This function is for non-Ecto uses. For Ecto fields use partition/3. Raises ArgumentError on errors.

partition(id, schema, field)

Returns partition stored in the field, or nil. Raises ArgumentError on errors.

to_integer(value, config)

Converts the id to integer. Returns {:ok, integer_id} or :error if the value can't be decoded.

to_integer(id, schema, field)

Converts the field value to integer. Returns {:ok, integer_id} or :error if the value can't be decoded.

to_integer!(id, config)

Converts the id to integer. Returns the integer id or raises if the value can't be decoded.

to_integer!(id, schema, field)

Converts the field value to integer. Returns integer id or raises if the value can't be decoded.

unpack(id, config)

Unpacks parameters stored in the id. This function is for non-Ecto uses. For Ecto fields use unpack/3. Raises ArgumentError on errors.

unpack(id, schema, field)

Unpacks parameters stored in the field. Raises ArgumentError on errors.

Types

t()

@type t() :: %Stamp{
  node: non_neg_integer() | nil,
  partition: non_neg_integer() | nil,
  sequence: non_neg_integer(),
  time: non_neg_integer()
}

value()

@type value() :: non_neg_integer() | String.t()

Functions

datetime(id, config)

@spec datetime(value(), Stamp.Config.t()) :: DateTime.t()

Returns UTC DateTime stored in the id. This function is for non-Ecto uses. For Ecto fields use datetime/3. Raises ArgumentError on errors.

Arguments:

  • id - stamp in integer or string form (strictly according to config)

  • config - Stamp.Config structure containing parameters for the stamp.

datetime(id, schema, field)

@spec datetime(value(), module(), atom()) :: DateTime.t() | :no_return

Returns UTC DateTime stored in the field. Raises ArgumentError on errors.

Arguments:

  • id - stamp in "loaded" form.

  • schema - Ecto schema module.

  • field - Ecto schema field atom.

next_field_id(schema, field, opts \\ [])

@spec next_field_id(module(), atom(), Keyword.t()) :: value() | :no_return

Generates next id for the field. Raises ArgumentError on errors.

Arguments:

  • schema - Ecto schema module.

  • field - Ecto schema field atom.

  • opts - generation options (same options as in next_id/3).

next_id(sequence_id, config, opts \\ [])

@spec next_id(any(), Stamp.Config.t(), Keyword.t()) :: value() | :no_return

Generates next id using provided sequence_id and configuration. This function is for non-Ecto uses. For Ecto fields use next_field_id/3.

Arguments:

  • sequence_id - unique term used to create sequence for the stamps. Stamps using different sequence_id are supposed to be used in separate contexts and can have intersecting values without causing issues. Do not include config parameters in it - it's done automatically by the library. Good examples: :comment_id, {Comment, :id}.

  • config - Stamp.Config structure containing parameters for generating the ID.

  • opts - generation options.

Supported options:

  • time - OS time in milliseconds, using unix epoch. When provided, Stamp will try to use it for the generation instead of calling System.os_time/1. The number must fit in time_bits without overflow.

  • partition - integer number of the partition that will be used instead of calling partition_fun/0 from the config, if the partitioning is enabled. The number must fit in partition_bits without overflow.

partition(id, config)

@spec partition(value(), Stamp.Config.t()) :: non_neg_integer() | nil

Returns partition stored in the id, or nil if the stamp is not partitioned. This function is for non-Ecto uses. For Ecto fields use partition/3. Raises ArgumentError on errors.

Arguments:

  • id - stamp in integer or string form (strictly according to config)

  • config - Stamp.Config structure containing parameters for the stamp.

partition(id, schema, field)

@spec partition(value(), module(), atom()) :: non_neg_integer() | nil

Returns partition stored in the field, or nil. Raises ArgumentError on errors.

Arguments:

  • id - stamp in "loaded" form.

  • schema - Ecto schema module.

  • field - Ecto schema field atom.

to_integer(value, config)

@spec to_integer(value(), Stamp.Config.t()) :: {:ok, non_neg_integer()} | :error

Converts the id to integer. Returns {:ok, integer_id} or :error if the value can't be decoded.

to_integer(id, schema, field)

@spec to_integer(value(), module(), atom()) :: {:ok, non_neg_integer()} | :error

Converts the field value to integer. Returns {:ok, integer_id} or :error if the value can't be decoded.

Arguments:

  • id - stamp in integer or string form.

  • schema - Ecto schema module.

  • field - Ecto schema field atom.

to_integer!(id, config)

@spec to_integer!(value(), Stamp.Config.t()) :: non_neg_integer() | :no_return

Converts the id to integer. Returns the integer id or raises if the value can't be decoded.

Arguments:

  • id - stamp in integer or string form

  • config - Stamp.Config structure containing parameters for the stamp.

to_integer!(id, schema, field)

@spec to_integer!(value(), module(), atom()) :: non_neg_integer() | :no_return

Converts the field value to integer. Returns integer id or raises if the value can't be decoded.

Arguments:

  • id - stamp in integer or string form.

  • schema - Ecto schema module.

  • field - Ecto schema field atom.

unpack(id, config)

@spec unpack(value(), Stamp.Config.t()) :: t() | :no_return

Unpacks parameters stored in the id. This function is for non-Ecto uses. For Ecto fields use unpack/3. Raises ArgumentError on errors.

Arguments:

  • id - stamp in integer or string form (strictly according to config)

  • config - Stamp.Config structure containing parameters for the stamp.

unpack(id, schema, field)

@spec unpack(value(), module(), atom()) :: t() | :no_return

Unpacks parameters stored in the field. Raises ArgumentError on errors.

Arguments:

  • id - stamp in "loaded" form.

  • schema - Ecto schema module.

  • field - Ecto schema field atom.