@yieldstar/sqlite-runtime 0.5.0

package/src/dao/timers-dao.ts

@@ -0,0 +1,81 @@
+import type { WorkflowEvent } from "@yieldstar/core";
+import type { SqliteDriver } from "../sqlite-driver";
+
+class TimerRow {
+  id!: string;
+  delay!: number;
+  workflow_id!: string;
+  execution_id!: string;
+  created_at!: number;
+  params?: string;
+  context?: string;
+}
+
+class CountRow {
+  count!: number;
+}
+
+export class TimersDao {
+  private db: SqliteDriver;
+
+  constructor(db: SqliteDriver) {
+    this.db = db;
+    this.setupDb();
+  }
+
+  private setupDb() {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS scheduled_tasks (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        delay INTEGER NOT NULL,
+        workflow_id TEXT NOT NULL,
+        execution_id TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        params TEXT,
+        context TEXT
+      );
+    `);
+  }
+
+  getExpiredTimers(): TimerRow[] {
+    const query = this.db.query<TimerRow>(
+      `SELECT id, delay, workflow_id, execution_id, created_at, params, context
+       FROM scheduled_tasks
+       WHERE (created_at + delay) < $currentTime`
+    );
+
+    return query.all({ $currentTime: Date.now() });
+  }
+
+  getTaskCount() {
+    const query = this.db.query<CountRow>(
+      `SELECT COUNT(*) as count
+       FROM scheduled_tasks
+       WHERE (created_at + delay) < $currentTime`
+    );
+
+    const count = query.get({ $currentTime: Date.now() })!;
+    return count.count;
+  }
+
+  insertTimer(event: WorkflowEvent, delay: number) {
+    const query = this.db.query(
+      `INSERT INTO scheduled_tasks (delay, workflow_id, execution_id, created_at, params, context) 
+      VALUES ($delay, $workflowId, $executionId, $createdAt, $params, $context)`
+    );
+
+    query.run({
+      $delay: delay,
+      $workflowId: event.workflowId,
+      $executionId: event.executionId,
+      $createdAt: Date.now(),
+      $params: event.params ? JSON.stringify(event.params) : null,
+      $context: JSON.stringify(Array.from(event.context.entries())),
+    });
+  }
+
+  deleteTimerById(id: string) {
+    const query = this.db.query(`DELETE FROM scheduled_tasks WHERE id = $id`);
+    query.run({ $id: id });
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { SqliteHeapClient } from "./sqlite-heap";
+export { SqliteStoreClient } from "./sqlite-store";
+export { SqliteSchedulerClient } from "./sqlite-scheduler";
+export { SqliteEventLoop } from "./sqlite-event-loop";
+export { SqliteTaskQueueClient } from "./sqlite-task-queue";
+export { SqliteTimersClient } from "./sqlite-timers";
+export type {
+  SqliteDriver,
+  SqliteParameters,
+  SqliteParameterValue,
+  SqliteRunResult,
+  SqliteStatement,
+} from "./sqlite-driver";
+export type { SqliteDbOpts } from "./sqlite-db";

package/src/node.ts

@@ -0,0 +1,47 @@
+import { DatabaseSync, type SQLInputValue } from "node:sqlite";
+import {
+  createSqliteDriver,
+  wrapSqliteStatement,
+  type SqliteDbOpts,
+} from "./sqlite-db";
+import type {
+  SqliteDriver,
+  SqliteParameters,
+  SqliteStatement,
+} from "./sqlite-driver";
+
+export * from "./index";
+
+export class NodeSqliteDriver implements SqliteDriver {
+  constructor(private readonly database: DatabaseSync) {}
+
+  run(sql: string) {
+    this.database.exec(sql);
+  }
+
+  query<Row>(sql: string): SqliteStatement<Row> {
+    return wrapSqliteStatement(this.database.prepare(sql), normalizeParameters);
+  }
+
+  close() {
+    this.database.close();
+  }
+}
+
+function normalizeParameters(
+  parameters: SqliteParameters
+): Record<string, SQLInputValue> {
+  return Object.fromEntries(
+    Object.entries(parameters).map(([name, value]) => [
+      name,
+      typeof value === "boolean" ? Number(value) : value,
+    ])
+  );
+}
+
+export function createSqliteDb(opts?: SqliteDbOpts) {
+  return createSqliteDriver(
+    (path) => new NodeSqliteDriver(new DatabaseSync(path)),
+    opts
+  );
+}

package/src/sqlite-db.ts

@@ -0,0 +1,70 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type {
+  SqliteDriver,
+  SqliteParameters,
+  SqliteRunResult,
+  SqliteStatement,
+} from "./sqlite-driver";
+
+export type SqliteDbOpts = {
+  /**
+   * Path to the SQLite database file
+   * @default "./.db/yieldstar.sqlite"
+   */
+  path?: string;
+  /**
+   * Enable Write-Ahead Logging (WAL) mode.
+   * Recommended for better performance and concurrency.
+   * @default true
+   */
+  wal?: boolean;
+};
+
+const defaultOpts: Required<SqliteDbOpts> = {
+  path: "./.db/yieldstar.sqlite",
+  wal: true,
+};
+
+export function createSqliteDriver<Driver extends SqliteDriver>(
+  create: (path: string) => Driver,
+  opts?: SqliteDbOpts
+) {
+  const mergedOpts = { ...defaultOpts, ...opts };
+  mkdirSync(dirname(mergedOpts.path), { recursive: true });
+
+  const db = create(mergedOpts.path);
+  if (mergedOpts.wal) {
+    db.run("PRAGMA journal_mode = WAL");
+  }
+  db.run("PRAGMA busy_timeout = 5000");
+  return db;
+}
+
+/** The native prepared-statement shape connectors adapt to SqliteStatement. */
+type NativeStatement = {
+  get(parameters?: any): unknown;
+  all(parameters?: any): unknown[];
+  run(parameters?: any): SqliteRunResult;
+};
+
+/**
+ * Adapt a native prepared statement to the SqliteStatement contract: bind
+ * parameters are only passed when provided, with `bind` mapping them to the
+ * native driver's binding shape.
+ */
+export function wrapSqliteStatement<Row>(
+  statement: NativeStatement,
+  bind: (parameters: SqliteParameters) => any = (parameters) => parameters
+): SqliteStatement<Row> {
+  return {
+    get: (parameters) =>
+      (parameters ? statement.get(bind(parameters)) : statement.get()) as
+        | Row
+        | undefined,
+    all: (parameters) =>
+      (parameters ? statement.all(bind(parameters)) : statement.all()) as Row[],
+    run: (parameters) =>
+      parameters ? statement.run(bind(parameters)) : statement.run(),
+  };
+}

package/src/sqlite-driver.ts

@@ -0,0 +1,30 @@
+export type SqliteParameterValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Uint8Array
+  | null;
+
+export type SqliteParameters = Record<`$${string}`, SqliteParameterValue>;
+
+export type SqliteRunResult = {
+  changes: number | bigint;
+};
+
+/**
+ * Callers must supply exactly the named parameters used by the SQL, including
+ * each `$` prefix. Connectors do not normalize additional names because native
+ * drivers differ: some ignore them while others throw.
+ */
+export interface SqliteStatement<Row> {
+  get(parameters?: SqliteParameters): Row | undefined;
+  all(parameters?: SqliteParameters): Row[];
+  run(parameters?: SqliteParameters): SqliteRunResult;
+}
+
+export interface SqliteDriver {
+  run(sql: string): void;
+  query<Row>(sql: string): SqliteStatement<Row>;
+  close(): void;
+}

package/src/sqlite-event-loop.ts

@@ -0,0 +1,41 @@
+import { SqliteTaskQueue } from "./sqlite-task-queue";
+import { SqliteTimers } from "./sqlite-timers";
+import type { EventProcessor } from "@yieldstar/core";
+import type { Logger } from "pino";
+import type { SqliteDriver } from "./sqlite-driver";
+
+export class SqliteEventLoop {
+  taskQueue: SqliteTaskQueue;
+  timers: SqliteTimers;
+  private isRunning: boolean = false;
+
+  constructor(db: SqliteDriver) {
+    this.taskQueue = new SqliteTaskQueue(db);
+    this.timers = new SqliteTimers({ db, taskQueue: this.taskQueue });
+  }
+
+  start(params: { onNewEvent: EventProcessor; logger: Logger }) {
+    this.isRunning = true;
+    this.loop(params.onNewEvent, params.logger);
+  }
+
+  stop() {
+    this.isRunning = false;
+  }
+
+  private async loop(processEvent: EventProcessor, logger: Logger) {
+    if (!this.isRunning) return;
+
+    while (!this.taskQueue.isEmpty) {
+      const task = this.taskQueue.process();
+      if (task) {
+        await processEvent(task.event, logger);
+        this.taskQueue.remove(task.taskId);
+      }
+    }
+
+    this.timers.processTimers();
+
+    setTimeout(() => this.loop(processEvent, logger), 10);
+  }
+}

package/src/sqlite-heap.ts

@@ -0,0 +1,54 @@
+import type { HeapClient } from "@yieldstar/core";
+import { StepResponsesDao } from "./dao/step-response-dao";
+import type { SqliteDriver } from "./sqlite-driver";
+
+export class SqliteHeapClient implements HeapClient {
+  private stepResponsesDao: StepResponsesDao;
+
+  constructor(db: SqliteDriver) {
+    this.stepResponsesDao = new StepResponsesDao(db);
+  }
+
+  async getAllSteps() {
+    return this.stepResponsesDao.getAllSteps();
+  }
+
+  async deleteAll() {
+    this.stepResponsesDao.deleteAll();
+  }
+
+  async readStep(params: { executionId: string; stepKey: string }) {
+    const result = this.stepResponsesDao.getLatestStepResponse(
+      params.executionId,
+      params.stepKey
+    );
+
+    if (!result?.step_response) {
+      return null;
+    }
+
+    return {
+      stepResponseJson: result.step_response,
+      meta: {
+        attempt: result.step_attempt,
+        done: Boolean(result.step_done),
+      },
+    };
+  }
+
+  async writeStep(params: {
+    executionId: string;
+    stepKey: string;
+    stepAttempt: number;
+    stepDone: boolean;
+    stepResponseJson: string;
+  }) {
+    this.stepResponsesDao.insertStepResponse(
+      params.executionId,
+      params.stepKey,
+      params.stepAttempt,
+      params.stepDone,
+      params.stepResponseJson
+    );
+  }
+}

package/src/sqlite-scheduler.ts

@@ -0,0 +1,24 @@
+import type { SchedulerClient, WorkflowEvent } from "@yieldstar/core";
+import { SqliteTaskQueueClient } from "./sqlite-task-queue";
+import { SqliteTimersClient } from "./sqlite-timers";
+
+export class SqliteSchedulerClient implements SchedulerClient {
+  private taskQueue: SqliteTaskQueueClient;
+  private timersClient: SqliteTimersClient;
+
+  constructor(params: {
+    taskQueueClient: SqliteTaskQueueClient;
+    timersClient: SqliteTimersClient;
+  }) {
+    this.taskQueue = params.taskQueueClient;
+    this.timersClient = params.timersClient;
+  }
+
+  async requestWakeUp(event: WorkflowEvent, resumeIn?: number) {
+    if (resumeIn) {
+      this.timersClient.createTimer(event, resumeIn);
+    } else {
+      this.taskQueue.add(event);
+    }
+  }
+}