A Flatfile plugin that streamlines the handling of asynchronous Jobs by managing their lifecycle, progress reporting, and completion status.
job:ready
event and executes a custom handler function when a matching job is triggered.
Its main purpose is to provide a structured way to manage the lifecycle of a job. It automatically acknowledges the job upon receipt, provides a tick
function to report progress back to the user, and handles the final completion or failure status. This is useful for any long-running process initiated within Flatfile, allowing developers to focus on the business logic of the task while the plugin manages the communication with the Flatfile API.
string | EventFilter
Function
event
object and a tick
function as arguments. Throwing an error within this function will cause the job to fail. If it completes successfully, it can optionally return a JobCompleteDetails
object to customize the outcome message.boolean
false
job:ready
event. When triggered, it immediately acknowledges the job with the Flatfile API, setting its status to “Accepted” and progress to 0%. It then executes the user-provided handler
. If the handler completes without returning a value, the plugin marks the job as complete with a default message “Job complete”. If the handler throws an error, the plugin catches it and marks the job as failed, using the error message as the reason.
debug
option. Setting opts.debug = true
when calling jobHandler
will enable verbose logging from the plugin, showing when a job is received and when it is completed. Fatal errors are logged using console.error
, which can be monitored in your server logs.
@flatfile/listener
package. It relies on the Flatfile API to update job statuses, so proper API keys and permissions are required for the environment where the listener is running.
handler
function in a try...catch
block if you need to perform cleanup actions, or to simply throw
an error to immediately fail the job. The plugin automatically handles the API call to api.jobs.fail()
when an unhandled exception is thrown from the handler
.
jobHandler
function returns a plugin function to be passed to listener.use()
handler
function can return either void
or a Flatfile.JobCompleteDetails
objectvoid
is returned, the job is completed with a default success messageJobCompleteDetails
object is returned, it is used to set a custom outcome for the completed jobtick
function returns a Promise<Flatfile.JobResponse>
which can be awaited but is not required