Estructura.Nested.Type.TimeSeries (estructura v1.11.0)

View Source

Estructura type scaffold for creating time series types, where the value is predictable changing with a time.

This module provides a way to create custom types containing the timestamp, “static” values, changing randomly, and the time series type.

The good example of such a type would be a currency exchange rate.

Usage

There are two ways to use this type scaffold:

1. Using the module directly

Unlike other scaffolded modules, this one is supposed to be created as a standalone module using Estructura.Nested.Type.TimeSeries.

2. Using the use macro

defmodule Rate do
  use Estructura.Nested.Type.TimeSeries,
    series: [
      value: {:oscillating, average: 1.0, amplitude: 0.3, outliers: 0.4}
    ],
    timestamp: :timestamp
end

Configuration Options

The scaffold accepts the following options:

  • :series - (required) List of valid values for the time series object
  • :timestamp - (optional) the type of timestamp field, allowed: :mototonic, :timestamp, default :timestamp
  • :coercer - (optional) Function to coerce input values
  • :encoder - (optional) Function to encode values for JSON

Example with Custom Coercion

defmodule Rate do
  use Estructura.Nested.Type.TimeSeries,
    series: [
      value: {:oscillating, average: 1.0, amplitude: 0.3, outliers: 0.4}
    ],
    timestamp: :timestamp,
    coercer: fn
      %Decimal{} = decimal -> {:ok, Decimal.to_float(decimal)}
      integer when is_integer(integer) -> {:ok, 1.0 * integer}
      float when is_float(float) -> {:ok, float}
      other -> {:error, "Cannot coerce #{inspect(other)} to TimeSeries object"}
    end
end

Example with Custom JSON Encoding

defmodule Rate do
  use Estructura.Nested.Type.TimeSeries,
    series: [
      value: {:oscillating, average: 1.0, amplitude: 0.3, outliers: 0.4}
    ],
    encoder: fn rate, opts -> Jason.Encode.map(Map.from_struct(rate), opts) end
end

Generated Functions

The scaffold implements the Estructura.Nested.Type behaviour and provides:

  • generate/1 - Generates random values from the enum for testing
  • coerce/1 - Attempts to convert input into a valid enum value
  • validate/1 - Ensures a value is part of the enum

Generation Options

The generate/1 function accepts:

  • :only - values to generate for (default: all)
  • :except - values to exclude from generation
Rate.generate() |> Enum.take(1)
#⇒ %Rate{
#    currency: :USD,
#    counter_currency: :EUR,
#    timestamp: ~U[2025-7-6T12:00:00Z],
#    value: 1.1
#  }

Summary

Functions

Implements the enum type directly in the current module.

Creates a new enum type module with the given name and options.

Functions

__using__(opts)

(macro)

Implements the enum type directly in the current module.

Options

See the module documentation for available options.

Examples

defmodule RateType do
  use Estructura.Nested.Type.TimeSeries,
    series: [value: {:oscillating, &RateType.rate_config/1}],
    timestamp: :timestamp

  def rate_config(_currencies) do
    [average: 1.2, amplitude: 0.3, outliers: 0.2]
  end
end

type_module_ast(name, opts)

Creates a new enum type module with the given name and options.

Options

See the module documentation for available options.