@dr.pogodin/js-utils 0.0.10 → 0.0.12

package/build/Barrier.d.ts

@@ -1,10 +1,27 @@
-type Resolver<T, TR = T> = (value: T | PromiseLike<T>) => Barrier<T, TR>;
-type Rejecter<T = unknown, TR = T> = (reason?: any) => Barrier<T, TR>;
-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, T>;
-    get reject(): Rejecter<unknown, unknown>;
+    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,25 +34,44 @@ 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;
-                return this;
+                // 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;
-                return this;
             };
             if (executor)
                 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr.pogodin/js-utils",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Collection of JavaScript (TypeScript) utilities.",
   "main": "build/index",
   "react-native": "src/index",
@@ -31,11 +31,10 @@
   },
   "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",
+    "@babel/core": "^7.24.6",
+    "@babel/preset-env": "^7.24.6",
+    "@babel/preset-typescript": "^7.24.6",
     "@tsconfig/recommended": "^1.0.6",
-    "@tsd/typescript": "^5.4.5",
     "@types/jest": "^29.5.12",
     "babel-jest": "^29.7.0",
     "eslint": "^8.57.0",
@@ -44,7 +43,6 @@
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.29.1",
     "jest": "^29.7.0",
-    "jest-runner-tsd": "^6.0.0",
     "rimraf": "^5.0.7",
     "tstyche": "^1.1.0",
     "typescript": "^5.4.5",

package/src/Barrier.ts

@@ -1,6 +1,7 @@
-type Resolver<T, TR = T> = (value: T | PromiseLike<T>) => Barrier<T, TR>;
-type Rejecter<T = unknown, TR = T> = (reason?: any) => Barrier<T, TR>;
-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,26 +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;
-        return this;
+
+        // 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;
-        return this;
       };
+
       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; }