@reboot-dev/reboot 0.28.0 → 0.29.1

package/index.d.ts

@@ -1,4 +1,5 @@
-import { errors_pb, IdempotencyOptions, protobuf_es, ScheduleOptions } from "@reboot-dev/reboot-api";
+import { errors_pb, IdempotencyOptions, protobuf_es, ScheduleOptions, 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";
 export { reboot_native };
@@ -160,8 +161,8 @@ export declare abstract class AuthorizerRule<StateType, RequestType> {
         request?: RequestType;
     }): Promise<AuthorizerDecision>;
 }
-export declare function deny(): AuthorizerRule<protobuf_es.Message, protobuf_es.Message>;
-export declare function allow(): AuthorizerRule<protobuf_es.Message, protobuf_es.Message>;
+export declare function deny(): AuthorizerRule<any, any>;
+export declare function allow(): AuthorizerRule<any, any>;
 export declare function allowIf<StateType, RequestType>(args: {
     all: AuthorizerCallable<StateType, RequestType>[];
     any?: never;
@@ -172,13 +173,13 @@ export declare function allowIf<StateType, RequestType>(args: {
 }): AuthorizerRule<StateType, RequestType>;
 export declare function hasVerifiedToken({ context, }: {
     context: ReaderContext;
-    state?: protobuf_es.Message;
-    request?: protobuf_es.Message;
+    state?: any;
+    request?: any;
 }): errors_pb.Unauthenticated | errors_pb.Ok;
 export declare function isAppInternal({ context, }: {
     context: ReaderContext;
-    state?: protobuf_es.Message;
-    request?: protobuf_es.Message;
+    state?: any;
+    request?: any;
 }): errors_pb.PermissionDenied | errors_pb.Ok;
 export declare class Application {
     #private;
@@ -213,10 +214,6 @@ export declare namespace Application {
         post(path: Http.Path, ...handlers: Http.Handler[]): void;
     }
 }
-/**
- * @deprecated testWithReboot is deprecated in favor of the manual start of Reboot in the test setup.
- */
-export declare function testWithReboot(name: string, body: (t: any, rbt: Reboot) => Promise<void>): void;
 export declare class Loop {
     when: Date;
     constructor(options?: ScheduleOptions);
@@ -265,3 +262,9 @@ export declare function until<T>(idempotencyAlias: string, context: WorkflowCont
     parse?: undefined;
     validate: (result: T) => boolean;
 }): Promise<Exclude<T, boolean>>;
+export declare const zod: {
+    tasks: {
+        TaskId: z.ZodCustom<protobuf_es.PartialMessage<tasks_pb.TaskId>, protobuf_es.PartialMessage<tasks_pb.TaskId>>;
+    };
+    bytes: z.ZodCustom<Uint8Array, Uint8Array>;
+};

package/index.js

@@ -10,12 +10,12 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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;
-import { auth_pb, errors_pb, protobuf_es, } from "@reboot-dev/reboot-api";
+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";
 import { fork } from "node:child_process";
 import { createRequire } from "node:module";
-import { test } from "node:test";
+import { z } from "zod/v4";
 import * as reboot_native from "./reboot_native.cjs";
 import { ensureError } from "./utils/errors.js";
 import { ensurePythonVenv } from "./venv.js";
@@ -613,22 +613,6 @@ _Application_servicers = new WeakMap(), _Application_tokenVerifier = new WeakMap
     _Http_express = new WeakMap(), _Http_createExternalContext = new WeakMap();
     Application.Http = Http;
 })(Application || (Application = {}));
-/**
- * @deprecated testWithReboot is deprecated in favor of the manual start of Reboot in the test setup.
- */
-export function testWithReboot(name, body) {
-    console.warn("testWithReboot is deprecated and will be removed in the future.");
-    test(name, async (t) => {
-        const rbt = new Reboot();
-        await rbt.start();
-        try {
-            await body(t, rbt);
-        }
-        finally {
-            await rbt.stop();
-        }
-    });
-}
 export class Loop {
     constructor(options) {
         this.when = options?.when || new Date();
@@ -658,13 +642,20 @@ export async function retry_reactively_until(context, condition) {
     });
     return t;
 }
-async function atLeastOrMostOnce(idempotencyAlias, context, callable, { stringify = JSON.stringify, parse = JSON.parse, validate, atMostOnce, }) {
+async function memoize(idempotencyAlias, 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.atLeastOrMostOnce(context.__external, idempotencyAlias, async () => {
+    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`);
+            }
+            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) }`.
@@ -680,25 +671,20 @@ async function atLeastOrMostOnce(idempotencyAlias, context, callable, { stringif
         // returning `void` (or explicitly `undefined`).
         return "";
     }, atMostOnce);
-    // NOTE: we parse and validate `value` every time, even the first
-    // time, so as to catch bugs where the `value` returned from
-    // `callable` might not parse or be valid. We will have already
-    // persisted `result`, so in the event of a bug the developer will
-    // have to change the idempotency alias so that `callable` is
-    // re-executed. These semantics are the same as Python (although
-    // Python uses the `type` keyword argument instead of the
-    // `parse` and `validate` properties we use here).
+    // 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
+    // instead of the `parse` and `validate` properties we use here).
     assert(result !== undefined);
     if (result !== "") {
         const { value } = JSON.parse(result);
         const t = parse(value);
         if (parse !== JSON.parse) {
             if (validate === undefined) {
-                // TODO: link to docs about why this is required, when those docs exist.
-                throw new Error("Missing `validate` property");
+                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("Failed to validate memoized result");
+                throw new Error(`Calling 'validate' on result of function passed to '${atMostOnce ? "atMostOnce" : until ? "until" : "atLeastOnce"}' returned 'false'`);
             }
         }
         return t;
@@ -708,7 +694,7 @@ async function atLeastOrMostOnce(idempotencyAlias, context, callable, { stringif
 }
 export async function atMostOnce(idempotencyAlias, context, callable, options = { validate: undefined }) {
     try {
-        return await atLeastOrMostOnce(idempotencyAlias, context, callable, {
+        return await memoize(idempotencyAlias, context, callable, {
             ...options,
             atMostOnce: true,
         });
@@ -721,7 +707,7 @@ export async function atMostOnce(idempotencyAlias, context, callable, options =
     }
 }
 export async function atLeastOnce(idempotencyAlias, context, callable, options = { validate: undefined }) {
-    return atLeastOrMostOnce(idempotencyAlias, context, callable, {
+    return memoize(idempotencyAlias, context, callable, {
         ...options,
         atMostOnce: false,
     });
@@ -733,7 +719,11 @@ export async function until(idempotencyAlias, context, callable, options = { val
     const converge = () => {
         return retry_reactively_until(context, callable);
     };
-    return atLeastOnce(idempotencyAlias, context, converge, options);
+    return memoize(idempotencyAlias, context, converge, {
+        ...options,
+        atMostOnce: false,
+        until: true,
+    });
 }
 const launchSubprocessConsensus = (base64_args) => {
     // Create a child process via `fork` (which does not mean `fork` as
@@ -756,3 +746,43 @@ const callback = (...args) => {
 };
 ensurePythonVenv();
 reboot_native.initialize(callback, Context.fromNativeExternal, launchSubprocessConsensus);
+// TODO: move these into @reboot-dev/reboot-api and also generate them
+// via plugin, perhaps via a new plugin which emits the Zod schemas
+// for all protobuf messages, which might be easier after we've moved
+// to protobuf-es v2 which has more natural TypeScript types.
+function protobufToZodSchema(type) {
+    return z
+        .custom((t) => {
+        // TODO: replace this with `protobuf_es.isMessage` after upgrading
+        // '@bufbuild/protobuf'.
+        if (t instanceof type) {
+            return true;
+        }
+        if (typeof t === "object" && "getType" in t) {
+            if (typeof t.getType === "function") {
+                const actualType = t.getType();
+                if (typeof actualType === "function" && "typeName" in actualType) {
+                    return actualType.typeName === type.typeName;
+                }
+            }
+        }
+        try {
+            type.fromJson(t);
+            return true;
+        }
+        catch (e) {
+            return false;
+        }
+    })
+        .meta({ protobuf: type.typeName });
+}
+export const zod = {
+    tasks: {
+        TaskId: protobufToZodSchema(tasks_pb.TaskId),
+    },
+    bytes: z
+        .custom((array) => {
+        return array instanceof Uint8Array;
+    })
+        .meta({ protobuf: "bytes" }),
+};

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.28.0",
+    "@reboot-dev/reboot-api": "0.29.1",
     "chalk": "^4.1.2",
     "node-addon-api": "^7.0.0",
     "node-gyp": ">=10.2.0",
@@ -12,11 +12,13 @@
     "extensionless": "^1.9.9",
     "esbuild": "^0.24.0",
     "express": "^5.1.0",
-    "@scarf/scarf": "1.4.0"
+    "@scarf/scarf": "1.4.0",
+    "tsx": "^4.19.2",
+    "zod": "^3.25.51"
   },
   "type": "module",
   "name": "@reboot-dev/reboot",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "npm package for Reboot",
   "scripts": {
     "preinstall": "node preinstall.cjs",
@@ -26,7 +28,7 @@
     "prepack": "tsc"
   },
   "devDependencies": {
-    "typescript": ">=4.9.5",
+    "typescript": "5.4.5",
     "@types/express": "^5.0.1",
     "@types/node": "20.11.5",
     "@types/uuid": "^9.0.4",
@@ -35,6 +37,7 @@
   "bin": {
     "rbt": "./rbt.js",
     "rbt-esbuild": "./rbt-esbuild.js",
+    "rbt-schema-to-proto": "./rbt-schema-to-proto.js",
     "protoc-gen-es": "./protoc-gen-es.js"
   },
   "engines": {
@@ -54,6 +57,8 @@
     "rbt.d.ts",
     "rbt-esbuild.d.ts",
     "rbt-esbuild.js",
+    "rbt-schema-to-proto.d.ts",
+    "rbt-schema-to-proto.js",
     "rbt.js",
     "index.d.ts",
     "index.js",

package/rbt-schema-to-proto.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+export {};

package/rbt-schema-to-proto.js

@@ -0,0 +1,597 @@
+#!/usr/bin/env tsx
+import { toPascalCase, toSnakeCase, ZOD_ERROR_NAMES, } from "@reboot-dev/reboot-api";
+import { strict as assert } from "assert";
+import chalk from "chalk";
+import { mkdtemp } from "fs/promises";
+import * as fs from "node:fs";
+import * as os from "os";
+import * as path from "path";
+import { z } from "zod/v4";
+// Expected usage: rbt-schema-to-protoc filesDirectory path/relative/to/filesDirectory/to/file.ts ...
+const args = process.argv.slice(2);
+const filesDirectory = args[0];
+const files = args.slice(1);
+const requestSchema = z.union([
+    z.instanceof(z.ZodObject),
+    z.record(z.string(), z.instanceof(z.ZodType)),
+]);
+const responseSchema = z.union([
+    z.instanceof(z.ZodObject),
+    z.record(z.string(), z.instanceof(z.ZodType)),
+    z.instanceof(z.ZodVoid),
+]);
+const errorsSchema = z.union([
+    z.tuple([z.instanceof(z.ZodObject)], z.instanceof(z.ZodObject)),
+    z.instanceof(z.ZodDiscriminatedUnion),
+]);
+const typeSchema = z.object({
+    state: z.union([
+        z.instanceof(z.ZodObject),
+        z.record(z.string(), z.instanceof(z.ZodType)),
+    ]),
+    methods: z.record(z.string(), z.discriminatedUnion("kind", [
+        z.object({
+            kind: z.literal(["reader", "workflow"]),
+            request: requestSchema,
+            response: responseSchema,
+            errors: errorsSchema.optional(),
+        }),
+        z.object({
+            kind: z.literal(["writer", "transaction"]),
+            factory: z.object({}).optional(),
+            request: requestSchema,
+            response: responseSchema,
+            errors: errorsSchema.optional(),
+        }),
+    ])),
+});
+// TODO:
+//
+// z.date (use well-known proto)
+// z.enum (only support number enums)
+// "recursive types"
+// z.map (use protobuf map and only allow the mapped types that protobuf supports)
+// z.set (use protobuf repeated but the fact that we must take a `Set` will ensure it's a set, and we could add annotations to do proto validations for other languages)
+// z.tuple
+//
+// UNREPRESENTABLE:
+//
+// z.union is unlikely because if it is not "flattened" we won't know
+// which fields to set when there are multiple possible "correct" fields
+//
+// z.intersection (suggest destructuring as that's what Zod suggests)
+const Z_JSON_GETTER_TO_STRING = z.json()._zod.def.getter.toString();
+const iszjson = (schema) => {
+    return (schema instanceof z.ZodLazy &&
+        schema._zod.def.getter?.toString() === Z_JSON_GETTER_TO_STRING);
+};
+const generate = (proto, { schema, path, name, state = false, }) => {
+    if (schema instanceof z.ZodObject) {
+        assert(name !== undefined);
+        proto.write(`message ${name} {`);
+        if (state) {
+            proto.write(`option (rbt.v1alpha1.state) = {};`);
+        }
+        const tags = new Map();
+        const shape = schema._zod.def.shape;
+        for (const key in shape) {
+            // TODO: ensure `key` is PascalCase.
+            let value = shape[key];
+            if (value === undefined || value._zod.def === undefined) {
+                // TODO: is this expected or possible or should we raise here
+                // instead?
+                continue;
+            }
+            const meta = value.meta();
+            if (meta === undefined || !("tag" in meta)) {
+                console.error(chalk.stderr.bold.red(`Missing tag for property '${key}'; all properties of your object schemas must be tagged for backwards compatibility`));
+                process.exit(-1);
+            }
+            const { tag } = meta;
+            if (tags.has(tag)) {
+                // TODO: give "path" to this property.
+                console.error(chalk.stderr.bold.red(`Trying to use tag ${tag} with property '${key}' already used by '${tags.get(tag)}'`));
+                process.exit(-1);
+            }
+            tags.set(tag, key);
+            const field = toSnakeCase(key);
+            if (value instanceof z.ZodPipe) {
+                value = value.in;
+            }
+            else if (value instanceof z.ZodOptional) {
+                value = value._zod.def.innerType;
+            }
+            else if (value instanceof z.ZodDefault) {
+                const firstDefaultValue = value._zod.def.defaultValue;
+                const secondDefaultValue = value._zod.def.defaultValue;
+                switch (typeof firstDefaultValue) {
+                    case "object":
+                        if (firstDefaultValue === secondDefaultValue) {
+                            console.error(chalk.stderr.bold.red(`'${path}.${key}' has a default value of type ` +
+                                `${Array.isArray(firstDefaultValue) ? "array" : "object"} which ` +
+                                `is dangerous and not supported, please use a ` +
+                                `primitive type (e.g., string, number, boolean) ` +
+                                `which is immutable or pass a function that creates ` +
+                                `a new ${Array.isArray(firstDefaultValue) ? "array" : "object"} ` +
+                                `each time\n`));
+                            process.exit(-1);
+                        }
+                        // Otherwise, if objects are different, that means that
+                        // the default value is a function that returns a new
+                        // object each time, which is fine.
+                        break;
+                    default:
+                        break;
+                }
+                value = value._zod.def.innerType;
+            }
+            if (value._zod.def.type === "string") {
+                proto.write(`optional string ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "number") {
+                proto.write(`optional double ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "bigint") {
+                proto.write(`optional int64 ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "boolean") {
+                proto.write(`optional bool ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "literal") {
+                // Make the name of this nested type be the PascalCase property
+                // TODO: ensure `key` is already camelCase.
+                const typeName = key.charAt(0).toUpperCase() + key.slice(1);
+                proto.write(`enum ${typeName} {`);
+                let i = 0;
+                for (const literal of value._zod.def.values) {
+                    if (typeof literal !== "string") {
+                        console.error(chalk.stderr.bold.red(`Unexpected literal '${literal}' for property '${key}'; only 'string' literals are currently supported`));
+                        process.exit(-1);
+                    }
+                    proto.write(`${literal} = ${i++};`);
+                }
+                proto.write(`}`);
+                proto.write(`optional ${typeName} ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "array") {
+                // Make the name of this nested type be the PascalCase property
+                // TODO: ensure `key` is already camelCase.
+                const typeName = key.charAt(0).toUpperCase() + key.slice(1) + "Array";
+                proto.write(`message ${typeName} {`);
+                generate(proto, { schema: value, path: `${path}.${key}` });
+                proto.write(`}`);
+                proto.write(`optional ${typeName} ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "record") {
+                // Make the name of this nested type be the PascalCase property
+                // TODO: ensure `key` is already camelCase.
+                const typeName = key.charAt(0).toUpperCase() + key.slice(1) + "Record";
+                proto.write(`message ${typeName} {`);
+                generate(proto, { schema: value, path: `${path}.${key}` });
+                proto.write(`}`);
+                proto.write(`optional ${typeName} ${field} = ${tag};`);
+            }
+            else if (value instanceof z.ZodDiscriminatedUnion) {
+                // `instanceof` b.c. type = "union".
+                // Make the name of this nested type be the PascalCase property
+                // TODO: ensure `key` is already camelCase.
+                const typeName = key.charAt(0).toUpperCase() + key.slice(1);
+                generate(proto, {
+                    schema: value,
+                    path: `${path}.${key}`,
+                    name: typeName,
+                });
+                proto.write(`optional ${typeName} ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "object") {
+                // Make the name of this nested type be the PascalCase property.
+                const typeName = key.charAt(0).toUpperCase() + key.slice(1);
+                generate(proto, {
+                    schema: value,
+                    path: `${path}.${key}`,
+                    name: typeName,
+                });
+                proto.write(`optional ${typeName} ${field} = ${tag};`);
+            }
+            else if (value._zod.def.type === "custom" && "protobuf" in meta) {
+                const typeName = meta.protobuf;
+                proto.write(`optional ${typeName} ${field} = ${tag};`);
+            }
+            else if (iszjson(value)) {
+                proto.write(`optional google.protobuf.Value ${field} = ${tag};`);
+            }
+            else {
+                console.error(chalk.stderr.bold.red(`'${path}.${key}' has type '${value._zod.def.type}' which is not (yet) supported, please reach out to the maintainers!`));
+                process.exit(-1);
+            }
+        }
+        proto.write(`}\n`);
+    }
+    else if (schema instanceof z.ZodRecord) {
+        const keyType = schema.keyType;
+        // To account for all possible "string" types in Zod, e.g.,
+        // `z.uuid()`, `z.email()`, etc, we can't use `instanceof`.
+        if (keyType._zod.def.type !== "string") {
+            console.error(chalk.stderr.bold.red(`Unexpected record key type '${keyType._zod.def.type}' at '${path}'; only 'string' key types are currently supported for records`));
+            process.exit(-1);
+        }
+        const valueType = schema.valueType;
+        if (valueType instanceof z.ZodOptional) {
+            console.error(chalk.stderr.bold.red(`Record at '${path}' has _optional_ value type which is not supported`));
+            process.exit(-1);
+        }
+        else if (valueType instanceof z.ZodDefault) {
+            console.error(chalk.stderr.bold.red(`Record at '${path}' has _default_ value type which is not supported`));
+            process.exit(-1);
+        }
+        const typeName = (() => {
+            // To account for all possible "string" types in Zod, e.g.,
+            // `z.uuid()`, `z.email()`, etc, we can't use `instanceof`.
+            if (valueType._zod.def.type === "string") {
+                return "string";
+            }
+            else if (valueType instanceof z.ZodNumber) {
+                return "double";
+            }
+            else if (valueType instanceof z.ZodBigInt) {
+                return "int64";
+            }
+            else if (valueType instanceof z.ZodBoolean) {
+                return "bool";
+            }
+            else if (valueType instanceof z.ZodObject) {
+                return "Value";
+            }
+            else if (valueType instanceof z.ZodRecord) {
+                return "Value";
+            }
+            else if (valueType instanceof z.ZodArray) {
+                return "Value";
+            }
+            else if (valueType instanceof z.ZodDiscriminatedUnion) {
+                return "Value";
+            }
+            else if (valueType instanceof z.ZodCustom) {
+                const meta = valueType.meta();
+                if (valueType instanceof z.ZodCustom && "protobuf" in meta) {
+                    return meta.protobuf;
+                }
+            }
+            else if (iszjson(valueType)) {
+                return "google.protobuf.Value";
+            }
+            console.error(chalk.stderr.bold.red(`Record at '${path}' has value type '${valueType._zod.def.type}' which is not (yet) supported`));
+            process.exit(-1);
+        })();
+        if (valueType instanceof z.ZodObject) {
+            generate(proto, {
+                schema: valueType,
+                path: `${path}.[value]`,
+                name: typeName,
+            });
+        }
+        else if (valueType instanceof z.ZodRecord) {
+            proto.write(`message ${typeName} {`);
+            generate(proto, {
+                schema: valueType,
+                path: `${path}.[value]`,
+            });
+            proto.write(`}`);
+        }
+        else if (valueType instanceof z.ZodArray) {
+            proto.write(`message ${typeName} {`);
+            generate(proto, {
+                schema: valueType,
+                path: `${path}.[value]`,
+            });
+            proto.write(`}`);
+        }
+        else if (valueType instanceof z.ZodDiscriminatedUnion) {
+            generate(proto, {
+                schema: valueType,
+                path: `${path}.[value]`,
+                name: typeName,
+            });
+        }
+        proto.write(`map <string, ${typeName}> record = 1;`);
+    }
+    else if (schema instanceof z.ZodArray) {
+        const element = schema.element;
+        if (element instanceof z.ZodOptional) {
+            console.error(chalk.stderr.bold.red(`Array at '${path}' has _optional_ element type which is not supported`));
+            process.exit(-1);
+        }
+        else if (element instanceof z.ZodDefault) {
+            console.error(chalk.stderr.bold.red(`Array at '${path}' has _default_ element type which is not supported`));
+            process.exit(-1);
+        }
+        const typeName = (() => {
+            // To account for all possible "string" types in Zod, e.g.,
+            // `z.uuid()`, `z.email()`, etc, we can't use `instanceof`.
+            if (element._zod.def.type === "string") {
+                return "string";
+            }
+            else if (element instanceof z.ZodNumber) {
+                return "double";
+            }
+            else if (element instanceof z.ZodBigInt) {
+                return "int64";
+            }
+            else if (element instanceof z.ZodBoolean) {
+                return "bool";
+            }
+            else if (element instanceof z.ZodObject) {
+                return "Element";
+            }
+            else if (element instanceof z.ZodRecord) {
+                return "Element";
+            }
+            else if (element instanceof z.ZodArray) {
+                return "Element";
+            }
+            else if (element instanceof z.ZodDiscriminatedUnion) {
+                return "Element";
+            }
+            else if (element instanceof z.ZodCustom) {
+                const meta = element.meta();
+                if (element instanceof z.ZodCustom && "protobuf" in meta) {
+                    return meta.protobuf;
+                }
+            }
+            else if (iszjson(element)) {
+                return "google.protobuf.Value";
+            }
+            console.error(chalk.stderr.bold.red(`Array at '${path}' has element type '${element._zod.def.type}' which is not (yet) supported`));
+            process.exit(-1);
+        })();
+        if (element instanceof z.ZodObject) {
+            generate(proto, {
+                schema: element,
+                path: `${path}.[element]`,
+                name: typeName,
+            });
+        }
+        else if (element instanceof z.ZodRecord) {
+            proto.write(`message ${typeName} {`);
+            generate(proto, {
+                schema: element,
+                path: `${path}.[element]`,
+            });
+            proto.write(`}`);
+        }
+        else if (element instanceof z.ZodArray) {
+            proto.write(`message ${typeName} {`);
+            generate(proto, {
+                schema: element,
+                path: `${path}.[element]`,
+            });
+            proto.write(`}`);
+        }
+        else if (element instanceof z.ZodDiscriminatedUnion) {
+            generate(proto, {
+                schema: element,
+                path: `${path}.[element]`,
+                name: typeName,
+            });
+        }
+        proto.write(`repeated ${typeName} elements = 1;`);
+    }
+    else if (schema instanceof z.ZodDiscriminatedUnion) {
+        assert(name !== undefined);
+        proto.write(`message ${name} {`);
+        const discriminator = schema._zod.def.discriminator;
+        const literals = new Set();
+        const tags = new Map();
+        for (const option of schema.options) {
+            if (!(option instanceof z.ZodObject)) {
+                console.error(chalk.stderr.bold.red(`Discriminated union at '${path}' has option of type '${option._zod.def.type}', should be 'object'`));
+                process.exit(-1);
+            }
+            if (!(discriminator in option.shape)) {
+                console.error(chalk.stderr.bold.red(`Discriminated union at '${path}' has option missing discriminator '${discriminator}'`));
+                process.exit(-1);
+            }
+            if (!(option.shape[discriminator] instanceof z.ZodLiteral)) {
+                console.error(chalk.stderr.bold.red(`Discriminated union at '${path}' has option with unexpected discriminator '${discriminator}'; only 'string' literals are currently supported`));
+                process.exit(-1);
+            }
+            for (const literal of option.shape[discriminator]._zod.def.values) {
+                if (typeof literal !== "string") {
+                    console.error(chalk.stderr.bold.red(`Discriminated union at '${path}' has option with unexpected discriminator '${discriminator}'; only 'string' literals are currently supported`));
+                    process.exit(-1);
+                }
+            }
+            // Can only support one value because of how we name
+            // things. Could consider using the `tag` to name things instead
+            // so that the literal values could change, but it makes the
+            // proto less readable in places like the inspect page.
+            if (option.shape[discriminator]._zod.def.values.length !== 1) {
+                console.error(chalk.stderr.bold.red(`Discriminated union at '${path}' has option with more than one discriminator '${discriminator}' literals, only one is currently supported`));
+                process.exit(-1);
+            }
+            const literal = option.shape[discriminator]._zod.def.values[0];
+            if (literals.has(literal)) {
+                console.error(chalk.stderr.bold.red(`Discriminated union at '${path}' has an option that is reusing the literal '${literal}' for discrimniator '${discriminator}'`));
+                process.exit(-1);
+            }
+            literals.add(literal);
+            // Make the name of this nested type be the PascalCase property.
+            const typeName = literal.charAt(0).toUpperCase() + literal.slice(1);
+            const meta = option.meta();
+            if (meta === undefined || !("tag" in meta)) {
+                console.error(chalk.stderr.bold.red(`Missing tag for discriminated union option at '${path}'; all discriminated union options must be tagged for backwards compatibility`));
+                process.exit(-1);
+            }
+            const { tag } = meta;
+            if (tags.has(tag)) {
+                console.error(chalk.stderr.bold.red(`Trying to use already used tag ${tag} in discriminated union`));
+                process.exit(-1);
+            }
+            tags.set(tag, [toSnakeCase(literal), typeName]);
+            const omit = {};
+            omit[discriminator] = true;
+            generate(proto, {
+                schema: option.omit(omit),
+                path: `${path}.{ ${discriminator}: "${literal}", ... }`,
+                name: typeName,
+            });
+        }
+        proto.write(`oneof ${discriminator} {`);
+        for (const [tag, [literal, typeName]] of tags) {
+            proto.write(`${typeName} ${literal} = ${tag};`);
+        }
+        proto.write(`}`);
+        proto.write(`}`);
+    }
+    else {
+        throw new Error(`Unexpected type '${schema._zod.def.type}'`);
+    }
+};
+const main = async () => {
+    // We generate the `.proto` files in a temporary directory.
+    const generatedProtosDirectory = await mkdtemp(path.join(os.tmpdir(), "protos-"));
+    const cwd = process.cwd();
+    let protoFileGenerated = false;
+    for (const file of files) {
+        const module = await import(`${path.join(cwd, filesDirectory, file)}`);
+        const api = module.api;
+        if (api === undefined) {
+            // Skipping the file if it does not export `api`.
+            // We will error out from 'protoc' if none of the files
+            // exported `api`.
+            continue;
+        }
+        // Get '.proto' file name, i.e., by changing '.ts' to '.proto'.
+        //
+        // NOTE: there is an prerequisite invariant here that the paths
+        // are already in the correct form, hence why we have to join with
+        // all of `cwd`, `filesDirectory`, and `file` above.
+        const parsed = path.parse(file);
+        parsed.ext = ".proto";
+        parsed.base = parsed.name + parsed.ext;
+        const name = `${path.format(parsed)}`;
+        fs.mkdirSync(path.dirname(path.join(generatedProtosDirectory, name)), {
+            recursive: true,
+        });
+        const proto = fs.createWriteStream(path.join(generatedProtosDirectory, name));
+        proto.write(`syntax = "proto3";\n`);
+        proto.write(`package ${parsed.dir.replace(/\//g, ".")};\n`);
+        proto.write(`import "google/protobuf/empty.proto";\n`);
+        proto.write(`import "google/protobuf/struct.proto";\n`);
+        proto.write(`import "rbt/v1alpha1/options.proto";\n`);
+        // Including 'rbt/v1alpha1/tasks.proto' preemptively to support
+        // protobuf messages like `TaskId`.
+        proto.write(`import "rbt/v1alpha1/tasks.proto";\n`);
+        proto.write(`option (rbt.v1alpha1.file).zod = "${path.join(cwd, filesDirectory, file)}";\n`);
+        for (const typeName in api) {
+            // TODO: ensure `typeName` is PascalCase.
+            const result = typeSchema.safeParse(api[typeName]);
+            if (!result.success) {
+                console.error(chalk.stderr.bold.red(`'api.${typeName}' in '${path.join(filesDirectory, file)}' could not be validated! Please try again after correcting the following errors: \n\n${z.prettifyError(result.error)}\n`));
+                // Check if we have any 'not instance of ZodType' errors,
+                // possibly indicating that 'zod/v4' is not being
+                // used. Unfortunately Zod does not provide a way to check
+                // what version of the library is being used, so this is just
+                // best effort.
+                for (const issue of result.error.issues) {
+                    if (JSON.stringify(issue).includes("not instance of ZodType")) {
+                        console.error(chalk.stderr.bold.red(`NOTE: Reboot requires 'zod/v4', are you using it?\n`));
+                        break;
+                    }
+                }
+                process.exit(-1);
+            }
+            const type = result.data;
+            generate(proto, {
+                schema: type.state instanceof z.ZodObject ? type.state : z.object(type.state),
+                path: `api.${typeName}.state`,
+                name: typeName,
+                state: true,
+            });
+            const errorsToGenerate = [];
+            for (const methodName in type.methods) {
+                // TODO: ensure `methodName` is PascalCase.
+                const { request, response } = type.methods[methodName];
+                const requestTypeName = `${typeName}${toPascalCase(methodName)}Request`;
+                generate(proto, {
+                    schema: request instanceof z.ZodObject ? request : z.object(request),
+                    path: `api.${typeName}.methods.${methodName}.request`,
+                    name: requestTypeName,
+                });
+                if (response instanceof z.ZodVoid) {
+                    continue;
+                }
+                const responseTypeName = `${typeName}${toPascalCase(methodName)}Response`;
+                generate(proto, {
+                    schema: response instanceof z.ZodObject ? response : z.object(response),
+                    path: `api.${typeName}.methods.${methodName}.response`,
+                    name: responseTypeName,
+                });
+            }
+            proto.write(`service ${typeName}Methods {\n`);
+            for (const methodName in type.methods) {
+                // TODO: ensure `methodName` is PascalCase.
+                const method = type.methods[methodName];
+                const requestTypeName = `${typeName}${toPascalCase(methodName)}Request`;
+                const responseTypeName = method.response instanceof z.ZodVoid
+                    ? `google.protobuf.Empty`
+                    : `${typeName}${toPascalCase(methodName)}Response`;
+                proto.write([
+                    `  rpc ${toPascalCase(methodName)}(${requestTypeName})`,
+                    `      returns (${responseTypeName}) {`,
+                    `    option (rbt.v1alpha1.method) = {`,
+                    `      ${method.kind}: {`,
+                ].join(`\n`));
+                if (method.kind === "writer" || method.kind === "transaction") {
+                    if (method.factory !== undefined) {
+                        proto.write(`        constructor: {},\n`);
+                    }
+                }
+                proto.write(`      },\n`);
+                if (method.errors !== undefined) {
+                    const errors = method.errors instanceof z.ZodDiscriminatedUnion
+                        ? method.errors
+                        : z.discriminatedUnion("type", method.errors);
+                    const path = `api.${typeName}.methods.${methodName}.errors`;
+                    const name = `${typeName}${toPascalCase(methodName)}Errors`;
+                    errorsToGenerate.push(() => {
+                        generate(proto, { schema: errors, path, name });
+                    });
+                    // In addition to all the checks we get above when calling
+                    // `generate()`, we also want to make sure that none of the
+                    // gRPC or Reboot error types conflict.
+                    for (const option of errors.options) {
+                        const literal = option.shape.type._zod.def.values[0];
+                        if (ZOD_ERROR_NAMES.includes(literal)) {
+                            console.error(chalk.stderr.bold.red(`'${path}' uses '${literal}' as an error 'type' that conflicts with system errors, please use a different literal!\n`));
+                            process.exit(-1);
+                        }
+                    }
+                    // And finally, we need to add this protobuf message to the
+                    // `errors` option for this method in the `.proto` file.
+                    proto.write(`      errors: ["${name}"],\n`);
+                }
+                proto.write([`    };`, `  }`].join(`\n`));
+            }
+            proto.write(`}\n`);
+            // Generate all the errors we need at the top-level.
+            errorsToGenerate.forEach((generate) => generate());
+        }
+        proto.end();
+        // Need to wait for the file to be written (TODO: wait for all of
+        // them via `Promise.all`).
+        await new Promise((resolve, reject) => {
+            proto.on("finish", () => resolve());
+            proto.on("error", (err) => reject(err));
+        });
+        protoFileGenerated = true;
+    }
+    if (protoFileGenerated) {
+        // If at least one proto file was generated, we write the
+        // directory to the stdout, so Python 'generate' script can
+        // glob inside it and adjust the 'protoc' generation command.
+        console.log(`${generatedProtosDirectory}`);
+    }
+    process.exit(0);
+};
+main();

package/reboot_native.cc

@@ -2597,7 +2597,7 @@ Napi::Value retry_reactively_until(const Napi::CallbackInfo& info) {
 }
 
 
-Napi::Value atLeastOrMostOnce(const Napi::CallbackInfo& info) {
+Napi::Value memoize(const Napi::CallbackInfo& info) {
   auto js_external_context = NapiSafeReference(
       info[0].As<Napi::External<py::object>>());
 
@@ -2840,8 +2840,8 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
       Napi::Function::New<retry_reactively_until>(env));
 
   exports.Set(
-      Napi::String::New(env, "atLeastOrMostOnce"),
-      Napi::Function::New<atLeastOrMostOnce>(env));
+      Napi::String::New(env, "memoize"),
+      Napi::Function::New<memoize>(env));
 
   exports.Set(
       Napi::String::New(env, "Task_await"),

package/reboot_native.cjs

@@ -85,7 +85,7 @@ exports.Context_generateIdempotentStateId =
   reboot_native.exports.Context_generateIdempotentStateId;
 exports.WriterContext_set_sync = reboot_native.exports.WriterContext_set_sync;
 exports.retry_reactively_until = reboot_native.exports.retry_reactively_until;
-exports.atLeastOrMostOnce = reboot_native.exports.atLeastOrMostOnce;
+exports.memoize = reboot_native.exports.memoize;
 exports.Servicer_read = reboot_native.exports.Servicer_read;
 exports.Servicer_write = reboot_native.exports.Servicer_write;
 exports.importPy = reboot_native.exports.importPy;

package/reboot_native.d.ts

@@ -89,7 +89,7 @@ export namespace rbt_native {
     external: NapiExternal,
     condition: () => Promise<boolean>
   ): Promise<void>;
-  function atLeastOrMostOnce(
+  function memoize(
     external: NapiExternal,
     idempotencyAlias: string,
     callable: () => Promise<string>,

package/secrets/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" resolution-mode="require"/>
 export declare const ENVVAR_RBT_SECRETS_DIRECTORY = "RBT_SECRETS_DIRECTORY";
 declare abstract class SecretSource {
     abstract get(secretName: string): Promise<Buffer>;

package/version.d.ts

@@ -1 +1 @@
-export declare const REBOOT_VERSION = "0.28.0";
+export declare const REBOOT_VERSION = "0.29.1";

package/version.js

@@ -1 +1 @@
-export const REBOOT_VERSION = "0.28.0";
+export const REBOOT_VERSION = "0.29.1";