velocious 1.0.93 → 1.0.95

package/src/database/drivers/base.js

@@ -10,6 +10,10 @@ import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/src/wait.js"
 
 export default class VelociousDatabaseDriversBase {
+  /**
+   * @param {object} config
+   * @param {import("../../configuration.js").default} configuration
+   */
   constructor(config, configuration) {
     this._args = config
     this.configuration = configuration
@@ -19,6 +23,14 @@ export default class VelociousDatabaseDriversBase {
     this._transactionsActionsMutex = new Mutex()
   }
 
+  /**
+   * @param {string} tableName
+   * @param {string} columnName
+   * @param {string} referencedTableName
+   * @param {string} referencedColumnName
+   * @param {object} args
+   * @returns {Promise<void>}
+   */
   async addForeignKey(tableName, columnName, referencedTableName, referencedColumnName, args) {
     const tableForeignKeyArgs = Object.assign(
       {
@@ -41,6 +53,18 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * @interface
+   * @returns {Promise<string[]>}
+   */
+  alterTableSql() {
+    throw new Error("alterTableSql not implemented")
+  }
+
+  /**
+   * @param {...Parameters<this["createTableSql"]>} args
+   * @returns {void}
+   */
   async createTable(...args) {
     const sqls = this.createTableSql(...args)
 
@@ -49,12 +73,20 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * @param {...Parameters<this["deleteSql"]>} args
+   * @returns {void}
+   */
   async delete(...args) {
     const sql = this.deleteSql(...args)
 
     await this.query(sql)
   }
 
+  /**
+   * @param {...Parameters<this['dropTableSql']>} args
+   * @returns {void}
+   */
   async dropTable(...args) {
     const sqls = this.dropTableSql(...args)
 
@@ -63,20 +95,45 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * @interface
+   * @param {string} _tableName
+   * @param {object} _args
+   * @param {boolean} _args.cascade
+   * @param {boolean} _args.ifExists
+   * @returns {string}
+   */
+  dropTableSql(_tableName, _args) { // eslint-disable-line no-unused-vars
+    throw new Error("dropTableSql not implemented")
+  }
+
+  /**
+   * @returns {object}
+   */
   getArgs() {
     return this._args
   }
 
+  /**
+   * @returns {import("../../configuration.js").default}
+   */
   getConfiguration() {
     if (!this.configuration) throw new Error("No configuration set")
 
     return this.configuration
   }
 
+  /**
+   * @returns {number}
+   */
   getIdSeq() {
     return this.idSeq
   }
 
+  /**
+   * @interface
+   * @returns {Array<import("./base-table.js").default>}
+   */
   getTables() {
     throw new Error(`${this.constructor.name}#getTables not implemented`)
   }
@@ -106,6 +163,10 @@ export default class VelociousDatabaseDriversBase {
     await this.query(sql)
   }
 
+  /**
+   * @interface
+   * @returns {Promise<number>}
+   */
   lastInsertID() {
     throw new Error(`${this.constructor.name}#lastInsertID not implemented`)
   }
@@ -181,8 +242,12 @@ export default class VelociousDatabaseDriversBase {
     return await this.query(sql)
   }
 
-  setIdSeq(id) {
-    this.idSeq = id
+  /**
+   * @param {number} newIdSeq
+   * @returns {void}
+   */
+  setIdSeq(newIdSeq) {
+    this.idSeq = newIdSeq
   }
 
   /**
@@ -246,6 +311,9 @@ export default class VelociousDatabaseDriversBase {
     return result
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async startTransaction() {
     await this._transactionsActionsMutex.sync(async () => {
       await this._startTransactionAction()
@@ -253,10 +321,16 @@ export default class VelociousDatabaseDriversBase {
     })
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async _startTransactionAction() {
     await this.query("BEGIN TRANSACTION")
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async commitTransaction() {
     await this._transactionsActionsMutex.sync(async () => {
       await this._commitTransactionAction()
@@ -264,13 +338,16 @@ export default class VelociousDatabaseDriversBase {
     })
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async _commitTransactionAction() {
     await this.query("COMMIT")
   }
 
   /**
    * @param {string} sql
-   * @returns {Promise<Array>}
+   * @returns {Promise<Array<Record<string, any>>>}
    */
   async query(sql) {
     let tries = 0
@@ -292,10 +369,18 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * @interface
+   * @param {Error} _error
+   * @returns {boolean}
+   */
   retryableDatabaseError(_error) { // eslint-disable-line no-unused-vars
     return false
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async rollbackTransaction() {
     await this._transactionsActionsMutex.sync(async () => {
       await this._rollbackTransactionAction()
@@ -303,20 +388,34 @@ export default class VelociousDatabaseDriversBase {
     })
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async _rollbackTransactionAction() {
     await this.query("ROLLBACK")
   }
 
+  /**
+   * @returns {string}
+   */
   generateSavePointName() {
     return `sp${new UUID(4).format().replaceAll("-", "")}`
   }
 
+  /**
+   * @param {string} savePointName
+   * @returns {Promise<void>}
+   */
   async startSavePoint(savePointName) {
     await this._transactionsActionsMutex.sync(async () => {
       await this._startSavePointAction(savePointName)
     })
   }
 
+  /**
+   * @param {string} savePointName
+   * @returns {Promise<void>}
+   */
   async _startSavePointAction(savePointName) {
     await this.query(`SAVEPOINT ${savePointName}`)
   }
@@ -343,26 +442,45 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * @param {string} savePointName
+   * @returns {Promise<void>}
+   */
   async releaseSavePoint(savePointName) {
     await this._transactionsActionsMutex.sync(async () => {
       await this._releaseSavePointAction(savePointName)
     })
   }
 
+  /**
+   * @param {string} savePointName
+   * @returns {Promise<void>}
+   */
   async _releaseSavePointAction(savePointName) {
     await this.query(`RELEASE SAVEPOINT ${savePointName}`)
   }
 
+  /**
+   * @param {string} savePointName
+   * @returns {Promise<void>}
+   */
   async rollbackSavePoint(savePointName) {
     await this._transactionsActionsMutex.sync(async () => {
       await this._rollbackSavePointAction(savePointName)
     })
   }
 
+  /**
+   * @param {string} savePointName
+   * @returns {Promise<void>}
+   */
   async _rollbackSavePointAction(savePointName) {
     await this.query(`ROLLBACK TO SAVEPOINT ${savePointName}`)
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async truncateAllTables() {
     await this.withDisabledForeignKeys(async () => {
       let tries = 0
@@ -408,6 +526,10 @@ export default class VelociousDatabaseDriversBase {
     await this.query(sql)
   }
 
+  /**
+   * @param {function() : void} callback
+   * @returns {Promise<any>}
+   */
   async withDisabledForeignKeys(callback) {
     await this.disableForeignKeys()
 

package/src/database/migrator.js

@@ -5,20 +5,30 @@ import restArgsError from "../utils/rest-args-error.js"
 import TableData from "./table-data/index.js"
 
 export default class VelociousDatabaseMigrator {
+  /**
+   * @param {object} args
+   * @param {import("../configuration.js").default} args.configuration
+   */
   constructor({configuration, ...restArgs}) {
     restArgsError(restArgs)
 
     if (!configuration) throw new Error("configuration argument is required")
 
     this.configuration = configuration
-    this.logger = new Logger(this)
+    this.logger = new Logger(this, {debug: false})
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async prepare() {
     await this.createMigrationsTable()
     await this.loadMigrationsVersions()
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async createMigrationsTable() {
     const dbs = await this.configuration.getCurrentConnections()
 
@@ -48,6 +58,11 @@ export default class VelociousDatabaseMigrator {
     }
   }
 
+  /**
+   * @param {string} dbIdentifier
+   * @param {string} version
+   * @returns {Promise<boolean>}
+   */
   hasRunMigrationVersion(dbIdentifier, version) {
     if (!this.migrationsVersions) throw new Error("Migrations versions hasn't been loaded yet")
     if (!this.migrationsVersions[dbIdentifier]) throw new Error(`Migrations versions hasn't been loaded yet for db: ${dbIdentifier}`)
@@ -197,7 +212,7 @@ export default class VelociousDatabaseMigrator {
     for (const migration of files) {
       await this.runMigrationFile({
         migration,
-        require: requireContext(migration.file).default
+        require: () => requireContext(migration.file).default
       })
     }
   }

package/src/database/query/drop-table-base.js

@@ -3,6 +3,14 @@ import QueryBase from "./base.js"
 import restArgsError from "../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseQueryDropTableBase extends QueryBase {
+  /**
+   * @param {object} args
+   * @param {boolean} args.cascade
+   * @param {import("./../drivers/base.js").default} args.driver
+   * @param {boolean} args.ifExists
+   * @param {object} args.options
+   * @param {string} args.tableName
+   */
   constructor({cascade, driver, ifExists, options, tableName, ...restArgs}) {
     super({driver, options})
 

package/src/database/query/index.js

@@ -11,7 +11,34 @@ import WhereHash from "./where-hash.js"
 import WherePlain from "./where-plain.js"
 import restArgsError from "../../utils/rest-args-error.js"
 
+/**
+ * @typedef {Record<string, boolean|NestedPreloadRecord>} NestedPreloadRecord
+ */
+
 export default class VelociousDatabaseQuery {
+  /**
+   * @param {object} args
+   * @template {import("../drivers/base.js").default} Tdriver
+   * @param {Tdriver} args.driver
+   * @template {import("./from-base.js").default} TfromBase
+   * @param {TfromBase[]} args.froms
+   * @param {string[]} args.groups
+   * @template {import("./join-base.js").default} TjoinBase
+   * @param {TjoinBase[]} args.joins
+   * @param {import("../handler.js").default} args.handler
+   * @param {number} args.limit
+   * @template {import("../record/index.js").default} Trecord
+   * @param {typeof Trecord} args.modelClass
+   * @param {number} args.offset
+   * @template {import("./order-basejs").default} TorderBase
+   * @param {TorderBase[]} args.orders
+   * @param {number} args.page
+   * @param {number} args.perPage
+   * @param {NestedPreloadRecord} args.preload
+   * @param {Record<string, Array<string>>} args.selects
+   * @template {import("./where-base.js").default} TwhereBase
+   * @param {TwhereBase[]} args.wheres
+   */
   constructor({driver, froms = [], groups = [], joins = [], handler, limit = null, modelClass, offset = null, orders = [], page = null, perPage, preload = {}, selects = [], wheres = [], ...restArgs}) {
     if (!driver) throw new Error("No driver given to query")
     if (!handler) throw new Error("No handler given to query")
@@ -100,6 +127,21 @@ export default class VelociousDatabaseQuery {
     return countResult
   }
 
+  /**
+   * @template {import("./from-base.js").default} T
+   * @returns {T[]}
+   */
+  getFroms() {
+    return this._froms
+  }
+
+  /**
+   * @returns {string[]}
+   */
+  getGroups() {
+    return this._groups
+  }
+
   /**
    * @returns {import("../query-parser/options.js").default}
    */

package/src/database/query-parser/from-parser.js

@@ -1,20 +1,31 @@
-import {digs} from "diggerize"
+// @ts-check
+
+import restArgsError from "../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseQueryParserFromParser {
-  constructor({pretty, query}) {
+  /**
+   * @param {object} args
+   * @param {boolean} args.pretty
+   * @param {import("../query/index.js").default} args.query
+   */
+  constructor({pretty, query, ...restArgs}) {
+    restArgsError(restArgs)
+
     this.pretty = pretty
     this.query = query
   }
 
+  /** @returns {string} */
   toSql() {
-    const {pretty, query} = digs(this, "pretty", "query")
+    const {pretty, query} = this
+    const froms = query.getFroms()
 
     let sql = " FROM"
 
-    for (const fromKey in query._froms) {
-      const from = query._froms[fromKey]
+    for (const fromKey in froms) {
+      const from = froms[fromKey]
 
-      if (fromKey > 0) {
+      if (typeof fromKey == "number" && fromKey > 0) {
         sql += ","
       }
 

package/src/database/query-parser/group-parser.js

@@ -1,24 +1,37 @@
-import {digs} from "diggerize"
+// @ts-check
+
+import restArgsError from "../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseQueryParserFromParser {
-  constructor({pretty, query}) {
+  /**
+   * @param {object} args
+   * @param {boolean} args.pretty
+   * @param {import("../query/index.js").default} args.query
+   */
+  constructor({pretty, query, ...restArgs}) {
+    restArgsError(restArgs)
+
     this.pretty = pretty
     this.query = query
   }
 
+  /**
+   * @returns {string}
+   */
   toSql() {
-    const {pretty, query} = digs(this, "pretty", "query")
+    const {pretty, query} = this
+    const groups = query.getGroups()
 
-    if (query._groups.length == 0) {
+    if (groups.length == 0) {
       return ""
     }
 
     let sql = " GROUP BY"
 
-    for (const groupKey in query._groups) {
-      const group = query._groups[groupKey]
+    for (const groupKey in groups) {
+      const group = groups[groupKey]
 
-      if (groupKey > 0) {
+      if (typeof groupKey == "number" && groupKey > 0) {
         sql += ","
       }
 
@@ -31,7 +44,7 @@ export default class VelociousDatabaseQueryParserFromParser {
       if (typeof group == "string") {
         sql += group
       } else {
-        sql += group.toSql()
+        throw new Error(`Unsupported group type: ${typeof group}`)
       }
     }
 

package/src/database/record/index.js

@@ -44,8 +44,7 @@ class ValidationError extends Error {
 
 class VelociousDatabaseRecord {
   /**
-   * @template T extends import("./validators/base.js").default
-   * @returns {Record<string, T>}
+   * @returns {Record<string, import("./validators/base.js").default>}
    */
   static validatorTypes() {
     if (!this._validatorTypes) this._validatorTypes = {}
@@ -55,16 +54,14 @@ class VelociousDatabaseRecord {
 
   /**
    * @param {string} name
-   * @template T extends import("./validators/base.js").default
-   * @param {T} validatorClass
+   * @param {import("./validators/base.js").default} validatorClass
    */
   static registerValidatorType(name, validatorClass) {
     this.validatorTypes()[name] = validatorClass
   }
 
   /**
-   * @template T extends import("./validators/base.js").default
-   * @returns {T}
+   * @returns {import("./validators/base.js").default}
    */
   static getValidatorType(validatorName) {
     if (!(validatorName in this.validatorTypes())) throw new Error(`Validator type ${validatorName} not found`)
@@ -189,8 +186,7 @@ class VelociousDatabaseRecord {
   }
 
   /**
-   * @template T extends import("./relationships/index.js").default
-   * @returns {T}
+   * @returns {import("./relationships/base.js").default}
    */
   static getRelationshipByName(relationshipName) {
     if (!this._relationships) this._relationships = {}
@@ -203,7 +199,7 @@ class VelociousDatabaseRecord {
   }
 
   /**
-   * @returns {Array}
+   * @returns {Array<import("./relationships/base.js").default>}
    */
   static getRelationships() {
     if (this._relationships) return Object.values(this._relationships)
@@ -269,7 +265,7 @@ class VelociousDatabaseRecord {
   }
 
   /**
-   * @param {object} attributes
+   * @param {Record<string, any>} attributes
    * @returns {Promise<InstanceType<typeof this>>}
    */
   static async create(attributes) {
@@ -306,6 +302,7 @@ class VelociousDatabaseRecord {
    * Adds a has-many-relationship to the model class.
    * @param {string} relationshipName The name of the relationship (e.g. "posts")
    * @param {object} options The options for the relationship (e.g. {className: "Post"})
+   * @returns {void}
    */
   static hasMany(relationshipName, options = {}) {
     return this._defineRelationship(relationshipName, Object.assign({type: "hasMany"}, options))
@@ -315,6 +312,7 @@ class VelociousDatabaseRecord {
    * Adds a has-one-relationship to the model class.
    * @param {string} relationshipName The name of the relationship (e.g. "post")
    * @param {object} options The options for the relationship (e.g. {className: "Post"})
+   * @returns {void}
    */
   static hasOne(relationshipName, options = {}) {
     return this._defineRelationship(relationshipName, Object.assign({type: "hasOne"}, options))
@@ -526,6 +524,9 @@ class VelociousDatabaseRecord {
     return this._columnNames
   }
 
+  /**
+   * @returns {import("../drivers/base-table.js").default}
+   */
   static _getTable() {
     if (!this._table) throw new Error(`${this.name} hasn't been initialized yet`)
 
@@ -1045,7 +1046,7 @@ class VelociousDatabaseRecord {
 
   /**
    * Assigns the given attributes to the record.
-   * @param {object} attributesToAssign
+   * @param {Record<string, any>} attributesToAssign
    * @returns {void}
    */
   assign(attributesToAssign) {

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

@@ -1,7 +1,22 @@
 import restArgsError from "../../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseRecordBaseRelationship {
-  constructor({className, configuration, dependent, foreignKey, inverseOf, klass, modelClass, primaryKey = "id", relationshipName, through, type, ...restArgs}) { // eslint-disable-line no-unused-vars
+  /**
+   * @param {object} args
+   * @param {string} args.className
+   * @param {import("../../../configuration.js").default} args.configuration
+   * @param {string} args.dependent
+   * @param {boolean|object} args.foreignKey
+   * @param {string} args.inverseOf
+   * @param {typeof import("../index.js").default} args.klass
+   * @param {typeof import("../index.js").default} args.modelClass
+   * @param {string} args.primaryKey
+   * @param {boolean} args.polymorphic
+   * @param {string} args.relationshipName
+   * @param {string} args.through
+   * @param {string} args.type
+   */
+  constructor({className, configuration, dependent, foreignKey, inverseOf, klass, modelClass, primaryKey = "id", polymorphic, relationshipName, through, type, ...restArgs}) { // eslint-disable-line no-unused-vars
     restArgsError(restArgs)
 
     if (!modelClass) throw new Error(`'modelClass' wasn't given for ${relationshipName}`)
@@ -14,6 +29,7 @@ export default class VelociousDatabaseRecordBaseRelationship {
     this._inverseOf
     this.klass = klass
     this.modelClass = modelClass
+    this._polymorphic = polymorphic
     this._primaryKey = primaryKey
     this.relationshipName = relationshipName
     this.through = through
@@ -42,8 +58,7 @@ export default class VelociousDatabaseRecordBaseRelationship {
   }
 
   /**
-   * @template T extends import("../index.js").default
-   * @returns {typeof T}
+   * @returns {typeof import("../index.js").default}
    */
   getModelClass() { return this.modelClass }
 
@@ -52,6 +67,13 @@ export default class VelociousDatabaseRecordBaseRelationship {
    */
   getRelationshipName() { return this.relationshipName }
 
+  /**
+   * @returns {boolean}
+   */
+  getPolymorphic() {
+    return this._polymorphic
+  }
+
   /**
    * @returns {string} The name of the foreign key, e.g. "id" etc.
    */
@@ -63,11 +85,12 @@ export default class VelociousDatabaseRecordBaseRelationship {
   getType() { return this.type }
 
   /**
-   * @template T extends import("../index.js").default
-   * @returns {typeof T} The target model class for this relationship, e.g. if the relationship is "posts" then the target model class is the Post class.
+   * @returns {typeof import("../index.js").default} The target model class for this relationship, e.g. if the relationship is "posts" then the target model class is the Post class.
    */
   getTargetModelClass() {
-    if (this.className) {
+    if (this.getPolymorphic()) {
+      return null
+    } else if (this.className) {
       return this.modelClass._getConfiguration().getModelClass(this.className)
     } else if (this.klass) {
       return this.klass