velocious 1.0.592 → 1.0.594

package/build/database/query/with-count.js

@@ -155,13 +155,14 @@ function queryForEntry({entry, modelClass, sourceModel}) {
     throw new Error(`withCount currently supports only hasMany relationships; ${modelClass.name}#${entry.relationshipName} is ${relationship.type}`)
   }
 
-  const targetModelClass = relationship.getTargetModelClass()
+  const rawTargetModelClass = relationship.getTargetModelClass()
 
-  if (!targetModelClass) {
+  if (!rawTargetModelClass) {
     throw new Error(`withCount: could not resolve target model for ${modelClass.name}#${entry.relationshipName}`)
   }
 
-  const foreignKey = relationship.getForeignKey()
+  const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
+  const foreignKey = relationship.getForeignKeyForModelClasses({modelClass, targetModelClass})
   /**
    * Mandatory cohort conditions.
    * @type {Record<string, ReturnType<typeof JSON.parse>>} */

package/build/database/record/index.js

@@ -24,6 +24,11 @@
 
 /** @typedef {import("../../configuration-types.js").TenantDatabaseProviderType} TenantDatabaseProviderType */
 
+/**
+ * Schema metadata cached for one record class and physical database generation.
+ * @typedef {boolean | null | string | undefined | Promise<void> | string[] | import("../drivers/base-column.js").default[] | import("../drivers/base-table.js").default | Record<string, string> | Record<string, string | undefined> | Record<string, import("../drivers/base-column.js").default>} RecordMetadataValue
+ */
+
 import AdvisoryLockRunner, {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError} from "../advisory-lock-runner.js"
 import BelongsToInstanceRelationship from "./instance-relationships/belongs-to.js"
 import BelongsToRelationship from "./relationships/belongs-to.js"
@@ -73,6 +78,39 @@ const declaredBooleanTruthyValues = new Set([1, true, "1"])
 /** Stored values that a declared `"boolean"` cast reads back as `false`. */
 const declaredBooleanFalsyValues = new Set([0, false, "0"])
 
+/** Static record metadata fields isolated per physical database/schema generation. */
+const recordMetadataPropertyNames = new Set([
+  "_attributeNameToColumnName",
+  "_columnNameToAttributeName",
+  "_columnNames",
+  "_columns",
+  "_columnsAsHash",
+  "_columnTypeByName",
+  "_databaseType",
+  "_initialized",
+  "_initializeRecordPromise",
+  "_table"
+])
+
+/** @type {WeakMap<typeof import("./index.js").default, Map<string, Map<string, RecordMetadataValue>>>} */
+const recordMetadataValuesByModel = new WeakMap()
+
+/**
+ * Returns the generation-keyed metadata store owned by one canonical model.
+ * @param {typeof import("./index.js").default} modelClass - Canonical model class.
+ * @returns {Map<string, Map<string, RecordMetadataValue>>} - Metadata store.
+ */
+function recordMetadataValuesFor(modelClass) {
+  let values = recordMetadataValuesByModel.get(modelClass)
+
+  if (!values) {
+    values = new Map()
+    recordMetadataValuesByModel.set(modelClass, values)
+  }
+
+  return values
+}
+
 class ValidationError extends Error {
   /**
    * Narrows the runtime value to the documented type.
@@ -236,6 +274,15 @@ class VelociousDatabaseRecord {
    * @type {Promise<void> | null | undefined} */
   static _initializeRecordPromise
 
+  /** @type {typeof VelociousDatabaseRecord | undefined} Canonical model class exposed only by an operation-bound metadata proxy. */
+  static _recordMetadataModelClass
+
+  /** @type {((modelClass: typeof VelociousDatabaseRecord) => typeof VelociousDatabaseRecord) | undefined} Binds related generated model classes to the same operation metadata generation. */
+  static _recordMetadataBinder
+
+  /** @type {import("../operation.js").default | undefined} Operation exposed only by a constructing metadata proxy. */
+  static _recordMetadataOperation
+
   /**
    * Narrows the runtime value to the documented type.
    * @type {boolean | undefined} */
@@ -360,10 +407,32 @@ class VelociousDatabaseRecord {
     return defineModelScope({
       callback,
       modelClass: this,
-      startQuery: () => this._newQuery()
+      startQuery: (modelClass = this) => {
+        // This backend scope factory can only be invoked through a DatabaseRecord class.
+        const BackendModelClass = /** @type {typeof VelociousDatabaseRecord} */ (modelClass)
+
+        return BackendModelClass._newQuery()
+      }
     })
   }
 
+  /**
+   * Returns the application model class behind an operation-bound metadata view.
+   * @returns {typeof VelociousDatabaseRecord} - Canonical model class.
+   */
+  static canonicalRecordMetadataModelClass() {
+    return this._recordMetadataModelClass || this
+  }
+
+  /**
+   * Binds a relationship target to this model class's metadata generation.
+   * @param {typeof VelociousDatabaseRecord} modelClass - Relationship target.
+   * @returns {typeof VelociousDatabaseRecord} - Generation-bound target, or the unchanged target for legacy queries.
+   */
+  static bindRecordMetadataModelClass(modelClass) {
+    return this._recordMetadataBinder ? this._recordMetadataBinder(modelClass) : modelClass
+  }
+
   static getColumnNameToAttributeNameMap() {
     if (!this._columnNameToAttributeName) {
       /**
@@ -1470,6 +1539,68 @@ class VelociousDatabaseRecord {
     this._columnTypeByName = undefined
     this._attributeNameToColumnName = undefined
     this._columnNameToAttributeName = undefined
+
+    if (!this._recordMetadataModelClass) this.clearRecordMetadataValues()
+  }
+
+  /**
+   * Static fields that belong to one physical database/schema generation.
+   * @returns {Set<string>} - Metadata property names.
+   */
+  static recordMetadataPropertyNames() {
+    return recordMetadataPropertyNames
+  }
+
+  /**
+   * Reads one operation-bound metadata field.
+   * @param {string} metadataKey - Physical database and schema generation key.
+   * @param {string} property - Static metadata property.
+   * @returns {RecordMetadataValue} - Stored metadata value.
+   */
+  static recordMetadataValue(metadataKey, property) {
+    return recordMetadataValuesFor(this).get(metadataKey)?.get(property)
+  }
+
+  /**
+   * Writes one operation-bound metadata field.
+   * @param {string} metadataKey - Physical database and schema generation key.
+   * @param {string} property - Static metadata property.
+   * @param {RecordMetadataValue} value - Metadata value.
+   * @returns {void}
+   */
+  static setRecordMetadataValue(metadataKey, property, value) {
+    let values = recordMetadataValuesFor(this).get(metadataKey)
+
+    if (!values) {
+      values = new Map()
+      recordMetadataValuesFor(this).set(metadataKey, values)
+    }
+
+    values.set(property, value)
+  }
+
+  /** Clears every tenant/generation metadata snapshot for this model. */
+  static clearRecordMetadataValues() {
+    recordMetadataValuesByModel.delete(this)
+  }
+
+  /**
+   * Clears snapshots whose key belongs to one physical database identity.
+   * @param {string} databaseIdentity - Logical identifier plus pool reuse key.
+   * @returns {void}
+   */
+  static clearRecordMetadataValuesForDatabaseIdentity(databaseIdentity) {
+    const values = recordMetadataValuesByModel.get(this)
+
+    if (!values) return
+
+    const metadataPrefix = `${databaseIdentity.length}:${databaseIdentity}:`
+
+    for (const metadataKey of values.keys()) {
+      if (metadataKey.startsWith(metadataPrefix)) values.delete(metadataKey)
+    }
+
+    if (values.size === 0) recordMetadataValuesByModel.delete(this)
   }
 
   /**
@@ -1484,8 +1615,10 @@ class VelociousDatabaseRecord {
     if (!configuration) throw new Error(`No configuration given for ${this.name}`)
 
     this.resetRecordMetadata()
-    this._configuration = configuration
-    this._configuration.registerModelClass(this)
+    const modelClass = this._recordMetadataModelClass || this
+
+    modelClass._configuration = configuration
+    configuration.registerModelClass(modelClass)
   }
 
   /**
@@ -1637,7 +1770,10 @@ class VelociousDatabaseRecord {
 
       if (!locales) throw new Error("Locales hasn't been set in the configuration")
 
-      await this.getTranslationClass().initializeRecord({
+      const TranslationClass = this.getTranslationClass()
+      const BoundTranslationClass = this._recordMetadataBinder ? this._recordMetadataBinder(TranslationClass) : TranslationClass
+
+      await BoundTranslationClass.initializeRecord({
         configuration: this._getConfiguration(),
         connection
       })
@@ -1825,6 +1961,8 @@ class VelociousDatabaseRecord {
   getModelClass() {
     const modelClass = /** @type {typeof VelociousDatabaseRecord} */ (this.constructor)
 
+    if (this._databaseOperation) return this._databaseOperation.modelClass(modelClass)
+
     return modelClass
   }
 
@@ -3092,8 +3230,10 @@ class VelociousDatabaseRecord {
    * @returns {ModelClassQuery<MC>} - The new query.
    */
   static _newQuery(args = {}) {
-    const {driver = () => this.connection(), operation, ...restArgs} = args
+    const {driver: givenDriver, operation: givenOperation, ...restArgs} = args
     restArgsError(restArgs)
+    const operation = givenOperation || this._recordMetadataOperation
+    const driver = givenDriver || (operation ? operation.connection() : () => this.connection())
     this._assertHasBeenInitialized()
     const handler = new Handler()
     const query = new ModelClassQuery({
@@ -3450,6 +3590,9 @@ class VelociousDatabaseRecord {
    * @param {WriteAttributes} changes - Changes.
    */
   constructor(changes = /** @type {WriteAttributes} */ ({})) {
+    const ModelClass = /** @type {typeof VelociousDatabaseRecord} */ (new.target)
+
+    this._databaseOperation = ModelClass._recordMetadataOperation
     this.getModelClass()._assertHasBeenInitialized()
     this._attributes = {}
     this._changes = {}

package/build/database/record/instance-relationships/base.js

@@ -62,6 +62,19 @@ export default class VelociousDatabaseRecordBaseInstanceRelationship {
     throw new Error("'build' not implemented")
   }
 
+  /**
+   * Resolves a relationship target through the source record's operation and
+   * metadata generation before construction.
+   * @returns {TMC | undefined} - Bound target model class.
+   */
+  getBoundTargetModelClass() {
+    const targetModelClass = this.getTargetModelClass()
+
+    if (!targetModelClass) return undefined
+
+    return /** @type {TMC} */ (this.getModel().getModelClass().bindRecordMetadataModelClass(targetModelClass))
+  }
+
   /**
    * Runs get auto save.
    * @returns {boolean | undefined} Whether the relationship should be auto-saved before saving the parent model

package/build/database/record/instance-relationships/belongs-to.js

@@ -23,7 +23,7 @@ export default class VelociousDatabaseRecordBelongsToInstanceRelationship extend
    * @returns {InstanceType<TMC>} - The build.
    */
   build(data) {
-    const TargetModelClass = /** @type {TMC} */ (this.getTargetModelClass())
+    const TargetModelClass = this.getBoundTargetModelClass()
 
     if (!TargetModelClass) throw new Error("Can't build a new record without a target model")
 

package/build/database/record/instance-relationships/has-many.js

@@ -25,7 +25,7 @@ export default class VelociousDatabaseRecordHasManyInstanceRelationship extends
    */
   build(data) {
     // Spawn new model of the targeted class
-    const targetModelClass = this.getTargetModelClass()
+    const targetModelClass = this.getBoundTargetModelClass()
 
     if (!targetModelClass) throw new Error("Can't build a new record without a taget model class")
 
@@ -58,7 +58,10 @@ export default class VelociousDatabaseRecordHasManyInstanceRelationship extends
     const parentModel = this.getModel()
 
     if (parentModel.isPersisted()) {
-      const foreignKeyName = this.getForeignKey()
+      const foreignKeyName = this.getRelationship().getForeignKeyForModelClasses({
+        modelClass: parentModel.getModelClass(),
+        targetModelClass
+      })
       const columnNameMap = targetModelClass.getColumnNameToAttributeNameMap()
       const foreignKeyAttributeName = columnNameMap[foreignKeyName]
       if (!foreignKeyAttributeName) throw new Error(`Unknown foreign key attribute name for ${foreignKeyName}`)

package/build/database/record/instance-relationships/has-one.js

@@ -28,7 +28,7 @@ export default class VelociousDatabaseRecordHasOneInstanceRelationship extends B
    * @returns {InstanceType<TMC>} - The build.
    */
   build(data) {
-    const TargetModelClass = /** @type {TMC} */ (this.getTargetModelClass())
+    const TargetModelClass = this.getBoundTargetModelClass()
 
     if (!TargetModelClass) throw new Error("Can't build a new record without a target model class")
 

package/build/database/record/relationships/base.js

@@ -117,6 +117,23 @@ export default class VelociousDatabaseRecordBaseRelationship {
     throw new Error("getForeignKey not implemented")
   }
 
+  /**
+   * Resolves an attribute-form foreign key through the model class that owns the physical column.
+   * @param {object} args - Bound relationship model classes.
+   * @param {typeof import("../index.js").default} args.modelClass - Relationship source model class.
+   * @param {typeof import("../index.js").default} args.targetModelClass - Relationship target model class.
+   * @returns {string} - Physical foreign-key column name.
+   */
+  getForeignKeyForModelClasses({modelClass, targetModelClass}) {
+    this.getForeignKey()
+
+    if (!this.foreignKey) throw new Error(`Relationship ${this.modelClass.name}#${this.relationshipName} did not resolve a foreign key`)
+
+    const foreignKeyModelClass = this.getType() === "belongsTo" ? modelClass : targetModelClass
+
+    return foreignKeyModelClass.getAttributeNameToColumnNameMap()[this.foreignKey] || this.foreignKey
+  }
+
   /**
    * Runs get inverse of.
    * @abstract

package/build/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/build/environment-handlers/base.js

@@ -27,6 +27,24 @@ export default class VelociousEnvironmentHandlerBase {
    */
   async createTestSharedTransactionConnection(_args) { return undefined }
 
+  /**
+   * Gets the active shared-transaction coordinator owner for a connection.
+   * Browser runtimes never install the Node test broker.
+   * @param {object} _connection - Parent physical connection.
+   * @returns {symbol | undefined} - Active coordinator owner.
+   */
+  getSharedTransactionCoordinatorOwner(_connection) { return undefined }
+
+  /**
+   * Runs work as the current shared-transaction coordinator owner.
+   * @template T
+   * @param {object} _connection - Parent physical connection.
+   * @param {symbol} _owner - Coordinator owner.
+   * @param {() => T} callback - Owned work.
+   * @returns {T} - Callback result.
+   */
+  runWithSharedTransactionCoordinatorOwner(_connection, _owner, callback) { return callback() }
+
   /**
    * Mutable ambient tenant used by runtimes without async-context storage.
    * @type {ReturnType<typeof JSON.parse> | undefined}

package/build/environment-handlers/node.js

@@ -80,6 +80,38 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @type {import("node:async_hooks").AsyncLocalStorage<TimezoneStore> | undefined} */
   _timezoneAsyncLocalStorage = NodeAsyncLocalStorage ? new NodeAsyncLocalStorage() : undefined
 
+  /**
+   * Shared-transaction coordinator ownership by physical connection.
+   * @type {import("node:async_hooks").AsyncLocalStorage<Map<object, symbol>> | undefined}
+   */
+  _sharedTransactionCoordinatorAsyncLocalStorage = NodeAsyncLocalStorage ? new NodeAsyncLocalStorage() : undefined
+
+  /**
+   * Gets the active shared-transaction coordinator owner for a connection.
+   * @param {object} connection - Parent physical connection.
+   * @returns {symbol | undefined} - Active coordinator owner.
+   */
+  getSharedTransactionCoordinatorOwner(connection) {
+    return this._sharedTransactionCoordinatorAsyncLocalStorage?.getStore()?.get(connection)
+  }
+
+  /**
+   * Runs work as the current shared-transaction coordinator owner.
+   * @template T
+   * @param {object} connection - Parent physical connection.
+   * @param {symbol} owner - Coordinator owner.
+   * @param {() => T} callback - Owned work.
+   * @returns {T} - Callback result.
+   */
+  runWithSharedTransactionCoordinatorOwner(connection, owner, callback) {
+    if (!this._sharedTransactionCoordinatorAsyncLocalStorage) return callback()
+
+    const owners = new Map(this._sharedTransactionCoordinatorAsyncLocalStorage.getStore())
+
+    owners.set(connection, owner)
+    return this._sharedTransactionCoordinatorAsyncLocalStorage.run(owners, callback)
+  }
+
   /**
    * Find commands result.
    * @type {import("./base.js").CommandFileObjectType[] | undefined} */

package/build/src/configuration-types.d.ts

@@ -154,7 +154,7 @@ export type DatabaseConfigurationType = {
      */
     migrations?: boolean;
     /**
-     * - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
+     * - (MySQL) Opt in to multi-statement queries so structure SQL loads and all-table cleanup can batch into one round-trip. Off by default; ordinary queries otherwise reject stacked statements.
      */
     multipleStatements?: boolean;
     /**
@@ -1660,7 +1660,7 @@ export type ConfigurationArgsType = {
  * @property {() => ReturnType<typeof JSON.parse>} [getConnection] - Custom connection factory override.
  * @property {string} [host] - Database host.
  * @property {boolean} [migrations] - Whether migrations are enabled for this database.
- * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so a whole structure SQL dump loads in one round-trip via `StructureSqlLoader`. Off by default; ordinary queries otherwise reject stacked statements.
+ * @property {boolean} [multipleStatements] - (MySQL) Opt in to multi-statement queries so structure SQL loads and all-table cleanup can batch into one round-trip. Off by default; ordinary queries otherwise reject stacked statements.
  * @property {number} [maxRowsPerInsert] - Maximum rows per `INSERT ... VALUES (...), (...), ...` statement generated by `Record.insertMultiple`. Defaults to 500.
  * @property {number} [maxInsertSqlBytes] - Maximum serialized SQL size, in bytes, for a single `INSERT ... VALUES (...), (...), ...` statement. Defaults to 1 MiB (1048576).
  * @property {number} [maxInClauseValues] - Maximum values in a single `IN (...)` cohort used by preloads, association counts, and queryData aggregates. Defaults to 999.