The Entity Reference Protocol (ERP) is a key component in the Noizu framework, used for handling references to entities in a uniform and flexible manner. The protocol defines a standard set of functions that must be implemented by any type that adheres to the protocol. This allows for a consistent way to interact with different types of entities (e.g., database records, structs, etc.) without having to know their specific implementation details.

purpose

Purpose

The purpose of the ERP is to provide a consistent interface for working with references to entities. This allows a table to reference various other entity types in a generic way. It also provides a straight forward mechanism for handling references without knowing in advance if they have been expanded or their exact type.

usage

Usage:

The ERP protocol is used whenever there is a need to reference an entity. This can be in the form of a ERP reference, a string reference, or the actual object. The protocol provides functions to convert between these different forms (i.e., ref, sref, entity, and record). This makes it easy to work with different types of references without having to know the specific details of the entity being referenced.

The protocol also includes functions that return either just the value (id, ref, sref, entity, record) or the same but wrapped in an {:ok, term} or {:error, details} tuple for matching (id_ok, ref_ok, sref_ok, entity_ok, entity_ok!).

This provides flexibility in handling both the normal and error cases.

why

Why

The ERP protocol is useful because it abstracts away the details of the entities being referenced. Making embedding, linking, urls, and other cases easy to implement in a generic way. Users can write code that doesn't care if it's being passed ref tuples, ref strings, actual entities, ecto records etc. but can simply call the protocol to cast to the desired format and handle as needed for querying, processing, returning, linking, etc.

protocol

Protocol

It defines the following functions:

• id/1: Retrieves the underlying id for a given ERP.
• id_ok/1: Similar to id/1 but returns the result in the form of {:ok, value} or {:error, error}.
• ref/1: Casts the given argument to a ERP reference.
• ref_ok/1: Similar to ref/1 but returns the result in the form of {:ok, value} or {:error, error}.
• sref/1: Casts the given argument to a ERP string reference.
• sref_ok/1: Similar to sref/1 but returns the result in the form of {:ok, value} or {:error, error}.
• record/1: Converts the given argument to a persistence object. Options may be passed to coordinate actions like expanding embedded references.
• record!/1: Similar to record/1 but with a transaction wrapper if required.
• entity/1: Converts the given argument to a scaffolding.struct object. Options may be passed to coordinate actions like expanding embedded references.
• entity_ok/1: Similar to entity/1 but returns the result in the form of {:ok, value} or {:error, error}.
• entity!/1: Similar to entity/1 but with a transaction wrapper if required.
• entity_ok!/1: Similar to entity_ok/1 but with a transaction wrapper if required.

The protocol is designed with the @fallback_to_any true directive, which means it will fall back to the Any implementation if no specific implementation for the provided data type is found.