@yieldstar/core 0.1.0

package/dist/index.js

@@ -0,0 +1,151 @@
+// @bun
+// src/base/step.ts
+class StepResponse {
+}
+
+class StepKey extends StepResponse {
+  static type = "step-key";
+  type = "step-key";
+  key;
+  constructor(key) {
+    super();
+    this.key = key;
+  }
+}
+
+class StepCacheCheck extends StepResponse {
+  static type = "cache-check";
+  type = "cache-check";
+}
+
+class StepInvalid extends StepResponse {
+  static type = "step-invalid";
+  type = "step-invalid";
+}
+
+class StepResult extends StepResponse {
+  static type = "step-result";
+  type = "step-result";
+  result;
+  constructor(result) {
+    super();
+    this.result = result;
+  }
+}
+
+class WorkflowResult extends StepResponse {
+  static type = "workflow-result";
+  type = "workflow-result";
+  result;
+  constructor(result) {
+    super();
+    this.result = result;
+  }
+}
+
+class WorkflowDelay extends StepResponse {
+  static type = "workflow-delay";
+  type = "workflow-delay";
+  resumeIn;
+  constructor(resumeIn) {
+    super();
+    this.resumeIn = resumeIn;
+  }
+}
+
+class WorkflowRestart extends StepResponse {
+  static type = "workflow-restart";
+  type = "workflow-restart";
+  constructor() {
+    super();
+  }
+}
+
+class StepError extends StepResponse {
+  static type = "step-error";
+  type = "step-error";
+  err;
+  maxAttempts;
+  retryInterval;
+  backOffStrategy;
+  constructor(err, opts) {
+    super();
+    this.err = err;
+    this.maxAttempts = opts?.maxAttempts ? opts.maxAttempts : 1;
+    this.retryInterval = opts?.retryInterval ? opts.retryInterval : 60000;
+    this.backOffStrategy = opts?.backoffStrategy ? opts.backoffStrategy : "decay";
+  }
+}
+
+class StepDelay extends StepResponse {
+  static type = "step-delay";
+  type = "step-delay";
+  resumeIn;
+  constructor(resumeIn) {
+    super();
+    this.resumeIn = resumeIn;
+  }
+}
+// src/lib/workflow-runner.ts
+class WorkflowRunner {
+  heapClient;
+  schedulerClient;
+  router;
+  constructor(params) {
+    this.heapClient = params.heapClient;
+    this.schedulerClient = params.schedulerClient;
+    this.router = params.router;
+  }
+  run = async (task) => {
+    const { workflowId, executionId } = task;
+    const workflow = this.router[workflowId];
+    if (!workflow) {
+      throw new Error(`No workflow registered for "${workflowId}"`);
+    }
+    try {
+      const response = await this.runWorkflows({ executionId, workflow });
+      switch (response.type) {
+        case "workflow-result":
+          return response;
+        case "workflow-delay":
+          this.schedulerClient.requestWakeUp({
+            workflowId,
+            executionId,
+            resumeIn: response.resumeIn
+          });
+          break;
+      }
+    } catch (err) {
+      throw err;
+    }
+  };
+  async runWorkflows(params) {
+    const { executionId, workflow } = params;
+    const workflowIterator = workflow({
+      heapClient: this.heapClient,
+      executionId
+    });
+    const iteratorResult = await workflowIterator.next();
+    const stageResponse = iteratorResult.value;
+    if (iteratorResult.done) {
+      return stageResponse;
+    }
+    if (stageResponse instanceof StepDelay) {
+      return new WorkflowDelay(stageResponse.resumeIn - Date.now());
+    }
+    throw new Error("Workflow runner critical error");
+  }
+}
+export {
+  WorkflowRunner,
+  WorkflowResult,
+  WorkflowRestart,
+  WorkflowDelay,
+  StepResult,
+  StepResponse,
+  StepKey,
+  StepInvalid,
+  StepError,
+  StepDelay,
+  StepCacheCheck
+};

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@yieldstar/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "src/index.ts",
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target bun --packages=external"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/base/heap.ts

@@ -0,0 +1,18 @@
+export type HeapRecord = {
+  stepResponseJson: string;
+  meta: { attempt: number; done: boolean };
+};
+
+export abstract class HeapClient {
+  abstract readStep(params: {
+    executionId: string;
+    stepKey: string;
+  }): Promise<HeapRecord | null>;
+  abstract writeStep(params: {
+    executionId: string;
+    stepKey: string;
+    stepAttempt: number;
+    stepDone: boolean;
+    stepResponseJson: string;
+  }): Promise<void>;
+}

package/src/base/invoker.ts

@@ -0,0 +1,7 @@
+import type { EventEmitter } from "node:events";
+import type { Task } from "./runtime";
+
+export type WorkflowInvoker = {
+  workflowEndEmitter: EventEmitter;
+  execute(task: Task): Promise<void>;
+};

package/src/base/runtime.ts

@@ -0,0 +1,7 @@
+import type { WorkflowResult } from "./step";
+
+export type Task = { workflowId: string; executionId: string; params?: any };
+
+export type TaskProcessor = <T = any>(
+  task: Task
+) => Promise<void | WorkflowResult<T>>;

package/src/base/scheduler.ts

@@ -0,0 +1,7 @@
+export interface SchedulerClient {
+  requestWakeUp(params: {
+    workflowId: string;
+    executionId: string;
+    resumeIn: number;
+  }): Promise<void>;
+}

package/src/base/step.ts

@@ -0,0 +1,96 @@
+export abstract class StepResponse {
+  abstract type: string;
+}
+
+export class StepKey extends StepResponse {
+  static type = "step-key";
+  readonly type = "step-key";
+  key: string | null;
+  constructor(key: string | null) {
+    super();
+    this.key = key;
+  }
+}
+
+export class StepCacheCheck extends StepResponse {
+  static type = "cache-check";
+  readonly type = "cache-check";
+}
+
+export class StepInvalid extends StepResponse {
+  static type = "step-invalid";
+  readonly type = "step-invalid";
+}
+
+export class StepResult extends StepResponse {
+  static type = "step-result";
+  readonly type = "step-result";
+  result: any;
+  constructor(result: any) {
+    super();
+    this.result = result;
+  }
+}
+
+export class WorkflowResult<T extends any> extends StepResponse {
+  static type = "workflow-result";
+  readonly type = "workflow-result";
+  result: T;
+  constructor(result: T) {
+    super();
+    this.result = result;
+  }
+}
+
+export class WorkflowDelay extends StepResponse {
+  static type = "workflow-delay";
+  readonly type = "workflow-delay";
+  resumeIn: number;
+  constructor(resumeIn: number) {
+    super();
+    this.resumeIn = resumeIn;
+  }
+}
+
+export class WorkflowRestart extends StepResponse {
+  static type = "workflow-restart";
+  readonly type = "workflow-restart";
+  constructor() {
+    super();
+  }
+}
+
+export class StepError extends StepResponse {
+  static type = "step-error";
+  readonly type = "step-error";
+  err: any;
+  maxAttempts: number;
+  retryInterval: number;
+  backOffStrategy: "linear" | "decay";
+  constructor(
+    err: any,
+    opts?: {
+      maxAttempts: number;
+      retryInterval?: number;
+      backoffStrategy?: "linear" | "decay";
+    }
+  ) {
+    super();
+    this.err = err;
+    this.maxAttempts = opts?.maxAttempts ? opts.maxAttempts : 1;
+    this.retryInterval = opts?.retryInterval ? opts.retryInterval : 60000;
+    this.backOffStrategy = opts?.backoffStrategy
+      ? opts.backoffStrategy
+      : "decay";
+  }
+}
+
+export class StepDelay extends StepResponse {
+  static type = "step-delay";
+  readonly type = "step-delay";
+  resumeIn: number;
+  constructor(resumeIn: number) {
+    super();
+    this.resumeIn = resumeIn;
+  }
+}

package/src/base/workflow.ts

@@ -0,0 +1,15 @@
+import { HeapClient } from "./heap";
+import { StepResponse, WorkflowResult } from "./step";
+
+export type WorkflowGenerator<T = any> = (params: {
+  executionId: string;
+  heapClient: HeapClient;
+}) => AsyncGenerator<StepResponse, WorkflowResult<T>, StepResponse>;
+
+export type WorkflowGeneratorReturnType<CG> = CG extends WorkflowGenerator<
+  infer T
+>
+  ? T
+  : never;
+
+export type WorkflowRouter = Record<string, WorkflowGenerator>;

package/src/index.ts

@@ -0,0 +1,24 @@
+export type { HeapClient, HeapRecord } from "./base/heap";
+export type { WorkflowInvoker } from "./base/invoker";
+export type { Task, TaskProcessor } from "./base/runtime";
+export type { SchedulerClient } from "./base/scheduler";
+export type {
+  WorkflowGenerator,
+  WorkflowGeneratorReturnType,
+  WorkflowRouter,
+} from "./base/workflow";
+
+export {
+  StepCacheCheck,
+  StepDelay,
+  StepError,
+  StepInvalid,
+  StepKey,
+  StepResponse,
+  StepResult,
+  WorkflowDelay,
+  WorkflowRestart,
+  WorkflowResult,
+} from "./base/step";
+
+export { WorkflowRunner } from "./lib/workflow-runner";

package/src/lib/workflow-runner.ts

@@ -0,0 +1,79 @@
+import type {
+  WorkflowGenerator,
+  HeapClient,
+  SchedulerClient,
+  TaskProcessor,
+} from "..";
+import { StepDelay, WorkflowDelay, WorkflowResult } from "..";
+
+export class WorkflowRunner<
+  Router extends Record<string, WorkflowGenerator<any>>
+> {
+  private heapClient: HeapClient;
+  private schedulerClient: SchedulerClient;
+  private router: Router;
+
+  constructor(params: {
+    heapClient: HeapClient;
+    schedulerClient: SchedulerClient;
+    router: Router;
+  }) {
+    this.heapClient = params.heapClient;
+    this.schedulerClient = params.schedulerClient;
+    this.router = params.router;
+  }
+
+  run: TaskProcessor = async (task) => {
+    const { workflowId, executionId } = task;
+    const workflow = this.router[workflowId];
+
+    if (!workflow) {
+      throw new Error(`No workflow registered for "${workflowId}"`);
+    }
+
+    try {
+      const response = await this.runWorkflows({ executionId, workflow });
+
+      switch (response.type) {
+        case "workflow-result":
+          return response;
+
+        case "workflow-delay":
+          this.schedulerClient.requestWakeUp({
+            workflowId,
+            executionId,
+            resumeIn: response.resumeIn,
+          });
+          break;
+      }
+    } catch (err) {
+      // todo: distinguish between a workflow error and a system error
+      throw err;
+    }
+  };
+
+  private async runWorkflows<T>(params: {
+    executionId: string;
+    workflow: WorkflowGenerator<T>;
+  }): Promise<WorkflowResult<T> | WorkflowDelay> {
+    const { executionId, workflow } = params;
+
+    const workflowIterator = workflow({
+      heapClient: this.heapClient,
+      executionId,
+    });
+
+    const iteratorResult = await workflowIterator.next();
+    const stageResponse = iteratorResult.value;
+
+    if (iteratorResult.done) {
+      return stageResponse as WorkflowResult<T>;
+    }
+
+    if (stageResponse instanceof StepDelay) {
+      return new WorkflowDelay(stageResponse.resumeIn - Date.now());
+    }
+
+    throw new Error("Workflow runner critical error");
+  }
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}