# simplythread

> JS Threads: Run arbitrary functions in immediatly-spawned browser threads with an async workflow

Latest version **2.0.4** (published 2016-12-21) · ISC license · 0 weekly downloads

## Install

```sh
npm install simplythread
pnpm add simplythread
yarn add simplythread
bun add simplythread
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.4 |
| Published | 2016-12-21 |
| First published | 2016-12-20 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Daniel Kalen |
| Maintainers | danielkalen |
| Keywords | thread, threads, threading, multi, multi-threading, parallel, spawn, cluster, worker, async |

## Links

- npm: https://www.npmjs.com/package/simplythread
- Repository: https://github.com/danielkalen/simplythread
- Homepage: https://github.com/danielkalen/simplythread#readme
- Issues: https://github.com/danielkalen/simplythread/issues
- npm.io page: https://npm.io/package/simplythread

## Dependencies (1)

- [javascript-stringify-plus](https://npm.io/package/javascript-stringify-plus.md) ^1.6.0

## Alternatives

- [cron](https://npm.io/package/cron.md) — 4.9M weekly downloads
- [@vercel/queue](https://npm.io/package/@vercel/queue.md) — 731.6K weekly downloads
- [create-sonicjs](https://npm.io/package/create-sonicjs.md) — 1.6K weekly downloads
- [@exellix/jobs-api](https://npm.io/package/@exellix/jobs-api.md) — 941 weekly downloads
- [@forwardimpact/libskill](https://npm.io/package/@forwardimpact/libskill.md) — 575 weekly downloads

## Recent versions

- 2.0.4 (latest) — 2016-12-21
- 2.0.0 — 2016-12-20

## README

# SimplyThread
[![Build Status](https://travis-ci.org/danielkalen/simplythread.svg?branch=master)](https://travis-ci.org/danielkalen/simplythread)
[![Coverage](.config/badges/coverage.png?raw=true)](https://github.com/danielkalen/simplythread)
[![Code Climate](https://codeclimate.com/github/danielkalen/simplythread/badges/gpa.svg)](https://codeclimate.com/github/danielkalen/simplythread)

[![Sauce Test Status](https://saucelabs.com/browser-matrix/simplythread.svg)](https://saucelabs.com/u/simplythread)


Execute arbitrary functions in immediatly-spawned browser threads with an async Promise workflow. Relies on worker technology for threads and uses fallback methods for unsupported browsers.

## Installation
`npm install simplythread --save`

#### Require (commonJS)
```javascript
var SimplyThread = require('simplythread');
```

#### `<script>` tag
```html
<script src="node_modules/simplythread/dist/simplythread.js"></script>
```



## Example Usage
```javascript
var thread = SimplyThread.create(function(a,b){
    return a+b;
});

thread.run(5, 10).then(function(result){ // Returns a promise
    console.log(result); // logs 15;
});



thread.setFn(function(a,b){ // Set a new function for the thread
    return (a+b)*b;
});

thread.run(5, 10).then(function(result){
    console.log(result); // logs 150;
});

thread.kill(); // Destroy thread.
```


## API
### `SimplyThread.create([function])`
Creates a new browser thread and returns a thread interface instance.

Arguments:
  - `function` (optional) - The function to set as the thread's main function that will be executed when calling `thread.run()`.


### `SimplyThread.list()`
Returns an array listing all active threads.


### `SimplyThread.killAll()`
Convinence method that kills all active threads.


### `thread.run([arg1[, arg2[, ...]]])`
Execute the function provided to the thread (either through `SimplyThread.create(fn)` or `thread.setFn(fn)`) with the provided arguments. Returns a promise which will either resolve with the result or reject upon error. If a function wasn't provided during thread creation or wasn't later set via thread.setFn the returned promise will be immediatly rejected.


### `thread.on(eventName, callback)`
Registers the provided callback to be invoked when `threadEmit(eventName)` is called from inside the thread's main function.

Example:
```javascript
var thread = SimplyThread.create(function(number){
    setTimeout(function(){
        threadEmit('myEvent', number*10);

        setTimeout(function(){
            threadEmit('myEvent', number*100);
        }, 50);
    }, 100);
});
thread.on('myEvent', (payload)=> console.log(payload)) // Logs '50' after 100ms, '500' after 150ms
thread.run(5);
```

Arguments:
  - `eventName` - the name of the event to register the callback with.
  - `callback` - the callback to invoke with the payload when `threadEmit(eventName)` is invoked from the thread.


### `thread.setFn(function[, context])`
Sets the provided function as the main function that will be executed when invoking thread.run().

Arguments:
  - `function` - the function to set as the thread's main function.
  - `context` (optional) - an object which will be the context that the provided function will run under (i.e. the value of `this` in the function body).


### `thread.setContext(context)`
Assigns the provided context as the thread's function's `this` value.

Arguments:
  - `context` - an object which will be the context that the thread's function will run under (i.e. the value of `this` in the function body).


### `thread.setScripts(scriptsArray)`
Loads each external script provided in the `scriptsArray` on the thread's global scope. The scripts will be loaded asynchronously and the thread will wait for all scripts to be loaded before running any following .run() calls. If one of the scripts fail to load (i.e. they have a status code >= 400), any following .run() calls will be immediatly rejected with the script load error.

Example:
```javascript
var thread = SimplyThread.create();
thread.setScripts(['https://code.jquery.com/jquery-3.1.1.js', 'MODULE:lodash']); // jQuery and Lodash will now be available on the thread's global scope.

thread.setScripts([function(){
    self.globalVariable = 'abc123';
}]) // globalVariable will now be available on the thread's global scope.
```

Arguments:
  - `scriptsArray` - array of scripts that the thread should attempt to load under its global scope. Possible values for scripts:
      - *URL path* - absolute path of a javascript file.
      - *Module path* - a string representing the name of an NPM package that'll be loaded via [Browserify](http://wzrd.in), preceded by a 'MODULE:' prefix. By default a module will be loaded on the thread's global scope under the package's name, but a custom name can be specified via 'MODULE:packageName#customName' syntax e.g. 'MODULE:lodash#_'.
      - *Function* - A function that'll be run on the thread's global scope (i.e. the `this` keyword will resolve to the thread's global scope). If the function returns a promise, the thread will await until it is resolved before running any .run() calls.


### `thread.setGlobals(object)`
Sets/assigns each key:value from the provided object on the thread's global scope.

Example:
```javascript
var thread = SimplyThread.create(function(){
    return typeof myVariable;
});

thread.run().then(function(result){ console.log(result);}) // Logs 'undefined'

thread.setGlobals({myVariable: 'someValue'});
thread.run().then(function(result){ console.log(result);}) // Logs 'string'
```

Arguments:
  - `object` - an object containing key:value pairs which will be set on the thread's global scope. The key will represent the name of the global variable that'll be assigned to its associated value.


### `thread.kill()`
Destroys the thread and its interface if it hasn't already been destroyed.



## Things to consider
You should generally delegate heavy/expensive computations to threads and avoid running tiny computations because transferring data between threads also takes a certain amount of time (depending on what you are transferring).

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