Aurora.Uix.Integration.Ash.Crud (Aurora UIX v0.1.4-rc.1)

Copy Markdown

Ash Framework implementation of CRUD operations.

Provides CRUD operations for Ash resources using the Ash Framework API. Supports both paginated and non-paginated listing, along with standard create, read, update, delete operations.

Key Features

  • Automatic action discovery and execution for Ash resources
  • Support for paginated and non-paginated queries
  • Query parsing with filters, sorting, and preloading
  • Primary action detection with fallback to first available action
  • AshPhoenix form integration for changesets

Key Constraints

  • Requires valid Ash resource module with defined actions
  • Pagination requires Ash action configured with pagination option
  • Preloading handled differently: via Ash.Query.load for queries, Ecto repo for new structs

Summary

Functions

change(crud_spec, entity, form_name, attrs)

Creates an AshPhoenix form for updating an entity.

create(crud_spec, params)

Creates a new resource in the database.

default_new_function(entity, opts)

Default new function for initializing Ash resource structs.

delete(crud_spec, entity)

Deletes a resource from the database.

get(crud_spec, id, opts)

Retrieves a single resource by ID.

list(definition, opts \\ [])

Lists resources from an Ash action with optional query parameters.

new(crud_spec, attrs, opts)

Creates a new Ash resource struct with optional preloading.

to_page(crud_spec, pagination, page)

Loads a specific page of results for paginated data.

update(crud_spec, entity, params)

Updates an existing resource in the database.

Functions

change(crud_spec, entity, form_name, attrs)

@spec change(
  Aurora.Uix.Integration.Ash.CrudSpec.t(),
  struct(),
  atom() | binary(),
  map()
) ::
  AshPhoenix.Form.t()

Creates an AshPhoenix form for updating an entity.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec containing action configuration.
  • entity (struct()) - The Ash resource struct to update.
  • attrs (map()) - Attributes to apply to the form.

Returns

AshPhoenix.Form.t() - The form structure for the update operation.

Examples

iex> crud_spec = %CrudSpec{action: %{name: :update}}
iex> change(crud_spec, %MyApp.User{}, %{name: "John"})
%AshPhoenix.Form{...}

create(crud_spec, params)

@spec create(Aurora.Uix.Integration.Ash.CrudSpec.t(), map()) :: tuple()

Creates a new resource in the database.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec containing resource and action configuration.
  • params (map()) - Parameters for the new resource.

Returns

tuple() - Result tuple, typically {:ok, struct()} or {:error, struct()}.

Examples

iex> crud_spec = %CrudSpec{resource: MyApp.User, action: %{name: :create}}
iex> create(crud_spec, %{name: "Alice", email: "alice@example.com"})
{:ok, %MyApp.User{name: "Alice", email: "alice@example.com"}}

default_new_function(entity, opts)

@spec default_new_function(struct(), keyword()) :: struct()

Default new function for initializing Ash resource structs.

Returns the entity struct as-is without modifications. This function serves as the default implementation for the :new_function operation when no custom function is provided via :ash_new_function option.

Parameters

  • entity (struct()) - The Ash resource struct to initialize.
  • opts (keyword()) - Options (currently unused).

Returns

struct() - The unmodified entity struct.

Examples

iex> post = %Post{status: :draft}
iex> default_new_function(post, [])
%Post{status: :draft}

delete(crud_spec, entity)

@spec delete(
  Aurora.Uix.Integration.Ash.CrudSpec.t(),
  struct()
) :: tuple()

Deletes a resource from the database.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec containing action configuration.
  • entity (struct()) - The resource to delete.

Returns

tuple() - Result tuple, typically {:ok, struct()} or {:error, struct()}.

Examples

iex> crud_spec = %CrudSpec{action: %{name: :destroy}}
iex> delete(crud_spec, %MyApp.User{id: 1})
{:ok, %MyApp.User{id: 1}}

get(crud_spec, id, opts)

@spec get(Aurora.Uix.Integration.Ash.CrudSpec.t(), term(), keyword()) ::
  struct() | nil

Retrieves a single resource by ID.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec containing resource and action configuration.
  • id (term()) - The resource identifier.
  • opts (keyword()) - Query options:
    • :preload (term()) - Associations to load.

Returns

struct() | nil - The matching resource or nil if not found or error occurs.

Examples

iex> crud_spec = %CrudSpec{resource: MyApp.User, action: %{name: :read}}
iex> get(crud_spec, "123", preload: [:posts])
%MyApp.User{id: "123", ...}

iex> get(crud_spec, "missing-id", [])
nil

list(definition, opts \\ [])

@spec list(
  Aurora.Uix.Integration.Ash.CrudSpec.t(),
  keyword()
) :: Aurora.Ctx.Pagination.t()

Lists resources from an Ash action with optional query parameters.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec containing resource and action configuration.
  • opts (keyword()) - Query options:
    • :where (list()) - Filter clauses.
    • :order_by (term()) - Sort specification.
    • :preload (term()) - Associations to load.
    • :paginate (Pagination.t()) - Pagination configuration (for paginated action).

Returns

Pagination.t() - %Pagination{} structure containing query results and metadata.

Examples

iex> crud_spec = %CrudSpec{resource: MyApp.User, action: %{name: :read, pagination: false}}
iex> list(crud_spec, where: [{:status, :eq, "active"}])
%Pagination{entries: [...], pages_count: 1, per_page: :infinity}

iex> crud_spec = %CrudSpec{resource: MyApp.Post, action: %{name: :read, pagination: true},
...>   auix_action_name: :list_function_paginated}
iex> list(crud_spec, paginate: %Pagination{page: 1, per_page: 20})
%Pagination{entries: [...], page: 1, pages_count: 5, per_page: 20}

new(crud_spec, attrs, opts)

@spec new(Aurora.Uix.Integration.Ash.CrudSpec.t(), map(), keyword()) :: struct()

Creates a new Ash resource struct with optional preloading.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec containing resource configuration.
  • attrs (map()) - Initial attributes for the new resource.
  • opts (keyword()) - Options:
    • :preload (list()) - Associations to preload via Ecto repository.

Returns

struct() - A new resource struct with the provided attributes and preloaded associations.

Examples

iex> crud_spec = %CrudSpec{resource: MyApp.User}
iex> new(crud_spec, %{name: "Jane"}, preload: [:profile])
%MyApp.User{name: "Jane", profile: %MyApp.Profile{}}

iex> new(crud_spec, %{title: "Hello"}, [])
%MyApp.Post{title: "Hello"}

to_page(crud_spec, pagination, page)

@spec to_page(
  Aurora.Uix.Integration.Ash.CrudSpec.t(),
  Aurora.Ctx.Pagination.t(),
  integer()
) ::
  Aurora.Ctx.Pagination.t()

Loads a specific page of results for paginated data.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec (currently unused for page bounds checking).
  • pagination (Pagination.t()) - The current pagination structure.
  • page (integer()) - The page number to load (must be >= 1 and <= pages_count).

Returns

Pagination.t() - Updated %Pagination{} structure with the requested page data, or unchanged pagination if page is out of bounds.

Examples

iex> crud_spec = %CrudSpec{resource: MyApp.User, action: %{name: :read}}
iex> to_page(crud_spec, %Pagination{page: 1, pages_count: 5, per_page: 20}, 3)
%Pagination{entries: [...], page: 3, pages_count: 5, per_page: 20}

iex> to_page(crud_spec, %Pagination{page: 1, pages_count: 5}, 10)
%Pagination{page: 1, pages_count: 5}

update(crud_spec, entity, params)

@spec update(Aurora.Uix.Integration.Ash.CrudSpec.t(), struct(), map()) :: tuple()

Updates an existing resource in the database.

Parameters

  • crud_spec (CrudSpec.t()) - The CrudSpec containing action configuration.
  • entity (struct()) - The resource to update.
  • params (map()) - Parameters to update.

Returns

tuple() - Result tuple, typically {:ok, struct()} or {:error, struct()}.

Examples

iex> crud_spec = %CrudSpec{action: %{name: :update}}
iex> update(crud_spec, %MyApp.User{id: 1}, %{name: "Bob"})
{:ok, %MyApp.User{id: 1, name: "Bob"}}