docs: partial revamp

.npmignore

@@ -22,4 +22,7 @@ bun.lockb
 jest.config.js
 .eslintrc.json
 .gitignore
-CHANGELOG.md
+CHANGELOG.md
+
+# Files that will be removed later
+OLD_README.md

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - README streaming examples to use `.shift()` instead of `.splice()`.
 - Context of `TaskHook`s to contain the name of the task being called and whether or not it's being called within a service.
+- `ServiceCluster.launch` to disallow negative or non-whole numbers.
 
 ### Fixed
 
@@ -25,6 +26,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Functionality for setting new keys on `SharedMap` instances rather than throwing an error.
 - The ability to set new values on `SharedMap` based on the previous value. This is fantastic for high-concurrency parallel operations and eliminates all race conditions.
+- `Nanolith.clusterize` method for easy creation of a service cluster and launching services all at the same time.
 
 ## [0.2.5] - 2022-24-12
 

src/__playground__/index.ts

@@ -1,19 +1,22 @@
-import api from './worker.js';
-import { SharedMap } from '@nanolith';
+// 💡 index.ts
+// Importing the Nanolith API we created in worker.ts
+import { worker } from './worker.js';
 
-const map = new SharedMap({ count: 0 });
+// Launch 6 services at the same time.
+const cluster = await worker.clusterize(6);
 
-const promise = api({ name: 'handler', params: [map.transfer] });
-const promise2 = api({ name: 'handler', params: [map.transfer] });
-const promise3 = api({ name: 'handler', params: [map.transfer] });
-const promise4 = api({ name: 'handler', params: [map.transfer] });
+// Use the least busy service on the cluster.
+// This is the service that is currently running
+// the least amount of task calls.
+const service = cluster.use();
 
-for (let i = 1; i <= 1000; i++) {
-    await map.set('count', (prev) => +prev + 1);
-}
+// Call the task on the service as you normally would.
+const result = await service.call({
+    name: 'subtract',
+    params: [10, 5],
+});
 
-await Promise.all([promise, promise2, promise3, promise4]);
+console.log(result);
 
-console.log(await map.get('count'));
-
-map.close();
+// Close all services on the cluster.
+await cluster.closeAll();

src/__playground__/worker.ts

@@ -1,12 +1,27 @@
-import { SharedMap, define } from '@nanolith';
-import type { SharedMapTransfer } from '@nanolith';
+// worker.ts 💼
+import { define } from 'nanolith';
 
-export default await define({
-    handler: async (transfer: SharedMapTransfer<{ count: number }>) => {
-        const map = new SharedMap(transfer);
-
-        for (let i = 1; i <= 1000; i++) {
-            await map.set('count', (prev) => +prev + 1);
-        }
+export const worker = await define({
+    __initializeService(threadId) {
+        console.log(`Initializing service on ${threadId}`);
+    },
+    __beforeTask({ name, inService }) {
+        console.log(`Running task ${name}.`);
+        console.log(`${inService ? 'Is' : 'Is not'} in a service.`);
+    },
+    __afterTask({ name, inService }) {
+        console.log(`Finished task ${name}`);
     },
+    add(x: number, y: number) {
+        return x + y;
+    },
+    async waitThenAdd(x: number, y: number) {
+        await new Promise((resolve) => setTimeout(resolve, 5e3));
+        return x + y;
+    },
+    subtract,
 });
+
+function subtract(x: number, y: number) {
+    return x - y;
+}

src/define/define.ts

@@ -2,11 +2,12 @@ import { isMainThread, workerData } from 'worker_threads';
 import { workerHandler } from '@handlers';
 import { runTaskWorker, runServiceWorker } from '@runners';
 import { assertCurrentFileNotEqual, getAutoIdentifier, getCurrentFile } from './utilities.js';
+import { ServiceCluster } from '@service_cluster';
 
 import type { DefineOptions, TaskDefinitions, Tasks } from '@typing/definitions.js';
 import type { Nanolith } from '@typing/nanolith.js';
 import type { ServiceWorkerOptions, TaskWorkerOptions } from '@typing/workers.js';
-import type { CleanKeyOf, CleanReturnType } from '@typing/utilities.js';
+import type { CleanKeyOf, CleanReturnType, PositiveWholeNumber } from '@typing/utilities.js';
 import type { BaseWorkerData } from '@typing/worker_data.js';
 
 /**
@@ -68,7 +69,18 @@ export async function define<Definitions extends TaskDefinitions>(
                     if (safeMode) assertCurrentFileNotEqual(file);
                     return runServiceWorker<Definitions, Options>(file, identifierToUse, options);
                 }),
+                clusterize: Object.freeze(async function <Count extends number, Options extends ServiceWorkerOptions>(
+                    this: Nanolith<Definitions>,
+                    count = 1 as PositiveWholeNumber<Count>,
+                    options = {} as Options
+                ) {
+                    if (safeMode) assertCurrentFileNotEqual(file);
+                    const cluster = new ServiceCluster(this);
+                    await cluster.launch(count, options);
+                    return cluster;
+                }),
                 file,
+                identifier: identifierToUse,
             }
         )
     );

src/service_cluster/service_cluster.ts

@@ -6,6 +6,7 @@ import type { Nanolith } from '@typing/nanolith.js';
 import type { Service } from '@service';
 import type { ServiceWorkerOptions } from '@typing/workers.js';
 import type { TaskDefinitions } from '@typing/definitions.js';
+import type { PositiveWholeNumber } from '@typing/utilities.js';
 
 type ServiceClusterMap<Definitions extends TaskDefinitions> = Map<
     string,
@@ -57,6 +58,7 @@ export class ServiceCluster<Definitions extends TaskDefinitions> {
      * Launch a new service on the provided {@link Nanolith} API, and automatically manage it
      * with the `ServiceCluster`.
      *
+     * @param count The number of services to launch on the cluster.
      * @param options A {@link ServiceWorkerOptions} object
      * @returns A promise of a {@link Service} instance. The promise resolves once the worker is online.
      *
@@ -69,12 +71,20 @@ export class ServiceCluster<Definitions extends TaskDefinitions> {
      * // Launch 2 services on the cluster
      * await cluster.launch(2, { priority: true });
      */
-    async launch<Options extends ServiceWorkerOptions>(count?: 1, options?: Options): Promise<Service<Definitions> | undefined>;
-    async launch<Options extends ServiceWorkerOptions>(
-        count: Exclude<number, 1 | 2>,
+    // async launch<Count extends number, Options extends ServiceWorkerOptions>(count?: 1, options?: Options): Promise<Service<Definitions> | undefined>;
+    // async launch<Count extends number, Options extends ServiceWorkerOptions>(
+    //     count: Exclude<number, 1 | 2>,
+    //     options?: Options
+    // ): Promise<(Service<Definitions> | undefined)[]>;
+    async launch<Count extends 1 | undefined, Options extends ServiceWorkerOptions>(
+        count?: Count,
+        options?: Options
+    ): Promise<Service<Definitions> | undefined>;
+    async launch<Count extends number, Options extends ServiceWorkerOptions>(
+        count: PositiveWholeNumber<Count>,
         options?: Options
     ): Promise<(Service<Definitions> | undefined)[]>;
-    async launch<Options extends ServiceWorkerOptions>(count?: number, options = {} as Options) {
+    async launch<Count extends number, Options extends ServiceWorkerOptions>(count?: PositiveWholeNumber<Count>, options = {} as Options) {
         // Don't allow more services to be added if it exceeds the pool's `maxConcurrency`
         if (!count || count === 1) return this.#launchService(options);
 

src/types/definitions.ts

@@ -57,13 +57,14 @@ export type Tasks<Definitions extends TaskDefinitions> = Except<Definitions, key
 
 export type DefineOptions = {
     /**
-     * If `define`'s default file location detection is not working correctly,
+     * If `define()`'s default file location detection is not working correctly,
      * the true file location for the set of definitions can be provided here.
      */
     file?: string;
     /**
      * A unique identifier that can be used when creating multiple sets of definitions
-     * in the same file to avoid nasty clashing.
+     * in the same file to avoid nasty clashing. Overrides the identifier created by
+     * Nanolith.
      */
     identifier?: string;
     /**

src/types/nanolith.ts

@@ -1,5 +1,6 @@
+import type { ServiceCluster } from '@service_cluster';
 import type { TaskDefinitions, Tasks } from './definitions.js';
-import type { CleanKeyOf, CleanReturnType } from './utilities.js';
+import type { CleanKeyOf, CleanReturnType, PositiveWholeNumber } from './utilities.js';
 import type { TaskWorkerOptions, ServiceWorkerOptions } from './workers.js';
 import type { Service } from '@service';
 
@@ -47,8 +48,23 @@ export type Nanolith<Definitions extends TaskDefinitions> = {
      * console.log(data);
      */
     launchService: <Options extends ServiceWorkerOptions>(options?: Options) => Promise<Service<Definitions>>;
+    /**
+     * Simultaneously create a cluster and launch a certain number of
+     * services on it.
+     *
+     * @param count The number of services to launch on the cluster.
+     * @param options
+     */
+    clusterize<Count extends number, Options extends ServiceWorkerOptions>(
+        count?: PositiveWholeNumber<Count>,
+        options?: Options
+    ): Promise<ServiceCluster<Definitions>>;
     /**
      * The file location at which the definitions live, and where the worker runs off of.
      */
     file: string;
+    /**
+     * The unique identifier for the set of definitions.
+     */
+    identifier: string;
 };

src/types/utilities.ts

@@ -21,13 +21,23 @@ export type CleanKeyOf<T extends Record<any, any>> = Extract<keyof T, string>;
 type IsEqual<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
 
 /**
-Filter out keys from an object.
-*/
+ * Filter out keys from an object.
+ */
 type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : KeyType extends ExcludeType ? never : KeyType;
 
 /**
-Create a type from an object type without certain keys.
-*/
+ * Create a type from an object type without certain keys.
+ */
 export type Except<ObjectType, KeysType extends keyof ObjectType> = {
     [KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
 };
+
+/**
+ * Create tuples of any length
+ */
+export type Tuple<T, N, R extends T[] = []> = R['length'] extends N ? R : Tuple<T, N, [...R, T]>;
+
+/**
+ * Ensure a number is a positive whole number.
+ */
+export type PositiveWholeNumber<Num extends number> = `${Num}` extends `-${string}` | `${string}.${string}` | '0' ? never : Num;