velocious 1.0.593 → 1.0.595

package/src/tenants/tenant-handle.js

@@ -1,11 +1,13 @@
 // @ts-check
 
+import Migrator from "../database/migrator.js"
+
 /**
  * TenantDescriptorValue type.
  * @typedef {null | boolean | number | string | TenantDescriptorValue[] | {[key: string]: TenantDescriptorValue}} TenantDescriptorValue
  */
 /** @typedef {{[key: string]: TenantDescriptorValue}} TenantDescriptor */
-/** @typedef {{databaseIdentifier: string, dirty: boolean, lastUsed: number, pinCount: number, state: "closed" | "closing" | "deleting" | "open" | "opening"}} TenantSqliteLifecycleSnapshot */
+/** @typedef {{databaseIdentifier: string, dirty: boolean, lastUsed: number, pinCount: number, ready: boolean, schemaGeneration: string | undefined, state: "closed" | "closing" | "deleting" | "open" | "opening"}} TenantSqliteLifecycleSnapshot */
 
 /**
  * Returns a readable path for a captured descriptor/configuration value.
@@ -204,6 +206,17 @@ export default class TenantHandle {
     return this._tenant
   }
 
+  /**
+   * Rejects using this handle with a different Configuration instance.
+   * @param {import("../configuration.js").default} configuration - Expected owner.
+   * @returns {void}
+   */
+  assertConfiguration(configuration) {
+    if (configuration !== this._configuration) {
+      throw new Error("Tenant handle belongs to a different Velocious configuration")
+    }
+  }
+
   /**
    * Returns the captured physical configuration for an active identifier.
    * @param {string} databaseIdentifier - Logical database identifier.
@@ -229,6 +242,58 @@ export default class TenantHandle {
     return await this._configuration.getFrontendTenantSqliteLifecycle().open(databaseIdentifier, this.databaseConfiguration(databaseIdentifier))
   }
 
+  /**
+   * Opens, migrates, and initializes record metadata for one captured physical
+   * tenant SQLite database and application schema generation.
+   * @param {object} options - Initialization options.
+   * @param {string} options.databaseIdentifier - Tenant-only logical database identifier.
+   * @param {import("../database/migrator/types.js").RequireMigrationContextType} options.migrations - Frontend migration require context.
+   * @param {string} options.schemaGeneration - Stable application schema generation.
+   * @returns {Promise<Readonly<TenantSqliteLifecycleSnapshot>>} - Ready lifecycle snapshot.
+   */
+  async initialize({databaseIdentifier, migrations, schemaGeneration}) {
+    if (!migrations || typeof migrations !== "function" || typeof migrations.keys !== "function") {
+      throw new TypeError("TenantHandle.initialize requires a migrations require context")
+    }
+
+    const databaseConfiguration = this.databaseConfiguration(databaseIdentifier)
+    const lifecycle = this._configuration.getFrontendTenantSqliteLifecycle()
+
+    return await lifecycle.initialize(databaseIdentifier, databaseConfiguration, schemaGeneration, async () => {
+      await this._databaseOperation({
+        databaseIdentifier,
+        name: `Initialize frontend tenant database: ${databaseIdentifier}`,
+        requireReady: false,
+        schemaGeneration
+      }, async (operation) => {
+        const migrator = new Migrator({configuration: this._configuration, databaseIdentifiers: [databaseIdentifier]})
+
+        operation.connection().clearSchemaCache()
+        await migrator.migrateRequireContextForDatabase({
+          databaseConfiguration,
+          databaseIdentifier,
+          db: operation.connection(),
+          requireContext: migrations
+        })
+        await this._configuration.initializeModels({type: "frontend-tenant"})
+
+        for (const modelClass of Object.values(this._configuration.getModelClasses())) {
+          if (modelClass.getDatabaseIdentifier({tenant: this._tenant}) !== databaseIdentifier) continue
+          const table = await operation.connection().getTableByName(modelClass.tableName(), {throwError: false})
+
+          if (!table && !modelClass.getEagerLoadRecordMetadata()) continue
+          if (Object.keys(modelClass.getTranslationsMap()).length > 0) {
+            const translationsTable = await operation.connection().getTableByName(modelClass.getTranslationsTableName(), {throwError: false})
+
+            if (!translationsTable && !modelClass.getEagerLoadRecordMetadata()) continue
+          }
+
+          await operation.ensureModelInitialized(modelClass)
+        }
+      })
+    })
+  }
+
   /**
    * Flushes this captured SQLite identity.
    * @param {{databaseIdentifier: string}} options - Lifecycle options.
@@ -290,13 +355,32 @@ export default class TenantHandle {
    * @returns {Promise<T>} - Callback result.
    */
   async databaseOperation({databaseIdentifier, name = "TenantHandle.databaseOperation"}, callback) {
+    return await this._databaseOperation({databaseIdentifier, name, requireReady: true}, callback)
+  }
+
+  /**
+   * Runs a captured operation with explicit readiness policy. Initialization is
+   * the only caller allowed to enter an unready schema generation.
+   * @template T
+   * @param {{databaseIdentifier: string, name: string, requireReady: boolean, schemaGeneration?: string}} options - Internal operation options.
+   * @param {(operation: import("../database/operation.js").default) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async _databaseOperation({databaseIdentifier, name, requireReady, schemaGeneration}, callback) {
     const databaseConfiguration = this.databaseConfiguration(databaseIdentifier)
-    return await this._configuration.getFrontendTenantSqliteLifecycle().databaseOperation(databaseIdentifier, databaseConfiguration, async () => await this._configuration.withDatabaseOperation({
-      databaseConfiguration,
+
+    return await this._configuration.getFrontendTenantSqliteLifecycle().databaseOperation(
       databaseIdentifier,
-      name,
-      tenant: this._tenant
-    }, callback))
+      databaseConfiguration,
+      {requireReady, schemaGeneration},
+      async (operationSchemaGeneration) => await this._configuration.withDatabaseOperation({
+        databaseConfiguration,
+        databaseIdentifier,
+        name,
+        schemaGeneration: operationSchemaGeneration,
+        tenant: this._tenant
+      }, callback)
+    )
   }
 
   /**

package/src/testing/browser-test-app.js

@@ -3,6 +3,7 @@
 import SystemTestBrowserHelper from "system-testing/build/system-test-browser-helper.js"
 import BrowserEnvironmentHandler from "../environment-handlers/browser.js"
 import runFrontendModelEventHookScenario from "./browser-frontend-model-event-hook-scenarios.js"
+import runUseDatabaseSelectionTransitionScenario from "./browser-use-database-hook-scenarios.js"
 
 const root = document.getElementById("root") || (() => {
   const element = document.createElement("div")
@@ -28,5 +29,6 @@ systemTestBrowserHelper.enableOnBrowser()
 Object.assign(globalThis, {velociousBrowserTest: {
   BrowserEnvironmentHandler,
   runFrontendModelEventHookScenario,
+  runUseDatabaseSelectionTransitionScenario,
   systemTestBrowserHelper
 }})

package/src/testing/browser-use-database-hook-scenarios.js

@@ -0,0 +1,204 @@
+// @ts-check
+
+import React, { act } from "react"
+import {createRoot} from "react-dom/client"
+
+import Configuration, {CurrentConfigurationNotSetError} from "../configuration.js"
+import BrowserEnvironmentHandler from "../environment-handlers/browser.js"
+import Migration from "../database/migration/index.js"
+import SingleMultiUsePool from "../database/pool/single-multi-use.js"
+import SqliteWebDriver from "../database/drivers/sqlite/index.web.js"
+import TenantHandle from "../tenants/tenant-handle.js"
+import useDatabase from "../database/use-database.js"
+
+/**
+ * Returns the current configuration without requiring one to exist.
+ * @returns {Configuration | undefined} - Current configuration when installed.
+ */
+function currentConfigurationOrUndefined() {
+  try {
+    return Configuration.current()
+  } catch (error) {
+    if (!(error instanceof CurrentConfigurationNotSetError)) throw error
+
+    return undefined
+  }
+}
+
+/**
+ * Builds the scoped browser configuration used by the real hook scenario.
+ * @returns {Configuration} - Browser test configuration.
+ */
+function buildHookConfiguration() {
+  return new Configuration({
+    database: {
+      test: {
+        projectTenant: {
+          driver: SqliteWebDriver,
+          getConnection: async () => { throw new Error("Hook scenario must not open a physical database") },
+          migrations: true,
+          name: "use-database-hook-template",
+          poolType: SingleMultiUsePool,
+          tenantOnly: true,
+          type: "sqlite"
+        }
+      }
+    },
+    directory: "/use-database-hook-scenario",
+    environment: "test",
+    environmentHandler: new BrowserEnvironmentHandler(),
+    initializeModels: async () => {},
+    locale: "en",
+    localeFallbacks: {en: ["en"]},
+    locales: ["en"],
+    tenantDatabaseResolver: ({identifier, tenant}) => {
+      if (identifier !== "projectTenant" || !tenant || typeof tenant !== "object") return
+
+      return {name: `use-database-hook-${String(/** @type {{slug?: string}} */ (tenant).slug)}`}
+    }
+  })
+}
+
+/**
+ * Flushes real React hook transitions and reports synchronous selection state,
+ * inline loader stability, and stale completion suppression.
+ * @returns {Promise<{firstChangedLoaded: boolean, initialLoaded: boolean, loaderCalls: string[], loadedAfterInlineLoaderRerender: boolean, thirdAfterStaleCompletion: {error: string | null, loaded: boolean}}>} - Render observations.
+ */
+export default async function runUseDatabaseSelectionTransitionScenario() {
+  const container = document.createElement("div")
+  document.body.appendChild(container)
+  const root = createRoot(container)
+  /** @type {{error: string | null, loaded: boolean, selection: "first" | "second" | "third"}[]} */
+  const renders = []
+  /** @type {string[]} */
+  const loaderCalls = []
+  /**
+   * Releases the deliberately stale second initialization.
+   * @type {() => void}
+   */
+  let releaseSecondInitialization = () => {}
+  const secondInitializationRelease = new Promise((resolve) => { releaseSecondInitialization = () => resolve(undefined) })
+  /**
+   * Signals that the deliberately stale second initialization started.
+   * @type {() => void}
+   */
+  let signalSecondInitialization = () => {}
+  const secondInitializationStarted = new Promise((resolve) => { signalSecondInitialization = () => resolve(undefined) })
+
+  class HookTenantHandle extends TenantHandle {
+    /**
+     * Runs test initialization without touching a physical database.
+     * @param {{migrations: import("../database/migrator/types.js").RequireMigrationContextType}} args - Hook initialization arguments.
+     * @returns {Promise<Readonly<ReturnType<TenantHandle["inspect"]>>>} - Ready test snapshot.
+     */
+    async initialize({migrations}) {
+      loaderCalls.push(migrations.id)
+
+      if (this.tenant().slug === "second") {
+        signalSecondInitialization()
+        await secondInitializationRelease
+        throw new Error("SECOND_SELECTION_FAILED")
+      }
+
+      return Object.freeze({databaseIdentifier: "projectTenant", dirty: false, lastUsed: 0, pinCount: 0, ready: true, schemaGeneration: "generation-1", state: "open"})
+    }
+  }
+  const previousConfiguration = currentConfigurationOrUndefined()
+  const restorationConfiguration = previousConfiguration || buildHookConfiguration()
+  const configuration = buildHookConfiguration()
+
+  configuration.setCurrent()
+
+  const firstHandle = new HookTenantHandle({configuration, tenant: {slug: "first"}})
+  const secondHandle = new HookTenantHandle({configuration, tenant: {slug: "second"}})
+  const thirdHandle = new HookTenantHandle({configuration, tenant: {slug: "third"}})
+  const renderCounts = {first: 0, second: 0, third: 0}
+
+  /**
+   * Runs hook probe.
+   * @param {{selection: "first" | "second" | "third", tenantHandle: HookTenantHandle}} props - Probe props.
+   * @returns {React.ReactElement} - Empty host element.
+   */
+  function HookProbe({selection, tenantHandle}) {
+    const state = useDatabase({
+      databaseIdentifier: "projectTenant",
+      migrationsRequireContextCallback: async () => {
+        /**
+         * Looks up an empty migration context entry recreated by every probe render.
+         * @param {string} fileName - Requested migration file.
+         * @returns {{default: typeof Migration}} - Placeholder migration module.
+         * @type {import("../database/migrator/types.js").RequireMigrationContextType}
+         */
+        const emptyMigrations = (fileName) => {
+          if (!fileName) throw new Error("Migration context lookup requires a file name")
+
+          return {default: Migration}
+        }
+
+        emptyMigrations.keys = () => []
+        emptyMigrations.id = selection
+
+        return emptyMigrations
+      },
+      schemaGeneration: "generation-1",
+      tenantHandle
+    })
+
+    renderCounts[selection]++
+    if (renderCounts[selection] > 20) throw new Error(`useDatabase render loop for ${selection}`)
+    renders.push({error: state.error?.message || null, loaded: state.loaded, selection})
+
+    return React.createElement("div")
+  }
+
+  try {
+    await act(async () => {
+      root.render(React.createElement(HookProbe, {selection: "first", tenantHandle: firstHandle}))
+    })
+
+    const initialRender = renders.at(-1)
+
+    await act(async () => {
+      root.render(React.createElement(HookProbe, {selection: "first", tenantHandle: firstHandle}))
+    })
+
+    const loadedAfterInlineLoaderRerender = renders.at(-1)?.loaded
+
+    act(() => {
+      root.render(React.createElement(HookProbe, {selection: "second", tenantHandle: secondHandle}))
+    })
+
+    const firstChangedRender = renders.find((render) => render.selection === "second")
+    await secondInitializationStarted
+
+    await act(async () => {
+      root.render(React.createElement(HookProbe, {selection: "third", tenantHandle: thirdHandle}))
+    })
+
+    releaseSecondInitialization()
+    await act(async () => { await secondInitializationRelease })
+
+    const thirdAfterStaleCompletion = renders.at(-1)
+
+    if (!initialRender || !firstChangedRender || !thirdAfterStaleCompletion || loadedAfterInlineLoaderRerender === undefined) {
+      throw new Error("useDatabase hook scenario did not render every selection")
+    }
+
+    return {
+      firstChangedLoaded: firstChangedRender.loaded,
+      initialLoaded: initialRender.loaded,
+      loaderCalls,
+      loadedAfterInlineLoaderRerender,
+      thirdAfterStaleCompletion: {
+        error: thirdAfterStaleCompletion.error,
+        loaded: thirdAfterStaleCompletion.loaded
+      }
+    }
+  } finally {
+    releaseSecondInitialization()
+    await act(async () => { root.unmount() })
+    container.remove()
+    restorationConfiguration.setCurrent()
+    await configuration.closeDatabaseConnections()
+  }
+}

package/src/testing/test-runner.js

@@ -1456,14 +1456,15 @@ export default class TestRunner {
      * @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */
     const consoleObject = /** @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */ (console)
     /**
-     * Original console methods.
+     * Original console methods captured as direct references so stopping restores
+     * the exact method that was installed at capture start.
      * @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */
     const originalConsoleMethods = {
-      debug: consoleObject.debug.bind(console),
-      error: consoleObject.error.bind(console),
-      info: consoleObject.info.bind(console),
-      log: consoleObject.log.bind(console),
-      warn: consoleObject.warn.bind(console)
+      debug: consoleObject.debug,
+      error: consoleObject.error,
+      info: consoleObject.info,
+      log: consoleObject.log,
+      warn: consoleObject.warn
     }
     let stopped = false
     let outputText = ""
@@ -1473,7 +1474,7 @@ export default class TestRunner {
         lines.push(`[${new Date().toISOString()}] [${methodName}] ${format(...args)}`)
 
         if (passthrough) {
-          originalConsoleMethods[methodName](...args)
+          originalConsoleMethods[methodName].apply(consoleObject, args)
         }
       }
     }

package/src/utils/model-scope.js

@@ -15,17 +15,20 @@ const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
  * @param {object} args - Definition arguments.
  * @param {(...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>} args.callback - Scope callback.
  * @param {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass} args.modelClass - Owning model class.
- * @param {() => ReturnType<typeof JSON.parse>} args.startQuery - Factory that returns a fresh query for the owning model class.
+ * @param {(modelClass?: typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass) => ReturnType<typeof JSON.parse>} args.startQuery - Factory that returns a fresh query for the invoked model class.
  * @returns {((...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>) & {scope: (...args: Array<ReturnType<typeof JSON.parse>>) => ModelScopeDescriptor}} - Scope helper.
  */
 export function defineModelScope({callback, modelClass, startQuery}) {
   /**
    * Runs defined scope.
+   * @this {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass | undefined}
    * @param {...ReturnType<typeof JSON.parse>} scopeArgs - Scope arguments.
    * @returns {ReturnType<typeof JSON.parse>} - Scoped root query.
    */
   function definedScope(...scopeArgs) {
-    return startQuery().scope(definedScope.scope(...scopeArgs))
+    const invokedModelClass = typeof this === "function" ? this : modelClass
+
+    return startQuery(invokedModelClass).scope(definedScope.scope(...scopeArgs))
   }
 
   /**

package/src/utils/ransack.js

@@ -572,9 +572,12 @@ function backendRelationshipEntries(modelClass) {
 
     if (typeof relationship.isPolymorphic === "function" && relationship.isPolymorphic()) continue
 
-    const targetModelClass = relationship.getTargetModelClass()
+    const rawTargetModelClass = relationship.getTargetModelClass()
 
-    if (!targetModelClass) continue
+    if (!rawTargetModelClass) continue
+
+    const targetModelClass = /** @type {typeof import("../database/record/index.js").default} */ (modelClass)
+      .bindRecordMetadataModelClass(rawTargetModelClass)
 
     entries[relationshipName] = {targetModelClass}
   }