# `Spark.Builder.Entity`
[🔗](https://github.com/ash-project/spark/blob/v2.7.0/lib/spark/builder/entity.ex#L5)

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

# `t`
*since 2.5.0* 

```elixir
@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()
}
```

# `build`
*since 2.5.0* 

```elixir
@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()

# `build!`
*since 2.5.0* 

```elixir
@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!()

# `new`
*since 2.5.0* 

```elixir
@spec new(atom(), module(), keyword()) :: t()
```

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 built
  - `opts` - 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]}

---

*Consult [api-reference.md](api-reference.md) for complete listing*