Builder for constructing Spark.Dsl.Entity structs.
This module provides an options-based API for creating DSL entity definitions programmatically. Entities represent DSL constructors that produce struct instances.
Examples
alias Spark.Builder.Entity
entity = Entity.new(:attribute, MyApp.Attribute,
describe: "Defines an attribute on the resource",
args: [:name, :type],
schema: [
name: [type: :atom, required: true, doc: "The attribute name"],
type: [type: :atom, required: true, doc: "The attribute type"],
default: [type: :any, doc: "Default value"]
],
identifier: :name,
examples: ["attribute :email, :string"]
)
|> Entity.build!()Nested Entities
Entities can contain nested entities via the :entities option:
Entity.new(:field, MyApp.Field,
entities: [
children: [
Entity.new(:validation, MyApp.Validation,
args: [:type],
schema: [type: [type: :atom, required: true]]
)
|> Entity.build!()
]
]
)
|> Entity.build!()Accepted Options
:schema- The schema for entity options:args- Positional arguments:identifier- Field used for uniqueness validation:transform- Transform function as{module, function, args}:entities- Nested entities as keyword list[key: [entity, ...]]:singleton_entity_keys- Entity keys that should contain only a single value:recursive_as- Key allowing this entity to nest within itself:auto_set_fields- Fields automatically set on the target struct:describe- Description for documentation:examples- List of example strings:snippet- IDE autocomplete snippet:links- Documentation links:deprecations- Deprecation warnings for specific fields:docs- Additional documentation:imports- Modules to import in the entity's DSL scope:modules- Schema fields containing module references:no_depend_modules- Module fields that should not create dependencies:hide- Fields to hide from documentation
Summary
Functions
Builds the %Spark.Dsl.Entity{} struct.
Builds the %Spark.Dsl.Entity{} struct, raising on validation errors.
Creates a new entity builder with the given name, target struct module, and options.
Types
@type t() :: %Spark.Builder.Entity{ args: [atom() | {:optional, atom()} | {:optional, atom(), any()}], auto_set_fields: keyword(), deprecations: keyword(String.t()), describe: String.t(), docs: String.t(), entities: keyword([Spark.Dsl.Entity.t()]), examples: [String.t()], hide: [atom()], identifier: atom() | {:auto, :unique_integer} | nil, imports: [module()], links: keyword([String.t()]) | nil, modules: [atom()], name: atom() | nil, no_depend_modules: [atom()], recursive_as: atom() | nil, schema: Spark.Options.schema(), singleton_entity_keys: [atom()], snippet: String.t(), target: module() | nil, transform: Spark.Dsl.Entity.transform() }
Functions
@spec build(t()) :: {:ok, Spark.Dsl.Entity.t()} | {:error, String.t()}
Builds the %Spark.Dsl.Entity{} struct.
Returns {:ok, entity} on success or {:error, reason} on validation failure.
Validations
- Name and target are required
- All args must reference keys in the schema
- Identifier must reference a schema or auto_set_fields key (unless schema has
:*)
Examples
{:ok, entity} = Entity.new(:field, Field,
schema: [name: [type: :atom]]
)
|> Entity.build()@spec build!(t()) :: Spark.Dsl.Entity.t()
Builds the %Spark.Dsl.Entity{} struct, raising on validation errors.
Examples
entity = Entity.new(:field, Field,
schema: [name: [type: :atom]]
)
|> Entity.build!()Creates a new entity builder with the given name, target struct module, and options.
Parameters
name- The atom name for the DSL entity (e.g.,:attribute)target- The module of the struct that will be builtopts- Options to configure the entity (see module docs for accepted options)
Examples
iex> Entity.new(:attribute, MyApp.Attribute)
%Spark.Builder.Entity{name: :attribute, target: MyApp.Attribute}
iex> Entity.new(:attribute, MyApp.Attribute,
...> schema: [name: [type: :atom]],
...> args: [:name]
...> )
%Spark.Builder.Entity{name: :attribute, target: MyApp.Attribute, schema: [name: [type: :atom]], args: [:name]}