@steadlake/run 0.3.0 → 0.3.1

package/README.md

@@ -1,15 +1,239 @@
-# steppler
+# @steadlake/run
 
-To install dependencies:
+Durable task execution for your backend. Define tasks with steps, retries, scheduling, and event-driven workflows — without managing infrastructure.
+
+## Install
 
 ```bash
-bun install
+npm install @steadlake/run
 ```
 
-To run:
+## Setup
 
-```bash
-bun run index.ts
+**Environment variables:**
+
+```
+STEADLAKE_API_KEY=sk_live_...
+STEADLAKE_PROJECT_ID=proj_...
+```
+
+## Quick start
+
+### 1. Define tasks
+
+```ts
+// tasks/send-email.ts
+import { task } from "@steadlake/run";
+import { z } from "zod";
+
+export const sendEmail = task({
+  id: "send-email",
+  schema: z.object({ to: z.string().email(), subject: z.string() }),
+  run: async ({ payload }) => {
+    await emailService.send(payload.to, payload.subject);
+    return { sent: true };
+  },
+});
+```
+
+### 2. Mount the handler
+
+**Next.js**
+```ts
+// app/api/steadlake/route.ts
+import { createNextHandler } from "@steadlake/run/adapters/next";
+import { sendEmail } from "@/tasks/send-email";
+
+export const { POST } = createNextHandler({
+  baseUrl: process.env.APP_URL!,
+  tasks: [sendEmail],
+});
+```
+
+**Hono / Generic**
+```ts
+import { createHandler } from "@steadlake/run/adapters/generic";
+import { sendEmail } from "./tasks/send-email";
+
+const handler = createHandler({
+  baseUrl: process.env.APP_URL!,
+  tasks: [sendEmail],
+});
+
+app.post("/api/steadlake", (c) => handler(c.req.raw));
+```
+
+**Cloudflare Workers**
+```ts
+import { createWorkerHandler } from "@steadlake/run/adapters/worker";
+import { sendEmail } from "./tasks/send-email";
+
+const handler = createWorkerHandler({ tasks: [sendEmail] });
+
+export default {
+  fetch(req: Request, env: Env) {
+    if (new URL(req.url).pathname === "/api/steadlake") {
+      return handler(req, env, env.WORKER_URL);
+    }
+    return app.fetch(req, env);
+  },
+};
+```
+
+### 3. Trigger
+
+```ts
+// anywhere in your server code
+import { sendEmail } from "@/tasks/send-email";
+
+await sendEmail.trigger({ to: "user@example.com", subject: "Welcome!" });
+```
+
+---
+
+## Steps
+
+Break long tasks into named, durable steps. Completed steps are replayed from state on retry — they never re-execute.
+
+```ts
+export const importUsers = task({
+  id: "import-users",
+  run: async ({ payload, step }) => {
+    const users = await step.run("fetch", () => api.getUsers(payload.source));
+    const valid = await step.run("validate", () => users.filter(isValid));
+    await step.run("insert", () => db.users.bulkInsert(valid));
+    return { imported: valid.length };
+  },
+});
+```
+
+### Sleep
+
+```ts
+await step.sleep("wait", "3d");        // duration: ms, s, m, h, d
+await step.sleepUntil("until", date);  // Date | ISO string
+```
+
+### Wait for external event
+
+```ts
+const shipment = await step.waitForEvent<{ trackingId: string }>("shipped", {
+  event: "order.shipped",
+  timeout: "7d",
+});
+```
+
+Resume by calling `run.sendEvent("order.shipped", { trackingId: "..." })`.
+
+### Human approval
+
+```ts
+const { approved } = await step.approve("review", {
+  title: "Approve $10,000 payout?",
+  timeout: "24h",
+});
+```
+
+Resume by calling `client.resolveApproval(runId, stepId, true)`.
+
+### Emit events to other runs
+
+```ts
+step.emit("order.shipped", { trackingId: "TRK123" });
 ```
 
-This project was created using `bun init` in bun v1.3.10. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+---
+
+## Retries
+
+```ts
+export const chargeCustomer = task({
+  id: "charge-customer",
+  retry: {
+    maxAttempts: 5,
+    backoff: "exponential", // "exponential" | "linear" | "fixed"
+  },
+  run: async ({ payload }) => {
+    await stripe.charges.create({ amount: payload.amount });
+  },
+});
+```
+
+Throw `FatalError` to fail permanently without retrying. Throw `RetryableError` to retry explicitly.
+
+---
+
+## Cron
+
+```ts
+export const dailyReport = task({
+  id: "daily-report",
+  cron: "0 9 * * 1-5",
+  run: async () => { ... },
+});
+
+// With timezone
+export const digest = task({
+  id: "digest",
+  cron: { pattern: "0 8 * * *", timezone: "America/New_York" },
+  run: async () => { ... },
+});
+```
+
+---
+
+## Queues
+
+```ts
+export const processVideo = task({
+  id: "process-video",
+  queue: {
+    name: "video",
+    concurrencyLimit: 3,
+    rateLimit: { max: 100, duration: "1h" },
+  },
+  run: async ({ payload }) => { ... },
+});
+```
+
+---
+
+## Trigger options
+
+```ts
+await sendEmail.trigger(payload, {
+  idempotencyKey: `email-${userId}`,
+  webhook: "https://myapp.com/webhooks/done",
+  tags: ["transactional"],
+  priority: 10,
+  scheduledAt: new Date(Date.now() + 60_000).toISOString(),
+});
+```
+
+Wait for result:
+
+```ts
+const result = await sendEmail.triggerAndWait(payload, { timeoutMs: 30_000 });
+console.log(result.status); // "success" | "failed"
+console.log(result.result);
+```
+
+---
+
+## Error types
+
+| | HTTP | DEW behaviour |
+|---|---|---|
+| `FatalError` | 400 | Permanent failure, no retry |
+| `RetryableError` | 500 | Explicit retry request |
+| Any other error | 500 | Retry if attempts remain |
+
+---
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `STEADLAKE_API_KEY` | Your project API key |
+| `STEADLAKE_PROJECT_ID` | Your project ID |
+| `STEADLAKE_API_URL` | Override platform URL (self-hosted) |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steadlake/run",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "Durable task execution SDK for Steadlake — define tasks with steps, retries, scheduling, and event-driven workflows.",
 	"files": [
 		"dist"
@@ -36,7 +36,7 @@
 		"format:check": "oxfmt --check .",
 		"changeset": "changeset",
 		"version": "changeset version",
-		"release": "npm run build && npm publish"
+		"release": "npm run build && changeset publish"
 	},
 	"dependencies": {
 		"@steadlake/core": "^0.3.2",