@spec array_list(list()) :: Xitdb.Collection.t()

Wraps list to be stored as a 16-way Radix Trie (Array_List).

@spec as_of(t(), integer()) :: Xitdb.Cursor.t()

Returns a lazy %Xitdb.Cursor{} pinned to historical moment_index (0..N-1, or negative from end).

@spec close(t()) :: :ok

Flushes and closes the underlying xitdb storage handle.

@spec compact(t(), keyword()) :: {:ok, t()} | {:error, Xitdb.Error.t()}

Compacts db into a new database keeping only the latest committed moment and deduplicating reachable slots.

@spec compact!(t(), keyword()) :: t()

Same as compact/2, but raises Xitdb.Error on failure.

@spec counted_map(Enumerable.t()) :: Xitdb.Collection.t()

Wraps map to be stored as a Counted_Hash_Map with $O(1)$ Enum.count/1.

@spec counted_set(Enumerable.t()) :: Xitdb.Collection.t()

Wraps members to be stored as a Counted_Hash_Set with $O(1)$ Enum.count/1.

@spec db(t()) :: Xitdb.Cursor.t()

Returns a lazy %Xitdb.Cursor{} pointing to the latest committed moment (-1).

@spec delete_at(Xitdb.Cursor.t(), String.t() | [term()], integer()) ::
  Xitdb.Cursor.t()

Stages an $O(\log N)$ removal from a Linked_Array_List at path_or_selector and index on a root %Xitdb.Cursor{} inside Xitdb.transact/2.

@spec diff_moments(t(), integer(), integer()) ::
  {:ok, [map()]} | {:error, Xitdb.Error.t()}

Computes the structural diff between moment_a and moment_b, skipping unchanged subtrees in $O(1)$ via 9-byte Slot equality.

@spec fork(Xitdb.Cursor.t(), String.t(), String.t()) :: Xitdb.Cursor.t()

Stages an $O(1)$ zero-copy structural clone (tx_fork) from from_selector to to_selector.

@spec hash_map(Enumerable.t()) :: Xitdb.Collection.t()

Wraps map to be stored as an uncounted 16-way HAMT (Tag.Hash_Map).

@spec hash_set(Enumerable.t()) :: Xitdb.Collection.t()

Wraps members to be stored as a 16-way HAMT Hash_Set.

@spec history_of(t(), String.t()) :: {:ok, [map()]} | {:error, Xitdb.Error.t()}

Returns the historical lineage of selector across all moments where its Slot changed.

@spec info(t()) :: {:ok, map()} | {:error, Xitdb.Error.t()}

Returns database metadata (%{moment_count: integer(), file_size: integer()}).

@spec info!(t()) :: map()

Same as info/1, but raises Xitdb.Error on failure.

@spec insert_at(Xitdb.Cursor.t(), String.t() | [term()], integer(), term()) ::
  Xitdb.Cursor.t()

Stages an $O(\log N)$ insertion into a Linked_Array_List at path_or_selector and index on a root %Xitdb.Cursor{} inside Xitdb.transact/2.

path_or_selector can be a selector string (path(users[id].queue)) or a list of keys / typed {kind, key} steps ([{:counted, "users"}, "alice", "queue"]).

@spec linked_list(list()) :: Xitdb.Collection.t()

Wraps list to be stored as a count-augmented B-Tree (Linked_Array_List).

@spec materialize(t() | Xitdb.Cursor.t() | term()) :: term()

Eagerly materializes a %Xitdb.Cursor{} (or %Xitdb{} database handle) into native Elixir maps (%{}), lists ([]), sets (MapSet.t()), and scalars.

@spec moment_count(t()) :: non_neg_integer()

Returns the number of committed historical moments in db.

@spec open(keyword()) :: {:ok, t()} | {:error, Xitdb.Error.t()}

Opens a Xitdb database instance.

Options

• :backend - Storage backend (:memory, :file, or :buffered_file). The default value is :memory.

• :path (String.t/0) - Filesystem path for :file or :buffered_file backends. The default value is "".

• :hash - Cryptographic digest algorithm for HAMT keys (:sha1 or :sha256). The default value is :sha1.

@spec open!(keyword()) :: t()

Same as open/1, but raises Xitdb.Error on failure.

@spec pull(t() | Xitdb.Cursor.t(), Xitdb.Pull.pattern()) ::
  {:ok, term()} | {:error, Xitdb.Error.t()}

Executes a Datomic-style Pull projection against a %Xitdb.Cursor{} or %Xitdb{} handle.

Accepts either a raw Pull pattern string ("{username, age, todos[0..2], profile{city}}") or a structural Elixir list ([:username, :age, todos: 0..2, profile: [:city]]).

@spec pull!(t() | Xitdb.Cursor.t(), Xitdb.Pull.pattern()) :: term()

Same as pull/2, but raises Xitdb.Error on failure.

@spec query(t() | Xitdb.Cursor.t(), String.t(), keyword()) ::
  {:ok, %{vars: [String.t()], rows: [[term()]]}} | {:error, Xitdb.Error.t()}

Executes a Datalog query (~q"find ?e, ?name where ...") against db or a %Xitdb.Cursor{}.

@spec query!(t() | Xitdb.Cursor.t(), String.t(), keyword()) :: %{
  vars: [String.t()],
  rows: [[term()]]
}

Same as query/3, but raises Xitdb.Error on failure.

@spec select(t() | Xitdb.Cursor.t(), String.t()) ::
  {:ok, term()} | {:error, Xitdb.Error.t()}

Resolves a canonical xitdb selector string (~x|.users["101"].todos[1]|) against db or a %Xitdb.Cursor{}.

@spec select!(t() | Xitdb.Cursor.t(), String.t()) :: term()

Same as select/2, but raises Xitdb.Error on failure.

@spec sorted_map(Enumerable.t()) :: Xitdb.Collection.t()

Wraps map to be stored as a lexicographically ordered B+Tree (Sorted_Map).

@spec sorted_set(Enumerable.t()) :: Xitdb.Collection.t()

Wraps members to be stored as a lexicographically ordered B+Tree Sorted_Set.

@spec sync(t()) :: :ok | {:error, Xitdb.Error.t()}

Synchronizes buffered writes to disk.

@spec transact(
  t(),
  map() | (Xitdb.Cursor.t() -> Xitdb.Cursor.t() | {:abort, term()}),
  keyword()
) ::
  {:ok, t()} | {:error, Xitdb.Error.t()}

Executes an atomic transaction committing a new moment to db.

Accepts either:

• A map of top-level keys/subtrees (Xitdb.transact(db, %{"users" => ...}, opts)), or
• A 1-arity callback receiving the root %Xitdb.Cursor{} (Xitdb.transact(db, fn root -> put_in(root["a"]["b"], 1) end)).

@spec transact!(t(), map() | (Xitdb.Cursor.t() -> Xitdb.Cursor.t()), keyword()) :: t()

Same as transact/3, but raises Xitdb.Error on failure.

@spec transact_ops(t(), list(), keyword()) :: {:ok, t()} | {:error, Xitdb.Error.t()}

Executes a list of low-level transaction tuples ({:put, path, val}, {:insert, path, idx, val}, etc.) in a single atomic NIF transaction commit.