Skip to content

Sys.RateLimiting

Sys.RateLimiting runs a list of asynchronous tasks while limiting how many run at the same time and how many start within a time window. Use it, for example, to call an external API for many records without exceeding the API’s rate limit.

Availability: Everywhere

executeTasks<T>(tasks: (() => Promise<T>)[], options: RateLimitingOptions<true>): Promise<(Awaited<T> | null)[]>
executeTasks<T>(tasks: (() => Promise<T>)[], options: RateLimitingOptions<boolean>): Promise<Awaited<T>[]>

Starts the tasks in list order, within the limits set in options, and resolves with their results once all tasks have finished. The results are in the same order as tasks, whatever order the tasks finish in.

ParameterTypeDescription
tasks(() => Promise<T>)[]Functions that each start one task and return its promise. Lowgile calls a function only when the task may start.
optionsRateLimitingOptionsLimits and error handling. Pass {} for no limits.

RateLimitingOptions fields

FieldTypeRequiredDescription
runMaxTasksConcurrentlynumberNoMaximum number of tasks running at the same time. Defaults to the number of tasks, so all start at once.
waitForAllConcurrentTasksBeforeNextBatchbooleanNoIf true, tasks run in batches of runMaxTasksConcurrently: the next batch starts only when every task of the current batch has finished. Otherwise a new task starts as soon as any running task finishes.
runMaxTasksWithinTimeframe{ numberOfTasks: number; numberOfSeconds: number }NoStarts at most numberOfTasks tasks within each window of numberOfSeconds seconds. The first window begins with the call; the next begins when the previous one ends.
dontThrowOnErrorbooleanNoIf true, a failing task gives null in the results and the other tasks continue. Otherwise the first failure rejects the returned promise and no further tasks are started; tasks already running are not stopped.
// orderIds: number[]
const responses = await Sys.RateLimiting.executeTasks(
orderIds.map((id) => () => Sys.HttpClient.get(`https://api.example.com/orders/${id}`)),
{
runMaxTasksConcurrently: 5,
runMaxTasksWithinTimeframe: { numberOfTasks: 100, numberOfSeconds: 60 },
dontThrowOnError: true,
},
)

Returns: Promise<(Awaited<T> | null)[]> · Availability: Everywhere

Note

The type check always selects the first signature, so the result type includes null even without dontThrowOnError. With an empty tasks list or runMaxTasksConcurrently: 0, the returned promise never settles. Lowgile writes the default for runMaxTasksConcurrently into the options object you pass.