readiness-manager 1.1.3 → 1.2.0-rc.x6cd566eea

package/jest.config.ts

@@ -0,0 +1,8 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+    displayName: 'readiness-manager',
+    preset: 'ts-jest',
+};
+
+export default config;

package/package.json

@@ -1,33 +1,22 @@
 {
   "name": "readiness-manager",
-  "version": "1.1.3",
+  "version": "1.2.0-rc.x6cd566eea",
   "description": "👨‍💼 Define when your app is ready",
-  "keywords": [
-    "ready",
-    "listeners",
-    "handlers",
-    "process"
-  ],
-  "author": "Fiverr Ants",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/fiverr/readiness-manager.git"
+  "main": "./dist/src/index.js",
+  "dependencies": {
+    "@fiverr-private/obs": "^1.35.0"
   },
-  "homepage": "https://github.com/fiverr/readiness-manager#readme",
-  "main": "index.js",
-  "types": "./src/types.d.ts",
-  "scripts": {
-    "test": "jest",
-    "lint": "eslint . --ext .js"
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./tests/mock": "./dist/tests/mock.js",
+    "./package.json": "./package.json"
   },
-  "devDependencies": {
-    "@fiverr/eslint-config-fiverr": "^3.2.1",
-    "eslint": "^7.10.0",
-    "eslint-plugin-log": "^1.2.6",
-    "jest": "^26.4.2"
-  },
-  "publishConfig": {
-    "tag": "latest"
+  "types": "./dist/src/index.d.ts",
+  "nx": {
+    "tags": [
+      "scope:lib",
+      "package_core",
+      "package_core:lib"
+    ]
   }
-}
+}

package/project.json

@@ -0,0 +1,16 @@
+{
+  "name": "readiness-manager",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "packages/atoms/readiness-manager/src",
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": ["rm -rf ./dist", "tsc --build tsconfig.json"],
+        "parallel": false,
+        "cwd": "packages/atoms/readiness-manager"
+      }
+    }
+  }
+}

package/src/error.ts

@@ -0,0 +1,46 @@
+import { logger } from '@fiverr-private/obs';
+/**
+ * The possible errors that could be thrown.
+ */
+export const ERRORS = {
+    BEACON_ALREADY_EXISTS: 'Beacon is already exists, please ensure to use a unique name per beacon',
+    BEACON_DOES_NOT_EXISTS:
+        'Beacon does not exists, make sure to call `register` before trying to set beacon ready hook.',
+    BEACON_EXECUTION_FAILED: 'Beacon execution failed',
+} as const;
+
+/**
+ * The retry function to be triggered upon beacon errors.
+ * @returns {Promise<unknown>}
+ */
+export type ActionRetry = () => Promise<unknown>;
+
+/**
+ * The error handler to be triggered upon beacon errors.
+ */
+export type ActionErrorHandler = (error: ActionExecutionError, retry: ActionRetry) => void;
+
+/**
+ * The custom error to be thrown when beacon execution fails.
+ */
+export class ActionExecutionError extends Error {
+    override name: string;
+    override stack: string;
+    attempt: number;
+    failReason: string;
+
+    constructor(name: string, attempt: number, error: Error) {
+        super();
+
+        this.message = ERRORS.BEACON_EXECUTION_FAILED;
+        this.name = name;
+        this.attempt = attempt;
+        this.stack = error.stack || '';
+        this.failReason = error.message;
+    }
+}
+
+/**
+ * Default error handler to be triggered upon beacon errors.
+ */
+export const defaultErrorHandler: ActionErrorHandler = (beaconError) => logger.error(beaconError);

package/src/index.ts

@@ -0,0 +1,230 @@
+import { logger } from '@fiverr-private/obs';
+import { ERRORS, ActionExecutionError, defaultErrorHandler, ActionErrorHandler } from './error';
+import type { ActionStatus, ReadyAction, ReadyCallback, ActionsStatus, BeaconsMap, Beacon } from './types';
+
+/**
+ * The internal "ready" state to determine process readiness.
+ */
+let readyState = false;
+
+export interface ReadinessManager {
+    register: (name: string, action: ReadyAction, debug?: boolean) => void;
+    run: () => ReadinessManager;
+    onReady: (callback: ReadyCallback) => ReadinessManager;
+    onActionReady: (name: string, callback: ReadyCallback) => ReadinessManager;
+    onError: (errorHandler: ActionErrorHandler) => ReadinessManager;
+    status: () => ActionsStatus;
+    ready: boolean;
+}
+
+/**
+ * The internal implementation of the ReadinessManager.
+ * @example
+ * const readinessManager = new ReadinessManager();
+ * readinessManager.register('database', () => connectToDB());
+ * readinessManager.register('redis', () => connectToRedis());
+ * readinessManager.run();
+ * readinessManager.onReady(() => console.log('App is ready! o/'));
+ * @returns {ReadinessManager}
+ */
+class ReadinessManagerImpl implements ReadinessManager {
+    #beacons: BeaconsMap;
+    #callbacks: ReadyCallback[];
+    #errorHandler: ActionErrorHandler;
+
+    constructor() {
+        this.#beacons = {};
+        this.#callbacks = [];
+        this.#errorHandler = defaultErrorHandler;
+    }
+
+    /**
+     * Returns `true` if all the registered actions has been ran without exceptions/rejections.
+     */
+    get ready(): boolean {
+        return readyState;
+    }
+
+    /**
+     * Returns current registered actions status
+     */
+    status(): ActionsStatus {
+        return Object.values(this.#beacons).reduce((acc, { name, status }) => {
+            const current = acc[status] || [];
+            return Object.assign(acc, { [status]: [...current, name] });
+        }, {} as ActionsStatus);
+    }
+
+    /**
+     * Registers a given name and action as beacon under manager.
+     * registered actions will be observed once ran in order to determine the process readiness state.
+     * @param name - The operation name to register with.
+     * @param action - The ready emitter to condition the process readiness with.
+     * @param debug - (Optional) flag to enable timing logs (default: `false`).
+     * @throws {Error} If the action name is already registered.
+     */
+    register(name: string, action: ReadyAction, debug = false): void {
+        if (this.ready) {
+            return;
+        }
+
+        if (this.#beacons[name]) {
+            throw new Error(ERRORS.BEACON_ALREADY_EXISTS);
+        }
+
+        const beacon: Beacon = {
+            name,
+            action,
+            callbacks: [],
+            status: 'not_started',
+            debug,
+        };
+
+        Object.assign(this.#beacons, { [name]: beacon });
+    }
+
+    /**
+     *
+     * Runs all registered actions. Once all actions are resolved successfully, your app state will be determined as `ready`.
+     * @returns {ReadinessManager}
+     */
+    run(): ReadinessManager {
+        readyState = false;
+
+        Object.values(this.#beacons).forEach((beacon) => this.#execute(beacon));
+
+        return this;
+    }
+
+    /**
+     * Registers a given callback on the global manager ready event.
+     * @param callback - The callback to run upon manager ready event.
+     * @returns {ReadinessManager}
+     */
+    onReady(callback: ReadyCallback): ReadinessManager {
+        if (readyState) {
+            // Invokes immediately given callback if process is already ready.
+            callback();
+            return this;
+        }
+
+        this.#callbacks.push(callback);
+        return this;
+    }
+
+    /**
+     * Registers a given callback on a specific action resolved.
+     * @param name - The name of the action the callback should be attached to.
+     * @param callback - The callback to run upon beacon resolved.
+     * @returns {ReadinessManager}
+     * @throws {Error} If the action name does not exists.
+     */
+    onActionReady(name: string, callback: ReadyCallback): ReadinessManager {
+        const beacon = this.#beacons[name];
+        if (!beacon) {
+            throw new Error(ERRORS.BEACON_DOES_NOT_EXISTS);
+        }
+
+        if (beacon.status === 'resolved') {
+            // Invokes immediately given callback if beacon status is already resolved.
+            callback();
+            return this;
+        }
+
+        this.#beacons[name].callbacks.push(callback);
+        return this;
+    }
+
+    /**
+     * Registers a given error handler under manager errors.
+     * @param errorHandler - The handler to trigger upon action errors.
+     */
+    onError(errorHandler: ActionErrorHandler): ReadinessManager {
+        this.#errorHandler = errorHandler;
+        return this;
+    }
+
+    /**
+     * Tracks a given beacon action.
+     * @param beacon - The beacon to execute.
+     * @param attempt - The attempt number of current beacon execution.
+     * @throws {ActionExecutionError}
+     * @private
+     */
+    async #execute(beacon: Beacon, attempt = 1): Promise<void> {
+        const { name, action, debug } = beacon;
+
+        const update = (status: ActionStatus) => this.#updateBeacon(name, status);
+
+        update('pending');
+
+        const startTime = debug ? Date.now() : null;
+
+        try {
+            // The actual beacon execution we want to keep track on.
+            const result = action();
+
+            if (result instanceof Promise) {
+                await result;
+            }
+
+            if (debug && startTime !== null) {
+                const duration = Date.now() - startTime;
+                logger.debug(`[ReadinessManager] Action "${name}" completed in ${duration}ms`);
+            }
+
+            update('resolved');
+        } catch (error) {
+            if (debug && startTime !== null) {
+                const duration = Date.now() - startTime;
+                logger.debug(`[ReadinessManager] Action "${name}" failed after ${duration}ms`);
+            }
+
+            update('rejected');
+
+            // Invokes consumer error hook with a retry method and the beacon error.
+            this.#errorHandler(new ActionExecutionError(name, attempt, error as Error), () =>
+                this.#execute(beacon, attempt + 1)
+            );
+        }
+    }
+
+    /**
+     * Updates a given beacon name with a given status.
+     * @param name - The beacon name to update.
+     * @param status - The beacon status to set.
+     * @private
+     */
+    #updateBeacon(name: string, status: ActionStatus): void {
+        Object.assign(this.#beacons[name], { status });
+
+        // Resolves specific beacon ready listeners.
+        if (status === 'resolved') {
+            this.#beacons[name].callbacks.forEach((callback) => callback());
+        }
+
+        this.#trackBeaconUpdate();
+    }
+
+    /**
+     * Tracks a beacon update event, checks whether process is "ready".
+     * If so, will trigger registered `onReady` callbacks.
+     * @private
+     */
+    #trackBeaconUpdate(): void {
+        if (readyState) {
+            return;
+        }
+
+        readyState = Object.values(this.#beacons).every((beacon) => beacon.status === 'resolved');
+
+        if (readyState) {
+            this.#callbacks.forEach((callback) => callback());
+        }
+    }
+}
+
+const manager: ReadinessManager = new ReadinessManagerImpl();
+
+export default manager;
+export { ActionExecutionError, ActionErrorHandler };

package/src/spec.ts

@@ -0,0 +1,250 @@
+import { ERRORS, ActionExecutionError } from './error';
+import { ReadinessManager } from './index';
+
+/**
+ * Waits a given milliseconds before resolving.
+ * @param time - The time to wait
+ */
+const wait = (time = 0): Promise<unknown> => new Promise((resolve) => setTimeout(resolve, time));
+
+describe('lib/readinessManager', () => {
+    let readyManager: ReadinessManager;
+
+    beforeEach(() => {
+        jest.isolateModules(() => {
+            readyManager = require('./index').default;
+        });
+    });
+
+    afterEach(jest.clearAllMocks);
+
+    describe('API', () => {
+        it.each(['register', 'run', 'onReady', 'onActionReady', 'status', 'onError'])(
+            'Exposes public API (%p)',
+            (property) => {
+                expect(typeof (readyManager as any)[property]).toBe('function');
+            }
+        );
+
+        it.each(['beacons', 'callbacks', 'execute', 'updateBeacon'])(
+            'Encapsulates private properties (%p)',
+            (property) => {
+                expect((readyManager as any)[property]).toBeUndefined();
+            }
+        );
+    });
+
+    describe('status', () => {
+        describe('When no actions are registered', () => {
+            it('Return an empty object', () => {
+                expect(readyManager.status()).toEqual({});
+            });
+        });
+
+        describe('When some actions exists', () => {
+            it('Group registered actions with same status', async () => {
+                readyManager.register('success', () => Promise.resolve());
+                readyManager.register('other', () => Promise.resolve());
+                readyManager.register('fail', () => Promise.reject(new Error()));
+
+                readyManager.run();
+                await wait(10);
+
+                const status = readyManager.status();
+
+                expect(status.resolved).toEqual(['success', 'other']);
+                expect(status.rejected).toEqual(['fail']);
+            });
+        });
+    });
+
+    describe('register', () => {
+        describe('When given action name is unique', () => {
+            it('Registers action and name as beacon with not_started status', () => {
+                readyManager.register('action', () => true);
+
+                expect(readyManager.status().not_started).toHaveLength(1);
+            });
+        });
+
+        describe('When action name was already registered', () => {
+            it('Throws upon registration', () => {
+                readyManager.register('once', () => true);
+
+                expect(() => readyManager.register('once', () => true)).toThrowError(ERRORS.BEACON_ALREADY_EXISTS);
+            });
+        });
+    });
+
+    describe('run', () => {
+        beforeEach(() => {
+            readyManager.register('action1', wait);
+            readyManager.register('action2', wait);
+        });
+
+        it('Executes all given actions', async () => {
+            expect(readyManager.status().not_started).toHaveLength(2);
+
+            readyManager.run();
+
+            expect(readyManager.status().not_started).toBeUndefined();
+
+            expect(readyManager.status().pending).toHaveLength(2);
+        });
+    });
+
+    describe('ready', () => {
+        it('Returns false by default', () => {
+            expect(readyManager.ready).toBeFalsy();
+        });
+
+        describe('When all actions resolves', () => {
+            beforeEach(() => {
+                readyManager.register('action1', () => true);
+                readyManager.register('action2', () => true);
+
+                readyManager.run();
+            });
+
+            it('Is ready', () => expect(readyManager.ready).toBeTruthy());
+        });
+
+        describe('When some action fails', () => {
+            beforeEach(() => {
+                readyManager.register('action1', () => true);
+                readyManager.register('action2', () => {
+                    throw new Error('What?');
+                });
+
+                readyManager.run();
+            });
+
+            it('Is not ready', () => expect(readyManager.ready).toBeFalsy());
+        });
+    });
+
+    describe('onReady', () => {
+        let callback: jest.Mock;
+
+        beforeEach(() => (callback = jest.fn()));
+
+        const ensureFresh = () => {
+            readyManager.register('action1', () => true);
+            expect(callback).toHaveBeenCalledTimes(0);
+        };
+
+        describe('When process is not ready', () => {
+            it('Registers given callback', () => {
+                const callback = jest.fn();
+                ensureFresh();
+
+                readyManager.onReady(callback);
+                readyManager.run();
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+        });
+
+        describe('When process is already ready', () => {
+            it('Activates immediately given callback', () => {
+                ensureFresh();
+
+                readyManager.run();
+                readyManager.onReady(callback);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+        });
+    });
+
+    describe('onActionReady', () => {
+        let callback: jest.Mock;
+
+        beforeEach(() => (callback = jest.fn()));
+
+        it('Throws when action does not exists', () => {
+            expect(() => readyManager.onActionReady('Hey', () => false)).toThrowError(ERRORS.BEACON_DOES_NOT_EXISTS);
+        });
+
+        describe('When action is not ready', () => {
+            it('Triggers callback once desired aciton is ready', async () => {
+                readyManager.register('some', () => true);
+                readyManager.register('thing', () => wait(500));
+                readyManager.register('other', () => wait(1000));
+
+                readyManager.onActionReady('thing', callback);
+
+                readyManager.run();
+                expect(callback).toHaveBeenCalledTimes(0);
+
+                await wait(500);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+        });
+
+        describe('When action is already resolved', () => {
+            it('Triggers immediately given callback', () => {
+                readyManager.register('some', () => true);
+
+                readyManager.run();
+                readyManager.onActionReady('some', callback);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+        });
+    });
+
+    describe('onError', () => {
+        let logger: jest.Mock;
+        beforeEach(() => (logger = jest.fn()));
+
+        describe('When no errors occur', () => {
+            beforeEach(() => {
+                readyManager.register('success', () => true);
+                readyManager.onError((error) => {
+                    logger(error);
+                });
+                readyManager.run();
+            });
+
+            it("Won't trigger error handler", () => {
+                expect(logger).toHaveBeenCalledTimes(0);
+            });
+        });
+
+        describe('When error occur', () => {
+            const error = new Error('Oh man, that did not worked!');
+
+            beforeEach(() => {
+                readyManager.register('success', () => {
+                    throw error;
+                });
+
+                readyManager.onError((error) => {
+                    logger(error);
+                });
+
+                readyManager.run();
+            });
+
+            it('Triggers consumer handler with beacon execution error', () => {
+                expect(logger).toHaveBeenCalledWith(new ActionExecutionError('success', 1, error));
+            });
+        });
+    });
+
+    describe('Chainable', () => {
+        it('Expose public chainable api', () => {
+            const ready = jest.fn();
+            const error = jest.fn();
+
+            readyManager.register('action', () => true);
+
+            readyManager.run().onReady(ready).onError(error);
+
+            expect(ready).toHaveBeenCalledTimes(1);
+            expect(error).toHaveBeenCalledTimes(0);
+        });
+    });
+});

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * A status of an action.
+ */
+export type ActionStatus = 'not_started' | 'pending' | 'resolved' | 'rejected';
+
+/**
+ * A callback to be executed when an action is ready.
+ */
+export type ReadyCallback = () => void;
+
+/**
+ * An action is a single function that needs to be executed to determine if the app is ready.
+ */
+export type ReadyAction = () => unknown | Promise<unknown>;
+
+/**
+ * A map of action statuses by their name.
+ */
+export type ActionsStatus = {
+    [key in ActionStatus]?: string[];
+};
+
+/**
+ * A beacon is a single action that needs to be executed to determine if the app is ready.
+ */
+export interface Beacon {
+    name: string;
+    action: ReadyAction;
+    status: ActionStatus;
+    callbacks: ReadyCallback[];
+    debug?: boolean;
+}
+/**
+ * A map of beacons by their name.
+ */
+export interface BeaconsMap {
+    [name: string]: Beacon;
+}

package/tests/mock.ts

@@ -0,0 +1,57 @@
+import { ReadinessManager } from '../src/index';
+import type { ReadyCallback, ReadyAction, ActionsStatus } from '../src/types';
+import type { ActionErrorHandler } from '../src/error';
+
+export interface ReadinessManagerMock extends ReadinessManager {
+    setReady: (isReady: boolean) => void;
+    orchestrate: () => void;
+}
+
+/**
+ * Test mock helper class.
+ */
+class ReadinessManagerMockImpl implements ReadinessManagerMock {
+    private _ready = false;
+
+    get ready(): boolean {
+        return this._ready;
+    }
+
+    status(): ActionsStatus {
+        return {} as ActionsStatus;
+    }
+
+    setReady(isReady: boolean): void {
+        this._ready = isReady;
+    }
+
+    register(_name: string, _action: ReadyAction, _debug?: boolean): void {
+        return undefined;
+    }
+
+    run(): ReadinessManager {
+        return this;
+    }
+
+    orchestrate(): void {
+        this._ready = true;
+    }
+
+    onReady(callback: ReadyCallback): ReadinessManager {
+        callback();
+        return this;
+    }
+
+    onActionReady(_name: string, callback: ReadyCallback): ReadinessManager {
+        callback();
+        return this;
+    }
+
+    onError(_errorHandler: ActionErrorHandler): ReadinessManager {
+        return this;
+    }
+}
+
+const manager: ReadinessManagerMock = new ReadinessManagerMockImpl();
+
+export default manager;