velocious 1.0.431 → 1.0.433

package/build/environment-handlers/node/cli/commands/db/schema/load.js

@@ -0,0 +1,69 @@
+import BaseCommand from "../../../../../../cli/base-command.js"
+import fs from "fs/promises"
+import path from "path"
+import splitSqlStatements from "../../../../../../utils/split-sql-statements.js"
+
+/** Node CLI command for loading DB structure SQL files. */
+export default class DbSchemaLoad extends BaseCommand {
+  /**
+   * Runs execute.
+    @returns {Promise<void>} */
+  async execute() {
+    await this.getConfiguration().ensureConnections({name: "DB schema load"}, async (dbs) => {
+      const dbDir = path.join(this.directory(), "db")
+
+      for (const identifier of Object.keys(dbs)) {
+        const db = dbs[identifier]
+        const structureFilePath = path.join(dbDir, `structure-${identifier}.sql`)
+        const structureSql = await fs.readFile(structureFilePath, "utf8")
+
+        await this.loadStructureSql({db, structureSql})
+      }
+    })
+  }
+
+  /**
+   * Runs load structure sql.
+   * @param {object} args - Options object.
+   * @param {import("../../../../../../database/drivers/base.js").default} args.db - Database connection.
+   * @param {string} args.structureSql - Structure SQL to load.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async loadStructureSql({db, structureSql}) {
+    const statements = splitSqlStatements(structureSql)
+
+    if (statements.length == 0) return
+
+    const executableConnection = this.executableConnection(db)
+
+    await db.disableForeignKeys()
+
+    try {
+      if (executableConnection) {
+        await executableConnection.exec(structureSql)
+      } else {
+        for (const statement of statements) {
+          await db.query(statement)
+        }
+      }
+    } finally {
+      await db.enableForeignKeys()
+    }
+  }
+
+  /**
+   * Runs executable connection.
+   * @param {import("../../../../../../database/drivers/base.js").default} db - Database connection.
+   * @returns {{exec: (sql: string) => Promise<?>} | undefined} - Connection with exec support.
+   */
+  executableConnection(db) {
+    const dbWithConnection = /**
+                              * Narrows the runtime value to the documented type.
+                               @type {import("../../../../../../database/drivers/base.js").default & {connection?: ?}} */ (db)
+    const connection = dbWithConnection.connection
+
+    if (connection && typeof connection == "object" && "exec" in connection && typeof connection.exec == "function") {
+      return /** Narrows the runtime value to the documented type. @type {{exec: (sql: string) => Promise<?>}} */ (connection)
+    }
+  }
+}

package/build/environment-handlers/node/cli/commands/db/seed.js

@@ -0,0 +1,79 @@
+import BaseCommand from "../../../../../cli/base-command.js"
+import buildCliCommandContext from "../cli-command-context.js"
+import path from "node:path"
+import toImportSpecifier from "../../../../../utils/to-import-specifier.js"
+
+/**
+ * RunnerContext type.
+ * @typedef {import("../cli-command-context.js").CliCommandContext} RunnerContext
+ */
+
+/**
+ * Runs import runner function.
+ * @param {string} filePath - Absolute path to script file.
+ * @returns {Promise<(context: RunnerContext) => Promise<?>>} - The default-exported async function.
+ */
+async function importRunnerFunction(filePath) {
+  const runnerImport = await import(toImportSpecifier(filePath))
+  const runnerFunction = runnerImport.default
+
+  if (typeof runnerFunction !== "function") {
+    throw new Error(`Expected default export to be a function in: ${filePath}`)
+  }
+
+  return runnerFunction
+}
+
+/** Node command for running project database seeds from src/db/seed.js. */
+export default class DbSeed extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<?>} - Resolves with the seed function result.
+   */
+  async execute() {
+    const configuration = this.getConfiguration()
+
+    await this.initializeRuntime()
+
+    try {
+      await configuration.ensureGlobalConnections()
+
+      const seedPath = this.seedFilePath()
+      const runnerFunction = await importRunnerFunction(seedPath)
+
+      return await runnerFunction(this.buildRunnerContext())
+    } finally {
+      await configuration.closeDatabaseConnections()
+    }
+  }
+
+  /**
+   * Runs initialize runtime.
+   * @returns {Promise<void>} - Resolves when runtime initialization is complete.
+   */
+  async initializeRuntime() {
+    const configuration = this.getConfiguration()
+
+    await configuration.initialize({type: "db-seed"})
+
+    if (!configuration.isDatabasePoolInitialized()) {
+      configuration.initializeDatabasePool()
+    }
+  }
+
+  /**
+   * Runs seed file path.
+   * @returns {string} - Absolute path to src/db/seed.js.
+   */
+  seedFilePath() {
+    return path.join(this.directory(), "src", "db", "seed.js")
+  }
+
+  /**
+   * Runs build runner context.
+   * @returns {RunnerContext} - Runtime context passed to the script function.
+   */
+  buildRunnerContext() {
+    return buildCliCommandContext(this, 1)
+  }
+}

package/build/environment-handlers/node/cli/commands/destroy/migration.js

@@ -0,0 +1,47 @@
+import BaseCommand from "../../../../../cli/base-command.js"
+import fs from "fs/promises"
+
+/**
+ * DbDestroyMigration class.
+ * @typedef {{destroyed: string[]}} DestroyMigrationResult
+ */
+
+export default class DbDestroyMigration extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<void | DestroyMigrationResult>} - Resolves with the execute.
+   */
+  async execute() {
+    const migrationName = this.processArgs?.[1]
+
+    if (!migrationName) throw new Error("Expected migration name")
+
+    const migrationDir = `${this.getConfiguration().getDirectory()}/src/database/migrations`
+    const migrationFiles = await fs.readdir(migrationDir)
+    const destroyed = []
+
+    for (const migrationFile of migrationFiles) {
+      const match = migrationFile.match(/^(\d{14})-(.+)\.js$/)
+
+      if (!match) {
+        continue
+      }
+
+      const fileName = match[2]
+
+      if (fileName != migrationName) continue
+
+      const fullFilePath = `${migrationDir}/${migrationFile}`
+      destroyed.push(fileName)
+
+      if (!this.args.testing) {
+        console.log(`Destroy src/database/migrations/${migrationFile}`)
+        await fs.unlink(fullFilePath)
+      }
+    }
+
+    if (this.args.testing) {
+      return {destroyed}
+    }
+  }
+}

package/build/environment-handlers/node/cli/commands/generate/base-models.js

@@ -0,0 +1,396 @@
+import BaseCommand from "../../../../../cli/base-command.js"
+import fileExists from "../../../../../utils/file-exists.js"
+import fs from "fs/promises"
+import * as inflection from "inflection"
+
+/** Maps an effective column type to the JSDoc type used in generated base models.
+ *  @type {Record<string, string>} */
+const jsDocTypeByColumnType = {
+  bigint: "number",
+  bit: "number",
+  blob: "string",
+  boolean: "boolean",
+  char: "string",
+  "character varying": "string",
+  date: "Date",
+  datetime: "Date",
+  decimal: "number",
+  float: "number",
+  int: "number",
+  integer: "number",
+  json: "Record<string, ?>",
+  longtext: "string",
+  mediumtext: "string",
+  numeric: "number",
+  nvarchar: "string",
+  smallint: "number",
+  text: "string",
+  "timestamp without time zone": "Date",
+  tinyint: "number",
+  tinytext: "string",
+  uuid: "string",
+  varchar: "string"
+}
+
+/** Effective column types whose generated setter additionally accepts a string. */
+const setterStringInputColumnTypes = new Set(["date", "datetime", "timestamp without time zone"])
+
+export default class DbGenerateModel extends BaseCommand {
+  async execute() {
+    await this.getConfiguration().initializeModels()
+
+    const enforceTenantDatabaseScopes = this.getConfiguration().getEnforceTenantDatabaseScopes()
+
+    const rootDirectory = this.directory()
+    const modelsDir = `${rootDirectory}/src/models`
+    const baseModelsDir = `${rootDirectory}/src/model-bases`
+    const modelClasses = this.getConfiguration().getModelClasses()
+    const allowMissingTables = Boolean(this.processArgs?.includes("--allow-missing-tables"))
+    let devMode = false
+
+    if (baseModelsDir.includes("/spec/dummy/src/model-bases")) {
+      devMode = true
+    }
+
+    if (!await fileExists(baseModelsDir)) {
+      await fs.mkdir(baseModelsDir, {recursive: true})
+    }
+
+    this.getConfiguration().setEnforceTenantDatabaseScopes(false)
+
+    try {
+      await this.getConfiguration().ensureConnections({name: "Generate base models"}, async () => {
+        for (const modelClassName in modelClasses) {
+        const modelClass = modelClasses[modelClassName]
+        const table = await modelClass.connection().getTableByName(modelClass.tableName(), {throwError: !allowMissingTables})
+
+        if (!table) {
+          console.warn(`Skipping base model for '${modelClass.name}': table '${modelClass.tableName()}' was not found (--allow-missing-tables). Keeping any existing base model.`)
+
+          continue
+        }
+
+        const modelName = inflection.dasherize(modelClassName)
+        const modelNameCamelized = inflection.camelize(modelName.replaceAll("-", "_"))
+        const modelBaseFileName = `${inflection.dasherize(inflection.underscore(modelName))}.js`
+        const modelPath = `${baseModelsDir}/${modelBaseFileName}`
+
+        console.log(`create src/model-bases/${modelBaseFileName}`)
+
+        const sourceModelFullFilePath = `${modelsDir}/${modelBaseFileName}`
+        let sourceModelFilePath
+
+        if (await fileExists(sourceModelFullFilePath)) {
+          sourceModelFilePath = `../models/${modelBaseFileName}`
+        } else {
+          sourceModelFilePath = "velocious/build/src/database/record/index.js"
+        }
+
+        let fileContent = ""
+        let velociousPath
+
+        if (devMode) {
+          velociousPath = "../../../../src"
+        } else {
+          velociousPath = "velocious/build/src"
+        }
+
+        fileContent += `import DatabaseRecord from "${velociousPath}/database/record/index.js"\n\n`
+
+        const hasManyRelationFilePath = `${velociousPath}/database/record/instance-relationships/has-many.js`
+
+        fileContent += `export default class ${modelNameCamelized}Base extends DatabaseRecord {\n`
+
+      // --- getModelClass() override (fixes polymorphic typing in JS/JSDoc) ---
+      if (await fileExists(sourceModelFullFilePath)) {
+        // Model file exists (e.g. src/models/ticket.js) → return typeof Ticket
+        fileContent += "  /**\n"
+        fileContent += `   * @returns {typeof import("${sourceModelFilePath}").default}\n`
+        fileContent += "   */\n"
+        fileContent += "  // @ts-ignore - override narrows return type for better IntelliSense in generated model bases\n"
+        fileContent += `  getModelClass() { return /** @type {typeof import("${sourceModelFilePath}").default} */ (this.constructor) }\n\n`
+      } else {
+        // No model file yet → fall back to typeof TicketBase
+        fileContent += "  /**\n"
+        fileContent += `   * @returns {typeof ${modelNameCamelized}Base}\n`
+        fileContent += "   */\n"
+        fileContent += "  // @ts-ignore - override narrows return type for better IntelliSense in generated model bases\n"
+        fileContent += `  getModelClass() { return /** @type {typeof ${modelNameCamelized}Base} */ (this.constructor) }\n\n`
+      }
+
+      const columns = await table.getColumns()
+      let methodsCount = 0
+
+      for (const column of columns) {
+        const camelizedColumnName = inflection.camelize(column.getName(), true)
+        const camelizedColumnNameBigFirst = inflection.camelize(column.getName())
+        const jsdocType = this.jsDocTypeFromColumn(column, modelClass)
+
+        if (methodsCount > 0) {
+          fileContent += "\n"
+        }
+
+        if (jsdocType) {
+          fileContent += "  /**\n"
+          fileContent += `   * @returns {${jsdocType}${column.getNull() ? " | null" : ""}}\n`
+          fileContent += "   */\n"
+        }
+
+        fileContent += `  ${camelizedColumnName}() { return this.readAttribute("${camelizedColumnName}") }\n\n`
+
+        const setterJsdocType = this.jsDocSetterTypeFromColumn(column, modelClass)
+
+        if (setterJsdocType) {
+          fileContent += "  /**\n"
+          fileContent += `   * @param {${setterJsdocType}${column.getNull() ? " | null" : ""}} newValue\n`
+          fileContent += "   * @returns {void}\n"
+          fileContent += "   */\n"
+        }
+
+        fileContent += `  set${camelizedColumnNameBigFirst}(newValue) { return this._setColumnAttribute("${camelizedColumnName}", newValue) }\n\n`
+
+        fileContent += "  /**\n"
+        fileContent += "   * @returns {boolean}\n"
+        fileContent += "   */\n"
+        fileContent += `  has${camelizedColumnNameBigFirst}() { return this._hasAttribute(this.${camelizedColumnName}()) }\n`
+
+        methodsCount++
+      }
+
+      if (Object.prototype.hasOwnProperty.call(modelClass, "_translations") && modelClass._translations && Object.keys(modelClass._translations).length > 0) {
+        const TranslationClass = modelClass.getTranslationClass()
+        const translationColumns = TranslationClass.getColumns()
+
+        for (const name in modelClass._translations) {
+          const nameUnderscore = inflection.underscore(name)
+          const column = translationColumns.find((translationColumn) => translationColumn.getName() === nameUnderscore)
+          let translationJsdocType
+
+          if (column) {
+            translationJsdocType = this.jsDocTypeFromColumn(column, TranslationClass)
+          }
+
+          if (translationJsdocType && column) {
+            fileContent += `\n`
+            fileContent += "  /**\n"
+            fileContent += `   * @returns {${translationJsdocType}${column.getNull() ? " | null" : ""}}\n`
+            fileContent += "   */\n"
+          }
+
+          fileContent += `  ${name}() { return this._getTranslatedAttributeWithFallback("${name}", this._getConfiguration().getLocale()) ?? null }\n`
+          methodsCount++
+
+          const hasName = `has${inflection.camelize(name)}`
+          const setterName = `set${inflection.camelize(name)}`
+          const setterParamType = translationJsdocType || "?"
+
+          fileContent += `\n`
+          fileContent += "  /**\n"
+          fileContent += `   * @abstract\n`
+          fileContent += `   * @returns {boolean}\n`
+          fileContent += "   */\n"
+          fileContent += `  ${hasName}() { throw new Error("${hasName} not implemented") }\n`
+          methodsCount++
+
+          fileContent += `\n`
+          fileContent += "  /**\n"
+          fileContent += `   * @param {${setterParamType}} newValue\n`
+          fileContent += `   * @returns {void}\n`
+          fileContent += "   */\n"
+          fileContent += `  ${setterName}(newValue) { return this._setTranslatedAttribute("${name}", this._getConfiguration().getLocale(), newValue) }\n`
+          methodsCount++
+
+          for (const locale of this.getConfiguration().getLocales()) {
+            const localeMethodName = `${name}${inflection.camelize(locale)}`
+
+            if (translationJsdocType && column) {
+              fileContent += `\n`
+              fileContent += "  /**\n"
+              fileContent += `   * @returns {${translationJsdocType}${column.getNull() ? " | null" : ""}}\n`
+              fileContent += "   */\n"
+            }
+
+            fileContent += `  ${localeMethodName}() { return this._getTranslatedAttributeWithFallback("${name}", "${locale}") ?? null }\n`
+            methodsCount++
+
+            const localeSetterName = `${setterName}${inflection.camelize(locale)}`
+
+            fileContent += `\n`
+            fileContent += "  /**\n"
+            fileContent += `   * @param {${setterParamType}} newValue\n`
+            fileContent += `   * @returns {void}\n`
+            fileContent += "   */\n"
+            fileContent += `  ${localeSetterName}(newValue) { return this._setTranslatedAttribute("${name}", "${locale}", newValue) }\n`
+            methodsCount++
+
+            const localeHasName = `has${inflection.camelize(localeMethodName)}`
+
+            fileContent += `\n`
+            fileContent += "  /**\n"
+            fileContent += `   * @abstract\n`
+            fileContent += `   * @returns {boolean}\n`
+            fileContent += "   */\n"
+            fileContent += `  ${localeHasName}() { throw new Error("${localeHasName} not implemented") }\n`
+            methodsCount++
+          }
+        }
+      }
+
+      for (const relationship of modelClass.getRelationships()) {
+        let baseFilePath, baseFullFilePath, fileName, fullFilePath
+
+        if (relationship.getPolymorphic()) {
+          fileName = "velocious/build/src/database/record/index.js"
+        } else {
+          const targetModelClass = relationship.getTargetModelClass()
+
+          if (!targetModelClass) throw new Error(`Relationship '${relationship.getRelationshipName()}' on '${modelClass.getModelName()}' has no target model class`)
+
+          fileName = inflection.dasherize(inflection.underscore(targetModelClass.getModelName()))
+          fullFilePath = `src/models/${fileName}.js`
+          baseFilePath = `../model-bases/${fileName}.js`
+          baseFullFilePath = `src/model-bases/${fileName}.js`
+        }
+
+        if (methodsCount > 0) {
+          fileContent += "\n"
+        }
+
+        if (relationship.getType() == "belongsTo" || relationship.getType() == "hasOne") {
+          let modelFilePath
+
+          if (fullFilePath && await fileExists(fullFilePath)) {
+            modelFilePath = `../models/${fileName}.js`
+          } else if (baseFullFilePath && await fileExists(baseFullFilePath)) {
+            modelFilePath = baseFilePath
+          } else {
+            modelFilePath = "velocious/build/src/database/record/index.js"
+          }
+
+          fileContent += "  /**\n"
+          fileContent += `   * @returns {import("${modelFilePath}").default}\n`
+          fileContent += "   */\n"
+          fileContent += `  ${relationship.getRelationshipName()}() { return /** @type {import("${modelFilePath}").default} */ (this.getRelationshipByName("${relationship.getRelationshipName()}").loaded()) }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += "   * @abstract\n"
+          fileContent += "   * @param {Record<string, ?>} [attributes]\n"
+          fileContent += `   * @returns {import("${modelFilePath}").default}\n`
+          fileContent += "   */\n"
+          fileContent += `  build${inflection.camelize(relationship.getRelationshipName())}(attributes) { void attributes; throw new Error("Not implemented") }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += "   * @abstract\n"
+          fileContent += `   * @returns {Promise<import("${modelFilePath}").default | undefined>}\n`
+          fileContent += "   */\n"
+          fileContent += `  load${inflection.camelize(relationship.getRelationshipName())}() { throw new Error("Not implemented") }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += `   * @returns {Promise<import("${modelFilePath}").default | undefined>}\n`
+          fileContent += "   */\n"
+          fileContent += `  ${relationship.getRelationshipName()}OrLoad() { return /** @type {Promise<import("${modelFilePath}").default | undefined>} */ (this.relationshipOrLoad("${relationship.getRelationshipName()}")) }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += "   * @abstract\n"
+          fileContent += `   * @param {import("${modelFilePath}").default} newModel\n`
+          fileContent += `   * @returns {void}\n`
+          fileContent += "   */\n"
+          fileContent += `  set${inflection.camelize(relationship.getRelationshipName())}(newModel) { void newModel; throw new Error("Not implemented") }\n`
+        } else if (relationship.getType() == "hasMany") {
+          let recordImport
+
+          if (fullFilePath && await fileExists(fullFilePath)) {
+            recordImport = `../models/${fileName}.js`
+          } else if (baseFullFilePath && await fileExists(baseFullFilePath)) {
+            recordImport = `../model-bases/${fileName}.js`
+          } else {
+            recordImport = `${velociousPath}/database/record/index.js`
+          }
+
+          fileContent += "  /**\n"
+          fileContent += `   * @returns {import("${hasManyRelationFilePath}").default<typeof import("${sourceModelFilePath}").default, typeof import("${recordImport}").default>}\n`
+          fileContent += "   */\n"
+          fileContent += `  ${relationship.getRelationshipName()}() { return /** @type {import("${hasManyRelationFilePath}").default<typeof import("${sourceModelFilePath}").default, typeof import("${recordImport}").default>} */ (this.getRelationshipByName("${relationship.getRelationshipName()}")) }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += `   * @returns {Array<import("${recordImport}").default>}\n`
+          fileContent += "   */\n"
+          fileContent += `  ${relationship.getRelationshipName()}Loaded() { return /** @type {Array<import("${recordImport}").default>} */ (this.getRelationshipByName("${relationship.getRelationshipName()}").loaded()) }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += "   * @abstract\n"
+          fileContent += `   * @returns {Promise<Array<import("${recordImport}").default>>}\n`
+          fileContent += "   */\n"
+          fileContent += `  load${inflection.camelize(relationship.getRelationshipName())}() { throw new Error("Not implemented") }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += `   * @returns {Promise<Array<import("${recordImport}").default>>}\n`
+          fileContent += "   */\n"
+          fileContent += `  ${relationship.getRelationshipName()}OrLoad() { return /** @type {Promise<Array<import("${recordImport}").default>>} */ (this.relationshipOrLoad("${relationship.getRelationshipName()}")) }\n`
+
+          fileContent += "\n"
+          fileContent += "  /**\n"
+          fileContent += "   * @abstract\n"
+          fileContent += `   * @param {Array<import("${recordImport}").default>} newModels\n`
+          fileContent += "   * @returns {void}\n"
+          fileContent += "   */\n"
+          fileContent += `  set${inflection.camelize(relationship.getRelationshipName())}(newModels) { void newModels; throw new Error("Not implemented") }\n`
+        } else {
+          throw new Error(`Unknown relationship type: ${relationship.getType()}`)
+        }
+
+        methodsCount++
+      }
+
+      fileContent += "}\n"
+
+        await fs.writeFile(modelPath, fileContent)
+        }
+      })
+    } finally {
+      this.getConfiguration().setEnforceTenantDatabaseScopes(enforceTenantDatabaseScopes)
+    }
+  }
+
+  /**
+   * Runs js doc type from column.
+   * @param {import("../../../../../database/drivers/base-column.js").default} column - Column.
+   * @param {typeof import("../../../../../database/record/index.js").default} modelClass - Model class owning the column (for declared attribute casts).
+   * @returns {string | undefined} - The js doc type from column.
+   */
+  jsDocTypeFromColumn(column, modelClass) {
+    const type = modelClass.getColumnTypeByName(column.getName())
+    const jsDocType = type ? jsDocTypeByColumnType[type] : undefined
+
+    if (!jsDocType) {
+      console.error(`Unknown column type: ${type}`)
+
+      return undefined
+    }
+
+    return jsDocType
+  }
+
+  /**
+   * Runs js doc setter type from column.
+   * @param {import("../../../../../database/drivers/base-column.js").default} column - Column.
+   * @param {typeof import("../../../../../database/record/index.js").default} modelClass - Model class owning the column (for declared attribute casts).
+   * @returns {string | undefined} - The js doc setter type from column.
+   */
+  jsDocSetterTypeFromColumn(column, modelClass) {
+    const type = modelClass.getColumnTypeByName(column.getName())
+
+    if (type && setterStringInputColumnTypes.has(type)) {
+      return "Date | string"
+    }
+
+    return this.jsDocTypeFromColumn(column, modelClass)
+  }
+}