@pickleball/expo-sdk 0.1.1

package/src/match/persistence/default-store.native.ts

@@ -0,0 +1,20 @@
+import { createExpoSqliteMatchDriver } from "./sqlite-driver";
+import { MatchEventStore } from "./store";
+
+const defaultStores = new Map<string, Promise<MatchEventStore>>();
+
+export function createDefaultMatchEventStore(
+  databaseName = "pickleball-matches.db",
+): Promise<MatchEventStore> {
+  const existing = defaultStores.get(databaseName);
+  if (existing) return existing;
+  const pending = import("expo-sqlite").then(async ({ openDatabaseAsync }) => {
+    const database = await openDatabaseAsync(databaseName, { useNewConnection: true });
+    return new MatchEventStore(createExpoSqliteMatchDriver(database));
+  });
+  defaultStores.set(databaseName, pending);
+  void pending.catch(() => {
+    if (defaultStores.get(databaseName) === pending) defaultStores.delete(databaseName);
+  });
+  return pending;
+}

package/src/match/persistence/default-store.ts

@@ -0,0 +1,11 @@
+import { MatchEventStore } from "./store";
+import { MatchPersistenceError } from "./types";
+
+export async function createDefaultMatchEventStore(
+  _databaseName = "pickleball-matches.db",
+): Promise<MatchEventStore> {
+  throw new MatchPersistenceError(
+    "storage_failure",
+    "The default match store requires a native iOS or Android Expo runtime",
+  );
+}

package/src/match/persistence/index.ts

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./migrations";
+export * from "./memory-driver";
+export * from "./sqlite-driver";
+export * from "./store";
+export * from "./default-store";

package/src/match/persistence/memory-driver.ts

@@ -0,0 +1,255 @@
+import type {
+  MatchPersistenceDriver,
+  MatchPersistenceTransaction,
+  StoredMatchEventRow,
+  StoredMatchRow,
+} from "./types";
+import type { RemoteBinding } from "../remote/types";
+
+interface MemoryState {
+  migrationVersion: number;
+  remoteBinding: RemoteBinding | null;
+  activeMatchId: string | null;
+  matches: StoredMatchRow[];
+  events: StoredMatchEventRow[];
+  nextOrdinal: number;
+  ordinals: Record<string, number>;
+}
+
+function cloneState(state: MemoryState): MemoryState {
+  return {
+    migrationVersion: state.migrationVersion,
+    remoteBinding: state.remoteBinding ? { ...state.remoteBinding } : null,
+    activeMatchId: state.activeMatchId,
+    matches: state.matches.map((row) => ({ ...row })),
+    events: state.events.map((row) => ({ ...row })),
+    nextOrdinal: state.nextOrdinal,
+    ordinals: { ...state.ordinals },
+  };
+}
+
+export class MemoryMatchPersistenceDriver implements MatchPersistenceDriver {
+  private state: MemoryState = {
+    migrationVersion: 0,
+    remoteBinding: null,
+    activeMatchId: null,
+    matches: [],
+    events: [],
+    nextOrdinal: 0,
+    ordinals: {},
+  };
+  private eventInsertFailure: Error | null = null;
+  private snapshotUpdateFailure: Error | null = null;
+  private transactionTail: Promise<void> = Promise.resolve();
+
+  async migrate() {
+    this.state.migrationVersion = 2;
+  }
+
+  async getRemoteBinding() {
+    return this.state.remoteBinding ? { ...this.state.remoteBinding } : null;
+  }
+
+  async setRemoteBinding(binding: RemoteBinding | null) {
+    this.state.remoteBinding = binding ? { ...binding } : null;
+  }
+
+  getMigrationVersion() {
+    return this.state.migrationVersion;
+  }
+
+  async transaction<T>(
+    work: (transaction: MatchPersistenceTransaction) => Promise<T>,
+  ): Promise<T> {
+    const previous = this.transactionTail;
+    let release!: () => void;
+    this.transactionTail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      const draft = cloneState(this.state);
+      const transaction: MatchPersistenceTransaction = {
+        getMatch: async (matchId) => {
+          const row = draft.matches.find(
+            (candidate) => candidate.matchId === matchId,
+          );
+          return row ? { ...row } : null;
+        },
+        getEvents: async (matchId) =>
+          draft.events
+            .filter((row) => row.matchId === matchId)
+            .sort((left, right) => left.sequence - right.sequence)
+            .map((row) => ({ ...row })),
+        insertMatch: async (row) => {
+          if (draft.matches.some((candidate) => candidate.matchId === row.matchId)) {
+            throw new Error("match id already exists");
+          }
+          draft.matches.push({ ...row });
+          draft.ordinals[row.matchId] = draft.nextOrdinal;
+          draft.nextOrdinal += 1;
+        },
+        insertEvent: async (row) => {
+          if (this.eventInsertFailure) {
+            const failure = this.eventInsertFailure;
+            this.eventInsertFailure = null;
+            throw failure;
+          }
+          if (
+            draft.events.some(
+              (candidate) =>
+                candidate.eventId === row.eventId ||
+                (candidate.matchId === row.matchId && candidate.sequence === row.sequence),
+            )
+          ) {
+            throw new Error("event ordering constraint failed");
+          }
+          if (!draft.matches.some((candidate) => candidate.matchId === row.matchId)) {
+            throw new Error("event foreign key constraint failed");
+          }
+          draft.events.push({ ...row });
+        },
+        updateSnapshot: async (matchId, expectedSequence, row) => {
+          if (this.snapshotUpdateFailure) {
+            const failure = this.snapshotUpdateFailure;
+            this.snapshotUpdateFailure = null;
+            throw failure;
+          }
+          const index = draft.matches.findIndex(
+            (candidate) =>
+              candidate.matchId === matchId &&
+              candidate.snapshotSequence === expectedSequence,
+          );
+          if (index < 0) return false;
+          draft.matches[index] = { matchId, ...row };
+          return true;
+        },
+        setActiveMatch: async (matchId) => {
+          if (
+            matchId !== null &&
+            !draft.matches.some((candidate) => candidate.matchId === matchId)
+          ) {
+            throw new Error("active match foreign key constraint failed");
+          }
+          draft.activeMatchId = matchId;
+        },
+        clearActiveMatch: async (matchId) => {
+          if (draft.activeMatchId === matchId) draft.activeMatchId = null;
+        },
+      };
+      const result = await work(transaction);
+      this.state = draft;
+      return result;
+    } finally {
+      release();
+    }
+  }
+
+  async readMatch(matchId: string) {
+    const snapshot = cloneState(this.state);
+    return {
+      match: snapshot.matches.find((candidate) => candidate.matchId === matchId) ?? null,
+      events: snapshot.events
+        .filter((row) => row.matchId === matchId)
+        .sort((left, right) => left.sequence - right.sequence),
+    };
+  }
+
+  async getActiveMatchId() {
+    return this.state.activeMatchId;
+  }
+
+  async readActiveMatch() {
+    const snapshot = cloneState(this.state);
+    const activeMatchId = snapshot.activeMatchId;
+    if (!activeMatchId) {
+      return { activeMatchId: null, match: null, events: [] };
+    }
+    return {
+      activeMatchId,
+      match:
+        snapshot.matches.find((candidate) => candidate.matchId === activeMatchId) ??
+        null,
+      events: snapshot.events
+        .filter((row) => row.matchId === activeMatchId)
+        .sort((left, right) => left.sequence - right.sequence),
+    };
+  }
+
+  async readMatchList() {
+    const snapshot = cloneState(this.state);
+    return {
+      matches: snapshot.matches
+        .slice()
+        .sort(
+          (left, right) =>
+            right.updatedAt - left.updatedAt ||
+            snapshot.ordinals[right.matchId] - snapshot.ordinals[left.matchId],
+        ),
+      activeMatchId: snapshot.activeMatchId,
+    };
+  }
+
+  inspect() {
+    return cloneState(this.state);
+  }
+
+  failNextSnapshotUpdate(error: Error) {
+    this.snapshotUpdateFailure = error;
+  }
+
+  failNextEventInsert(error: Error) {
+    this.eventInsertFailure = error;
+  }
+
+  corruptSnapshotJson(matchId: string, snapshotJson: string) {
+    this.mutateMatch(matchId, (row) => ({ ...row, snapshotJson }));
+  }
+
+  corruptEventJson(matchId: string, sequence: number, eventJson: string) {
+    this.mutateEvent(matchId, sequence, (row) => ({ ...row, eventJson }));
+  }
+
+  corruptEventSchema(matchId: string, sequence: number, schemaVersion: number) {
+    this.mutateEvent(matchId, sequence, (row) => ({ ...row, schemaVersion }));
+  }
+
+  corruptEventSequence(matchId: string, sequence: number) {
+    this.mutateEvent(matchId, 0, (row) => ({ ...row, sequence }));
+  }
+
+  duplicateEventRow(matchId: string, sequence: number) {
+    const row = this.state.events.find(
+      (candidate) => candidate.matchId === matchId && candidate.sequence === sequence,
+    );
+    if (!row) throw new Error("event row not found");
+    this.state.events.push({ ...row });
+  }
+
+  removeEventRow(matchId: string, sequence: number) {
+    this.state.events = this.state.events.filter(
+      (row) => row.matchId !== matchId || row.sequence !== sequence,
+    );
+  }
+
+  private mutateMatch(
+    matchId: string,
+    mutation: (row: StoredMatchRow) => StoredMatchRow,
+  ) {
+    const index = this.state.matches.findIndex((row) => row.matchId === matchId);
+    if (index < 0) throw new Error("match row not found");
+    this.state.matches[index] = mutation(this.state.matches[index]);
+  }
+
+  private mutateEvent(
+    matchId: string,
+    sequence: number,
+    mutation: (row: StoredMatchEventRow) => StoredMatchEventRow,
+  ) {
+    const index = this.state.events.findIndex(
+      (row) => row.matchId === matchId && row.sequence === sequence,
+    );
+    if (index < 0) throw new Error("event row not found");
+    this.state.events[index] = mutation(this.state.events[index]);
+  }
+}

package/src/match/persistence/migrations.ts

@@ -0,0 +1,40 @@
+export const MATCH_SQL_SCHEMA_VERSION = 2 as const;
+
+export const MATCH_SQL_MIGRATIONS = [
+  `CREATE TABLE IF NOT EXISTS match_aggregates (
+    match_id TEXT PRIMARY KEY NOT NULL,
+    schema_version INTEGER NOT NULL CHECK (schema_version = 1),
+    snapshot_json TEXT NOT NULL,
+    snapshot_sequence INTEGER NOT NULL CHECK (snapshot_sequence >= 0),
+    status TEXT NOT NULL CHECK (status IN ('inProgress', 'completed', 'ended')),
+    updated_at INTEGER NOT NULL
+  )`,
+  `CREATE TABLE IF NOT EXISTS match_events (
+    match_id TEXT NOT NULL,
+    sequence INTEGER NOT NULL CHECK (sequence >= 0),
+    event_id TEXT NOT NULL UNIQUE,
+    schema_version INTEGER NOT NULL CHECK (schema_version = 1),
+    event_json TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (match_id, sequence),
+    FOREIGN KEY (match_id) REFERENCES match_aggregates(match_id) ON DELETE RESTRICT
+  )`,
+  `CREATE TABLE IF NOT EXISTS match_active_pointer (
+    slot INTEGER PRIMARY KEY NOT NULL CHECK (slot = 1),
+    match_id TEXT NOT NULL UNIQUE,
+    FOREIGN KEY (match_id) REFERENCES match_aggregates(match_id) ON DELETE RESTRICT
+  )`,
+  `CREATE INDEX IF NOT EXISTS match_aggregates_recent
+    ON match_aggregates(updated_at DESC)`,
+  `CREATE TRIGGER IF NOT EXISTS match_events_no_update
+    BEFORE UPDATE ON match_events
+    BEGIN SELECT RAISE(ABORT, 'match events are immutable'); END`,
+  `CREATE TRIGGER IF NOT EXISTS match_events_no_delete
+    BEFORE DELETE ON match_events
+    BEGIN SELECT RAISE(ABORT, 'match events are immutable'); END`,
+  `CREATE TABLE IF NOT EXISTS remote_binding (
+    slot INTEGER PRIMARY KEY NOT NULL CHECK (slot = 1),
+    device_id TEXT NOT NULL CHECK (length(trim(device_id)) > 0),
+    label TEXT
+  )`,
+] as const;

package/src/match/persistence/sqlite-driver.ts

@@ -0,0 +1,348 @@
+import { MATCH_SQL_MIGRATIONS, MATCH_SQL_SCHEMA_VERSION } from "./migrations";
+import {
+  MatchPersistenceError,
+  type MatchPersistenceDriver,
+  type MatchPersistenceTransaction,
+  type StoredMatchEventRow,
+  type StoredMatchRow,
+} from "./types";
+import type { RemoteBinding } from "../remote/types";
+/*
+ * Coordination is shared for every adapter wrapping the same Expo SQLite
+ * connection object. Distinct connections to the same file are coordinated by
+ * SQLite itself; busy_timeout bounds their lock wait instead of a process-global
+ * name registry that would retain database names indefinitely.
+ */
+interface ConnectionCoordination {
+  tail: Promise<void>;
+  poisoned: MatchPersistenceError | null;
+}
+
+const connectionCoordinators = new WeakMap<object, ConnectionCoordination>();
+
+function coordinationFor(database: ExpoSqliteDatabaseLike): ConnectionCoordination {
+  const existing = connectionCoordinators.get(database);
+  if (existing) return existing;
+  const coordination: ConnectionCoordination = {
+    tail: Promise.resolve(),
+    poisoned: null,
+  };
+  connectionCoordinators.set(database, coordination);
+  return coordination;
+}
+
+interface SqlRunResult {
+  readonly changes: number;
+  readonly lastInsertRowId: number;
+}
+
+interface SqlExecutor {
+  runAsync(sql: string, ...params: unknown[]): Promise<SqlRunResult>;
+  getFirstAsync<T>(sql: string, ...params: unknown[]): Promise<T | null>;
+  getAllAsync<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+}
+
+export interface ExpoSqliteDatabaseLike extends SqlExecutor {
+  execAsync(sql: string): Promise<void>;
+}
+
+interface SqlMatchRow {
+  match_id: string;
+  schema_version: number;
+  snapshot_json: string;
+  snapshot_sequence: number;
+  status: StoredMatchRow["status"];
+  updated_at: number;
+}
+
+interface SqlEventRow {
+  match_id: string;
+  sequence: number;
+  event_id: string;
+  schema_version: number;
+  event_json: string;
+  created_at: number;
+}
+
+const mapMatchRow = (row: SqlMatchRow): StoredMatchRow => ({
+  matchId: row.match_id,
+  schemaVersion: row.schema_version,
+  snapshotJson: row.snapshot_json,
+  snapshotSequence: row.snapshot_sequence,
+  status: row.status,
+  updatedAt: row.updated_at,
+});
+
+const mapEventRow = (row: SqlEventRow): StoredMatchEventRow => ({
+  matchId: row.match_id,
+  sequence: row.sequence,
+  eventId: row.event_id,
+  schemaVersion: row.schema_version,
+  eventJson: row.event_json,
+  createdAt: row.created_at,
+});
+
+function transactionFor(executor: SqlExecutor): MatchPersistenceTransaction {
+  return {
+    async getMatch(matchId) {
+      const row = await executor.getFirstAsync<SqlMatchRow>(
+        "SELECT * FROM match_aggregates WHERE match_id = ?",
+        matchId,
+      );
+      return row ? mapMatchRow(row) : null;
+    },
+    async getEvents(matchId) {
+      const rows = await executor.getAllAsync<SqlEventRow>(
+        "SELECT * FROM match_events WHERE match_id = ? ORDER BY sequence ASC",
+        matchId,
+      );
+      return rows.map(mapEventRow);
+    },
+    async insertMatch(row) {
+      await executor.runAsync(
+        `INSERT INTO match_aggregates
+          (match_id, schema_version, snapshot_json, snapshot_sequence, status, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?)`,
+        row.matchId,
+        row.schemaVersion,
+        row.snapshotJson,
+        row.snapshotSequence,
+        row.status,
+        row.updatedAt,
+      );
+    },
+    async insertEvent(row) {
+      await executor.runAsync(
+        `INSERT INTO match_events
+          (match_id, sequence, event_id, schema_version, event_json, created_at)
+          VALUES (?, ?, ?, ?, ?, ?)`,
+        row.matchId,
+        row.sequence,
+        row.eventId,
+        row.schemaVersion,
+        row.eventJson,
+        row.createdAt,
+      );
+    },
+    async updateSnapshot(matchId, expectedSequence, row) {
+      const result = await executor.runAsync(
+        `UPDATE match_aggregates
+          SET schema_version = ?, snapshot_json = ?, snapshot_sequence = ?, status = ?, updated_at = ?
+          WHERE match_id = ? AND snapshot_sequence = ?`,
+        row.schemaVersion,
+        row.snapshotJson,
+        row.snapshotSequence,
+        row.status,
+        row.updatedAt,
+        matchId,
+        expectedSequence,
+      );
+      return result.changes === 1;
+    },
+    async setActiveMatch(matchId) {
+      if (matchId === null) {
+        await executor.runAsync("DELETE FROM match_active_pointer WHERE slot = 1");
+        return;
+      }
+      await executor.runAsync(
+        `INSERT INTO match_active_pointer (slot, match_id) VALUES (1, ?)
+          ON CONFLICT(slot) DO UPDATE SET match_id = excluded.match_id`,
+        matchId,
+      );
+    },
+    async clearActiveMatch(matchId) {
+      await executor.runAsync(
+        "DELETE FROM match_active_pointer WHERE slot = 1 AND match_id = ?",
+        matchId,
+      );
+    },
+  };
+}
+
+/**
+ * Serializes adapters sharing this exact connection object. Separate
+ * connections to the same file rely on SQLite locking plus busy_timeout.
+ */
+export function createExpoSqliteMatchDriver(
+  database: ExpoSqliteDatabaseLike,
+): MatchPersistenceDriver {
+  const coordination = coordinationFor(database);
+
+  function poisonAfterRollbackFailure(error: unknown) {
+    if (!coordination.poisoned) {
+      coordination.poisoned = new MatchPersistenceError(
+        "storage_failure",
+        "The SQLite connection is unusable after rollback failed",
+        { cause: error },
+      );
+    }
+  }
+
+  async function runSerialized<T>(work: () => Promise<T>): Promise<T> {
+    const previous = coordination.tail;
+    let release!: () => void;
+    coordination.tail = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      if (coordination.poisoned) throw coordination.poisoned;
+      return await work();
+    } finally {
+      release();
+    }
+  }
+
+  function runAtomic<T>(
+    begin: "BEGIN" | "BEGIN IMMEDIATE",
+    work: (transaction: MatchPersistenceTransaction) => Promise<T>,
+  ): Promise<T> {
+    return runSerialized(async () => {
+      let began = false;
+      try {
+        await database.execAsync(begin);
+        began = true;
+        const result = await work(transactionFor(database));
+        await database.execAsync("COMMIT");
+        return result;
+      } catch (error) {
+        if (!began) throw error;
+        try {
+          await database.execAsync("ROLLBACK");
+        } catch (rollbackError) {
+          poisonAfterRollbackFailure(rollbackError);
+        }
+        throw error;
+      }
+    });
+  }
+
+  return {
+    async migrate() {
+      await runSerialized(async () => {
+        await database.execAsync("PRAGMA busy_timeout = 5000");
+        await database.execAsync("PRAGMA foreign_keys = ON");
+        const foreignKeys = await database.getFirstAsync<{ foreign_keys: number }>(
+          "PRAGMA foreign_keys",
+        );
+        if (foreignKeys?.foreign_keys !== 1) {
+          throw new MatchPersistenceError(
+            "storage_failure",
+            "SQLite foreign-key enforcement could not be enabled",
+          );
+        }
+        const version = await database.getFirstAsync<{ user_version: number }>(
+          "PRAGMA user_version",
+        );
+        if (!version || !Number.isInteger(version.user_version)) {
+          throw new MatchPersistenceError(
+            "storage_failure",
+            "SQLite did not return a valid schema version",
+          );
+        }
+        if (version.user_version > MATCH_SQL_SCHEMA_VERSION) {
+          throw new MatchPersistenceError(
+            "unsupported_schema",
+            "The local match database uses a newer schema version",
+          );
+        }
+        if (version.user_version === MATCH_SQL_SCHEMA_VERSION) return;
+
+        let began = false;
+        try {
+          await database.execAsync("BEGIN IMMEDIATE");
+          began = true;
+          for (const migration of MATCH_SQL_MIGRATIONS) {
+            await database.execAsync(migration);
+          }
+          await database.execAsync(`PRAGMA user_version = ${MATCH_SQL_SCHEMA_VERSION}`);
+          await database.execAsync("COMMIT");
+        } catch (error) {
+          if (began) {
+            try {
+              await database.execAsync("ROLLBACK");
+            } catch (rollbackError) {
+              poisonAfterRollbackFailure(rollbackError);
+            }
+          }
+          throw error;
+        }
+      });
+    },
+    async transaction<T>(work: (transaction: MatchPersistenceTransaction) => Promise<T>) {
+      return runAtomic("BEGIN IMMEDIATE", work);
+    },
+    async readMatch(matchId) {
+      return runAtomic("BEGIN", async (reader) => {
+        const [match, events] = await Promise.all([
+          reader.getMatch(matchId),
+          reader.getEvents(matchId),
+        ]);
+        return { match, events };
+      });
+    },
+    async getActiveMatchId() {
+      return runSerialized(async () => {
+        const row = await database.getFirstAsync<{ match_id: string }>(
+          "SELECT match_id FROM match_active_pointer WHERE slot = 1",
+        );
+        return row?.match_id ?? null;
+      });
+    },
+    async readActiveMatch() {
+      return runAtomic("BEGIN", async (reader) => {
+        const active = await database.getFirstAsync<{ match_id: string }>(
+          "SELECT match_id FROM match_active_pointer WHERE slot = 1",
+        );
+        if (!active) {
+          return { activeMatchId: null, match: null, events: [] };
+        }
+        const [match, events] = await Promise.all([
+          reader.getMatch(active.match_id),
+          reader.getEvents(active.match_id),
+        ]);
+        return { activeMatchId: active.match_id, match, events };
+      });
+    },
+    async readMatchList() {
+      return runAtomic("BEGIN", async () => {
+        const [matches, activeMatch] = await Promise.all([
+          database.getAllAsync<SqlMatchRow>(
+            "SELECT * FROM match_aggregates ORDER BY updated_at DESC, rowid DESC",
+          ),
+          database.getFirstAsync<{ match_id: string }>(
+            "SELECT match_id FROM match_active_pointer WHERE slot = 1",
+          ),
+        ]);
+        return {
+          matches: matches.map(mapMatchRow),
+          activeMatchId: activeMatch?.match_id ?? null,
+        };
+      });
+    },
+    async getRemoteBinding() {
+      return runSerialized(async () => {
+        const row = await database.getFirstAsync<{ device_id: string; label: string | null }>(
+          "SELECT device_id, label FROM remote_binding WHERE slot = 1",
+        );
+        return row
+          ? { deviceId: row.device_id, ...(row.label === null ? {} : { label: row.label }) }
+          : null;
+      });
+    },
+    async setRemoteBinding(binding: RemoteBinding | null) {
+      return runSerialized(async () => {
+        if (!binding) {
+          await database.runAsync("DELETE FROM remote_binding WHERE slot = 1");
+          return;
+        }
+        await database.runAsync(
+          `INSERT INTO remote_binding (slot, device_id, label) VALUES (1, ?, ?)
+            ON CONFLICT(slot) DO UPDATE SET device_id = excluded.device_id, label = excluded.label`,
+          binding.deviceId,
+          binding.label ?? null,
+        );
+      });
+    },
+  };
+}