Jido.Flow.Registry (Jido Action v3.0.0-beta.12)

View Source

Resolves stable stored identifiers to trusted host Actions, Flows, schemas, and data atoms.

A Registry is flat. Each string identifier maps to one typed write entry or one read alias:

Jido.Flow.Registry.new!(%{
  "actions/send-email" => {:action, MyApp.SendEmail},
  "flows/send-email" => {:flow, MyApp.SendEmailFlow},
  "actions/send-email-old" => {:alias, "actions/send-email"},
  "schemas/email" => {:schema, MyApp.EmailSchema.schema()},
  "atoms/approved" => {:atom, :approved}
})

A typed entry is the canonical identifier that the writer uses for its value. An alias is accepted only during reads and must refer directly to a typed entry. This permits identifier migration without making writes ambiguous.

Stored Flow data contains identifiers only. The reader resolves them through a Registry that the host application owns. Resolution does not create atoms or derive module names from stored data.

Use from_flow/1 only when temporary generated identifiers are sufficient. Keep the returned Registry with the encoded document because the document does not contain the Registry.

Summary

Functions

Builds a convenience Registry from one executable Flow.

Finds the canonical write identifier for a trusted Action, Flow, schema, or atom value.

Builds and validates a flat trusted-host Registry.

Builds a Registry or raises the validation error.

Resolves one identifier of the required kind.

Types

alias_entry()

@type alias_entry() :: {:alias, stable_id()}

entry()

@type entry() :: write_entry() | alias_entry()

kind()

@type kind() :: :action | :flow | :schema | :atom

stable_id()

@type stable_id() :: String.t()

t()

@type t() :: %Jido.Flow.Registry{
  entries: %{required(stable_id()) => entry()},
  write_ids: %{required(write_key()) => stable_id()}
}

write_entry()

@type write_entry() ::
  {:action, module()} | {:flow, module()} | {:schema, term()} | {:atom, atom()}

write_key()

@type write_key() :: {kind(), term()}

Functions

from_flow(flow)

@spec from_flow(Jido.Flow.t()) :: {:ok, t()} | {:error, Exception.t()}

Builds a convenience Registry from one executable Flow.

The generated identifiers are deterministic only for the exact canonical Flow value. They can change when the Flow, a target module, or a schema changes. Use this function for temporary storage, tests, or transport within one application version. Use new/1 with application-owned identifiers for durable storage.

The function validates the Flow and all Action and child Flow contracts. It does not run Action work.

identifier(registry, kind, value)

@spec identifier(t(), kind(), term()) :: {:ok, stable_id()} | {:error, Exception.t()}

Finds the canonical write identifier for a trusted Action, Flow, schema, or atom value.

new(entries)

@spec new(map() | t()) :: {:ok, t()} | {:error, Exception.t()}

Builds and validates a flat trusted-host Registry.

new!(entries)

@spec new!(map() | t()) :: t() | no_return()

Builds a Registry or raises the validation error.

resolve(registry, identifier, kind)

@spec resolve(t(), stable_id(), kind()) ::
  {:ok, module() | term()} | {:error, Exception.t()}

Resolves one identifier of the required kind.