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
#  }