Lazy Cursors, Access & Enumerable (%Xitdb.Cursor{})

Unlike traditional embedded database wrappers that eagerly deserialize on-disk records into BEAM heap maps on every read, Xitdb exposes database nodes as Clojure/Datomic-style lazy %Xitdb.Cursor{} handles.

Each %Xitdb.Cursor{} wraps only the NIF database resource reference (db_ref) and a 9-byte Slot coordinate (tag, tag_id, value, moment). Navigating or slicing a cursor resolves only the requested path steps across the NIF boundary without touching or copying sibling subtrees.

1. The 9-Byte Slot Cursor Model & Process Safety

When you read from a %Xitdb{} handle (Xitdb.db(db), Xitdb.as_of(db, moment), or db["users"]):

1. Containers return %Xitdb.Cursor{} in $O(1)$ heap space: If the target slot is a collection (:hash_map, :counted_hash_map, :sorted_map, :array_list, :linked_array_list, :hash_set, :counted_hash_set, :sorted_set), Xitdb returns a lightweight %Xitdb.Cursor{} struct pointing to that collection's byte offset.
2. Leaf scalars unwrap automatically: If the target slot is a scalar (String.t(), integer(), float(), boolean(), or {:tagged, tag, payload}), Xitdb immediately decodes and returns the native Elixir value.
3. Pure Elixir values across BEAM processes: Because %Xitdb.Cursor{} holds only an ErlNifResourceType reference (db_ref) and integer slot coordinates—with ErlNifRWLock reader/writer synchronization inside the NIF—cursors are pure, immutable Elixir values. You can pass them freely across Task.async_stream/3, GenServers, :ets tables, and Phoenix LiveView assigns without locks or lifetime hazards:

{:ok, db} = Xitdb.open(backend: :memory)

{:ok, db} =
  Xitdb.transact(db, %{
    "users" => %{
      "alice" => %{"name" => "Alice Liddell", "age" => 30, "roles" => ["admin", "staff"]},
      "bob" => %{"name" => "Bob Builder", "age" => 28, "roles" => ["member"]}
    }
  })

# Grab a lazy cursor to the "users" Hash_Map (O(1), 0 map keys copied)
users_cursor = db["users"]

# Fan out concurrent reads across BEAM schedulers using the same cursor value
names =
  ["alice", "bob"]
  |> Task.async_stream(fn id -> users_cursor[id]["name"] end)
  |> Enum.map(fn {:ok, name} -> name end)
# => ["Alice Liddell", "Bob Builder"]

2. Reading with Access (cursor[key], get_in/2, Xitdb.at/1)

Both %Xitdb{} and %Xitdb.Cursor{} implement Elixir's @behaviour Access:

root = Xitdb.db(db)

# 1. String and atom keys on maps (Hash_Map, Counted_Hash_Map, Sorted_Map)
root["users"]["alice"]["name"] # => "Alice Liddell"
root[:users][:alice][:age]     # => 30
root["users"]["missing"]       # => nil

# 2. Positive and negative integer indices on lists (Array_List, Linked_Array_List)
root["users"]["alice"]["roles"][0]  # => "admin"
root["users"]["alice"]["roles"][-1] # => "staff"
root["users"]["alice"]["roles"][99] # => nil

# 3. Deep navigation with Kernel.get_in/2
get_in(root, ["users", "alice", "roles", 0])
# => "admin"

Using Xitdb.at/1 Instead of Access.at/1

Elixir's built-in Access.at/1 function guards when is_list(data) and raises FunctionClauseError when given a %Xitdb.Cursor{} struct. When building functional lens pipelines with get_in/2 or update_in/3, either pass raw integer indices in the path list or use Xitdb.at/1:

# Direct integer key in path list:
get_in(root, ["users", "alice", "roles", 1])
# => "staff"

# Or using the Xitdb.at/1 lens function:
get_in(root, ["users", "alice", "roles", Xitdb.at(1)])
# => "staff"

3. Transactional Access Mutations (put_in/3, update_in/3, pop_in/2)

When you pass a 1-arity callback to Xitdb.transact/3, the callback receives a root %Xitdb.Cursor{} with tx_mode: true.

In tx_mode: true:

• put_in/3, update_in/3, pop_in/2, and get_and_update_in/3 stage coarse-grained transaction operations on the root cursor.
• Read-your-own-writes: Staged puts (staged_overrides) and removals (deleted_paths) are tracked in memory on the cursor so subsequent cursor[key] or update_in/3 calls in the same callback see your uncommitted edits immediately.
• Native list and subtree helpers (Xitdb.insert_at/4, Xitdb.delete_at/3, Xitdb.fork/3) pipe directly on the root cursor.

{:ok, db} =
  Xitdb.transact(
    db,
    fn root ->
      # 1. Remove a field with pop_in/2
      {_removed, root} = pop_in(root["users"]["alice"]["temp_token"])

      # 2. Pipe standard Access mutations and native collection operations
      root
      |> put_in(["users", "alice", "role"], "principal")
      |> update_in(["users", "alice", "age"], &(&1 + 1))
      |> Xitdb.insert_at(["users", "alice", "roles"], 0, "owner")
      |> Xitdb.fork(".users.alice", ".backups.alice")
    end,
    doc: "Promote Alice via Access pipeline"
  )

To abort and roll back from inside a Xitdb.transact/3 callback, return {:abort, reason}:

{:error, %Xitdb.Error{reason: :insufficient_balance}} =
  Xitdb.transact(db, fn root ->
    if root["vault"]["balance"] < 500 do
      {:abort, :insufficient_balance}
    else
      update_in(root["vault"]["balance"], &(&1 - 500))
    end
  end)

4. Enumerable Fast-Path Pushdowns & Stream Pagination

%Xitdb.Cursor{} implements Enumerable with native data-structure pushdowns so common Enum operations execute in $O(1)$ or $O(\log N)$ inside Odin rather than linearly scanning elements in Elixir:

Examples

{:ok, db} =
  Xitdb.transact(db, %{
    "metrics" => Xitdb.counted_map(%{"cpu" => 42, "mem" => 78, "disk" => 19}),
    "leaderboard" => Xitdb.sorted_map(%{" rank:1" => "alice", " rank:2" => "bob", " rank:3" => "carol"}),
    "permissions" => Xitdb.counted_set(["read", "write", "deploy"]),
    "events" => Xitdb.linked_list(["e1", "e2", "e3", "e4", "e5"])
  })

root = Xitdb.db(db)

# 1. O(1) count header lookup
Enum.count(root["metrics"])     # => 3
Enum.count(root["permissions"]) # => 3

# 2. O(1) HAMT membership check (does NOT convert the set or map to a list)
Enum.member?(root["permissions"], "deploy") # => true
Enum.member?(root["metrics"], {"cpu", 42})  # => true

# 3. O(log N + K) index-seek slicing on Linked_Array_List and Sorted_Map
Enum.slice(root["events"], 1..3)
# => ["e2", "e3", "e4"]

Enum.slice(root["leaderboard"], 0..1)
# => [{" rank:1", "alice"}, {" rank:2", "bob"}]

# 4. Lazy streaming with adaptive chunking (fetches only the first 16-item page)
root["leaderboard"]
|> Stream.map(fn {_rank, user} -> String.upcase(user) end)
|> Enum.take(2)
# => ["ALICE", "BOB"]

5. When to Use Access vs. the Macro DSL (use Xitdb.DSL)