feat: Initial implementation

Author: joachimvh

.componentsignore

@@ -1 +1,5 @@
-[]
+[
+  "AsyncHandlerInput",
+  "AsyncHandlerOutput",
+  "Error"
+]

README.md

@@ -1 +1,112 @@
 # AsyncHandler
+
+[![npm version](https://badge.fury.io/js/asynchandler.svg)](https://www.npmjs.com/package/asynchandler)
+
+This library provides a generic interface which you can use for classes,
+so they can easily be combined using composite patterns.
+An `AsyncHandler` implementation has 3 functions: `canHandle`, `handle`, and `handleSafe`.
+
+`canHandle` is used to determine if a class supports a given input.
+In case it does not, it should throw an error.
+If a `canHandle` call succeeds, the `handle` function can be called to perform the necessary action.
+`handleSafe` is a utility function that combines the above two steps into one.
+
+For example, assume you want to handle an HTTP request,
+and have a separate class for every HTTP method.
+In the `canHandle` call for each of those,
+they would check if the method is the correct one and throw an error if this is not the case.
+In the `handle` call, they could then perform the necessary action for this method,
+knowing that the request has the correct method.
+
+This library comes with several utility composite handlers that can be used to combine such handlers into one.
+These have the same interface, so from the point of view of the caller,
+a single HTTP request class, and a composite handler that combines all the HTTP request classes,
+look and perform the same.
+
+## Composite handlers
+
+Below is an overview of all composite handlers provided in this library.
+
+### AsyncHandler
+
+The main interface. Although in practice this is actually an abstract class.
+This way it can provide a default `canHandle` implementation that always succeeds,
+and a `handleSafe` implementation that calls `canHandle`, and then `handle` if the first succeeds.
+
+### BooleanHandler
+
+Takes as input one or more handlers that return a boolean.
+This handler will return `true` if any of the input handlers can handle the input and return `true`.
+
+### CachedHandler
+
+Caches the result of the source handler in a [WeakMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap).
+The input is used as the key to cache with.
+Input field names can also be provided to only use a subset of the input.
+
+### ParallelHandler
+
+Runs the `handleSafe` function of all its source handlers simultaneously.
+The `canHandle` of this handler will always succeed.
+
+### ProcessHandler
+
+A handler made for worker threads.
+It can be used to only run the source handler depending on if it is executed on the primary or a worker thread.
+
+### SequenceHandler
+
+Runs all its handlers sequentially and returns the result of the last one that can handle the input.
+The `canHandle` of this handler will always succeed.
+
+### StaticHandler
+
+A handler that always succeeds and returns the provided value.
+
+### StaticThrowHandler
+
+A handler that always throws the provided error.
+It can be configured to always succeed `canHandle` and only throw when `handle` is called,
+or to throw in both cases.
+
+### UnionHandler
+
+An abstract class that combines the results of all its source handlers in some way.
+How these are combined is determined by the abstract `combine` function.
+It can be configured to ignore handlers that do not support the input,
+and to ignore errors.
+
+#### ArrayUnionHandler
+
+A `UnionHandler` that combines and flattens the results of its source handlers into a single array.
+
+### WaterfallHandler
+
+This handler will call the `handle` function of the first source handler where the `canHandle` call succeeds.
+
+## Utility
+
+Besides the composite handlers, some utility functions and classes are provided.
+
+### findHandler
+
+A function that returns the first handler from a list of handlers where `canHandle` succeeds.
+Throws an error if no such handler can be found.
+
+### filterHandlers
+
+Filters a list of handlers to only return those where `canHandle` succeeds.
+Throws an error if this would be an empty list.
+
+### ErrorFactory
+
+An interface for a factory that can create errors.
+This can be used in combination with a `StaticThrowHandler`.
+
+#### BaseErrorFactory
+
+An `ErrorFactory` that creates a standard Error.
+
+#### ClassErrorFactory
+
+An `ErrorFactory` that reuses the constructor of the input Error.

config/dummy.json

@@ -0,0 +1,3 @@
+{
+  "comment": "Empty JSON file to make sure the config folder exits. If you are not using Components.js this can be removed."
+}

jest.config.js

@@ -19,5 +19,13 @@ module.exports = {
     '/node_modules/',
     '/test/',
   ],
+  coverageThreshold: {
+    './src': {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
   testTimeout: 90000,
 };

package.json

@@ -1,18 +1,19 @@
 {
   "name": "asynchandler",
-  "version": "1.0.0",
+  "version": "0.0.1",
   "license": "MIT",
+  "repository": "[email protected]:CommunitySolidServer/AsyncHandler.git",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "lsd:module": "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler",
   "lsd:components": "dist/components/components.jsonld",
   "lsd:contexts": {
-    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^1.0.0/components/context.jsonld": "dist/components/context.jsonld"
+    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^0.0.0/components/context.jsonld": "dist/components/context.jsonld"
   },
   "lsd:importPaths": {
-    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^1.0.0/components/": "dist/components/",
-    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^1.0.0/config/": "config/",
-    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^1.0.0/dist/": "dist/"
+    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^0.0.0/components/": "dist/components/",
+    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^0.0.0/config/": "config/",
+    "https://linkedsoftwaredependencies.org/bundles/npm/asynchandler/^0.0.0/dist/": "dist/"
   },
   "files": [
     "config",
@@ -28,6 +29,9 @@
     "release": "commit-and-tag-version",
     "test": "jest"
   },
+  "dependencies": {
+    "global-logger-factory": "^1.0.0"
+  },
   "devDependencies": {
     "@commitlint/cli": "^19.4.0",
     "@commitlint/config-conventional": "^19.2.2",
@@ -57,9 +61,6 @@
     },
     "writerOpts": {
       "commitsSort": false
-    },
-    "skip": {
-      "tag": true
     }
   }
 }

src/ArrayUnionHandler.ts

@@ -0,0 +1,15 @@
+import type { AsyncHandler, AsyncHandlerOutput } from './AsyncHandler';
+import { UnionHandler } from './UnionHandler';
+
+/**
+ * A utility handler that concatenates the results of all its handlers into a single result.
+ */
+export class ArrayUnionHandler<T extends AsyncHandler<unknown, unknown[]>> extends UnionHandler<T> {
+  public constructor(handlers: T[], requireAll?: boolean, ignoreErrors?: boolean) {
+    super(handlers, requireAll, ignoreErrors);
+  }
+
+  protected async combine(results: AsyncHandlerOutput<T>[]): Promise<AsyncHandlerOutput<T>> {
+    return results.flat() as AsyncHandlerOutput<T>;
+  }
+}

src/AsyncHandler.ts

@@ -0,0 +1,47 @@
+type Awaited<T> = T extends PromiseLike<infer U> ? U : T;
+export type AsyncHandlerInput<T extends AsyncHandler<unknown, unknown>> = Parameters<T['handle']>[0];
+export type AsyncHandlerOutput<T extends AsyncHandler<unknown, unknown>> = Awaited<ReturnType<T['handle']>>;
+
+/**
+ * Simple interface for classes that can potentially handle a specific kind of data asynchronously.
+ * Actually a class and not an interface to have a base implementation of `canHandle` and `handleSafe`,
+ * but can also be used as an interface.
+ */
+export abstract class AsyncHandler<TIn = void, TOut = void> {
+  /**
+   * Checks whether the input can be handled by this class.
+   * If it cannot handle the input, rejects with an error explaining why.
+   *
+   * @param input - Input that could potentially be handled.
+   *
+   * @returns A promise resolving if the input can be handled, rejecting with an Error if not.
+   */
+  // eslint-disable-next-line unused-imports/no-unused-vars
+  public async canHandle(input: TIn): Promise<void> {
+    // Support any input by default
+  }
+
+  /**
+   * Handles the given input. This may only be called if {@link canHandle} did not reject.
+   * When unconditionally calling both in sequence, consider {@link handleSafe} instead.
+   *
+   * @param input - Input that needs to be handled.
+   *
+   * @returns A promise resolving when handling is finished.
+   */
+  public abstract handle(input: TIn): Promise<TOut>;
+
+  /**
+   * Helper function that first runs {@link canHandle} followed by {@link handle}.
+   * Throws the error of {@link canHandle} if the data cannot be handled,
+   * or returns the result of {@link handle} otherwise.
+   *
+   * @param input - Input data that will be handled if it can be handled.
+   *
+   * @returns A promise resolving if the input can be handled, rejecting with an Error if not.
+   */
+  public async handleSafe(input: TIn): Promise<TOut> {
+    await this.canHandle(input);
+    return this.handle(input);
+  }
+}

src/BaseErrorFactory.ts

@@ -0,0 +1,19 @@
+import type { ErrorFactory } from './ErrorFactory';
+
+/**
+ * An {@link ErrorFactory} that generates a basic {@link Error} with the given message.
+ *
+ * If no message is provided when calling the `create` function,
+ * the message that was provided in the constructor will be used.
+ */
+export class BaseErrorFactory implements ErrorFactory {
+  protected readonly message?: string;
+
+  public constructor(message?: string) {
+    this.message = message;
+  }
+
+  public create(message?: string): Error {
+    return new Error(message ?? this.message);
+  }
+}

src/BooleanHandler.ts

@@ -0,0 +1,70 @@
+import { getLoggerFor } from 'global-logger-factory';
+import { AsyncHandler } from './AsyncHandler';
+import { filterHandlers } from './HandlerUtil';
+
+/**
+ * A composite handler that returns true if any of its handlers can handle the input and return true.
+ * Handler errors are interpreted as false results.
+ */
+export class BooleanHandler<TIn> extends AsyncHandler<TIn, boolean> {
+  protected readonly logger = getLoggerFor(this);
+
+  protected readonly handlers: AsyncHandler<TIn, boolean>[];
+
+  /**
+   * Creates a new BooleanHandler that stores the given handlers.
+   *
+   * @param handlers - Handlers over which it will run.
+   */
+  public constructor(handlers: AsyncHandler<TIn, boolean>[]) {
+    super();
+    this.handlers = handlers;
+  }
+
+  public async canHandle(input: TIn): Promise<void> {
+    // We use this to generate an error if no handler supports the input
+    await filterHandlers(this.handlers, input);
+  }
+
+  public async handleSafe(input: TIn): Promise<boolean> {
+    const handlers = await filterHandlers(this.handlers, input);
+    return promiseSome(handlers.map(async(handler): Promise<boolean> => handler.handle(input)));
+  }
+
+  public async handle(input: TIn): Promise<boolean> {
+    let handlers: AsyncHandler<TIn, boolean>[];
+    try {
+      handlers = await filterHandlers(this.handlers, input);
+    } catch (error: unknown) {
+      this.logger.warn('All handlers failed. This might be the consequence of calling handle before canHandle.');
+      throw new Error('All handlers failed', { cause: error });
+    }
+    return promiseSome(handlers.map(async(handler): Promise<boolean> => handler.handle(input)));
+  }
+}
+
+function noop(): void {}
+
+/**
+ * A function that simulates the Array.some behaviour but on an array of Promises.
+ * Returns true if at least one promise returns true.
+ * Returns false if all promises return false or error.
+ *
+ * @remarks
+ *
+ * Predicates provided as input must be implemented considering
+ * the following points:
+ * 1. if they throw an error, it won't be propagated;
+ * 2. throwing an error should be logically equivalent to returning false.
+ */
+export async function promiseSome(predicates: Promise<boolean>[]): Promise<boolean> {
+  return new Promise((resolve): void => {
+    function resolveIfTrue(value: boolean): void {
+      if (value) {
+        resolve(true);
+      }
+    }
+    Promise.all(predicates.map(async(predicate): Promise<void> => predicate.then(resolveIfTrue, noop)))
+      .then((): void => resolve(false), noop);
+  });
+}