MapSchema

It´s a Simple, Agile, Map schema in Elixir with types check , with integer and float number autocasting of string to number, let define custom types with casting and validation and include json encoding using the popular Jason library.... furthermore it can build the documentation with doctest for validation your schemas and share easily with your agile team.

Next release Note: Now, I am working in improve it. You can use it but return here for check updates and documentation.

Installation

def deps do
  [
    {:map_schema, "~> 0.2.6"}
  ]
end

Usage

The map_schema will include in the module multiple methods with documentation even with some doctest examples... ;) then it´s simple create your schema, add ex_doc in mix, and use mix docs and your team will can see all methods that your module will have thanks the "witchcraft" of elixir macros, all ready to use it.

defmodule MapSchema.Examples.Person do
  @moduledoc """
  Example of Person Model Map using MapSchema
  """
  use MapSchema,
    schema: %{
        "name" => :string,
        "surname" => :string,
        "country" => :string,
        "lang" => :language_iso639,
        "age" => :integer,
        "contact" => %{
          "email" => :string,
          "phone" => :string,
          "others" => :any
        },
        "friends" => :list_people,
        "family" => :list_people
    },
    custom_types: [
      MapSchema.Examples.CustomTypeLang,
      MapSchema.Examples.CustomTypeRecursive.ListPeople
    ]
    
end

Basics functions

MethodDescription
newConstructor
schemaReturn the Schema
is_valid?(map)Is valid the map?

Gets and Puts functions

  test "Example get and put usage" do
    person = Person.new() # %{}
      |> Person.put_name("Leo") # %{"name" => "Leo"}
      |> Person.put_surname("Messi") # %{"name" => "Leo", "surname" => "Messi" }
      |> Person.put_country("Argentina") # %{"name" => "Leo", "surname" => "Messi", "country" => "Argentina" }
      |> Person.put_age(33) # %{"name" => "Leo", "surname" => "Messi", "country" => "Argentina", "age" => 33 }
      |> Person.put_lang("ES") # %{"name" => "Leo", "surname" => "Messi", "country" => "Argentina", "age" => 33 , "lang" => "es"} 
      
      # the lang field it´s custom type :language_iso639 make automatic # the downcase in strings before of validate. 
      # Review the example MapSchema.Examples.CustomTypeLang

    assert Person.get_name(person) == "Leo"
    assert Person.get_surname(person) == "Messi"
    assert Person.get_country(person) == "Argentina"
    assert Person.get_age(person) == 33
    assert Person.get_lang(person) == "es"
  end
GetsPuts
get_name(map)put_name(map,value)
get_surname(map)put_surname(map,value)
get_country(map)put_country(map,value)
get_age(map)put_age(map,value)
get_contact_email(map)put_contact_email(map,value)
get_contact_phone(map)put_contact_phone(map,value)
get_contact_others(map)put_contact_others(map,value)

General Put and Put_ifmatch

You can update many fields using a general put, every field will be cast and type check before of update. But if you try put a field that dont exist in the schema the method put will return a exception because you tried break the schema. Well there are a other option, you can use put_ifmatch that if a field dont exist in the schema it will omited.

  test "Example general put function" do
    person = Person.new() # %{}
    person = Person.put(person, %{
      "contact" => %{"email" => "example@mail.com" },
      "country" => "Spain"
    }) # %{"country" => "Spain","contact" => %{"email" => "example@mail.com"}}

    assert Person.get_contact_email(person) == "example@mail.com"
    assert Person.get_country(person) == "Spain"
  end
  test "Using put with exception and put_ifmatch without exception" do
    try do
      Person.new()
      |> Person.put(%{"name" => "ric", "not_exist_field"=> "something"})

      assert false
    catch
      e ->
        assert e == Exceptions.not_exist_field_in_schema("not_exist_field")
        person = Person.new()
          |> Person.put_ifmatch(%{"name" => "ric", "not_exist_field"=> "something"})

        assert Person.get_name(person) == "ric"
    end
  end

Mutation functions

  test "Example mutation of age" do
    person = Person.new() # %{}
    |> Person.put_age(29) # %{"age" => 29}
    |> Person.mut_age(&(&1 + 1)) # %{"age" => 30}

    assert Person.get_age(person) == 30
  end
MethodDescription
mut_name(map,fn_mut)Change the value of name using fn_mut
mut_surname(map,fn_mut)Change the value of surname using fn_mut
mut_country(map,fn_mut)Change the value of country using fn_mut
mut_age(map,fn_mut)Change the value of age using fn_mut
mut_contact_email(map,fn_mut)Change the value using fn_mut
mut_contact_phone(map,fn_mut)Change the value using fn_mut
mut_contact_others(map,fn_mut)Change the value using fn_mut

Json Encoding

  test "Example of json encoding" do
    person = Person.new()
    person = Person.put(person, %{
      "contact" => %{"email" => "hi@mail.com" },
      "age" => 45
    })

    json = Person.json_encode(person)
    json_expected ="{\"age\":45,\"contact\":{\"email\":\"hi@mail.com\"}}"
    assert json == json_expected

    person_json = Person.json_decode(json)

    assert Person.get_contact_email(person_json) == "hi@mail.com"
    assert Person.get_age(person_json) == 45
  end
MethodDescription
json_encode(map)Map to Json
json_encode(json)Json to Map (Check typing, and cast)
json_encode(mapa, json)Json to Existing Map (Checking typing, and cast)

Table of Types

Note: :string_to_integer and :string_to_float make implicit the cast of string to number then automatic and simple you will have your information in the right format and type following the schema define. ;)

TypeUse Guard
:integer:is_integer
:float:is_float
:string_to_integer:is_integer
:string_to_float:is_float
:string:is_bitstring
:bool:is_boolean
:boolean:is_boolean
:map:is_map
:list:is_list
:anyNONE
in othercaseNONE

Recursive Custom Type example of use

  test "Example using recursive list of people" do
    person_neymar = Person.new()
      |> Person.put_name("Neymar")

    person_messi = Person.new()
      |> Person.put_name("Leo")
      |> Person.put_surname("Messi")
      |> Person.put_friends([
        %{"name"=>"Suarez"},
        person_neymar
      ])
      |> Person.put_family([
        %{"name"=>"Antonella"}
      ])

    assert Person.get_name(person_messi) == "Leo"
    assert Person.get_surname(person_messi) == "Messi"
    assert Person.get_friends(person_messi) == [
      %{"name"=>"Suarez"},
      person_neymar
    ]
    assert Person.get_family(person_messi) == [
      %{"name"=>"Antonella"}
    ]
  end

Custom Type example

defmodule MapSchema.Examples.CustomTypeLang do
  @moduledoc """
  MapSchema.Examples.CustomTypeLang

    Imagine here a query to Database or any place where you have
    the list https://www.iso.org/iso-639-language-codes.html
    https://es.wikipedia.org/wiki/ISO_639-1
    only if the value exist it will be valid in other case
    the schema wont be valid. It´s simple. ;)

  """
  @behaviour MapSchema.CustomType

  @spec name :: atom
  def name, do: :language_iso639
  def nested?, do: false

  @doc """
  We are interesting in that every string will be lowcase.
  then it´s simple we add in the cast a function that make downcase.

  ## Examples

    iex> alias MapSchema.Examples.CustomTypeLang
    iex> CustomTypeLang.cast("ES")
    ...> |> CustomTypeLang.is_valid?()
    true

    iex> alias MapSchema.Examples.CustomTypeLang
    iex> CustomTypeLang.cast(nil)
    :error

  """
  @spec cast(any) :: any | :error
  def cast(value) when is_bitstring(value) do
    value
    |> String.downcase()
  end
  def cast(_), do: :error

  @doc """
   In this example our database it´s a simple list with
   ["zh", "en", "es"]

  ## Examples

      iex> alias MapSchema.Examples.CustomTypeLang
      iex> CustomTypeLang.is_valid?("zh")
      true
      iex> CustomTypeLang.is_valid?("en")
      true
      iex> CustomTypeLang.is_valid?("es")
      true

      iex> alias MapSchema.Examples.CustomTypeLang
      iex> CustomTypeLang.is_valid?("ES")
      false

      iex> alias MapSchema.Examples.CustomTypeLang
      iex> CustomTypeLang.is_valid?("Español")
      false

  """
  @spec is_valid?(any) :: boolean
  def is_valid?(value) do
    ## Imagine here a query to Database or any place where you have
    ## the list https://www.iso.org/iso-639-language-codes.html
    ## https://es.wikipedia.org/wiki/ISO_639-1
    ## only if the value exist it will be valid.
    value in ["zh", "en", "es"]
  end


  @doc """
  Stop... the magic continue. After define our cast and validation functions
  we can define a generador of doctest... Yes ¡¡ You are reading well.. TEST FREE¡¡

  If you define this function well... you can have a fast test of your new datatype ;)

  This method return a list of tuples [{value_test, expected_value},{.. , ..}...]
  map schema selected a random tuple for build the test ;) Please be careful, and
  test that every tuple it´s correct. Thanks.

  It´s important be careful because the values should be in string format for can be writed
  in the doctest please review that `mix docs` run without problems.


  """
  @spec doctest_values :: [{any, any}]
  def doctest_values do
    ["zh", "en", "es"]
    |> Enum.map(fn(text) -> {"\"#{text}\"", "\"#{text}\""} end)
  end

end

Features

  • Simple definition of data schema

    A simple map %{} and ;)

  • Implicit types check and casting

    Forgot the type checks and casting

  • Compatible with Json.

    Perfect, for APIs, webapps... so on.

  • Independent data of module

    A map would can be compatible with multiples schemas always that it follow each schema types.

  • Custom data types

    This custom data types let you define the rules of schema.

... and more now working ...

Only in Versions > 0.2.2

Atomize Schema (Dot Sintax)

defmodule MapSchema.Examples.Employee do
  use MapSchema,
    atomize: true,
    schema: %{
        :name => :string,
        :surname => :string,
        :contact => %{
          :email => :string,
        }
    },
    custom_types: []
end

In the next release you will can active atomize mode in your schemas, this can be problematic with json_encoding then we need say the schema that you want use it. It´s important this because let us use a doc sintax to access easy the information.

  test "New employee get with dot sintax" do
    emp = Employee.new()
      |> Employee.put_name("Ric")
      |> Employee.put_surname("H")
      |> Employee.put_contact_email("nested@email.com")

    assert emp.name == "Ric"
    assert Employee.get_name(emp) == "Ric"

    assert emp.surname == "H"
    assert Employee.get_surname(emp) == "H"

    assert emp.contact.email == "nested@email.com"
    assert Employee.get_contact_email(emp) == "nested@email.com"
  end

Schema like a CustomType

The schemas can be type for other schemas, only it´s require define the name of type with type_name and if you need a list of can define other type type_list_name. Of course this let a basic functionality but always you can build your custom type for your schema.

In the example you can see the modules of custom types "... Item.Type", "... Item.TypeList" where you need include the type or the typelist that you want use.

defmodule Item do
  @moduledoc false
  ## Example of recursive type
  use MapSchema,
    type_name: "<item>",
    type_list_name: "<list_items>",
    schema: %{
      "name" => :string,
      "list_items" => "<list_items>"
    },
    custom_types: %{
      "<item>" => MapSchema.DefineTypeTest.Item.Type,
      "<list_items>" => MapSchema.DefineTypeTest.Item.TypeList
    }
end