{"_id":"@drew-foxall/upstash-workflow-world","name":"@drew-foxall/upstash-workflow-world","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@drew-foxall/upstash-workflow-world","version":"0.1.0","description":"Edge-runtime compatible World implementation for Workflow DevKit using Upstash Redis","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","clean":"rm -rf dist","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","prepublishOnly":"npm run clean && npm run build"},"keywords":["workflow","upstash","redis","edge","cloudflare-workers","vercel-edge","deno","serverless","queue","streaming"],"author":{"name":"Drew Foxall"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/drew-foxall/upstash-workflow-world.git"},"bugs":{"url":"https://github.com/drew-foxall/upstash-workflow-world/issues"},"homepage":"https://github.com/drew-foxall/upstash-workflow-world#readme","attribution":{"originalProject":"workflow-worlds","originalAuthor":"Dustin Townsend","originalRepository":"https://github.com/mizzle-dev/workflow-worlds","license":"MIT"},"dependencies":{"@upstash/redis":"^1.34.0","@workflow/errors":"4.0.1-beta.6","@workflow/world":"4.0.1-beta.7","cbor-x":"^1.6.0","ulid":"^2.3.0","zod":"^3.24.0"},"devDependencies":{"@types/node":"^20.0.0","@workflow/world-testing":"4.0.1-beta.7","typescript":"^5.0.0","vitest":"^1.0.0"},"peerDependencies":{"@upstash/redis":"^1.34.0"},"engines":{"node":">=18.0.0"},"_id":"@drew-foxall/upstash-workflow-world@0.1.0","_nodeVersion":"22.16.0","_npmVersion":"11.6.4","dist":{"integrity":"sha512-bA3/pl1/bXaGksQTYICi5BwIotS9lYezqnXhG0vT0f4DDYE9eTqo+TpUa2rR3gX4XgPCQl+5qeCAQtvTWe/GYg==","shasum":"5b877176245f96eb98061d983bf7fac5521a201f","tarball":"https://registry.npmjs.org/@drew-foxall/upstash-workflow-world/-/upstash-workflow-world-0.1.0.tgz","fileCount":24,"unpackedSize":196080,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBianMdTjxR04prU0/8SpR6NHw0OdkjqC69zPUJweV7CAiEAlOzdewvSR5UG3/KHRYog+VUT9HXIEF+yJg5xSUgw8AY="}]},"_npmUser":{"name":"drew-foxall","email":"drew@foxalltogether.com"},"directories":{},"maintainers":[{"name":"drew-foxall","email":"drew@foxalltogether.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/upstash-workflow-world_0.1.0_1764920840767_0.11915159576313217"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-05T07:47:20.696Z","0.1.0":"2025-12-05T07:47:20.923Z","modified":"2025-12-05T07:47:21.215Z"},"maintainers":[{"name":"drew-foxall","email":"drew@foxalltogether.com"}],"description":"Edge-runtime compatible World implementation for Workflow DevKit using Upstash Redis","homepage":"https://github.com/drew-foxall/upstash-workflow-world#readme","keywords":["workflow","upstash","redis","edge","cloudflare-workers","vercel-edge","deno","serverless","queue","streaming"],"repository":{"type":"git","url":"git+https://github.com/drew-foxall/upstash-workflow-world.git"},"author":{"name":"Drew Foxall"},"bugs":{"url":"https://github.com/drew-foxall/upstash-workflow-world/issues"},"license":"MIT","readme":"# @drew-foxall/upstash-workflow-world\n\nAn edge-runtime compatible World implementation for [Workflow DevKit](https://github.com/mizzle-dev/workflow) using [Upstash Redis](https://upstash.com/).\n\nWorks on: **Cloudflare Workers**, **Vercel Edge**, **Deno Deploy**, and any JavaScript runtime with `fetch()`.\n\n## Attribution\n\nThis package is derived from [workflow-worlds](https://github.com/mizzle-dev/workflow-worlds) by Dustin Townsend. The original project provides the foundational architecture and patterns for implementing World interfaces for the Workflow DevKit.\n\n## Features\n\n- **Edge-Runtime Compatible**: Uses HTTP-based Redis operations (no TCP connections required)\n- **Full World Interface**: Implements Storage, Queue, and Streamer capabilities\n- **Self-Invoking Queue**: Uses Redis Streams with HTTP triggers for reliable job processing\n- **Polling-Based Streaming**: Real-time output streaming without persistent connections\n- **Automatic Retries**: Built-in retry logic with exponential backoff\n- **Idempotency**: Prevents duplicate job processing\n\n## Installation\n\n```bash\nnpm install @drew-foxall/upstash-workflow-world @upstash/redis\n```\n\n## Quick Start\n\n```typescript\nimport { createWorld } from '@drew-foxall/upstash-workflow-world';\n\n// Create a world instance\nconst world = createWorld({\n  redisUrl: process.env.UPSTASH_REDIS_REST_URL,\n  redisToken: process.env.UPSTASH_REDIS_REST_TOKEN,\n  baseUrl: 'https://my-app.vercel.app', // Your deployed app URL\n});\n\nexport default world;\n```\n\n## Configuration\n\n### Environment Variables\n\nThe package supports the following environment variables:\n\n| Variable | Description |\n|----------|-------------|\n| `UPSTASH_REDIS_REST_URL` | Upstash Redis REST URL |\n| `UPSTASH_REDIS_REST_TOKEN` | Upstash Redis REST Token |\n| `WORKFLOW_UPSTASH_REDIS_REST_URL` | Alternative Redis URL (higher priority) |\n| `WORKFLOW_UPSTASH_REDIS_REST_TOKEN` | Alternative Redis Token (higher priority) |\n| `DEBUG` | Set to `workflow:*` for debug logging |\n\n### Config Options\n\n```typescript\ninterface UpstashWorldConfig {\n  // Redis connection\n  redisUrl?: string;           // Upstash Redis REST URL\n  redisToken?: string;         // Upstash Redis REST Token\n  redis?: Redis;               // Pre-existing @upstash/redis client\n\n  // Key prefix for all Redis keys (default: 'workflow')\n  keyPrefix?: string;\n\n  // Queue configuration\n  baseUrl?: string;            // Base URL for self-invoking HTTP triggers\n  maxRetries?: number;         // Max retry attempts (default: 3)\n  retryDelayMs?: number;       // Initial retry delay (default: 1000)\n  idempotencyTtlMs?: number;   // Idempotency key TTL (default: 60000)\n\n  // Streamer configuration\n  streamMaxLen?: number;       // Max stream length (default: 10000)\n  pollIntervalMs?: number;     // Polling interval (default: 100)\n}\n```\n\n## Usage with Workflow DevKit\n\n### Creating a Workflow\n\n```typescript\nimport { createWorkflow } from '@workflow/core';\nimport { createWorld } from '@drew-foxall/upstash-workflow-world';\n\nconst world = createWorld({\n  redisUrl: process.env.UPSTASH_REDIS_REST_URL,\n  redisToken: process.env.UPSTASH_REDIS_REST_TOKEN,\n  baseUrl: process.env.VERCEL_URL,\n});\n\nconst myWorkflow = createWorkflow({\n  world,\n  name: 'my-workflow',\n  async run(ctx, input) {\n    const result = await ctx.step('process', async () => {\n      return { processed: true };\n    });\n    return result;\n  },\n});\n```\n\n### Queue Handler (Edge Function)\n\nFor the self-invoking queue pattern to work, you need to expose a `/drain` endpoint:\n\n```typescript\n// pages/api/drain.ts (Next.js) or similar\nimport { world } from './world';\n\nexport const config = { runtime: 'edge' };\n\nexport default world.createQueueHandler('workflow', async (message) => {\n  // Process queue message\n  console.log('Processing:', message);\n});\n```\n\n## Architecture\n\nThis implementation uses:\n\n1. **Storage**: Redis Hashes and Sorted Sets for runs, steps, events, and hooks\n2. **Queue**: Redis Streams with self-invoking HTTP triggers (no BullMQ/TCP required)\n3. **Streamer**: Redis Streams with polling-based reads (no Pub/Sub required)\n\n### Why Not BullMQ?\n\nBullMQ requires TCP connections which are not available in edge runtimes. This implementation uses:\n- Redis Streams for reliable message queuing\n- HTTP-based self-invocation for job processing triggers\n- Polling instead of blocking reads for stream consumption\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests (requires Upstash Redis credentials)\nUPSTASH_REDIS_REST_URL=... UPSTASH_REDIS_REST_TOKEN=... npm test\n\n# Build\nnpm run build\n\n# Type check\nnpm run typecheck\n```\n\n## License\n\nMIT - See [LICENSE](./LICENSE) for details.\n\n## Credits\n\n- Original [workflow-worlds](https://github.com/mizzle-dev/workflow-worlds) by Dustin Townsend\n- [Upstash](https://upstash.com/) for the HTTP-based Redis service\n- [Workflow DevKit](https://github.com/mizzle-dev/workflow) team\n","readmeFilename":"README.md","_rev":"1-54ee4c56df33a98eda238d9154956cbd"}