yieldstar bun monorepo example

An example project showing how use yieldstar with Bun in a monorepo.

Project Overview

The architecture consists of three main services:

1. Workflows Service: Defines workflows that can be shared across services
2. Engine Service: Runs a workflow engine with SQLite persistence
3. Webapp Service: A client application that triggers workflows

Prerequisites

• Bun (latest version)

Project Structure

monorepo-yieldstar/

├── workflows/     # Shared workflow definitions
├── engine/        # yieldstar workflow engine implementation
├── webapp/        # Client application that uses workflows
├── package.json   # Root package.json with workspaces config

Getting Started

1. Clone the repository
2. Install dependencies:

bun install

3. Start the workflow engine:

cd engine
bun run serve

4. In a separate terminal, run the webapp to trigger a workflow:

cd webapp
bun run start

How It Works

Workflows Service

The workflows service defines workflows using createWorkflow. Each workflow is defined as a generator function that yields steps to be executed.

Example workflow (workflows/src/email.ts):

import { createWorkflow } from "yieldstar";

export const sendEmailAddress = createWorkflow(async function* (step) {
  yield* step.run(() => {
    console.log("\nwarming up email servers\n");
  });

  yield* step.delay(4000);

  const result = yield* step.run(() => {
    console.log("\nsending email!\n");
    return { status: "success" };
  });

  return result;
});

The service also exports a router and SDK factory for other services to trigger workflows:

// Router (workflows/src/router.ts)
import { createWorkflowRouter } from "yieldstar";
import { sendEmailAddress } from "./email";

export const workflowRouter = createWorkflowRouter({
  "send-email-workflow": sendEmailAddress,
});

// SDK (workflows/src/sdk.ts)
import { createHttpSdkFactory } from "yieldstar";
import { workflowRouter } from "./router";

export const createWorkflowSdk = createHttpSdkFactory(workflowRouter);

Engine Service

The engine service runs a workflow engine with SQLite persistence. It consists of:

1. Server: HTTP server that receives workflow requests
2. Worker: Executes workflow steps
3. Runtime: SQLite-based persistence for workflow state

Webapp Service

The webapp service demonstrates how to use the workflow SDK to trigger workflows:

import { createWorkflowSdk } from "workflows";

const workflowSdk = createWorkflowSdk({ host: "localhost", port: 8080 });

const sendResult = await workflowSdk.triggerAndWait("send-email-workflow");

console.log(sendResult);

Key yieldstar Features Demonstrated

• Workflow definition with createWorkflow
• Workflow routing with createWorkflowRouter
• HTTP SDK generation with createHttpSdkFactory
• Workflow execution with Bun workers
• SQLite-based persistence for workflow state
• Workflow triggering and waiting for results

Dependencies

This project uses the following yieldstar packages:

• yieldstar: Core package
• @yieldstar/core: Core workflow engine
• @yieldstar/bun-http-server: HTTP server for Bun
• @yieldstar/bun-sqlite-runtime: SQLite persistence for Bun
• @yieldstar/bun-worker-invoker: Worker execution for Bun

License

MIT