Context for managing warehouse stock balances.
Provides functions to read stock levels and upsert quantities. Decimal coercion helpers ensure callers passing jsonb-origin strings or floats are handled safely.
Summary
Functions
UUID of the default warehouse Location stock is held at (setting), or nil.
Returns the current quantity for the given item UUID as a Decimal.
Returns Decimal.new("0") if no row exists.
Conditionally decrements warehouse stock for item_uuid.
Returns all stock rows.
Additively increases the stock quantity for item_uuid.
Sets the default warehouse Location UUID. Pass nil to clear.
Sets the LocationType UUID that marks warehouses. Pass nil to clear.
Returns stock rows for the given list of item UUIDs.
Returns a map of item_uuid => %{quantity: Decimal, unit_value: Decimal | nil}
for fast tree annotation.
Coerces a value to Decimal. nil and "" become Decimal.new("0").
Coerces a value to Decimal or nil. nil, blank strings, and empty strings
return nil. All other values convert like to_decimal/1.
Returns the total stock value: Σ (quantity * unit_value), skipping rows where unit_value is nil.
Upserts the stock quantity for item_uuid.
UUID of the LocationType that marks warehouses (admin-configurable setting), or nil.
Functions
UUID of the default warehouse Location stock is held at (setting), or nil.
Returns the current quantity for the given item UUID as a Decimal.
Returns Decimal.new("0") if no row exists.
Conditionally decrements warehouse stock for item_uuid.
Performs an atomic UPDATE with WHERE quantity >= qty to guard against
driving stock negative. Never inserts a row — if no stock row exists for
the item/location, the WHERE predicate matches 0 rows and the function
returns {:error, {:insufficient_stock, item_uuid}}.
Options:
:repo— override the repo (default fromPhoenixKit.RepoHelper.repo/0), used byEcto.Multitransactions.:location_uuid— warehouse location (default: configured default warehouse).
Returns:
{:ok, new_quantity}on success (Decimal).{:error, {:insufficient_stock, item_uuid}}when stock row is missing OR whenquantity < qty(covers both cases atomically via the WHERE guard).
Returns all stock rows.
Additively increases the stock quantity for item_uuid.
Unlike upsert_quantity/3 which does an absolute SET, this function performs
an additive INSERT … ON CONFLICT DO UPDATE SET quantity = quantity + EXCLUDED.quantity.
Options:
:unit_value— when not nil, also sets the unit_value; when nil, leaves existing value intact.:repo— override the repo (default fromPhoenixKit.RepoHelper.repo/0), used byEcto.Multitransactions.:location_uuid— warehouse location (default: configured default warehouse).
Returns {:ok, %Stock{}}.
Sets the default warehouse Location UUID. Pass nil to clear.
Sets the LocationType UUID that marks warehouses. Pass nil to clear.
Returns stock rows for the given list of item UUIDs.
Returns a map of item_uuid => %{quantity: Decimal, unit_value: Decimal | nil}
for fast tree annotation.
Coerces a value to Decimal. nil and "" become Decimal.new("0").
Coerces a value to Decimal or nil. nil, blank strings, and empty strings
return nil. All other values convert like to_decimal/1.
Returns the total stock value: Σ (quantity * unit_value), skipping rows where unit_value is nil.
Upserts the stock quantity for item_uuid.
Options:
:unit_value— when not nil, also sets the unit_value; when nil, leaves existing value intact.:repo— override the repo (default fromPhoenixKit.RepoHelper.repo/0), used byEcto.Multitransactions.
Returns {:ok, %Stock{}}.
UUID of the LocationType that marks warehouses (admin-configurable setting), or nil.