first commit

.github/workflows/deploy.yml

@@ -0,0 +1,32 @@
+name: Deploy
+
+on:
+    pull_request:
+        types: [closed]
+        branches:
+            - release
+
+jobs:
+    build:
+        if: github.event.pull_request.merged
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  # The branch, tag or SHA to checkout. When checking out the repository that
+                  # triggered a workflow, this defaults to the reference or SHA for that event.
+                  # Otherwise, defaults to `master`.
+                  ref: "dev"
+            - name: npm install
+              run: |
+                  cd $GITHUB_WORKSPACE
+                  npm i
+            - name: build package
+              run: |
+                  cd $GITHUB_WORKSPACE
+                  npm run build
+            - name: publish to npm
+              uses: JS-DevTools/npm-publish@v1
+              with:
+                  token: ${{ secrets.NPM_TOKEN }}
+                  package: ./package.json

.github/workflows/main.yml

@@ -0,0 +1,31 @@
+name: CI/CD
+# Controls when the action will run.
+on: push
+# workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+    test:
+        # The type of runner that the job will run on
+        runs-on: ubuntu-latest
+        steps:
+            # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+            - uses: actions/checkout@v4
+            # runs npm i inside the root directory
+            - name: npm i root
+              run: |
+                  cd $GITHUB_WORKSPACE
+                  npm i
+            # builds the library
+            - name: build package
+              run: |
+                  cd $GITHUB_WORKSPACE
+                  npm run build
+            # runs linting
+            - name: Lint
+              run: |
+                  cd $GITHUB_WORKSPACE
+                  npm run lint
+            # runs tests
+            - name: Test
+              run: |
+                  cd $GITHUB_WORKSPACE
+                  npm run test

.gitignore

@@ -0,0 +1,67 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# Transpiled JavaScript files from Typescript
+/dist
+
+# Cache used by TypeScript's incremental build
+*.tsbuildinfo
+
+# Emacs auto-save file
+\#*#

.mocharc.json

@@ -0,0 +1,5 @@
+{
+    "exit": true,
+    "recursive": true,
+    "require": "source-map-support/register"
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "yaml.schemas": {
+        "https://json.schemastore.org/github-workflow.json": "file:///home/timf/Documents/Programmierung/Open-Source/lbx-multithreading/.github/workflows/deploy.yml"
+    }
+}

.yo-rc.json

@@ -0,0 +1,6 @@
+{
+    "@loopback/cli": {
+        "packageManager": "npm",
+        "version": "6.0.2"
+    }
+}

DEVELOPING.md

@@ -0,0 +1,36 @@
+# Developer's Guide
+
+We use Visual Studio Code for developing LoopBack and recommend the same to our
+users.
+
+## VSCode setup
+
+Install the following extensions:
+
+ - [eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+ - [prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+
+## Development workflow
+
+### Visual Studio Code
+
+1. Start the build task (Cmd+Shift+B) to run TypeScript compiler in the
+   background, watching and recompiling files as you change them. Compilation
+   errors will be shown in the VSCode's "PROBLEMS" window.
+
+2. Execute "Run Rest Task" from the Command Palette (Cmd+Shift+P) to re-run the
+   test suite and lint the code for both programming and style errors. Linting
+   errors will be shown in VSCode's "PROBLEMS" window. Failed tests are printed
+   to terminal output only.
+
+### Other editors/IDEs
+
+1. Open a new terminal window/tab and start the continuous build process via
+   `npm run build:watch`. It will run TypeScript compiler in watch mode,
+   recompiling files as you change them. Any compilation errors will be printed
+   to the terminal.
+
+2. In your main terminal window/tab, run `npm run test:dev` to re-run the test
+   suite and lint the code for both programming and style errors. You should run
+   this command manually whenever you have new changes to test. Test failures
+   and linter errors will be printed to the terminal.

README.md

@@ -0,0 +1,183 @@
+# lbx-multithreading
+This packages aims to take care of most of your multi threading concerns, including:
+- a reusable worker pool that is automatically sized based on the available threads (can be [configured](#optional-configuration))
+- support for typescript out of the box
+- a way to run worker files, being really close to the original implementation
+- a simple way to run a function in a separate thread
+- storing data about your thread jobs like status, error etc. inside the database
+- utility functions to easily update the progress, status, error or result of the job
+- configurable timeouts for jobs and self healing capabilities of the worker pool
+
+This library was built with customization in mind, so most things can easily be modified.
+
+# Usage
+## Register the component
+The minimum required code changes to use the library to its full extend is simply registering it in the `application.ts`:
+```typescript
+import { LbxMultithreadingComponent, ThreadJobEntityRepository } from 'lbx-multithreading';
+
+export class MyApplication extends BootMixin(ServiceMixin(RepositoryMixin(RestApplication))) {
+    constructor(options: ApplicationConfig = {}) {
+        // ...
+        this.component(LbxMultithreadingComponent);
+        this.repository(ThreadJobEntityRepository);
+        // ...
+    }
+}
+```
+
+### (optional) Configuration
+Below you can see the bindings of the library that you can override:
+```ts
+/* eslint-disable jsdoc/require-jsdoc */
+import { BindingKey, CoreBindings } from '@loopback/core';
+
+import { LbxMultithreadingComponent } from './component';
+import { ThreadJobService } from './services';
+
+/**
+ * Binding keys used by the lbx-multithreading library.
+ */
+// eslint-disable-next-line typescript/no-namespace
+export namespace LbxMultithreadingBindings {
+    export const COMPONENT: BindingKey<LbxMultithreadingComponent> = BindingKey.create(
+        `${CoreBindings.COMPONENTS}.LbxMultithreadingComponent`
+    );
+    /**
+     * The key of the datasource.
+     */
+    export const DATASOURCE_KEY: string = 'datasources.db';
+    /**
+     * The key of the repository responsible for the thread job entities.
+     */
+    export const THREAD_JOB_ENTITY_REPOSITORY: string = 'repositories.ThreadJobEntityRepository';
+    /**
+     * The key of the service responsible for handling thread jobs.
+     */
+    export const THREAD_JOB_SERVICE: BindingKey<ThreadJobService> = BindingKey.create(`${COMPONENT}.threadJobService`);
+    /**
+     * The number of threads that can be used.
+     * Please notice that there is also **MAX_PRIORITY_THREADS** for the number of threads that should be reserved for priority jobs.
+     * Both these values added up need to be smaller than your current machines available threads.
+     * @default os.availableParallelism() - 1 (the -1 is reserved for a priority thread)
+     */
+    export const MAX_THREADS: BindingKey<number> = BindingKey.create(`${COMPONENT}.maxThreads`);
+    /**
+     * The number of threads that can be used by priority jobs.
+     * Please notice that there is also **MAX_THREADS** for the number of threads that can be used by normal and priority jobs.
+     * Both these values added up need to be smaller than your current machines available threads.
+     * @default 1
+     */
+    export const MAX_PRIORITY_THREADS: BindingKey<number> = BindingKey.create(`${COMPONENT}.maxPriorityThreads`);
+}
+```
+
+### Wait for service startup
+At startup, the service initiates a worker pool. This will only take a few seconds and is most likely not a concern for you.
+
+But if you want to use the threadJobService directly at startup, you should probably use `waitForInitialization` method to make sure everything is ready.
+
+## Queue and run a thread job
+If you have some more complex tasks where you also want to be able to report progress during runtime you will probably queue a thread job.
+
+There are 3 methods provided by the thread job service for that:
+- queueThreadJob
+- waitForThreadJob
+- runThreadJob (a combination of the two methods above)
+
+To queue/run a thread job you need to provide some thread job data:
+
+```ts
+const jobId: string = await this.threadJobService.queueThreadJob({
+    workerData: {
+        filePath: './fibonacci.worker.ts', // .ts and .js both work
+        startValue: 20
+    }
+});
+// const threadJobEntity = await this.threadJobService.waitForThreadJob(jobId);
+```
+
+Let's take a look at the worker file under `fibonacci.worker.ts`:
+
+### Worker file definition
+
+The provided worker file needs to work a bit different than a normal one:
+
+```ts
+/* eslint-disable jsdoc/require-jsdoc */
+import { parentPort, workerData as nodeWorkerData } from 'node:worker_threads';
+
+import { BaseWorkerData, reportCompletion, reportError } from 'lbx-multithreading';
+
+type FibonacciWorkerData = BaseWorkerData & {
+    startValue: number
+};
+
+const workerData: FibonacciWorkerData | undefined = nodeWorkerData as FibonacciWorkerData | undefined;
+
+if (!workerData) {
+    //@ts-ignore-next-line
+    return;
+}
+
+function fibonacci(n: number): number {
+    if (n <= 1) {
+        return n;
+    }
+    return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+try {
+    const res: number = fibonacci(workerData.startValue);
+    reportCompletion(res);
+}
+catch (error) {
+    reportError(error as Error);
+}
+```
+
+The `reportCompletion` and `reportError` parts are really important, as the thread job would run into a timeout without them.
+
+If you have a long running thread job where you want to know about the progress, you can also use the `reportProgress(percentNumber)` to do that.
+<br>
+Please note that this will result in a job completion when you report 100, so be sure that you round down this value if you set it dynamically.
+
+## Run a simple function
+
+You can run simple functions on a separate thread by using the `run` method of the `ThreadJobService`.
+<br>
+This returns the result of the function call or rejects with an error.
+
+> **Restrictions**
+> - It is expected that only known and trusted functions are passed to this method, as `eval` is used under the hood
+> -  Imports won't be resolved when the code is executed on the thread, which means that your function should only use things that are globally available (eg. console.log) or passed via the second argument
+> -  The run will not be stored inside a database, and the utility functions like `reportProgress` will not work
+
+By default this is also run with priority. This is because the execution time will probably be not that long. (Because you can await the result.)
+<br>
+You can however also add a fourth parameter to define whether or not it should run with priority.
+
+```ts
+import { service } from '@loopback/core';
+
+function fibonacci(n: number): number {
+    if (n <= 1) {
+        return n;
+    }
+    return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+//...
+export class MyClass {
+    constructor(
+        @service(ThreadJobService)
+        private readonly threadJobService: ThreadJobService
+    ) {}
+
+    runFibonacci(): number {
+        const res: number = await this.threadJobService.run(fibonacci, 20);
+        return res;
+    }
+}
+//...
+```

eslint.config.js

@@ -0,0 +1,8 @@
+config = require('eslint-config-service-soft');
+
+module.exports = [
+    ...config,
+    {
+        ignores: ['showcase']
+    }
+];