Fact.Seam (Fact v0.2.0)

This module is the foundation for building flexible, versioned, and configurable components throughout the Fact system, providing consistency and reducing boilerplate.

Fact.Seam defines a standard interface and default implementation for modules that expose configurable components, providing:

• Identification: id/0, family/0, and version/0 to uniquely identify implementations.
• Options management: mechanisms to define default options, validate user-provided options, normalize options, and prepare them for internal use.
• Meta-programming helpers: a __using__/1 macro to easily inject behaviour and standard implementation into other modules.

Key Features

1. Behaviour Definition Modules that use Fact.Seam must implement:

   • id/0 – returns a {family, version} tuple
   • family/0 – the component family
   • version/0 – numeric version of the component
   • default_options/0 – default configuration options
   • init/1 – initializes the module with validated options
   • normalize_options/1 – normalizes and validates a given options map
   • option_specs/0 – specifications for each option including parsing and allowed values
   • prepare_options/1 – prepares the validated options for struct creation

2. Option Validation Validates options against a provided option_specs/0 map, applying parsing functions, checking allowed values, and returning detailed errors for unknown or invalid options.

3. Struct Initialization Automatically merges user-provided options with defaults, validates them, and constructs a struct for the module.

4. Meta-programming Convenience Injects default implementations for behaviours via the __using__/1 macro, allowing modules to focus on implementing only unique functionality.