Singleton Functions TypeScript v3.38.0+
These docs are part of a developer preview for Inngest's Singleton Functions API. Learn more about the developer preview here.
Singleton Functions enable you to ensure that only a single run of your function (or a set of specific function runs, based on specific event properties) is happening at a time.
Singleton Functions are available in the TypeScript SDK starting from version 3.38.0.
When to use Singleton Functions
Singleton Functions are useful when you want to ensure that only a single instance of a function is running at a time, for example:
- A third-party data synchronization workflow
- A compute- or time-intensive function that should not be run multiple times at the same time (ex: AI processing)
Singleton compared to concurrency:
While Concurrency set to 1 ensures that only a single step of a given function is running at a time, Singleton Functions ensure that only a single run of a given function is happening at a time.
Singleton compared to Rate Limiting:
Rate Limiting is similar to Singleton Functions, but it is designed to limit the number of runs started within a time period, whereas Singleton Functions are designed to ensure that only a single run of a function occurs over a given time window.
Rate Limiting is useful for controlling the rate of execution of a function, while Singleton Functions are useful for ensuring that only a single run of a function occurs over a given time window.
How it works
Singleton Functions are configured using the singleton property in the function definition.
The following data-sync function will skip new runs if another run of the same function is already running for the same user:
const dataSync = inngest.createFunction({
id: "data-sync",
singleton: {
key: "event.data.user_id",
mode: "skip",
}
},
{ event: "data-sync.start" },
async ({ event }) => {
// ...
},
);
Refer to the reference documentation for more details.
Using a key
When a key is added, the unique runs rule is applied for each unique value of the key expression. For example, if your key is set to event.data.user_id,
each user would have their individual singleton rule applied to functions runs, ensuring that only a single run of the function is happening at a time for each user. Read our guide to writing expressions for more information.
Compatibility with other flow control features
Singleton Functions can be combined with other flow control features, with the following considerations:
| Flow control | Compatibility | Considerations |
|---|---|---|
| Debounce | ✅ | Can be used together without issues. |
| Rate limiting | ✅ | Similar functionality but rate limiting operates over a predefined time window rather than function execution duration. |
| Throttling | ✅ | Similar functionality but throttling enqueues events over time rather than discarding/canceling them. |
| Concurrency | ❌ | Singleton functions implicitly have a concurrency of 1. A concurrency setting can be set but should be used with caution. |
| Batching | ❌ | Not compatible with singleton functions. |
Developer preview
Singleton Functions is a developer preview feature and are subject to change without following semver.
Developer preview help us getting early feedback from the community. You can share your feedback in the Inngest Discord or via our support channel.
The following limitations are known and will be addressed in a future release:
- Skipped runs are not visible in the Inngest dashboard.
- Singleton isn't compatible with batching; function registration will fail if both are set.
FAQ
How does Singleton Functions work with retries?
If a singleton function fails and is retrying, it should still skip new incoming runs.