View Source AshJason

Module Version Hex Docs License

Ash resource extension for implementing Jason.Encoder protocol.

Installation

Add to the deps, get deps (mix deps.get), compile them (mix deps.compile).

def deps do
  [
    {:ash_jason, "~> 0.3.1"},
  ]
end

Usage

Add AshJason.Extension to extensions list in use Ash.Resource:

defmodule Example.Resource do
  use Ash.Resource,
    extensions: [Ash.ULID.Extension]
end

Configuration

The process to get data for json happens with three steps:

  • Pick keys from a record.
  • Merge some fixed values.
  • Customize a result.

By default only first step happens and it picks all non-private fields (attributes, relationships, aggregates, calculations) with loaded non-nil values.

For configuration there is an optional jason dsl section:

defmodule Example.Resource do
  use Ash.Resource,
    extensions: [Ash.ULID.Extension]

  jason do
    # options
  end
end

pick

Keys to pick from a record and include in json. Values of nil/Ash.NotLoaded/Ash.NotSelected are omitted.

Can be specified as a fixed explicit list of keys or a map with a configuration of default behaviour.

Map can have such options as:

  • private? - Whenever to pick private fields.
  • sensitive? - Whenever to pick sensitive fields.
  • include - Keys to pick. In addition to fields.
  • exclude - Keys not to pick.
jason do
  # Pick only those listed keys
  pick [:only_some_field]

  # Pick non-sensitive fields
  pick %{private?: true}

  # Pick non-private fields
  pick %{sensitive?: true}

  # Pick all fields
  pick %{private?: true, sensitive?: true}

  # Pick usual but include and exclude some specific keys
  pick %{include: [:ok_private_field], exclude: [:irrelevant_public_field]}
end

merge

A map to merge into json.

jason do
  merge %{merged_key: "merged_value"}
end

customize

A function to customize json. Receives a current resulted json map and a source resource record. Returns a modified json map.

jason do
  customize fn result, _record ->
    result |> Map.put(:custom_key, "custom_value")
  end
end

Jason docs.