solid-objects 0.13.2 → 0.14.0

package/examples/failure-recovery/serialization.ts

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict"
+
+export interface SerializationEvent {
+  event: "start" | "finish"
+  messageId: string
+  attempt: number
+  processId: number
+  at: number
+}
+
+export interface SerializationProof {
+  executions: number
+  retried: boolean
+  supersededOverlap: boolean
+}
+
+interface Execution {
+  messageId: string
+  attempt: number
+  processId: number
+  startedAt: number
+  finishedAt: number
+}
+
+export function parseSerializationEvent(line: string): SerializationEvent {
+  const event = JSON.parse(line) as Partial<SerializationEvent>
+  if (
+    (event.event !== "start" && event.event !== "finish") ||
+    typeof event.messageId !== "string" ||
+    typeof event.attempt !== "number" ||
+    typeof event.processId !== "number" ||
+    typeof event.at !== "number"
+  ) {
+    throw new TypeError("invalid serialization event")
+  }
+  return {
+    event: event.event,
+    messageId: event.messageId,
+    attempt: event.attempt,
+    processId: event.processId,
+    at: event.at,
+  }
+}
+
+// One identity commits one state transition at a time. The control file is
+// written outside the transaction, so it records execution attempts rather than
+// commits: a worker that loses its lease keeps running until it notices, and its
+// replacement executes the same message under a higher attempt. The superseded
+// attempt may therefore overlap anything, because its write is fenced out and
+// the committed state is what proves it.
+//
+// Each event carries its attempt and process, so a start pairs with its own
+// finish rather than with whichever finish arrived next. Without that, a
+// superseded attempt finishing late reads as its replacement finishing, and a
+// second message could then overlap a replacement that is still running.
+export function assertSerializedExecution(
+  events: readonly SerializationEvent[],
+  options: { messageCount: number },
+): SerializationProof {
+  const executions = pairExecutions(events)
+
+  const messageIds = new Set(executions.map((execution) => execution.messageId))
+  assert.equal(
+    messageIds.size,
+    options.messageCount,
+    `expected ${options.messageCount} messages to run, saw ${messageIds.size}`,
+  )
+
+  const survivingAttempt = new Map<string, number>()
+  for (const execution of executions) {
+    const highest = survivingAttempt.get(execution.messageId) ?? 0
+    if (execution.attempt > highest) survivingAttempt.set(execution.messageId, execution.attempt)
+  }
+  const surviving = executions.filter(
+    (execution) => survivingAttempt.get(execution.messageId) === execution.attempt,
+  )
+
+  for (const [index, execution] of surviving.entries()) {
+    for (const other of surviving.slice(index + 1)) {
+      assert(
+        !overlaps(execution, other),
+        `${describe(execution)} and ${describe(other)} overlap, and neither was superseded`,
+      )
+    }
+  }
+
+  const supersededOverlap = executions.some((execution) =>
+    executions.some((other) => other !== execution && overlaps(execution, other)),
+  )
+
+  return {
+    executions: executions.length,
+    retried: executions.length > options.messageCount,
+    supersededOverlap,
+  }
+}
+
+function pairExecutions(events: readonly SerializationEvent[]): Execution[] {
+  const started = new Map<string, SerializationEvent>()
+  const executions: Execution[] = []
+
+  for (const event of [...events].sort((left, right) => left.at - right.at)) {
+    const key = `${event.messageId}#${event.attempt}#${event.processId}`
+    if (event.event === "start") {
+      assert(!started.has(key), `${describe(event)} started twice`)
+      started.set(key, event)
+      continue
+    }
+    const start = started.get(key)
+    assert(start !== undefined, `${describe(event)} finished with no matching start`)
+    started.delete(key)
+    executions.push({
+      messageId: event.messageId,
+      attempt: event.attempt,
+      processId: event.processId,
+      startedAt: start.at,
+      finishedAt: event.at,
+    })
+  }
+
+  const unfinished = [...started.values()].map(describe)
+  assert.equal(unfinished.length, 0, `${unfinished.join(", ")} never wrote a finish`)
+
+  return executions
+}
+
+function overlaps(left: Execution, right: Execution): boolean {
+  return left.startedAt < right.finishedAt && right.startedAt < left.finishedAt
+}
+
+function describe(execution: { messageId: string; attempt: number }): string {
+  return `${execution.messageId} attempt ${execution.attempt}`
+}

package/examples/quickstart-report.ts

@@ -0,0 +1,151 @@
+export interface QuickstartSummary {
+  sameIdentityCalls: number
+  sameIdentityFinalState: number
+  independentIdentitiesOverlapped: boolean
+  temporaryStateRemoved: boolean
+}
+
+interface QuickstartCheck {
+  passed: boolean
+  title: string
+  detail: readonly string[]
+}
+
+const INSTALL_COMMAND = "npm install solid-objects"
+const AGENT_PROMPT = "where would the solid-objects library be best used in this app?"
+const DOCUMENTATION_URL = "https://solidobjects.dev/node"
+
+export function formatQuickstartPlan(plan: {
+  sameIdentityCalls: number
+  actorSource: string
+}): string {
+  return [
+    "Solid Objects quickstart",
+    "",
+    "This command will:",
+    "",
+    "  1. create a temporary SQLite database;",
+    `  2. send ${plan.sameIdentityCalls} concurrent calls to one identity;`,
+    "  3. run two other identities at the same time;",
+    "  4. close the runtime and delete the temporary database.",
+    "",
+    "No server, container, or configuration is needed.",
+    "",
+    "The actor it runs:",
+    "",
+    ...plan.actorSource.split("\n").map((line) => `  ${line}`.trimEnd()),
+    "",
+    "",
+  ].join("\n")
+}
+
+export function formatQuickstartPrompt(): string {
+  return "Run it now? [Y/n] "
+}
+
+export function answerAllowsRun(answer: string): boolean {
+  const value = answer.trim().toLowerCase()
+  if (value === "") return true
+  return value === "y" || value === "yes"
+}
+
+export function formatQuickstartStop(): string {
+  return ["", "Nothing ran. No database and no files were created.", ""].join("\n")
+}
+
+export function formatQuickstartReport(summary: QuickstartSummary): string {
+  const results = checks(summary)
+  return [
+    "Results",
+    "",
+    ...results.flatMap(checkLines),
+    "",
+    "Each line above is an assertion, not a print. The command exits with a",
+    "non-zero code when one of them fails.",
+    "",
+    ...meaning(results),
+    "Add it to your app",
+    "",
+    `  ${INSTALL_COMMAND}`,
+    "",
+    "Or tell your agent",
+    "",
+    `  ${AGENT_PROMPT}`,
+    "",
+    `Docs: ${DOCUMENTATION_URL}`,
+    "",
+  ].join("\n")
+}
+
+function meaning(results: readonly QuickstartCheck[]): string[] {
+  if (results.some((check) => !check.passed)) return []
+  return [
+    "What each PASS means",
+    "",
+    "  Two requests on the same cart cannot overwrite each other.",
+    "  That identity has one durable mailbox, so its calls commit one at a",
+    "  time and no update is lost.",
+    "",
+    "  Unrelated identities do not wait for that mailbox.",
+    "  The order is per identity, not global.",
+    "",
+    "  The state lives in an ordinary SQL database, so it survives a restart.",
+    "",
+  ]
+}
+
+function checkLines(check: QuickstartCheck): string[] {
+  const result = check.passed ? "PASS" : "FAIL"
+  return [`${result}  ${check.title}`, ...check.detail.map((line) => `      ${line}`)]
+}
+
+function checks(summary: QuickstartSummary): QuickstartCheck[] {
+  return [
+    {
+      passed: summary.sameIdentityFinalState === summary.sameIdentityCalls,
+      title: `${summary.sameIdentityCalls} concurrent calls to one identity`,
+      detail: sameIdentityDetail(summary),
+    },
+    {
+      passed: summary.independentIdentitiesOverlapped,
+      title: "Two different identities ran at the same time",
+      detail: overlapDetail(summary),
+    },
+    {
+      passed: summary.temporaryStateRemoved,
+      title: "Temporary state removed",
+      detail: cleanupDetail(summary),
+    },
+  ]
+}
+
+function sameIdentityDetail(summary: QuickstartSummary): string[] {
+  if (summary.sameIdentityFinalState !== summary.sameIdentityCalls) {
+    return [
+      `The committed state is ${summary.sameIdentityFinalState} after ${summary.sameIdentityCalls} calls.`,
+      "The runtime lost an update.",
+    ]
+  }
+  return [
+    "They ran in order on one mailbox.",
+    `The committed state is ${summary.sameIdentityFinalState}.`,
+    `The return values were the complete sequence 1 through ${summary.sameIdentityCalls}.`,
+  ]
+}
+
+function overlapDetail(summary: QuickstartSummary): string[] {
+  if (!summary.independentIdentitiesOverlapped) {
+    return ["Their execution windows did not overlap."]
+  }
+  return [
+    "Their execution windows overlapped, so an unrelated identity",
+    "never waits behind this one.",
+  ]
+}
+
+function cleanupDetail(summary: QuickstartSummary): string[] {
+  if (!summary.temporaryStateRemoved) {
+    return ["The temporary SQLite database is still on disk."]
+  }
+  return ["The scoped temporary SQLite database was deleted at exit."]
+}

package/examples/sqlite-quickstart.ts

@@ -6,6 +6,17 @@ import { join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { Actor, createRuntime } from "solid-objects"
 import { sqlite } from "solid-objects/database/sqlite"
+import { createInterface } from "node:readline/promises"
+import {
+  answerAllowsRun,
+  formatQuickstartPlan,
+  formatQuickstartPrompt,
+  formatQuickstartReport,
+  formatQuickstartStop,
+  type QuickstartSummary,
+} from "./quickstart-report.js"
+
+const SAME_IDENTITY_CALLS = 25
 
 class Counter extends Actor {
   static override readonly actorType = "QuickstartCounter"
@@ -27,12 +38,61 @@ class Counter extends Actor {
   }
 }
 
+const COUNTER_SOURCE = `class Counter extends Actor {
+  static override readonly actorType = "QuickstartCounter"
+
+  count = 0
+
+  increment(): number {
+    this.count += 1
+    return this.count
+  }
+
+  async pause({ milliseconds }: { milliseconds: number }) {
+    const startedAt = performance.now()
+    await new Promise((done) => setTimeout(done, milliseconds))
+    return { startedAt, finishedAt: performance.now() }
+  }
+}`
+
+async function confirmRun(options: {
+  format?: "report" | "json"
+  confirm?: () => boolean | Promise<boolean>
+}): Promise<boolean> {
+  if (options.format === "json") return true
+  if (options.confirm) return options.confirm()
+  if (!process.stdin.isTTY) return true
+  const questions = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return answerAllowsRun(await questions.question(formatQuickstartPrompt()))
+  } catch {
+    return false
+  } finally {
+    questions.close()
+  }
+}
+
 export async function runQuickstart(
   options: {
     signal?: AbortSignal
     write?: (value: string) => void
+    format?: "report" | "json"
+    confirm?: () => boolean | Promise<boolean>
   } = {},
 ): Promise<void> {
+  const write = options.write ?? ((value: string) => process.stdout.write(value))
+  if (options.format !== "json") {
+    write(
+      formatQuickstartPlan({
+        sameIdentityCalls: SAME_IDENTITY_CALLS,
+        actorSource: COUNTER_SOURCE,
+      }),
+    )
+  }
+  if (!(await confirmRun(options))) {
+    write(formatQuickstartStop())
+    return
+  }
   const directory = await mkdtemp(join(tmpdir(), "solid-objects-quickstart-"))
   const databasePath = join(directory, "state.sqlite3")
   const runtime = createRuntime({
@@ -58,13 +118,15 @@ export async function runQuickstart(
     running = runtime.run(shutdown.signal)
 
     const counter = runtime.ref(Counter, "room-1")
-    const results = await Promise.all(Array.from({ length: 25 }, () => counter.increment()))
+    const results = await Promise.all(
+      Array.from({ length: SAME_IDENTITY_CALLS }, () => counter.increment()),
+    )
     assert.deepEqual(
       [...results].sort((left, right) => left - right),
-      Array.from({ length: 25 }, (_value, index) => index + 1),
+      Array.from({ length: SAME_IDENTITY_CALLS }, (_value, index) => index + 1),
     )
     sameIdentityFinalState = await counter.count
-    assert.equal(sameIdentityFinalState, 25)
+    assert.equal(sameIdentityFinalState, SAME_IDENTITY_CALLS)
 
     const pauses = await Promise.all([
       runtime.ref(Counter, "room-2").send.pause({ milliseconds: 100 }),
@@ -89,19 +151,17 @@ export async function runQuickstart(
   }
 
   assert.equal(existsSync(directory), false)
-  const write = options.write ?? ((value: string) => process.stdout.write(value))
-  write(
-    `${JSON.stringify(
-      {
-        sameIdentityCalls: 25,
-        sameIdentityFinalState,
-        independentIdentitiesOverlapped,
-        temporaryStateRemoved: true,
-      },
-      null,
-      2,
-    )}\n`,
-  )
+  const summary: QuickstartSummary = {
+    sameIdentityCalls: SAME_IDENTITY_CALLS,
+    sameIdentityFinalState,
+    independentIdentitiesOverlapped,
+    temporaryStateRemoved: true,
+  }
+  if (options.format === "json") {
+    write(`${JSON.stringify(summary, null, 2)}\n`)
+    return
+  }
+  write(formatQuickstartReport(summary))
 }
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "url": "git+https://github.com/cardmagic/solid-objects-js.git"
   },
   "engines": {
-    "node": ">=24.15.0"
+    "node": ">=24.4.0"
   },
   "packageManager": "pnpm@11.11.0",
   "bin": {
@@ -46,6 +46,14 @@
       "types": "./dist/database/sqlite.d.ts",
       "import": "./dist/database/sqlite.js"
     },
+    "./database/sqlite-wasm": {
+      "types": "./dist/database/sqlite-wasm.d.ts",
+      "import": "./dist/database/sqlite-wasm.js"
+    },
+    "./database/shared-sqlite-wasm": {
+      "types": "./dist/database/shared-sqlite-wasm.d.ts",
+      "import": "./dist/database/shared-sqlite-wasm.js"
+    },
     "./database/postgresql": {
       "types": "./dist/database/postgresql.d.ts",
       "import": "./dist/database/postgresql.js"
@@ -62,6 +70,18 @@
       "types": "./dist/browser/index.d.ts",
       "import": "./dist/browser/index.js"
     },
+    "./browser/host": {
+      "types": "./dist/browser/host.d.ts",
+      "import": "./dist/browser/host.js"
+    },
+    "./browser/tab-host": {
+      "types": "./dist/browser/tab-host.d.ts",
+      "import": "./dist/browser/tab-host.js"
+    },
+    "./transmit": {
+      "types": "./dist/transmit.d.ts",
+      "import": "./dist/transmit.js"
+    },
     "./web": {
       "types": "./dist/web/index.d.ts",
       "import": "./dist/web/index.js"
@@ -69,7 +89,8 @@
   },
   "scripts": {
     "build": "pnpm run clean && tsc -p tsconfig.build.json && tsc -p tsconfig.quickstart-build.json && node scripts/prepare-executable.mjs",
-    "check": "pnpm run check:parameters && pnpm run check:documentation && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.examples.json --noEmit",
+    "check": "pnpm run check:parameters && pnpm run check:documentation && pnpm run check:browser-imports && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.examples.json --noEmit",
+    "check:browser-imports": "node scripts/check-browser-imports.mjs",
     "check:documentation": "node scripts/check-documentation.mjs",
     "check:parameters": "node scripts/check-parameter-style.mjs",
     "clean": "node scripts/clean.mjs",
@@ -91,6 +112,7 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.62.1",
+    "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.21.0",
     "@types/ws": "^8.18.1",
@@ -104,11 +126,15 @@
     "ws": "^8.21.3"
   },
   "peerDependencies": {
+    "@sqlite.org/sqlite-wasm": ">=3.50.0-build1",
     "mysql2": "^3.23.3",
     "pg": "^8.23.0",
     "redis": "^6.2.1"
   },
   "peerDependenciesMeta": {
+    "@sqlite.org/sqlite-wasm": {
+      "optional": true
+    },
     "mysql2": {
       "optional": true
     },