velocious 1.0.85 → 1.0.87

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

@@ -6,12 +6,37 @@ export default class VelociousDatabaseRecordBaseInstanceRelationship {
     this.relationship = relationship
   }
 
+  /**
+   * @returns {boolean} Whether the relationship should be auto-saved before saving the parent model
+   */
   getAutoSave() { return this._autoSave }
+
+  /**
+   * @param {boolean} newAutoSaveValue Whether the relationship should be auto-saved before saving the parent model
+   * @returns {void}
+   */
   setAutoSave(newAutoSaveValue) { this._autoSave = newAutoSaveValue }
+
+  /**
+   * @param {boolean} newValue Whether the relationship is dirty (has been modified)
+   * @returns {void}
+   */
   setDirty(newValue) { this._dirty = newValue }
+
+  /**
+   * @returns {boolean} Whether the relationship is dirty (has been modified)
+   */
   getDirty() { return this._dirty }
+
+  /**
+   * @returns {boolean} Whether the relationship has been preloaded
+   */
   isLoaded() { return Boolean(this._loaded) }
 
+  /**
+   * @template T extends import("../index.js").default
+   * @returns {T|Array<T>} The loaded model or models (depending on relationship type)
+   */
   loaded() {
     if (!this._preloaded && this.model.isPersisted()) {
       throw new Error(`${this.model.constructor.name}#${this.relationship.getRelationshipName()} hasn't been preloaded`)
@@ -20,13 +45,53 @@ export default class VelociousDatabaseRecordBaseInstanceRelationship {
     return this._loaded
   }
 
+  /**
+   * @template T extends import("../index.js").default
+   * @param {T|Array<T>} model
+   */
   setLoaded(model) { this._loaded = model }
+
+  /**
+   * @template T extends import("../index.js").default
+   * @returns {T|Array<T>} The loaded model or models (depending on relationship type)
+   */
   getPreloaded() { return this._preloaded }
-  setPreloaded(preloadedValue) { this._preloaded = preloadedValue }
+
+  /**
+   * @template T extends import("../index.js").default
+   * @param {T|Array<T>} preloadedModelOrModels
+   */
+  setPreloaded(preloadedModelOrModels) { this._preloaded = preloadedModelOrModels }
+
+  /**
+   * @returns {string} The foreign key for this relationship
+   */
   getForeignKey() { return this.getRelationship().getForeignKey() }
+
+  /**
+   * @template T extends import("../index.js").default
+   * @returns {T} model
+   */
   getModel() { return this.model }
+
+  /**
+   * @returns {string} The primary key for this relationship's model
+   */
   getPrimaryKey() { return this.getRelationship().getPrimaryKey() }
+
+  /**
+   * @template T extends import("../relationships/base.js").default
+   * @returns {T} The relationship object that this instance relationship is based on
+   */
   getRelationship() { return this.relationship }
+
+  /**
+   * @returns {typeof import("../index.js").default} The model class that this instance relationship
+   */
   getTargetModelClass() { return this.getRelationship().getTargetModelClass() }
+
+  /**
+   * @returns {string} The type of relationship (e.g. "has_many", "belongs_to", etc.)
+   */
   getType() { return this.getRelationship().getType() }
 }

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

@@ -1,7 +1,7 @@
 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}) {
+  constructor({className, configuration, dependent, foreignKey, inverseOf, klass, modelClass, primaryKey = "id", relationshipName, through, type, ...restArgs}) { // eslint-disable-line no-unused-vars
     restArgsError(restArgs)
 
     if (!modelClass) throw new Error(`'modelClass' wasn't given for ${relationshipName}`)
@@ -20,12 +20,52 @@ export default class VelociousDatabaseRecordBaseRelationship {
     this.type = type
   }
 
+  /**
+   * @returns {string} What will be done when the parent record is destroyed. E.g. "destroy", "nullify", "restrict" etc.
+   */
   getDependent() { return this._dependent }
+
+  /**
+   * @interface
+   * @returns {string} The name of the foreign key, e.g. "user_id", "post_id" etc.
+   */
+  getForeignKey() {
+    throw new Error("getForeignKey not implemented")
+  }
+
+  /**
+   * @interface
+   * @returns {string} The name of the inverse relationship, e.g. "posts", "comments" etc.
+   */
+  getInverseOf() {
+    throw new Error("getInverseOf not implemented")
+  }
+
+  /**
+   * @template T extends import("../index.js").default
+   * @returns {typeof T}
+   */
   getModelClass() { return this.modelClass }
+
+  /**
+   * @returns {string} The name of the relationship, e.g. "posts", "user", "comments" etc.
+   */
   getRelationshipName() { return this.relationshipName }
+
+  /**
+   * @returns {string} The name of the foreign key, e.g. "id" etc.
+   */
   getPrimaryKey() { return this._primaryKey }
+
+  /**
+   * @returns {string} The type of the relationship, e.g. "has_many", "belongs_to", "has_one", "has_and_belongs_to_many" etc.
+   */
   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.
+   */
   getTargetModelClass() {
     if (this.className) {
       return this.modelClass._getConfiguration().getModelClass(this.className)

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

@@ -1,2 +1,12 @@
 export default class VelociousDatabaseRecordValidatorsBase {
+  /**
+   * @interface
+   * @template T extends import("../index.js").default
+   * @param {object} args
+   * @param {T} args.model
+   * @param {string} args.attributeName
+   */
+  async validate({model, attributeName}) { // eslint-disable-line no-unused-vars
+    throw new Error("validate not implemented")
+  }
 }

package/src/database/record/validators/presence.js

@@ -1,7 +1,7 @@
 import Base from "./base.js"
 
 export default class VelociousDatabaseRecordValidatorsPresence extends Base {
-  validate({model, attributeName}) {
+  async validate({model, attributeName}) {
     const attributeValue = model.readAttribute(attributeName)?.trim()
 
     if (!attributeValue) {

package/src/database/table-data/table-column.js

@@ -5,7 +5,7 @@ import TableForeignKey from "./table-foreign-key.js"
 export default class TableColumn {
   constructor(name, args) {
     if (args) {
-      const {autoIncrement, default: columnDefault, foreignKey, index, isNewColumn, maxLength, name, null: argsNull, primaryKey, type, ...restArgs} = args
+      const {autoIncrement, default: columnDefault, dropColumn, foreignKey, index, isNewColumn, maxLength, name, null: argsNull, primaryKey, type, ...restArgs} = args // eslint-disable-line no-unused-vars
 
       if (Object.keys(args).length == 0) {
         throw new Error("Empty args given")
@@ -18,19 +18,50 @@ export default class TableColumn {
     this.name = name
   }
 
+  /**
+   * @returns {string} name
+   */
   getName() { return this.name }
 
+  /**
+   * @returns {string}
+   */
   getNewName() { return this._newName }
+
+  /**
+   * @param {string} newName
+   * @returns {void}
+   */
   setNewName(newName) { this._newName = newName }
 
+  /**
+   * @returns {string}
+   */
   getActualName() { return this.getNewName() || this.getName() }
 
-  getAutoIncrement() { return this.args?.autoIncrement }
+  /**
+   * @returns {boolean}
+   */
+  getAutoIncrement() { return this.args?.autoIncrement || false }
+
+  /**
+   * @param {boolean} newAutoIncrement
+   * @returns {void}
+   */
   setAutoIncrement(newAutoIncrement) { this.args.autoIncrement = newAutoIncrement }
 
   getDefault() { return this.args?.default }
+
+  /**
+   * @returns {void}
+   */
   setDefault(newDefault) { this.args.default = newDefault }
 
+  /**
+   * @returns {boolean}
+   */
+  getDropColumn() { return this.args?.dropColumn || false }
+
   getForeignKey() { return this.args?.foreignKey }
   setForeignKey(newForeignKey) { this.args.foreignKey = newForeignKey }
 
@@ -49,7 +80,10 @@ export default class TableColumn {
   getType() { return this.args?.type }
   setType(newType) { this.args.type = newType }
 
-  isNewColumn() { return this.args?.isNewColumn }
+  /**
+   * @returns {boolean}
+   */
+  isNewColumn() { return this.args?.isNewColumn || false }
 
   getSQL({forAlterTable, driver}) {
     const databaseType = driver.getType()

package/src/database/table-data/table-index.js

@@ -3,7 +3,7 @@ import restArgsError from "../../utils/rest-args-error.js"
 export default class TableIndex {
   constructor(columns, args) {
     if (args) {
-      const {name, unique, ...restArgs} = args
+      const {name, unique, ...restArgs} = args // eslint-disable-line no-unused-vars
 
       restArgsError(restArgs)
     }

package/src/database/use-database.js

@@ -5,7 +5,7 @@ import Configuration from "../configuration.js"
 import Migrator from "./migrator.js"
 import restArgsError from "../utils/rest-args-error.js"
 
-const loadMigrations = function loadMigrations({migrationsRequireContext, ...restArgs}) {
+const loadMigrations = function loadMigrations({migrationsRequireContextCallback, ...restArgs}) {
   const instance = React.useMemo(() => ({running: false}), [])
   const {isServer} = useEnvSense()
   const [loaded, setLoaded] = React.useState(false)
@@ -18,7 +18,7 @@ const loadMigrations = function loadMigrations({migrationsRequireContext, ...res
         const migrator = new Migrator({configuration: Configuration.current()})
 
         await migrator.prepare()
-        await migrator.migrateFilesFromRequireContext(migrationsRequireContext)
+        await migrator.migrateFilesFromRequireContext(await migrationsRequireContextCallback())
       })
 
       await Configuration.current().initialize()

package/src/environment-handlers/base.js

@@ -0,0 +1,53 @@
+export default class VelociousEnvironmentHandlerBase {
+  /**
+   * @interface
+   */
+  async findCommands() { throw new Error("findCommands not implemented") }
+
+  /**
+   * @interface
+   */
+  async findMigrations() { throw new Error("findMigrations not implemneted") }
+
+  /**
+   * @interface
+   */
+  async getVelociousPath() { throw new Error("getVelociousPath not implemented") }
+
+  /**
+   * @interface
+   */
+  async importApplicationRoutes() { throw new Error("importApplicationRoutes not implemented") }
+
+  /**
+   * @interface
+   */
+  async requireCommand({commandParts}) { throw new Error("requireCommand not implemented") } // eslint-disable-line no-unused-vars
+
+  /**
+   * @param {object} newArgs
+   * @returns {void}
+   */
+  setArgs(newArgs) { this.args = newArgs }
+
+  /**
+   * @param {import("../configuration.js").default} newConfiguration
+   * @returns {void}
+   */
+  setConfiguration(newConfiguration) { this.configuration = newConfiguration }
+
+  /**
+   * @returns {import("../configuration.js").default}
+   */
+  getConfiguration() {
+    if (!this.configuration) throw new Error("Configuration hasn't been set")
+
+    return this.configuration
+  }
+
+  /**
+   * @param {string[]} newProcessArgs
+   * @returns {void}
+   */
+  setProcessArgs(newProcessArgs) { this.processArgs = newProcessArgs }
+}

package/src/environment-handlers/browser.js

@@ -0,0 +1,171 @@
+import Base from "./base.js"
+import {digg} from "diggerize"
+import * as inflection from "inflection"
+import restArgsError from "../utils/rest-args-error.js"
+
+export default class VelociousEnvironmentsHandlerBrowser extends Base {
+  /**
+   * @param {object} args
+   * @param {function() : void} args.migrationsRequireContextCallback
+   */
+  constructor({migrationsRequireContextCallback, ...restArgs} = {}) {
+    super()
+    restArgsError(restArgs)
+
+    this.migrationsRequireContextCallback = migrationsRequireContextCallback
+  }
+
+  /**
+   * @returns {object}
+   */
+  migrationsRequireContext() {
+    const migrationsRequireContextCallback = digg(this, "migrationsRequireContextCallback")
+
+    if (!migrationsRequireContextCallback) throw new Error("migrationsRequireContextCallback is required")
+
+    this._migrationsRequireContextResult ||= migrationsRequireContextCallback()
+
+    return this._migrationsRequireContextResult
+  }
+
+  /**
+   * @returns {Promise<Array<{name: string, file: string}>>}
+   */
+  findCommands() {
+    this._findCommandsResult = this._actualFindCommands()
+
+    return this._findCommandsResult
+  }
+
+  _findCommandsRequireContext() {
+    this.findCommandsRequireContextResult ||= require.context("../cli/commands", true, /\.js$/)
+
+    return this.findCommandsRequireContextResult
+  }
+
+  _actualFindCommands() {
+    const commandFiles = this._findCommandsRequireContext()
+    const commands = []
+
+    for (const aFilePath of commandFiles.keys()) {
+      const aFilePathParts = aFilePath.split("/")
+      const lastPart = aFilePathParts[aFilePathParts.length - 1]
+      let name
+
+      if (lastPart == "index.js") {
+        name = aFilePathParts[aFilePathParts.length - 2]
+      } else {
+        name = lastPart.replace(".js", "")
+      }
+
+      commands.push({name, file: aFilePath})
+    }
+
+    return commands
+  }
+
+  /**
+   * @param {Array<string>} commandParts
+   * @template T extends import("./base-command.js").default
+   * @returns {Promise<T>}
+   */
+  async requireCommand({commandParts, ...restArgs}) {
+    restArgsError(restArgs)
+
+    let filePath = "."
+
+    for (let commandPart of commandParts) {
+      if (commandPart == "d") commandPart = "destroy"
+      if (commandPart == "g") commandPart = "generate"
+      if (commandPart == "s") commandPart = "server"
+
+      filePath += `/${commandPart}`
+    }
+
+    const filePaths = []
+
+    filePaths.push(`${filePath}/index.js`)
+    filePath += ".js"
+    filePaths.push(filePath)
+
+    const commandsRequireContext = await this._findCommandsRequireContext()
+    let commandClassImport
+
+    for (const aFilePath of filePaths) {
+      commandClassImport = commandsRequireContext(aFilePath)
+
+      if (commandClassImport) {
+        break
+      }
+    }
+
+    if (!commandClassImport) {
+      throw new Error(`Unknown command: ${commandParts.join(":")}. Possible commands: ${commandsRequireContext.keys()}`)
+    }
+
+    const CommandClass = commandClassImport.default
+
+    return CommandClass
+  }
+
+  /**
+   * @returns {Promise<Array<{name: string, file: string}>>}
+   */
+  async findMigrations() {
+    const migrationsRequireContext = await this.migrationsRequireContext()
+    const files = migrationsRequireContext
+      .keys()
+      .map((file) => {
+        // "13,14" because somes "require-context"-npm-module deletes first character!?
+        const match = file.match(/(\d{13,14})-(.+)\.js$/)
+
+        if (!match) return null
+
+        // Fix require-context-npm-module deletes first character
+        let fileName = file
+        let dateNumber = match[1]
+
+        if (dateNumber.length == 13) {
+          dateNumber = `2${dateNumber}`
+          fileName = `2${fileName}`
+        }
+
+        // Parse regex
+        const date = parseInt(dateNumber)
+        const migrationName = match[2]
+        const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
+
+        return {
+          file: fileName,
+          fullPath: file,
+          date,
+          migrationClassName
+        }
+      })
+      .filter((migration) => Boolean(migration))
+      .sort((migration1, migration2) => migration1.date - migration2.date)
+
+    return files
+  }
+
+  /**
+   * @param {string} filePath
+   * @template T extends import("../migration/index.js").default
+   * @returns {Promise<T>}
+   */
+  requireMigration = async (filePath) => {
+    if (!filePath) throw new Error("filePath is required")
+
+    const migrationsRequireContext = await this.migrationsRequireContext()
+    const migrationImport = migrationsRequireContext(filePath)
+
+    if (!migrationImport) throw new Error(`Migration file ${filePath} not found`)
+
+    const migrationImportDefault = migrationImport.default
+
+    if (!migrationImportDefault) throw new Error("Migration file must export a default migration class")
+    if (typeof migrationImportDefault !== "function") throw new Error("Migration default export isn't a function (should be a class which is a function in JS)")
+
+    return migrationImportDefault
+  }
+}

package/src/environment-handlers/node.js

@@ -0,0 +1,162 @@
+import Base from "./base.js"
+import {dirname} from "path"
+import {fileURLToPath} from "url"
+import fs from "fs/promises"
+import * as inflection from "inflection"
+import path from "path"
+
+export default class VelociousEnvironmentHandlerNode extends Base{
+  /**
+   * @returns {Promise<Array<{name: string, file: string}>>}
+   */
+  async findCommands() {
+    this._findCommandsResult ||= this._actualFindCommands()
+
+    return this._findCommandsResult
+  }
+
+  async _actualFindCommands() {
+    const basePath = await this.getBasePath()
+    const commandFiles = fs.glob(`${basePath}/src/cli/commands/**/*.js`)
+    const commands = []
+
+    for await (const aFilePath of commandFiles) {
+      const aFilePathParts = aFilePath.split("/")
+      const commandPathLocation = aFilePathParts.indexOf("commands") + 1
+      const lastPart = aFilePathParts[aFilePathParts.length - 1]
+      let name, paths
+
+      if (lastPart == "index.js") {
+        name = aFilePathParts[aFilePathParts.length - 2]
+        paths = aFilePathParts.slice(commandPathLocation, -2)
+      } else {
+        name = lastPart.replace(".js", "")
+        paths = aFilePathParts.slice(commandPathLocation, -1)
+      }
+
+      const commandName = `${paths.join(":")}${paths.length > 0 ? ":" : ""}${name}`
+
+      commands.push({name: commandName, file: aFilePath})
+    }
+
+    return commands
+  }
+
+  /**
+   * @param {Array<string>} commandParts
+   * @template T extends import ("./base-command.js").default
+   * @returns {Promise<T>}
+   */
+  async requireCommand({commandParts}) {
+    const commands = await this.findCommands()
+    const command = commands.find((aCommand) => aCommand.name === commandParts.join(":"))
+
+    if (!command) {
+      const possibleCommands = commands.map(aCommand => aCommand.name)
+
+      throw new Error(`Unknown command: ${this.args.processArgs[0]} which should have been one of: ${possibleCommands.sort().join(", ")}`)
+    }
+
+    const commandClassImport = await import(command.file)
+    const CommandClass = commandClassImport.default
+
+    return CommandClass
+  }
+
+  /**
+   * @returns {Promise<Array<{name: string, file: string}>>}
+   */
+  async findMigrations() {
+    const migrationsPath = `${this.getConfiguration().getDirectory()}/src/database/migrations`
+    const glob = await fs.glob(`${migrationsPath}/**/*.js`)
+    const files = []
+
+    for await (const fullPath of glob) {
+      const file = await path.basename(fullPath)
+
+      files.push(file)
+    }
+
+    const migrationFiles = files
+      .map((file) => {
+        const match = file.match(/^(\d{14})-(.+)\.js$/)
+
+        if (!match) return null
+
+        const date = parseInt(match[1])
+        const migrationName = match[2]
+        const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
+
+        return {
+          file,
+          fullPath: `${migrationsPath}/${file}`,
+          date,
+          migrationClassName
+        }
+      })
+      .filter((migration) => Boolean(migration))
+      .sort((migration1, migration2) => migration1.date - migration2.date)
+
+    return migrationFiles
+  }
+
+  /**
+   * @returns {Promise<import("../routes/index.js").default>}
+   */
+  async importApplicationRoutes() {
+    const routesImport = await import(`${this.getConfiguration().getDirectory()}/src/config/routes.js`)
+
+    return routesImport.default
+  }
+
+  /**
+   * @returns {string}
+   */
+  async getVelociousPath() {
+    if (!this._velociousPath) {
+      const __filename = fileURLToPath(import.meta.url)
+      const __dirname = dirname(__filename)
+
+      this._velociousPath = await fs.realpath(`${__dirname}/../..`)
+    }
+
+    return this._velociousPath
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async importTestFiles(testFiles) {
+    for (const testFile of testFiles) {
+      await import(testFile)
+    }
+  }
+
+  async importTestingConfigPath() {
+    const testingConfigPath = this.getConfiguration().getTesting()
+
+    await import(testingConfigPath)
+  }
+
+  /**
+   * @param {string} filePath
+   * @template T extends import ("../migration/index.js").default
+   * @returns {Promise<T>}
+   */
+  async requireMigration(filePath) {
+    const migrationImport = await import(filePath)
+    const migrationImportDefault = migrationImport.default
+
+    if (!migrationImportDefault) throw new Error("Migration file must export a default migration class")
+    if (typeof migrationImportDefault !== "function") throw new Error("Migration default export isn't a function (should be a class which is a function in JS)")
+
+    return migrationImportDefault
+  }
+
+  async getBasePath() {
+    const __filename = fileURLToPath(import.meta.url)
+    const basePath = await fs.realpath(`${dirname(__filename)}/../..`)
+
+    return basePath
+  }
+}