Skip to content

Commit 4732586

Browse files
committed
feat: add readme
1 parent 306d4cc commit 4732586

File tree

1 file changed

+119
-2
lines changed

1 file changed

+119
-2
lines changed

README.md

Lines changed: 119 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,120 @@
1-
# Upstash Workflow
1+
# Upstash Workflow SDK
22

3-
Durable, Reliable and Performant Serverless Functions
3+
![npm (scoped)](https://img.shields.io/npm/v/@upstash/workflow)
4+
5+
> [!NOTE]
6+
> **This project is in GA Stage.**
7+
> The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes.
8+
> The Upstash team is committed to maintaining and improving its functionality.
9+
10+
**Upstash Workflow** lets you write durable, reliable and performant serverless functions. Get delivery guarantees, automatic retries on failure, scheduling and more without managing any infrastructure.
11+
12+
See [the documentation](https://upstash.com/docs/qstash/workflow/getstarted) for more details
13+
14+
## Quick Start
15+
16+
Here, we will briefly showcase how you can get started with Upstash Workflow.
17+
18+
Alternatively, you can check [our quickstarts for different frameworks](https://upstash.com/docs/qstash/workflow/quickstarts/platforms), including [Next.js](https://upstash.com/docs/qstash/workflow/quickstarts/vercel-nextjs) and [Cloudflare](https://upstash.com/docs/qstash/workflow/quickstarts/cloudflare-workers).
19+
20+
### Install
21+
22+
First, install the package with:
23+
24+
```
25+
npm install @upstash/workflow
26+
```
27+
28+
### Get QStash token
29+
30+
Go to [Upstash Console](https://console.upstash.com/qstash) and copy the QSTASH_TOKEN.
31+
32+
### Define a Workflow Endpoint
33+
34+
To declare workflow endpoints, use the `serve` method:
35+
36+
```ts
37+
import { serve } from "@upstash/workflow/nextjs";
38+
39+
// mock function
40+
const someWork = (input: string) => {
41+
return `processed '${JSON.stringify(input)}'`;
42+
};
43+
44+
// serve endpoint which expects a string payload:
45+
export const { POST } = serve<string>(async (context) => {
46+
// get request body:
47+
const input = context.requestPayload;
48+
49+
// run the first step:
50+
const result1 = await context.run("step1", async () => {
51+
const output = someWork(input);
52+
console.log("step 1 input", input, "output", output);
53+
return output;
54+
});
55+
56+
// run the second step:
57+
await context.run("step2", async () => {
58+
const output = someWork(result1);
59+
console.log("step 2 input", result1, "output", output);
60+
});
61+
});
62+
```
63+
64+
In the example, you can see that steps are declared through the `context` object.
65+
66+
The kinds of steps which are available are:
67+
68+
- `context.run`: execute a function
69+
- `context.sleep`: sleep for some time
70+
- `context.sleepUntil`: sleep until some timestamp
71+
- `context.call`: make a third party call without consuming any runtime
72+
- `context.waitForEvent`: wait for an event
73+
- `context.notify`: notify an event to make workflows waiting for the event continue
74+
75+
You can [learn more about these methods from our documentation](https://upstash.com/docs/qstash/workflow/basics/context).
76+
77+
### Workflow Client
78+
79+
You can use [the Upstash Workflow client](https://upstash.com/docs/qstash/workflow/basics/client) to cancel workflows, notify workflows
80+
waiting for an event or get the workflows waiting for an event:
81+
82+
```ts
83+
import { Client } from "@upstash/workflow";
84+
const client = new Client({ token: "<QSTASH_TOKEN>" });
85+
86+
// cancel workflow:
87+
await client.cancel({ workflowRunId: "<WORKFLOW_RUN_ID>" });
88+
89+
// notify workflows:
90+
await client.notify({
91+
eventId: "my-event-id",
92+
eventData: "my-data", // data passed to the workflow run
93+
});
94+
95+
// get waiters:
96+
const result = await client.getWaiters({
97+
eventId: "my-event-id",
98+
});
99+
```
100+
101+
## Contributing
102+
103+
### Setup
104+
105+
This project requires [Bun](https://bun.sh/) to be installed. Please see the [Bun installation documentation](https://bun.sh/docs/installation) for further instructions.
106+
107+
Once you have cloned the project, you will need to install the dependencies and then you can run the project.
108+
109+
```sh
110+
bun install
111+
bun run build
112+
```
113+
114+
### Testing
115+
116+
To begin testing, environment variables will need to be setup. First, create a `.env` file in the root of the project. [`.env.template`](/.env.template) can be used as a template. Your values can be found in the [Qstash Console](https://console.upstash.com/qstash).
117+
118+
```sh
119+
bun run test
120+
```

0 commit comments

Comments
 (0)