readiness-manager 1.2.0-rc.xf50ab1c7f → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readiness-manager",
-  "version": "1.2.0-rc.xf50ab1c7f",
+  "version": "1.2.0",
   "description": "👨‍💼 Define when your app is ready",
   "main": "./dist/src/index.js",
   "dependencies": {

package/src/error.ts

@@ -9,7 +9,15 @@ export const ERRORS = {
     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;
 
 /**

package/src/index.ts

@@ -1,35 +1,6 @@
 import { logger } from '@fiverr-private/obs';
 import { ERRORS, ActionExecutionError, defaultErrorHandler, ActionErrorHandler } from './error';
-import { BeaconStatus, ActionStatus } from './constants';
-
-export type ReadyCallback = () => void;
-export type ReadyAction = () => unknown | Promise<unknown>;
-
-export interface ActionsStatus {
-    [status: string]: string[];
-}
-
-interface Beacon {
-    name: string;
-    action: ReadyAction;
-    status: ActionStatus;
-    callbacks: ReadyCallback[];
-    debug?: boolean;
-}
-
-interface BeaconsMap {
-    [name: string]: Beacon;
-}
-
-/**
- * Sets of private attributes which should not be exposed / accessed by consumer.
- */
-const beaconsSymbol = Symbol('beacons');
-const callbacksSymbol = Symbol('callbacks');
-const executeSymbol = Symbol('execute');
-const trackBeaconUpdateSymbol = Symbol('trackBeaconUpdate');
-const updateBeaconSymbol = Symbol('updateBeacon');
-const errorHandlerSymbol = Symbol('errorHandler');
+import type { ActionStatus, ReadyAction, ReadyCallback, ActionsStatus, BeaconsMap, Beacon } from './types';
 
 /**
  * The internal "ready" state to determine process readiness.
@@ -46,21 +17,29 @@ export interface ReadinessManager {
     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 {
-    private [beaconsSymbol]: BeaconsMap;
-    private [callbacksSymbol]: ReadyCallback[];
-    private [errorHandlerSymbol]: ActionErrorHandler;
+    #beacons: BeaconsMap;
+    #callbacks: ReadyCallback[];
+    #errorHandler: ActionErrorHandler;
 
     constructor() {
-        this[beaconsSymbol] = {};
-        this[callbacksSymbol] = [];
-        this[errorHandlerSymbol] = defaultErrorHandler;
-
-        this[executeSymbol] = this[executeSymbol].bind(this);
+        this.#beacons = {};
+        this.#callbacks = [];
+        this.#errorHandler = defaultErrorHandler;
     }
 
     /**
-     * Returns true if current process state is considered as "ready".
+     * Returns `true` if all the registered actions has been ran without exceptions/rejections.
      */
     get ready(): boolean {
         return readyState;
@@ -70,7 +49,7 @@ class ReadinessManagerImpl implements ReadinessManager {
      * Returns current registered actions status
      */
     status(): ActionsStatus {
-        return Object.values(this[beaconsSymbol]).reduce((acc, { name, status }) => {
+        return Object.values(this.#beacons).reduce((acc, { name, status }) => {
             const current = acc[status] || [];
             return Object.assign(acc, { [status]: [...current, name] });
         }, {} as ActionsStatus);
@@ -78,16 +57,18 @@ class ReadinessManagerImpl implements ReadinessManager {
 
     /**
      * 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 debug timing logs.
+     * @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[beaconsSymbol][name]) {
+        if (this.#beacons[name]) {
             throw new Error(ERRORS.BEACON_ALREADY_EXISTS);
         }
 
@@ -95,27 +76,30 @@ class ReadinessManagerImpl implements ReadinessManager {
             name,
             action,
             callbacks: [],
-            status: BeaconStatus.NOT_STARTED,
+            status: 'not_started',
             debug,
         };
 
-        Object.assign(this[beaconsSymbol], { [name]: beacon });
+        Object.assign(this.#beacons, { [name]: beacon });
     }
 
     /**
-     * Runs current registered beacons execution to determine process "ready" state.
+     *
+     * 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[beaconsSymbol]).forEach((beacon) => this[executeSymbol](beacon));
+        Object.values(this.#beacons).forEach((beacon) => this.#execute(beacon));
 
         return this;
     }
 
     /**
-     * Registers a given callback to be triggered once process is marked as "ready".
-     * @param callback
+     * 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) {
@@ -124,7 +108,7 @@ class ReadinessManagerImpl implements ReadinessManager {
             return this;
         }
 
-        this[callbacksSymbol].push(callback);
+        this.#callbacks.push(callback);
         return this;
     }
 
@@ -132,20 +116,22 @@ class ReadinessManagerImpl implements ReadinessManager {
      * 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[beaconsSymbol][name];
+        const beacon = this.#beacons[name];
         if (!beacon) {
             throw new Error(ERRORS.BEACON_DOES_NOT_EXISTS);
         }
 
-        if (beacon.status === BeaconStatus.RESOLVED) {
+        if (beacon.status === 'resolved') {
             // Invokes immediately given callback if beacon status is already resolved.
             callback();
             return this;
         }
 
-        this[beaconsSymbol][name].callbacks.push(callback);
+        this.#beacons[name].callbacks.push(callback);
         return this;
     }
 
@@ -154,7 +140,7 @@ class ReadinessManagerImpl implements ReadinessManager {
      * @param errorHandler - The handler to trigger upon action errors.
      */
     onError(errorHandler: ActionErrorHandler): ReadinessManager {
-        this[errorHandlerSymbol] = errorHandler;
+        this.#errorHandler = errorHandler;
         return this;
     }
 
@@ -165,12 +151,12 @@ class ReadinessManagerImpl implements ReadinessManager {
      * @throws {ActionExecutionError}
      * @private
      */
-    private async [executeSymbol](beacon: Beacon, attempt = 1): Promise<void> {
+    async #execute(beacon: Beacon, attempt = 1): Promise<void> {
         const { name, action, debug } = beacon;
 
-        const update = (status: ActionStatus) => this[updateBeaconSymbol](name, status);
+        const update = (status: ActionStatus) => this.#updateBeacon(name, status);
 
-        update(BeaconStatus.PENDING);
+        update('pending');
 
         const startTime = debug ? Date.now() : null;
 
@@ -187,18 +173,18 @@ class ReadinessManagerImpl implements ReadinessManager {
                 logger.debug(`[ReadinessManager] Action "${name}" completed in ${duration}ms`);
             }
 
-            update(BeaconStatus.RESOLVED);
+            update('resolved');
         } catch (error) {
             if (debug && startTime !== null) {
                 const duration = Date.now() - startTime;
                 logger.debug(`[ReadinessManager] Action "${name}" failed after ${duration}ms`);
             }
 
-            update(BeaconStatus.REJECTED);
+            update('rejected');
 
             // Invokes consumer error hook with a retry method and the beacon error.
-            this[errorHandlerSymbol](new ActionExecutionError(name, attempt, error as Error), () =>
-                this[executeSymbol](beacon, attempt + 1)
+            this.#errorHandler(new ActionExecutionError(name, attempt, error as Error), () =>
+                this.#execute(beacon, attempt + 1)
             );
         }
     }
@@ -209,15 +195,15 @@ class ReadinessManagerImpl implements ReadinessManager {
      * @param status - The beacon status to set.
      * @private
      */
-    private [updateBeaconSymbol](name: string, status: ActionStatus): void {
-        Object.assign(this[beaconsSymbol][name], { status });
+    #updateBeacon(name: string, status: ActionStatus): void {
+        Object.assign(this.#beacons[name], { status });
 
         // Resolves specific beacon ready listeners.
-        if (status === BeaconStatus.RESOLVED) {
-            this[beaconsSymbol][name].callbacks.forEach((callback) => callback());
+        if (status === 'resolved') {
+            this.#beacons[name].callbacks.forEach((callback) => callback());
         }
 
-        this[trackBeaconUpdateSymbol]();
+        this.#trackBeaconUpdate();
     }
 
     /**
@@ -225,15 +211,15 @@ class ReadinessManagerImpl implements ReadinessManager {
      * If so, will trigger registered `onReady` callbacks.
      * @private
      */
-    private [trackBeaconUpdateSymbol](): void {
+    #trackBeaconUpdate(): void {
         if (readyState) {
             return;
         }
 
-        readyState = Object.values(this[beaconsSymbol]).every((beacon) => beacon.status === BeaconStatus.RESOLVED);
+        readyState = Object.values(this.#beacons).every((beacon) => beacon.status === 'resolved');
 
         if (readyState) {
-            this[callbacksSymbol].forEach((callback) => callback());
+            this.#callbacks.forEach((callback) => callback());
         }
     }
 }

package/src/spec.ts

@@ -1,4 +1,3 @@
-import { BeaconStatus } from './constants';
 import { ERRORS, ActionExecutionError } from './error';
 import { ReadinessManager } from './index';
 
@@ -8,12 +7,6 @@ import { ReadinessManager } from './index';
  */
 const wait = (time = 0): Promise<unknown> => new Promise((resolve) => setTimeout(resolve, time));
 
-/**
- * Delays a promise resolve with a given time.
- * @param time - The time to wait.
- */
-const delayResolve = (time = 100): Promise<unknown> => new Promise((resolve) => setTimeout(resolve, time));
-
 describe('lib/readinessManager', () => {
     let readyManager: ReadinessManager;
 
@@ -59,8 +52,8 @@ describe('lib/readinessManager', () => {
 
                 const status = readyManager.status();
 
-                expect(status[BeaconStatus.RESOLVED]).toEqual(['success', 'other']);
-                expect(status[BeaconStatus.REJECTED]).toEqual(['fail']);
+                expect(status.resolved).toEqual(['success', 'other']);
+                expect(status.rejected).toEqual(['fail']);
             });
         });
     });
@@ -70,7 +63,7 @@ describe('lib/readinessManager', () => {
             it('Registers action and name as beacon with not_started status', () => {
                 readyManager.register('action', () => true);
 
-                expect(readyManager.status()[BeaconStatus.NOT_STARTED]).toHaveLength(1);
+                expect(readyManager.status().not_started).toHaveLength(1);
             });
         });
 
@@ -85,18 +78,18 @@ describe('lib/readinessManager', () => {
 
     describe('run', () => {
         beforeEach(() => {
-            readyManager.register('action1', delayResolve);
-            readyManager.register('action2', delayResolve);
+            readyManager.register('action1', wait);
+            readyManager.register('action2', wait);
         });
 
         it('Executes all given actions', async () => {
-            expect(readyManager.status()[BeaconStatus.NOT_STARTED]).toHaveLength(2);
+            expect(readyManager.status().not_started).toHaveLength(2);
 
             readyManager.run();
 
-            expect(readyManager.status()[BeaconStatus.NOT_STARTED]).toBeUndefined();
+            expect(readyManager.status().not_started).toBeUndefined();
 
-            expect(readyManager.status()[BeaconStatus.PENDING]).toHaveLength(2);
+            expect(readyManager.status().pending).toHaveLength(2);
         });
     });
 
@@ -176,8 +169,8 @@ describe('lib/readinessManager', () => {
         describe('When action is not ready', () => {
             it('Triggers callback once desired aciton is ready', async () => {
                 readyManager.register('some', () => true);
-                readyManager.register('thing', () => delayResolve(500));
-                readyManager.register('other', () => delayResolve(1000));
+                readyManager.register('thing', () => wait(500));
+                readyManager.register('other', () => wait(1000));
 
                 readyManager.onActionReady('thing', callback);
 

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

@@ -1,5 +1,6 @@
-import { ReadinessManager, ReadyCallback, ReadyAction, ActionsStatus } from '../src/index';
-import { ActionErrorHandler } from '../src/error';
+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;

package/dist/src/constants.d.ts

@@ -1,3 +0,0 @@
-export type ActionStatus = 'not_started' | 'pending' | 'resolved' | 'rejected';
-export declare const BeaconStatus: Record<string, ActionStatus>;
-//# sourceMappingURL=constants.d.ts.map

package/dist/src/constants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAK/E,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAK5C,CAAC"}

package/dist/src/constants.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BeaconStatus = void 0;
-exports.BeaconStatus = {
-    NOT_STARTED: 'not_started',
-    PENDING: 'pending',
-    RESOLVED: 'resolved',
-    REJECTED: 'rejected',
-};
-//# sourceMappingURL=constants.js.map

package/dist/src/constants.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";;;AAKa,QAAA,YAAY,GAAiC;IACtD,WAAW,EAAE,aAAa;IAC1B,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;CACd,CAAC"}

package/src/constants.ts

@@ -1,11 +0,0 @@
-export type ActionStatus = 'not_started' | 'pending' | 'resolved' | 'rejected';
-
-/**
- * The possible beacon status.
- */
-export const BeaconStatus: Record<string, ActionStatus> = {
-    NOT_STARTED: 'not_started',
-    PENDING: 'pending',
-    RESOLVED: 'resolved',
-    REJECTED: 'rejected',
-} as const;