Aurora.Ctx.Core (Aurora.Ctx v0.1.4)

View Source

Core implementation of common database operations using Ecto.

Provides functions for:

  • CRUD operations (create, read, update, delete)
  • Pagination (list_paginated, navigation)
  • Query operations (count, list) with filtering, sorting, and preloading
  • Record management (change, new)
  • Query building and clause exclusion

Summary

Functions

Creates a changeset for the given entity.

Creates a changeset for the given entity using a specific changeset function.

Counts total records matching query conditions.

Creates a new record with optional custom changeset function.

Creates a new record, raising on errors.

Deletes the given entity.

Deletes the given entity, raising on errors.

Excludes query clauses from an Ecto query.

Gets a record by id, raising if not found.

Gets a record by filtering clauses.

Gets a record by filtering clauses.

Lists all records for a schema with optional filtering and sorting.

Lists records with pagination support.

Initializes a new schema struct with optional attributes or options.

Initializes a new struct with optional preloads.

Moves to next page in paginated results.

Moves to previous page in paginated results.

Changes to a specific page in paginated results.

Updates an entity with given attributes.

Functions

change(entity_or_changeset, attrs)

@spec change(Ecto.Schema.t() | Ecto.Changeset.t(), map() | nil) :: Ecto.Changeset.t()

Creates a changeset for the given entity.

Parameters:

  • entity_or_changeset (Ecto.Schema.t() | Ecto.Changeset.t()) - Entity for changeset

  • attrs (map) - Changeset attributes

Returns Ecto.Changeset.

change(entity_or_changeset, changeset_function \\ :changeset, attrs \\ %{})

@spec change(Ecto.Schema.t() | Ecto.Changeset.t(), atom() | function(), map() | nil) ::
  Ecto.Changeset.t()

Creates a changeset for the given entity using a specific changeset function.

Parameters

  • entity_or_changeset (Ecto.Schema.t() | Ecto.Changeset.t()) - Existing record or changeset

  • changeset_function (atom() | function()) - Custom changeset function. can be an atom representing the function name, or can be a reference to a function. If it is an atom, the function is assumed to be located in the schema.

  • attrs (map()) - Changeset attributes

Returns

  • Ecto.Changeset.t()

Examples

alias MyApp.Product
product = %Product{name: "Widget"}
Core.change(product, %{name: "New Widget"})
#=> #Ecto.Changeset<changes: %{name: "New Widget"}>

Core.change(product, :custom_changeset, %{status: "active"})
#=> #Ecto.Changeset<changes: %{status: "active"}>

count(repo_module, schema_module, opts \\ [])

@spec count(module(), module(), keyword()) :: non_neg_integer()

Counts total records matching query conditions.

Parameters:

  • repo_module (module) - Ecto.Repo to use
  • schema_module (module) - Schema to query
  • opts (keyword) - Optional query filtering options

Returns total count of matching records.

create(repo_module, schema_module_or_changeset, attrs)

@spec create(module(), module() | Ecto.Changeset.t(), map() | nil) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Creates a new record.

Parameters:

  • repo_module (module()) - Ecto.Repo to use
  • schema_module (module() | ) - Schema to create

  • attrs (map()) - Attributes for the new record

Returns {:ok, schema} on success, {:error, changeset} on failure.

create(repo_module, schema_module_or_changeset, changeset_function \\ :changeset, attrs \\ %{})

@spec create(
  module(),
  module() | Ecto.Changeset.t(),
  atom() | function(),
  map() | nil
) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Creates a new record with optional custom changeset function.

Parameters

  • repo_module (module()) - Ecto.Repo module to use
  • schema_module (module() | Ecto.Changeset.t()) - Schema module for the record

  • changeset_function (atom()) - Custom changeset function to use can be an atom representing the function name, or can be a reference to a function. If it is an atom, the function is assumed to be located in the schema.
  • attrs (map()) - Attributes for the new record

Returns

  • {:ok, Ecto.Schema.t()} - On success
  • {:error, Ecto.Changeset.t()} - On validation failure

Examples

alias MyApp.{Repo, Product}
Core.create(Repo, Product, %{name: "Widget"})
#=> {:ok, %Product{name: "Widget"}}

Core.create(Repo, Product, :custom_changeset, %{
  name: "Widget",
  status: "active"
})
#=> {:ok, %Product{name: "Widget", status: "active"}}

create!(repo_module, schema_module_or_changeset, attrs)

@spec create!(module(), module() | Ecto.Changeset.t(), map() | nil) :: Ecto.Schema.t()

Creates a new record, raising on errors.

Parameters:

  • repo_module (module()) - Ecto.Repo to use
  • schema_module_or_changeset (module() | Ecto.Changeset.t()) - Schema to create

  • attrs (map()) - Attributes for the new record

Returns created schema or raises on error.

create!(repo_module, schema_module_or_changeset, changeset_function \\ :changeset, attrs \\ %{})

@spec create!(
  module(),
  module() | Ecto.Changeset.t(),
  atom() | function(),
  map() | nil
) ::
  Ecto.Schema.t()

Creates a new record, raising on errors.

Parameters:

  • repo_module (module) - Ecto.Repo to use
  • schema_module_or_changeset (module | Ecto.Changeset) - Schema to create

  • changeset_function (atom | function()) - Changeset function to use

  • attrs (map) - Attributes for the new record

Returns created schema or raises on error.

delete(repo_module, entity)

@spec delete(module(), Ecto.Schema.t()) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Deletes the given entity.

Parameters:

  • repo_module (module): The Ecto.Repo module to use
  • entity (Ecto.Schema.t()): The entity to delete

Returns: {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

delete!(repo_module, entity)

@spec delete!(module(), Ecto.Schema.t()) :: Ecto.Schema.t()

Deletes the given entity, raising on errors.

Parameters:

  • repo_module (module): The Ecto.Repo module to use
  • entity (Ecto.Schema.t()): The entity to delete

Returns: Ecto.Schema.t() Raises: Ecto.StaleEntryError

exclude_clauses(query, clauses)

@spec exclude_clauses(Ecto.Query.t(), atom() | [atom()]) :: Ecto.Query.t()

Excludes query clauses from an Ecto query.

Parameters:

  • query (Ecto.Query.t()) - Query to modify
  • clauses (atom | [atom]) - Clause(s) to exclude. Available clauses:

    • :where - WHERE conditions
    • :select - SELECT clauses
    • :order_by - ORDER BY clauses
    • :group_by - GROUP BY clauses
    • :having - HAVING conditions
    • :limit - LIMIT clause
    • :offset - OFFSET clause
    • :preload - Preload associations
    • :lock - Lock clauses

Returns modified query.

Examples

query = from(p in Product)
exclude_clauses(query, :where)
exclude_clauses(query, [:select, :order_by])

get(repo_module, schema_module, id, opts \\ [])

@spec get(module(), module(), term(), keyword()) :: Ecto.Schema.t() | nil

Gets a record by id.

Parameters:

  • repo_module (module) - Ecto.Repo to use
  • schema_module (module) - Schema to query
  • id (term) - Primary key to look up
  • opts (keyword) - Optional query parameters

Returns found schema or nil if not found.

get!(repo_module, schema_module, id, opts \\ [])

@spec get!(module(), module(), term(), keyword()) :: Ecto.Schema.t()

Gets a record by id, raising if not found.

Parameters:

  • repo_module (module) - Ecto.Repo to use
  • schema_module (module) - Schema to query
  • id (term) - Primary key to look up
  • opts (keyword) - Optional query parameters

Returns found schema or raises Ecto.NoResultsError.

get_by(repo_module, schema_module, clauses, opts \\ [])

@spec get_by(module(), module(), keyword(), keyword()) :: Ecto.Schema.t()

Gets a record by filtering clauses.

Parameters:

  • repo_module (module) - Ecto.Repo to use
  • schema_module (module) - Schema to query
  • clauses (keyword) - Clauses for getting the element
  • opts (keyword) - Optional query parameters

Returns found schema or nil if not found. If more than one is found raises Ecto.MultipleResultsError

get_by!(repo_module, schema_module, clauses, opts \\ [])

@spec get_by!(module(), module(), keyword(), keyword()) :: Ecto.Schema.t()

Gets a record by filtering clauses.

Parameters:

  • repo_module (module) - Ecto.Repo to use
  • schema_module (module) - Schema to query
  • clauses (keyword) - Clauses for getting the element
  • opts (keyword) - Optional query parameters

Returns found schema. Raises Ecto.NoResultsError or Ecto.MultipleResultsError.

list(repo_module, schema_module, opts \\ [])

@spec list(module(), module(), keyword()) :: list()

Lists all records for a schema with optional filtering and sorting.

Parameters

  • repo_module (module()) - Ecto.Repo module to use
  • schema_module (module()) - Schema module to query
  • opts (keyword()) - Optional query parameters (see Aurora.Ctx.QueryBuilder for available options)

Returns

  • list(Ecto.Schema.t())

Examples

alias MyApp.{Repo, Product}
Core.list(Repo, Product)
#=> [%Product{}, ...]

Core.list(Repo, Product,
  where: [status: :active],
  order_by: [desc: :inserted_at],
  preload: [:category]
)
#=> [%Product{category: %Category{}}, ...]

list_paginated(repo_module, schema_module, opts \\ [])

@spec list_paginated(module(), module(), keyword()) :: Aurora.Ctx.Pagination.t()

Lists records with pagination support.

Parameters

  • repo_module (module()) - Ecto.Repo module to use
  • schema_module (module()) - Schema module to query
  • opts (keyword()) - See Aurora.Ctx.QueryBuilder for available query options.

Configuration

Default pagination settings can be configured in your config.exs:

config :aurora_ctx, :pagination,
  page: 1,
  per_page: 40

If not configured, defaults to page: 1, per_page: 40. Page navigation is safe - attempting to navigate beyond valid pages will return the current page unchanged.

Returns

Examples

alias MyApp.{Repo, Product}
Core.list_paginated(Repo, Product,
  paginate: %{page: 1, per_page: 20},
  where: [category_id: 1],
  order_by: [desc: :inserted_at]
)
#=> %Aurora.Ctx.Pagination{
#=>   entries: [%Product{}],
#=>   page: 1,
#=>   per_page: 20,
#=>   entries_count: 50,
#=>   pages_count: 3
#=> }

new(repo_module, schema_module, attrs)

@spec new(module(), module(), map() | keyword()) :: Ecto.Schema.t()

Initializes a new schema struct with optional attributes or options.

Parameters

  • repo_module (module) - Ecto.Repo to use
  • schema_module (module) - Schema to initialize
  • attrs_or_opts - One of:
    • map: Initial attributes (will use empty options)
    • keyword list: Options (will use empty attributes)

Returns initialized schema struct.

new(repo_module, schema_module, attrs \\ %{}, opts \\ [])

@spec new(module(), module(), map(), keyword()) :: Ecto.Schema.t()

Initializes a new struct with optional preloads.

Parameters:

  • repo_module (module): The Ecto.Repo module to use
  • schema_module (module): The Ecto.Schema module to initialize
  • opts (keyword): Optional preload parameters

Returns: Ecto.Schema.t()

next_page(paginate)

Moves to next page in paginated results.

Parameters:

  • paginate (Aurora.Ctx.Pagination.t()) - Current pagination state containing entries, page number, and other metadata. If already on the last page, returns the current page unchanged.

Example:

paginate = list_products_paginated(per_page: 20)
next_page = next_page(paginate) # Moves to page 2

previous_page(paginate)

@spec previous_page(Aurora.Ctx.Pagination.t() | map()) :: Aurora.Ctx.Pagination.t()

Moves to previous page in paginated results.

Parameters:

  • paginate (Aurora.Ctx.Pagination.t()) - Current pagination state containing entries, page number, and other metadata. If already on page 1, returns the first page unchanged.

Example:

paginate = list_products_paginated(page: 2, per_page: 20)
prev_page = previous_page(paginate) # Moves back to page 1

to_page(paginate, page)

Changes to a specific page in paginated results.

Parameters:

  • paginate (Aurora.Ctx.Pagination.t()) - Current pagination state
  • page (integer) - Target page number. If the requested page is out of range (< 1 or > pages_count), returns the current page unchanged.

Example:

paginate = list_products_paginated(per_page: 20)
page5 = to_page(paginate, 5)  # Jumps directly to page 5

# Out of range page results in no change
page5 = to_page(paginate, 999) # Returns current page if 999 > pages_count

Returns:

  • Aurora.Ctx.Pagination struct with entries for the target page, or unchanged if the target page is out of range.

update(repo_module, entity_or_changeset, attrs)

@spec update(module(), Ecto.Schema.t() | Ecto.Changeset.t(), map() | nil) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Updates an entity with given attributes.

Parameters:

  • repo_module (module) - Ecto.Repo to use
  • entity_or_changeset (Ecto.Schema.t() | Ecto.Changeset.t()) - Entity to update or changeset to apply

  • attrs (map) - Update attributes

Returns {:ok, schema} on success, {:error, changeset} on failure.

update(repo_module, entity_or_changeset, changeset_function \\ :changeset, attrs \\ %{})

@spec update(
  module(),
  Ecto.Schema.t() | Ecto.Changeset.t(),
  atom() | function(),
  map() | nil
) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Updates an entity using a specific changeset function.

Parameters

  • repo_module (module()) - Ecto.Repo module to use
  • entity_or_changeset (Ecto.Schema.t() | Ecto.Changeset.t()) - Existing record to update

  • changeset_function (atom() | function()) - Custom changeset function. can be an atom representing the function name, or can be a reference to a function. If it is an atom, the function is assumed to be located in the schema.

  • attrs (map()) - Update attributes

Returns

  • {:ok, Ecto.Schema.t()} - On success
  • {:error, Ecto.Changeset.t()} - On validation failure

Examples

alias MyApp.{Repo, Product}
product = %Product{name: "Old Name"}
Core.update(Repo, product, %{name: "New Name"})
#=> {:ok, %Product{name: "New Name"}}