Modules and Functions

Here is a brief summary of the modules and functions exposed by Journey.

`Journey` (Main Module)

The entry point for the Journey library. Provides functions for creating and managing computation graphs, starting and managing executions, and retrieving values from executions.

Graph Management

Journey.new_graph/4 - Creates a new computation graph with the given name, version, and node definitions. Accepts options including singleton: true for singleton graphs and keep_latest_completed_computations: N for graph-wide computation retention.

Execution Lifecycle

Journey.start/1 - Starts a new execution instance of a computation graph (raises for singleton graphs)
Journey.find_or_start/1 - Returns existing execution or creates new for singleton graphs
Journey.load/2 - Loads the current version of an execution from the database
Journey.list_executions/1 - Queries and retrieves executions with filtering, sorting, and pagination
Journey.count_executions/1 - Returns the count of executions matching the specified criteria without fetching the execution records
Journey.archive/1 - Archives an execution, making it invisible and stopping all background processing
Journey.unarchive/1 - Un-archives the supplied execution if it is archived
Journey.history/1 - Returns the chronological history of all successful computations and set values

Value Operations

Journey.set/2, Journey.set/3 - Sets values for input node(s) in an execution (potentially unblocking downstream computations). Accepts an execution struct or an execution ID.
Journey.unset/2 - Removes values from input nodes and invalidates all dependent computed nodes. Accepts an execution struct or an execution ID.
Journey.get/3 - Returns the value of a node in an execution and its revision, optionally waits for the value to be set or updated. Accepts an execution struct or an execution ID.

Data Retrieval

Journey.values/2 - Returns a map of all set node values in an execution, excluding unset nodes. Accepts an execution struct or an execution ID.
Journey.values_all/2 - Returns a map of all nodes in an execution with their current status, including unset nodes. Accepts an execution struct or an execution ID.

Deprecated

Journey.get_value/3 - Deprecated, use Journey.get/3 instead.

`Journey.Node`

Functions for creating various types of nodes in a graph.

Functions:

Journey.Node.input/1 - Creates a graph input node whose value is set with Journey.set/3 or Journey.set/2
Journey.Node.input/2 - Creates a graph input node with options (e.g., f_on_save callback invoked after Journey.set/3)
Journey.Node.compute/4 - Creates a self-computing node that calculates its value based on upstream dependencies, when unblocked
Journey.Node.mutate/4 - Creates a graph node that mutates the value of another node, when unblocked (optionally triggers downstream recomputation with update_revision_on_change: true)
Journey.Node.historian/3 - Creates a history-tracking node that maintains a chronological log of changes to one or more nodes (default limit: 1000 entries)
Journey.Node.archive/3 - Creates a graph node that archives the execution when unblocked
Journey.Node.tick_once/4 - Creates a graph node that declares its readiness at a specific time, once
Journey.Node.tick_recurring/4 - Creates a graph node that declares its readiness at specific times, repeatedly
Journey.Node.loop/4 - Creates a self-iterating node that threads state across iterations durably until termination or an iteration cap (the durable analogue of Stream.unfold/2/Enum.reduce_while/3)

`Journey.Node.Conditions`

Helper functions for use in graph definitions, when defining upstream dependencies for compute modules.

Functions:

Journey.Node.Conditions.provided?/1 - Checks if the supplied node has a value (for scheduled nodes, also checks timing)
Journey.Node.Conditions.true?/1 - Checks if the upstream node's value is true
Journey.Node.Conditions.false?/1 - Checks if the upstream node's value is false

`Journey.Node.UpstreamDependencies`

Functions for defining complex conditions under which nodes are unblocked.

Functions:

Journey.Node.UpstreamDependencies.unblocked_when/1 - Helper function for defining unblock conditions
Journey.Node.UpstreamDependencies.unblocked_when/2 - Defines conditions using predicate trees with :and, :or, :not operations

`Journey.Tools`

Utility functions for debugging, analysis, and visualization of Journey executions.

Functions:

Journey.Tools.abandon_computation/1 - Manually abandons a computation in :computing state, scheduling a retry if max_retries not exhausted
Journey.Tools.computation_state/2 - Returns the current state of a computation node (:not_set, :computing, :success, :failed, etc.)
Journey.Tools.computation_state_to_text/1 - Converts a computation state atom to human-readable text with visual symbols
Journey.Tools.computation_status_as_text/2 - Shows the status and dependencies for a single computation node
Journey.Tools.generate_mermaid_graph/2 - Generates a Mermaid diagram representation of a Journey graph
Journey.Tools.generate_mermaid_execution/2 - Generates a Mermaid diagram of an execution with runtime status emojis overlaid on each node
Journey.Tools.introspect/1 - Introspects an execution's current state with a human-readable text summary including computation timing. This is the primary debugging and introspection tool
Journey.Tools.retry_computation/2 - Retries a failed computation by making previous attempts stale
Journey.Tools.summarize_as_data/1 - Generates structured data about an execution's current state
Journey.Tools.what_am_i_waiting_for/2 - Shows the status of upstream dependencies for a computation node

Deprecated

Journey.Tools.summarize/1 - Deprecated, use Journey.Tools.introspect/1 instead.
Journey.Tools.summarize_as_text/1 - Deprecated, use Journey.Tools.introspect/1 instead.

`Journey.Insights.FlowAnalytics`

System-wide aggregate data about the state of executions for a particular graph. Business-focused analytics for understanding customer behavior.

Functions:

Journey.Insights.FlowAnalytics.flow_analytics/3 - Provides business-focused analytics for understanding customer behavior through Journey graphs
Journey.Insights.FlowAnalytics.to_text/1 - Formats flow analytics data as human-readable text output

`Journey.Insights.Status`

System health and monitoring insights for Journey executions.

Functions:

Journey.Insights.Status.status/0 - Returns current system health for monitoring/alerting (:healthy/:unhealthy status, DB connectivity, graph statistics)
Journey.Insights.Status.to_text/1 - Formats status data as human-readable text output