velocious 1.0.516 → 1.0.517

package/README.md

@@ -1930,6 +1930,8 @@ Create the file `src/routes/testing/another-action.ejs` and so something like th
 
 Velocious includes a simple background jobs system inspired by Sidekiq.
 
+Jobs can opt into cross-worker durable concurrency limits by pairing a non-empty `concurrencyKey` with a positive-integer `maxConcurrency` in their background-job options. The first cap registered for a key is stable; conflicting caps are rejected. See [durable concurrency limits](docs/background-jobs.md#durable-concurrency-limits).
+
 Production apps can listen for `background-job-failed` or its `all-error` mirror to report accepted failed attempts, including retry and terminal state metadata. See [docs/background-jobs.md](docs/background-jobs.md#failure-events).
 
 ## Setup

package/build/background-jobs/store.js

@@ -11,6 +11,7 @@ const MIGRATION_SCOPE = "background_jobs"
 const MIGRATION_VERSION = "20250215000000"
 const EXECUTION_MODE_BACKFILL_MIGRATION_VERSION = "20260607131010"
 const JOBS_TABLE = "background_jobs"
+const CONCURRENCY_TABLE = "background_job_concurrency"
 const DEFAULT_MAX_RETRIES = 10
 const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
 /**
@@ -94,8 +95,10 @@ export default class BackgroundJobsStore {
     const executionMode = this._normalizeExecutionMode(options)
     const maxRetries = this._normalizeMaxRetries(options?.maxRetries)
     const argsJson = JSON.stringify(args || [])
+    const concurrency = this._normalizeConcurrencyOptions(options)
 
     await this._withDb(async (db) => {
+      if (concurrency) await this._ensureConcurrencyKey(db, concurrency)
       await db.insert({
         tableName: JOBS_TABLE,
         data: {
@@ -108,7 +111,9 @@ export default class BackgroundJobsStore {
           attempts: 0,
           status: "queued",
           scheduled_at_ms: now,
-          created_at_ms: now
+          created_at_ms: now,
+          concurrency_key: concurrency?.concurrencyKey || null,
+          max_concurrency: concurrency?.maxConcurrency || null
         }
       })
     })
@@ -169,6 +174,17 @@ export default class BackgroundJobsStore {
       .where({status: "queued"})
       .where(`scheduled_at_ms ${scheduledAtOperator} ${db.quote(now)}`)
 
+    if (scheduledAtOperator === "<=") {
+      const jobsTable = db.quoteTable(JOBS_TABLE)
+      const concurrencyTable = db.quoteTable(CONCURRENCY_TABLE)
+      query = query.where(
+        `(${jobsTable}.${db.quoteColumn("concurrency_key")} IS NULL OR EXISTS (` +
+        `SELECT 1 FROM ${concurrencyTable} WHERE ` +
+        `${concurrencyTable}.${db.quoteColumn("concurrency_key")} = ${jobsTable}.${db.quoteColumn("concurrency_key")} AND ` +
+        `${concurrencyTable}.${db.quoteColumn("active_count")} < ${concurrencyTable}.${db.quoteColumn("max_concurrency")}))`
+      )
+    }
+
     if (typeof forked === "boolean") {
       query = query.where({forked})
     }
@@ -314,8 +330,12 @@ export default class BackgroundJobsStore {
     const handedOffAtMs = Date.now()
     const handoffId = randomUUID()
 
-    return await this._withDb(async (db) => {
-      await db.update({
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
+      const queuedJob = await this._getJobRowById(db, jobId)
+      if (!queuedJob || queuedJob.status !== "queued") return null
+      if (queuedJob.concurrencyKey && !(await this._reserveConcurrency(db, queuedJob.concurrencyKey))) return null
+
+      const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
         data: {
           status: "handed_off",
@@ -326,12 +346,13 @@ export default class BackgroundJobsStore {
         conditions: {id: jobId, status: "queued"}
       })
 
-      const job = await this._getJobRowById(db, jobId)
-
-      if (job?.status !== "handed_off" || job.handoffId !== handoffId) return null
+      if (affectedRows !== 1) {
+        await this._releaseConcurrency(db, queuedJob.concurrencyKey)
+        return null
+      }
 
       return {handedOffAtMs, handoffId}
-    })
+    }))
   }
 
   /**
@@ -346,13 +367,13 @@ export default class BackgroundJobsStore {
   async markCompleted({jobId, handoffId, workerId, handedOffAtMs}) {
     await this.ensureReady()
 
-    return await this._withDb(async (db) => await this._withHandoffLock({db, jobId}, async () => {
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
       const job = await this._getJobRowById(db, jobId)
 
       if (!job) return false
       if (!this._shouldAcceptReport({job, handoffId, workerId, handedOffAtMs})) return false
 
-      await db.update({
+      const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
         data: {
           status: "completed",
@@ -361,9 +382,9 @@ export default class BackgroundJobsStore {
         conditions: this._activeHandoffConditions(job)
       })
 
-      const updatedJob = await this._getJobRowById(db, jobId)
-
-      return updatedJob?.status === "completed" && updatedJob.handoffId === job.handoffId
+      if (affectedRows !== 1) return false
+      await this._releaseConcurrency(db, job.concurrencyKey)
+      return true
     }))
   }
 
@@ -377,8 +398,10 @@ export default class BackgroundJobsStore {
   async markReturnedToQueue({jobId, handoffId}) {
     await this.ensureReady()
 
-    await this._withDb(async (db) => {
-      await db.update({
+    await this._withDb(async (db) => await db.transaction(async () => {
+      const job = await this._getJobRowById(db, jobId)
+      if (!job || job.handoffId !== handoffId || job.status !== "handed_off") return
+      const affectedRows = await this._updateAffectedRows(db, {
         tableName: JOBS_TABLE,
         data: {
           status: "queued",
@@ -389,7 +412,8 @@ export default class BackgroundJobsStore {
         },
         conditions: {handoff_id: handoffId, id: jobId, status: "handed_off"}
       })
-    })
+      if (affectedRows === 1) await this._releaseConcurrency(db, job.concurrencyKey)
+    }))
   }
 
   /**
@@ -405,13 +429,14 @@ export default class BackgroundJobsStore {
   async markFailed({jobId, error, handoffId, workerId, handedOffAtMs}) {
     await this.ensureReady()
 
-    return await this._withDb(async (db) => await this._withHandoffLock({db, jobId}, async () => {
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
       const job = await this._getJobRowById(db, jobId)
 
       if (!job) return null
       if (!this._shouldAcceptReport({job, handoffId, workerId, handedOffAtMs})) return null
 
-      return await this._applyFailure({db, job, error, markOrphaned: false})
+      const updatedJob = await this._applyFailure({db, job, error, markOrphaned: false})
+      return updatedJob
     }))
   }
 
@@ -462,9 +487,27 @@ export default class BackgroundJobsStore {
 
     await this._withDb(async (db) => {
       await db.query(`DELETE FROM ${db.quoteTable(JOBS_TABLE)}`)
+      if (await db.tableExists(CONCURRENCY_TABLE)) await db.query(`DELETE FROM ${db.quoteTable(CONCURRENCY_TABLE)}`)
     })
   }
 
+  /**
+   * Cancels a queued or handed-off job and releases any durable concurrency reservation.
+   * @param {string} jobId - Job id.
+   * @returns {Promise<boolean>} - Whether the job was cancelled.
+   */
+  async cancel(jobId) {
+    await this.ensureReady()
+    return await this._withDb(async (db) => await this._transactionResult(db, async () => {
+      const job = await this._getJobRowById(db, jobId)
+      if (!job || (job.status !== "queued" && job.status !== "handed_off")) return false
+      const affectedRows = await this._updateAffectedRows(db, {tableName: JOBS_TABLE, data: {status: "cancelled"}, conditions: {id: job.id, status: job.status}})
+      if (affectedRows !== 1) return false
+      if (job.status === "handed_off") await this._releaseConcurrency(db, job.concurrencyKey)
+      return true
+    }))
+  }
+
   /**
    * Runs get retry delay ms.
    * @param {number} retryCount - Retry attempt count (1-based).
@@ -506,11 +549,15 @@ export default class BackgroundJobsStore {
       // row alone, otherwise later callers fail with "no such table".
       if (alreadyApplied && await db.tableExists(JOBS_TABLE)) {
         await this._ensureJobsTableColumns(db)
+        await this._ensureConcurrencyTable(db)
+        await this._reconcileConcurrency(db)
         return
       }
 
       await this._applyMigrations(db)
       await this._ensureJobsTableColumns(db)
+      await this._ensureConcurrencyTable(db)
+      await this._reconcileConcurrency(db)
 
       if (alreadyApplied) return
 
@@ -586,6 +633,8 @@ export default class BackgroundJobsStore {
     table.bigint("orphaned_at_ms", {null: true, index: true})
     table.string("worker_id", {null: true})
     table.text("last_error", {null: true})
+    table.string("concurrency_key", {null: true, index: true})
+    table.integer("max_concurrency", {null: true})
 
     await db.createTable(table)
   }
@@ -643,6 +692,37 @@ export default class BackgroundJobsStore {
     }
 
     await this._backfillExecutionModesOnce(db)
+
+    const lockName = `${MIGRATION_SCOPE}:concurrency_columns`
+    const acquired = await db.acquireAdvisoryLock(lockName)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs concurrency schema lock")
+
+    try {
+      // SQL Server schema reads can deadlock with a concurrent ALTER TABLE, so
+      // acquire the lock before inspecting either column rather than only
+      // protecting the mutation.
+      db.clearSchemaCache()
+      const lockedTable = await db.getTableByNameOrFail(JOBS_TABLE)
+      const concurrencyColumnNames = ["concurrency_key", "max_concurrency"]
+
+      for (const concurrencyColumnName of concurrencyColumnNames) {
+        if (await lockedTable.getColumnByName(concurrencyColumnName)) continue
+
+        const tableData = new TableData(JOBS_TABLE)
+        if (concurrencyColumnName == "concurrency_key") {
+          tableData.string("concurrency_key", {null: true, index: true})
+        } else {
+          tableData.integer("max_concurrency", {null: true})
+        }
+
+        for (const sql of await db.alterTableSQLs(tableData)) await db.query(sql)
+      }
+
+      db.clearSchemaCache()
+    } finally {
+      await db.releaseAdvisoryLock(lockName)
+    }
   }
 
   /**
@@ -757,19 +837,18 @@ export default class BackgroundJobsStore {
       shouldRetry
     })
 
-    await db.update({
+    const affectedRows = await this._updateAffectedRows(db, {
       tableName: JOBS_TABLE,
       data: update,
       conditions: this._activeHandoffConditions(job)
     })
 
+    if (affectedRows !== 1) return null
+    await this._releaseConcurrency(db, job.concurrencyKey)
+
     const updatedJob = await this._getJobRowById(db, job.id)
 
     if (!updatedJob) return null
-    if (updatedJob.handoffId !== job.handoffId) return null
-    if (updatedJob.attempts !== nextAttempt) return null
-    if (updatedJob.status !== update.status) return null
-
     return updatedJob
   }
 
@@ -866,8 +945,115 @@ export default class BackgroundJobsStore {
       failedAtMs: this._normalizeNumber(row.failed_at_ms),
       orphanedAtMs: this._normalizeNumber(row.orphaned_at_ms),
       workerId: row.worker_id ? String(row.worker_id) : null,
-      lastError: row.last_error ? String(row.last_error) : null
+      lastError: row.last_error ? String(row.last_error) : null,
+      concurrencyKey: row.concurrency_key ? String(row.concurrency_key) : null,
+      maxConcurrency: this._normalizeNumber(row.max_concurrency)
+    }
+  }
+
+  /**
+   * Validates concurrency options.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @returns {{concurrencyKey: string, maxConcurrency: number} | null} - Normalized configuration.
+   */
+  _normalizeConcurrencyOptions(options) {
+    const key = options?.concurrencyKey
+    const cap = options?.maxConcurrency
+    if (key === undefined && cap === undefined) return null
+    if (typeof key !== "string" || key.length === 0 || !Number.isInteger(cap) || Number(cap) <= 0) {
+      throw new Error("background job concurrencyKey and maxConcurrency must be paired; concurrencyKey must be non-empty and maxConcurrency must be a positive integer")
+    }
+    return {concurrencyKey: key, maxConcurrency: Number(cap)}
+  }
+
+  /**
+   * Ensures the concurrency state table exists.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when ready.
+   */
+  async _ensureConcurrencyTable(db) {
+    if (await db.tableExists(CONCURRENCY_TABLE)) return
+    const table = new TableData(CONCURRENCY_TABLE, {ifNotExists: true})
+    table.string("concurrency_key", {primaryKey: true})
+    table.integer("max_concurrency", {null: false})
+    table.integer("active_count", {null: false})
+    await db.createTable(table)
+  }
+
+  /**
+   * Registers or verifies a stable key configuration.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {object} concurrency - Concurrency configuration.
+   * @param {string} concurrency.concurrencyKey - Concurrency key.
+   * @param {number} concurrency.maxConcurrency - Stable cap.
+   * @returns {Promise<void>} - Resolves when verified.
+   */
+  async _ensureConcurrencyKey(db, {concurrencyKey, maxConcurrency}) {
+    const rows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+    if (!rows[0]) {
+      try {
+        await db.insert({tableName: CONCURRENCY_TABLE, data: {active_count: 0, concurrency_key: concurrencyKey, max_concurrency: maxConcurrency}})
+        return
+      } catch (error) {
+        const racedRows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+        if (!racedRows[0]) throw error
+        rows[0] = racedRows[0]
+      }
     }
+    const configured = /** @type {{max_concurrency?: number | string}} */ (rows[0])
+    if (this._normalizeNumber(configured.max_concurrency) !== maxConcurrency) throw new Error(`Conflicting maxConcurrency for background job concurrencyKey: ${concurrencyKey}`)
+  }
+
+  /**
+   * Atomically reserves capacity for a key.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} concurrencyKey - Concurrency key.
+   * @returns {Promise<boolean>} - Whether capacity was reserved.
+   */
+  async _reserveConcurrency(db, concurrencyKey) {
+    const table = db.quoteTable(CONCURRENCY_TABLE)
+    const count = db.quoteColumn("active_count")
+    const affectedRows = await db.affectedRows(`UPDATE ${table} SET ${count} = ${count} + 1 WHERE ${db.quoteColumn("concurrency_key")} = ${db.quote(concurrencyKey)} AND ${count} < ${db.quoteColumn("max_concurrency")}`)
+    return affectedRows === 1
+  }
+
+  /**
+   * Runs a portable update and returns its affected-row count.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {import("../database/drivers/base.js").UpdateSqlArgsType} args - Update options.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _updateAffectedRows(db, args) {
+    return await db.affectedRows(db.updateSql(args))
+  }
+
+  /**
+   * Releases capacity for a key.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string | null} concurrencyKey - Concurrency key.
+   * @returns {Promise<void>} - Resolves when released.
+   */
+  async _releaseConcurrency(db, concurrencyKey) {
+    if (!concurrencyKey) return
+    const table = db.quoteTable(CONCURRENCY_TABLE)
+    const count = db.quoteColumn("active_count")
+    await db.query(`UPDATE ${table} SET ${count} = ${count} - 1 WHERE ${db.quoteColumn("concurrency_key")} = ${db.quote(concurrencyKey)} AND ${count} > 0`)
+  }
+
+  /**
+   * Rebuilds durable counts from active handoffs after startup.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when reconciled.
+   */
+  async _reconcileConcurrency(db) {
+    if (!(await db.tableExists(CONCURRENCY_TABLE))) return
+    const concurrencyTable = db.quoteTable(CONCURRENCY_TABLE)
+    const jobsTable = db.quoteTable(JOBS_TABLE)
+    await db.query(
+      `UPDATE ${concurrencyTable} SET ${db.quoteColumn("active_count")} = (` +
+      `SELECT COUNT(*) FROM ${jobsTable} WHERE ${jobsTable}.${db.quoteColumn("status")} = ${db.quote("handed_off")} AND ` +
+      `${jobsTable}.${db.quoteColumn("concurrency_key")} = ${concurrencyTable}.${db.quoteColumn("concurrency_key")})`
+    )
   }
 
   /**
@@ -973,25 +1159,22 @@ export default class BackgroundJobsStore {
   }
 
   /**
-   * Serializes reports for one job so duplicate reports cannot both appear accepted.
+   * Runs a value-returning callback inside the driver's void-typed transaction API.
    * @template T
-   * @param {object} args - Options.
-   * @param {import("../database/drivers/base.js").default} args.db - Database connection.
-   * @param {string} args.jobId - Job id.
-   * @param {() => Promise<T>} callback - Locked callback.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {() => Promise<T>} callback - Transaction callback.
    * @returns {Promise<T>} - Callback result.
    */
-  async _withHandoffLock({db, jobId}, callback) {
-    const lockName = `background-job:${jobId}`
-    const acquired = await db.acquireAdvisoryLock(lockName)
-
-    if (!acquired) throw new Error(`Failed to acquire background job handoff lock: ${jobId}`)
-
-    try {
-      return await callback()
-    } finally {
-      await db.releaseAdvisoryLock(lockName)
-    }
+  async _transactionResult(db, callback) {
+    let completed = false
+    /** @type {T | undefined} */
+    let result
+    await db.transaction(async () => {
+      result = await callback()
+      completed = true
+    })
+    if (!completed) throw new Error("Background jobs transaction callback was not invoked")
+    return /** @type {T} */ (result)
   }
 
   /**

package/build/background-jobs/types.js

@@ -13,6 +13,8 @@
  * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"forked"`.
  * @property {boolean} [forked] - Compatibility alias: `false` maps to `"inline"` and `true` maps to `"forked"`.
  * @property {number} [maxRetries] - Max retries for a failed job before it is marked failed.
+ * @property {string} [concurrencyKey] - Opaque non-empty key used to share a concurrency cap.
+ * @property {number} [maxConcurrency] - Positive integer cap; must be paired with `concurrencyKey`.
  */
 /**
  * @typedef {object} BackgroundJobPayload
@@ -43,6 +45,8 @@
  * @property {number | null} orphanedAtMs - Orphaned time in ms.
  * @property {string | null} workerId - Worker id handling the job.
  * @property {string | null} lastError - Last failure message.
+ * @property {string | null} concurrencyKey - Durable concurrency key.
+ * @property {number | null} maxConcurrency - Durable per-key cap.
  */
 /**
  * @typedef {object} BackgroundJobFailureEvent

package/build/database/drivers/base.js

@@ -1050,6 +1050,22 @@ export default class VelociousDatabaseDriversBase {
     throw new Error("'query' unexpected came here")
   }
 
+  /**
+   * Executes a mutation and returns the number of rows changed by that statement.
+   * @param {string} sql - Mutation SQL string.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async affectedRows(sql) {
+    this._assertWritableQuery(sql)
+    await this.beforeQuery(sql, {})
+
+    try {
+      return await this._affectedRowsActual(sql)
+    } finally {
+      await this.afterQuery(sql, {})
+    }
+  }
+
   /**
    * Runs query actual with logging.
    * @param {object} args - Options object.
@@ -1308,6 +1324,16 @@ export default class VelociousDatabaseDriversBase {
     throw new Error(`queryActual not implemented`)
   }
 
+  /**
+   * Executes a mutation and returns its affected row count.
+   * @abstract
+   * @param {string} sql - Mutation SQL string.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  _affectedRowsActual(sql) { // eslint-disable-line no-unused-vars
+    throw new Error(`affectedRowsActual not implemented`)
+  }
+
   /**
    * Runs query to sql.
    * @abstract

package/build/database/drivers/mssql/index.js

@@ -328,6 +328,19 @@ export default class VelociousDatabaseDriversMssql extends Base{
     return Array.isArray(result.recordsets) ? result.recordsets[0] || [] : []
   }
 
+  /**
+   * Executes a mutation with affected-row metadata.
+   * @param {string} sql - Mutation SQL.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _affectedRowsActual(sql) {
+    const request = this._currentTransaction
+      ? new mssql.Request(this._currentTransaction)
+      : new mssql.Request(this.connection)
+    const result = await request.query(sql)
+    return result.rowsAffected.reduce((total, count) => total + count, 0)
+  }
+
   /**
    * Runs query to sql.
    * @param {import("../../query/index.js").default} query - Query instance.

package/build/database/drivers/mysql/index.js

@@ -344,6 +344,24 @@ export default class VelociousDatabaseDriversMysql extends Base{
     }
   }
 
+  /**
+   * Executes a mutation with affected-row metadata.
+   * @param {string} sql - Mutation SQL.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _affectedRowsActual(sql) {
+    if (!this.pool) await this.connect()
+    if (!this.pool) throw new Error("MySQL pool failed to initialize")
+    const pool = this.pool
+
+    return await new Promise((resolve, reject) => {
+      pool.query(sql, (error, result) => {
+        if (error) reject(error)
+        else resolve("affectedRows" in result ? result.affectedRows : 0)
+      })
+    })
+  }
+
   /**
    * Runs query to sql.
    * @param {import("../../query/index.js").default} query - Query instance.

package/build/database/drivers/pgsql/index.js

@@ -227,6 +227,18 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return response.rows
   }
 
+  /**
+   * Executes a mutation with affected-row metadata.
+   * @param {string} sql - Mutation SQL.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _affectedRowsActual(sql) {
+    if (!this.connection) await this.connect()
+    if (!this.connection) throw new Error("PostgreSQL connection failed to initialize")
+    const response = await this.connection.query(sql)
+    return response.rowCount || 0
+  }
+
   /**
    * Runs query to sql.
    * @param {import("../../query/index.js").default} query - Query instance.

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

@@ -47,6 +47,17 @@ export default class VelociousDatabaseDriversSqliteConnectionSqlJs {
     return result
   }
 
+  /**
+   * Executes a mutation with affected-row metadata.
+   * @param {string} sql - Mutation SQL.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async affectedRows(sql) {
+    await this.query(sql)
+    const connection = /** @type {import("sql.js").Database & {getRowsModified: () => number}} */ (this.connection)
+    return connection.getRowsModified()
+  }
+
   saveDatabase = async () => {
     const databaseContent = this.connection.export()
 

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

@@ -15,7 +15,7 @@ import fileExists from "../../../utils/file-exists.js"
 export default class VelociousDatabaseDriversSqliteNode extends Base {
   /**
    * Connection.
-   * @type {import("sqlite3").Database | undefined} */
+   * @type {import("sqlite").Database | undefined} */
   connection = undefined
 
   /**
@@ -39,11 +39,10 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     this._advisoryLockDirectory = path.join(databaseDir, `${this.localStorageName()}.velocious-advisory-locks`)
 
     try {
-      // @ts-expect-error
-      this.connection = /** @type {import("sqlite3").Database} */ (await open({
+      this.connection = await open({
         filename: databasePath,
         driver: sqlite3.Database
-      }))
+      })
     } catch (error) {
       if (error instanceof Error) {
         throw new Error(`Couldn't open database ${databasePath} because of ${error.constructor.name}: ${error.message}`, {cause: error})
@@ -79,6 +78,17 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     return await query(this.connection, sql)
   }
 
+  /**
+   * Executes a mutation with affected-row metadata.
+   * @param {string} sql - Mutation SQL.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _affectedRowsActual(sql) {
+    if (!this.connection) throw new Error("No connection")
+    const result = await this.connection.run(sql)
+    return result.changes || 0
+  }
+
   /**
    * Layers a filesystem lock directory on top of the in-process waiter
    * queue so SQLite deployments with multiple Node processes writing to

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

@@ -81,4 +81,17 @@ export default class VelociousDatabaseDriversSqliteNative extends Base {
       return query(this.connection, sql)
     })
   }
+
+  /**
+   * Executes a mutation with affected-row metadata.
+   * @param {string} sql - Mutation SQL.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _affectedRowsActual(sql) {
+    return await this._queryMutex.sync(async () => {
+      if (!this.connection) throw new Error("Not connected yet")
+      const result = await this.connection.runAsync(sql)
+      return result.changes
+    })
+  }
 }

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

@@ -8,7 +8,7 @@ import Base from "./base.js"
 
 /**
  * VelociousDatabaseDriversSqliteWeb class.
- * @typedef {{query: (sql: string) => Promise<Record<string, ?>[]>, close: () => Promise<void>}} SqliteWebConnection
+ * @typedef {{query: (sql: string) => Promise<Record<string, ?>[]>, affectedRows: (sql: string) => Promise<number>, close: () => Promise<void>}} SqliteWebConnection
  */
 
 export default class VelociousDatabaseDriversSqliteWeb extends Base {
@@ -110,4 +110,14 @@ export default class VelociousDatabaseDriversSqliteWeb extends Base {
 
     return result
   }
+
+  /**
+   * Executes a mutation with affected-row metadata.
+   * @param {string} sql - Mutation SQL.
+   * @returns {Promise<number>} - Affected row count.
+   */
+  async _affectedRowsActual(sql) {
+    const connection = this.getConnection()
+    return await connection.affectedRows(sql)
+  }
 }

package/build/database/drivers/sqlite/query.js

@@ -2,7 +2,7 @@
 
 /**
  * Runs query.
- * @param {import("sqlite3").Database} connection - Connection.
+ * @param {import("sqlite").Database} connection - Connection.
  * @param {string} sql - SQL string.
  * @returns {Promise<Record<string, ?>[]>} - Resolves with string value.
  */
@@ -13,7 +13,6 @@ export default async function query(connection, sql) {
      * @type {Record<string, ?>[]} */
     let result
 
-    // @ts-expect-error
     result = await connection.all(sql)
 
     return result