<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshVersioned.Resource

Configures a resource for versioning. The source table gets a stable resource
identifier, a version number, and a flag marking a row as the latest version, and
mutations append new rows instead of updating in place.

Versioned resources must already have the following fields declared in `attributes`.

- A surrogate primary key (`uuid_v7_primary_key`, `integer_primary_key`, or one already
  on a ported table). Composite keys are not supported.
- Create and update timestamps (usually `:inserted_at` and `:updated_at`) with any
  non-null datetime-family attribute.


## versioning
Configures SCD (type 2) version tracking on this resource.

### Nested DSLs
 * [identity](#versioning-identity)
 * [version](#versioning-version)
 * [latest](#versioning-latest)
 * [archive](#versioning-archive)
 * [reference_actor](#versioning-reference_actor)
 * [belongs_to_actor](#versioning-belongs_to_actor)


### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`create_timestamp_attribute`](#versioning-create_timestamp_attribute){: #versioning-create_timestamp_attribute } | `atom` | `:inserted_at` | The name of the timestamp attribute used when inserting a new version. This reflects when this version became active. The attribute must already be defined in `attributes`. |
| [`update_timestamp_attribute`](#versioning-update_timestamp_attribute){: #versioning-update_timestamp_attribute } | `atom` | `:updated_at` | The name of the timestamp attribute updated when a version is marked stale. This reflects when this version became inactive. The attribute must already be defined in `attributes`. |
| [`exclude_update_actions`](#versioning-exclude_update_actions){: #versioning-exclude_update_actions } | `list(atom)` | `[]` | Update actions intentionally left as ordinary in-place updates instead of appending a new version. Every other update action on the resource is wired to append automatically. WARNING: This should _only_ be used in exceptional circumstances, because it breaks the core promise of SCD (type 2) versioning: inactive versions don't change. |
| [`exclude_read_actions`](#versioning-exclude_read_actions){: #versioning-exclude_read_actions } | `list(atom)` | `[]` | Read actions that should skip the default latest (and archived) scoping applied to every other read action. This could include hand-declared audit or admin-facing actions that need to see stale and archived versions. |
| [`history_action`](#versioning-history_action){: #versioning-history_action } | `atom` | `:version_history` | The name of the generated read action that returns every version, ignoring the default latest/archived scoping. |
| [`source_prefix`](#versioning-source_prefix){: #versioning-source_prefix } | `String.t` |  | If specified, this prefix is applied to the underlying `source` of the generated AshVersioned fields. Fields adopting defined fields (`define_attribute? false`) or that declare `source` ignore this setting. ```elixir versioning do   archive()   source_prefix "vo_" end ``` This is equivalent to: ```elixir versioning do   archive :archived, source: :vo_archived   identity :resource_id, source: :vo_resource_id   latest :latest_version, source: :vo_latest_version   version :version_number, source: :vo_version_number end ``` The prefix is applied in front of _any_ name given, so `identity :mo_id` would become `identity :mo_id, source: :vo_mo_id`. |


### versioning.identity
```elixir
identity name \\ :resource_id
```


Configures the identity held by every version of the same versioned resource;
a "logical" primary key.

If omitted, this is equivalent to `identity :resource_id`.


### Examples
```
identity :resource_id
```

```
identity do
  origin :accepted
end

```

```
identity :resource_id, origin: :accepted
```

```
identity :mo_id do
  define_attribute? false
end

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#versioning-identity-name){: #versioning-identity-name } | `atom` | `:resource_id` | The name of the identity attribute. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`define_attribute?`](#versioning-identity-define_attribute?){: #versioning-identity-define_attribute? } | `boolean` | `true` | If set to `false`, the identity attribute is not created and one must be manually added to `attributes`, invalidating many other options. |
| [`origin`](#versioning-identity-origin){: #versioning-identity-origin } | `:generated \| :accepted` | `:generated` | If not set or set as `:generated`, the value of the identity is generated on resource creation. If set to `:accepted`, the identity is an accepted parameter on every create action. |
| [`type`](#versioning-identity-type){: #versioning-identity-type } | `any` | `:uuid_v7` | The type of the generated attribute. See `Ash.Type` for more details. Types other than `:uuid` and `:uuid_v7` require that `origin` be set to `:accepted`. |
| [`source`](#versioning-identity-source){: #versioning-identity-source } | `atom` |  | The name of the field on the underlying data layer. |


### Introspection

Target: `AshVersioned.Resource.Identity`

### versioning.version
```elixir
version name \\ :version_number
```


Configures the monotonically increasing version number, starting at 0.

If omitted, this is equivalent to `version :version_number`.


### Examples
```
version :version_number
```

```
version :mo_version do
  define_attribute? false
end

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#versioning-version-name){: #versioning-version-name } | `atom` | `:version_number` | The name of the version attribute. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`define_attribute?`](#versioning-version-define_attribute?){: #versioning-version-define_attribute? } | `boolean` | `true` | If set to `false`, the version attribute is not created and one must be manually added to `attributes`, invalidating many other options. |
| [`source`](#versioning-version-source){: #versioning-version-source } | `atom` |  | The name of the field on the underlying data layer. |


### Introspection

Target: `AshVersioned.Resource.Version`

### versioning.latest
```elixir
latest name \\ :latest_version
```


Configures the boolean flag marking the current version for this resource.

If omitted, this is equivalent to `latest :latest_version`.


### Examples
```
latest :latest_version
```

```
latest :mo_is_latest do
  define_attribute? false
end

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#versioning-latest-name){: #versioning-latest-name } | `atom` | `:latest_version` | The name of the latest attribute. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`define_attribute?`](#versioning-latest-define_attribute?){: #versioning-latest-define_attribute? } | `boolean` | `true` | If set to `false`, the latest attribute is not created and one must be manually added to `attributes`, invalidating many other options. |
| [`source`](#versioning-latest-source){: #versioning-latest-source } | `atom` |  | The name of the field on the underlying data layer. |


### Introspection

Target: `AshVersioned.Resource.Latest`

### versioning.archive
```elixir
archive attribute \\ :archived
```


Declares this resource archivable, which makes every destroy action a `soft?: true`
destroy action.

If not set, defining destroy actions on the resource is a compile error.


### Examples
```
archive :archived
```

```
archive do
  action :discard
end

```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`attribute`](#versioning-archive-attribute){: #versioning-archive-attribute } | `atom` | `:archived` | The name of the boolean attribute marking a version as archived. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`define_attribute?`](#versioning-archive-define_attribute?){: #versioning-archive-define_attribute? } | `boolean` | `true` | If set to `false`, the archived attribute is not created and one must be manually added to `attributes`, invalidating many other options. |
| [`action`](#versioning-archive-action){: #versioning-archive-action } | `atom \| false` | `:archive` | The name of a generated default destroy action, created using this name unless a destroy action is already defined (regardless of its name). Set to `false` to skip generating it unconditionally. |
| [`read_action`](#versioning-archive-read_action){: #versioning-archive-read_action } | `atom \| false` | `:get_with_archived` | The name of a generated `get_by` read action that returns the latest version of a resource by its identity attribute, whether or not it's archived. This action is scoped to return the latest version of a resource. Skipped if an action with this name is already defined. Set to `false` to skip generating it unconditionally. |
| [`unarchive`](#versioning-archive-unarchive){: #versioning-archive-unarchive } | `atom \| false` | `:unarchive` | The name of a generated update action that sets the archived to `false`, accepting no input. Skipped if an action with this name is already defined. Set to `false` to skip generating it unconditionally. |
| [`exclude_read_actions`](#versioning-archive-exclude_read_actions){: #versioning-archive-exclude_read_actions } | `list(atom)` | `[]` | Additional read actions (beyond `read_action`) that should skip the filtering archived resources while still respecting the latest version filtering. An action name only needs to appear here or in the top-level `exclude_read_actions`, not both. |
| [`source`](#versioning-archive-source){: #versioning-archive-source } | `atom` |  | The name of the field on the underlying data layer. |


### Introspection

Target: `AshVersioned.Resource.Archive`

### versioning.reference_actor
```elixir
reference_actor name
```


Creates a `:string` attribute for storing the actor responsible for resource version
creation.

`reference_actor` can be used when the actor field holds heterogeneous ID spaces
(admin, customer, or sentinel values like `"system"`) that may not resolve
to Ash resources. It works best with prefixed object ID strings (`admin_QweRTy`,
`customer_Dv0rAk`, etc.).

For more than one possible Ash resource actor type, use `belongs_to_actor` instead,
which discriminates by the actor type.


### Examples
```
reference_actor :created_by
```

```
reference_actor :created_by, transform: &MyApp.actor_reference/1
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#versioning-reference_actor-name){: #versioning-reference_actor-name .spark-required} | `atom` |  | The name of the attribute to use for the actor. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`transform`](#versioning-reference_actor-transform){: #versioning-reference_actor-transform } | `(any -> any) \| mfa` | `&AshVersioned.ReferenceActorValue.value_for/1` | A function or `{module, function, args}` to transform the actor into a suitable string reference. The default is `AshVersioned.ReferenceActorValue.value_for/1`. Use a different function when support for composite primary keys, prefixed keys, or some other requirement arises. |
| [`allow_nil?`](#versioning-reference_actor-allow_nil?){: #versioning-reference_actor-allow_nil? } | `boolean` | `true` | Whether this attribute can be nil. |
| [`public?`](#versioning-reference_actor-public?){: #versioning-reference_actor-public? } | `boolean` | `false` | Whether this attribute should be shown over public interfaces. |


### Introspection

Target: `AshVersioned.Resource.ReferenceActor`

### versioning.belongs_to_actor
```elixir
belongs_to_actor name, destination
```


Creates a `belongs_to` relationship to the actor resource. When creating a new
version, associates the action's actor with the matching resource type. For
polymorphic or variant types, declare a `belongs_to_actor` for each type.

If your actor is not a resource, consider using `reference_actor` instead.


### Examples
```
belongs_to_actor :edited_by, MyApp.Users.Author
```

```
belongs_to_actor :reviewed_by, MyApp.Users.Author, domain: MyApp.Users
```


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#versioning-belongs_to_actor-name){: #versioning-belongs_to_actor-name .spark-required} | `atom` |  | The name of the relationship to use for the actor. |
| [`destination`](#versioning-belongs_to_actor-destination){: #versioning-belongs_to_actor-destination .spark-required} | `module` |  | The resource of the actor (e.g. MyApp.Users.User) |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`allow_nil?`](#versioning-belongs_to_actor-allow_nil?){: #versioning-belongs_to_actor-allow_nil? } | `boolean` | `true` | Whether this relationship must always be present. The generated attribute will not allow nil values. |
| [`domain`](#versioning-belongs_to_actor-domain){: #versioning-belongs_to_actor-domain } | `atom` |  | The Domain module to use when working with the related entity. |
| [`attribute_type`](#versioning-belongs_to_actor-attribute_type){: #versioning-belongs_to_actor-attribute_type } | `any` | `:uuid` | The type of the generated attribute. See `Ash.Type` for more. |
| [`public?`](#versioning-belongs_to_actor-public?){: #versioning-belongs_to_actor-public? } | `boolean` | `false` | Whether this relationship should be included in public interfaces |
| [`define_attribute?`](#versioning-belongs_to_actor-define_attribute?){: #versioning-belongs_to_actor-define_attribute? } | `boolean` | `true` | If set to `false`, an attribute is not created on the resource for this relationship, and one must be manually added in `attributes`, invalidating many other options. |
| [`on_delete`](#versioning-belongs_to_actor-on_delete){: #versioning-belongs_to_actor-on_delete } | `:delete \| :nilify \| :nothing \| :restrict \| {:nilify, atom \| list(atom)}` | `:nothing` | The action to take on this row when the actor is deleted. Can also be `{:nilify, columns}` to nilify specific columns (Postgres 15+ only). Only relevant for resources using a SQL data layer. Has no impact when `destination` is an `AshVersioned.Resource`. |


### Introspection

Target: `AshVersioned.Resource.BelongsToActor`


<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>