Skip to content

Choosing a Pattern ​

Holo gives you several ways to run code in response to something in your app. This page helps you pick between a direct function call, an event with listeners, a queue job, and a notification.

Quick guide ​

You want to...Use
Run one action that the caller depends onA direct function call
Announce that something happened and let several parts of the app reactAn event with listeners
React to an event without slowing down the requestA queued listener
Run one specific piece of background workA queue job
Tell a user something by email, database, or another channelA notification

Direct function calls ​

Call a function directly when the caller needs the result, or when there is only ever one thing to do. Direct calls are the easiest to read and debug. Don't add an event just to call one function.

Events with sync listeners ​

Use an event when one action has several independent reactions, and the code that triggers it shouldn't know about each one. For example, user.registered might trigger an audit log entry, a welcome email, and an analytics call. You can add a fourth reaction later without touching the registration code.

Sync listeners run during the dispatch, in order. Use them for quick work that should finish before the request responds. A sync listener that throws makes the dispatch throw.

Queued listeners ​

Use a queued listener when the reaction is slow, calls an external service, or should survive a crash and be retried. Good fits are welcome emails, analytics fan-out, and updating search indexes.

You keep the event's "one signal, many reactions" structure, and each slow reaction runs in a worker.

Queue jobs ​

Use a queue job when the work itself is the point, not a reaction to something that happened. For example: generating a nightly report, processing an uploaded video, or cleaning up expired records.

Jobs have their own typed payload and their own retry settings. A listener can dispatch a job, which is a good way to reuse the same background work from several places.

Notifications ​

Use a notification when the goal is to tell a person something, possibly through several channels like email and the database. Notifications handle choosing channels and formatting the message, and they can be queued too.

A common setup is to dispatch an event, then send a notification from one of its listeners.

Next steps ​

Released under the MIT License.