Add waitUntil

Author: surunzi

DOC.md

@@ -4882,8 +4882,8 @@ Unlike filter, this method mutates array.
 
 |Name     |Type    |Desc                                |
 |---------|--------|------------------------------------|
-|obj      |array   |Collection to iterate over          |
-|predicate|function|Function invoked per iteration      |
+|list     |array   |Collection to iterate over          |
+|iterator |function|Function invoked per iteration      |
 |[context]|*       |Predicate context                   |
 |return   |array   |Array of all values that are removed|
 
@@ -6009,6 +6009,24 @@ vlq.decode('2H'); // -> [123]
 vlq.decode('2HwcqxB'); // -> [123, 456, 789]
 ```
 
+## waitUntil 
+
+Wait until function returns a truthy value.
+
+|Name          |Type    |Desc              |
+|--------------|--------|------------------|
+|condition     |function|Condition function|
+|[timeout=0]   |number  |Timeout           |
+|[interval=250]|number  |Wait interval     |
+
+```javascript
+let a = 5;
+setTimeout(() => a = 10, 500);
+waitUntil(() => a === 10).then(() => {
+    console.log(a); // -> 10
+});
+```
+
 ## waterfall 
 
 Run an array of functions in series.

DOC_CN.md

@@ -4876,8 +4876,8 @@ reject([1, 2, 3, 4, 5], function (val) {
 
 |参数名|类型|说明|
 |-----|----|---|
-|obj|array|要遍历的集合|
-|predicate|function|真值检测函数|
+|list|array|要遍历的集合|
+|iterator|function|真值检测函数|
 |[context]|*|函数上下文|
 |返回值|array|包含所有删除元素的数组|
 
@@ -6003,6 +6003,24 @@ vlq.decode('2H'); // -> [123]
 vlq.decode('2HwcqxB'); // -> [123, 456, 789]
 ```
 
+## waitUntil
+
+等待直到条件函数返回真值。
+
+|参数名|类型|说明|
+|-----|----|---|
+|condition|function|条件函数|
+|[timeout=0]|number|超时|
+|[interval=250]|number|等待间隔|
+
+```javascript
+let a = 5;
+setTimeout(() => a = 10, 500);
+waitUntil(() => a === 10).then(() => {
+    console.log(a); // -> 10
+});
+```
+
 ## waterfall
 
 按顺序执行函数序列。

index.json

@@ -2285,7 +2285,8 @@
     "remove": {
         "description": "Remove all elements from array that predicate returns truthy for and return an array of the removed elements.",
         "dependencies": [
-            "safeCb"
+            "safeCb",
+            "types"
         ],
         "env": "all",
         "test": "all"
@@ -2880,6 +2881,14 @@
         "env": "all",
         "test": "all"
     },
+    "waitUntil": {
+        "description": "Wait until function returns a truthy value.",
+        "dependencies": [
+            "now"
+        ],
+        "env": "all",
+        "test": "all"
+    },
     "waterfall": {
         "description": "Run an array of functions in series.",
         "dependencies": [

src/w/waitUntil.i18n.md

@@ -0,0 +1,9 @@
+## CN
+
+等待直到条件函数返回真值。
+
+|参数名|类型|说明|
+|-----|----|---|
+|condition|function|条件函数|
+|[timeout=0]|number|超时|
+|[interval=250]|number|等待间隔|

src/w/waitUntil.js

@@ -0,0 +1,60 @@
+/* Wait until function returns a truthy value.
+ *
+ * |Name          |Type    |Desc              |
+ * |--------------|--------|------------------|
+ * |condition     |function|Condition function|
+ * |[timeout=0]   |number  |Timeout           |
+ * |[interval=250]|number  |Wait interval     |
+ */
+
+/* example
+ * let a = 5;
+ * setTimeout(() => a = 10, 500);
+ * waitUntil(() => a === 10).then(() => {
+ *     console.log(a); // -> 10
+ * });
+ */
+
+/* module
+ * env: all
+ * test: all
+ */
+
+/* typescript
+ * export declare function waitUntil(
+ *     condition: Function,
+ *     timeout?: number,
+ *     interval?: number
+ * ): Promise<any>;
+ */
+
+_('now');
+
+exports = function(condition, timeout = 0, interval = 250) {
+    function evalCondition() {
+        return new Promise((resolve, reject) => {
+            try {
+                resolve(condition());
+            } catch (e) {
+                reject(e);
+            }
+        });
+    }
+
+    return new Promise((resolve, reject) => {
+        const startTime = now();
+        const pollCondition = () => {
+            evalCondition().then(val => {
+                const elapsed = now() - startTime;
+                if (val) {
+                    resolve(val);
+                } else if (timeout && elapsed >= timeout) {
+                    reject(Error(`Wait timed out after ${elapsed} ms`));
+                } else {
+                    setTimeout(pollCondition, interval);
+                }
+            }, reject);
+        };
+        pollCondition();
+    });
+};

src/w/waitUntil.test.js

@@ -0,0 +1,36 @@
+const now = util.now;
+
+it('basic', async () => {
+    let a = 5;
+    setTimeout(() => (a = 10), 500);
+    await waitUntil(() => a === 10);
+    expect(a).to.equal(10);
+});
+
+it('timeout', async () => {
+    let a = 5;
+    setTimeout(() => (a = 10), 500);
+    let err;
+    try {
+        await waitUntil(() => a === 10, 20);
+    } catch (e) {
+        err = e;
+    }
+    expect(err).to.be.an('error');
+});
+
+it('interval', async () => {
+    const startTime = now();
+    let a = 5;
+    setTimeout(() => (a = 10), 20);
+    await waitUntil(() => a === 10, 0, 20);
+    expect(a).to.equal(10);
+    expect(now() - startTime).to.be.below(50);
+});
+
+it('async', async () => {
+    let a = 5;
+    setTimeout(() => (a = 10), 500);
+    await waitUntil(async () => a === 10);
+    expect(a).to.equal(10);
+});