journey

<!-- livebook:{"persist_outputs":true} -->

# "tick_once" nodes

```elixir
# [Optional] Setting Build Key, see https://gojourney.dev/your_keys
# (Using "Journey Livebook Demo" build key)
System.put_env("JOURNEY_BUILD_KEY", "B27AXHMERm2Z6ehZhL49v")

Mix.install(
  [
    {:ecto_sql, "~> 3.13"},
    {:postgrex, "~> 0.22"},
    {:jason, "~> 1.4"},
    {:journey, "~> 0.10"},
    {:kino, "~> 0.19"}
  ],
  start_applications: false
)

Application.put_env(:journey, :log_level, :warning)

# Configure more frequent background sweeper runs (the default is 60 seconds).
# The precision of the timer is determined by the granularity of the sweeper.
Application.put_env(:journey, :background_sweeper, period_seconds: 5)

# This livebook requires a PostgreSQL database.
# If you don't have one running, you can start one with Docker:
# docker run --rm --name postgres -p 5432:5432 -e POSTGRES_PASSWORD=postgres -d postgres:16

# Update this configuration to point to your database server
Application.put_env(:journey, Journey.Repo,
  database: "journey_tick_once_nodes",
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  log: false,
  port: 5432
)

Application.put_env(:journey, :ecto_repos, [Journey.Repo])

Journey.Repo.__adapter__().storage_up(Journey.Repo.config())

Application.loaded_applications()
|> Enum.map(fn {app, _, _} -> app end)
|> Enum.each(&Application.ensure_all_started/1)
```

## DB Setup

This livebook requires a PostgreSQL service. If you don't have one running, you can start one with Docker:

```bash
docker run --rm --name postgres -p 5432:5432 -e POSTGRES_PASSWORD=postgres -d postgres:16
```

## What We'll Cover

This tutorial focuses on the `tick_once` node type, which is used for scheduling future events.

A `tick_once` node computes a future timestamp (in unix seconds).

Its downstream nodes become unblocked and fire when that future time arrives.

In this livebook, we'll build a nap scheduler: spin up an execution, tell it your name, `tick_once` will compute the scheduled nap time, and a `compute` node fires when the time arrives.

We will also look at the execution's values, diagram, and detailed introspection.

## Define the Graph

```elixir
import Journey.Node

schedule_nap_in_seconds = 30

graph = Journey.new_graph(
  "Nap Scheduler",
  "v1",
  [
    input(:name),
    tick_once(:schedule_nap, [:name],
      fn %{name: name} ->
        IO.puts("schedule_nap: scheduling a nap for #{name} in #{schedule_nap_in_seconds} seconds")
        {:ok, System.os_time(:second) + schedule_nap_in_seconds}
      end
    ),
    compute(:start_nap, [:name, :schedule_nap],
      fn %{name: name} ->
        {:ok, "time for a nap, #{name}!"}
      end
    )
  ]
); :ok
```

<!-- livebook:{"output":true} -->

```
:ok
```

Three nodes:

* `:name` is an input node, setting it kicks everything off,
* `:schedule_nap` fires as soon as `:name` is set, and returns the time (unix epoch seconds) at which the nap should start, and
* `:start_nap` fires when the time returned by `:schedule_nap` has arrived.

<!-- livebook:{"break_markdown":true} -->

Visualize the graph:

```elixir
graph
|> Journey.Tools.generate_mermaid_graph()
|> Kino.Mermaid.new()
```

<!-- livebook:{"output":true} -->

```mermaid
graph TD
    %% Graph
    subgraph Graph["🧩 'Nap Scheduler', version v1"]
        execution_id[execution_id]
        last_updated_at[last_updated_at]
        name[name]
        schedule_nap[["schedule_nap<br/>(anonymous fn)<br/>tick_once node"]]
        start_nap[["start_nap<br/>(anonymous fn)"]]

        name -->  schedule_nap
        name -->  start_nap
        schedule_nap -->  start_nap
    end

    %% Styling
    classDef defaultNode fill:#f8f9fa,stroke:#495057,stroke-width:2px,color:#000000

    %% Apply styles to nodes
    class execution_id,last_updated_at,name,schedule_nap,start_nap defaultNode
```

## Start an Execution and Request a Nap

```elixir
execution = 
  graph 
  |> Journey.start()
  |> Journey.set(:name, "Luigi");
:ok
```

<!-- livebook:{"output":true} -->

```
:ok
```

## Schedule That Nap

The tick fires immediately, but it's not time to start a nap just yet:

```elixir
{:ok, scheduled_time, revision} = Journey.get(execution, :schedule_nap, wait: :any)
now = System.os_time(:second)
scheduled_at_string = scheduled_time |> DateTime.from_unix!() |> Calendar.strftime("%H:%M:%S UTC")
"scheduled_time: #{scheduled_at_string}, in #{scheduled_time-now} seconds"
```

<!-- livebook:{"output":true} -->

```
schedule_nap: scheduling a nap for Luigi in 30 seconds
```

<!-- livebook:{"output":true} -->

```
"scheduled_time: 05:17:13 UTC, in 29 seconds"
```

`:schedule_nap` has computed — its value is a unix timestamp, containing the scheduled time.

`:start_nap` hasn't fired yet. It's waiting for the scheduled time:

```elixir
execution.id
|> Journey.Tools.generate_mermaid_execution()
|> Kino.Mermaid.new()
```

<!-- livebook:{"output":true} -->

```mermaid
graph TD
    %% Graph
    subgraph Graph["🧩 'Nap Scheduler', version v1, EXECL4Y00T46HD7MJH72R6A0"]
        execution_id["✅ execution_id"]
        last_updated_at["✅ last_updated_at"]
        name["✅ name"]
        schedule_nap[["✅ schedule_nap<br/>(anonymous fn)<br/>tick_once node"]]
        start_nap[["🚫 start_nap<br/>(anonymous fn)"]]

        name -->  schedule_nap
        name -->  start_nap
        schedule_nap -->  start_nap
    end

    %% Styling
    classDef setNode fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000000
    classDef computingNode fill:#fff8e1,stroke:#f57f17,stroke-width:2px,color:#000000
    classDef errorNode fill:#f8bbd0,stroke:#b71c1c,stroke-width:2px,color:#000000
    classDef neutralNode fill:#f8f9fa,stroke:#495057,stroke-width:2px,color:#000000

    %% Apply styles to nodes
    class schedule_nap,name,last_updated_at,execution_id setNode
    class start_nap neutralNode
```

## Wait for Nap Time to Start

```elixir
"Waiting for #{scheduled_at_string}..."
```

<!-- livebook:{"output":true} -->

```
"Waiting for 05:17:13 UTC..."
```

This will block until it's time:

```elixir
{:ok, value, _revision} = Journey.get(execution, :start_nap, wait: {:newer_than, revision}, timeout: 60_000)
now = DateTime.utc_now() |> Calendar.strftime("%H:%M:%S UTC")
"#{now}: #{value}"
```

<!-- livebook:{"output":true} -->

```
"05:17:17 UTC: time for a nap, Luigi!"
```

The actual event might occur a few seconds after its scheduled time. The precision of the timer is determined by the configured granularity of the sweeper – see `background_sweeper` configuration in the setup section.

<!-- livebook:{"break_markdown":true} -->

Examining the execution, we can see that `:start_nap` has been "computed."

```elixir
Journey.values(execution)
```

<!-- livebook:{"output":true} -->

```
%{
  name: "Luigi",
  last_updated_at: 1776921436,
  execution_id: "EXECL4Y00T46HD7MJH72R6A0",
  schedule_nap: 1776921433,
  start_nap: "time for a nap, Luigi!"
}
```

```elixir
execution.id
|> Journey.Tools.generate_mermaid_execution()
|> Kino.Mermaid.new()
```

<!-- livebook:{"output":true} -->

```mermaid
graph TD
    %% Graph
    subgraph Graph["🧩 'Nap Scheduler', version v1, EXECL4Y00T46HD7MJH72R6A0"]
        execution_id["✅ execution_id"]
        last_updated_at["✅ last_updated_at"]
        name["✅ name"]
        schedule_nap[["✅ schedule_nap<br/>(anonymous fn)<br/>tick_once node"]]
        start_nap[["✅ start_nap<br/>(anonymous fn)"]]

        name -->  schedule_nap
        name -->  start_nap
        schedule_nap -->  start_nap
    end

    %% Styling
    classDef setNode fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000000
    classDef computingNode fill:#fff8e1,stroke:#f57f17,stroke-width:2px,color:#000000
    classDef errorNode fill:#f8bbd0,stroke:#b71c1c,stroke-width:2px,color:#000000
    classDef neutralNode fill:#f8f9fa,stroke:#495057,stroke-width:2px,color:#000000

    %% Apply styles to nodes
    class start_nap,schedule_nap,name,last_updated_at,execution_id setNode
```

```elixir
Journey.Tools.introspect(execution.id) |> IO.puts()
```

<!-- livebook:{"output":true} -->

```
Execution summary:
- ID: 'EXECL4Y00T46HD7MJH72R6A0'
- Graph: 'Nap Scheduler' | 'v1'
- Archived at: not archived
- Created at: 2026-04-23 05:16:43Z UTC | 34 seconds ago
- Last updated at: 2026-04-23 05:17:16Z UTC | 1 seconds ago
- Duration: 33 seconds
- Revision: 5
- # of Values: 5 (set) / 5 (total)
- # of Computations: 2

Values:
- Set:
  - last_updated_at: '1776921436' | :input
    set at 2026-04-23 05:17:16Z | rev: 5

  - start_nap: '"time for a nap, Luigi!"' | :compute
    computed at 2026-04-23 05:17:16Z | rev: 5

  - schedule_nap: '1776921433' | :tick_once
    computed at 2026-04-23 05:16:43Z | rev: 3

  - name: '"Luigi"' | :input
    set at 2026-04-23 05:16:43Z | rev: 1

  - execution_id: 'EXECL4Y00T46HD7MJH72R6A0' | :input
    set at 2026-04-23 05:16:43Z | rev: 0


- Not set:
  

Computations:
- Completed:
  - :start_nap (CMPXDL51R4XEZD24YR7JG0D): ✅ :success | :compute | rev 5
    started: 2026-04-23 05:17:16Z | completed: 2026-04-23 05:17:16Z (0s)
    inputs used:
       :name (rev 1)
       :schedule_nap (rev 3)

  - :schedule_nap (CMP4A4LTR1L38R80X9RATGJ): ✅ :success | :tick_once | rev 3
    started: 2026-04-23 05:16:43Z | completed: 2026-04-23 05:16:43Z (0s)
    inputs used:
       :name (rev 1)

- Outstanding:

```

<!-- livebook:{"output":true} -->

```
:ok
```

## Beyond Naps

`tick_once` is useful when you need to schedule an action at a specific future time. Things like:

* issue a reminder a day before the due date,
* send the user a reminder email 2 weeks after their last visit,
* archive user information 1 month after their last engagement,
* ... any other place where you need to schedule a future event.

See the `tick_once/4` documentation for more details and examples.

## Summary

In this Livebook, we saw how `tick_once` nodes schedule actions for a specific future time.

We built a nap scheduler with three nodes — an `input`, a `tick_once`, and a `compute` — and watched the compute node wait until the scheduled time before firing.

Key takeaways:

* A `tick_once` node computes immediately, but its value is a future timestamp (in unix seconds).
* Downstream nodes will be unblocked when that time arrives.
* Use `tick_once` for reminders, delayed actions, scheduled cleanup — any time something should happen at a later point.