@xylabs/threads 3.0.4

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog - threads.js
+
+## v1.0
+
+For newer versions of `threads`, visit the [releases page](https://github.com/andywer/threads.js/releases) on GitHub.
+
+You will find a description of each release's changes there.
+
+## v0.x
+
+For old versions of `threads`, see the [CHANGELOG.md on the `v0` branch](https://github.com/andywer/threads.js/blob/v0/CHANGELOG.md).

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Andy Wermke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+<h1 align="center">
+  <img alt="threads.js" src="./docs/assets/logo-label.png" width="75%" />
+</h1>
+<p align="center">
+  <a href="https://travis-ci.org/andywer/threads.js" target="_blank"><img alt="Build status" src="https://img.shields.io/travis/andywer/threads.js/v1.svg?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/threads" target="_blank"><img alt="npm (tag)" src="https://img.shields.io/npm/v/threads.svg?style=flat-square"></a>
+  <a href="https://gitter.im/threadsjs/community" target="_blank"><img alt="Chat room" src="https://img.shields.io/badge/chat-gitter.im-orange" /></a>
+</p>
+
+<br />
+
+Offload CPU-intensive tasks to worker threads in node.js, web browsers and electron using one uniform API.
+
+Uses web workers in the browser, `worker_threads` in node 12+ and [`tiny-worker`](https://github.com/avoidwork/tiny-worker) in node 8 to 11.
+
+### Features
+
+* First-class support for **async functions** & **observables**
+* Write code once, run it **on all platforms**
+* Manage bulk task executions with **thread pools**
+* Use **require()** and **import**/**export** in workers
+* Works great with **webpack**
+
+### Version 0.x
+
+You can find the old version 0.12 of threads.js on the [`v0` branch](https://github.com/andywer/threads.js/tree/v0). All the content on this page refers to version 1.0 which is a rewrite of the library with a whole new API.
+
+## Installation
+
+```
+npm install threads tiny-worker
+```
+
+*You only need to install the `tiny-worker` package to support node.js < 12. It's an optional dependency and used as a fallback if `worker_threads` are not available.*
+
+## Platform support
+
+<details>
+<summary>Run on node.js</summary>
+
+<p></p>
+
+Running code using threads.js in node works out of the box.
+
+Note that we wrap the native `Worker`, so `new Worker("./foo/bar")` will resolve the path relative to the module that calls it, not relative to the current working directory.
+
+That aligns it with the behavior when bundling the code with webpack or parcel.
+
+</details>
+
+<details>
+<summary>Webpack build setup</summary>
+
+#### Webpack config
+
+Use with the [`threads-plugin`](https://github.com/andywer/threads-plugin). It will transparently detect all `new Worker("./unbundled-path")` expressions, bundles the worker code and replaces the `new Worker(...)` path with the worker bundle path, so you don't need to explicitly use the `worker-loader` or define extra entry points.
+
+```sh
+  npm install -D threads-plugin
+```
+
+Then add it to your `webpack.config.js`:
+
+```diff
++ const ThreadsPlugin = require('threads-plugin');
+
+  module.exports = {
+    // ...
+    plugins: [
++     new ThreadsPlugin()
+    ]
+    // ...
+  }
+```
+
+#### Node.js bundles
+
+If you are using webpack to create a bundle that will be run in node (webpack config `target: "node"`), you also need to specify that the `tiny-worker` package used for node < 12 should not be bundled:
+
+```diff
+  module.exports = {
+    // ...
++   externals: {
++     "tiny-worker": "tiny-worker"
++   }
+    // ...
+}
+```
+
+Make sure that `tiny-worker` is listed in your `package.json` `dependencies` in that case.
+
+#### When using TypeScript
+
+Note: You'll need to be using Typescript version 4+, as the types generated by threads.js are not supported in Typescript 3.
+
+Make sure the TypeScript compiler keeps the `import` / `export` statements intact, so webpack resolves them. Otherwise the `threads-plugin` won't be able to do its job.
+
+```diff
+  module.exports = {
+    // ...
+    module: {
+      rules: [
+        {
+          test: /\.ts$/,
+          loader: "ts-loader",
++         options: {
++           compilerOptions: {
++             module: "esnext"
++           }
++         }
+        }
+      ]
+    },
+    // ...
+  }
+```
+
+</details>
+
+<details>
+<summary>Parcel bundler setup</summary>
+
+<p></p>
+
+You need to import `threads/register` once at the beginning of your application code (in the master code, not in the workers):
+
+```diff
+  import { spawn } from "threads"
++ import "threads/register"
+
+  // ...
+
+  const work = await spawn(new Worker("./worker"))
+```
+
+This registers the library's `Worker` implementation for your platform as the global `Worker`. This is necessary, since you cannot `import { Worker } from "threads"` or Parcel won't recognize `new Worker()` as a web worker anymore.
+
+Be aware that this might affect any code that tries to instantiate a normal web worker `Worker` and now instead instantiates a threads.js `Worker`. The threads.js `Worker` is just a web worker with some sugar on top, but that sugar might have unexpected side effects on third-party libraries.
+
+Everything else should work out of the box.
+
+</details>
+
+## Getting Started
+
+### Basics
+
+```js
+// master.js
+import { spawn, Thread, Worker } from "threads"
+
+const auth = await spawn(new Worker("./workers/auth"))
+const hashed = await auth.hashPassword("Super secret password", "1234")
+
+console.log("Hashed password:", hashed)
+
+await Thread.terminate(auth)
+```
+
+```js
+// workers/auth.js
+import sha256 from "js-sha256"
+import { expose } from "threads/worker"
+
+expose({
+  hashPassword(password, salt) {
+    return sha256(password + salt)
+  }
+})
+```
+
+### spawn()
+
+The `hashPassword()` function of the `auth` object in the master code proxies the call to the `hashPassword()` function in the worker:
+
+If the worker's function returns a promise or an observable then you can just use the return value as such in the master code. If the function returns a primitive value, expect the master function to return a promise resolving to that value.
+
+### expose()
+
+Use `expose()` to make a function or an object containing methods callable from the master thread.
+
+In case of exposing an object, `spawn()` will asynchronously return an object exposing all the object's functions. If you `expose()` a function, `spawn` will also return a callable function, not an object.
+
+## Usage
+
+<p>
+  Find the full documentation on the <a href="https://threads.js.org/" rel="nofollow">website</a>:
+</p>
+
+- [**Quick start**](https://threads.js.org/getting-started)
+- [**Basic usage**](https://threads.js.org/usage)
+- [**Using observables**](https://threads.js.org/usage-observables)
+- [**Thread pools**](https://threads.js.org/usage-pool)
+- [**Advanced**](https://threads.js.org/usage-advanced)
+
+## Webpack
+
+Threads.js works with webpack. Usually all you need to do is adding the
+[`threads-plugin`](https://github.com/andywer/threads-plugin).
+
+See [Build with webpack](https://threads.js.org/getting-started#build-with-webpack)
+on the website for details.
+
+<!--
+## API
+
+TODO
+-->
+
+## Debug
+
+We are using the [`debug`](https://github.com/visionmedia/debug) package to provide opt-in debug logging. All the package's debug messages have a scope starting with `threads:`, with different sub-scopes:
+
+- `threads:master:messages`
+- `threads:master:spawn`
+- `threads:master:thread-utils`
+- `threads:pool:${poolName || poolID}`
+
+Set it to `DEBUG=threads:*` to enable all the library's debug logging. To run its tests with full debug logging, for instance:
+
+```
+DEBUG=threads:* npm test
+```
+
+## License
+
+MIT

package/dist/common.d.ts

@@ -0,0 +1,4 @@
+import { JsonSerializable, SerializerImplementation } from './serializers';
+export declare function registerSerializer(serializer: SerializerImplementation<JsonSerializable>): void;
+export declare function deserialize(message: JsonSerializable): any;
+export declare function serialize(input: any): JsonSerializable;

package/dist/common.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serialize = exports.deserialize = exports.registerSerializer = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const serializers_1 = require("./serializers");
+let registeredSerializer = serializers_1.DefaultSerializer;
+function registerSerializer(serializer) {
+    registeredSerializer = (0, serializers_1.extendSerializer)(registeredSerializer, serializer);
+}
+exports.registerSerializer = registerSerializer;
+function deserialize(message) {
+    return registeredSerializer.deserialize(message);
+}
+exports.deserialize = deserialize;
+function serialize(input) {
+    return registeredSerializer.serialize(input);
+}
+exports.serialize = serialize;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { registerSerializer } from './common';
+export * from './master/index';
+export { QueuedTask } from './master/pool';
+export { ExposedToThreadType as ExposedAs } from './master/spawn';
+export { DefaultSerializer, JsonSerializable, Serializer, SerializerImplementation } from './serializers';
+export { Transfer, TransferDescriptor } from './transferable';
+export { expose } from './worker/index';

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expose = exports.Transfer = exports.DefaultSerializer = exports.registerSerializer = void 0;
+/* eslint-disable import/no-internal-modules */
+var common_1 = require("./common");
+Object.defineProperty(exports, "registerSerializer", { enumerable: true, get: function () { return common_1.registerSerializer; } });
+__exportStar(require("./master/index"), exports);
+var serializers_1 = require("./serializers");
+Object.defineProperty(exports, "DefaultSerializer", { enumerable: true, get: function () { return serializers_1.DefaultSerializer; } });
+var transferable_1 = require("./transferable");
+Object.defineProperty(exports, "Transfer", { enumerable: true, get: function () { return transferable_1.Transfer; } });
+var index_1 = require("./worker/index");
+Object.defineProperty(exports, "expose", { enumerable: true, get: function () { return index_1.expose; } });

package/dist/master/get-bundle-url.browser.d.ts

@@ -0,0 +1,3 @@
+declare function getBundleURLCached(): string;
+declare function getBaseURL(url: string): string;
+export { getBaseURL, getBundleURLCached as getBundleURL };

package/dist/master/get-bundle-url.browser.js

@@ -0,0 +1,29 @@
+"use strict";
+// Source: <https://github.com/parcel-bundler/parcel/blob/master/packages/core/parcel-bundler/src/builtins/bundle-url.js>
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBundleURL = exports.getBaseURL = void 0;
+let bundleURL;
+function getBundleURLCached() {
+    if (!bundleURL) {
+        bundleURL = getBundleURL();
+    }
+    return bundleURL;
+}
+exports.getBundleURL = getBundleURLCached;
+function getBundleURL() {
+    // Attempt to find the URL of the current script and use that as the base URL
+    try {
+        throw new Error('getBundleURL failed');
+    }
+    catch (err) {
+        const matches = ('' + err.stack).match(/(https?|file|ftp|chrome-extension|moz-extension):\/\/[^\n)]+/g);
+        if (matches) {
+            return getBaseURL(matches[0]);
+        }
+    }
+    return '/';
+}
+function getBaseURL(url) {
+    return ('' + url).replace(/^((?:https?|file|ftp|chrome-extension|moz-extension):\/\/.+)?\/[^/]+(?:\?.*)?$/, '$1') + '/';
+}
+exports.getBaseURL = getBaseURL;

package/dist/master/implementation.browser.d.ts

@@ -0,0 +1,4 @@
+import { ImplementationExport } from '../types/master';
+export declare const defaultPoolSize: number;
+export declare function getWorkerImplementation(): ImplementationExport;
+export declare function isWorkerRuntime(): boolean;

package/dist/master/implementation.browser.js

@@ -0,0 +1,69 @@
+"use strict";
+// tslint:disable max-classes-per-file
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWorkerRuntime = exports.getWorkerImplementation = exports.defaultPoolSize = void 0;
+const get_bundle_url_browser_1 = require("./get-bundle-url.browser");
+exports.defaultPoolSize = typeof navigator !== 'undefined' && navigator.hardwareConcurrency ? navigator.hardwareConcurrency : 4;
+const isAbsoluteURL = (value) => /^[A-Za-z][\d+.A-Za-z\-]*:/.test(value);
+function createSourceBlobURL(code) {
+    const blob = new Blob([code], { type: 'application/javascript' });
+    return URL.createObjectURL(blob);
+}
+function selectWorkerImplementation() {
+    if (typeof Worker === 'undefined') {
+        // Might happen on Safari, for instance
+        // The idea is to only fail if the constructor is actually used
+        return class NoWebWorker {
+            constructor() {
+                throw new Error("No web worker implementation available. You might have tried to spawn a worker within a worker in a browser that doesn't support workers in workers.");
+            }
+        };
+    }
+    class WebWorker extends Worker {
+        constructor(url, options) {
+            if (typeof url === 'string' && options && options._baseURL) {
+                url = new URL(url, options._baseURL);
+            }
+            else if (typeof url === 'string' && !isAbsoluteURL(url) && /^file:\/\//i.test((0, get_bundle_url_browser_1.getBundleURL)())) {
+                url = new URL(url, (0, get_bundle_url_browser_1.getBundleURL)().replace(/\/[^/]+$/, '/'));
+                if (options?.CORSWorkaround ?? true) {
+                    url = createSourceBlobURL(`importScripts(${JSON.stringify(url)});`);
+                }
+            }
+            if (typeof url === 'string' &&
+                isAbsoluteURL(url) && // Create source code blob loading JS file via `importScripts()`
+                // to circumvent worker CORS restrictions
+                (options?.CORSWorkaround ?? true)) {
+                url = createSourceBlobURL(`importScripts(${JSON.stringify(url)});`);
+            }
+            super(url, options);
+        }
+    }
+    class BlobWorker extends WebWorker {
+        constructor(blob, options) {
+            const url = window.URL.createObjectURL(blob);
+            super(url, options);
+        }
+        static fromText(source, options) {
+            const blob = new window.Blob([source], { type: 'text/javascript' });
+            return new BlobWorker(blob, options);
+        }
+    }
+    return {
+        blob: BlobWorker,
+        default: WebWorker,
+    };
+}
+let implementation;
+function getWorkerImplementation() {
+    if (!implementation) {
+        implementation = selectWorkerImplementation();
+    }
+    return implementation;
+}
+exports.getWorkerImplementation = getWorkerImplementation;
+function isWorkerRuntime() {
+    const isWindowContext = typeof self !== 'undefined' && typeof Window !== 'undefined' && self instanceof Window;
+    return typeof self !== 'undefined' && self['postMessage'] && !isWindowContext ? true : false;
+}
+exports.isWorkerRuntime = isWorkerRuntime;

package/dist/master/implementation.d.ts

@@ -0,0 +1,6 @@
+import * as BrowserImplementation from './implementation.browser';
+/** Default size of pools. Depending on the platform the value might vary from device to device. */
+export declare const defaultPoolSize: number;
+export declare const getWorkerImplementation: typeof BrowserImplementation.getWorkerImplementation;
+/** Returns `true` if this code is currently running in a worker. */
+export declare const isWorkerRuntime: typeof BrowserImplementation.isWorkerRuntime;

package/dist/master/implementation.js

@@ -0,0 +1,41 @@
+"use strict";
+/*
+ * This file is only a stub to make './implementation' resolve to the right module.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWorkerRuntime = exports.getWorkerImplementation = exports.defaultPoolSize = void 0;
+// We alias `src/master/implementation` to `src/master/implementation.browser` for web
+// browsers already in the package.json, so if get here, it's safe to pass-through the
+// node implementation
+const BrowserImplementation = __importStar(require("./implementation.browser"));
+const NodeImplementation = __importStar(require("./implementation.node"));
+const runningInNode = typeof process !== 'undefined' && process.arch !== 'browser' && 'pid' in process;
+const implementation = runningInNode ? NodeImplementation : BrowserImplementation;
+/** Default size of pools. Depending on the platform the value might vary from device to device. */
+exports.defaultPoolSize = implementation.defaultPoolSize;
+exports.getWorkerImplementation = implementation.getWorkerImplementation;
+/** Returns `true` if this code is currently running in a worker. */
+exports.isWorkerRuntime = implementation.isWorkerRuntime;

package/dist/master/implementation.node.d.ts

@@ -0,0 +1,5 @@
+/// <reference lib="dom" />
+import { ImplementationExport } from '../types/master';
+export declare const defaultPoolSize: number;
+export declare function getWorkerImplementation(): ImplementationExport;
+export declare function isWorkerRuntime(): boolean;