View Source Sqids behaviour (sqids v0.1.0)

Sqids API

ℹ️ Check out the docs entry page for an example on how to use Sqids to generate a module that bypasses the need to pass along sqids context on every encode or decode call.

Summary

Types

Wrapper type for Elixir 1.13 or older

Opts for new/1

t()

Context for Sqids

Callbacks

Returns Supervisor child spec for callback module.

Functions

Decodes an id into zero or more numbers according to sqids's alphabet.

Tries to encode zero or more numbers into as an id, according to sqids's alphabet, blocklist, and minimum length. Returns an error otherwise.

Encodes zero or more numbers into an id, according to sqids's alphabet, blocklist, and minimum length. Raises in case of error.

Creates a context used for both encoding and decoding.

Types

@type enumerable(t) :: Enumerable.t(t)

Wrapper type for Elixir 1.13 or older

@type opts() :: [
  alphabet: String.t(),
  min_length: non_neg_integer(),
  blocklist: enumerable(String.t())
]

Opts for new/1

@opaque t()

Context for Sqids

Callbacks

@callback child_spec() :: Supervisor.child_spec()

Returns Supervisor child spec for callback module.

Functions

@spec decode!(sqids, id) :: numbers
when sqids: t(), id: String.t(), numbers: [non_neg_integer()]

Decodes an id into zero or more numbers according to sqids's alphabet.

Like in the reference implementation, the presence of unknown characters within id will result in an empty list being returned.

@spec encode(sqids, numbers) :: {:ok, id} | {:error, term()}
when sqids: t(), numbers: enumerable(non_neg_integer()), id: String.t()

Tries to encode zero or more numbers into as an id, according to sqids's alphabet, blocklist, and minimum length. Returns an error otherwise.

@spec encode!(sqids, numbers) :: id
when sqids: t(), numbers: enumerable(non_neg_integer()), id: String.t()

Encodes zero or more numbers into an id, according to sqids's alphabet, blocklist, and minimum length. Raises in case of error.

@spec new(opts()) :: {:ok, t()} | {:error, term()}

Creates a context used for both encoding and decoding.

Can receive a list of zero or more opts/0:

  • alphabet: a case and order -sensitive string containing the chars of which generated IDs will be made of;
  • min_length: the minimum length of your generated IDs (padding added if needed);
  • blocklist: an enumerable collection of strings which shouldn't appear in generated IDs.

Returns error if any of the opts/0 is invalid.