Skuld.Effects.Fresh (skuld v0.1.26)

Fresh effect - generate fresh/unique UUIDs.

Provides 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.fresh_uuid()
  return({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()
  return(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()
  return(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

Summary

Functions

__handle__(comp, arg2)

Install Fresh handler via catch clause syntax.

fresh_uuid()

Generate a fresh UUID.

with_test_handler(comp, opts \\ [])

Install a deterministic UUID handler for testing.

with_uuid7_handler(comp)

Install a v7 UUID handler for production use.

Functions

handle(comp, arg2)

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

fresh_uuid()

@spec fresh_uuid() :: Skuld.Comp.Types.computation()

Generate a fresh UUID.

The UUID format depends on the installed handler:

with_uuid7_handler/1: Generates v7 UUIDs (time-ordered, production)
with_test_handler/2: Generates v5 UUIDs (deterministic, testing)

Example

comp do
  uuid1 <- Fresh.fresh_uuid()
  uuid2 <- Fresh.fresh_uuid()
  return({uuid1, uuid2})
end
|> Fresh.with_uuid7_handler()
|> Comp.run!()

with_test_handler(comp, opts \\ [])

@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()
  return(uuid)
end
|> Fresh.with_test_handler(namespace: namespace)
|> Comp.run!()

with_uuid7_handler(comp)

@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()
  return(id)
end
|> Fresh.with_uuid7_handler()
|> Comp.run!()
#=> "01945a3b-7c9d-7000-8000-..."  # v7 UUID