velocious 1.0.568 → 1.0.569

package/build/database/drivers/sqlite/connection-sql-js.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import debounce from "debounce"
+import Mutex from "epic-locks/build/mutex.js"
 import queryWeb from "./query.web.js"
 
 export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
@@ -12,6 +13,9 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
    */
   constructor(driver, connection, persistence) {
     this.connection = connection
+    this.databaseSaveDeferred = false
+    this.databaseSaveMutex = new Mutex()
+    this.databaseTransactionStarting = false
     this.driver = driver
     this.persistence = persistence
   }
@@ -30,6 +34,54 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
     await this.saveDatabase()
   }
 
+  /**
+   * Flushes only when a mutation save is pending or was deferred by a transaction.
+   * @returns {Promise<void>} - Resolves when pending database bytes are stored.
+   */
+  async flushPendingDatabaseSave() {
+    if (!this.saveDatabaseDebounce.isPending && !this.databaseSaveDeferred) return
+
+    await this.flushDatabaseSave()
+  }
+
+  /**
+   * Drains active and queued persistence before atomically starting an outer transaction.
+   * @param {() => Promise<void>} callback - Starts the SQL transaction.
+   * @returns {Promise<void>} - Resolves after BEGIN succeeds.
+   */
+  async withTransactionStart(callback) {
+    if (this.saveDatabaseDebounce.isPending) {
+      this.saveDatabaseDebounce.clear()
+      this.databaseSaveDeferred = true
+    }
+
+    await this.databaseSaveMutex.sync(async () => {
+      if (this.databaseSaveDeferred) {
+        this.databaseSaveDeferred = false
+        const databaseContent = this.connection.export()
+
+        await this.persistence.save(databaseContent)
+      }
+
+      this.databaseTransactionStarting = true
+
+      try {
+        await callback()
+      } catch (error) {
+        this.databaseTransactionStarting = false
+        throw error
+      }
+    })
+  }
+
+  /**
+   * Marks successful outer transaction admission complete after driver state is updated.
+   * @returns {void}
+   */
+  completeTransactionStart() {
+    this.databaseTransactionStarting = false
+  }
+
   /**
    * Runs query.
    * @param {string} sql - SQL string.
@@ -59,9 +111,17 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
   }
 
   saveDatabase = async () => {
-    const databaseContent = this.connection.export()
+    await this.databaseSaveMutex.sync(async () => {
+      if (this.driver.insideTransaction() || this.databaseTransactionStarting) {
+        this.databaseSaveDeferred = true
+        return
+      }
+
+      this.databaseSaveDeferred = false
+      const databaseContent = this.connection.export()
 
-    await this.persistence.save(databaseContent)
+      await this.persistence.save(databaseContent)
+    })
   }
 
   saveDatabaseDebounce = debounce(this.saveDatabase, 500)

package/build/database/drivers/sqlite/index.web.js

@@ -64,6 +64,80 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
     }
   }
 
+  /**
+   * Starts an outer transaction after draining SQL.js persistence admission.
+   * @param {Pick<import("../base.js").QueryOptions, "operationOwner">} [options] - Transaction ownership.
+   * @returns {Promise<void>} - Resolves when the transaction starts.
+   */
+  async startTransaction(options = {}) {
+    if (!this.args?.getConnection) {
+      if (!this._connection) throw new Error("SQLite web connection has not been initialized")
+
+      try {
+        await super.startTransaction(options)
+      } finally {
+        this._connection.completeTransactionStart()
+      }
+
+      return
+    }
+
+    await super.startTransaction(options)
+  }
+
+  /**
+   * Coordinates SQL BEGIN with active and queued persistence exports.
+   * @param {Pick<import("../base.js").QueryOptions, "operationOwner">} [options] - Transaction ownership.
+   * @returns {Promise<void>} - Resolves when the transaction starts.
+   */
+  async _startTransactionAction(options = {}) {
+    if (!this.args?.getConnection) {
+      if (!this._connection) throw new Error("SQLite web connection has not been initialized")
+
+      await this._connection.withTransactionStart(async () => {
+        await super._startTransactionAction(options)
+      })
+
+      return
+    }
+
+    await super._startTransactionAction(options)
+  }
+
+  /**
+   * Commits and persists bytes after the outermost SQL.js transaction closes.
+   * @param {Pick<import("../base.js").QueryOptions, "operationOwner">} [options] - Transaction ownership.
+   * @returns {Promise<void>} - Resolves when committed bytes are persisted.
+   */
+  async commitTransaction(options = {}) {
+    const outermostTransaction = this._transactionsCount === 1
+
+    await super.commitTransaction(options)
+
+    if (outermostTransaction && !this.args?.getConnection) {
+      if (!this._connection) throw new Error("SQLite web connection has not been initialized")
+
+      await this._connection.flushPendingDatabaseSave()
+    }
+  }
+
+  /**
+   * Rolls back and persists bytes after the outermost SQL.js transaction closes.
+   * @param {Pick<import("../base.js").QueryOptions, "operationOwner">} [options] - Transaction ownership.
+   * @returns {Promise<void>} - Resolves when rolled-back bytes are persisted.
+   */
+  async rollbackTransaction(options = {}) {
+    const outermostTransaction = this._transactionsCount === 1
+
+    await super.rollbackTransaction(options)
+
+    if (outermostTransaction && !this.args?.getConnection) {
+      if (!this._connection) throw new Error("SQLite web connection has not been initialized")
+
+      await this._connection.flushPendingDatabaseSave()
+    }
+  }
+
   /**
    * Runs get connection.
    * @returns {ConnectionSqlJs | SqliteWebConnection} - The connection.

package/build/database/operation-connection.js

@@ -0,0 +1,110 @@
+// @ts-check
+
+/**
+ * Explicit connection facade that tags operation-owned asynchronous work while
+ * forwarding the driver's synchronous SQL-builder and capability APIs.
+ */
+export default class VelociousDatabaseOperationConnection {
+  /**
+   * Runs constructor.
+   * @param {object} args - Connection ownership.
+   * @param {import("./drivers/base.js").default} args.connection - Pinned physical connection.
+   * @param {import("./operation.js").default} args.operation - Owning operation.
+   * @param {symbol} args.owner - Opaque lease owner token.
+   */
+  constructor({connection, operation, owner}) {
+    this._physicalConnection = connection
+    this._operation = operation
+    this._owner = owner
+
+    return new Proxy(this, {
+      get: (target, property, receiver) => {
+        if (Reflect.has(target, property)) {
+          const value = Reflect.get(target, property, receiver)
+
+          return typeof value === "function" ? value.bind(target) : value
+        }
+
+        const value = Reflect.get(connection, property, receiver)
+
+        return typeof value === "function" ? value.bind(receiver) : value
+      },
+      set: (target, property, value, receiver) => {
+        if (Reflect.has(target, property)) {
+          return Reflect.set(target, property, value, receiver)
+        }
+
+        return Reflect.set(connection, property, value, connection)
+      }
+    })
+  }
+
+  /**
+   * Runs a tagged SQL query on the pinned connection.
+   * @param {string} sql - SQL string.
+   * @param {import("./drivers/base.js").QueryOptions} [options] - Query options.
+   * @returns {Promise<import("./drivers/base.js").QueryResultType>} - Query result.
+   */
+  async query(sql, options = {}) {
+    this._operation.assertActive()
+
+    return await this._physicalConnection.query(sql, {...options, operationOwner: this._owner})
+  }
+
+  /**
+   * Streams an operation-owned SQL query.
+   * @param {string} sql - SQL string.
+   * @param {import("./drivers/base.js").QueryOptions} [options] - Query options.
+   * @yields {Record<string, unknown>} - Query rows.
+   */
+  async *queryStream(sql, options = {}) {
+    this._operation.assertActive()
+
+    yield* this._physicalConnection.queryStream(sql, {...options, operationOwner: this._owner})
+  }
+
+  /**
+   * Executes an operation-owned mutation and returns its affected row count.
+   * @param {string} sql - Mutation SQL string.
+   * @param {import("./drivers/base.js").QueryOptions} [options] - Query options.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async affectedRows(sql, options = {}) {
+    this._operation.assertActive()
+
+    return await this._physicalConnection.affectedRows(sql, {...options, operationOwner: this._owner})
+  }
+
+  /**
+   * Runs an operation-owned transaction or nested savepoint.
+   * @template T
+   * @param {() => Promise<T>} callback - Transaction callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async transaction(callback) {
+    this._operation.assertActive()
+
+    return /** @type {Promise<T>} */ (this._physicalConnection.transaction(callback, {operationOwner: this._owner}))
+  }
+
+  /**
+   * Registers an operation-owned after-commit callback.
+   * @param {() => void | Promise<void>} callback - Callback.
+   * @returns {Promise<void>} - Resolves after registration or execution.
+   */
+  async afterCommit(callback) {
+    this._operation.assertActive()
+
+    await this._physicalConnection.afterCommit(callback, {operationOwner: this._owner})
+  }
+
+  /**
+   * Returns the last inserted identifier through the operation lease.
+   * @returns {Promise<number>} - Last inserted identifier.
+   */
+  async lastInsertID() {
+    this._operation.assertActive()
+
+    return await this._physicalConnection.lastInsertID({operationOwner: this._owner})
+  }
+}

package/build/database/operation-lease.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+/**
+ * Exclusive lease installed on a shared physical connection while one
+ * operation-scoped transaction owns it.
+ */
+export default class VelociousDatabaseOperationLease {
+  /**
+   * Runs constructor.
+   * @param {symbol} owner - Opaque operation owner token.
+   */
+  constructor(owner) {
+    this.owner = owner
+    this.released = false
+    /**
+     * Resolves the lease waiters.
+     * @type {() => void} */
+    let release = () => {}
+
+    this.releasedPromise = new Promise((resolve) => {
+      release = () => resolve(undefined)
+    })
+    this.releasePromise = release
+  }
+
+  /**
+   * Waits until the lease is released unless `owner` owns it.
+   * @param {symbol | undefined} owner - Candidate operation owner.
+   * @returns {Promise<void>} - Resolves when access is allowed.
+   */
+  async wait(owner) {
+    if (owner === this.owner) return
+
+    await this.releasedPromise
+  }
+
+  /**
+   * Releases all waiters exactly once.
+   * @returns {void}
+   */
+  release() {
+    if (this.released) return
+
+    this.released = true
+    this.releasePromise()
+  }
+}

package/build/database/operation.js

@@ -0,0 +1,140 @@
+// @ts-check
+
+import OperationConnection from "./operation-connection.js"
+
+/**
+ * Explicit owner for model work performed on one pinned transactional
+ * connection.
+ */
+export default class VelociousDatabaseOperation {
+  /**
+   * Runs constructor.
+   * @param {object} args - Operation ownership.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {string} args.configurationReuseKey - Physical database configuration key captured at checkout.
+   * @param {import("./drivers/base.js").default} args.connection - Pinned physical connection.
+   * @param {string} args.databaseIdentifier - Singular database identifier.
+   * @param {symbol} args.owner - Opaque pool lease owner.
+   */
+  constructor({configuration, configurationReuseKey, connection, databaseIdentifier, owner}) {
+    this._active = true
+    this._configuration = configuration
+    this._configurationReuseKey = configurationReuseKey
+    this._databaseIdentifier = databaseIdentifier
+    this._connection = new OperationConnection({
+      connection,
+      operation: this,
+      owner
+    })
+  }
+
+  /**
+   * Returns an operation-bound model query/create scope.
+   * @template {typeof import("./record/index.js").default} MC
+   * @param {MC} ModelClass - Model class to bind.
+   * @returns {import("./query/model-class-query.js").default<MC>} - Operation-bound scope.
+   */
+  forModel(ModelClass) {
+    this.assertActive()
+    this.assertModel(ModelClass)
+
+    return ModelClass._newQuery({
+      driver: this.connection(),
+      operation: this
+    })
+  }
+
+  /**
+   * Verifies that a model belongs to this operation's configuration and database.
+   * @param {typeof import("./record/index.js").default} ModelClass - Model class to verify.
+   * @returns {void}
+   */
+  assertModel(ModelClass) {
+    if (ModelClass._getConfiguration() !== this._configuration) {
+      throw new Error(`${ModelClass.getModelName()} belongs to another Velocious configuration`)
+    }
+
+    const modelDatabaseIdentifier = ModelClass.getDatabaseIdentifier()
+
+    if (modelDatabaseIdentifier !== this._databaseIdentifier) {
+      throw new Error(`${ModelClass.getModelName()} uses database ${JSON.stringify(modelDatabaseIdentifier)}, not operation database ${JSON.stringify(this._databaseIdentifier)}`)
+    }
+  }
+
+  /**
+   * Binds a loaded or built record to this operation.
+   * @template {import("./record/index.js").default} Model
+   * @param {Model} record - Record to bind.
+   * @returns {Model} - Bound record.
+   */
+  bindRecord(record) {
+    this.assertActive()
+    this.assertModel(record.getModelClass())
+    record.bindDatabaseOperation(this)
+
+    return record
+  }
+
+  /**
+   * Registers a callback owned by the current operation transaction frame.
+   * @param {() => void | Promise<void>} callback - Callback.
+   * @returns {Promise<void>} - Resolves after registration or execution.
+   */
+  async afterCommit(callback) {
+    this.assertActive()
+    await this.connection().afterCommit(callback)
+  }
+
+  /**
+   * Runs a nested operation transaction/savepoint.
+   * @template T
+   * @param {() => Promise<T>} callback - Callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async transaction(callback) {
+    this.assertActive()
+
+    return await this.connection().transaction(callback)
+  }
+
+  /**
+   * Returns the deliberately exposed operation connection facade for raw SQL.
+   * @returns {import("./drivers/base.js").default} - Operation-bound connection.
+   */
+  connection() {
+    this.assertActive()
+
+    /**
+     * Narrows the Proxy facade to the complete driver surface that it forwards.
+     * @type {import("./drivers/base.js").default}
+     */
+    const connectionFacade = /** @type {?} */ (this._connection)
+
+    return connectionFacade
+  }
+
+  /**
+   * Raises when an operation handle has left its callback.
+   * @returns {void}
+   */
+  assertActive() {
+    if (!this._active) throw new Error("Database operation has completed")
+
+    const currentReuseKey = this
+      ._configuration
+      .getDatabasePool(this._databaseIdentifier)
+      .getConfigurationReuseKey()
+
+    if (currentReuseKey !== this._configurationReuseKey) {
+      throw new Error(`Database operation for ${JSON.stringify(this._databaseIdentifier)} belongs to a different physical database than the current tenant context`)
+    }
+  }
+
+  /**
+   * Expires the operation and all scopes/records bound to it.
+   * @returns {void}
+   */
+  complete() {
+    this._active = false
+  }
+}

package/build/database/pool/base.js

@@ -241,9 +241,21 @@ class VelociousDatabasePoolBase {
    * @returns {boolean} - Whether connection matches current resolved configuration.
    */
   connectionMatchesCurrentConfiguration(connection) {
+    return this.getConnectionConfigurationReuseKey(connection) === this.getConfigurationReuseKey()
+  }
+
+  /**
+   * Returns the resolved database configuration key stamped on a connection at checkout.
+   * @param {import("../drivers/base.js").default} connection - Checked-out connection.
+   * @returns {string} - Connection configuration reuse key.
+   */
+  getConnectionConfigurationReuseKey(connection) {
     const connectionWithPoolKey = /** @type {import("../drivers/base.js").default & {[POOL_CONFIGURATION_KEY]?: string}} */ (connection)
+    const reuseKey = connectionWithPoolKey[POOL_CONFIGURATION_KEY]
+
+    if (!reuseKey) throw new Error("Database connection is missing its configuration reuse key")
 
-    return connectionWithPoolKey[POOL_CONFIGURATION_KEY] === this.getConfigurationReuseKey()
+    return reuseKey
   }
 
   /**
@@ -357,6 +369,19 @@ class VelociousDatabasePoolBase {
     throw new Error("'withConnection' not implemented")
   }
 
+  /**
+   * Runs an operation on a freshly checked-out connection.
+   * @template T
+   * @param {ConnectionCheckoutOptions} options - Checkout options.
+   * @param {(connection: import("../drivers/base.js").default, owner: symbol) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withOperationConnection(options, callback) {
+    const owner = Symbol("database-operation-owner")
+
+    return await this.withConnection(options, async (connection) => await callback(connection, owner))
+  }
+
   /**
    * Ensures a reusable connection exists for contexts where AsyncLocalStorage isn't set.
    * Default implementation just checks out a connection.

package/build/database/pool/single-multi-use.js

@@ -1,10 +1,12 @@
 // @ts-check
 
 import BasePool from "./base.js"
+import OperationLease from "../operation-lease.js"
 
 export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
   activeCheckoutCount = 0
   suppressedConnectionContextCount = 0
+  operationLeaseQueue = Promise.resolve()
 
   /**
    * Checkout names of the currently-active nested checkouts, innermost last. The
@@ -107,6 +109,53 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
     }
   }
 
+  /**
+   * Runs an operation under an exclusive FIFO lease on the reusable physical connection.
+   * @template T
+   * @param {import("./base.js").ConnectionCheckoutOptions} options - Checkout options.
+   * @param {(connection: import("../drivers/base.js").default, owner: symbol) => Promise<T>} callback - Operation callback.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withOperationConnection(options, callback) {
+    const previousLease = this.operationLeaseQueue
+    /**
+     * Resolves this FIFO queue turn.
+     * @type {() => void} */
+    let releaseQueue = () => {}
+    const queueTurn = new Promise((resolve) => {
+      releaseQueue = () => resolve(undefined)
+    })
+
+    this.operationLeaseQueue = previousLease.then(async () => await queueTurn)
+    await previousLease
+
+    const owner = Symbol("single-pool-operation-owner")
+    const operationLease = new OperationLease(owner)
+    /** @type {import("../drivers/base.js").default | undefined} */
+    let connection
+    let operationLeaseInstalled = false
+
+    try {
+      connection = await this.checkout(options)
+      await connection.setOperationLease(operationLease)
+      operationLeaseInstalled = true
+
+      return await callback(connection, owner)
+    } finally {
+      operationLease.release()
+
+      try {
+        if (connection && operationLeaseInstalled) connection.clearOperationLease(operationLease)
+      } finally {
+        try {
+          if (connection) await this.checkin(connection)
+        } finally {
+          releaseQueue()
+        }
+      }
+    }
+  }
+
   /**
    * Runs without current connection context.
    * @template T

package/build/database/query/model-class-query.js

@@ -24,7 +24,7 @@ import WhereParser from "../query-parser/where-parser.js"
 /**
  * Defines this typedef.
  * @template {typeof import("../record/index.js").default} [MC=typeof import("../record/index.js").default]
- * @typedef {import("./index.js").QueryArgsType & {modelClass: MC, joinBasePath?: string[], joinTracker?: import("./join-tracker.js").default, forceQualifyBaseTable?: boolean, withCount?: import("./with-count.js").WithCountEntry[], queryData?: import("./query-data.js").QueryDataEntry[]}} ModelClassQueryArgsType
+ * @typedef {import("./index.js").QueryArgsType & {modelClass: MC, joinBasePath?: string[], joinTracker?: import("./join-tracker.js").default, forceQualifyBaseTable?: boolean, withCount?: import("./with-count.js").WithCountEntry[], queryData?: import("./query-data.js").QueryDataEntry[], operation?: import("../operation.js").default}} ModelClassQueryArgsType
  */
 /**
  * Runs unquote sql identifier.
@@ -200,6 +200,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     this._joinBasePath = args.joinBasePath || []
     this._joinTracker = args.joinTracker || new JoinTracker({modelClass: this.modelClass})
     this._forceQualifyBaseTable = Boolean(args.forceQualifyBaseTable)
+    this._operation = args.operation
 
     /**
      * Narrows the runtime value to the documented type.
@@ -240,7 +241,8 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       joinTracker: this._joinTracker.clone(),
       forceQualifyBaseTable: this._forceQualifyBaseTable,
       withCount: [...this._withCount],
-      queryData: [...this._queryData]
+      queryData: [...this._queryData],
+      operation: this._operation
     }))
 
     // @ts-expect-error
@@ -723,7 +725,11 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
    * @returns {VelociousDatabaseQueryModelClassQuery<MC>} - The scoped join query.
    */
   buildJoinScopeQuery(targetModelClass, joinPath) {
-    const scopedQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (targetModelClass._newQuery())
+    const scopedQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (
+      this._operation
+        ? this._operation.forModel(targetModelClass)
+        : targetModelClass._newQuery()
+    )
 
     scopedQuery._joinTracker = this._joinTracker
     scopedQuery._joinBasePath = joinPath
@@ -864,8 +870,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
     if (record) return record
 
-    const ModelClass = this.getModelClass()
-    const newRecord = /** @type {InstanceType<MC>} */ (new ModelClass(conditions))
+    const newRecord = this.build(conditions)
 
     if (callback) {
       callback(newRecord)
@@ -874,6 +879,33 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     return newRecord
   }
 
+  /**
+   * Builds a record owned by the query's operation, when present.
+   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @returns {InstanceType<MC>} - Built record.
+   */
+  build(attributes = {}) {
+    const ModelClass = this.getModelClass()
+    const record = /** @type {InstanceType<MC>} */ (new ModelClass(attributes))
+
+    if (this._operation) this._operation.bindRecord(record)
+
+    return record
+  }
+
+  /**
+   * Creates a record owned by the query's operation, when present.
+   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @returns {Promise<InstanceType<MC>>} - Created record.
+   */
+  async create(attributes = {}) {
+    const record = this.build(attributes)
+
+    await record.save()
+
+    return record
+  }
+
   /**
    * Runs first.
    * @returns {Promise<InstanceType<MC> | null>} - Resolves with the first.
@@ -917,8 +949,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     const results = await this.results()
 
     for (const result of results) {
-      const ModelClass = this.getModelClass()
-      const model = /** @type {InstanceType<MC>} */ (new ModelClass())
+      const model = this.build()
 
       model.loadExistingRecord(result)
       models.push(model)