fast-worker/README.md

Module for executing heavy tasks in parallel, by providing a `Promise` based interface, minimum overhead, and bound workers.

[npm]: https://img.shields.io/npm/v/fast-worker
[npm-url]: https://www.npmjs.com/package/fast-worker
[size]: https://packagephobia.now.sh/badge?p=fast-worker
[size-url]: https://packagephobia.now.sh/result?p=fast-worker

# fast-worker

[![npm][npm]][npm-url]
[![size][size]][size-url]

- Module for executing heavy tasks in parallel, by providing a `Promise` based interface, minimum overhead, and bound workers.

`fast-worker` uses a unified, efficient and scalable thread-pool internally, makes full use of system resources, and reduces unnecessary memory consumption and complex configuration. Multiple `fast-worker` instances use the same thread-pool in the same process.
You can use this worker by making similar simple calls to the target module.

## Features

- 🤭 Supports for functions to be passed to workers as arguments. (which will be converted to asynchronous functions)
- 🤟 Supports es-modules.
- ⚡️ Unified and flexible thread-pool manager.
- ✨ `Typescript` supports.
- 💚 Automatically releases unreferenced `fast-worker` instances. (Node.js >= 14.6.0)

## Install

### npm

```
$ npm install fast-worker --save-dev
```

### Yarn

```
$ yarn add fast-worker --dev
```

### pnpm

```
$ pnpm add fast-worker --save-dev
```

## Usage

This example covers the minimal usage:

#### File `worker.ts`

```ts
export function hello(param) {
  return `Hello, ${param}`
}

export async function workerCall(fn, ...args) {
  return `result: ${await fn(...args)}`
}

// private
export function _privateMethod() {
  return `I am a private method`
}
```

#### File `main.ts`

```ts
import { createFastWorker } from 'fast-worker'
import { fileURLToPath } from 'url'
import { dirname, join } from 'path'

const _dirname = dirname(fileURLToPath(import.meta.url))
const _targetModulePath = join(_dirname, './worker')

async function main() {
  // create fast-worker instance
  const worker = createFastWorker<typeof import('./worker')>(_targetModulePath, {
    /* FastWorkerOptions */
  })

  // invoke `hello` method.
  console.log(await worker.hello('Jock'))  // Hello, Jock

  // invoke `workerCall` method.
  console.log(await worker.workerCall((a, b) => a * b, 30, 50)) // result: 1500

  // Methods that begin with '_' are marked as private and not directly accessible.
  // console.log(await worker._privateMethod()) // Error!

  // dispose `fast-worker`.
  worker.dispose()
}

main()
```

## Options

```ts
interface FastWorkerOptions<Module extends Record<keyof any, any>> {
  /**
   * Maximum number of times to re execute when execution fails.
   * @default 0
   */
  maxRetries?: number
  /**
   * By default, the 'fast worker' task can be handed over to the main thread or the worker thread for execution.
   * Enable this option will force the task to be handed over to the worker thread for execution.
   *
   * Please set this to True if you are using es-module.
   */
  onlyExecInWorker?: boolean
  /**
   * Sets the timeout period to throw an exception if the task is not completed within the specified time.
   * @default 5000
   */
  timeout?: number | null
  /**
   * Set the retry interval.
   * @default 0
   */
  retryInterval?: number
  /**
   * init (NEW)
   */
  onInit?: (this: Omit<FastWorker<Module>, 'dispose' | 'disposed'>) => void
}
```

## Give a ⭐️ if this project helped you!

## License

[MIT](./LICENSE) License © 2022 xxXyh1908