chore: add some basic examples

.lintstagedrc.js

@@ -2,7 +2,7 @@ module.exports = {
   '*.md,!test/**/*.md': [
     (filenames) => filenames.map((filename) => `remark ${filename} -qfo`)
   ],
-  'package.json': 'fixpack',
+  './package.json': 'fixpack',
   '*.js': 'xo --fix',
   '*.ts': 'xo --fix'
 };

examples/commonjs/README.md

@@ -0,0 +1,3 @@
+# Commonjs Example
+
+This is the most basic Bree example.

examples/commonjs/index.js

@@ -0,0 +1,7 @@
+const Bree = require('../../src/index.js');
+
+const bree = new Bree({
+  jobs: ['job']
+});
+
+bree.start();

examples/commonjs/jobs/job.js

@@ -0,0 +1,9 @@
+const { parentPort } = require('node:worker_threads');
+const process = require('node:process');
+
+console.log('Hello Commonjs!');
+
+// signal to parent that the job is done
+if (parentPort) parentPort.postMessage('done');
+// eslint-disable-next-line unicorn/no-process-exit
+else process.exit(0);

examples/commonjs/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "bree-js-example",
+  "version": "1.0.0",
+  "description": "basic bree example",
+  "main": "index.js",
+  "author": "Spencer Snyder <sasnyde2@gmail.com> (https://spencersnyder.io/)",
+  "license": "MIT"
+}

examples/esmodules/README.md

@@ -0,0 +1,7 @@
+# Working with ESModules
+
+This is the most basic Bree example.
+
+Esmodules are implemented by setting `type` to `module` in the `package.json`.
+
+No other special steps need to be taken to use `bree` with ESModule sytax.

examples/esmodules/index.js

@@ -0,0 +1,7 @@
+import Bree from '../../src/index.js';
+
+const bree = new Bree({
+  jobs: ['job']
+});
+
+bree.start();

examples/esmodules/jobs/job.js

@@ -0,0 +1,9 @@
+import { parentPort } from 'node:worker_threads';
+import process from 'node:process';
+
+console.log('Hello ESM!');
+
+// signal to parent that the job is done
+if (parentPort) parentPort.postMessage('done');
+// eslint-disable-next-line unicorn/no-process-exit
+else process.exit(0);

examples/esmodules/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "bree-js-example",
+  "version": "1.0.0",
+  "description": "basic bree example",
+  "main": "index.js",
+  "author": "Spencer Snyder <sasnyde2@gmail.com> (https://spencersnyder.io/)",
+  "license": "MIT",
+  "type": "module"
+}

examples/typescript-esm/README.md

@@ -0,0 +1,25 @@
+# Working with TypeScript
+
+This is the most basic bree example that shows a basic workflow for working with bree and typescript.
+
+## Using the root option
+
+It is generally best to set the `bree` `root` option when using any tool that may be tranpiling your code. Generally it makes the most sense to set it to `path.join(__dirname, 'jobs')`. If you are compiling to ESModules, you should set it to `path.join(path.dirname(fileURLToPath(import.meta.url)), 'jobs')` as the global `__dirname` variable will be unavailable.
+
+## Using TS Node
+
+[TS Node](https://github.com/TypeStrong/ts-node) is a project that uses hooks to compile typescript on the fly for fast and convenient TypeScript development. In order to use `bree` successfully with TS Node and to be able to write your jobs in TypeScript - one needs to run it in such a way that allows TS Node to transpile child process and worker scripts on the fly.
+
+We do this by implementing a `dev` script in our `package.json` as is outlined in the [TS Node docs.](https://github.com/TypeStrong/ts-node#other).
+
+`"dev": "TS_NODE=true NODE_OPTIONS=\"-r ts-node/register\" node ."`
+
+We further add a TS_NODE env var, as when in a TS Node environment, we need to append ts file extensions to our worker paths instead of the default JS. However, when we compile the code for production with the TypeScript compiler (running `tsc`), we need to keep the default js extensions on our worker paths.
+
+## Compiling to ESModules
+
+To compile to ESModules first set `"type": "module"` in your package.json. Ensure your compiler options are set to compile to ESModules output. After that, we need to change our `dev` script in our `package.json` so TS Node [properly compiles workers](https://github.com/TypeStrong/ts-node#other) to ESModules as well.
+
+`"dev": "TS_NODE=true NODE_OPTIONS=\"--loader ts-node/esm\" node ."`
+
+In our `tsconfig.json` we need to ensure that our `moduleResolution` is set to `node` and that `module` is set to an option that will give the output as esmodule syntax as seen in this example.

examples/typescript-esm/index.ts

@@ -0,0 +1,24 @@
+import * as path from 'node:path';
+import * as process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import Bree from 'bree';
+
+const bree = new Bree({
+  /**
+   * Always set the root option when doing any type of
+   * compiling with bree. This just makes it clearer where
+   * bree should resolve the jobs folder from. By default it
+   * resolves to the jobs folder relative to where the program
+   * is executed.
+   */
+  root: path.join(path.dirname(fileURLToPath(import.meta.url)), 'jobs'),
+  /**
+   * We only need the default extension to be "ts"
+   * when we are running the app with ts-node - otherwise
+   * the compiled-to-js code still needs to use JS
+   */
+  defaultExtension: process.env.TS_NODE ? 'ts' : 'js',
+  jobs: ['job']
+});
+
+bree.start();

examples/typescript-esm/jobs/job.ts

@@ -0,0 +1,9 @@
+import { parentPort } from 'node:worker_threads';
+import process from 'node:process';
+
+console.log('Hello TypeScript with ESM!');
+
+// signal to parent that the job is done
+if (parentPort) parentPort.postMessage('done');
+// eslint-disable-next-line unicorn/no-process-exit
+else process.exit(0);

examples/typescript-esm/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "bree-js-example",
+  "version": "1.0.0",
+  "description": "basic bree example",
+  "main": "index.ts",
+  "author": "Spencer Snyder <sasnyde2@gmail.com> (https://spencersnyder.io/)",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^16.11.7",
+    "ts-node": "^10.4.0",
+    "tslib": "^2.3.1",
+    "typescript": "^4.4.4"
+  },
+  "scripts": {
+    "dev": "TS_NODE=true NODE_OPTIONS=\"--loader ts-node/esm\" node .",
+    "start": "rm -rf dist && tsc && node dist/index.js"
+  },
+  "dependencies": {
+    "bree": "latest"
+  },
+  "type": "module"
+}

examples/typescript-esm/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@tsconfig/node16/tsconfig.json",
+  "include": ["**/*.ts"],
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "ES2020",
+    "moduleResolution": "node"
+  }
+}

examples/typescript/README.md

@@ -0,0 +1,23 @@
+# Working with TypeScript
+
+This is the most basic bree example that shows a basic workflow for working with bree and typescript.
+
+## Using the root option
+
+It is generally best to set the `bree` `root` option when using any tool that may be tranpiling your code. Generally it makes the most sense to set it to `path.join(__dirname, 'jobs')`. If you are compiling to ESModules, you should set it to `path.join(path.dirname(fileURLToPath(import.meta.url)), 'jobs')` as the global `__dirname` variable will be unavailable.
+
+## Using TS Node
+
+[TS Node](https://github.com/TypeStrong/ts-node) is a project that uses hooks to compile typescript on the fly for fast and convenient TypeScript development. In order to use `bree` successfully with TS Node and to be able to write your jobs in TypeScript - one needs to run it in such a way that allows TS Node to transpile child process and worker scripts on the fly.
+
+We do this by implementing a `dev` script in our `package.json` as is outlined in the [TS Node docs.](https://github.com/TypeStrong/ts-node#other).
+
+`"dev": "TS_NODE=true NODE_OPTIONS=\"-r ts-node/register\" node ."`
+
+We further add a TS_NODE env var, as when in a TS Node environment, we need to append ts file extensions to our worker paths instead of the default JS. However, when we compile the code for production with the TypeScript compiler (running `tsc`), we need to keep the default js extensions on our worker paths.
+
+## Compiling to ESModules
+
+To compile to ESModules first set `"type": "module"` in your package.json. Ensure your compiler options are set to compile to ESModules output. After that, we need to change our `dev` script in our `package.json` so TS Node [properly compiles workers](https://github.com/TypeStrong/ts-node#other) to ESModules as well.
+
+`"dev": "TS_NODE=true NODE_OPTIONS=\"--loader ts-node/esm\" node ."`

examples/typescript/index.ts

@@ -0,0 +1,23 @@
+import process from 'node:process';
+import * as path from 'node:path';
+import Bree from 'bree';
+
+const bree = new Bree({
+  /**
+   * Always set the root option when doing any type of
+   * compiling with bree. This just makes it clearer where
+   * bree should resolve the jobs folder from. By default it
+   * resolves to the jobs folder relative to where the program
+   * is executed.
+   */
+  root: path.join(__dirname, 'jobs'),
+  /**
+   * We only need the default extension to be "ts"
+   * when we are running the app with ts-node - otherwise
+   * the compiled-to-js code still needs to use JS
+   */
+  defaultExtension: process.env.TS_NODE ? 'ts' : 'js',
+  jobs: ['job']
+});
+
+bree.start();

examples/typescript/jobs/job.ts

@@ -0,0 +1,9 @@
+import { parentPort } from 'node:worker_threads';
+import process from 'node:process';
+
+console.log('Hello TypeScript!');
+
+// signal to parent that the job is done
+if (parentPort) parentPort.postMessage('done');
+// eslint-disable-next-line unicorn/no-process-exit
+else process.exit(0);

examples/typescript/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "bree-js-example",
+  "version": "1.0.0",
+  "description": "basic bree example",
+  "main": "index.ts",
+  "author": "Spencer Snyder <sasnyde2@gmail.com> (https://spencersnyder.io/)",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^16.11.7",
+    "ts-node": "^10.4.0",
+    "tslib": "^2.3.1",
+    "typescript": "^4.4.4"
+  },
+  "scripts": {
+    "dev": "TS_NODE=true NODE_OPTIONS=\"-r ts-node/register\" node .",
+    "start": "rm -rf dist && tsc && node dist/index.js"
+  },
+  "dependencies": {
+    "bree": "latest"
+  }
+}

examples/typescript/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@tsconfig/node16/tsconfig.json",
+  "include": ["**/*.ts"],
+  "compilerOptions": {
+    "outDir": "dist",
+    "moduleResolution": "node"
+  }
+}