Rate this page:
This API enables Forge apps to push events and execute them asynchronously in the background.
To import the Forge events package and instantiate the queue in your app, run:
1 2import { Queue } from '@forge/events'; const queue = new Queue({ key: 'queue-name' });
Pushes events to the queue to be processed later. The events processing can be delayed up to 15 minutes
using the delayInSeconds
setting. A maximum of 50 events can be pushed per request, up to a maximum
combined payload of 200kb.
1 2type Payload = string | number | boolean | { [key: string]: Payload }; type PushSettings = { delayInSeconds: number } /** * @returns Id of the job created * */ await queue.push(Payload | Payload[], PushSettings)
To push event(s) to the queue:
1 2// Push a single event with string payload await queue.push('hello world'); // Push a single event with JSON payload await queue.push({ "hello": "world" }); // Push multiple events to the queue await queue.push(["hello", "world"]); // Delay the processing of the event by 5 seconds await queue.push("hello world", { delayInSeconds: 5 })
To create an event consumer module in the app manifest, use:
1 2modules: consumer: - key: queue-consumer # Name of the queue for which this consumer will be invoked queue: queue-name resolver: function: consumer-function # resolver function to be called with payload method: event-listener function: - key: consumer-function handler: consumer.handler
To create the resolver for the consumer module, use:
1 2import Resolver from "@forge/resolver"; const resolver = new Resolver(); resolver.define("event-listener", async ({ payload, context }) => { // process the event }); export const handler = resolver.getDefinitions();
When you push events to the queue, a new job is created. This job’s id
is returned from the push API. To get the job’s stats using the id
, use:
1 2// Get the job ID const jobId = await queue.push(['event1', 'event2']); // Get the JobProgress object const jobProgress = queue.getJob(jobId); // Get stats of a particular job const response = await jobProgress.getStats(); const {success, inProgress, failed} = await response.json();
Job ID is also accessible via the context
parameter of your resolver function:
1 2resolver.define("event-listener", async ({ payload, context }) => { // Get the JobProgress object const jobProgress = queue.getJob(context.jobId); });
You can cancel a job that’s in progress using its JobProgress
instance. When a job is canceled, events of that job are no longer processed.
1 2resolver.define("event-listener", async ({ payload, context }) => { // Get the JobProgress object const jobProgress = queue.getJob(context.jobId); try { // process the event } catch (error) { // You can cancel the job when an error happens await jobProgress.cancel() } });
You can retry events to handle app errors. Doing so does not create a new job. To create the retry response through the QueueResponse
API, use:
1 2import { QueueResponse } from "@forge/events" resolver.define("import-builds", async () => { const res = new QueueResponse(); try { // App logic } catch(error) { // update response to event retry res.retry(); } return res; });
Rate this page: