Narabe.Ecto.Mixed (Narabe v0.2.0)

Copy Markdown View Source

A tree whose items are rows of several schemas: folders and the pages in them, sections and their lessons, categories and their products. Each schema keeps its own table, its own position, and its own parent field, and a folder's children, folders and pages alike, are one list in one order.

tree =
  Narabe.Ecto.Mixed.new(
    [
      folder: [from: where(Folder, space_id: ^space.id), parent: :parent_id],
      page: [from: where(Page, space_id: ^space.id), parent: :folder_id]
    ],
    parents: :folder,
    rules: [accepts: %{"root" => ["folder", "page"], "folder" => ["folder", "page"]}]
  )

Each kind's :from is the whole of what may be moved of it (one space's folders), and its :parent is the field that holds its parent's id. The parents are rows of one kind, parents:, whose parent field holds a row of the same kind: a folder in a folder. The other kinds hold nothing.

An item's id in the tree is its kind and its primary key, "folder:3" or "page:9" (id/2), so that two tables' ids never meet. The items go to Narabe.Components.tree/1 as items/2 gives them, and the moves it sends come back to move/3:

<.tree id="pages" items={@items} item_kind={:kind} item_label={&label/1}
  rules={@tree.rules} on_move="move" />

def handle_event("move", params, socket) do
  tree = socket.assigns.tree
  result = Narabe.Ecto.Mixed.move(Repo, tree, Narabe.Move.parse!(params))
  {:reply, Narabe.Live.reply(result), assign(socket, items: Narabe.Ecto.Mixed.items(Repo, tree))}
end

A move works as Narabe.Ecto.move/4 does (see its moduledoc): it writes the moved rows only, their key and their parent, in one transaction; it lands after move.after, else before move.before, else at move.index, else at the end, among the siblings of every kind; it never goes into an item itself or under it, and it keeps the rules (:max_depth counts the levels of every kind under the moved items). Siblings of different kinds with the same key (two inserted at once) are in the order of the kinds, then by id.

Options of new/2

  • :parents - the kind whose rows hold others (required).
  • :rules - Narabe.Rules, or its options. An item's kind is its kind in the tree, "folder" or "page"; the kinds other than :parents are leaves, and a mixed tree nests.
  • :position - the position field of every kind (:position); a kind's own :position wins.
  • :serialize, :lock, :rebalance_at - as Narabe.Ecto's.

Errors

  • :not_found - an id that is not of the tree, an item or the new parent not in its kind's :from.
  • :into_itself, :not_accepted, :too_deep - the rules (Narabe.Rules).

Summary

Types

An item of items/2: its id in the tree, its parent's, its kind, and its row.

A kind of the tree: its queryable, schema, primary key and fields.

t()

Functions

An item's id in the tree, from its kind and its primary key, or from its row.

The id in the tree of a row of one of its kinds.

A key for a new row: :last (the default), :first, {:after, id} or {:before, id}, among the children of in: (an id of the tree, or nil for the top level), of every kind.

Every item of the tree, flat, each siblings' list in its order, as Narabe.Components.tree/1 takes them (item_kind={:kind}; the row is the item's :record).

Applies a move in a transaction: {:ok, rows}, the moved rows as they are now, in their new order; or {:error, reason}, with nothing changed. The move's ids are ids of the tree ("page:9"), as Narabe.Move.parse/2 gives them by default.

A tree of several schemas: see the moduledoc.

An id of the tree read back: {:ok, {kind, primary key}}, the key cast to its schema's type, or :error for an id that is not of the tree.

Puts a position in a changeset for a new row of one of the tree's kinds, unless it has one: at :last (or :first, …) among the children of its parent field's value.

Writes the keys of a parent's children anew, evenly, in their current order: for keys grown long, or tables that had no positions. in: is the parent, an id of the tree or nil. Returns how many rows it wrote.

Types

item()

@type item() :: %{
  id: String.t(),
  parent_id: String.t() | nil,
  kind: String.t(),
  record: struct()
}

An item of items/2: its id in the tree, its parent's, its kind, and its row.

kind()

@type kind() :: %{
  name: String.t(),
  queryable: Ecto.Queryable.t(),
  schema: module(),
  pk: atom(),
  pk_type: term(),
  parent: atom(),
  position: atom()
}

A kind of the tree: its queryable, schema, primary key and fields.

t()

@type t() :: %Narabe.Ecto.Mixed{
  kinds: %{required(String.t()) => kind()},
  lock: boolean() | nil,
  order: [String.t()],
  parents: String.t(),
  rebalance_at: pos_integer(),
  rules: Narabe.Rules.t(),
  serialize: Ecto.Queryable.t() | nil
}

Functions

id(kind, pk)

@spec id(atom() | String.t(), term()) :: String.t()

An item's id in the tree, from its kind and its primary key, or from its row.

iex> Narabe.Ecto.Mixed.id(:folder, 3)
"folder:3"

id_of(tree, record)

@spec id_of(t(), struct()) :: String.t()

The id in the tree of a row of one of its kinds.

insert_position(repo, tree, at \\ :last, opts \\ [])

@spec insert_position(Ecto.Repo.t(), t(), atom() | {atom(), String.t()}, keyword()) ::
  Narabe.Position.t()

A key for a new row: :last (the default), :first, {:after, id} or {:before, id}, among the children of in: (an id of the tree, or nil for the top level), of every kind.

position = Narabe.Ecto.Mixed.insert_position(Repo, tree, :last, in: "folder:3")

items(repo, tree)

@spec items(Ecto.Repo.t(), t()) :: [item()]

Every item of the tree, flat, each siblings' list in its order, as Narabe.Components.tree/1 takes them (item_kind={:kind}; the row is the item's :record).

move(repo, tree, move)

@spec move(Ecto.Repo.t(), t(), Narabe.Move.t()) ::
  {:ok, [struct()]} | {:error, term()}

Applies a move in a transaction: {:ok, rows}, the moved rows as they are now, in their new order; or {:error, reason}, with nothing changed. The move's ids are ids of the tree ("page:9"), as Narabe.Move.parse/2 gives them by default.

move_multi(multi, name, tree, move)

@spec move_multi(
  Ecto.Multi.t(),
  Ecto.Multi.name(),
  t(),
  Narabe.Move.t() | (map() -> Narabe.Move.t())
) ::
  Ecto.Multi.t()

A move as a step of an Ecto.Multi, as Narabe.Ecto.move_multi/5.

new(kinds, opts)

@spec new(keyword() | [{atom() | String.t(), keyword()}], keyword()) :: t()

A tree of several schemas: see the moduledoc.

parse_id(tree, id)

@spec parse_id(t(), String.t()) :: {:ok, {String.t(), term()}} | :error

An id of the tree read back: {:ok, {kind, primary key}}, the key cast to its schema's type, or :error for an id that is not of the tree.

put_position(changeset, repo, tree, at \\ :last)

@spec put_position(
  Ecto.Changeset.t(),
  Ecto.Repo.t(),
  t(),
  atom() | {atom(), String.t()}
) ::
  Ecto.Changeset.t()

Puts a position in a changeset for a new row of one of the tree's kinds, unless it has one: at :last (or :first, …) among the children of its parent field's value.

%Page{space_id: space.id}
|> Page.changeset(attrs)
|> Narabe.Ecto.Mixed.put_position(Repo, tree)
|> Repo.insert()

rebalance(repo, tree, opts \\ [])

@spec rebalance(Ecto.Repo.t(), t(), keyword()) :: non_neg_integer()

Writes the keys of a parent's children anew, evenly, in their current order: for keys grown long, or tables that had no positions. in: is the parent, an id of the tree or nil. Returns how many rows it wrote.