velocious 1.0.101 → 1.0.103

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

@@ -1,3 +1,5 @@
+// @ts-check
+
 import AlterTable from "./sql/alter-table.js"
 import Base from "../base.js"
 import CreateDatabase from "./sql/create-database.js"
@@ -23,6 +25,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
     this.pool.on("error", this.onPoolError)
   }
 
+  /** @param {Error} error */
   onPoolError = (error) => {
     console.error("Velocious / MySQL driver / Pool error", error)
   }
@@ -31,7 +34,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * @returns {Promise<void>}
    */
   async close() {
-    await this.pool.end()
+    await this.pool?.end()
     this.pool = undefined
   }
 
@@ -40,9 +43,11 @@ export default class VelociousDatabaseDriversMysql extends Base{
    */
   connectArgs() {
     const args = this.getArgs()
-    const connectArgs = []
     const forward = ["database", "host", "password"]
 
+    /** @type {Record<string, any>} */
+    const connectArgs = {}
+
     for (const forwardValue of forward) {
       if (forwardValue in args) connectArgs[forwardValue] = digg(args, forwardValue)
     }
@@ -53,17 +58,21 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
+   * @param {import("../../table-data/index.js").default} tableData
    * @returns {Promise<string[]>}
    */
-  async alterTableSql(tableData) {
+  async alterTableSQLs(tableData) {
     const alterArgs = {tableData, driver: this}
     const alterTable = new AlterTable(alterArgs)
 
-    return await alterTable.toSqls()
+    return await alterTable.toSQLs()
   }
 
   /**
-   * @returns {Promise<string[]>}
+   * @param {string} databaseName
+   * @param {object} [args]
+   * @param {boolean} [args.ifNotExists]
+   * @returns {string[]}
    */
   createDatabaseSql(databaseName, args) {
     const createArgs = Object.assign({databaseName, driver: this}, args)
@@ -73,16 +82,18 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
-   * @returns {string}
+   * @param {import("../base.js").CreateIndexSqlArgs} indexData
+   * @returns {string[]}
    */
-  createIndexSql(indexData) {
+  createIndexSQLs(indexData) {
     const createArgs = Object.assign({driver: this}, indexData)
     const createIndex = new CreateIndex(createArgs)
 
-    return createIndex.toSql()
+    return createIndex.toSQLs()
   }
 
   /**
+   * @param {import("../../table-data/index.js").default} tableData
    * @returns {string[]}
    */
   createTableSql(tableData) {
@@ -116,13 +127,15 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
+   * @param {string} tableName
+   * @param {import("../base.js").DropTableSqlArgsType} [args]
    * @returns {string[]}
    */
-  dropTableSql(tableName, args = {}) {
+  dropTableSQLs(tableName, args = {}) {
     const dropArgs = Object.assign({tableName, driver: this}, args)
     const dropTable = new DropTable(dropArgs)
 
-    return dropTable.toSql()
+    return dropTable.toSQLs()
   }
 
   /**
@@ -136,18 +149,26 @@ export default class VelociousDatabaseDriversMysql extends Base{
   primaryKeyType() { return "bigint" }
 
   /**
-   * @returns {Array<Record<string, any>>}
+   * @param {string} sql
+   * @returns {Promise<import("../base.js").QueryResultType>}
    */
   async _queryActual(sql) {
+    if (!this.pool) throw new Error("Not connected to a pool yet")
+
     try {
       return await query(this.pool, sql)
     } catch (error) {
       // Re-throw to un-corrupt stacktrace
-      throw new Error(error.message)
+      if (error instanceof Error) {
+        throw new Error(`Query failed: ${error.message}`)
+      } else {
+        throw new Error(`Query failed: ${error}`)
+      }
     }
   }
 
   /**
+   * @param {import("../../query/index.js").default} query
    * @returns {string}
    */
   queryToSql(query) { return new QueryParser({query}).toSql() }
@@ -158,7 +179,8 @@ export default class VelociousDatabaseDriversMysql extends Base{
   shouldSetAutoIncrementWhenPrimaryKey() { return true }
 
   /**
-   * @returns {string}
+   * @param {any} value
+   * @returns {any}
    */
   escape(value) {
     if (!this.pool) throw new Error("Can't escape before connected")
@@ -169,6 +191,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
+   * @param {string} value
    * @returns {string}
    */
   quote(value) {
@@ -178,6 +201,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
+   * @param {import("../base.js").DeleteSqlArgsType} args
    * @returns {string}
    */
   deleteSql({tableName, conditions}) {
@@ -187,6 +211,8 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
+   * @abstract
+   * @param {import("../base.js").InsertSqlArgsType} args
    * @returns {string}
    */
   insertSql(args) {
@@ -197,7 +223,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
-   * @returns {Array<Table>}
+   * @returns {Promise<Array<import("../base-table.js").default>>}
    */
   async getTables() {
     const result = await this.query("SHOW FULL TABLES")
@@ -213,7 +239,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
-   * @returns {number}
+   * @returns {Promise<number>}
    */
   async lastInsertID() {
     const result = await this.query("SELECT LAST_INSERT_ID() AS last_insert_id")
@@ -231,13 +257,14 @@ export default class VelociousDatabaseDriversMysql extends Base{
   }
 
   /**
-   * @returns {void}
+   * @returns {Promise<void>}
    */
   async _startTransactionAction() {
     await this.query("START TRANSACTION")
   }
 
   /**
+   * @param {import("../base.js").UpdateSqlArgsType} args
    * @returns {string}
    */
   updateSql({conditions, data, tableName}) {

package/src/database/drivers/mysql/query-parser.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import BaseQueryParser from "../../query-parser/base-query-parser.js"
 
 export default class VelociousDatabaseConnectionDriversMysqlQueryParser extends BaseQueryParser {

package/src/database/drivers/mysql/query.js

@@ -1,12 +1,17 @@
-export default async function query(connection, sql) {
+/**
+ * @param {import("mysql").Pool} pool
+ * @param {string} sql
+ */
+export default async function query(pool, sql) {
   return new Promise((resolve, reject) => {
-    connection.query(sql, (error, results, fields) => {
+    pool.query(sql, (error, results, fields) => {
       if (error) {
         reject(new Error(`Query failed because of ${error}: ${sql}`))
       } else {
         const rows = []
 
         for (const resultIndex in results) {
+          /** @type {Record<string, any>} */
           const result = {}
 
           for (const fieldKey in fields) {

package/src/database/drivers/mysql/table.js

@@ -1,9 +1,15 @@
+// @ts-check
+
 import BaseTable from "../base-table.js"
 import Column from "./column.js"
 import ColumnsIndex from "./columns-index.js"
 import ForeignKey from "./foreign-key.js"
 
 export default class VelociousDatabaseDriversMysqlTable extends BaseTable {
+  /**
+   * @param {import("../base.js").default} driver
+   * @param {Record<string, any>} data
+   */
   constructor(driver, data) {
     super()
     this.data = data

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

@@ -1,3 +1,5 @@
+// @ts-check
+
 import AlterTable from "./sql/alter-table.js"
 import Base from "../base.js"
 import {Client} from "pg"
@@ -21,21 +23,27 @@ export default class VelociousDatabaseDriversPgsql extends Base{
       await client.connect()
     } catch (error) {
       // Re-throw to recover real stack trace
-      throw new Error(`Connect to Postgres server failed: ${error.message}`)
+      if (error instanceof Error) {
+        throw new Error(`Connect to Postgres server failed: ${error.message}`)
+      } else {
+        throw new Error(`Connect to Postgres server failed: ${error}`)
+      }
     }
 
     this.connection = client
   }
 
   async disconnect() {
-    await this.connection.end()
+    await this.connection?.end()
   }
 
   connectArgs() {
     const args = this.getArgs()
-    const connectArgs = []
     const forward = ["database", "host", "password", "port"]
 
+    /** @type {Record<string, any>} */
+    const connectArgs = {}
+
     for (const forwardValue of forward) {
       if (forwardValue in args) connectArgs[forwardValue] = digg(args, forwardValue)
     }
@@ -46,17 +54,27 @@ export default class VelociousDatabaseDriversPgsql extends Base{
   }
 
   async close() {
-    await this.connection.end()
+    await this.connection?.end()
     this.connection = undefined
   }
 
-  async alterTableSql(tableData) {
+  /**
+   * @param {import("../../table-data/index.js").default} tableData
+   * @returns {Promise<string[]>}
+   */
+  async alterTableSQLs(tableData) {
     const alterArgs = {tableData, driver: this}
     const alterTable = new AlterTable(alterArgs)
 
-    return await alterTable.toSqls()
+    return await alterTable.toSQLs()
   }
 
+  /**
+   * @param {string} databaseName
+   * @param {object} [args]
+   * @param {boolean} [args.ifNotExists]
+   * @returns {string[]}
+   */
   createDatabaseSql(databaseName, args) {
     const createArgs = Object.assign({databaseName, driver: this}, args)
     const createDatabase = new CreateDatabase(createArgs)
@@ -64,13 +82,21 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return createDatabase.toSql()
   }
 
-  createIndexSql(indexData) {
+  /**
+   * @param {import("../base.js").CreateIndexSqlArgs} indexData
+   * @returns {string[]}
+   */
+  createIndexSQLs(indexData) {
     const createArgs = Object.assign({driver: this}, indexData)
     const createIndex = new CreateIndex(createArgs)
 
-    return createIndex.toSql()
+    return createIndex.toSQLs()
   }
 
+  /**
+   * @param {import("../../table-data/index.js").default} tableData
+   * @returns {string[]}
+   */
   createTableSql(tableData) {
     const createArgs = {tableData, driver: this, indexInCreateTable: false}
     const createTable = new CreateTable(createArgs)
@@ -92,31 +118,54 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     await this.query("SET session_replication_role = 'origin'")
   }
 
-  dropTableSql(tableName, args = {}) {
+  /**
+   * @param {string} tableName
+   * @param {import("../base.js").DropTableSqlArgsType} [args]
+   * @returns {string[]}
+   */
+  dropTableSQLs(tableName, args = {}) {
     const dropArgs = Object.assign({tableName, driver: this}, args)
     const dropTable = new DropTable(dropArgs)
 
-    return dropTable.toSql()
+    return dropTable.toSQLs()
   }
 
   getType() { return "pgsql" }
   primaryKeyType() { return "bigint" }
 
+  /**
+   * @param {string} sql
+   * @returns {Promise<import("../base.js").QueryResultType>}
+   */
   async _queryActual(sql) {
     let response
 
+    if (!this.connection) throw new Error("Not yet connected")
+
     try {
       response = await this.connection.query(sql)
     } catch (error) {
-      throw new Error(`Query failed: ${error.message} with SQL: ${sql}`)
+      if (error instanceof Error) {
+        throw new Error(`Query failed: ${error.message} with SQL: ${sql}`)
+      } else {
+        throw new Error(`Query failed: ${error} with SQL: ${sql}`)
+      }
     }
 
     return response.rows
   }
 
+  /**
+   * @param {import("../../query/index.js").default} query
+   * @returns {string}
+   */
   queryToSql(query) { return new QueryParser({query}).toSql() }
   shouldSetAutoIncrementWhenPrimaryKey() { return true }
 
+  /**
+   * @param {any} value
+   * @returns {any}
+   */
   escape(value) {
     if (!this.connection) throw new Error("Can't escape before connected")
     if (typeof value === "number") return value
@@ -126,6 +175,10 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return escapedValueWithQuotes.slice(1, escapedValueWithQuotes.length - 1)
   }
 
+  /**
+   * @param {string} value
+   * @returns {string}
+   */
   quote(value) {
     if (!this.connection) throw new Error("Can't escape before connected")
     if (typeof value === "number") return value
@@ -133,12 +186,21 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return this.connection.escapeLiteral(this._convertValue(value))
   }
 
+  /**
+   * @param {import("../base.js").DeleteSqlArgsType} args
+   * @returns {string}
+   */
   deleteSql({tableName, conditions}) {
     const deleteInstruction = new Delete({conditions, driver: this, tableName})
 
     return deleteInstruction.toSql()
   }
 
+  /**
+   * @abstract
+   * @param {import("../base.js").InsertSqlArgsType} args
+   * @returns {string}
+   */
   insertSql(args) {
     const insertArgs = Object.assign({driver: this}, args)
     const insert = new Insert(insertArgs)
@@ -175,6 +237,11 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     await this.query("START TRANSACTION")
   }
 
+  /**
+   * @abstract
+   * @param {import("../base.js").UpdateSqlArgsType} args
+   * @returns {string}
+   */
   updateSql({conditions, data, tableName}) {
     const update = new Update({conditions, data, driver: this, tableName})
 

package/src/database/drivers/sqlite/base.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import {digg} from "diggerize"
 
 import AlterTable from "./sql/alter-table.js"
@@ -14,20 +16,33 @@ import Table from "./table.js"
 import Update from "./sql/update.js"
 
 export default class VelociousDatabaseDriversSqliteBase extends Base {
-  async alterTableSql(tableData) {
+  /**
+   * @param {import("../../table-data/index.js").default} tableData
+   * @returns {Promise<string[]>}
+   */
+  async alterTableSQLs(tableData) {
     const alterArgs = {driver: this, tableData}
     const alterTable = new AlterTable(alterArgs)
 
-    return await alterTable.toSqls()
+    return await alterTable.toSQLs()
   }
 
-  createIndexSql(indexData) {
+  /**
+   * @param {import("../base.js").CreateIndexSqlArgs} indexData
+   * @returns {string[]}
+   */
+  createIndexSQLs(indexData) {
     const createArgs = Object.assign({driver: this}, indexData)
     const createIndex = new CreateIndex(createArgs)
 
-    return createIndex.toSql()
+    return createIndex.toSQLs()
   }
 
+  /**
+   * @abstract
+   * @param {import("../../table-data/index.js").default} tableData
+   * @returns {string[]}
+   */
   createTableSql(tableData) {
     const createArgs = {tableData, driver: this, indexInCreateTable: false}
     const createTable = new CreateTable(createArgs)
@@ -47,14 +62,21 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     await this.query("PRAGMA foreign_keys = 1")
   }
 
-  dropTableSql(tableName, args = {}) {
-    const dropArgs = Object.assign({tableName, driver: this}, args)
+  /**
+   * @param {string} tableName
+   * @param {import("../base.js").DropTableSqlArgsType} [args]
+   * @returns {string[]}
+   */
+  dropTableSQLs(tableName, args = {}) {
+    const driver = /** @type {import("../base.js").default} */ (this)
+    const dropArgs = Object.assign({tableName, driver}, args)
     const dropTable = new DropTable(dropArgs)
 
-    return dropTable.toSql()
+    return dropTable.toSQLs()
   }
 
   /**
+   * @param {import("../base.js").DeleteSqlArgsType} args
    * @returns {string}
    */
   deleteSql(args) { return new Delete(Object.assign({driver: this}, args)).toSql() }
@@ -65,18 +87,19 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
   getType() { return "sqlite" }
 
   /**
+   * @param {import("../base.js").InsertSqlArgsType} args
    * @returns {string}
    */
   insertSql(args) { return new Insert(Object.assign({driver: this}, args)).toSql() }
 
   /**
-   * @param {string} tableName
-   * @param {object} args
+   * @param {string} name
+   * @param {object} [args]
    * @param {boolean} args.throwError
-   * @returns {Promise<Table>}
+   * @returns {Promise<import("../base-table.js").default | undefined>}
    */
-  async getTableByName(tableName, args) {
-    const result = await this.query(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ${this.quote(tableName)} LIMIT 1`)
+  async getTableByName(name, args) {
+    const result = await this.query(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ${this.quote(name)} LIMIT 1`)
     const row = result[0]
 
     if (row) {
@@ -87,13 +110,11 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
       const tables = await this.getTables()
       const tableNames = tables.map((table) => table.getName())
 
-      throw new Error(`No table by that name: ${tableName} in ${tableNames.join(", ")}`)
+      throw new Error(`No table by that name: ${name} in ${tableNames.join(", ")}`)
     }
   }
 
-  /**
-   * @returns {Promise<Table[]>}
-   */
+  /** @returns {Promise<Array<import("../base-table.js").default>>} */
   async getTables() {
     const result = await this.query("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")
     const tables = []
@@ -107,13 +128,19 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     return tables
   }
 
-  async insertMultiple(...args) {
+  /**
+   * @param {string} tableName
+   * @param {Array<string>} columns
+   * @param {Array<Array<string>>} rows
+   * @returns {Promise<void>}
+   */
+  async insertMultiple(tableName, columns, rows) {
     await this.registerVersion()
 
     if (this.supportsMultipleInsertValues()) {
-      return await this.insertMultipleWithSingleInsert(...args)
+      await this.insertMultipleWithSingleInsert(tableName, columns, rows)
     } else {
-      return await this.insertMultipleWithTransaction(...args)
+      await this.insertMultipleWithTransaction(tableName, columns, rows)
     }
   }
 
@@ -140,20 +167,28 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
 
   /**
    * @param {string} tableName
-   * @param {string[]} columns
-   * @param {any[][]} rows
-   * @returns {Promise<any[]>}
+   * @param {Array<string>} columns
+   * @param {Array<Array<string>>} rows
+   * @returns {Promise<void>}
    */
   async insertMultipleWithSingleInsert(tableName, columns, rows) {
     const sql = new Insert({columns, driver: this, rows, tableName}).toSql()
 
-    return await this.query(sql)
+    await this.query(sql)
   }
 
+  /**
+   * @param {string} tableName
+   * @param {Array<string>} columns
+   * @param {Array<Array<string>>} rows
+   * @returns {Promise<void>}
+   */
   async insertMultipleWithTransaction(tableName, columns, rows) {
+    /** @type {string[]} */
     const sqls = []
 
     for (const row of rows) {
+      /** @type {Record<string, any>} */
       const data = []
 
       for (const columnIndex in columns) {
@@ -193,6 +228,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
   primaryKeyType() { return "integer" } // Because bigint on SQLite doesn't support auto increment
 
   /**
+   * @param {import("../../query/index.js").default} query
    * @returns {string}
    */
   queryToSql(query) { return new QueryParser({query}).toSql() }
@@ -215,6 +251,10 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
 
   shouldSetAutoIncrementWhenPrimaryKey() { return false }
 
+  /**
+   * @param {any} value
+   * @returns {any}
+   */
   escape(value) {
     value = this._convertValue(value)
 
@@ -222,12 +262,16 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
 
     if (type != "string") value = `${value}`
 
-    const resultWithQuotes = escapeString(value)
+    const resultWithQuotes = escapeString(value, null)
     const result = resultWithQuotes.substring(1, resultWithQuotes.length - 1)
 
     return result
   }
 
+  /**
+   * @param {Error} error
+   * @returns {boolean}
+   */
   retryableDatabaseError(error) {
     if (error.message?.startsWith("attempt to write a readonly database")) return true
     if (error.message?.startsWith("database is locked")) return true
@@ -236,6 +280,10 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     return false
   }
 
+  /**
+   * @param {string} value
+   * @returns {string}
+   */
   quote(value) {
     value = this._convertValue(value)
 
@@ -244,8 +292,12 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     if (type == "number") return value
     if (type != "string") value = `${value}`
 
-    return escapeString(value)
+    return escapeString(value, null)
   }
 
+  /**
+   * @param {import("../base.js").UpdateSqlArgsType} args
+   * @returns {string}
+   */
   updateSql({conditions, data, tableName}) { return new Update({conditions, data, driver: this, tableName}).toSql() }
 }

package/src/database/drivers/sqlite/column.js

@@ -1,7 +1,15 @@
+// @ts-check
+
 import {digg} from "diggerize"
 import BaseColumn from "../base-column.js"
 
 export default class VelociousDatabaseDriversSqliteColumn extends BaseColumn {
+  /**
+   * @param {object} args
+   * @param {Record<string, any>} args.column
+   * @param {import("../base.js").default} args.driver
+   * @param {import("../base-table.js").default} args.table
+   */
   constructor({column, driver, table}) {
     super()
     this.column = column