@dr.pogodin/js-utils 0.0.11 → 0.0.13

package/build/Barrier.d.ts

@@ -1,10 +1,27 @@
-type Resolver<T> = (value: T | PromiseLike<T>) => void;
-type Rejecter = (reason?: any) => void;
-export type Executor<T> = (resolve: Resolver<T>, reject: Rejecter) => void;
+export type Executor<T> = ConstructorParameters<typeof Promise<T>>[0];
+type Resolver<T> = Parameters<Executor<T>>[0];
+type Rejecter = Parameters<Executor<unknown>>[1];
 /**
  * Barrier is just a Promise which has resolve and reject exposed as instance
  * methods.
  *
+ * It has two generic arguments T and TR which correspond to the argument of
+ * the .resolve() method, and to the value resolved by the promise (barrier).
+ * For a simple barrier TR equals to T, however for barriers created via .then()
+ * chain, T corresponds to the argument of the original barrier, and TR to
+ * the value resolved by the latest promise in the chain. Consider this:
+ *
+ * const b = new Barrier<string>();
+ * b.resolve('result');
+ * const s = await b; // `s` has `string` type, and equals "result".
+ *
+ * const b = (new Barrier<string>()).then((s) => s.length);
+ * b.resolve('result'); // Chained barrier exposes .resolve() method of
+ *                      // the first barrier in the chain, which expects
+ *                      // `string` arugment (T), but the chained barrier
+ *                      // resolves to `number` (TR).
+ * const n = await b; // `n` has `number` type, and equals 6.
+ *
  * Docs: https://dr.pogodin.studio/docs/react-utils/docs/api/classes/Barrier
  */
 export default class Barrier<T = unknown, TR = T> extends Promise<TR> {
@@ -12,8 +29,8 @@ export default class Barrier<T = unknown, TR = T> extends Promise<TR> {
     private p_reject;
     private p_state;
     constructor(executor?: Executor<TR>);
-    get resolve(): Resolver<T>;
-    get reject(): Rejecter;
+    get resolve(): (arg: Parameters<Resolver<T>>[0]) => this;
+    get reject(): (arg: Parameters<Rejecter>[0]) => this;
     get resolved(): boolean;
     get rejected(): boolean;
     get settled(): boolean;

package/build/Barrier.js

@@ -10,6 +10,23 @@ var STATE;
  * Barrier is just a Promise which has resolve and reject exposed as instance
  * methods.
  *
+ * It has two generic arguments T and TR which correspond to the argument of
+ * the .resolve() method, and to the value resolved by the promise (barrier).
+ * For a simple barrier TR equals to T, however for barriers created via .then()
+ * chain, T corresponds to the argument of the original barrier, and TR to
+ * the value resolved by the latest promise in the chain. Consider this:
+ *
+ * const b = new Barrier<string>();
+ * b.resolve('result');
+ * const s = await b; // `s` has `string` type, and equals "result".
+ *
+ * const b = (new Barrier<string>()).then((s) => s.length);
+ * b.resolve('result'); // Chained barrier exposes .resolve() method of
+ *                      // the first barrier in the chain, which expects
+ *                      // `string` arugment (T), but the chained barrier
+ *                      // resolves to `number` (TR).
+ * const n = await b; // `n` has `number` type, and equals 6.
+ *
  * Docs: https://dr.pogodin.studio/docs/react-utils/docs/api/classes/Barrier
  */
 class Barrier extends Promise {
@@ -17,10 +34,17 @@ class Barrier extends Promise {
         let resolveRef;
         let rejectRef;
         super((resolve, reject) => {
+            // Note: Enforcing `void` return type because of the BEWARE note below.
             resolveRef = (value) => {
                 resolve(value);
                 this.p_state = STATE.RESOLVED;
+                // BEWARE: Don't try to return `this` here, it will easily cause
+                // infinite loops in React Native, which are extremely difficult
+                // to troubleshoot (I wasn't able to figure out, are they due to
+                // internal Promise implementation in RN, or because of some bad
+                // patterns in the host code).
             };
+            // Note: Enforcing `void` return type because of the BEWARE note below.
             rejectRef = (reason) => {
                 reject(reason);
                 this.p_state = STATE.REJECTED;
@@ -29,11 +53,25 @@ class Barrier extends Promise {
                 executor(resolveRef, rejectRef);
         });
         this.p_state = STATE.PENDING;
+        // NOTE: We assume, the only scenario where TR is not equal T is when
+        // the Barrier is constructed by a .then() call on a "parent" barrier,
+        // and in that scenario .then() itself will replace .p_resolve by another
+        // resolver immediately after this constructor returns.
         this.p_resolve = resolveRef;
         this.p_reject = rejectRef;
     }
-    get resolve() { return this.p_resolve; }
-    get reject() { return this.p_reject; }
+    get resolve() {
+        return (arg) => {
+            this.p_resolve(arg);
+            return this;
+        };
+    }
+    get reject() {
+        return (arg) => {
+            this.p_reject(arg);
+            return this;
+        };
+    }
     get resolved() { return this.p_state === STATE.RESOLVED; }
     get rejected() { return this.p_state === STATE.REJECTED; }
     get settled() { return this.p_state !== STATE.PENDING; }

package/build/time.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timer = exports.Timer = exports.YEAR_MS = exports.DAY_MS = exports.HOUR_MS = exports.MIN_MS = exports.SEC_MS = void 0;
+exports.Timer = exports.YEAR_MS = exports.DAY_MS = exports.HOUR_MS = exports.MIN_MS = exports.SEC_MS = void 0;
+exports.timer = timer;
 const Barrier_1 = __importDefault(require("./Barrier"));
 // This is not very elegant, but as of now TypeScript does not support type
 // arithmetic, thus we can't have constants assigned like `MIN_MS = 60 * SEC_MS`
@@ -70,4 +71,3 @@ function timer(timeout) {
     const t = new Timer();
     return t.init(timeout);
 }
-exports.timer = timer;

package/build/withRetries.js

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = withRetries;
 const time_1 = require("./time");
 /**
  * Attempts to perform the given async `action` up to `maxRetries` times with
@@ -39,4 +40,3 @@ function withRetries(action_1) {
         /* eslint-enable no-await-in-loop */
     });
 }
-exports.default = withRetries;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr.pogodin/js-utils",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Collection of JavaScript (TypeScript) utilities.",
   "main": "build/index",
   "react-native": "src/index",
@@ -31,21 +31,21 @@
   },
   "homepage": "https://github.com/birdofpreyru/js-utils#readme",
   "devDependencies": {
-    "@babel/core": "^7.24.5",
-    "@babel/preset-env": "^7.24.5",
-    "@babel/preset-typescript": "^7.24.1",
-    "@tsconfig/recommended": "^1.0.6",
-    "@types/jest": "^29.5.12",
+    "@babel/core": "^7.26.0",
+    "@babel/preset-env": "^7.26.0",
+    "@babel/preset-typescript": "^7.26.0",
+    "@tsconfig/recommended": "^1.0.8",
+    "@types/jest": "^29.5.14",
     "babel-jest": "^29.7.0",
-    "eslint": "^8.57.0",
+    "eslint": "^8.57.1",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-airbnb-typescript": "^18.0.0",
-    "eslint-import-resolver-typescript": "^3.6.1",
-    "eslint-plugin-import": "^2.29.1",
+    "eslint-import-resolver-typescript": "^3.7.0",
+    "eslint-plugin-import": "^2.31.0",
     "jest": "^29.7.0",
-    "rimraf": "^5.0.7",
-    "tstyche": "^1.1.0",
-    "typescript": "^5.4.5",
-    "typescript-eslint": "^7.10.0"
+    "rimraf": "^6.0.1",
+    "tstyche": "^3.2.0",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.2"
   }
 }

package/src/Barrier.ts

@@ -1,6 +1,7 @@
-type Resolver<T> = (value: T | PromiseLike<T>) => void;
-type Rejecter = (reason?: any) => void;
-export type Executor<T> = (resolve: Resolver<T>, reject: Rejecter) => void;
+export type Executor<T> = ConstructorParameters<typeof Promise<T>>[0];
+
+type Resolver<T> = Parameters<Executor<T>>[0];
+type Rejecter = Parameters<Executor<unknown>>[1];
 
 enum STATE {
   PENDING = 'PENDING',
@@ -12,10 +13,27 @@ enum STATE {
  * Barrier is just a Promise which has resolve and reject exposed as instance
  * methods.
  *
+ * It has two generic arguments T and TR which correspond to the argument of
+ * the .resolve() method, and to the value resolved by the promise (barrier).
+ * For a simple barrier TR equals to T, however for barriers created via .then()
+ * chain, T corresponds to the argument of the original barrier, and TR to
+ * the value resolved by the latest promise in the chain. Consider this:
+ *
+ * const b = new Barrier<string>();
+ * b.resolve('result');
+ * const s = await b; // `s` has `string` type, and equals "result".
+ *
+ * const b = (new Barrier<string>()).then((s) => s.length);
+ * b.resolve('result'); // Chained barrier exposes .resolve() method of
+ *                      // the first barrier in the chain, which expects
+ *                      // `string` arugment (T), but the chained barrier
+ *                      // resolves to `number` (TR).
+ * const n = await b; // `n` has `number` type, and equals 6.
+ *
  * Docs: https://dr.pogodin.studio/docs/react-utils/docs/api/classes/Barrier
  */
 export default class Barrier<T = unknown, TR = T> extends Promise<TR> {
-  private p_resolve: Resolver<T> | Resolver<TR>;
+  private p_resolve: Resolver<T>;
 
   private p_reject: Rejecter;
 
@@ -26,24 +44,49 @@ export default class Barrier<T = unknown, TR = T> extends Promise<TR> {
     let rejectRef: Rejecter;
 
     super((resolve, reject) => {
-      resolveRef = (value: TR | PromiseLike<TR>) => {
+      // Note: Enforcing `void` return type because of the BEWARE note below.
+      resolveRef = (value: TR | PromiseLike<TR>): void => {
         resolve(value);
         this.p_state = STATE.RESOLVED;
+
+        // BEWARE: Don't try to return `this` here, it will easily cause
+        // infinite loops in React Native, which are extremely difficult
+        // to troubleshoot (I wasn't able to figure out, are they due to
+        // internal Promise implementation in RN, or because of some bad
+        // patterns in the host code).
       };
-      rejectRef = (reason?: any) => {
+
+      // Note: Enforcing `void` return type because of the BEWARE note below.
+      rejectRef = (reason?: any): void => {
         reject(reason);
         this.p_state = STATE.REJECTED;
       };
+
       if (executor) executor(resolveRef, rejectRef);
     });
 
-    this.p_resolve = resolveRef!;
+    // NOTE: We assume, the only scenario where TR is not equal T is when
+    // the Barrier is constructed by a .then() call on a "parent" barrier,
+    // and in that scenario .then() itself will replace .p_resolve by another
+    // resolver immediately after this constructor returns.
+    this.p_resolve = resolveRef! as Resolver<T>;
+
     this.p_reject = rejectRef!;
   }
 
-  get resolve() { return <Resolver<T>> this.p_resolve; }
+  get resolve() {
+    return (arg: Parameters<Resolver<T>>[0]) => {
+      this.p_resolve(arg);
+      return this;
+    };
+  }
 
-  get reject() { return this.p_reject; }
+  get reject() {
+    return (arg: Parameters<Rejecter>[0]) => {
+      this.p_reject(arg);
+      return this;
+    };
+  }
 
   get resolved() { return this.p_state === STATE.RESOLVED; }
 

package/tstyche.config.json

@@ -1,3 +1,6 @@
 {
-  "testFileMatch": ["__tests__"]
+  "testFileMatch": [
+    "__tests__/**/*.ts",
+    "__tests__/**/*.tsx"
+  ]
 }