Merge pull request #1 from StatelessStudio/v1.0.0

V1.0.0

Author: DrewImm

CHANGELOG.md

@@ -1 +1,5 @@
 # ts-task-queue
+
+## [1.0.0]
+
+Initial Release

README.md

@@ -1 +1,153 @@
 # ts-task-queue
+
+Create & queue tasks on a pool of workers.
+
+## Installation
+
+`npm i ts-task-queue`
+
+## Usage
+
+In this example, we'll create a queue that will add two numbers.
+
+### 1. Declare the task interface
+
+Create a file for the queue, `src/add-queue.ts`. In this file, we'll create an interface that will be used for our task.
+
+Our add task will accept two inputs, `a` and `b`, which must both be numbers:
+
+`src/add-queue.ts`
+```typescript
+export interface AddTask {
+	a: number;
+	b: number;
+}
+```
+
+### 2. Create a queue
+
+Our task will take an `AddTask` as input, and output a number (the sum). So we'll create a queue that takes an AddTask as input and returns a number `new Queue<AddTask, number>()`.
+
+
+`src/add-queue.ts`
+```typescript
+export interface AddTask {
+	a: number;
+	b: number;
+}
+
+export const addQueue = new Queue<AddTask, number>({
+
+});
+```
+
+### 3. Setup the queue
+
+At a minimum, our queue needs a `name` and a `callback`. The name must be a unique string to identify the queue, and the callback is a function that will perform the work that this queue does. The callback must be an async function!
+
+`src/add-queue.ts`
+```typescript
+export interface AddTask {
+	a: number;
+	b: number;
+}
+
+export const addQueue = new Queue<AddTask, number>({
+	name: 'add-queue',
+	callback: async (task: AddTask) => task.a + task.b,
+});
+```
+
+### 4. Use the queue
+
+We can use `addQueue.await()` to push tasks onto the queue and get a Promise back. You most likely will want to wrap your application startup in `Queue.isMainThread()`; so you're not running application code on the worker that should only be run on the main thread:
+
+`src/index.ts`
+```typescript
+import { AddTask, addQueue } from './add-queue';
+
+if (addQueue.isMainThread()) {
+	const sum = await addQueue.await({ a: 4, b: 8 });
+
+	console.log('Sum is', sum);
+	// Sum is 12
+}
+```
+
+### 5. (Optional) Using with ts-node
+
+If you plan to run this through ts-node, you will also need to create a javascript entry-point for the workers:
+
+`./index.js`
+```javascript
+/**
+ * This file boots the worker in dev when the project is run through ts-node.
+ *  - This file is not included in the build.
+ */
+if (!process.execArgv.includes('ts-node/register')) {
+    require('ts-node').register();
+}
+
+const path = require('path');
+require(path.resolve(__dirname, './src/index.ts'));
+```
+
+### 6. Using multiple queues
+
+To run different tasks on multiple queues, you can repeat steps 1-4 to create additional queues. Just make sure the name is unique!
+
+`src/subtract-queue.ts`
+```typescript
+
+export interface SubtractTask {
+	a: number;
+	b: number;
+};
+
+export subtractQueue = new Queue<SubtractTask, number>({
+	name: 'subtract-queue',
+	callback: async (task: SubtractTask) => task.a - task.b,
+});
+```
+
+`src/index.ts`
+```typescript
+import { AddTask, addQueue } from './add-queue';
+import { SubtractTask, subtractQueue } from './subtract-queue';
+
+if (addQueue.isMainThread()) {
+	const sum = await addQueue.await({ a: 4, b: 8 });
+	console.log('Sum is', sum);
+	// Sum is 12
+}
+
+if (subtractQueue.isMainThread()) {
+	const diff = await subtractQueue.await({ a: 6, b: 4 });
+	console.log('Difference is', diff);
+	// Difference is 2
+}
+```
+
+## Customizing the Queue
+
+Use the following options to customize the queue:
+
+### workerEntry
+
+Specify a different file to load the workers. Default is index.js or the main file from package.json
+
+### nWorkers
+
+Number of workers pooled for the queue. Default is 4
+
+### startup
+
+Run a function on worker startup, e.g. establish database connection
+
+### error
+
+Specify an error-handler function. Default logs to stderr
+
+### fatal
+
+Specify a fatal error-handler function. Default logs to stderr and exits

example/fibonacci.ts

@@ -0,0 +1,15 @@
+export function fibonacci(num: number): number {
+	if (num <= 1) {
+		return num;
+	}
+
+	return fibonacci(num - 1) + fibonacci(num - 2);
+}
+
+export function timeFibonacci(num: number): number {
+	const start = Date.now();
+
+	fibonacci(num);
+
+	return Date.now() - start;
+}

example/index.js

@@ -0,0 +1,10 @@
+/**
+ * This file boots the worker in dev when the project is run through ts-node.
+ *  - This file is not included in the build.
+ */
+if (!process.execArgv.includes('ts-node/register')) {
+    require('ts-node').register();
+}
+
+const path = require('path');
+require(path.resolve(__dirname, './index.ts'));

example/index.ts

@@ -0,0 +1,33 @@
+import { timeFibonacci } from './fibonacci';
+import { log } from './log';
+import { fibonacciQueue } from './queue';
+
+if (fibonacciQueue.isMainThread()) {
+	log.info('Starting main thread...');
+
+	const n = 30;
+
+	// Run a single fib on the main thread as a control
+	log.info('main thread took', timeFibonacci(n));
+
+	const start = Date.now();
+
+	const p1 = fibonacciQueue.await(n)
+		.then((res: number) => log.info('First worker complete in (ms)', res))
+		.catch(log.error);
+
+	const p2 = fibonacciQueue.await(n)
+		.then((res: number) => log.info('Second worker complete in (ms)', res))
+		.catch(log.error);
+
+	const p3 = fibonacciQueue.await(n)
+		.then((res: number) => log.info('Third worker complete in (ms)', res))
+		.catch(log.error);
+
+	Promise.all([p1, p2, p3])
+		.then(() => {
+			const time = Date.now() - start;
+			log.info('All took (ms) ' + time);
+		})
+		.catch(log.error);
+}

example/log.ts

@@ -0,0 +1,3 @@
+import { Log } from 'ts-tiny-log';
+
+export const log = new Log();

example/queue.ts

@@ -0,0 +1,13 @@
+import { Queue } from '../src';
+import { log } from './log';
+import { timeFibonacci } from './fibonacci';
+
+/**
+ * Worker threads
+ */
+export const fibonacciQueue = new Queue<number, number>({
+	name: 'fibonacci',
+	workerEntry: __dirname,
+	nWorkers: 4,
+	callback: async (num) => timeFibonacci(num),
+});