Flop.Cursor (Flop v0.10.0) View Source
Functions for encoding, decoding and extracting cursor values.
Link to this section Summary
Functions
Decodes a cursor value.
Same as Flop.Cursor.decode/1
, but raises an error if the cursor is invalid.
Encodes a cursor value.
Takes a map or a struct and the order_by
field list and returns the cursor
value.
Retrieves the start and end cursors from a query result.
Link to this section Functions
Specs
Decodes a cursor value.
Returns :error
if the cursor cannot be decoded or the decoded term is not a
map with atom keys.
iex> Flop.Cursor.decode("g3QAAAABZAACaWRiAAACDg==")
{:ok, %{id: 526}}
iex> Flop.Cursor.decode("AAAH")
:error
iex> f = fn a -> a + 1 end
iex> cursor = Flop.Cursor.encode(%{a: f})
iex> Flop.Cursor.decode(cursor)
:error
iex> cursor = Flop.Cursor.encode(a: "b")
iex> Flop.Cursor.decode(cursor)
:error
iex> cursor = Flop.Cursor.encode(%{"a" => "b"})
iex> Flop.Cursor.decode(cursor)
:error
Trying to decode a cursor that contains non-existent atoms also results in an error.
iex> Flop.Cursor.decode("g3QAAAABZAAGYmFybmV5ZAAGcnViYmVs")
:error
Specs
Same as Flop.Cursor.decode/1
, but raises an error if the cursor is invalid.
iex> Flop.Cursor.decode!("g3QAAAABZAACaWRiAAACDg==")
%{id: 526}
iex> Flop.Cursor.decode!("AAAH")
** (RuntimeError) invalid cursor
Specs
Encodes a cursor value.
iex> Flop.Cursor.encode(%{name: "Peter", email: "peter@mail"})
"g3QAAAACZAAFZW1haWxtAAAACnBldGVyQG1haWxkAARuYW1lbQAAAAVQZXRlcg=="
Specs
Takes a map or a struct and the order_by
field list and returns the cursor
value.
This function is used as a default if no :get_cursor_value_func
option is
set.
iex> record = %{id: 20, name: "George", age: 62}
iex>
iex> Flop.Cursor.get_cursor_from_map(record, [:id])
%{id: 20}
iex> Flop.Cursor.get_cursor_from_map(record, [:name, :age])
%{age: 62, name: "George"}
Specs
get_cursors([any()], [atom()], [Flop.option()]) :: {binary(), binary()} | {nil, nil}
Retrieves the start and end cursors from a query result.
iex> results = [%{name: "Mary"}, %{name: "Paul"}, %{name: "Peter"}]
iex> order_by = [:name]
iex>
iex> {start_cursor, end_cursor} =
...> Flop.Cursor.get_cursors(results, order_by)
{"g3QAAAABZAAEbmFtZW0AAAAETWFyeQ==", "g3QAAAABZAAEbmFtZW0AAAAFUGV0ZXI="}
iex>
iex> Flop.Cursor.decode(start_cursor)
{:ok, %{name: "Mary"}}
iex> Flop.Cursor.decode(end_cursor)
{:ok, %{name: "Peter"}}
If the result set is empty, the cursor values will be nil
.
iex> Flop.Cursor.get_cursors([], [:id])
{nil, nil}
If the records in the result set are not maps, you can pass a custom cursor value function.
iex> results = [{"Mary", 1936}, {"Paul", 1937}, {"Peter", 1938}]
iex> cursor_func = fn {name, year}, order_fields ->
...> Enum.into(order_fields, %{}, fn
...> :name -> {:name, name}
...> :year -> {:year, year}
...> end)
...> end
iex> opts = [get_cursor_value_func: cursor_func]
iex>
iex> {start_cursor, end_cursor} =
...> Flop.Cursor.get_cursors(results, [:name, :year], opts)
{"g3QAAAACZAAEbmFtZW0AAAAETWFyeWQABHllYXJiAAAHkA==",
"g3QAAAACZAAEbmFtZW0AAAAFUGV0ZXJkAAR5ZWFyYgAAB5I="}
iex>
iex> Flop.Cursor.decode(start_cursor)
{:ok, %{name: "Mary", year: 1936}}
iex> Flop.Cursor.decode(end_cursor)
{:ok, %{name: "Peter", year: 1938}}