@sixb/sqlite 0.0.1

package/src/sync-run-storage.ts

@@ -0,0 +1,299 @@
+import type { Database } from "bun:sqlite"
+import type { JsonValue } from "@sixb/core"
+import type {
+  FinishSyncRunInput,
+  ListLatestSyncRunsInput,
+  ListLatestSyncRunsResult,
+  ListSyncRunsInput,
+  ListSyncRunsResult,
+  StartSyncRunInput,
+  SyncRunFailure,
+  SyncRunRecord,
+  SyncRunStorage,
+} from "@sixb/core/storage"
+import { SyncRunError } from "@sixb/core/storage"
+import { queryLatestRunsByOwnerId } from "./latest-run-query"
+import { installFreshSqliteSchema } from "./migrations"
+import {
+  appendRunListFilters,
+  hasEmptyStatuses,
+  queryRunList,
+  type SqliteValue,
+} from "./run-list-query"
+import {
+  closeSqliteStoreConnection,
+  openSqliteStoreConnection,
+  type SqliteStoreConnection,
+} from "./transactions"
+
+export interface SqliteSyncRunStorageOptions {
+  /** Path to SQLite database file. Defaults to ':memory:' for in-memory database. */
+  path?: string
+  /** Internal shared connection used by bundled SqliteStorage. */
+  connection?: SqliteStoreConnection
+}
+
+export class SqliteSyncRunStorage implements SyncRunStorage {
+  private readonly connection: SqliteStoreConnection
+  private readonly db: Database
+
+  constructor(options: SqliteSyncRunStorageOptions = {}) {
+    this.connection = openSqliteStoreConnection(options)
+    this.db = this.connection.db
+
+    if (this.connection.installFreshSchema) {
+      installFreshSqliteSchema(this.db)
+    }
+  }
+
+  async start(input: StartSyncRunInput): Promise<SyncRunRecord> {
+    const startedAt = input.startedAt ?? new Date()
+
+    try {
+      this.db
+        .query(
+          `
+          INSERT INTO sync_runs (
+            project_id,
+            id,
+            sync_id,
+            dataset_id,
+            mode,
+            status,
+            started_at,
+            expected_latest_version_id,
+            commit_message
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `
+        )
+        .run(
+          input.projectId,
+          input.id,
+          input.syncId,
+          input.datasetId,
+          input.mode,
+          "running",
+          startedAt.toISOString(),
+          input.expectedLatestVersionId ?? null,
+          input.commitMessage ?? null
+        )
+    } catch (error) {
+      if (isUniqueConstraintError(error)) {
+        throw new SyncRunError(
+          `[SixbSqlite] Sync run '${input.id}' already exists for project '${input.projectId}'.`
+        )
+      }
+
+      throw error
+    }
+
+    const record = await this.getById({ projectId: input.projectId, id: input.id })
+    if (!record) {
+      throw new SyncRunError(
+        `[SixbSqlite] Failed to load sync run '${input.id}' for project '${input.projectId}'.`
+      )
+    }
+
+    return record
+  }
+
+  async finish(input: FinishSyncRunInput): Promise<SyncRunRecord> {
+    return this.db.transaction(() => {
+      const existing = this.db
+        .query("SELECT * FROM sync_runs WHERE project_id = ? AND id = ?")
+        .get(input.projectId, input.id) as DatabaseRow | null
+
+      if (!existing) {
+        throw new SyncRunError(
+          `[SixbSqlite] Sync run '${input.id}' not found for project '${input.projectId}'.`
+        )
+      }
+
+      if (input.status === "succeeded") {
+        if (input.output && input.output.datasetId !== existing.dataset_id) {
+          throw new SyncRunError(
+            `[SixbSqlite] Sync run '${input.id}' output dataset '${input.output.datasetId}' does not match '${existing.dataset_id}'.`
+          )
+        }
+        if (!input.output && (existing.mode !== "append" || input.rowsRead !== 0)) {
+          throw new SyncRunError(
+            `[SixbSqlite] Sync run '${input.id}' may omit its output only for an empty append.`
+          )
+        }
+      }
+
+      this.db
+        .query(
+          `
+          UPDATE sync_runs
+          SET
+            status = ?,
+            finished_at = ?,
+            rows_read = ?,
+            output_version_id = ?,
+            error_name = ?,
+            error_message = ?,
+            checkpoint = ?
+          WHERE project_id = ? AND id = ?
+        `
+        )
+        .run(
+          input.status,
+          (input.finishedAt ?? new Date()).toISOString(),
+          input.status === "succeeded"
+            ? input.rowsRead
+            : (input.rowsRead ?? existing.rows_read ?? null),
+          input.status === "succeeded" ? (input.output?.versionId ?? null) : null,
+          input.status === "succeeded" ? null : (input.error?.name ?? null),
+          input.status === "succeeded" ? null : (input.error?.message ?? null),
+          input.status === "succeeded" ? serializeCheckpoint(input.checkpoint) : null,
+          input.projectId,
+          input.id
+        )
+
+      const updated = this.db
+        .query("SELECT * FROM sync_runs WHERE project_id = ? AND id = ?")
+        .get(input.projectId, input.id) as DatabaseRow
+
+      return rowToSyncRunRecord(updated)
+    })()
+  }
+
+  async getById(params: { projectId: string; id: string }): Promise<SyncRunRecord | null> {
+    const row = this.db
+      .query("SELECT * FROM sync_runs WHERE project_id = ? AND id = ?")
+      .get(params.projectId, params.id) as DatabaseRow | null
+
+    return row ? rowToSyncRunRecord(row) : null
+  }
+
+  async list(input: ListSyncRunsInput): Promise<ListSyncRunsResult> {
+    if (hasEmptyStatuses(input) || input.syncIds?.length === 0) {
+      return {
+        runs: [],
+        hasMore: false,
+        total: 0,
+      }
+    }
+
+    const whereClauses = ["project_id = ?"]
+    const args: SqliteValue[] = [input.projectId]
+
+    if (input.syncId) {
+      whereClauses.push("sync_id = ?")
+      args.push(input.syncId)
+    }
+
+    if (input.syncIds) {
+      whereClauses.push(`sync_id IN (${input.syncIds.map(() => "?").join(", ")})`)
+      args.push(...input.syncIds)
+    }
+
+    if (input.datasetId) {
+      whereClauses.push("dataset_id = ?")
+      args.push(input.datasetId)
+    }
+
+    appendRunListFilters(whereClauses, args, input)
+
+    const { rows, total, hasMore } = queryRunList<DatabaseRow>({
+      db: this.db,
+      tableName: "sync_runs",
+      whereClauses,
+      args,
+      order: input.order,
+      limit: input.limit,
+      offset: input.offset,
+    })
+
+    return {
+      runs: rows.map(rowToSyncRunRecord),
+      hasMore,
+      total,
+    }
+  }
+
+  async listLatestBySyncIds(input: ListLatestSyncRunsInput): Promise<ListLatestSyncRunsResult> {
+    const rows = queryLatestRunsByOwnerId<DatabaseRow>({
+      db: this.db,
+      tableName: "sync_runs",
+      ownerColumn: "sync_id",
+      ownerIds: input.syncIds,
+      projectId: input.projectId,
+      ownerIdFor: (row) => row.sync_id,
+    })
+
+    return {
+      runs: rows.map(rowToSyncRunRecord),
+    }
+  }
+
+  close(): void {
+    closeSqliteStoreConnection(this.connection)
+  }
+}
+
+function serializeCheckpoint(checkpoint: JsonValue | undefined): string | null {
+  return checkpoint !== undefined ? JSON.stringify(checkpoint) : null
+}
+
+function parseCheckpoint(value: string | null | undefined): JsonValue | undefined {
+  return value != null ? (JSON.parse(value) as JsonValue) : undefined
+}
+
+function toSyncRunFailure(row: DatabaseRow): SyncRunFailure | undefined {
+  if (!row.error_message) {
+    return undefined
+  }
+
+  return {
+    name: row.error_name ?? undefined,
+    message: row.error_message,
+  }
+}
+
+function rowToSyncRunRecord(row: DatabaseRow): SyncRunRecord {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    syncId: row.sync_id,
+    datasetId: row.dataset_id,
+    mode: row.mode,
+    status: row.status,
+    startedAt: new Date(row.started_at),
+    finishedAt: row.finished_at ? new Date(row.finished_at) : undefined,
+    rowsRead: row.rows_read ?? undefined,
+    output: row.output_version_id
+      ? {
+          datasetId: row.dataset_id,
+          versionId: row.output_version_id,
+        }
+      : undefined,
+    expectedLatestVersionId: row.expected_latest_version_id ?? undefined,
+    commitMessage: row.commit_message ?? undefined,
+    error: toSyncRunFailure(row),
+    checkpoint: parseCheckpoint(row.checkpoint),
+  }
+}
+
+function isUniqueConstraintError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("UNIQUE constraint failed")
+}
+
+interface DatabaseRow {
+  project_id: string
+  id: string
+  sync_id: string
+  dataset_id: string
+  mode: SyncRunRecord["mode"]
+  status: SyncRunRecord["status"]
+  started_at: string
+  finished_at: string | null
+  rows_read: number | null
+  output_version_id: string | null
+  expected_latest_version_id: string | null
+  commit_message: string | null
+  error_name: string | null
+  error_message: string | null
+  checkpoint: string | null
+}

package/src/timeseries-storage.ts

@@ -0,0 +1,212 @@
+import type { Database } from "bun:sqlite"
+import type {
+  TimeseriesHistoryBatchInput,
+  TimeseriesHistoryBatchResult,
+  TimeseriesPoint,
+  TimeseriesStorage,
+} from "@sixb/core/storage"
+import { installFreshSqliteSchema } from "./migrations"
+import {
+  closeSqliteStoreConnection,
+  openSqliteStoreConnection,
+  type SqliteStoreConnection,
+} from "./transactions"
+
+export interface SqliteTimeseriesStorageOptions {
+  /** Path to SQLite database file. Defaults to ':memory:' for in-memory database. */
+  path?: string
+  /** Internal shared connection used by bundled SqliteStorage. */
+  connection?: SqliteStoreConnection
+}
+
+/**
+ * SQLite-based TimeseriesStorage implementation.
+ *
+ * Stores time-series data with efficient querying for history and latest values.
+ */
+export class SqliteTimeseriesStorage implements TimeseriesStorage {
+  private readonly connection: SqliteStoreConnection
+  private readonly db: Database
+
+  constructor(options: SqliteTimeseriesStorageOptions = {}) {
+    this.connection = openSqliteStoreConnection(options)
+    this.db = this.connection.db
+
+    if (this.connection.installFreshSchema) {
+      installFreshSqliteSchema(this.db)
+    }
+  }
+
+  async getHistory(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+    from?: Date
+    to?: Date
+    limit?: number
+    order?: "asc" | "desc"
+  }): Promise<readonly TimeseriesPoint[]> {
+    let query = `
+      SELECT * FROM timeseries
+      WHERE project_id = ? AND object_type_id = ? AND object_id = ? AND property_id = ?
+    `
+    const args: (string | number | null)[] = [
+      params.projectId,
+      params.objectTypeId,
+      params.objectId,
+      params.propertyId,
+    ]
+
+    if (params.from) {
+      query += " AND at >= ?"
+      args.push(params.from.toISOString())
+    }
+
+    if (params.to) {
+      query += " AND at <= ?"
+      args.push(params.to.toISOString())
+    }
+
+    query += ` ORDER BY at ${params.order === "desc" ? "DESC" : "ASC"}`
+
+    if (params.limit !== undefined) {
+      query += " LIMIT ?"
+      args.push(params.limit)
+    }
+
+    const rows = this.db.query(query).all(...args) as DatabaseRow[]
+
+    return rows.map((row) => this.rowToPoint(row))
+  }
+
+  async getHistoryBatch(
+    input: TimeseriesHistoryBatchInput
+  ): Promise<readonly TimeseriesHistoryBatchResult[]> {
+    if (input.series.length === 0) {
+      return []
+    }
+
+    const order = input.order === "desc" ? "DESC" : "ASC"
+    const values = input.series.map(() => "(?, ?, ?, ?)").join(", ")
+    const args: (string | number | null)[] = []
+
+    input.series.forEach((series, index) => {
+      args.push(index, series.objectTypeId, series.objectId, series.propertyId)
+    })
+
+    let query = `
+      WITH requested(series_index, object_type_id, object_id, property_id) AS (
+        VALUES ${values}
+      ),
+      ranked AS (
+        SELECT
+          requested.series_index,
+          timeseries.*,
+          ROW_NUMBER() OVER (
+            PARTITION BY requested.series_index
+            ORDER BY timeseries.at ${order}
+          ) AS series_row_number
+        FROM requested
+        JOIN timeseries
+          ON timeseries.project_id = ?
+         AND timeseries.object_type_id = requested.object_type_id
+         AND timeseries.object_id = requested.object_id
+         AND timeseries.property_id = requested.property_id
+        WHERE 1 = 1
+    `
+    args.push(input.projectId)
+
+    if (input.from) {
+      query += " AND timeseries.at >= ?"
+      args.push(input.from.toISOString())
+    }
+
+    if (input.to) {
+      query += " AND timeseries.at <= ?"
+      args.push(input.to.toISOString())
+    }
+
+    query += "\n      )\n      SELECT * FROM ranked"
+
+    if (input.limitPerSeries !== undefined) {
+      query += " WHERE series_row_number <= ?"
+      args.push(Math.max(0, input.limitPerSeries))
+    }
+
+    query += ` ORDER BY series_index ASC, at ${order}`
+
+    const rows = this.db.query(query).all(...args) as (DatabaseRow & {
+      series_index: number
+      series_row_number: number
+    })[]
+    const results = input.series.map((series) => ({
+      ...series,
+      points: [] as TimeseriesPoint[],
+    }))
+
+    for (const row of rows) {
+      const result = results[row.series_index]
+      if (result) {
+        result.points.push(this.rowToPoint(row))
+      }
+    }
+
+    return results
+  }
+
+  async getLatest(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+  }): Promise<TimeseriesPoint | null> {
+    const row = this.db
+      .query(
+        `
+        SELECT * FROM timeseries
+        WHERE project_id = ? AND object_type_id = ? AND object_id = ? AND property_id = ?
+        ORDER BY at DESC
+        LIMIT 1
+      `
+      )
+      .get(
+        params.projectId,
+        params.objectTypeId,
+        params.objectId,
+        params.propertyId
+      ) as DatabaseRow | null
+
+    return row ? this.rowToPoint(row) : null
+  }
+  private rowToPoint(row: DatabaseRow): TimeseriesPoint {
+    return {
+      projectId: row.project_id,
+      objectTypeId: row.object_type_id,
+      objectId: row.object_id,
+      propertyId: row.property_id,
+      value: JSON.parse(row.value),
+      unit: row.unit ?? undefined,
+      at: new Date(row.at),
+      lastCommitId: row.last_commit_id,
+    }
+  }
+
+  /**
+   * Close the database connection.
+   */
+  close(): void {
+    closeSqliteStoreConnection(this.connection)
+  }
+}
+
+interface DatabaseRow {
+  project_id: string
+  object_type_id: string
+  object_id: string
+  property_id: string
+  value: string
+  unit: string | null
+  at: string
+  last_commit_id: string
+}

package/src/transactions.ts

@@ -0,0 +1,96 @@
+import type { Database } from "bun:sqlite"
+import { Database as SqliteDatabase } from "bun:sqlite"
+import { mkdirSync } from "node:fs"
+import { dirname } from "node:path"
+
+export interface SqliteStoreConnection {
+  readonly db: Database
+  readonly ownsConnection: boolean
+  readonly installFreshSchema: boolean
+}
+
+export interface SqliteStoreConnectionOptions {
+  readonly path?: string
+  readonly connection?: SqliteStoreConnection
+}
+
+export function openSqliteStoreConnection(
+  options: SqliteStoreConnectionOptions = {}
+): SqliteStoreConnection {
+  if (options.connection) {
+    return {
+      db: options.connection.db,
+      ownsConnection: false,
+      installFreshSchema: false,
+    }
+  }
+
+  const path = options.path ?? ":memory:"
+  if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true })
+  const db = new SqliteDatabase(path)
+  db.run("PRAGMA foreign_keys = ON")
+  return {
+    db,
+    ownsConnection: true,
+    installFreshSchema: path === ":memory:",
+  }
+}
+
+export function closeSqliteStoreConnection(connection: SqliteStoreConnection): void {
+  if (connection.ownsConnection) {
+    connection.db.close()
+  }
+}
+
+const activeImmediateTransactions = new WeakSet<Database>()
+
+export function runImmediateTransaction<T>(db: Database, run: () => T): T {
+  if (activeImmediateTransactions.has(db)) {
+    return run()
+  }
+
+  db.run("BEGIN IMMEDIATE")
+  activeImmediateTransactions.add(db)
+
+  try {
+    const result = run()
+    db.run("COMMIT")
+    return result
+  } catch (error) {
+    rollbackQuietly(db)
+    throw error
+  } finally {
+    activeImmediateTransactions.delete(db)
+  }
+}
+
+export async function runImmediateTransactionAsync<T>(
+  db: Database,
+  run: () => Promise<T> | T
+): Promise<T> {
+  if (activeImmediateTransactions.has(db)) {
+    return run()
+  }
+
+  db.run("BEGIN IMMEDIATE")
+  activeImmediateTransactions.add(db)
+
+  try {
+    const result = await run()
+    db.run("COMMIT")
+    return result
+  } catch (error) {
+    rollbackQuietly(db)
+    throw error
+  } finally {
+    activeImmediateTransactions.delete(db)
+  }
+}
+
+function rollbackQuietly(db: Database): void {
+  try {
+    db.run("ROLLBACK")
+  } catch {
+    // Preserve the original SQLite storage failure.
+  }
+}

package/src/validation.ts

@@ -0,0 +1,30 @@
+import { ProjectionRunError } from "@sixb/core/storage"
+
+export function assertProjectionRunFieldNonEmpty(value: string, fieldName: string): void {
+  if (value.trim().length === 0) {
+    throw new ProjectionRunError(`[SixbSqlite] Projection run ${fieldName} must not be empty.`)
+  }
+}
+
+export function assertProjectionRunCounter(value: number, fieldName: string): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new ProjectionRunError(
+      `[SixbSqlite] Projection run ${fieldName} must be a non-negative integer.`
+    )
+  }
+}
+
+export function assertOptionalProjectionRunCounter(
+  value: number | undefined,
+  fieldName: string
+): void {
+  if (value !== undefined) {
+    assertProjectionRunCounter(value, fieldName)
+  }
+}
+
+export function assertProjectionRunListWindowValue(value: number, fieldName: string): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new ProjectionRunError(`[SixbSqlite] Projection run list ${fieldName} must be >= 0.`)
+  }
+}