rethread 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# rethread
+
+[![npm version](https://img.shields.io/npm/v/rethread.svg)](https://www.npmjs.com/package/rethread)
+[![npm downloads](https://img.shields.io/npm/dm/rethread.svg)](https://www.npmjs.com/package/rethread)
+[![gzip size](https://img.shields.io/badge/gzip-352_bytes-brightgreen)](https://www.npmjs.com/package/rethread)
+
+
+**One function for multi-step workflows over stateless transports.** An
+onboarding wizard, a checkout funnel, an approval flow, an SMS or chat bot or any
+process that advances one request → reply at a time.
+
+## Getting started
+
+```ts
+import { rethread } from 'rethread';
+
+const signup = rethread(function* (suspend) {
+  const email = yield* suspend(() => "Welcome! What's your email?");
+  const plan = yield* suspend(() => 'Pick a plan: (1) Free  (2) Pro');
+
+  if (plan === '2') {
+    const card = yield* suspend(() => "Great - what's your card number?");
+    return `You're on Pro, ${email} - charged to ••••${card.slice(-4)}.`;
+  }
+  return `You're on Free, ${email}. Welcome aboard!`;
+});
+
+// The caller - usually an http handler, slack callback, etc.
+handleNewSms(async (msg, respond) => {
+  const state = await db.getState(msg.sessionId);
+  const events = [...state, msg.text];
+  const { value, done, events: newEvents } = signup(events);
+  await db.saveState(msg.sessionId, newEvents);
+  respond(value);
+});
+```
+
+The workflow is a generator. `yield* suspend(() => whatToSend)` halts the workflow and
+returns `whatToSend` to the caller. The next time the workflow runs with the updated
+log, it picks up right after that `yield*` with the reply. All events are strings
+since they need to be persisted and replayed.
+
+See `test/` for more advanced patterns (back, time-travel, recording nondeterminism, async).

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Resumable flows via stateless generator replay. The only state is `events` (the
+ * replies so far); each call replays the body over it, fast-forwarding answered
+ * `suspend`s and stopping at the first un-answered one.
+ *
+ *   const turn = rethread(function* (suspend) {
+ *     const name = yield* suspend(() => "Enter your name?");
+ *     return `Hi ${name}`;
+ *   });
+ *   const { value, done, events } = turn(events);
+ */
+declare function suspend<O>(render: () => O): Generator<() => O, string, string>;
+type GetEvents = () => string[];
+type Turn<Y, R> = {
+    value: Y;
+    done: false;
+    events: string[];
+} | {
+    value: R;
+    done: true;
+    events: string[];
+};
+type Unwrap<T> = T extends () => infer O ? O : T;
+type HasAsync<T> = Extract<T, Promise<unknown>> extends never ? false : true;
+type SyncResult<Y, R> = HasAsync<Unwrap<Y>> extends true ? Promise<Turn<Awaited<Unwrap<Y>>, R>> : Turn<Unwrap<Y>, R>;
+/**
+ * Sync body → `Turn`; async body → `Promise<Turn>`. If any render is async (even in a
+ * sync body), the return promotes to `Promise<Turn>` so the caller must `await`.
+ */
+export declare function rethread<Y, R>(body: (s: typeof suspend, getEvents: GetEvents) => Generator<Y, R, string>): (events?: string[]) => SyncResult<Y, R>;
+export declare function rethread<Y, R>(body: (s: typeof suspend, getEvents: GetEvents) => AsyncGenerator<Y, R, string>): (events?: string[]) => Promise<Turn<Awaited<Unwrap<Y>>, Awaited<R>>>;
+export {};

package/dist/index.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rethread = rethread;
+/**
+ * Resumable flows via stateless generator replay. The only state is `events` (the
+ * replies so far); each call replays the body over it, fast-forwarding answered
+ * `suspend`s and stopping at the first un-answered one.
+ *
+ *   const turn = rethread(function* (suspend) {
+ *     const name = yield* suspend(() => "Enter your name?");
+ *     return `Hi ${name}`;
+ *   });
+ *   const { value, done, events } = turn(events);
+ */
+function* suspend(render) {
+    return yield render;
+}
+const isThenable = (x) => x != null && typeof x.then === 'function';
+function rethread(body) {
+    return (events = []) => {
+        let i = 0;
+        const gen = body(suspend, () => events.slice(0, i));
+        const finish = (value, done) => isThenable(value)
+            ? Promise.resolve(value).then((v) => ({ value: v, done, events }))
+            : { value, done, events };
+        const pump = (res) => {
+            while (!isThenable(res)) {
+                if (res.done)
+                    return finish(res.value, true);
+                if (i < events.length) {
+                    res = gen.next(events[i++]);
+                    continue;
+                } // fast-forward
+                const cb = res.value;
+                if (typeof cb === 'function')
+                    return finish(cb(), false);
+                return finish(cb, false);
+            }
+            return res.then(pump);
+        };
+        return pump(gen.next());
+    };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "rethread",
+  "version": "1.0.0",
+  "description": "One function for multi-step workflows over stateless transports",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test \"test/**/*.test.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "Moshe Kolodny",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kolodny/rethread.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kolodny/rethread/issues"
+  },
+  "homepage": "https://github.com/kolodny/rethread#readme"
+}