AbsintheRelayKeysetConnection.CursorTranslator behaviour (absinthe_relay_keyset_connection v2.1.1)

View Source

A cursor translator handles encoding and decoding pagination cursors.

This module provides the behaviour for implementing a cursor translator. An example use case of this module would be a cursor translator that encodes and decodes signed or encrypted pagination cursors.

Example Cursor Translator

A basic example that encodes and decodes cursors using Jason and base64:

defmodule MyApp.Absinthe.Cursor do
  @behaviour AbsintheRelayKeysetConnection.CursorTranslator

  @impl AbsintheRelayKeysetConnection.CursorTranslator
  def from_key(key_map, cursor_columns, config \ %{}) do
    null_coalesce = Map.get(config, :null_coalesce, %{})
    
    values = 
      cursor_columns
      |> Enum.map(fn column ->
        value = Map.fetch!(key_map, column)
        case value do
          nil -> Map.get(null_coalesce, column, nil)
          _ -> value
        end
      end)
    
    values
    |> Jason.encode!()
    |> Base.encode64(padding: false)
  end

  @impl AbsintheRelayKeysetConnection.CursorTranslator
  def to_key(encoded_cursor, expected_columns, _config \ %{}) do
    values = encoded_cursor |> Base.decode64!(padding: false) |> Jason.decode!()
    key = expected_columns |> Enum.zip(values) |> Map.new()

    {:ok, key}
  end
end

Summary

Types

A key of the column of the node being paginated.

A string containing the encoded cursor.

A map containing the node data.

Callbacks

Creates the cursor string from a key.

Creates the cursor string from a key with additional configuration.

Rederives the key from the cursor string.

Rederives the key from the cursor string with additional configuration.

Types

column_key()

@type column_key() :: atom() | String.t()

A key of the column of the node being paginated.

encoded_cursor()

@type encoded_cursor() :: String.t()

A string containing the encoded cursor.

key_map()

@type key_map() :: %{required(column_key()) => term()}

A map containing the node data.

Callbacks

from_key(key_map, list)

@callback from_key(key_map(), [column_key()]) :: encoded_cursor()

Creates the cursor string from a key.

Converts a key map into a cursor string using the given cursor columns.

from_key(key_map, list, config)

@callback from_key(key_map(), [column_key()], config :: map()) :: encoded_cursor()

Creates the cursor string from a key with additional configuration.

Converts a key map into a cursor string using the given cursor columns, applying any configured transformations like null coalescing.

Configuration Options

  • :null_coalesce - Map of column names to coalesce values for NULL handling

to_key(encoded_cursor, expected_columns)

@callback to_key(encoded_cursor(), expected_columns :: [column_key()]) ::
  {:ok, key_map()} | {:error, term()}

Rederives the key from the cursor string.

Converts a cursor string into a key map using the given cursor columns.

to_key(encoded_cursor, expected_columns, config)

@callback to_key(encoded_cursor(), expected_columns :: [column_key()], config :: map()) ::
  {:ok, key_map()} | {:error, term()}

Rederives the key from the cursor string with additional configuration.

Converts a cursor string into a key map using the given cursor columns, applying any configured transformations like null coalescing.

Configuration Options

  • :null_coalesce - Map of column names to coalesce values for NULL handling