# `Skuld.Effects.Fresh`
[🔗](https://github.com/mccraigmccraig/skuld/blob/main/lib/skuld/effects/fresh.ex#L1)

Fresh effect - generate fresh/unique UUIDs.

Provides three operations:

  * `Fresh.fresh_uuid()` — generate a UUID (version unspecified)
  * `Fresh.uuid4()` — explicitly request a v4 UUID
  * `Fresh.uuid7()` — explicitly request a v7 UUID

The caller expresses the version they want; the handler decides what to
actually emit. A production handler honours the contract; a test handler
returns deterministic values from all three operations for reproducibility.

Two handler modes:

- **Production** (`with_uuid7_handler/1`): Generates v7 UUIDs which are
  time-ordered and suitable for database primary keys (good data locality,
  lexical ordering).

- **Test** (`with_test_handler/2`): Generates deterministic v5 UUIDs based
  on a namespace and counter, making sequences reproducible for testing.

## Production Usage

    use Skuld.Syntax
    alias Skuld.Comp
    alias Skuld.Effects.Fresh

    comp do
      id1 <- Fresh.fresh_uuid()
      id2 <- Fresh.uuid7()
      {id1, id2}
    end
    |> Fresh.with_uuid7_handler()
    |> Comp.run!()
    #=> {"01945a3b-...", "01945a3b-..."}  # time-ordered v7 UUIDs

## Test Usage (Deterministic)

    # Same namespace produces same UUID sequence - reproducible tests
    namespace = Uniq.UUID.uuid4()

    comp do
      uuid <- Fresh.fresh_uuid()
      uuid
    end
    |> Fresh.with_test_handler(namespace: namespace)
    |> Comp.run!()
    #=> "550e8400-..."  # deterministic v5 UUID

    # Running again with same namespace produces same result
    comp do
      uuid <- Fresh.fresh_uuid()
      uuid
    end
    |> Fresh.with_test_handler(namespace: namespace)
    |> Comp.run!()
    #=> "550e8400-..."  # same UUID!

## Handler Submodules

- `Fresh.UUID7` - Production v7 UUID handler
- `Fresh.Test` - Deterministic v5 UUID handler for testing

# `__handle__`

Install Fresh handler via catch clause syntax.

Config selects handler type:

    catch
      Fresh -> :uuid7                      # production handler
      Fresh -> {:test, namespace: ns}      # test handler with opts
      Fresh -> :test                       # test handler, default opts

# `state_key`

# `with_test_handler`

```elixir
@spec with_test_handler(
  Skuld.Comp.Types.computation(),
  keyword()
) :: Skuld.Comp.Types.computation()
```

Install a deterministic UUID handler for testing.

Delegates to `Fresh.Test.with_handler/2`.

## Options

- `namespace` - UUID namespace for generation (default: a fixed UUID).
- `output` - optional function `(result, final_counter) -> new_result`
  to transform the result before returning.

## Example

    namespace = Uniq.UUID.uuid4()

    comp do
      uuid <- Fresh.fresh_uuid()
      uuid
    end
    |> Fresh.with_test_handler(namespace: namespace)
    |> Comp.run!()

# `with_uuid7_handler`

```elixir
@spec with_uuid7_handler(Skuld.Comp.Types.computation()) ::
  Skuld.Comp.Types.computation()
```

Install a v7 UUID handler for production use.

Delegates to `Fresh.UUID7.with_handler/1`.

## Example

    comp do
      id <- Fresh.fresh_uuid()
      id
    end
    |> Fresh.with_uuid7_handler()
    |> Comp.run!()
    #=> "01945a3b-7c9d-7000-8000-..."  # v7 UUID

---

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