velocious 1.0.593 → 1.0.595

package/src/database/use-database.js

@@ -8,41 +8,94 @@ import Migrator from "./migrator.js"
 import restArgsError from "../utils/rest-args-error.js"
 
 /**
- * Runs load migrations.
- * @param {object} args - Options object.
- * @param {() => Promise<import("./migrator/types.js").RequireMigrationContextType>} args.migrationsRequireContextCallback - Migrations require context callback.
- * @returns {{loaded: boolean}} - Whether the database was loaded by this call.
+ * Initializes either the legacy ambient frontend database or one immutable
+ * tenant-bound physical database generation.
+ * @param {object} args - Initialization options.
+ * @param {import("../configuration.js").default} args.configuration - Current frontend configuration.
+ * @param {string} [args.databaseIdentifier] - Tenant-only logical database identifier.
+ * @param {() => Promise<import("./migrator/types.js").RequireMigrationContextType>} args.migrationsRequireContextCallback - Migrations loader.
+ * @param {string} [args.schemaGeneration] - Tenant schema generation.
+ * @param {import("../tenants/tenant-handle.js").default} [args.tenantHandle] - Immutable tenant handle.
+ * @returns {Promise<void>} - Resolves when the selected database is ready.
  */
-export default function loadMigrations({migrationsRequireContextCallback, ...restArgs}) {
-  const instance = React.useMemo(() => ({running: false}), [])
+export async function initializeFrontendDatabase({configuration, databaseIdentifier, migrationsRequireContextCallback, schemaGeneration, tenantHandle}) {
+  if (tenantHandle) {
+    tenantHandle.assertConfiguration(configuration)
+    if (!databaseIdentifier) throw new Error("Tenant frontend database initialization requires databaseIdentifier")
+    if (!schemaGeneration) throw new Error("Tenant frontend database initialization requires schemaGeneration")
+
+    await tenantHandle.initialize({
+      databaseIdentifier,
+      migrations: await migrationsRequireContextCallback(),
+      schemaGeneration
+    })
+    await configuration.initialize()
+    return
+  }
+  if (databaseIdentifier || schemaGeneration) {
+    throw new Error("Tenant frontend database initialization requires tenantHandle")
+  }
+
+  await configuration.ensureConnections({name: "React database migration loader"}, async () => {
+    const migrator = new Migrator({configuration})
+
+    await migrator.prepare()
+    await migrator.migrateFilesFromRequireContext(await migrationsRequireContextCallback())
+  })
+
+  await configuration.initialize()
+}
+
+/**
+ * React lifecycle hook for frontend database readiness. With `tenantHandle`,
+ * readiness follows that immutable physical tenant plus `schemaGeneration`;
+ * changing either cancels the stale render result without cancelling shared
+ * lifecycle work needed by another caller.
+ * @param {object} args - Hook options.
+ * @param {string} [args.databaseIdentifier] - Tenant-only logical database identifier.
+ * @param {() => Promise<import("./migrator/types.js").RequireMigrationContextType>} args.migrationsRequireContextCallback - Migrations loader.
+ * @param {string} [args.schemaGeneration] - Tenant schema generation.
+ * @param {import("../tenants/tenant-handle.js").default} [args.tenantHandle] - Immutable tenant handle.
+ * @returns {{error: Error | null, loaded: boolean}} - Selected database readiness.
+ */
+export default function useDatabase({databaseIdentifier, migrationsRequireContextCallback, schemaGeneration, tenantHandle, ...restArgs}) {
+  restArgsError(restArgs)
+
   const {isServer} = useEnvSense()
-  const [loaded, setLoaded] = React.useState(false)
+  const migrationsRequireContextCallbackRef = React.useRef(migrationsRequireContextCallback)
 
-  const loadDatabase = React.useCallback(async () => {
-    instance.running = true
+  migrationsRequireContextCallbackRef.current = migrationsRequireContextCallback
 
-    try {
-      await Configuration.current().ensureConnections({name: "React database migration loader"}, async () => {
-        const migrator = new Migrator({configuration: Configuration.current()})
+  const selection = React.useMemo(() => {
+    if (isServer) return undefined
 
-        await migrator.prepare()
-        await migrator.migrateFilesFromRequireContext(await migrationsRequireContextCallback())
-      })
+    return {configuration: Configuration.current(), databaseIdentifier, schemaGeneration, tenantHandle}
+  }, [isServer, databaseIdentifier, schemaGeneration, tenantHandle])
+  const [state, setState] = React.useState({error: /** @type {Error | null} */ (null), loaded: false, selection})
 
-      await Configuration.current().initialize()
-      setLoaded(true)
-    } finally {
-      instance.running = false
-    }
-  }, [])
+  React.useEffect(() => {
+    if (!selection) return undefined
 
-  React.useMemo(() => {
-    if (!loaded && !isServer && !instance.running) {
-      loadDatabase()
-    }
-  }, [loaded])
+    let current = true
+    const migrationsLoader = migrationsRequireContextCallbackRef.current
 
-  restArgsError(restArgs)
+    setState({error: null, loaded: false, selection})
+    void initializeFrontendDatabase({
+      configuration: selection.configuration,
+      databaseIdentifier: selection.databaseIdentifier,
+      migrationsRequireContextCallback: migrationsLoader,
+      schemaGeneration: selection.schemaGeneration,
+      tenantHandle: selection.tenantHandle
+    }).then(() => {
+      if (current) setState({error: null, loaded: true, selection})
+    }, (error) => {
+      if (current) setState({error: error instanceof Error ? error : new Error(String(error)), loaded: false, selection})
+    })
+
+    return () => { current = false }
+  }, [selection])
+
+  if (state.selection !== selection) return {error: null, loaded: false}
 
-  return {loaded}
+  return {error: state.error, loaded: state.loaded}
 }

package/src/sync/server-change-feed.js

@@ -76,7 +76,10 @@ export default class ServerChangeFeedStore {
     this._memoryChanges = []
     this._memorySequence = 0
     this._isReady = false
+    /** @type {Promise<void> | null} */
     this._readyPromise = null
+    /** @type {WeakMap<import("../database/drivers/base.js").default, {completion: Promise<void>, promise: Promise<void>}>} */
+    this._transactionReadyPromises = new WeakMap()
   }
 
   /**
@@ -90,15 +93,60 @@ export default class ServerChangeFeedStore {
     }
 
     if (await this._schemaReady()) return
-    if (this._readyPromise) return await this._readyPromise
 
-    this._readyPromise = (async () => {
-      this.configuration.setCurrent()
-      await this._withDb(async (db) => {
-        await this._ensureChangesTable(db)
+    this.configuration.setCurrent()
+    await this._withDb(async (db) => await this._ensureReadyWithDb(db))
+  }
+
+  /**
+   * Coordinates durable and transaction-local readiness on one connection.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} Resolves when this caller can use the table.
+   */
+  async _ensureReadyWithDb(db) {
+    if (this._isReady) return
+
+    const transactionCompletion = db.insideTransaction() ? db.transactionCompletion() : null
+    const transactionReady = this._transactionReadyPromises.get(db)
+
+    if (transactionCompletion && transactionReady?.completion === transactionCompletion) {
+      await transactionReady.promise
+      return
+    }
+
+    if (this._readyPromise) {
+      const readyPromise = this._readyPromise
+
+      await readyPromise
+      if (this._readyPromise === readyPromise) this._readyPromise = null
+      if (this._isReady) return
+
+      await this.ensureReady()
+      return
+    }
+
+    if (transactionCompletion) {
+      const tableReadyPromise = this._ensureChangesTable(db)
+      const transactionReadyPromise = tableReadyPromise.then(() => undefined)
+
+      const durableReadyPromise = tableReadyPromise.then(async (created) => {
+        if (!created) {
+          this._isReady = true
+          return
+        }
+
+        await transactionCompletion
       })
+
+      this._transactionReadyPromises.set(db, {completion: transactionCompletion, promise: transactionReadyPromise})
+      this._readyPromise = durableReadyPromise
+      await transactionReadyPromise
+      return
+    }
+
+    this._readyPromise = this._ensureChangesTable(db).then(() => {
       this._isReady = true
-    })()
+    })
 
     try {
       await this._readyPromise
@@ -257,10 +305,10 @@ export default class ServerChangeFeedStore {
   /**
    * Ensures changes table exists.
    * @param {import("../database/drivers/base.js").default} db - Database connection.
-   * @returns {Promise<void>} - Resolves when complete.
+   * @returns {Promise<boolean>} - Whether the table had to be created.
    */
   async _ensureChangesTable(db) {
-    if (await db.tableExists(TABLE_NAME)) return
+    if (await db.tableExists(TABLE_NAME)) return false
 
     const table = new TableData(TABLE_NAME, {ifNotExists: true})
 
@@ -279,6 +327,8 @@ export default class ServerChangeFeedStore {
     table.datetime("created_at", {index: true, null: false})
 
     await db.createTable(table)
+
+    return true
   }
 
   /**

package/src/sync/sync-scope-store.js

@@ -50,6 +50,8 @@ export default class SyncScopeStore {
     this._isReady = false
     /** @type {Promise<void> | null} */
     this._readyPromise = null
+    /** @type {WeakMap<import("../database/drivers/base.js").default, {completion: Promise<void>, promise: Promise<void>}>} */
+    this._transactionReadyPromises = new WeakMap()
   }
 
   /**
@@ -64,10 +66,56 @@ export default class SyncScopeStore {
       return
     }
 
-    if (this._readyPromise) return await this._readyPromise
+    await this._withDb(async (db) => await this._ensureReadyWithDb(db))
+  }
+
+  /**
+   * Coordinates durable and transaction-local readiness on one connection.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} Resolves when this caller can use the table.
+   */
+  async _ensureReadyWithDb(db) {
+    if (this._isReady) return
+
+    const transactionCompletion = db.insideTransaction() ? db.transactionCompletion() : null
+    const transactionReady = this._transactionReadyPromises.get(db)
 
-    this._readyPromise = this._withDb(async (db) => {
-      await this._ensureScopesTable(db)
+    if (transactionCompletion && transactionReady?.completion === transactionCompletion) {
+      await transactionReady.promise
+      return
+    }
+
+    if (this._readyPromise) {
+      const readyPromise = this._readyPromise
+
+      await readyPromise
+      if (this._readyPromise === readyPromise) this._readyPromise = null
+      if (this._isReady) return
+
+      await this.ensureReady()
+      return
+    }
+
+    if (transactionCompletion) {
+      const tableReadyPromise = this._ensureScopesTable(db)
+      const transactionReadyPromise = tableReadyPromise.then(() => undefined)
+
+      const durableReadyPromise = tableReadyPromise.then(async (created) => {
+        if (!created) {
+          this._isReady = true
+          return
+        }
+
+        await transactionCompletion
+      })
+
+      this._transactionReadyPromises.set(db, {completion: transactionCompletion, promise: transactionReadyPromise})
+      this._readyPromise = durableReadyPromise
+      await transactionReadyPromise
+      return
+    }
+
+    this._readyPromise = this._ensureScopesTable(db).then(() => {
       this._isReady = true
     })
 
@@ -274,10 +322,10 @@ export default class SyncScopeStore {
   /**
    * Ensures the scopes table exists.
    * @param {import("../database/drivers/base.js").default} db - Database connection.
-   * @returns {Promise<void>}
+   * @returns {Promise<boolean>} Whether the table had to be created.
    */
   async _ensureScopesTable(db) {
-    if (await db.tableExists(TABLE_NAME)) return
+    if (await db.tableExists(TABLE_NAME)) return false
 
     const table = new TableData(TABLE_NAME, {ifNotExists: true})
 
@@ -291,6 +339,8 @@ export default class SyncScopeStore {
     table.datetime("updated_at", {null: false})
 
     await db.createTable(table)
+
+    return true
   }
 
   /**

package/src/tenants/frontend-tenant-sqlite-lifecycle.js

@@ -8,6 +8,9 @@
  * @property {boolean} dirty - Whether delayed writes remain.
  * @property {number} lastUsed - Monotonic recency sequence.
  * @property {number} pinCount - Active scoped pins.
+ * @property {Promise<void> | undefined} readinessPromise - In-progress schema readiness.
+ * @property {boolean} ready - Whether migrations and model metadata are ready.
+ * @property {string | undefined} schemaGeneration - Ready or in-progress schema generation.
  * @property {LifecycleState} state - Current lifecycle state.
  */
 
@@ -55,7 +58,17 @@ export default class FrontendTenantSqliteLifecycle {
     const key = this.key(databaseIdentifier, databaseConfiguration)
     let entry = this.entries.get(key)
     if (!entry) {
-      entry = {databaseConfiguration, databaseIdentifier, dirty: false, lastUsed: 0, pinCount: 0, state: "closed"}
+      entry = {
+        databaseConfiguration,
+        databaseIdentifier,
+        dirty: false,
+        lastUsed: 0,
+        pinCount: 0,
+        readinessPromise: undefined,
+        ready: false,
+        schemaGeneration: undefined,
+        state: "closed"
+      }
       this.entries.set(key, entry)
     }
     return entry
@@ -67,6 +80,8 @@ export default class FrontendTenantSqliteLifecycle {
       dirty: entry.dirty,
       lastUsed: entry.lastUsed,
       pinCount: entry.pinCount,
+      ready: entry.ready,
+      schemaGeneration: entry.schemaGeneration,
       state: entry.state
     })
   }
@@ -94,6 +109,78 @@ export default class FrontendTenantSqliteLifecycle {
     })
   }
 
+  /**
+   * Opens and prepares one captured physical tenant database generation. The
+   * readiness callback runs outside the lifecycle bookkeeping lock, so distinct
+   * tenant databases can migrate concurrently while matching callers share one
+   * promise.
+   * @param {string} databaseIdentifier - Logical database identifier.
+   * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Captured physical configuration.
+   * @param {string} schemaGeneration - Application schema generation.
+   * @param {() => Promise<void>} callback - Migration and metadata initialization.
+   * @returns {Promise<Readonly<ReturnType<FrontendTenantSqliteLifecycle["snapshot"]>>>} - Ready lifecycle snapshot.
+   */
+  async initialize(databaseIdentifier, databaseConfiguration, schemaGeneration, callback) {
+    this.assertSqlite(databaseConfiguration)
+    if (!databaseConfiguration.tenantOnly) throw new Error("Frontend tenant database initialization requires a tenant-only SQLite database")
+    if (typeof schemaGeneration !== "string" || schemaGeneration.length === 0) {
+      throw new TypeError("Frontend tenant database initialization requires a non-empty schemaGeneration")
+    }
+
+    const readiness = await this.serialize(async () => {
+      const entry = this.entry(databaseIdentifier, databaseConfiguration)
+
+      if (entry.readinessPromise) {
+        if (entry.schemaGeneration !== schemaGeneration) {
+          throw new Error(`Frontend tenant database is already initializing schema generation ${JSON.stringify(entry.schemaGeneration)}; cannot initialize mismatched generation ${JSON.stringify(schemaGeneration)}`)
+        }
+
+        return {entry, promise: entry.readinessPromise}
+      }
+      if (entry.ready && entry.schemaGeneration === schemaGeneration) {
+        return {entry, promise: Promise.resolve()}
+      }
+      if (entry.schemaGeneration && entry.schemaGeneration !== schemaGeneration && (entry.pinCount > 0 || this.configuration.getDatabasePool(databaseIdentifier).capturedConnectionInUse(databaseConfiguration))) {
+        throw new Error(`Cannot replace frontend tenant schema generation ${JSON.stringify(entry.schemaGeneration)} while its physical database is in use`)
+      }
+      if (entry.state !== "open") await this.openUnlocked(entry)
+      if (entry.schemaGeneration && entry.schemaGeneration !== schemaGeneration) {
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
+      }
+
+      entry.ready = false
+      entry.schemaGeneration = schemaGeneration
+      entry.pinCount++
+      const promise = Promise.resolve().then(callback)
+
+      entry.readinessPromise = promise
+
+      return {entry, promise}
+    })
+
+    try {
+      await readiness.promise
+      await this.serialize(async () => {
+        if (readiness.entry.readinessPromise === readiness.promise) {
+          readiness.entry.readinessPromise = undefined
+          readiness.entry.ready = true
+          readiness.entry.pinCount--
+        }
+      })
+    } catch (error) {
+      await this.serialize(async () => {
+        if (readiness.entry.readinessPromise === readiness.promise) {
+          readiness.entry.readinessPromise = undefined
+          readiness.entry.ready = false
+          readiness.entry.pinCount--
+        }
+      })
+      throw error
+    }
+
+    return this.snapshot(readiness.entry)
+  }
+
   async flush(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration) {
     this.assertSqlite(databaseConfiguration)
     return await this.serialize(async () => {
@@ -117,7 +204,10 @@ export default class FrontendTenantSqliteLifecycle {
       try {
         if (flush) await this.configuration.getDatabasePool(databaseIdentifier).flushCapturedConnection(databaseConfiguration)
         await this.configuration.getDatabasePool(databaseIdentifier).closeCapturedConnection(databaseConfiguration)
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
         entry.dirty = false
+        entry.ready = false
+        entry.schemaGeneration = undefined
         entry.state = "closed"
         this.entries.delete(this.key(databaseIdentifier, databaseConfiguration))
         return this.snapshot(entry)
@@ -136,11 +226,16 @@ export default class FrontendTenantSqliteLifecycle {
       entry.state = "deleting"
       try {
         await this.configuration.getDatabasePool(databaseIdentifier).deleteCapturedDatabase(databaseConfiguration)
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
         entry.dirty = false
+        entry.ready = false
+        entry.schemaGeneration = undefined
         entry.state = "closed"
         this.entries.delete(this.key(databaseIdentifier, databaseConfiguration))
         return this.snapshot(entry)
       } catch (error) {
+        this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(databaseIdentifier, databaseConfiguration))
+        entry.ready = false
         entry.state = "closed"
         throw error
       }
@@ -150,7 +245,7 @@ export default class FrontendTenantSqliteLifecycle {
   inspect(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration) {
     this.assertSqlite(databaseConfiguration)
     const entry = this.entries.get(this.key(databaseIdentifier, databaseConfiguration))
-    return entry ? this.snapshot(entry) : Object.freeze({databaseIdentifier, dirty: false, lastUsed: 0, pinCount: 0, state: "closed"})
+    return entry ? this.snapshot(entry) : Object.freeze({databaseIdentifier, dirty: false, lastUsed: 0, pinCount: 0, ready: false, schemaGeneration: undefined, state: "closed"})
   }
 
   inspectAll() {
@@ -158,7 +253,13 @@ export default class FrontendTenantSqliteLifecycle {
     return Object.freeze({handles: Object.freeze(handles), maxOpenHandles: this.maxOpenHandles, openCount: handles.filter(({state}) => state === "open").length})
   }
 
-  reset() { this.entries.clear() }
+  reset() {
+    for (const entry of this.entries.values()) {
+      this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(entry.databaseIdentifier, entry.databaseConfiguration))
+    }
+
+    this.entries.clear()
+  }
 
   async withPin(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration, /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ callback) {
     this.assertSqlite(databaseConfiguration)
@@ -176,21 +277,52 @@ export default class FrontendTenantSqliteLifecycle {
     }
   }
 
-  async databaseOperation(/** @type {string} */ databaseIdentifier, /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ databaseConfiguration, /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ callback) {
-    if (!this.entries.has(this.key(databaseIdentifier, databaseConfiguration))) return await callback()
+  /**
+   * Atomically validates readiness, captures the schema generation, and pins
+   * one lifecycle entry before starting database work.
+   * @param {string} databaseIdentifier - Logical database identifier.
+   * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Captured physical configuration.
+   * @param {{requireReady: boolean, schemaGeneration?: string}} options - Operation readiness requirements.
+   * @param {(schemaGeneration: string | undefined) => Promise<ReturnType<typeof JSON.parse>>} callback - Pinned operation callback.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Operation result.
+   */
+  async databaseOperation(databaseIdentifier, databaseConfiguration, {requireReady, schemaGeneration}, callback) {
+    if (databaseConfiguration.type !== "sqlite") return await callback(schemaGeneration)
 
-    return await this.withPin(databaseIdentifier, databaseConfiguration, async () => {
-      try {
-        return await callback()
-      } finally {
-        const dirty = this.configuration.getDatabasePool(databaseIdentifier).capturedConnectionHasPendingWrites(databaseConfiguration)
-        await this.serialize(async () => {
-          const entry = this.entry(databaseIdentifier, databaseConfiguration)
-          entry.dirty ||= dirty
-          entry.lastUsed = ++this.sequence
-        })
+    const entry = await this.serialize(async () => {
+      const operationEntry = this.entries.get(this.key(databaseIdentifier, databaseConfiguration))
+
+      if (requireReady && databaseConfiguration.tenantOnly && databaseConfiguration.migrations && !operationEntry?.ready) {
+        const generation = operationEntry?.schemaGeneration ? ` for schema generation ${JSON.stringify(operationEntry.schemaGeneration)}` : ""
+
+        throw new Error(`Frontend tenant database ${JSON.stringify(databaseIdentifier)} is not ready${generation}`)
+      }
+      if (!operationEntry) return undefined
+      if (schemaGeneration && operationEntry.schemaGeneration && schemaGeneration !== operationEntry.schemaGeneration) {
+        throw new Error(`Frontend tenant database ${JSON.stringify(databaseIdentifier)} is on schema generation ${JSON.stringify(operationEntry.schemaGeneration)}, not ${JSON.stringify(schemaGeneration)}`)
       }
+      if (operationEntry.state !== "open") await this.openUnlocked(operationEntry)
+
+      operationEntry.pinCount++
+      operationEntry.lastUsed = ++this.sequence
+
+      return operationEntry
     })
+    const operationSchemaGeneration = schemaGeneration || entry?.schemaGeneration
+
+    if (!entry) return await callback(operationSchemaGeneration)
+
+    try {
+      return await callback(operationSchemaGeneration)
+    } finally {
+      const dirty = this.configuration.getDatabasePool(databaseIdentifier).capturedConnectionHasPendingWrites(databaseConfiguration)
+
+      await this.serialize(async () => {
+        entry.dirty ||= dirty
+        entry.lastUsed = ++this.sequence
+        entry.pinCount--
+      })
+    }
   }
 
   async openUnlocked(/** @type {LifecycleEntry} */ entry) {
@@ -222,6 +354,9 @@ export default class FrontendTenantSqliteLifecycle {
     const victim = candidates[0]
     if (!victim) throw new Error(`Frontend tenant SQLite handle capacity ${this.maxOpenHandles} reached; every handle is dirty, pinned, or in use`)
     await this.configuration.getDatabasePool(victim.databaseIdentifier).closeCapturedConnection(victim.databaseConfiguration)
+    this.configuration.clearRecordMetadataForDatabaseIdentity(this.key(victim.databaseIdentifier, victim.databaseConfiguration))
+    victim.ready = false
+    victim.schemaGeneration = undefined
     victim.state = "closed"
     this.entries.delete(this.key(victim.databaseIdentifier, victim.databaseConfiguration))
   }