@zwave-js/waddle 1.1.0 → 1.2.0

package/README.md

@@ -211,7 +211,39 @@ async function* fetchResourcesTask() {
 }
 ```
 
-When using TypeScript, you may need to assert the return type due to limits in type inference in generator functions:
+When using TypeScript, you will likely hit limits in type inference in generator functions:
+
+```ts
+async function* fetchResourcesTask() {
+	// async function doLongRunningWork1(): Promise<string> { ... }
+	const result1 = yield () => doLongRunningWork1(); // unknown ⚠️
+	// async function doLongRunningWork2(): Promise<number> { ... }
+	const result2 = yield () => doLongRunningWork2(); // unknown ⚠️
+	// async function doLongRunningWork3(): Promise<boolean> { ... }
+	const result3 = yield () => doLongRunningWork3(); // unknown ⚠️
+
+	// ...
+}
+```
+
+To help mitigate this, we recommend using the `waitFor` utility function together with `yield*` instead. Note that this expects a Promise, not a function!
+
+```ts
+import { waitFor } from "@zwave-js/waddle";
+
+async function* fetchResourcesTask() {
+	// async function doLongRunningWork1(): Promise<string> { ... }
+	const result1 = yield* waitFor(doLongRunningWork1()); // string ✅
+	// async function doLongRunningWork2(): Promise<number> { ... }
+	const result2 = yield* waitFor(doLongRunningWork2()); // number ✅
+	// async function doLongRunningWork3(): Promise<boolean> { ... }
+	const result3 = yield* waitFor(doLongRunningWork3()); // boolean ✅
+
+	// ...
+}
+```
+
+Alternatively, you can assert the return type manually, but this is not type-safe:
 
 ```ts
 async function* fetchResourcesTask() {
@@ -317,22 +349,22 @@ To use concurrency groups, specify the `group` property in the task builder:
 
 ```ts
 const task1 = scheduler.queueTask({
-  priority: TaskPriority.Normal,
-  group: {
-    id: "my-concurrency-group",
-  },
+	priority: TaskPriority.Normal,
+	group: {
+		id: "my-concurrency-group",
+	},
 	task: async function* () {
-    // ...
+		// ...
 	},
 });
 
 const task2 = scheduler.queueTask({
-  priority: TaskPriority.Normal,
-  group: {
-    id: "my-concurrency-group",
-  },
+	priority: TaskPriority.Normal,
+	group: {
+		id: "my-concurrency-group",
+	},
 	task: async function* () {
-    // ...
+		// ...
 	},
 });
 ```
@@ -449,6 +481,10 @@ const scheduler = new TaskScheduler(() => new Error("We are all doomed!"));
 ```
 
 ## Changelog
+### 1.2.0 (2025-06-24)
+
+- Add utility method `waitFor` for type-safe yielding of Promises
+
 ### 1.1.0 (2025-06-24)
 
 - Add support for task concurrency groups, preventing interleaving related tasks

package/build/cjs/index.d.ts

@@ -1,2 +1,3 @@
 export { type Task, type TaskBuilder, TaskInterruptBehavior, TaskPriority, type TaskReturnType, TaskScheduler, TaskState, type TaskStepResult, type TaskConcurrencyGroup, } from "./Task.js";
+export { waitFor } from "./utils.js";
 //# sourceMappingURL=index.d.ts.map

package/build/cjs/index.js

@@ -21,15 +21,18 @@ __export(index_exports, {
   TaskInterruptBehavior: () => import_Task.TaskInterruptBehavior,
   TaskPriority: () => import_Task.TaskPriority,
   TaskScheduler: () => import_Task.TaskScheduler,
-  TaskState: () => import_Task.TaskState
+  TaskState: () => import_Task.TaskState,
+  waitFor: () => import_utils.waitFor
 });
 module.exports = __toCommonJS(index_exports);
 var import_Task = require("./Task.js");
+var import_utils = require("./utils.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TaskInterruptBehavior,
   TaskPriority,
   TaskScheduler,
-  TaskState
+  TaskState,
+  waitFor
 });
 //# sourceMappingURL=index.js.map

package/build/cjs/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/index.ts"],
-  "sourcesContent": ["export {\n\ttype Task,\n\ttype TaskBuilder,\n\tTaskInterruptBehavior,\n\tTaskPriority,\n\ttype TaskReturnType,\n\tTaskScheduler,\n\tTaskState,\n\ttype TaskStepResult,\n\ttype TaskConcurrencyGroup,\n} from \"./Task.js\";\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;;;;;;;;AAAA,kBAUO;",
+  "sourcesContent": ["export {\n\ttype Task,\n\ttype TaskBuilder,\n\tTaskInterruptBehavior,\n\tTaskPriority,\n\ttype TaskReturnType,\n\tTaskScheduler,\n\tTaskState,\n\ttype TaskStepResult,\n\ttype TaskConcurrencyGroup,\n} from \"./Task.js\";\nexport { waitFor } from \"./utils.js\";\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;AAAA,kBAUO;AACP,mBAAwB;",
   "names": []
 }

package/build/cjs/utils.d.ts

@@ -5,4 +5,5 @@ export declare function noop(): void;
 export type FnOrStatic<TArgs extends any[], TReturn> = ((...args: TArgs) => TReturn) | TReturn;
 export type ReturnTypeOrStatic<T> = T extends (...args: any[]) => infer R ? R : T;
 export declare function evalOrStatic<T>(fnOrConst: T, ...args: any[]): ReturnTypeOrStatic<T>;
+export declare function waitFor<T>(promise: Promise<T>): AsyncGenerator<() => Promise<T>, T>;
 //# sourceMappingURL=utils.d.ts.map

package/build/cjs/utils.js

@@ -21,7 +21,8 @@ var utils_exports = {};
 __export(utils_exports, {
   evalOrStatic: () => evalOrStatic,
   highResTimestamp: () => highResTimestamp,
-  noop: () => noop
+  noop: () => noop,
+  waitFor: () => waitFor
 });
 module.exports = __toCommonJS(utils_exports);
 function highResTimestamp() {
@@ -42,10 +43,16 @@ function evalOrStatic(fnOrConst, ...args) {
   return typeof fnOrConst === "function" ? fnOrConst(...args) : fnOrConst;
 }
 __name(evalOrStatic, "evalOrStatic");
+async function* waitFor(promise) {
+  const result = yield () => promise;
+  return result;
+}
+__name(waitFor, "waitFor");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   evalOrStatic,
   highResTimestamp,
-  noop
+  noop,
+  waitFor
 });
 //# sourceMappingURL=utils.js.map

package/build/cjs/utils.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils.ts"],
-  "sourcesContent": ["/** Returns a timestamp with nano-second precision */\nexport function highResTimestamp(): number {\n\tif (typeof process !== \"undefined\") {\n\t\tconst [s, ns] = process.hrtime();\n\t\treturn s * 1e9 + ns;\n\t} else if (performance != undefined) {\n\t\treturn performance.now() * 1e6;\n\t} else {\n\t\tthrow new Error(\"No high-resolution timer available\");\n\t}\n}\n\n/** Does nothing. Can be used for empty `.catch(...)` calls. */\nexport function noop(): void {\n\t// intentionally empty\n}\n\nexport type FnOrStatic<TArgs extends any[], TReturn> =\n\t| ((...args: TArgs) => TReturn)\n\t| TReturn;\n\nexport type ReturnTypeOrStatic<T> = T extends (...args: any[]) => infer R\n\t? R\n\t: T;\n\nexport function evalOrStatic<T>(\n\tfnOrConst: T,\n\t...args: any[]\n): ReturnTypeOrStatic<T> {\n\t// @ts-expect-error https://github.com/microsoft/TypeScript/issues/61337\n\treturn typeof fnOrConst === \"function\" ? fnOrConst(...args) : fnOrConst;\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;;;;;;;AACM,SAAU,mBAAgB;AAC/B,MAAI,OAAO,YAAY,aAAa;AACnC,UAAM,CAAC,GAAG,EAAE,IAAI,QAAQ,OAAM;AAC9B,WAAO,IAAI,MAAM;EAClB,WAAW,eAAe,QAAW;AACpC,WAAO,YAAY,IAAG,IAAK;EAC5B,OAAO;AACN,UAAM,IAAI,MAAM,oCAAoC;EACrD;AACD;AATgB;AAYV,SAAU,OAAI;AAEpB;AAFgB;AAYV,SAAU,aACf,cACG,MAAW;AAGd,SAAO,OAAO,cAAc,aAAa,UAAU,GAAG,IAAI,IAAI;AAC/D;AANgB;",
+  "sourcesContent": ["/** Returns a timestamp with nano-second precision */\nexport function highResTimestamp(): number {\n\tif (typeof process !== \"undefined\") {\n\t\tconst [s, ns] = process.hrtime();\n\t\treturn s * 1e9 + ns;\n\t} else if (performance != undefined) {\n\t\treturn performance.now() * 1e6;\n\t} else {\n\t\tthrow new Error(\"No high-resolution timer available\");\n\t}\n}\n\n/** Does nothing. Can be used for empty `.catch(...)` calls. */\nexport function noop(): void {\n\t// intentionally empty\n}\n\nexport type FnOrStatic<TArgs extends any[], TReturn> =\n\t| ((...args: TArgs) => TReturn)\n\t| TReturn;\n\nexport type ReturnTypeOrStatic<T> = T extends (...args: any[]) => infer R\n\t? R\n\t: T;\n\nexport function evalOrStatic<T>(\n\tfnOrConst: T,\n\t...args: any[]\n): ReturnTypeOrStatic<T> {\n\t// @ts-expect-error https://github.com/microsoft/TypeScript/issues/61337\n\treturn typeof fnOrConst === \"function\" ? fnOrConst(...args) : fnOrConst;\n}\n\nexport async function* waitFor<T>(\n\tpromise: Promise<T>,\n): AsyncGenerator<() => Promise<T>, T> {\n\tconst result = yield () => promise;\n\treturn result;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;AACM,SAAU,mBAAgB;AAC/B,MAAI,OAAO,YAAY,aAAa;AACnC,UAAM,CAAC,GAAG,EAAE,IAAI,QAAQ,OAAM;AAC9B,WAAO,IAAI,MAAM;EAClB,WAAW,eAAe,QAAW;AACpC,WAAO,YAAY,IAAG,IAAK;EAC5B,OAAO;AACN,UAAM,IAAI,MAAM,oCAAoC;EACrD;AACD;AATgB;AAYV,SAAU,OAAI;AAEpB;AAFgB;AAYV,SAAU,aACf,cACG,MAAW;AAGd,SAAO,OAAO,cAAc,aAAa,UAAU,GAAG,IAAI,IAAI;AAC/D;AANgB;AAQhB,gBAAuB,QACtB,SAAmB;AAEnB,QAAM,SAAS,MAAM,MAAM;AAC3B,SAAO;AACR;AALuB;",
   "names": []
 }

package/build/esm/index.d.ts

@@ -1,2 +1,3 @@
 export { type Task, type TaskBuilder, TaskInterruptBehavior, TaskPriority, type TaskReturnType, TaskScheduler, TaskState, type TaskStepResult, type TaskConcurrencyGroup, } from "./Task.js";
+export { waitFor } from "./utils.js";
 //# sourceMappingURL=index.d.ts.map

package/build/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,qBAAqB,EACrB,YAAY,EACZ,KAAK,cAAc,EACnB,aAAa,EACb,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,oBAAoB,GACzB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,qBAAqB,EACrB,YAAY,EACZ,KAAK,cAAc,EACnB,aAAa,EACb,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,oBAAoB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/build/esm/index.js

@@ -1,2 +1,3 @@
 export { TaskInterruptBehavior, TaskPriority, TaskScheduler, TaskState, } from "./Task.js";
+export { waitFor } from "./utils.js";
 //# sourceMappingURL=index.js.map

package/build/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,qBAAqB,EACrB,YAAY,EAEZ,aAAa,EACb,SAAS,GAGT,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,qBAAqB,EACrB,YAAY,EAEZ,aAAa,EACb,SAAS,GAGT,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/build/esm/utils.d.ts

@@ -5,4 +5,5 @@ export declare function noop(): void;
 export type FnOrStatic<TArgs extends any[], TReturn> = ((...args: TArgs) => TReturn) | TReturn;
 export type ReturnTypeOrStatic<T> = T extends (...args: any[]) => infer R ? R : T;
 export declare function evalOrStatic<T>(fnOrConst: T, ...args: any[]): ReturnTypeOrStatic<T>;
+export declare function waitFor<T>(promise: Promise<T>): AsyncGenerator<() => Promise<T>, T>;
 //# sourceMappingURL=utils.d.ts.map

package/build/esm/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,wBAAgB,gBAAgB,IAAI,MAAM,CASzC;AAED,+DAA+D;AAC/D,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED,MAAM,MAAM,UAAU,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,OAAO,IAChD,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,GAC7B,OAAO,CAAC;AAEX,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,GACtE,CAAC,GACD,CAAC,CAAC;AAEL,wBAAgB,YAAY,CAAC,CAAC,EAC7B,SAAS,EAAE,CAAC,EACZ,GAAG,IAAI,EAAE,GAAG,EAAE,GACZ,kBAAkB,CAAC,CAAC,CAAC,CAGvB"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,wBAAgB,gBAAgB,IAAI,MAAM,CASzC;AAED,+DAA+D;AAC/D,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED,MAAM,MAAM,UAAU,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,OAAO,IAChD,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,GAC7B,OAAO,CAAC;AAEX,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,GACtE,CAAC,GACD,CAAC,CAAC;AAEL,wBAAgB,YAAY,CAAC,CAAC,EAC7B,SAAS,EAAE,CAAC,EACZ,GAAG,IAAI,EAAE,GAAG,EAAE,GACZ,kBAAkB,CAAC,CAAC,CAAC,CAGvB;AAED,wBAAuB,OAAO,CAAC,CAAC,EAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GACjB,cAAc,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAGrC"}

package/build/esm/utils.js

@@ -19,4 +19,8 @@ export function evalOrStatic(fnOrConst, ...args) {
     // @ts-expect-error https://github.com/microsoft/TypeScript/issues/61337
     return typeof fnOrConst === "function" ? fnOrConst(...args) : fnOrConst;
 }
+export async function* waitFor(promise) {
+    const result = yield () => promise;
+    return result;
+}
 //# sourceMappingURL=utils.js.map

package/build/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,UAAU,gBAAgB;IAC/B,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;QACpC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QACjC,OAAO,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC;IACrB,CAAC;SAAM,IAAI,WAAW,IAAI,SAAS,EAAE,CAAC;QACrC,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC;IAChC,CAAC;SAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACvD,CAAC;AACF,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,IAAI;IACnB,sBAAsB;AACvB,CAAC;AAUD,MAAM,UAAU,YAAY,CAC3B,SAAY,EACZ,GAAG,IAAW;IAEd,wEAAwE;IACxE,OAAO,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,UAAU,gBAAgB;IAC/B,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;QACpC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QACjC,OAAO,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC;IACrB,CAAC;SAAM,IAAI,WAAW,IAAI,SAAS,EAAE,CAAC;QACrC,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC;IAChC,CAAC;SAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACvD,CAAC;AACF,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,IAAI;IACnB,sBAAsB;AACvB,CAAC;AAUD,MAAM,UAAU,YAAY,CAC3B,SAAY,EACZ,GAAG,IAAW;IAEd,wEAAwE;IACxE,OAAO,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC;AAED,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,CAC7B,OAAmB;IAEnB,MAAM,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC;IACnC,OAAO,MAAM,CAAC;AACf,CAAC"}

package/package.json

@@ -4,7 +4,7 @@
     "access": "public"
   },
   "description": "A cooperative task scheduler based on generator functions",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "MIT",
   "type": "module",
   "module": "build/index.js",