calcinator

v5.0.0

calcinator v5.0.0 Calcinator.Resources behaviour View Source

A module that exposes Ecto schema structs

Link to this section Summary

Types

id()

ID that uniquely identifies the struct

pagination()

Pagination information returned from the backing store

params()
query_options()

  • :associations - associations to load in the struct

    • :filters - filters on the result
    • :meta - meta data that is traded back and forth between clients and servers that don’t fit into JSONAPI, such as Calcinator.Meta.Beam.
    • :page - the page used for pagination. nil implies no pagination, not default pagination.
    • :sorts - the directions to sort fields on the primary resource or its associations
sandbox_access_token()
t()

A module that implements the Resources behaviour

Functions

attribute_to_field(attribute, ecto_schema_module)

Converts the attribute to a field if a corresponding field exists in ecto_schema_module

split_filter_value(comma_separated)

JSONAPI filter values that allow multiple values, similar to includes, are comma separated without spaces, instead of having to do String.split(comma_separated_values, ",") in all filters that accept multiple values, this function can be used

unknown_filter(name)

Error when a filter name is not supported by the callback module

Callbacks

allow_sandbox_access(sandbox_access_token)

Allows access to sandbox for testing

changeset(params)

Changeset for creating a struct from the params

changeset(resource, params)
  • Changeset for updating resource with params.
  • Changeset for deleting resource (params will be an empty map)
delete(changeset, query_options)

Deletes a single struct in a changeset

get(id, query_options)

Gets a single struct

insert(changeset, query_options)

insert(changeset, query_options)

list(query_options)

Gets a list of structs

sandboxed?()

Returns

update(changeset, query_options)

Applies updates in changeset

update(resource, params, query_options)

Updates struct

Link to this section Types

Link to this type id() View Source 
id() :: term

ID that uniquely identifies the struct

Link to this type pagination() View Source 
pagination() :: map

Pagination information returned from the backing store.

Link to this type params() View Source 
params() :: map
Link to this type query_options() View Source 
query_options() :: %{optional(:associations) => atom | [atom], optional(:filters) => %{optional(String.t) => String.t}, optional(:meta) => %{optional(String.t) => Alembic.json}, optional(:page) => Resources.Page.t | nil, optional(:sorts) => Sorts.t}
  • :associations - associations to load in the struct
  • :filters - filters on the result
  • :meta - meta data that is traded back and forth between clients and servers that don’t fit into JSONAPI, such as Calcinator.Meta.Beam.
  • :page - the page used for pagination. nil implies no pagination, not default pagination.
  • :sorts - the directions to sort fields on the primary resource or its associations
Link to this type sandbox_access_token() View Source 
sandbox_access_token() :: %{:owner => term, optional(atom) => any}
Link to this type t() View Source 
t() :: module

A module that implements the Resources behaviour

Link to this section Functions

Link to this function attribute_to_field(attribute, ecto_schema_module) View Source

Converts the attribute to a field if a corresponding field exists in ecto_schema_module

If a field exists, then it is returned. This includes fields with _ that have - in their attribute name and virtual fields.

iex> Calcinator.Resources.attribute_to_field("name", Calcinator.Resources.TestAuthor)
{:ok, :name}
iex> Calcinator.Resources.attribute_to_field("password-confirmation", Calcinator.Resources.TestAuthor)
{:ok, :password_confirmation}

Invalid field names will return an error

iex> Calcinator.Resources.attribute_to_field("password-hash", Calcinator.Resources.TestAuthor)
{:error, "password-hash"}

Associations are not fields, so they will return an error

iex> Calcinator.Resources.attribute_to_field("author", Calcinator.Resources.TestPost)
{:error, "author"}

Returns

  • {:ok, field} - attribute with - has the corresponding field with _ in ecto_schema_module
  • {:error, attribute} - attribute does not have corresponding field in ecto_schema_module
Link to this function split_filter_value(comma_separated) View Source 
split_filter_value(String.t) :: [String.t]

JSONAPI filter values that allow multiple values, similar to includes, are comma separated without spaces, instead of having to do String.split(comma_separated_values, ",") in all filters that accept multiple values, this function can be used.

iex> Calcinator.Resources.split_filter_value("1,2,3")
["1", "2", "3"]
Link to this function unknown_filter(name) View Source 
unknown_filter(name :: String.t) :: Alembic.Document.t

Error when a filter name is not supported by the callback module.

iex> Calcinator.Resources.unknown_filter("name")
%Alembic.Document{
  errors: [
    %Alembic.Error{
      detail: "Unknown name filter",
      source: %Alembic.Source{
        pointer: "/filter/name"
      },
      status: "422",
      title: "Unknown Filter"
    }
  ]
}

Link to this section Callbacks

Link to this callback allow_sandbox_access(sandbox_access_token) View Source 
allow_sandbox_access(sandbox_access_token) ::
  :ok |
  {:error, :sandbox_access_disallowed}

Allows access to sandbox for testing

Link to this callback changeset(params) View Source 
changeset(params) ::
  {:ok, Ecto.Changeset.t} |
  {:error, :ownership}

Changeset for creating a struct from the params

Returns

  • {:ok, Ecto.Changeset.t} - a changeset was created with no error while trying to access the backing store
  • {:error, :ownership} - connection to backing store was not owned by the calling process when associations were preloaded into the data for the changeset. many_to_many associations require the associations to be preloaded into the Ecto.Changeset.t data before calling Ecto.Changeset.put_assoc/3.
Link to this callback changeset(resource, params) View Source 
changeset(resource :: Ecto.Schema.t, params) ::
  {:ok, Ecto.Changeset.t} |
  {:error, :ownership}
  • Changeset for updating resource with params.
  • Changeset for deleting resource (params will be an empty map)

Returns

  • {:ok, Ecto.Changeset.t} - a changeset was created with no error while trying to access the backing store
  • {:error, :ownership} - connection to backing store was not owned by the calling process when associations were preloaded into the data for the changeset. many_to_many associations require the associations to be preloaded into the Ecto.Changeset.t data before calling Ecto.Changeset.put_assoc/3.
Link to this callback delete(changeset, query_options) View Source 
delete(changeset :: Ecto.Changeset.t, query_options) ::
  {:ok, struct} |
  {:error, :ownership} |
  {:error, :timeout} |
  {:error, Ecto.Changeset.t}

Deletes a single struct in a changeset

Returns

  • {:ok, struct} - the delete succeeded and the returned struct is the state before delete
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :timeout} - timeout occured while deleting struct from backing store.
  • {:error, Ecto.Changeset.t} - errors while deleting the changeset. Ecto.Changeset.t errors contains errors. These will normally be constraint errors or only those validations that can occur in prepare_changes callbacks that require Ecto.Changeset.t action and or repo to be set.
Link to this callback get(id, query_options) View Source 
get(id, query_options) ::
  {:ok, struct} |
  {:error, :not_found} |
  {:error, :ownership} |
  {:error, :timeout} |
  {:error, reason :: term}

Gets a single struct

Returns

  • {:ok, struct} - id was found.
  • {:error, :not_found} - id was not found.
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :timeout} - timeout occured while getting id from backing store.
  • {:error, reason} - an error occurred with the backing store for reason that is backing store specific.
Link to this callback insert(changeset, query_options) View Source 
insert(changeset :: Ecto.Changeset.t | params, query_options) ::
  {:ok, struct} |
  {:error, :ownership} |
  {:error, :timeout} |
  {:error, Ecto.Changeset.t}

insert(changeset, query_options)

Inserts changeset into a single new struct.

Returns

  • {:ok, struct} - changeset was inserted into struct
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :timeout} - timeout occured while inserting changeset into backing store.
  • {:error, Ecto.Changeset.t} - insert failed. Ecto.Changeset.t errors contain errors.

insert(params, query_options)

Inserts params into a single new struct.

Returns

  • {:ok, struct} - params were inserted into struct
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :timeout} - timeout occured while inserting params into backing store.
  • {:error, Ecto.Changeset.t} - insert failed. Ecto.Changeset.t errors contain errors.
Link to this callback list(query_options) View Source 
list(query_options) ::
  {:ok, [struct], pagination | nil} |
  {:error, :ownership} |
  {:error, :timeout} |
  {:error, reason :: term}

Gets a list of structs.

Returns

  • {:ok, [resource], nil} - all resources matching query
  • {:ok, [resource], pagination} - page of resources matching query
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :timeout} - timeout occured while getting resources from backing store.
  • {:error, reason} - an error occurred with the backing store for reason that is backing store specific.
Link to this callback sandboxed?() View Source 
sandboxed?() :: boolean

Returns

  • true - if allow_sandbox_access/1 should be called before any of the query methods are called
  • false - otherwise
Link to this callback update(changeset, query_options) View Source 
update(changeset :: Ecto.Changeset.t, query_options) ::
  {:ok, struct} |
  {:error, :ownership} |
  {:error, :timeout} |
  {:error, Ecto.Changeset.t}

Applies updates in changeset

Returns

  • {:ok, struct} - the update succeeded and the returned struct contains the updates
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :timeout} - timeout occured while updating changeset with params in backing store.
  • {:error, Ecto.Changeset.t} - errors while updating struct with params. Ecto.Changeset.t errors contains errors.
Link to this callback update(resource, params, query_options) View Source 
update(resource :: Ecto.Schema.t, params, query_options) ::
  {:ok, struct} |
  {:error, Ecto.Changeset.t} |
  {:error, :bad_gateway} |
  {:error, :not_found} |
  {:error, :ownership} |
  {:error, :timeout}

Updates struct

Returns

  • {:ok, struct} - the update succeeded and the returned struct contains the updates
  • {:error, Ecto.Changeset.t} - errors while updating struct with params. Ecto.Changeset.t errors contains errors.
  • {:error, :bad_gateway} - error in backing store that cannot be represented as another type of error
  • {:error, :not_found} - the resource in the changeset was not found and so cannot be updated. This may mean that the resource was deleted with delete/1 after the get/2 or list/1 returned.
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :timeout} - timeout occured while updating resource with params in backing store.