@workflow/world-postgres 4.0.1-beta.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @workflow/world-postgres
+
+An embedded worker/workflow system backed by PostgreSQL for multi-host self-hosted solutions. This is a reference implementation - a production-ready solution might run workers in separate processes with a more robust queuing system.
+
+## Installation
+
+```bash
+npm install @workflow/world-postgres
+# or
+pnpm add @workflow/world-postgres
+# or
+yarn add @workflow/world-postgres
+```
+
+## Usage
+
+### Basic Setup
+
+The postgres world can be configured by setting the `WORKFLOW_TARGET_WORLD` environment variable to the package name:
+
+```bash
+export WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
+```
+
+### Configuration
+
+Configure the PostgreSQL world using environment variables:
+
+```bash
+# Required: PostgreSQL connection string
+export WORKFLOW_POSTGRES_URL="postgres://username:password@localhost:5432/database"
+
+# Optional: Job prefix for queue operations
+export WORKFLOW_POSTGRES_JOB_PREFIX="myapp"
+
+# Optional: Worker concurrency (default: 10)
+export WORKFLOW_POSTGRES_WORKER_CONCURRENCY="10"
+```
+
+### Programmatic Usage
+
+You can also create a PostgreSQL world directly in your code:
+
+```typescript
+import { createWorld } from "@workflow/world-postgres";
+
+const world = createWorld({
+  connectionString: "postgres://username:password@localhost:5432/database",
+  jobPrefix: "myapp", // optional
+  queueConcurrency: 10, // optional
+});
+```
+
+## Configuration Options
+
+| Option             | Type     | Default                                                                                | Description                         |
+| ------------------ | -------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
+| `connectionString` | `string` | `process.env.WORKFLOW_POSTGRES_URL` or `'postgres://world:world@localhost:5432/world'` | PostgreSQL connection string        |
+| `jobPrefix`        | `string` | `process.env.WORKFLOW_POSTGRES_JOB_PREFIX`                                             | Optional prefix for queue job names |
+| `queueConcurrency` | `number` | `10`                                                                                   | Number of concurrent queue workers  |
+
+## Environment Variables
+
+| Variable                               | Description                                                  | Default                                         |
+| -------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
+| `WORKFLOW_TARGET_WORLD`                | Set to `"@workflow/world-postgres"` to use this world | -                                               |
+| `WORKFLOW_POSTGRES_URL`                | PostgreSQL connection string                                 | `'postgres://world:world@localhost:5432/world'` |
+| `WORKFLOW_POSTGRES_JOB_PREFIX`         | Prefix for queue job names                                   | -                                               |
+| `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | Number of concurrent workers                                 | `10`                                            |
+
+## Database Setup
+
+This package uses PostgreSQL with the following components:
+
+- **pg-boss**: For queue processing and job management
+- **Drizzle ORM**: For database operations and schema management
+- **postgres**: For PostgreSQL client connections
+
+Make sure your PostgreSQL database is accessible and the user has sufficient permissions to create tables and manage jobs.
+
+## Features
+
+- **Durable Storage**: Stores workflow runs, events, steps, hooks, and webhooks in PostgreSQL
+- **Queue Processing**: Uses pg-boss for reliable job queue processing
+- **Streaming**: Real-time event streaming capabilities
+- **Health Checks**: Built-in connection health monitoring
+- **Configurable Concurrency**: Adjustable worker concurrency for queue processing
+
+## Development
+
+For local development, you can use the included Docker Compose configuration:
+
+```bash
+# Start PostgreSQL database
+docker-compose up -d
+
+# Create and run migrations
+pnpm drizzle-kit generate
+pnpm drizzle-kit migrate
+
+# Set environment variables for local development
+export WORKFLOW_POSTGRES_URL="postgres://world:world@localhost:5432/world"
+export WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
+```
+
+## World Selection
+
+To use the PostgreSQL world, set the `WORKFLOW_TARGET_WORLD` environment variable to the package name:
+
+```bash
+export WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@workflow/world-postgres",
+  "version": "4.0.1-beta.0",
+  "description": "A reference World implementation based on PostgreSQL",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@vercel/queue": "0.0.0-alpha.23",
+    "drizzle-orm": "^0.31.2",
+    "pg-boss": "^11.0.7",
+    "postgres": "^3.4.7",
+    "ulid": "^3.0.1",
+    "zod": "4.1.11",
+    "@workflow/errors": "4.0.1-beta.0",
+    "@workflow/world": "4.0.1-beta.0",
+    "@workflow/world-local": "4.0.1-beta.0"
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^11.7.1",
+    "@types/node": "24.6.2",
+    "drizzle-kit": "^0.22.7",
+    "vitest": "^3.2.4",
+    "@workflow/errors": "4.0.1-beta.0",
+    "@workflow/world-testing": "4.0.1-beta.0",
+    "@workflow/tsconfig": "4.0.1-beta.0"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "tsc --build --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "db:push": "pnpm exec drizzle-kit --version && drizzle-kit push"
+  }
+}