velocious 1.0.577 → 1.0.579

package/build/database/record/auditing.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import UUID from "pure-uuid"
+import HasManyRelationship from "./relationships/has-many.js"
 
 /**
  * Global audit event bus matching ActiveRecordAuditable::Events.
@@ -11,7 +12,7 @@ import UUID from "pure-uuid"
  */
 /**
  * AuditChanges type.
- * @typedef {Record<string, ?>} AuditChanges
+ * @typedef {Record<string, ReturnType<typeof JSON.parse>>} AuditChanges
  */
 
 /**
@@ -20,7 +21,7 @@ import UUID from "pure-uuid"
  * @property {string} action - Audit action name.
  * @property {number | string} auditId - Created audit row id.
  * @property {AuditChanges | null} auditedChanges - Changes captured for the audit.
- * @property {Record<string, ?> | null} params - Optional caller-supplied audit params.
+ * @property {Record<string, ReturnType<typeof JSON.parse>> | null} params - Optional caller-supplied audit params.
  * @property {import("./index.js").default} record - Audited record.
  */
 
@@ -34,7 +35,7 @@ import UUID from "pure-uuid"
  * @typedef {object} CreateAuditArgs
  * @property {string} action - Audit action name.
  * @property {AuditChanges | null} [auditedChanges] - Explicit changes to persist.
- * @property {Record<string, ?> | null} [params] - Optional metadata to store with the audit.
+ * @property {Record<string, ReturnType<typeof JSON.parse>> | null} [params] - Optional metadata to store with the audit.
  */
 
 /**
@@ -56,14 +57,20 @@ import UUID from "pure-uuid"
  * @property {typeof import("./index.js").default} auditClass - The audit model class to use.
  */
 
-/** @type {Map<string, boolean>} */
-const dedicatedTableCache = new Map()
+/** @type {WeakMap<import("../../configuration.js").default, Map<string, boolean>>} */
+const dedicatedTableCacheByConfiguration = new WeakMap()
+
+/** @type {WeakMap<AuditedModelClass, Map<string, AuditTableData>>} */
+const auditTableDataByModel = new WeakMap()
 
 /** @type {Map<string, typeof import("./index.js").default>} */
 const auditClassCache = new Map()
 
 const generatedAuditRelationships = new WeakSet()
 
+/** @type {WeakMap<AuditedModelClass, Map<string, HasManyRelationship>>} */
+const auditRelationshipsByModel = new WeakMap()
+
 // ---------------------------------------------------------------------------
 // Global event bus (like ActiveRecordAuditable::Events)
 // ---------------------------------------------------------------------------
@@ -149,15 +156,27 @@ function dedicatedAuditTableName(modelClass) {
  * Called lazily on first createAudit / withoutAudit / relationship usage.
  * @param {AuditedModelClass} modelClass - Audited model class.
  * @param {import("../drivers/base.js").default} [connection] - Explicit record-owned connection.
+ * @param {import("../operation.js").default} [operation] - Explicit record operation.
  * @returns {Promise<AuditTableData>} Resolved audit table metadata.
  */
-async function resolveAuditTableData(modelClass, connection) {
-  if (modelClass._auditTableResolved && modelClass._auditTableData) {
-    return modelClass._auditTableData
+async function resolveAuditTableData(modelClass, connection, operation) {
+  const resolvedConnection = connection || modelClass.connection()
+  const databaseIdentity = auditDatabaseIdentity(modelClass, resolvedConnection, operation)
+  let tableDataByIdentity = auditTableDataByModel.get(modelClass)
+
+  if (!tableDataByIdentity) {
+    tableDataByIdentity = new Map()
+    auditTableDataByModel.set(modelClass, tableDataByIdentity)
   }
 
-  const resolvedConnection = connection || modelClass.connection()
-  const tableData = await buildAuditTableData(modelClass, resolvedConnection)
+  const cachedTableData = tableDataByIdentity.get(databaseIdentity)
+
+  if (cachedTableData) {
+    registerAuditRelationship(modelClass, cachedTableData, databaseIdentity)
+    return cachedTableData
+  }
+
+  const tableData = await buildAuditTableData(modelClass, resolvedConnection, databaseIdentity)
   const configuration = modelClass._getConfiguration()
 
   tableData.auditClass.registerRecordClass({configuration})
@@ -165,8 +184,9 @@ async function resolveAuditTableData(modelClass, connection) {
 
   modelClass._auditTableData = tableData
   modelClass._auditTableResolved = true
+  tableDataByIdentity.set(databaseIdentity, tableData)
 
-  registerAuditRelationship(modelClass, tableData)
+  registerAuditRelationship(modelClass, tableData, databaseIdentity)
 
   return tableData
 }
@@ -177,11 +197,12 @@ async function resolveAuditTableData(modelClass, connection) {
  * dynamic class.
  * @param {AuditedModelClass} modelClass - Audited model class.
  * @param {import("../drivers/base.js").default} connection - Explicit record-owned connection.
+ * @param {string} databaseIdentity - Captured physical database identity.
  * @returns {Promise<AuditTableData>} Audit table metadata.
  */
-async function buildAuditTableData(modelClass, connection) {
+async function buildAuditTableData(modelClass, connection, databaseIdentity) {
   const dedicatedTable = dedicatedAuditTableName(modelClass)
-  const dedicatedExists = await dedicatedTableExistsForConnection(modelClass, dedicatedTable, connection)
+  const dedicatedExists = await dedicatedTableExistsForConnection(modelClass, dedicatedTable, connection, databaseIdentity)
 
   if (dedicatedExists) {
     const auditClass = dedicatedAuditClass(modelClass, dedicatedTable)
@@ -218,14 +239,22 @@ async function buildAuditTableData(modelClass, connection) {
 
 /**
  * Checks whether a dedicated audit table exists for a model's connection.
- * @param {AuditedModelClass} modelClass - Audited model class.
+ * @param {AuditedModelClass} modelClass - Audited model class owning the Configuration.
  * @param {string} tableName - Dedicated audit table name to check.
  * @param {import("../drivers/base.js").default} connection - Explicit record-owned connection.
+ * @param {string} databaseIdentity - Captured physical database identity.
  * @returns {Promise<boolean>} Whether the table exists.
  */
-async function dedicatedTableExistsForConnection(modelClass, tableName, connection) {
-  const databaseIdentifier = modelClass.getDatabaseIdentifier()
-  const cacheKey = `${databaseIdentifier}:${tableName}`
+async function dedicatedTableExistsForConnection(modelClass, tableName, connection, databaseIdentity) {
+  const configuration = modelClass._getConfiguration()
+  const cacheKey = `${databaseIdentity}:${tableName}`
+  let dedicatedTableCache = dedicatedTableCacheByConfiguration.get(configuration)
+
+  if (!dedicatedTableCache) {
+    dedicatedTableCache = new Map()
+    dedicatedTableCacheByConfiguration.set(configuration, dedicatedTableCache)
+  }
+
   const cached = dedicatedTableCache.get(cacheKey)
 
   if (typeof cached === "boolean") {
@@ -240,6 +269,24 @@ async function dedicatedTableExistsForConnection(modelClass, tableName, connecti
   return exists
 }
 
+/**
+ * Resolves a cache identity from explicit operation ownership or the actual
+ * stamped pool connection. Ambient tenant state is never used when an
+ * operation is available.
+ * @param {AuditedModelClass} modelClass - Audited model class.
+ * @param {import("../drivers/base.js").default} connection - Actual connection.
+ * @param {import("../operation.js").default} [operation] - Explicit operation.
+ * @returns {string} - Physical database identity.
+ */
+function auditDatabaseIdentity(modelClass, connection, operation) {
+  if (operation) return operation.databaseIdentity()
+
+  const databaseIdentifier = modelClass.getDatabaseIdentifier()
+  const pool = modelClass._getConfiguration().getDatabasePool(databaseIdentifier)
+
+  return `${databaseIdentifier}:${pool.getConnectionConfigurationReuseKey(connection)}`
+}
+
 // ---------------------------------------------------------------------------
 // Dynamic audit classes
 // ---------------------------------------------------------------------------
@@ -452,19 +499,15 @@ function shouldResolveAuditTableData(modelClass) {
  * Registers the audits relationship without forcing audit table detection.
  * @param {AuditedModelClass} modelClass - Model class to audit.
  * @param {AuditTableData} [tableData] - Resolved audit table data when available.
+ * @param {string} [databaseIdentity] - Resolved physical database identity.
  * @returns {void}
  */
-function registerAuditRelationship(modelClass, tableData = defaultAuditRelationshipTableData(modelClass)) {
+function registerAuditRelationship(modelClass, tableData = defaultAuditRelationshipTableData(modelClass), databaseIdentity) {
   if (modelClass._relationshipExists("audits")) {
     const relationship = modelClass.getRelationshipByName("audits")
 
-    if (generatedAuditRelationships.has(relationship)) {
-      relationship.className = undefined
-      relationship.klass = tableData.auditClass
-      relationship.foreignKey = tableData.foreignKey
-      relationship._explicitForeignKey = tableData.foreignKey
-      relationship._polymorphic = !tableData.dedicated
-      relationship._polymorphicTypeColumn = undefined
+    if (generatedAuditRelationships.has(relationship) && databaseIdentity) {
+      auditRelationshipMap(modelClass).set(databaseIdentity, buildAuditRelationship(modelClass, tableData))
     }
 
     return
@@ -475,7 +518,54 @@ function registerAuditRelationship(modelClass, tableData = defaultAuditRelations
     klass: tableData.auditClass,
     polymorphic: !tableData.dedicated
   })
-  generatedAuditRelationships.add(modelClass.getRelationshipByName("audits"))
+  const relationship = modelClass.getRelationshipByName("audits")
+
+  generatedAuditRelationships.add(relationship)
+  relationship.setRecordResolver((record) => {
+    const relationships = auditRelationshipMap(modelClass)
+    const operation = record.databaseOperation()
+
+    if (operation) return relationships.get(operation.databaseIdentity()) || relationship
+    if (relationships.size === 1) return [...relationships.values()][0]
+
+    const identity = auditDatabaseIdentity(modelClass, record.connection())
+
+    return relationships.get(identity) || relationship
+  })
+}
+
+/**
+ * Returns physical audit relationship variants for a model.
+ * @param {AuditedModelClass} modelClass - Audited model class.
+ * @returns {Map<string, HasManyRelationship>} - Relationships keyed by physical database identity.
+ */
+function auditRelationshipMap(modelClass) {
+  let relationships = auditRelationshipsByModel.get(modelClass)
+
+  if (!relationships) {
+    relationships = new Map()
+    auditRelationshipsByModel.set(modelClass, relationships)
+  }
+
+  return relationships
+}
+
+/**
+ * Builds immutable-by-ownership audit relationship metadata for one physical database.
+ * @param {AuditedModelClass} modelClass - Audited model class.
+ * @param {AuditTableData} tableData - Resolved audit table data.
+ * @returns {HasManyRelationship} - Physical relationship definition.
+ */
+function buildAuditRelationship(modelClass, tableData) {
+  return new HasManyRelationship({
+    foreignKey: tableData.foreignKey,
+    klass: tableData.auditClass,
+    modelClass,
+    polymorphic: !tableData.dedicated,
+    relationshipName: "audits",
+    scope: auditRelationshipScope,
+    type: "hasMany"
+  })
 }
 
 /**
@@ -532,6 +622,9 @@ function canResolveAuditTableData(modelClass) {
  */
 async function createAudit(record, args) {
   const modelClass = /** @type {AuditedModelClass} */ (record.getModelClass())
+  const operation = record.databaseOperation()
+
+  if (operation) return await createAuditWithCurrentConnection(record, args, modelClass)
 
   return await modelClass._getConfiguration().ensureConnections({name: `${modelClass.getModelName()} audit`}, async () => {
     return await createAuditWithCurrentConnection(record, args, modelClass)
@@ -550,7 +643,7 @@ async function createAuditWithCurrentConnection(record, args, modelClass) {
   if (!record.isPersisted()) throw new Error(`Cannot audit unpersisted ${modelClass.getModelName()} record`)
 
   const db = record.connection()
-  const tableData = await resolveAuditTableData(modelClass, db)
+  const tableData = await resolveAuditTableData(modelClass, db, record.databaseOperation())
   const action = normalizeAction(args.action)
   const auditedChanges = args.auditedChanges === undefined ? null : args.auditedChanges
   const params = args.params === undefined ? null : args.params
@@ -739,14 +832,15 @@ function auditChangesForDestroy(record) {
  */
 function withoutAudit(modelClass, action) {
   const db = modelClass.connection()
+  const databaseIdentity = auditDatabaseIdentity(modelClass, db)
+  const tableData = auditTableDataByModel.get(modelClass)?.get(databaseIdentity)
   const modelTableSql = db.quoteTable(modelClass.tableName())
   const auditActionsTableSql = db.quoteTable("audit_actions")
   const modelPrimaryKeySql = `${modelTableSql}.${db.quoteColumn(modelClass.primaryKey())}`
   const auditActionsIdSql = `${auditActionsTableSql}.${db.quoteColumn("id")}`
   const auditActionsActionSql = `${auditActionsTableSql}.${db.quoteColumn("action")}`
 
-  if (modelClass._auditTableResolved && modelClass._auditTableData?.dedicated) {
-    const tableData = modelClass._auditTableData
+  if (tableData?.dedicated) {
     const modelKey = modelParamKey(modelClass)
     const auditsTableSql = db.quoteTable(tableData.tableName)
     const auditActionIdSql = `${auditsTableSql}.${db.quoteColumn("audit_action_id")}`

package/build/database/record/counter-cache-magnitude.js

@@ -20,13 +20,13 @@
  *   belongsTo: string,
  *   counterColumn: string,
  *   sourceAttribute: string,
- *   magnitude: (sourceValue: ?) => number
+ *   magnitude: (sourceValue: ReturnType<typeof JSON.parse>) => number
  * }} MagnitudeCounterCacheDefinition
  */
 
 /**
  * Captured pending magnitude change stashed on a record between beforeSave and afterSave.
- * @typedef {{newMagnitude: number, oldMagnitude: number, newParentId: ?, oldParentId: ?}} PendingMagnitudeDelta
+ * @typedef {{newMagnitude: number, oldMagnitude: number, newParentId: ReturnType<typeof JSON.parse>, oldParentId: ReturnType<typeof JSON.parse>}} PendingMagnitudeDelta
  */
 
 /**
@@ -38,7 +38,7 @@
 export function registerMagnitudeCounterCache(modelClass, definition) {
   /**
    * Dynamic class.
-   * @type {?} */
+   * @type {ReturnType<typeof JSON.parse>} */
   const dynamicClass = modelClass
   const registeredFlag = `_magnitudeCounterCacheRegistered_${definition.counterColumn}`
 
@@ -54,7 +54,7 @@ export function registerMagnitudeCounterCache(modelClass, definition) {
   modelClass.beforeSave(async function (record) {
     /**
      * Dynamic record.
-     * @type {?} */
+     * @type {ReturnType<typeof JSON.parse>} */
     const dynamicRecord = record
 
     dynamicRecord[pendingKey] = computePendingMagnitudeDelta(record, definition)
@@ -63,7 +63,7 @@ export function registerMagnitudeCounterCache(modelClass, definition) {
   modelClass.afterSave(async function (record) {
     /**
      * Dynamic record.
-     * @type {?} */
+     * @type {ReturnType<typeof JSON.parse>} */
     const dynamicRecord = record
     const pending = /** @type {PendingMagnitudeDelta | null} */ (dynamicRecord[pendingKey])
 
@@ -151,9 +151,9 @@ async function applyPendingMagnitudeDelta(record, definition, pending) {
  * @param {import("./index.js").default} record - Record being saved.
  * @param {string} sourceAttribute - Source attribute name.
  * @param {string} sourceColumn - Source column name.
- * @param {Record<string, ?>} changes - The record's pre-save changes (column-keyed).
- * @param {?} currentValue - The current (new) read value, returned when the source did not change.
- * @returns {?} The read-cast pre-save value.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} changes - The record's pre-save changes (column-keyed).
+ * @param {ReturnType<typeof JSON.parse>} currentValue - The current (new) read value, returned when the source did not change.
+ * @returns {ReturnType<typeof JSON.parse>} The read-cast pre-save value.
  */
 function oldSourceValueThroughReadCast(record, sourceAttribute, sourceColumn, changes, currentValue) {
   if (!(sourceColumn in changes)) {
@@ -162,7 +162,7 @@ function oldSourceValueThroughReadCast(record, sourceAttribute, sourceColumn, ch
 
   /**
    * Dynamic record.
-   * @type {?} */
+   * @type {ReturnType<typeof JSON.parse>} */
   const dynamicRecord = record
   const pendingChange = dynamicRecord._changes[sourceColumn]
 
@@ -179,7 +179,7 @@ function oldSourceValueThroughReadCast(record, sourceAttribute, sourceColumn, ch
  * Reads the record's current foreign-key value for the counter-cache parent.
  * @param {import("./index.js").default} record - Record whose parent is targeted.
  * @param {MagnitudeCounterCacheDefinition} definition - Counter cache definition.
- * @returns {?} The current foreign-key value.
+ * @returns {ReturnType<typeof JSON.parse>} The current foreign-key value.
  */
 function currentParentId(record, definition) {
   const foreignKeyColumn = record.getModelClass().getRelationshipByName(definition.belongsTo).getForeignKey()
@@ -191,7 +191,7 @@ function currentParentId(record, definition) {
  * Atomically adds `amount` to the parent's counter column for one parent row.
  * @param {import("./index.js").default} record - Child record (for connection + relationship metadata).
  * @param {MagnitudeCounterCacheDefinition} definition - Counter cache definition.
- * @param {?} parentId - Parent primary-key value.
+ * @param {ReturnType<typeof JSON.parse>} parentId - Parent primary-key value.
  * @param {number} amount - Signed integer to add.
  * @returns {Promise<void>}
  */