Skip to content

Latest commit

 

History

History
172 lines (123 loc) · 4.62 KB

README.md

File metadata and controls

172 lines (123 loc) · 4.62 KB
Raw

Pathex

Speed or composability? Choose both!

Elixir 1.17 warning

It turns out that Elixir 1.17 release has 3 bugs which block reliable usage of Pathex library, one of which is critical. So please, do not use Elixir 1.17 with the Pathex library. However, these issues are fixed in upcoming Elixir 1.18 release.

What is Pathex?

Pathex is a library for performing fast actions with nested data structures in Elixir. With pathex you can trivially set, get and update values in structures in a functional manner. It provides all necessary logic to manipulate data structures in different ways using flexible functional lens pattern.

Why another library?

Existing methods of accesssing data in nested structures are either slow (like Focus) or do not provide enough functionality (like Access). For example setting the value in structure with Pathex is 70-160x faster than Focus or 2-3x faster than put_in and get_in

You can checkout benchmarks at https://github.com/hissssst/pathex_bench

Usage

Pathex is really simple and straightforward to use (almost like Enum). You don't need to learn any specific language, just create paths with path and use verbs with them.

Add it to your module

# This will import path macro and operators and require Pathex
use Pathex

Or just import Pathex

Create the path

path_to_streets = path :user / :private / :addresses / 0 / :street
path_in_json = path "users" / 1 / "street", :json

This creates closure which can get, set, update and delete values in this path

Use the path

{:ok, "6th avenue" = street} =
  %{
    user: %{
      id: 1,
      name: "hissssst",
      private: %{
        phone: "123-456-789",
        addresses: [
           [city: "City", street: "6th avenue", mail_index: 123456]
        ]
      }
    }
  }
  |> Pathex.view(path_to_streets)

%{
  "users" => %{
    1 => %{"street" => "6th avenue"}
  }
} = Pathex.force_set!(%{}, path_in_json, street)

Features

Pathex has a lot of different features and can even compete with code written by hand in terms of efficiency. Pathex significantly reduces the time to write a code which manipulates nested structure, while providing efficiency and composability. No more functions like get_users, set_users, update_users! No more XPaths, JSONPaths, CSS Selectors!

Easy to use

It's not harder to use than Map or Enum! Check out the cheatsheet for common tasks.

Pathex also provides more information about errors than any other tool.

iex(1)> field = :email
iex(2)> Pathex.view!(%{}, path(:users) ~> all() ~> path(:personal / field))
** (Pathex.Error)
  Couldn't find element

    Path:      path(:users) ~> all() ~> path(:personal / :email)

    Structure: %{}

Fast

Paths are just a set of pattern-matching cases. This is done to extract maximum efficiency from BEAM's pattern-matching compiler.

# Code for viewing variables for path
path(1 / "y", :map)

# Almost equals to
case input do
  %{1 => %{"y" => res}} ->
    {:ok, res}

  _ ->
    :error
end

Reusable

One path can be used to update, get, set, delete or update a value in the structure! And these paths can even be composed together. This composition is very efficient, there's no need to concatenate lists like Access does.

# User structure
user = %User{
  personal: %{fname: "Kabs", sname: "Rocks"},
  phone: "123-456-789"
}

# Path to username in user structure
username = path(:personal / :fname)

# Get a username
{:ok, "Kabs"} = Pathex.view(user, username)

# Set a username
another_user =
  %User{
    personal: %{fname: "Blabs", sname: "Rocks"},
    phone: "123-456-789"
  } = Pathex.set!(user, username, "Blabs")

# Get all usernames!
import Pathex.Lenses
["Kabs", "Blabs"] =
  [
    user,
    another_user
  ]
  |> Pathex.view!(all() ~> username)

Pathex can be used to manipulate different nested data structures. From GenServer state to HTML or Elixir's AST!

Extensible

Pathex is built around simple primitive called path-closure, which is a simple closure with clearly defined specification. Anything complying with Pathex.t() spec can be used within Pathex.

Installation

def deps do
  [
    {:pathex, "~> 2.0"}
  ]
end

Pathex is significantly faster with OTP 26

Contributions

Welcome! If you want to get your hands dirty, you can check existing TODO's.

By the way

If you have any suggestions or want to change something in this library don't hesitate to open an issue. If you have any whitepapers about functional lenses, you can add them in a PR to the bottom of this readme