@reboot-dev/reboot 0.29.5 → 0.31.0

package/index.d.ts

@@ -1,4 +1,4 @@
-import { errors_pb, IdempotencyOptions, protobuf_es, ScheduleOptions, tasks_pb } from "@reboot-dev/reboot-api";
+import { errors_pb, IdempotencyOptions, protobuf_es, tasks_pb } from "@reboot-dev/reboot-api";
 import { z } from "zod/v4";
 import * as reboot_native from "./reboot_native.cjs";
 import { Application as ExpressApplication, NextFunction as ExpressNextFunction, Request as ExpressRequest, Response as ExpressResponse } from "express";
@@ -42,6 +42,9 @@ export declare class ExternalContext {
     generateIdempotentStateId(stateType: string, serviceName: string, method: string, idempotency: IdempotencyOptions): Promise<string>;
 }
 export declare function getContext(): Context;
+export declare function isWithinUntil(): boolean;
+export declare function isWithinLoop(): boolean;
+export declare function getLoopIteration(): number;
 export declare function runWithContext<T>(context: Context, callback: () => T): Promise<T>;
 export declare class Context {
     #private;
@@ -52,7 +55,6 @@ export declare class Context {
     get auth(): Auth | null;
     get stateId(): string;
     get callerBearerToken(): string | null;
-    get iteration(): number;
     get cookie(): string;
     get appInternal(): boolean;
     generateIdempotentStateId(stateType: string, serviceName: string, method: string, idempotency: IdempotencyOptions): Promise<any>;
@@ -70,9 +72,19 @@ export declare class TransactionContext extends Context {
     #private;
     constructor(external: any, cancelled: any);
 }
+export type Interval = {
+    ms?: number;
+    secs?: number;
+    mins?: number;
+    hours?: number;
+    days?: number;
+};
 export declare class WorkflowContext extends Context {
     #private;
     constructor(external: any, cancelled: any);
+    loop(alias: string, { interval }?: {
+        interval?: Interval;
+    }): AsyncGenerator<number, void, unknown>;
 }
 export declare function clearField(field: any, target: any): void;
 export declare function clearFields(target: any): void;
@@ -214,18 +226,50 @@ export declare namespace Application {
         post(path: Http.Path, ...handlers: Http.Handler[]): void;
     }
 }
-export declare class Loop {
-    when: Date;
-    constructor(options?: ScheduleOptions);
-}
-export declare function retry_reactively_until(context: WorkflowContext, condition: () => Promise<boolean>): Promise<void>;
-export declare function retry_reactively_until<T>(context: WorkflowContext, condition: () => Promise<false | Exclude<T, boolean>>): Promise<Exclude<T, boolean>>;
-export declare function atMostOnce(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<void>, options?: {
+export declare function retryReactivelyUntil(context: WorkflowContext, condition: () => Promise<boolean>): Promise<void>;
+export declare function retryReactivelyUntil<T>(context: WorkflowContext, condition: () => Promise<false | Exclude<T, boolean>>): Promise<Exclude<T, boolean>>;
+export declare const ALWAYS: "ALWAYS";
+export declare const PER_WORKFLOW: "PER_WORKFLOW";
+export declare const PER_ITERATION: "PER_ITERATION";
+export type How = "ALWAYS" | "PER_WORKFLOW" | "PER_ITERATION";
+export type AtMostLeastOnceTupleType = [
+    string,
+    "PER_WORKFLOW" | "PER_ITERATION"
+];
+export declare function atMostOnce(idempotencyAliasOrTuple: string | AtMostLeastOnceTupleType, context: WorkflowContext, callable: () => Promise<void>, options?: {
+    stringify?: undefined;
+    parse?: undefined;
+    validate?: undefined;
+}): Promise<void>;
+export declare function atMostOnce<T>(idempotencyAliasOrTuple: string | AtMostLeastOnceTupleType, context: WorkflowContext, callable: () => Promise<T>, options: {
+    stringify?: (result: T) => string;
+    parse: (value: string) => T;
+    validate?: undefined;
+} | {
+    stringify?: (result: T) => string;
+    parse?: undefined;
+    validate: (result: T) => boolean;
+}): Promise<T>;
+export declare function atMostOncePerWorkflow(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<void>, options?: {
+    stringify?: undefined;
+    parse?: undefined;
+    validate?: undefined;
+}): Promise<void>;
+export declare function atMostOncePerWorkflow<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<T>, options: {
+    stringify?: (result: T) => string;
+    parse: (value: string) => T;
+    validate?: undefined;
+} | {
+    stringify?: (result: T) => string;
+    parse?: undefined;
+    validate: (result: T) => boolean;
+}): Promise<T>;
+export declare function atLeastOnce(idempotencyAliasOrTuple: string | AtMostLeastOnceTupleType, context: WorkflowContext, callable: () => Promise<void>, options?: {
     stringify?: undefined;
     parse?: undefined;
     validate?: undefined;
 }): Promise<void>;
-export declare function atMostOnce<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<T>, options: {
+export declare function atLeastOnce<T>(idempotencyAliasOrTuple: string | AtMostLeastOnceTupleType, context: WorkflowContext, callable: () => Promise<T>, options: {
     stringify?: (result: T) => string;
     parse: (value: string) => T;
     validate?: undefined;
@@ -234,12 +278,12 @@ export declare function atMostOnce<T>(idempotencyAlias: string, context: Workflo
     parse?: undefined;
     validate: (result: T) => boolean;
 }): Promise<T>;
-export declare function atLeastOnce(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<void>, options?: {
+export declare function atLeastOncePerWorkflow(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<void>, options?: {
     stringify?: undefined;
     parse?: undefined;
     validate?: undefined;
 }): Promise<void>;
-export declare function atLeastOnce<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<T>, options: {
+export declare function atLeastOncePerWorkflow<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<T>, options: {
     stringify?: (result: T) => string;
     parse: (value: string) => T;
     validate?: undefined;
@@ -248,12 +292,30 @@ export declare function atLeastOnce<T>(idempotencyAlias: string, context: Workfl
     parse?: undefined;
     validate: (result: T) => boolean;
 }): Promise<T>;
-export declare function until(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<boolean>, options?: {
+export type UntilTupleType = [
+    string,
+    "ALWAYS" | "PER_WORKFLOW" | "PER_ITERATION"
+];
+export declare function until(idempotencyAliasOrTuple: string | UntilTupleType, context: WorkflowContext, callable: () => Promise<boolean>, options?: {
+    stringify?: undefined;
+    parse?: undefined;
+    validate?: undefined;
+}): Promise<void>;
+export declare function until<T>(idempotencyAliasOrTuple: string | UntilTupleType, context: WorkflowContext, callable: () => Promise<false | Exclude<T, boolean>>, options: {
+    stringify?: (result: T) => string;
+    parse: (value: string) => T;
+    validate?: undefined;
+} | {
+    stringify?: (result: T) => string;
+    parse?: undefined;
+    validate: (result: T) => boolean;
+}): Promise<Exclude<T, boolean>>;
+export declare function untilPerWorkflow(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<boolean>, options?: {
     stringify?: undefined;
     parse?: undefined;
     validate?: undefined;
 }): Promise<void>;
-export declare function until<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<false | Exclude<T, boolean>>, options: {
+export declare function untilPerWorkflow<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<false | Exclude<T, boolean>>, options: {
     stringify?: (result: T) => string;
     parse: (value: string) => T;
     validate?: undefined;
@@ -262,6 +324,12 @@ export declare function until<T>(idempotencyAlias: string, context: WorkflowCont
     parse?: undefined;
     validate: (result: T) => boolean;
 }): Promise<Exclude<T, boolean>>;
+export declare function untilChanges<T>(idempotencyAlias: string, context: WorkflowContext, callable: () => Promise<T>, options: {
+    equals: (previous: T, current: T) => boolean;
+    stringify?: (result: T) => string;
+    parse?: (value: string) => T;
+    validate?: (result: T) => boolean;
+}): Promise<T>;
 export declare const zod: {
     tasks: {
         TaskId: z.ZodCustom<protobuf_es.PartialMessage<tasks_pb.TaskId>, protobuf_es.PartialMessage<tasks_pb.TaskId>>;

package/index.js

@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Reboot_external, _ExternalContext_external, _a, _Context_external, _Context_isInternalConstructing, _ReaderContext_kind, _WriterContext_kind, _TransactionContext_kind, _WorkflowContext_kind, _Application_servicers, _Application_tokenVerifier, _Application_express, _Application_http, _Application_servers, _Application_createExternalContext, _Application_external;
+var _Reboot_external, _ExternalContext_external, _a, _Context_external, _Context_isInternalConstructing, _Context_stateId, _ReaderContext_kind, _WriterContext_kind, _TransactionContext_kind, _WorkflowContext_kind, _Application_servicers, _Application_tokenVerifier, _Application_express, _Application_http, _Application_servers, _Application_createExternalContext, _Application_external;
 import { auth_pb, errors_pb, protobuf_es, tasks_pb, } from "@reboot-dev/reboot-api";
 import { strict as assert } from "assert";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -128,18 +128,44 @@ export class ExternalContext {
 _ExternalContext_external = new WeakMap();
 const contextStorage = new AsyncLocalStorage();
 export function getContext() {
-    const context = contextStorage.getStore();
-    if (!context) {
+    const store = contextStorage.getStore();
+    if (!store) {
         throw new Error("`getContext` may only be called within a `Servicer` method.");
     }
-    return context;
+    return store.context;
+}
+export function isWithinUntil() {
+    const store = contextStorage.getStore();
+    if (!store) {
+        throw new Error("`isWithinUntil` may only be called within a `Servicer` method.");
+    }
+    return store.withinUntil;
+}
+export function isWithinLoop() {
+    const store = contextStorage.getStore();
+    if (!store) {
+        throw new Error("`isWithinLoop` may only be called within a `Servicer` method.");
+    }
+    return store.withinLoop;
+}
+export function getLoopIteration() {
+    const store = contextStorage.getStore();
+    if (!store) {
+        throw new Error("`getLoopIteration` may only be called within a `Servicer` method.");
+    }
+    return store.loopIteration;
 }
 export async function runWithContext(context, callback) {
-    return await contextStorage.run(context, callback);
+    return await contextStorage.run({
+        context,
+        withinLoop: false,
+        withinUntil: false,
+    }, callback);
 }
 export class Context {
     constructor(external, cancelled) {
         _Context_external.set(this, void 0);
+        _Context_stateId.set(this, void 0);
         if (!__classPrivateFieldGet(_a, _a, "f", _Context_isInternalConstructing)) {
             throw new TypeError("Context is not publicly constructable");
         }
@@ -174,14 +200,14 @@ export class Context {
         return null;
     }
     get stateId() {
-        return reboot_native.Context_stateId(__classPrivateFieldGet(this, _Context_external, "f"));
+        if (__classPrivateFieldGet(this, _Context_stateId, "f") === undefined) {
+            __classPrivateFieldSet(this, _Context_stateId, reboot_native.Context_stateId(__classPrivateFieldGet(this, _Context_external, "f")), "f");
+        }
+        return __classPrivateFieldGet(this, _Context_stateId, "f");
     }
     get callerBearerToken() {
         return reboot_native.Context_callerBearerToken(__classPrivateFieldGet(this, _Context_external, "f"));
     }
-    get iteration() {
-        return reboot_native.Context_iteration(__classPrivateFieldGet(this, _Context_external, "f"));
-    }
     get cookie() {
         return reboot_native.Context_cookie(__classPrivateFieldGet(this, _Context_external, "f"));
     }
@@ -192,7 +218,7 @@ export class Context {
         return reboot_native.Context_generateIdempotentStateId(__classPrivateFieldGet(this, _Context_external, "f"), stateType, serviceName, method, idempotency);
     }
 }
-_a = Context, _Context_external = new WeakMap();
+_a = Context, _Context_external = new WeakMap(), _Context_stateId = new WeakMap();
 _Context_isInternalConstructing = { value: false };
 export class ReaderContext extends Context {
     constructor(external, cancelled) {
@@ -243,6 +269,41 @@ export class WorkflowContext extends Context {
         // context type that structurally looks equivalent.
         _WorkflowContext_kind.set(this, "workflow");
     }
+    // TODO: implement workflow specific properties/methods.
+    async *loop(alias, { interval } = {}) {
+        const iterate = await reboot_native.WorkflowContext_loop(this.__external, alias);
+        const ms = (interval &&
+            (interval?.ms || 0) +
+                (interval?.secs * 1000 || 0) +
+                (interval?.mins * 60 * 1000 || 0) +
+                (interval?.hours * 60 * 60 * 1000 || 0) +
+                (interval?.days * 24 * 60 * 60 * 1000 || 0)) ||
+            0;
+        const store = contextStorage.getStore();
+        assert(store !== undefined);
+        store.withinLoop = true;
+        let iteration = null;
+        try {
+            while (true) {
+                iteration = await iterate(true);
+                if (iteration === null) {
+                    return;
+                }
+                store.loopIteration = iteration;
+                yield iteration;
+                if (ms > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, ms));
+                }
+            }
+        }
+        finally {
+            if (iteration !== null) {
+                await iterate(false);
+            }
+            store.withinLoop = false;
+            delete store.loopIteration;
+        }
+    }
 }
 _WorkflowContext_kind = new WeakMap();
 // Helper for clearing a specific field of a protobuf-es message.
@@ -613,14 +674,12 @@ _Application_servicers = new WeakMap(), _Application_tokenVerifier = new WeakMap
     _Http_express = new WeakMap(), _Http_createExternalContext = new WeakMap();
     Application.Http = Http;
 })(Application || (Application = {}));
-export class Loop {
-    constructor(options) {
-        this.when = options?.when || new Date();
-    }
-}
-export async function retry_reactively_until(context, condition) {
+export async function retryReactivelyUntil(context, condition) {
     let t = undefined;
-    await reboot_native.retry_reactively_until(context.__external, async () => {
+    await reboot_native.retry_reactively_until(context.__external, AsyncLocalStorage.bind(async () => {
+        const store = contextStorage.getStore();
+        assert(store !== undefined);
+        store.withinUntil = true;
         try {
             const result = await condition();
             if (typeof result === "boolean") {
@@ -632,45 +691,71 @@ export async function retry_reactively_until(context, condition) {
             }
         }
         catch (e) {
-            if (e instanceof Error) {
-                throw e;
-            }
-            else {
-                throw new Error(`${e}`);
-            }
+            const error = ensureError(e);
+            console.error(error);
+            throw error;
         }
-    });
+        finally {
+            store.withinUntil = false;
+        }
+    }));
     return t;
 }
-async function memoize(idempotencyAlias, context, callable, { stringify = JSON.stringify, parse = JSON.parse, validate, atMostOnce, until = false, }) {
+// NOTE: we're not using an enum because the values that can be used in
+// `atMostOnce` and `atLeastOnce` are different than `until`.
+export const ALWAYS = "ALWAYS";
+export const PER_WORKFLOW = "PER_WORKFLOW";
+export const PER_ITERATION = "PER_ITERATION";
+async function memoize(idempotencyAliasOrTuple, context, callable, { stringify = JSON.stringify, parse = JSON.parse, validate, atMostOnce, until = false, }) {
     assert(stringify !== undefined);
     assert(parse !== undefined);
     assert(atMostOnce !== undefined);
-    const result = await reboot_native.memoize(context.__external, idempotencyAlias, async () => {
-        const t = await callable();
-        if (t !== undefined) {
-            if (validate === undefined) {
-                // TODO: link to docs about why this is required, when those docs exist.
-                throw new Error(`Result of function passed to '${atMostOnce ? "atMostOnce" : until ? "until" : "atLeastOnce"}' is not 'boolean' but 'validate' option is undefined`);
+    if (!(typeof idempotencyAliasOrTuple === "string" ||
+        (Array.isArray(idempotencyAliasOrTuple) &&
+            idempotencyAliasOrTuple.length === 2))) {
+        throw new TypeError(`Expecting either a 'string' or a tuple for first argument passed to '${atMostOnce ? "atMostOnce" : until ? "until" : "atLeastOnce"}'`);
+    }
+    const result = await reboot_native.memoize(context.__external, typeof idempotencyAliasOrTuple === "string"
+        ? [idempotencyAliasOrTuple, PER_ITERATION]
+        : idempotencyAliasOrTuple, 
+    // Bind with async local storage so we can check things like
+    // `isWithinLoop`, etc.
+    AsyncLocalStorage.bind(async () => {
+        try {
+            const t = await callable();
+            if (t !== undefined) {
+                if (validate === undefined) {
+                    // TODO: link to docs about why this is required, when those docs exist.
+                    throw new Error(`Result of function passed to '${atMostOnce ? "atMostOnce" : until ? "until" : "atLeastOnce"}' is not 'boolean' but 'validate' option is undefined`);
+                }
+                else if (!validate(t)) {
+                    throw new Error(`Calling 'validate' on result of function passed to '${atMostOnce ? "atMostOnce" : until ? "until" : "atLeastOnce"}' returned 'false'`);
+                }
+                // NOTE: to differentiate `callable` returning `void` (or
+                // explicitly `undefined`) from `stringify` returning an empty
+                // string we use `{ value: stringify(t) }`.
+                const result = { value: stringify(t) };
+                return JSON.stringify(result);
             }
-            else if (!validate(t)) {
-                throw new Error(`Calling 'validate' on result of function passed to '${atMostOnce ? "atMostOnce" : until ? "until" : "atLeastOnce"}' returned 'false'`);
+            // Fail early if the developer thinks that they have some value
+            // that they want to validate but we got `undefined`.
+            if (validate !== undefined) {
+                throw new Error("Not expecting `validate` as you are returning `void` (or explicitly `undefined`); did you mean to return a value (or if you want to explicitly return the absence of a value use `null`)");
             }
-            // NOTE: to differentiate `callable` returning `void` (or
-            // explicitly `undefined`) from `stringify` returning an empty
-            // string we use `{ value: stringify(t) }`.
-            const result = { value: stringify(t) };
-            return JSON.stringify(result);
-        }
-        // Fail early if the developer thinks that they have some value
-        // that they want to validate but we got `undefined`.
-        if (validate !== undefined) {
-            throw new Error("Not expecting `validate` as you are returning `void` (or explicitly `undefined`); did you mean to return a value (or if you want to explicitly return the absence of a value use `null`)");
-        }
-        // NOTE: using the empty string to represent a `callable`
-        // returning `void` (or explicitly `undefined`).
-        return "";
-    }, atMostOnce);
+            // NOTE: using the empty string to represent a `callable`
+            // returning `void` (or explicitly `undefined`).
+            return "";
+        }
+        catch (e) {
+            const error = ensureError(e);
+            // We handle printing the exception for `until` in
+            // `retryReactivelyUntil`.
+            if (!until) {
+                console.error(error);
+            }
+            throw error;
+        }
+    }), atMostOnce, until);
     // NOTE: we parse and validate `value` every time (even the first
     // time, even though we validate above). These semantics are the
     // same as Python (although Python uses the `type` keyword argument
@@ -692,9 +777,9 @@ async function memoize(idempotencyAlias, context, callable, { stringify = JSON.s
     // Otherwise `callable` must have returned void (or explicitly
     // `undefined`), fall through.
 }
-export async function atMostOnce(idempotencyAlias, context, callable, options = { validate: undefined }) {
+export async function atMostOnce(idempotencyAliasOrTuple, context, callable, options = { validate: undefined }) {
     try {
-        return await memoize(idempotencyAlias, context, callable, {
+        return await memoize(idempotencyAliasOrTuple, context, callable, {
             ...options,
             atMostOnce: true,
         });
@@ -706,25 +791,67 @@ export async function atMostOnce(idempotencyAlias, context, callable, options =
         throw e;
     }
 }
-export async function atLeastOnce(idempotencyAlias, context, callable, options = { validate: undefined }) {
-    return memoize(idempotencyAlias, context, callable, {
+export async function atMostOncePerWorkflow(idempotencyAlias, context, callable, options = { validate: undefined }) {
+    return atMostOnce([idempotencyAlias, PER_WORKFLOW], context, callable, options);
+}
+export async function atLeastOnce(idempotencyAliasOrTuple, context, callable, options = { validate: undefined }) {
+    return memoize(idempotencyAliasOrTuple, context, callable, {
         ...options,
         atMostOnce: false,
     });
 }
-export async function until(idempotencyAlias, context, callable, options = { validate: undefined }) {
+export async function atLeastOncePerWorkflow(idempotencyAlias, context, callable, options = { validate: undefined }) {
+    return await atLeastOnce([idempotencyAlias, PER_WORKFLOW], context, callable, options);
+}
+export async function until(idempotencyAliasOrTuple, context, callable, options = { validate: undefined }) {
     // TODO(benh): figure out how to not use `as` type assertions here
     // to appease the TypeScript compiler which otherwise isn't happy
     // with passing on these types.
     const converge = () => {
-        return retry_reactively_until(context, callable);
+        return retryReactivelyUntil(context, callable);
     };
-    return memoize(idempotencyAlias, context, converge, {
+    // TODO: should we not memoize if passed `ALWAYS`? There still might
+    // be value in having a "paper trail" of what happened ...
+    return memoize(idempotencyAliasOrTuple, context, converge, {
         ...options,
         atMostOnce: false,
         until: true,
     });
 }
+export async function untilPerWorkflow(idempotencyAlias, context, callable, options = { validate: undefined }) {
+    return await until([idempotencyAlias, PER_WORKFLOW], context, callable, options);
+}
+export async function untilChanges(idempotencyAlias, context, callable, options) {
+    const iteration = getLoopIteration();
+    if (iteration === undefined) {
+        throw new Error("Waiting for changes must be done _within_ a control loop");
+    }
+    if (options.equals === undefined) {
+        // TODO: don't make `equals` required, instead use one of the
+        // various libraries that does deep equality.
+        throw new Error("Missing 'equals' option");
+    }
+    const { equals, ...optionsWithoutEquals } = options;
+    let previous = null;
+    if (iteration > 0) {
+        // Get the previous memoized result!
+        previous = (await untilPerWorkflow(`${idempotencyAlias} #${iteration - 1}`, context, (async () => {
+            throw new Error(`Missing memoized value for '${idempotencyAlias}'`);
+        }), optionsWithoutEquals));
+    }
+    // Wait until previous result does not equal current result.
+    return (await untilPerWorkflow(`${idempotencyAlias} #${iteration}`, context, (async () => {
+        const current = await callable();
+        if (iteration === 0) {
+            return current;
+        }
+        assert(previous !== null);
+        if (!equals(previous, current)) {
+            return current;
+        }
+        return false;
+    }), optionsWithoutEquals));
+}
 const launchSubprocessConsensus = (base64_args) => {
     // Create a child process via `fork` (which does not mean `fork` as
     // in POSIX fork/clone) that uses the exact same module that was

package/package.json

@@ -3,7 +3,7 @@
     "@bufbuild/protobuf": "1.3.2",
     "@bufbuild/protoplugin": "1.3.2",
     "@bufbuild/protoc-gen-es": "1.3.2",
-    "@reboot-dev/reboot-api": "0.29.5",
+    "@reboot-dev/reboot-api": "0.31.0",
     "chalk": "^4.1.2",
     "node-addon-api": "^7.0.0",
     "node-gyp": ">=10.2.0",
@@ -18,7 +18,7 @@
   },
   "type": "module",
   "name": "@reboot-dev/reboot",
-  "version": "0.29.5",
+  "version": "0.31.0",
   "description": "npm package for Reboot",
   "scripts": {
     "preinstall": "node preinstall.cjs",

package/reboot_native.cc

@@ -1533,7 +1533,7 @@ py::list make_py_servicers(
 
   // Include memoize servicers by default!
   py_servicers.attr("extend")(
-      py::module::import("reboot.aio.memoize").attr("servicers")());
+      py::module::import("rebootdev.aio.memoize").attr("servicers")());
 
   return py_servicers;
 }
@@ -2401,33 +2401,6 @@ Napi::Value Context_callerBearerToken(
 }
 
 
-Napi::Value Context_iteration(const Napi::CallbackInfo& info) {
-  Napi::External<py::object> js_external_context =
-      info[0].As<Napi::External<py::object>>();
-
-  // CHECK(...CheckTypeTag(...));
-
-  py::object* py_context = js_external_context.Data();
-
-  std::optional<int> iteration = RunCallbackOnPythonEventLoop(
-      [py_context]() -> std::optional<int> {
-        py::object iteration = py_context->attr("iteration");
-
-        if (iteration.is_none()) {
-          return std::nullopt;
-        } else {
-          return iteration.cast<int>();
-        }
-      });
-
-  if (iteration.has_value()) {
-    return Napi::Number::New(info.Env(), *iteration);
-  } else {
-    return info.Env().Undefined();
-  }
-}
-
-
 Napi::Value Context_cookie(const Napi::CallbackInfo& info) {
   Napi::External<py::object> js_external_context =
       info[0].As<Napi::External<py::object>>();
@@ -2493,6 +2466,11 @@ Napi::Value Context_generateIdempotentStateId(const Napi::CallbackInfo& info) {
   if (js_alias.IsString()) {
     alias = js_alias.As<Napi::String>().Utf8Value();
   }
+  auto js_each_iteration = idempotency_options.Get("eachIteration");
+  std::optional<bool> each_iteration;
+  if (js_each_iteration.IsBoolean()) {
+    each_iteration = js_each_iteration.As<Napi::Boolean>();
+  }
 
   return NodePromiseFromPythonCallback(
       info.Env(),
@@ -2502,21 +2480,34 @@ Napi::Value Context_generateIdempotentStateId(const Napi::CallbackInfo& info) {
        service_name = std::move(service_name),
        method = std::move(method),
        key = std::move(key),
-       alias = std::move(alias)]() {
-        py::object py_key = py::none();
-        if (key.has_value()) {
-          py_key = py::cast(*key);
-        }
-        py::object py_alias = py::none();
-        if (alias.has_value()) {
-          py_alias = py::cast(*alias);
-        }
-        py::object py_idempotency_module = py::module::import(
-            "rebootdev.aio.idempotency");
-        py::object py_idempotency = py::object(
-            py_idempotency_module.attr("Idempotency")(
-                "key"_a = py_key,
-                "alias"_a = py_alias));
+       alias = std::move(alias),
+       each_iteration = std::move(each_iteration)]() {
+        // Need to use `call_with_context` to ensure that we have
+        // `py_context` as a valid asyncio context variable.
+        py::object py_idempotency =
+            py::module::import("rebootdev.nodejs.python")
+                .attr("call_with_context")(
+                    py::cpp_function([&]() {
+                      py::object py_key = py::none();
+                      if (key.has_value()) {
+                        py_key = py::cast(*key);
+                      }
+                      py::object py_alias = py::none();
+                      if (alias.has_value()) {
+                        py_alias = py::cast(*alias);
+                      }
+                      py::object py_each_iteration = py::none();
+                      if (each_iteration.has_value()) {
+                        py_each_iteration = py::cast(*each_iteration);
+                      }
+                      return py::module::import("rebootdev.aio.contexts")
+                          .attr("Context")
+                          .attr("idempotency")(
+                              "key"_a = py_key,
+                              "alias"_a = py_alias,
+                              "each_iteration"_a = py_each_iteration);
+                    }),
+                    py_context);
 
         py::object py_generate_idempotent_state_id =
             py_context->attr("generate_idempotent_state_id");
@@ -2555,6 +2546,71 @@ Napi::Value WriterContext_set_sync(const Napi::CallbackInfo& info) {
 }
 
 
+Napi::Value WorkflowContext_loop(const Napi::CallbackInfo& info) {
+  auto js_external_context = NapiSafeReference(
+      info[0].As<Napi::External<py::object>>());
+
+  // CHECK(...CheckTypeTag(...));
+
+  py::object* py_context = js_external_context.Value(info.Env()).Data();
+
+  std::string alias = info[1].As<Napi::String>().Utf8Value();
+
+  return NodePromiseFromPythonTaskWithContext(
+      info.Env(),
+      "context.loop(...) in nodejs",
+      js_external_context,
+      [js_external_context, // Ensures `py_context` remains valid.
+       py_context,
+       alias = std::move(alias)]() {
+        return py::module::import("rebootdev.nodejs.python")
+            .attr("loop")(py_context, alias);
+      },
+      [](py::object py_iterate) {
+        return new py::object(py_iterate);
+      },
+      [js_external_context](Napi::Env env, py::object* py_iterate) mutable {
+        Napi::External<py::object> js_iterate_external =
+            make_napi_external(env, py_iterate);
+
+        Napi::Function js_iterate =
+            Napi::Function::New(
+                env,
+                [js_external_context,
+                 js_iterate_external = // Ensures `py_iterate` remains valid.
+                 NapiSafeReference(js_iterate_external),
+                 py_iterate](
+                    const Napi::CallbackInfo& info) mutable {
+                  bool more = info[0].As<Napi::Boolean>();
+                  return NodePromiseFromPythonTaskWithContext(
+                      info.Env(),
+                      "iterate(...) in nodejs",
+                      js_external_context,
+                      [js_iterate_external, py_iterate, more]() {
+                        return (*py_iterate)(more);
+                      },
+                      [](py::object py_iteration) -> std::optional<int> {
+                        if (!py_iteration.is_none()) {
+                          return py_iteration.cast<int>();
+                        } else {
+                          return std::nullopt;
+                        }
+                      },
+                      [](Napi::Env env,
+                         std::optional<int>&& iteration) -> Napi::Value {
+                        if (iteration.has_value()) {
+                          return Napi::Number::New(env, *iteration);
+                        } else {
+                          return env.Null();
+                        }
+                      });
+                });
+
+        return js_iterate;
+      });
+}
+
+
 Napi::Value retry_reactively_until(const Napi::CallbackInfo& info) {
   auto js_external_context = NapiSafeReference(
       info[0].As<Napi::External<py::object>>());
@@ -2605,22 +2661,30 @@ Napi::Value memoize(const Napi::CallbackInfo& info) {
 
   py::object* py_context = js_external_context.Value(info.Env()).Data();
 
-  std::string idempotency_alias = info[1].As<Napi::String>().Utf8Value();
+  Napi::Object idempotency_tuple = info[1].As<Napi::Array>();
+  auto js_alias = idempotency_tuple.Get((uint32_t) 0);
+  std::string alias = js_alias.As<Napi::String>().Utf8Value();
+  auto js_how = idempotency_tuple.Get((uint32_t) 1);
+  std::string how = js_how.As<Napi::String>().Utf8Value();
 
   auto js_callable = NapiSafeFunctionReference(
       info[2].As<Napi::Function>());
 
   bool at_most_once = info[3].As<Napi::Boolean>();
 
+  bool until = info[4].As<Napi::Boolean>();
+
   return NodePromiseFromPythonTaskWithContext(
       info.Env(),
       "memoize(...) in nodejs",
       js_external_context,
       [js_external_context, // Ensures `py_context` remains valid.
        py_context,
+       alias = std::move(alias),
+       how = std::move(how),
        js_callable = std::move(js_callable),
-       idempotency_alias = std::move(idempotency_alias),
-       at_most_once]() {
+       at_most_once,
+       until]() {
         py::object py_callable = py::cpp_function(
             [js_callable = std::move(js_callable)]() mutable {
               return PythonFutureFromNodePromise(
@@ -2637,13 +2701,14 @@ Napi::Value memoize(const Napi::CallbackInfo& info) {
                   });
             });
 
-        return py::module::import("reboot.aio.memoize")
+        return py::module::import("rebootdev.aio.memoize")
             .attr("memoize")(
-                py::str(idempotency_alias),
+                py::make_tuple(alias, how),
                 py_context,
                 py_callable,
                 "type_t"_a = py::eval("str"),
-                "at_most_once"_a = at_most_once);
+                "at_most_once"_a = at_most_once,
+                "until"_a = until);
       },
       [](py::object py_json) {
         return py_json.cast<std::string>();
@@ -2667,6 +2732,8 @@ Napi::Value Servicer_read(const Napi::CallbackInfo& info) {
 
   // CHECK(...CheckTypeTag(...));
 
+  std::string json_options = info[2].As<Napi::String>().Utf8Value();
+
   py::object* py_context = js_external_context.Value(info.Env()).Data();
 
   return NodePromiseFromPythonTaskWithContext(
@@ -2676,8 +2743,9 @@ Napi::Value Servicer_read(const Napi::CallbackInfo& info) {
       [js_external_servicer, // Ensures `py_servicer` remains valid.
        py_servicer,
        js_external_context, // Ensures `py_context` remains valid.
-       py_context]() {
-        return py_servicer->attr("_read")(py_context);
+       py_context,
+       json_options = std::move(json_options)]() {
+        return py_servicer->attr("_read")(py_context, json_options);
       },
       [](py::object py_json) {
         return py_json.cast<std::string>();
@@ -2815,10 +2883,6 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
       Napi::String::New(env, "Context_callerBearerToken"),
       Napi::Function::New<Context_callerBearerToken>(env));
 
-  exports.Set(
-      Napi::String::New(env, "Context_iteration"),
-      Napi::Function::New<Context_iteration>(env));
-
   exports.Set(
       Napi::String::New(env, "Context_cookie"),
       Napi::Function::New<Context_cookie>(env));
@@ -2835,6 +2899,10 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
       Napi::String::New(env, "WriterContext_set_sync"),
       Napi::Function::New<WriterContext_set_sync>(env));
 
+  exports.Set(
+      Napi::String::New(env, "WorkflowContext_loop"),
+      Napi::Function::New<WorkflowContext_loop>(env));
+
   exports.Set(
       Napi::String::New(env, "retry_reactively_until"),
       Napi::Function::New<retry_reactively_until>(env));

package/reboot_native.cjs

@@ -80,10 +80,10 @@ exports.Context_callerBearerToken =
   reboot_native.exports.Context_callerBearerToken;
 exports.Context_cookie = reboot_native.exports.Context_cookie;
 exports.Context_appInternal = reboot_native.exports.Context_appInternal;
-exports.Context_iteration = reboot_native.exports.Context_iteration;
 exports.Context_generateIdempotentStateId =
   reboot_native.exports.Context_generateIdempotentStateId;
 exports.WriterContext_set_sync = reboot_native.exports.WriterContext_set_sync;
+exports.WorkflowContext_loop = reboot_native.exports.WorkflowContext_loop;
 exports.retry_reactively_until = reboot_native.exports.retry_reactively_until;
 exports.memoize = reboot_native.exports.memoize;
 exports.Servicer_read = reboot_native.exports.Servicer_read;

package/version.d.ts

@@ -1 +1 @@
-export declare const REBOOT_VERSION = "0.29.5";
+export declare const REBOOT_VERSION = "0.31.0";

package/version.js

@@ -1 +1 @@
-export const REBOOT_VERSION = "0.29.5";
+export const REBOOT_VERSION = "0.31.0";