@pathmx/core 0.5.0

package/database.ts

@@ -0,0 +1,189 @@
+import type { PathMXDatabaseEnvironment } from "./environment.ts"
+
+export type SqlValue = string | number | bigint | Uint8Array | null
+export type SqlParams = readonly SqlValue[] | Readonly<Record<string, SqlValue>>
+
+export type SqlResult = Readonly<{
+  changes: number
+  lastInsertRowId?: number | bigint
+}>
+
+export type SqlDatabase = Readonly<{
+  all<Row>(sql: string, params?: SqlParams): Promise<readonly Row[]>
+  get<Row>(sql: string, params?: SqlParams): Promise<Row | undefined>
+  run(sql: string, params?: SqlParams): Promise<SqlResult>
+  exec(sql: string): Promise<void>
+  transaction<T>(run: (database: SqlDatabase) => Promise<T>): Promise<T>
+}>
+
+export type SqlConnection = SqlDatabase & Readonly<{ close(): Promise<void> }>
+
+export type DatabaseMigration = Readonly<{
+  id: string
+  sql: string
+}>
+
+export type PluginDatabase = Readonly<{
+  migrations?: readonly DatabaseMigration[]
+}>
+
+const MIGRATION_ID = /^[a-z0-9]+(?:[-_.][a-z0-9]+)*$/
+const MIGRATIONS_TABLE = "_pathmx_migrations"
+
+async function checksum(text: string) {
+  const bytes = new TextEncoder().encode(text)
+  const digest = await crypto.subtle.digest("SHA-256", bytes)
+  return [...new Uint8Array(digest)]
+    .map((value) => value.toString(16).padStart(2, "0"))
+    .join("")
+}
+
+function validateMigrations(migrations: readonly DatabaseMigration[]) {
+  const ids = new Set<string>()
+  for (const migration of migrations) {
+    if (!MIGRATION_ID.test(migration.id)) {
+      throw new Error(`Invalid database migration id: ${migration.id}`)
+    }
+    if (ids.has(migration.id)) {
+      throw new Error(`Duplicate database migration id: ${migration.id}`)
+    }
+    if (!migration.sql.trim()) {
+      throw new Error(`Database migration ${migration.id} is empty.`)
+    }
+    ids.add(migration.id)
+  }
+}
+
+async function migrate(
+  plugin: string,
+  database: SqlConnection,
+  migrations: readonly DatabaseMigration[],
+) {
+  validateMigrations(migrations)
+  await database.transaction(async (transaction) => {
+    await transaction.exec(`
+      CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+        id TEXT PRIMARY KEY,
+        checksum TEXT NOT NULL,
+        applied_at TEXT NOT NULL
+      )
+    `)
+    const applied = await transaction.all<{ id: string; checksum: string }>(
+      `SELECT id, checksum FROM ${MIGRATIONS_TABLE} ORDER BY rowid`,
+    )
+    for (const [index, current] of applied.entries()) {
+      const migration = migrations[index]
+      if (!migration || migration.id !== current.id) {
+        throw new Error(`Database migration history changed: ${plugin}`)
+      }
+      const expected = await checksum(migration.sql)
+      if (current.checksum !== expected) {
+        throw new Error(
+          `Applied database migration changed: ${plugin}/${migration.id}`,
+        )
+      }
+    }
+    for (const migration of migrations.slice(applied.length)) {
+      const expected = await checksum(migration.sql)
+      await transaction.exec(migration.sql)
+      await transaction.run(
+        `INSERT INTO ${MIGRATIONS_TABLE} (id, checksum, applied_at) VALUES (?, ?, ?)`,
+        [migration.id, expected, new Date().toISOString()],
+      )
+    }
+  })
+}
+
+function lazyDatabase(open: () => Promise<SqlConnection>): SqlDatabase {
+  return Object.freeze({
+    all: <Row>(sql: string, params?: SqlParams) =>
+      open().then((database) => database.all<Row>(sql, params)),
+    get: <Row>(sql: string, params?: SqlParams) =>
+      open().then((database) => database.get<Row>(sql, params)),
+    run: (sql: string, params?: SqlParams) =>
+      open().then((database) => database.run(sql, params)),
+    exec: (sql: string) => open().then((database) => database.exec(sql)),
+    transaction: <T>(run: (database: SqlDatabase) => Promise<T>) =>
+      open().then((database) => database.transaction(run)),
+  })
+}
+
+type RegisteredDatabase = {
+  handle: SqlDatabase
+  connection(): Promise<SqlConnection> | undefined
+}
+
+/** Own lazy, isolated plugin databases and their migration lifecycle. */
+export class PluginDatabases {
+  private registered = new Map<string, RegisteredDatabase>()
+  private closing?: Promise<void>
+
+  constructor(
+    private environment: PathMXDatabaseEnvironment | undefined,
+    private stateRoot: string,
+  ) {}
+
+  prepare(definition: PluginDatabase) {
+    const migrations = (definition.migrations ?? []).map((migration) =>
+      Object.freeze({ ...migration }),
+    )
+    validateMigrations(migrations)
+    return Object.freeze({ migrations: Object.freeze(migrations) })
+  }
+
+  register(plugin: string, definition: PluginDatabase) {
+    const prepared = this.prepare(definition)
+    if (this.registered.has(plugin)) {
+      throw new Error(`Duplicate plugin database: ${plugin}`)
+    }
+    let connection: Promise<SqlConnection> | undefined
+    const registered: RegisteredDatabase = {
+      handle: lazyDatabase(
+        () => (connection ??= this.create(plugin, prepared)),
+      ),
+      connection: () => connection,
+    }
+    this.registered.set(plugin, registered)
+  }
+
+  get(plugin: string) {
+    return this.registered.get(plugin)?.handle
+  }
+
+  private async create(plugin: string, definition: PluginDatabase) {
+    if (!this.environment) {
+      throw new Error(
+        `Plugin ${plugin} requires SQL database support in this environment.`,
+      )
+    }
+    const connection = await this.environment.open(
+      this.environment.path(this.stateRoot, `${plugin}.sqlite`),
+    )
+    try {
+      await migrate(plugin, connection, definition.migrations ?? [])
+      return connection
+    } catch (error) {
+      await connection.close().catch(() => undefined)
+      throw error
+    }
+  }
+
+  private async closeAll() {
+    const connections = [...this.registered.values()]
+      .map((registered) => registered.connection())
+      .filter(
+        (connection): connection is Promise<SqlConnection> => !!connection,
+      )
+    const settled = await Promise.allSettled(
+      connections.map(async (connection) => (await connection).close()),
+    )
+    const rejected = settled.find(
+      (result): result is PromiseRejectedResult => result.status === "rejected",
+    )
+    if (rejected) throw rejected.reason
+  }
+
+  close() {
+    return (this.closing ??= this.closeAll())
+  }
+}

package/dependencies.ts

@@ -0,0 +1,60 @@
+export type Dependency =
+  | Readonly<{ type: "source"; path: string }>
+  | Readonly<{ type: "plugin"; plugin: string; key: string }>
+
+export type DependencyContext = {
+  depend(dependency: Dependency): void
+}
+
+export function dependencyKey(dependency: Dependency) {
+  if (dependency.type === "source") return dependency.path
+  return `plugin:${dependency.plugin}:${dependency.key}`
+}
+
+export class PageDependencies implements DependencyContext {
+  readonly keys = new Set<string>()
+
+  depend = (dependency: Dependency) => {
+    this.keys.add(dependencyKey(dependency))
+  }
+}
+
+/** Bidirectional compile-time dependency index. Replacement is authoritative. */
+export class DependencyIndex {
+  private outgoing = new Map<string, Set<string>>()
+  private incoming = new Map<string, Set<string>>()
+
+  replaceDependent(dependent: string, dependencies: Iterable<string>) {
+    this.deleteDependent(dependent)
+    const deps = new Set(dependencies)
+    if (!deps.size) return
+    this.outgoing.set(dependent, deps)
+    for (const dependency of deps) {
+      let dependents = this.incoming.get(dependency)
+      if (!dependents) {
+        dependents = new Set()
+        this.incoming.set(dependency, dependents)
+      }
+      dependents.add(dependent)
+    }
+  }
+
+  deleteDependent(dependent: string) {
+    const deps = this.outgoing.get(dependent)
+    if (!deps) return
+    for (const dependency of deps) {
+      const dependents = this.incoming.get(dependency)
+      dependents?.delete(dependent)
+      if (dependents && dependents.size === 0) this.incoming.delete(dependency)
+    }
+    this.outgoing.delete(dependent)
+  }
+
+  dependentsOf(dependency: string) {
+    return this.incoming.get(dependency) ?? new Set<string>()
+  }
+
+  dependenciesOf(dependent: string) {
+    return this.outgoing.get(dependent) ?? new Set<string>()
+  }
+}