docs: Added examples section in the documentation site (#614)

Co-authored-by: Carlos Fuentes <[email protected]>

docs/docs/advanced-topics/custom-task-queues.md → docs/docs/advanced-topics/custom-task-queues.mdx

@@ -3,6 +3,8 @@ id: Custom Task Queues
 sidebar_position: 1
 ---
 import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 By default, Piscina uses a simple array-based first-in-first-out (fifo)
 task queue. When a new task is submitted and there are no available
@@ -70,7 +72,9 @@ Users can import `FixedQueue` from the `Piscina` package and pass it as the `tas
 
 Here's an example of how to use the `FixedQueue`:
 
-```js tab={"label":"Javascript"}
+<Tabs>
+<TabItem value="Javascript">
+```js
 const { Piscina, FixedQueue } = require("piscina");
 const { resolve } = require("path");
 
@@ -93,7 +97,9 @@ for (let i = 0; i < 10; i++) {
 }
 ```
 
-```js tab={"label":"Typescript","span":2} title="main.ts"
+</TabItem>
+<TabItem value="Typescript">
+```js  title="main.ts"
 import Piscina from "piscina";
 import { resolve } from "path";
 import { filename } from "./worker";
@@ -116,6 +122,9 @@ for (let i = 0; i < 10; i++) {
 }
 ```
 <WorkerWrapperComponent/>
+</TabItem>
+</Tabs>
+
 :::info
 The `FixedQueue` will become the default task queue implementation in a next major version.
 :::

docs/docs/api-reference/method.md

@@ -43,7 +43,7 @@ Schedules a task to be run on a Worker thread.
 * `filename`: Optionally overrides the `filename` option passed to the
   constructor for this task. If no `filename` was specified to the constructor,
   this is mandatory.
-* `abortSignal`: An [`AbortSignal`][] instance. If passed, this can be used to
+* `signal`: An [`AbortSignal`][] instance. If passed, this can be used to
   cancel a task. If the task is already running, the corresponding `Worker`
   thread will be stopped.
   (More generally, any `EventEmitter` or `EventTarget` that emits `'abort'`

docs/docs/examples/abort.md → docs/docs/examples/abort.mdx

@@ -2,16 +2,19 @@
 id: Aborting Tasks
 sidebar_position: 1
 ---
-import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx';
+
+import { WorkerWrapperComponent } from '@site/src/components/WorkerWrapper.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 Piscina allows submitted tasks to be cancelled even if the task has already been submitted to a worker and is being actively processed. This can be used, for instance, to cancel tasks that are taking too long to run.
 
 In this example, we'll simulate a long running task using `setTimeout`:
 
 ```js title="worker.js" tab={"label":"Javascript"}
-"use strict";
+'use strict';
 
-const { promisify } = require("util");
+const { promisify } = require('util');
 const sleep = promisify(setTimeout);
 
 module.exports = async ({ a, b }) => {
@@ -21,8 +24,8 @@ module.exports = async ({ a, b }) => {
 ```
 
 ```js title="worker.ts" tab={"label":"Typescript"}
-import { promisify } from "util";
-import { resolve } from "path";
+import { promisify } from 'util';
+import { resolve } from 'path';
 
 export const filename = resolve(__filename);
 
@@ -43,35 +46,39 @@ Tasks can be canceled using an `AbortController` or an `EventEmitter`.
 
 ## Using AbortController
 
-In this example, the AbortController instance is passed as the signal option to the `piscina.run` method. After submitting the task, we call `abortController.abort()` to cancel the task.
+In this example, the `AbortController` instance is passed as the signal option to the `piscina.run` method. After submitting the task, we call `abortController.abort()` to cancel the task.
 
-```js tab={"label":"Javascript"}
+<Tabs>
+<TabItem value="Javascript">
+```js
 "use strict";
 
 const Piscina = require("piscina");
 const { AbortController } = require("abort-controller");
 const { resolve } = require("path");
 
 const piscina = new Piscina({
-  filename: resolve(__dirname, "worker.js"),
+filename: resolve(__dirname, "worker.js"),
 });
 
 (async function () {
-  const abortController = new AbortController();
-  try {
-    const task = piscina.run(
-      { a: 4, b: 6 },
-      { signal: abortController.signal }
-    );
-    abortController.abort();
-    await task;
-  } catch (err) {
-    console.log("The task was cancelled");
-  }
+const abortController = new AbortController();
+try {
+const task = piscina.run(
+{ a: 4, b: 6 },
+{ signal: abortController.signal }
+);
+abortController.abort();
+await task;
+} catch (err) {
+console.log("The task was cancelled");
+}
 })();
-```
 
-```js tab={"label":"Typescript","span":2}
+````
+</TabItem>
+<TabItem value="Typescript">
+```js
 import Piscina from "piscina"; // Adjust the import path as necessary
 import { AbortController } from "abort-controller";
 import { resolve } from "path";
@@ -96,122 +103,133 @@ const piscina = new Piscina({
   }
 })();
 ```
-<WorkerWrapperComponent/>
+<WorkerWrapperComponent />
+</TabItem>
+</Tabs>
 
 ## Using EventEmitter
 
-The EventEmitter instance is passed as the signal option to the `piscina.run` method.
+The `EventEmitter` instance is passed as the signal option to the `piscina.run` method.
 
-```js tab={"label":"Javascript"}
-"use strict";
+<Tabs>
+<TabItem value="Javascript">
+```js
+'use strict';
 
-const Piscina = require("../..");
-const EventEmitter = require("events");
-const { resolve } = require("path");
+const Piscina = require('../..');
+const EventEmitter = require('events');
+const { resolve } = require('path');
 
 const piscina = new Piscina({
-  filename: resolve(__dirname, "worker.js"),
+  filename: resolve(__dirname, 'worker.js')
 });
 
 (async function () {
   const ee = new EventEmitter();
   try {
     const task = piscina.run({ a: 4, b: 6 }, { signal: ee });
-    ee.emit("abort");
+    ee.emit('abort');
     await task;
   } catch (err) {
-    console.log("The task was cancelled");
+    console.log('The task was cancelled');
   }
 })();
 ```
+</TabItem>
+<TabItem value="Typescript">
 
-```js tab={"label":"Typescript","span":2}
-import Piscina from "piscina";
-import { resolve } from "path";
-import { filename } from "./worker.js";
-import { EventEmitter } from "events";
+```js
+import Piscina from 'piscina';
+import { resolve } from 'path';
+import { filename } from './worker.js';
+import { EventEmitter } from 'events';
 
 const piscina = new Piscina({
-  filename: resolve(__dirname, "./workerWrapper.js"),
-  workerData: { fullpath: filename },
+  filename: resolve(__dirname, './workerWrapper.js'),
+  workerData: { fullpath: filename }
 });
 
 (async function () {
   const ee = new EventEmitter();
   try {
     const task = piscina.run({ a: 4, b: 6 }, { signal: ee });
-    ee.emit("abort");
+    ee.emit('abort');
     await task;
   } catch (err) {
-    console.log("The task was cancelled");
+    console.log('The task was cancelled');
   }
 })();
 ```
-<WorkerWrapperComponent/>
+<WorkerWrapperComponent />
+</TabItem>
+</Tabs>
 
 ## Using a Timer with EventEmitter
 
-In this example, we use a timer and an `EventEmitter` instance to cancel a task that takes longer than a specified time to complete.
-
-```js tab={"label":"Javascript"}
-"use strict";
+<Tabs>
+<TabItem value="Javascript">
+```js
+'use strict';
 
-const Piscina = require("../..");
-const EventEmitter = require("events");
-const { resolve } = require("path");
+const Piscina = require('../..');
+const EventEmitter = require('events');
+const { resolve } = require('path');
 
 const piscina = new Piscina({
-  filename: resolve(__dirname, "worker.js"),
+  filename: resolve(__dirname, 'worker.js')
 });
 
 (async function () {
   const ee = new EventEmitter();
   // Use a timer to limit task processing length
-  const t = setTimeout(() => ee.emit("abort"), 500);
+  const t = setTimeout(() => ee.emit('abort'), 500);
   try {
     await piscina.run({ a: 4, b: 6 }, { signal: ee });
   } catch (err) {
-    console.log("The task timed out");
+    console.log('The task timed out');
   } finally {
     // Clear the timeout in a finally to make sure
     // it is definitely cleared.
     clearTimeout(t);
   }
 })();
 ```
-
+</TabItem>
+<TabItem value="Typescript">
 ```js tab={"label":"Typescript","span":2}
-import Piscina from "piscina";
-import { resolve } from "path";
-import { filename } from "./worker.js";
-import { EventEmitter } from "events";
+import Piscina from 'piscina';
+import { resolve } from 'path';
+import { filename } from './worker.js';
+import { EventEmitter } from 'events';
 
 const piscina = new Piscina({
-  filename: resolve(__dirname, "./workerWrapper.js"),
-  workerData: { fullpath: filename },
+  filename: resolve(__dirname, './workerWrapper.js'),
+  workerData: { fullpath: filename }
 });
 
 (async function () {
   const ee = new EventEmitter();
   // Use a timer to limit task processing length
-  const t = setTimeout(() => ee.emit("abort"), 500);
+  const t = setTimeout(() => ee.emit('abort'), 500);
   try {
     await piscina.run({ a: 4, b: 6 }, { signal: ee });
   } catch (err) {
-    console.log("The task timed out");
+    console.log('The task timed out');
   } finally {
     // Clear the timeout in a finally to make sure
     // it is definitely cleared.
     clearTimeout(t);
   }
 })();
 ```
-<WorkerWrapperComponent/>
+<WorkerWrapperComponent />
+</TabItem>
+</Tabs>
 
 ## Using a Timer with AbortController
 
-In this example, we use a timer `AbortController` to cancel a task that takes longer than a specified time to complete.
-
+<Tabs>
+<TabItem value="Javascript">
 ```js tab={"label":"Javascript"}
 'use strict';
 
@@ -241,16 +259,17 @@ const piscina = new Piscina({
   }
 })();
 ```
-
-```js tab={"label":"Typescript","span":2}
-import Piscina from "piscina";
-import { resolve } from "path";
-import { filename } from "./worker.js";
-import { EventEmitter } from "events";
+</TabItem>
+<TabItem value="Typescript">
+    ```js tab={"label":"Typescript","span":2}
+import Piscina from 'piscina';
+import { resolve } from 'path';
+import { filename } from './worker.js';
+import { EventEmitter } from 'events';
 
 const piscina = new Piscina({
-  filename: resolve(__dirname, "./workerWrapper.js"),
-  workerData: { fullpath: filename },
+  filename: resolve(__dirname, './workerWrapper.js'),
+  workerData: { fullpath: filename }
 });
 
 (async function () {
@@ -264,14 +283,17 @@ const piscina = new Piscina({
   try {
     await piscina.run({ a: 4, b: 6 }, { signal: ac.signal });
   } catch (err) {
-    console.log("The task timed out");
+    console.log('The task timed out');
   } finally {
     // Clear the timeout in a finally to make sure
     // it is definitely cleared.
     clearTimeout(t);
   }
 })();
 ```
-<WorkerWrapperComponent/>
 
-You can also check out this example on [github](https://github.com/piscinajs/piscina/tree/current/examples/abort).
+<WorkerWrapperComponent />
+    </TabItem>
+</Tabs>
+
+You can also check out this example on [github](https://github.com/piscinajs/piscina/tree/current/examples/abort).