solid-objects 0.17.5 → 0.17.6

package/examples/guides/persistent-rooms/sql-room.ts

@@ -0,0 +1,80 @@
+import { DatabaseSync } from "node:sqlite"
+
+export type RoomState = { players: string[]; turnNumber: number }
+
+export function openRoomStore({ path }: { path: string }): DatabaseSync {
+  const database = new DatabaseSync(path)
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS rooms (
+      room_id TEXT PRIMARY KEY,
+      state TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      turn_deadline INTEGER
+    )
+  `)
+  return database
+}
+
+export function saveRoom({
+  database,
+  roomId,
+  state,
+  expectedVersion,
+  turnDeadline,
+}: {
+  database: DatabaseSync
+  roomId: string
+  state: RoomState
+  expectedVersion: number
+  turnDeadline: number | null
+}): { saved: boolean } {
+  if (expectedVersion === 0) {
+    const inserted = database
+      .prepare(
+        "INSERT OR IGNORE INTO rooms (room_id, state, version, turn_deadline) VALUES (?, ?, 1, ?)",
+      )
+      .run(roomId, JSON.stringify(state), turnDeadline)
+    return { saved: inserted.changes === 1 }
+  }
+  const updated = database
+    .prepare(
+      "UPDATE rooms SET state = ?, version = version + 1, turn_deadline = ? WHERE room_id = ? AND version = ?",
+    )
+    .run(JSON.stringify(state), turnDeadline, roomId, expectedVersion)
+  return { saved: updated.changes === 1 }
+}
+
+export function loadRoom({
+  database,
+  roomId,
+}: {
+  database: DatabaseSync
+  roomId: string
+}): { state: RoomState; version: number } | undefined {
+  const row = database.prepare("SELECT state, version FROM rooms WHERE room_id = ?").get(roomId) as
+    { state: string; version: number } | undefined
+  if (!row) return undefined
+  const state: unknown = JSON.parse(row.state)
+  if (!isRoomState(state)) throw new Error(`stored room ${roomId} has an unexpected shape`)
+  return { state, version: row.version }
+}
+
+export function dueTurnDeadlines({
+  database,
+  now,
+}: {
+  database: DatabaseSync
+  now: number
+}): string[] {
+  const rows = database
+    .prepare("SELECT room_id FROM rooms WHERE turn_deadline <= ? ORDER BY turn_deadline")
+    .all(now) as { room_id: string }[]
+  return rows.map((row) => row.room_id)
+}
+
+function isRoomState(value: unknown): value is RoomState {
+  if (typeof value !== "object" || value === null) return false
+  if (!("players" in value) || !Array.isArray(value.players)) return false
+  if (!value.players.every((player) => typeof player === "string")) return false
+  return "turnNumber" in value && Number.isSafeInteger(value.turnNumber)
+}

package/examples/guides/persistent-rooms/turn-room.ts

@@ -0,0 +1,85 @@
+import { Actor } from "solid-objects"
+
+export const TURN_MILLISECONDS = 60_000
+
+const MAXIMUM_PLAYERS = 4
+
+type Move = { playerId: string; move: string; turnNumber: number }
+
+export class TurnRoom extends Actor {
+  static override readonly actorType = "TurnRoom"
+
+  players: string[] = []
+  started = false
+  turnNumber = 0
+  moves: Move[] = []
+  skippedTurns: number[] = []
+  revision = 0
+
+  get currentPlayer(): string | null {
+    if (!this.started) return null
+    return this.players[this.turnNumber % this.players.length] ?? null
+  }
+
+  join({ playerId }: { playerId: string }): { players: string[] } {
+    if (this.players.includes(playerId)) return { players: this.players }
+    if (this.started) this.reject("game_started", { message: "The game already started" })
+    if (this.players.length === MAXIMUM_PLAYERS) {
+      this.reject("room_full", { message: "The room is full" })
+    }
+    this.players = [...this.players, playerId]
+    this.revision += 1
+    return { players: this.players }
+  }
+
+  start({ playerId }: { playerId: string }): { turnNumber: number } {
+    if (this.started) return { turnNumber: this.turnNumber }
+    if (!this.players.includes(playerId)) {
+      this.reject("not_in_room", { message: "Only a player in the room can start the game" })
+    }
+    if (this.players.length < 2) {
+      this.reject("not_enough_players", { message: "The game needs two players" })
+    }
+    this.started = true
+    this.revision += 1
+    this.#armTurnTimer()
+    return { turnNumber: this.turnNumber }
+  }
+
+  play({ playerId, move, turnNumber }: { playerId: string; move: string; turnNumber: number }): {
+    turnNumber: number
+  } {
+    if (!this.started) this.reject("game_not_started", { message: "The game has not started" })
+    if (turnNumber !== this.turnNumber) {
+      this.reject("stale_turn", {
+        message: "That turn already ended",
+        details: { turnNumber: this.turnNumber },
+      })
+    }
+    if (playerId !== this.currentPlayer) {
+      this.reject("not_your_turn", { message: "It is not your turn" })
+    }
+    this.moves = [...this.moves, { playerId, move, turnNumber }]
+    this.#advanceTurn()
+    return { turnNumber: this.turnNumber }
+  }
+
+  turnTimeout({ turnNumber }: { turnNumber: number }): { skipped: boolean } {
+    if (turnNumber !== this.turnNumber) return { skipped: false }
+    this.skippedTurns = [...this.skippedTurns, turnNumber]
+    this.#advanceTurn()
+    return { skipped: true }
+  }
+
+  #advanceTurn(): void {
+    this.turnNumber += 1
+    this.revision += 1
+    this.#armTurnTimer()
+  }
+
+  #armTurnTimer(): void {
+    this.schedule({ at: new Date(Date.now() + TURN_MILLISECONDS) }).turnTimeout({
+      turnNumber: this.turnNumber,
+    })
+  }
+}

package/examples/guides/race-conditions/atomic-hold.ts

@@ -0,0 +1,28 @@
+import type { DatabaseSync } from "node:sqlite"
+
+export function holdSeatAtomically({
+  database,
+  eventId,
+  buyer,
+}: {
+  database: DatabaseSync
+  eventId: string
+  buyer: string
+}): { held: boolean } {
+  database.exec("BEGIN IMMEDIATE")
+  try {
+    const result = database
+      .prepare("UPDATE seats SET available = available - 1 WHERE event_id = ? AND available > 0")
+      .run(eventId)
+    if (result.changes === 0) {
+      database.exec("ROLLBACK")
+      return { held: false }
+    }
+    database.prepare("INSERT INTO holds (event_id, buyer) VALUES (?, ?)").run(eventId, buyer)
+    database.exec("COMMIT")
+    return { held: true }
+  } catch (error) {
+    database.exec("ROLLBACK")
+    throw error
+  }
+}

package/examples/guides/race-conditions/event-runtime.ts

@@ -0,0 +1,48 @@
+import { createRuntime, type SolidObjectsRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { EventSeats, type EventCaller } from "./event-seats.js"
+
+const SYSTEM_OPERATIONS = new Set(["confirm", "expire"])
+
+export function authorizeEventMessage({
+  actorType,
+  operation,
+  authorizationContext,
+}: {
+  actorType: string
+  operation: string
+  authorizationContext: unknown
+}): boolean {
+  if (actorType !== EventSeats.actorType) return false
+  if (!isEventCaller(authorizationContext)) return false
+  if (operation === "setCapacity") return authorizationContext.role === "organizer"
+  if (SYSTEM_OPERATIONS.has(operation)) return authorizationContext.role === "system"
+  return true
+}
+
+export function authorizeEventQuery({
+  actorType,
+  authorizationContext,
+}: {
+  actorType: string
+  authorizationContext: unknown
+}): boolean {
+  return actorType === EventSeats.actorType && isEventCaller(authorizationContext)
+}
+
+export function eventRuntime({ path }: { path: string }): SolidObjectsRuntime {
+  const runtime = createRuntime({
+    database: sqlite({ path }),
+    authorizeMessage: authorizeEventMessage,
+    authorizeQuery: authorizeEventQuery,
+  })
+  runtime.register(EventSeats)
+  return runtime
+}
+
+function isEventCaller(value: unknown): value is EventCaller {
+  if (typeof value !== "object" || value === null) return false
+  if (!("userId" in value) || typeof value.userId !== "string") return false
+  if (!("role" in value)) return false
+  return value.role === "buyer" || value.role === "organizer" || value.role === "system"
+}

package/examples/guides/race-conditions/event-seats.ts

@@ -0,0 +1,76 @@
+import { Actor } from "solid-objects"
+
+export const HOLD_MILLISECONDS = 10 * 60 * 1000
+
+export type EventCaller = { userId: string; role: "buyer" | "organizer" | "system" }
+
+type Hold = { buyer: string; expiresAt: number }
+
+export class EventSeats extends Actor {
+  static override readonly actorType = "EventSeats"
+
+  capacity = 0
+  revision = 0
+  holds: Record<string, Hold> = {}
+  sold: Record<string, string> = {}
+
+  get available(): number {
+    return this.capacity - Object.keys(this.holds).length - Object.keys(this.sold).length
+  }
+
+  setCapacity({ capacity, expectedRevision }: { capacity: number; expectedRevision: number }): {
+    revision: number
+  } {
+    if (!Number.isSafeInteger(capacity) || capacity < 0) {
+      this.reject("invalid_capacity", { message: "Capacity must be a whole number of seats" })
+    }
+    if (expectedRevision !== this.revision) {
+      this.reject("stale_revision", {
+        message: "The event changed after you loaded it",
+        details: { revision: this.revision },
+      })
+    }
+    if (capacity < this.capacity - this.available) {
+      this.reject("capacity_below_sold", { message: "Holds and sales already use more seats" })
+    }
+    this.capacity = capacity
+    this.revision += 1
+    return { revision: this.revision }
+  }
+
+  hold({ holdId, buyer }: { holdId: string; buyer: string }): { held: boolean; available: number } {
+    if (Object.hasOwn(this.holds, holdId) || Object.hasOwn(this.sold, holdId)) {
+      return { held: true, available: this.available }
+    }
+    if (this.available <= 0) return { held: false, available: 0 }
+
+    const expiresAt = Date.now() + HOLD_MILLISECONDS
+    this.holds = { ...this.holds, [holdId]: { buyer, expiresAt } }
+    this.schedule({ at: new Date(expiresAt), key: holdId }).expire({ holdId })
+    return { held: true, available: this.available }
+  }
+
+  confirm({ holdId }: { holdId: string }): { confirmed: boolean } {
+    if (Object.hasOwn(this.sold, holdId)) return { confirmed: true }
+    const hold = this.holds[holdId]
+    if (!hold) {
+      this.reject("hold_expired", { message: "The hold expired before the payment arrived" })
+    }
+
+    this.holds = withoutKey(this.holds, holdId)
+    this.sold = { ...this.sold, [holdId]: hold.buyer }
+    this.unschedule("expire", { key: holdId })
+    return { confirmed: true }
+  }
+
+  expire({ holdId }: { holdId: string }): { expired: boolean } {
+    if (!Object.hasOwn(this.holds, holdId)) return { expired: false }
+
+    this.holds = withoutKey(this.holds, holdId)
+    return { expired: true }
+  }
+}
+
+function withoutKey<Value>(record: Record<string, Value>, key: string): Record<string, Value> {
+  return Object.fromEntries(Object.entries(record).filter(([entryKey]) => entryKey !== key))
+}

package/examples/guides/race-conditions/lost-update.ts

@@ -0,0 +1,37 @@
+import type { DatabaseSync } from "node:sqlite"
+
+export async function holdSeatWithRace({
+  database,
+  eventId,
+  buyer,
+  checkBuyer,
+}: {
+  database: DatabaseSync
+  eventId: string
+  buyer: string
+  checkBuyer: () => Promise<void>
+}): Promise<{ held: boolean }> {
+  const row = database.prepare("SELECT available FROM seats WHERE event_id = ?").get(eventId) as {
+    available: number
+  }
+  if (row.available === 0) return { held: false }
+
+  await checkBuyer()
+
+  database
+    .prepare("UPDATE seats SET available = ? WHERE event_id = ?")
+    .run(row.available - 1, eventId)
+  database.prepare("INSERT INTO holds (event_id, buyer) VALUES (?, ?)").run(eventId, buyer)
+  return { held: true }
+}
+
+export function createLocalMutex(): { run<Result>(task: () => Promise<Result>): Promise<Result> } {
+  let tail: Promise<unknown> = Promise.resolve()
+  return {
+    run<Result>(task: () => Promise<Result>): Promise<Result> {
+      const result = tail.then(task)
+      tail = result.catch(() => undefined)
+      return result
+    },
+  }
+}

package/examples/guides/race-conditions/seat-inventory.ts

@@ -0,0 +1,36 @@
+import { DatabaseSync } from "node:sqlite"
+
+export function openSeatInventory({
+  path,
+  eventId,
+  available,
+}: {
+  path: string
+  eventId: string
+  available: number
+}): DatabaseSync {
+  const database = new DatabaseSync(path)
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS seats (event_id TEXT PRIMARY KEY, available INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS holds (event_id TEXT NOT NULL, buyer TEXT NOT NULL);
+  `)
+  database
+    .prepare("INSERT OR IGNORE INTO seats (event_id, available) VALUES (?, ?)")
+    .run(eventId, available)
+  return database
+}
+
+export function seatCounts({ database, eventId }: { database: DatabaseSync; eventId: string }): {
+  available: number
+  holds: number
+} {
+  const seats = database.prepare("SELECT available FROM seats WHERE event_id = ?").get(eventId) as {
+    available: number
+  }
+  const holds = database
+    .prepare("SELECT COUNT(*) AS count FROM holds WHERE event_id = ?")
+    .get(eventId) as {
+    count: number
+  }
+  return { available: seats.available, holds: holds.count }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.17.5",
+  "version": "0.17.6",
   "description": "SQL-backed virtual actor library for TypeScript and Node.js, with durable state, ordered operations, and automatic activation on SQLite, PostgreSQL, or MySQL",
   "type": "module",
   "license": "MIT",