# `Goblin.Tx`
[🔗](https://github.com/zteln/goblin/blob/main/lib/goblin/tx.ex#L1)

Module for reading and writing within a transaction.

Used inside `Goblin.transaction/2` (read-write) and `Goblin.read/2` (read-only).

    Goblin.transaction(db, fn tx ->
      counter = Goblin.Tx.get(tx, :counter, default: 0)

      tx
      |> Goblin.Tx.put(:counter, counter + 1)
      |> Goblin.Tx.commit()
    end)

    Goblin.read(db, fn tx ->
      Goblin.Tx.get(tx, :alice)
    end)

# `t`

```elixir
@type t() :: %Goblin.Tx{
  commits: [{term(), non_neg_integer(), term()}],
  max_level_key: -1 | non_neg_integer(),
  mode: :write | :read,
  mvcc: :ets.table(),
  sequence: non_neg_integer(),
  tx_id: non_neg_integer()
}
```

# `abort`

```elixir
@spec abort(t(), any()) :: {:abort, any()}
```

Pipeline-friendly helper function to abort the transaction.

## Parameters

- `tx` - The transaction to abort
- `reply` - The reply after aborting (default: `:error`)

## Returns

- The abort tuple, i.e. `{:abort, reply}`.

## Examples

    tx
    |> Goblin.Tx.put(:alice, "Alice")
    |> Goblin.Tx.abort()

# `commit`

```elixir
@spec commit(t(), any()) :: {:commit, t(), any()}
```

Pipeline-friendly helper function to commit the transaction.

## Parameters

- `tx` - The transaction to commit
- `reply` - The reply after committing (default: `:ok`)

## Returns

- The commit tuple, i.e. `{:commit, tx, reply}`.

## Examples

    tx
    |> Goblin.Tx.put(:alice, "Alice")
    |> Goblin.Tx.commit()

# `get`

```elixir
@spec get(t(), term(), keyword()) :: term()
```

Retrieves a value within a transaction.

## Parameters

- `tx` - The transaction struct
- `key` - The key to look up
- `opts` - A keyword list with the following options (default: `[]`):
  - `:tag` - Tag the key is namespaced under
  - `:default` - Value to return if `key` is not found (default: `nil`)

## Returns

- The value associated with the key, or `default` if not found

## Examples

    Goblin.Tx.get(tx, :alice)
    # => "Alice"

    Goblin.Tx.get(tx, :nonexistent, default: :not_found)
    # => :not_found

# `get_multi`

```elixir
@spec get_multi(t(), [term()], keyword()) :: [{term(), term()}]
```

Retrieves values for multiple keys within a transaction.

Keys not found are excluded from the result.

## Parameters

- `tx` - The transaction struct
- `keys` - A list of keys to look up
- `opts` - A keyword list with the following options (default: `[]`):
  - `:tag` - Tag the keys are namespaced under

## Returns

- A list of `{key, value}` tuples for keys found, in unspecified order

## Examples

    [{:alice, "Alice"}, {:bob, "Bob"}] = Goblin.Tx.get_multi(tx, [:alice, :bob])

# `put`

```elixir
@spec put(t(), term(), term(), keyword()) :: t()
```

Writes a key-value pair within a transaction.

## Parameters

- `tx` - The transaction struct
- `key` - Any Elixir term to use as the key
- `value` - Any Elixir term to store
- `opts` - A keyword list with the following options (default: `[]`):
  - `:tag` - Tag to namespace the key under

## Returns

- Updated transaction struct

## Examples

    tx = Goblin.Tx.put(tx, :alice, "Alice")

# `put_multi`

```elixir
@spec put_multi(t(), [{term(), term()}], keyword()) :: t()
```

Writes multiple key-value pairs within a transaction.

## Parameters

- `tx` - The transaction struct
- `pairs` - A list of `{key, value}` tuples
- `opts` - A keyword list with the following options (default: `[]`):
  - `:tag` - Tag to namespace the keys under

## Returns

- Updated transaction struct

## Examples

    tx = Goblin.Tx.put_multi(tx, [{:alice, "Alice"}, {:bob, "Bob"}])

# `remove`

```elixir
@spec remove(t(), term(), keyword()) :: t()
```

Removes a key within a transaction.

## Parameters

- `tx` - The transaction struct
- `key` - The key to remove
- `opts` - A keyword list with the following options (default: `[]`):
  - `:tag` - Tag the key is namespaced under

## Returns

- Updated transaction struct

## Examples

    tx = Goblin.Tx.remove(tx, :alice)

# `remove_multi`

```elixir
@spec remove_multi(t(), [term()], keyword()) :: t()
```

Removes multiple keys within a transaction.

## Parameters

- `tx` - The transaction struct
- `keys` - A list of keys to remove
- `opts` - A keyword list with the following options (default: `[]`):
  - `:tag` - Tag the keys are namespaced under

## Returns

- Updated transaction struct

## Examples

    tx = Goblin.Tx.remove_multi(tx, [:alice, :bob])

---

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