# `Xitdb.DSL`
[🔗](https://github.com/boxxxie/xitdb-elixir/blob/v1.0.1/lib/xitdb/dsl.ex#L1)

Compile-time macro DSL for `Xitdb` path selectors, transaction mutation blocks,
structural Pull patterns, and Ecto/Datomic-style Datalog queries.

## Usage

    use Xitdb.DSL

    # 1. Path selector macro with runtime interpolation & collection tags
    sel = path(users[user_id].todos[[idx]])
    counted_sel = path(org.counted(:departments)[dept_id].headcount)

    # 2. Atomic transaction block (0 intermediate NIF reads, auto-vivifies paths)
    {:ok, db} =
      tx db, doc: "promote alice" do
        put users[id].role, "admin"
        append users[id].audit_log, "promoted"
        insert users[id].todos[[0]], "urgent task"
        slice users[id].todos, 0..9
        fork users[id], backups[id]
        rm users[id].temp_token
        update users[id].login_count, &((&1 || 0) + 1)
      end

    # 3. Declarative Datalog query macro with ^var pinning
    {:ok, res} =
      query db do
        find {name, salary}
        where [
          sorted("username->id")[name] == id,
          starts_with(name, ^prefix),
          users[id].salary == salary,
          salary >= ^min_salary,
          not(users[id].flags.set_member("suspended"))
        ]
      end

# `datalog`
*macro* 

Compiles an Ecto/Datomic-style Datalog query block into a canonical `xitdb` Datalog string.

## Examples

    min_age = 21

    q =
      datalog do
        find {e, name, age}
        from users
        where [
          e.username == name,
          e.age == age,
          age >= ^min_age,
          not(e.banned == true)
        ]
      end

# `path`
*macro* 

Compiles an Elixir path expression into a canonical `xitdb` selector binary.

Static segments are folded into a single binary literal at compile time, while
dynamic runtime expressions (`users[id]`, `todos[[idx]]`) are safely encoded at
runtime.

## Supported Step Modifiers
- `.field` or `[key]` — `:hash_map` (`.key`)
- `counted(:key)` or `counted(var)` — `:counted_hash_map` (`#key`)
- `sorted(:key)` or `sorted(var)` — `:sorted_map` (`$key`)
- `[idx]` or `array(idx)` — `:array_list` (`[idx]`)
- `[[idx]]` or `linked(idx)` — `:linked_array_list` (`[[idx]]`)
- `set_member(m)` — `:hash_set` (`%m`)
- `counted_set_member(m)` — `:counted_hash_set` (`#%m`)
- `sorted_set_member(m)` — `:sorted_set` (`^m`)
- `at_moment(moment, path)` — prefixes `@<moment>`

# `pull_pattern`
*macro* 

Compiles a structural Pull pattern into a canonical `xitdb` Pull string at compile time
when given a literal list, or at runtime if dynamic.

# `query`
*macro* 

Compiles and executes a Datalog query block against `target` (`%Xitdb{}` or `%Xitdb.Cursor{}`).

# `query`
*macro* 

# `query!`
*macro* 

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

# `query!`
*macro* 

# `tx`
*macro* 

Executes a declarative transaction block and commits all staged operations in a
single atomic NIF call.

Inside `tx`, the following operations are available:
- `put path_expr, value` (or 1-arity `put set_path.set_member(member)` for set members)
- `update path_expr, fun` (or 3-arity `update path_expr, default, fun`)
- `rm path_expr`
- `append path_expr, value`
- `insert list_path[[idx]], value` (or `insert list_path, idx, value`)
- `slice list_path, first..last` (or `slice list_path, offset, size`)
- `fork from_path, to_path`
- `index_on source_map, field_key, index_map`
- `init_col path_expr, kind`
- `reset_col path_expr, kind`
- `meta key, value`
- `instant epoch_ms`
- `savepoint()`
- `abort reason`

# `tx`
*macro* 

# `tx!`
*macro* 

Same as `tx/2` and `tx/3`, but returns the updated `%Xitdb{}` handle directly
or raises `Xitdb.Error` on failure.

# `tx!`
*macro* 

# `tx_for`
*macro* 

Wraps `tx/2` and `tx/3`, automatically injecting all `index_on` declarations
configured on one or more `Xitdb.Ash.Resource` modules (or modules exporting
`__xitdb_indexes__/0` and optional `__xitdb_collection__/0`).

# `tx_for`
*macro* 

# `tx_for!`
*macro* 

Same as `tx_for/3` and `tx_for/4`, but returns the updated `%Xitdb{}` handle directly
or raises `Xitdb.Error` on failure.

# `tx_for!`
*macro* 

---

*Consult [api-reference.md](api-reference.md) for complete listing*