AshJason

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, "~> 1.0.1"},
  ]
end

Usage

Add AshJason.Resource to extensions list within use Ash.Resource options:

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

Configuration

The process to get data for json happens with five potential steps:

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

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: [AshJason.Resource]

  jason do
    # options
  end
end

pick

Keys to pick from a record and include in json. Values of nil/Ash.NotLoaded/Ash.ForbiddenField 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

rename

A mapping for renaming keys in json. Can be a map or a keyword list.

jason do
  rename original_name: "ResultedName"
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

order

Can be specified as a boolean, a sort function or a fixed explicit list of keys in a desired order.

If it is a list then it also omits keys not present in that list.

jason do
  # Order with standard `Enum.sort`
  order true

  # Order with a custom sort function
  order fn keys -> Enum.sort(keys, :desc) end

  # Order in accordance with a list
  order [:a, :b, :c]
end

Links

Jason docs.