# @flatfile/plugin-job-handler

> A plugin for handling Flatfile Jobs.

Latest version **0.8.1** (published 2024-12-19) · ISC license · 0 weekly downloads

## Install

```sh
npm install @flatfile/plugin-job-handler
pnpm add @flatfile/plugin-job-handler
yarn add @flatfile/plugin-job-handler
bun add @flatfile/plugin-job-handler
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.8.1 |
| Published | 2024-12-19 |
| First published | 2023-08-30 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 18 |
| Dependencies | 1 |
| Unpacked size | 27.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Flatfile, Inc. |
| Maintainers | sarocu, dboskovic, nate.ferrero, jmmander, madmandrit, bangarang, carlbrugger, flatfileinfra, flatderek, bigcountrycrane, flatfilecolin, alnoor, rjhyde, sambarrowclough, meritmalling, mmccooyyy |
| Keywords | flatfile-plugins, category-core |

## Links

- npm: https://www.npmjs.com/package/@flatfile/plugin-job-handler
- Repository: https://github.com/FlatFilers/flatfile-plugins
- Homepage: https://github.com/FlatFilers/flatfile-plugins#readme
- Issues: https://github.com/FlatFilers/flatfile-plugins/issues
- npm.io page: https://npm.io/package/@flatfile/plugin-job-handler

## Dependencies (1)

- [@flatfile/util-common](https://npm.io/package/@flatfile/util-common.md) ^1.6.0

## Recent versions

- 0.8.1 (latest) — 2024-12-19
- 0.8.0 — 2024-11-07
- 0.7.0 — 2024-10-29
- 0.6.1 — 2024-10-03
- 0.6.0 — 2024-09-24
- 0.5.5 — 2024-09-03
- 0.5.4 — 2024-05-29
- 0.5.3 — 2024-05-28
- 0.5.2 — 2024-05-20
- 0.5.1 — 2024-04-30
- 0.5.0 — 2024-04-23
- 0.4.3 — 2024-04-11
- 0.4.2 — 2024-04-08
- 0.4.1 — 2024-03-29
- 0.4.0 — 2024-03-25
- … 14 more at https://npm.io/package/@flatfile/plugin-job-handler/versions

## README

<!-- START_INFOCARD -->

The `@flatfile/plugin-job-handler` package is a plugin designed to streamline handling Flatfile Jobs, which are a large unit of work performed asynchronously on a resource such as a file, Workbook, or Sheet.

**Event Type:**
`listener.on('job:ready')`

<!-- END_INFOCARD -->

## Parameters

#### `job` - `string` - (required)

The `job` parameter is applied as a filter when listening for `job:ready`.


#### `handler` - `function` - (required)

The `handler` parameter is a callback where you execute your code. It accepts two arguments: `event` and `tick`.

- `event`: Represents the `FlatfileEvent`, giving context to the handler.
- `tick`: A function that can be used to update Job progress. It accepts two parameters:
  - `progress`: A number between 0 and 100 indicating the progress percentage.
  - `message`: An optional descriptive string.

Invoking the `tick` function returns a promise that resolves to a JobResponse object. However, using the `tick` function is optional.


#### `opts.debug` - `boolean` - `default: false`

The `debug` parameter is used to enable debug logging for the plugin.



## Usage

The `jobHandler` plugin manages Flatfile Jobs. It listens for the `job:ready` event and screens it based on the `job` parameter.

When a `job:ready` event occurs:

- The `handler` callback is triggered with the `FlatfileEvent` and an optional `tick` function.
- This `tick` function, if used, updates the Job's progress.
- The `handler` may yield a promise that culminates in a `JobResponse` object, allowing for a customized successful Job status.

#### Install

```bash install
npm i @flatfile/plugin-job-handler
```

#### Import

```js import
import { jobHandler } from "@flatfile/plugin-job-handler";
```

Replace `"domain:operation"` with the domain and operation you want to listen for.


#### `listener.js`

```js listener.js
listener.use(
  jobHandler("domain:operation", async (event, tick) => {
    try {
      // your code here...
      await tick(50, "Halfway there!"); // update Job progress
      // ...continue your code...
      await tick(75, "Three quarters there!"); // update Job progress
      // ...continue your code...
      return {
        outcome: {
          message: "Job complete",
        },
      };
    } catch (error) {
      throw error; // will fail the Job
    }
  })
);
```

---
_Source: https://npm.io/package/@flatfile/plugin-job-handler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._