Ark

hex.pm Version Build Status License

Ark is a collection of small utilities for common Elixir patterns: things you find yourself rewriting across projects, too small to warrant a dedicated package but absent from the standard library.

The implementations are intentionally simple. They cover the common case well, but your project's needs may outgrow them, at which point reaching for a dedicated library or a custom solution is the right call.

Installation

defp deps do
  [
    {:ark, "~> 0.15"},
  ]
end

Plugins

Ark.BinarySearch

This module provides an integer binary search driven by a comparison callback.

Ark.EctoCursor

This module provides keyset pagination for Ecto queries, with cursors that can be stored in an embedded schema.

cursor = Ark.EctoCursor.new(order_by: [desc: :inserted_at, asc: :id], page_size: 20)

%Ark.EctoCursor.Page{entries: posts, next_cursor: next} =
  Ark.EctoCursor.fetch_page(cursor, MyApp.Post, MyApp.Repo)

Ark.Error

This module provides function to work errors as data.

Ark.Interface

This module provides a way to define protocols that dispatch to functions defined on the implementing struct's own module.

Ark.Ok

This module provides base functions to work with ok/error tuples.

Ark.Opts

This module validates options, given as a keyword list or a map, with a callback and merges them over defaults, with helpers to check the option values.

Ark.Opts.validate!([timeout: 500], %{timeout: 5000, retry: true}, fn
  :timeout, value -> Ark.Opts.pos_integer(value)
  :retry, value -> Ark.Opts.boolean(value)
  _, _ -> :unknown
end)

# => %{timeout: 500, retry: true}

Ark.Paginator

This module provides a helper to build streams from paginated sources.

A user-supplied callback is called with an initial state and is expected to return the items for the current page along with the next state, until it signals that pagination is over.

pages = %{1 => [1, 2, 3], 2 => [4, 5, 6]}

{:ok, stream} =
  Ark.Paginator.stream(1, fn page ->
    case Map.get(pages, page, []) do
      [] -> {:halt, []}
      items -> {:cont, items, page + 1}
    end
  end)

Enum.to_list(stream)
# => [1, 2, 3, 4, 5, 6]

Ark.Retry

This module provides base functions to retry operations.

Ark.StructAccess

This module provides a simple way to implement the Access behaviour for any struct.

Example

defmodule MyStruct do
  defstruct [:k]
  use Ark.StructAccess
end

s = %MyStruct{k: 1}
put_in(s.k, 2)

# => %MyStruct{k: 2}

Ark.Timeout

Helpers to work with numerical timeout values

Ark.Workflow

This module computes values from rules with ordered fallback alternatives, dependencies between rules, namespaces, and a state that persists across runs.

import Ark.Workflow, only: [rule: 1, rule: 2]

wf =
  Ark.Workflow.new()
  |> Ark.Workflow.add_rule(:config, rule(fn _params, _deps, _ctx -> {:ok, read_config()} end))
  |> Ark.Workflow.add_rule(:report, rule([:config], fn params, %{config: config}, _ctx ->
    {:ok, build_report(config, params.month)}
  end))

key = {:report, %{month: 11}}
{:ok, wf} = Ark.Workflow.run(wf, [key])
{:ok, report} = Ark.Workflow.fetch(wf, key)

Documentation

The docs can be found at hexdocs.