velocious 1.0.430 → 1.0.432

package/src/environment-handlers/browser.js

@@ -0,0 +1,338 @@
+import Base from "./base.js"
+import * as inflection from "inflection"
+import restArgsError from "../utils/rest-args-error.js"
+import Logger from "../logger.js"
+
+/**
+ * Defines this typedef.
+ * @typedef {(id: string) => {default: typeof import("../database/migration/index.js").default}} MigrationsRequireContextIDFunctionType
+ * @typedef {MigrationsRequireContextIDFunctionType & {
+ *   keys: () => string[],
+ *   id: string
+ * }} MigrationsRequireContextType
+ */
+
+/**
+ * Defines this typedef.
+ * @typedef {(id: string) => {default: typeof import("../cli/base-command.js").default}} CommandsRequireContextIDFunctionType
+ * @typedef {CommandsRequireContextIDFunctionType & {
+ *   keys: () => string[],
+ *   id: string
+ * }} CommandsRequireContextType
+ */
+
+/**
+ * TestFilesRequireContextIDFunctionType type.
+ * @typedef {(id: string) => ?} TestFilesRequireContextIDFunctionType
+ * @typedef {TestFilesRequireContextIDFunctionType & {
+ *   keys: () => string[],
+ *   id: string
+ * }} TestFilesRequireContextType
+ */
+
+/**
+ * Runs is migration object.
+ * @param {import("./base.js").MigrationObjectType | null} migration - Candidate migration object.
+ * @returns {migration is import("./base.js").MigrationObjectType} - Whether migration exists.
+ */
+function isMigrationObject(migration) {
+  return Boolean(migration)
+}
+
+export default class VelociousEnvironmentsHandlerBrowser extends Base {
+  /**
+   * Find commands require context result.
+    @type {CommandsRequireContextType | undefined} */
+  findCommandsRequireContextResult = undefined
+
+  /**
+   * Migrations require context result.
+    @type {MigrationsRequireContextType | undefined} */
+  _migrationsRequireContextResult = undefined
+
+  /**
+   * Test files require context result.
+    @type {TestFilesRequireContextType | undefined} */
+  _testFilesRequireContextResult = undefined
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {() => Promise<MigrationsRequireContextType>} [args.migrationsRequireContextCallback] - Migrations require context callback.
+   * @param {() => Promise<TestFilesRequireContextType>} [args.testFilesRequireContextCallback] - Test files require context callback.
+   */
+  constructor({migrationsRequireContextCallback, testFilesRequireContextCallback, ...restArgs} = {}) {
+    super()
+    restArgsError(restArgs)
+
+    this.migrationsRequireContextCallback = migrationsRequireContextCallback
+    this.testFilesRequireContextCallback = testFilesRequireContextCallback
+    this.logger = new Logger(this)
+  }
+
+
+  /**
+   * Runs migrations require context.
+   * @returns {Promise<MigrationsRequireContextType>} - Resolves with the migrations require context.
+   */
+  async migrationsRequireContext() {
+    const {migrationsRequireContextCallback} = this
+
+    if (!migrationsRequireContextCallback) throw new Error("migrationsRequireContextCallback is required")
+
+    this._migrationsRequireContextResult ||= await migrationsRequireContextCallback()
+
+    return this._migrationsRequireContextResult
+  }
+
+  /**
+   * Runs test files require context.
+   * @returns {Promise<TestFilesRequireContextType>} - Resolves with the test files require context.
+   */
+  async testFilesRequireContext() {
+    const {testFilesRequireContextCallback} = this
+
+    if (!testFilesRequireContextCallback) {
+      throw new Error("testFilesRequireContextCallback is required when running browser tests")
+    }
+
+    this._testFilesRequireContextResult ||= await testFilesRequireContextCallback()
+
+    return this._testFilesRequireContextResult
+  }
+
+  /**
+   * Runs find commands.
+   * @returns {Promise<Array<import("./base.js").CommandFileObjectType>>} - Resolves with the commands.
+   */
+  async findCommands() {
+    this._findCommandsResult = this._actualFindCommands()
+
+    return this._findCommandsResult
+  }
+
+  /**
+   * Runs find commands require context.
+   * @returns {CommandsRequireContextType} - The commands require context.
+   */
+  _findCommandsRequireContext() {
+    // @ts-expect-error
+    this.findCommandsRequireContextResult ||= /** Narrows the runtime value to the documented type. @type {CommandsRequireContextType} */ (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
+  }
+
+  /**
+   * Runs require command.
+   * @param {object} args - Options object.
+   * @param {Array<string>} args.commandParts - Command parts.
+   * @returns {Promise<typeof import("../cli/base-command.js").default>} - Resolves with the require command.
+   */
+  async requireCommand({commandParts}) {
+    let filePath = "."
+
+    for (let commandPart of commandParts) {
+      if (commandPart == "c") commandPart = "console"
+      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
+  }
+
+  /**
+   * Runs find migrations.
+   * @returns {Promise<Array<import("./base.js").MigrationObjectType>>} - Resolves with the migrations.
+   */
+  async findMigrations() {
+    const migrationsRequireContext = await this.migrationsRequireContext()
+    /**
+     * Migrations.
+      @type {Array<import("./base.js").MigrationObjectType | null>} */
+    const migrations = 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(isMigrationObject)
+    /**
+     * Files.
+      @type {import("./base.js").MigrationObjectType[]} */
+    const files = /**
+                   * Narrows the runtime value to the documented type.
+                    @type {import("./base.js").MigrationObjectType[]} */ (migrations)
+
+    files.sort((migration1, migration2) => migration1.date - migration2.date)
+
+    return files
+  }
+
+  /**
+   * Runs import test files.
+   * @param {string[]} testFiles - Test files.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async importTestFiles(testFiles) {
+    const testFilesRequireContext = await this.testFilesRequireContext()
+    const requireKeys = testFilesRequireContext.keys()
+    const normalizedKeys = requireKeys.map((key) => ({
+      key,
+      normalized: key.replace(/\\/g, "/").replace(/^\.\//, "")
+    }))
+
+    for (const testFile of testFiles) {
+      const normalizedFile = testFile.replace(/\\/g, "/")
+      const matchedKey = normalizedKeys.find((entry) => normalizedFile.endsWith(entry.normalized))?.key
+
+      if (!matchedKey) {
+        throw new Error(`Test file ${testFile} was not found in the provided require context`)
+      }
+
+      const imported = testFilesRequireContext(matchedKey)
+
+      if (imported && typeof imported == "object" && "then" in imported && typeof imported.then == "function") {
+        await imported
+      }
+    }
+  }
+
+  /**
+   * Require migration.
+   * @param {string} filePath - File path.
+   * @returns {Promise<typeof import("../database/migration/index.js").default>} - Resolves with the require migration.
+   */
+  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
+  }
+
+  /**
+   * Runs after migrations.
+   * @param {object} args - Options object.
+   * @param {Record<string, import("../database/drivers/base.js").default>} args.dbs - Dbs.
+   * @param {"migration" | "schemaDump"} [args.reason] - Why the structure hook is running.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async afterMigrations({dbs}) {
+    const structureSql = await this._sqliteStructureSql({dbs})
+
+    if (!structureSql) return
+
+    await this.logger.debug(() => ["structure.sql:", structureSql])
+  }
+
+  /**
+   * Runs sqlite structure sql.
+   * @param {object} args - Options object.
+   * @param {Record<string, import("../database/drivers/base.js").default>} args.dbs - Dbs.
+   * @returns {Promise<string | null>} - Resolves with SQL string.
+   */
+  async _sqliteStructureSql({dbs}) {
+    const sqliteIdentifiers = Object.keys(dbs)
+      .filter((identifier) => this.getConfiguration().getDatabaseType(identifier) == "sqlite")
+
+    if (sqliteIdentifiers.length == 0) return null
+
+    const sections = []
+
+    for (const identifier of sqliteIdentifiers) {
+      const db = dbs[identifier]
+      const structureSql = typeof db.structureSql === "function" ? await db.structureSql() : null
+      const trimmedSql = structureSql?.trimEnd()
+
+      if (!trimmedSql) continue
+
+      if (sqliteIdentifiers.length > 1) {
+        sections.push(`-- ${identifier}`)
+      }
+
+      sections.push(trimmedSql)
+    }
+
+    if (sections.length == 0) return null
+
+    return `${sections.join("\n\n")}\n`
+  }
+}

package/src/environment-handlers/node/cli/commands/background-jobs-main.js

@@ -0,0 +1,21 @@
+import BaseCommand from "../../../../cli/base-command.js"
+import BackgroundJobsMain from "../../../../background-jobs/main.js"
+
+export default class BackgroundJobsMainCommand extends BaseCommand {
+  async execute() {
+    const main = new BackgroundJobsMain({configuration: this.getConfiguration()})
+    await main.start()
+
+    console.log(`Background jobs main listening on ${main.host}:${main.getPort()}`)
+
+    await new Promise((resolve) => {
+      const shutdown = async () => {
+        await main.stop()
+        resolve(undefined)
+      }
+
+      process.once("SIGINT", shutdown)
+      process.once("SIGTERM", shutdown)
+    })
+  }
+}

package/src/environment-handlers/node/cli/commands/background-jobs-runner.js

@@ -0,0 +1,24 @@
+import BaseCommand from "../../../../cli/base-command.js"
+import runJobPayload from "../../../../background-jobs/job-runner.js"
+
+export default class BackgroundJobsRunnerCommand extends BaseCommand {
+  async execute() {
+    const payload = process.env.VELOCIOUS_JOB_PAYLOAD
+
+    if (!payload) throw new Error("Missing VELOCIOUS_JOB_PAYLOAD")
+
+    // A graceful worker shutdown (e.g. a deploy draining the old release)
+    // SIGTERMs this spawned runner to reap it. Exit promptly so it does not
+    // linger as an orphan running against deleted release code; the OS releases
+    // the runner's DB/beacon sockets on exit and main's orphan sweep reclaims
+    // the in-flight job.
+    for (const signal of ["SIGTERM", "SIGINT"]) {
+      process.once(signal, () => process.exit(0))
+    }
+
+    const decoded = Buffer.from(payload, "base64").toString("utf8")
+    const jobPayload = JSON.parse(decoded)
+
+    await runJobPayload(jobPayload)
+  }
+}

package/src/environment-handlers/node/cli/commands/background-jobs-worker.js

@@ -0,0 +1,47 @@
+import BaseCommand from "../../../../cli/base-command.js"
+import BackgroundJobsWorker from "../../../../background-jobs/worker.js"
+
+/**
+ * Resolves the shutdown drain timeout from
+ * `VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS`:
+ *   - unset / "indefinite" / "0" → indefinite: wait for in-flight jobs to
+ *     finish and never kill a process runner. This is the default so a graceful
+ *     stop (e.g. a deploy) does not interrupt long-running jobs such as builds.
+ *   - positive integer → that many milliseconds, after which any process runner
+ *     still in flight is terminated (SIGTERM, then SIGKILL) instead of orphaned.
+ *
+ * When a finite cap is used it must be shorter than the supervisor's
+ * graceful-stop window so the worker reaps its own children before being
+ * force-killed.
+ * @returns {number | undefined} - Timeout in ms, or undefined for indefinite.
+ */
+function resolveShutdownTimeoutMs() {
+  const raw = (process.env.VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS || "").trim().toLowerCase()
+
+  if (!raw || raw === "indefinite" || raw === "0") return undefined
+
+  const parsed = Number.parseInt(raw, 10)
+
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined
+}
+
+export default class BackgroundJobsWorkerCommand extends BaseCommand {
+  async execute() {
+    const worker = new BackgroundJobsWorker({configuration: this.getConfiguration()})
+    await worker.start()
+
+    console.log("Background jobs worker connected")
+
+    const timeoutMs = resolveShutdownTimeoutMs()
+
+    await new Promise((resolve) => {
+      const shutdown = async () => {
+        await worker.stop({timeoutMs})
+        resolve(undefined)
+      }
+
+      process.once("SIGINT", shutdown)
+      process.once("SIGTERM", shutdown)
+    })
+  }
+}

package/src/environment-handlers/node/cli/commands/beacon.js

@@ -0,0 +1,21 @@
+import BaseCommand from "../../../../cli/base-command.js"
+import BeaconServer from "../../../../beacon/server.js"
+
+export default class BeaconCommand extends BaseCommand {
+  async execute() {
+    const beacon = new BeaconServer({configuration: this.getConfiguration()})
+    await beacon.start()
+
+    console.log(`Beacon listening on ${beacon.host}:${beacon.getPort()}`)
+
+    await new Promise((resolve) => {
+      const shutdown = async () => {
+        await beacon.stop()
+        resolve(undefined)
+      }
+
+      process.once("SIGINT", shutdown)
+      process.once("SIGTERM", shutdown)
+    })
+  }
+}

package/src/environment-handlers/node/cli/commands/cli-command-context.js

@@ -0,0 +1,31 @@
+/**
+ * CliCommandContext type.
+ * @typedef {object} CliCommandContext
+ * @property {import("../../../../configuration.js").default} configuration - Configuration instance.
+ * @property {import("../../../../database/drivers/base.js").default | undefined} db - Default database connection.
+ * @property {Record<string, import("../../../../database/drivers/base.js").default>} dbs - Database connections keyed by identifier.
+ * @property {string[]} args - CLI args after command-specific leading arguments.
+ */
+
+/**
+ * Runs build cli command context.
+ * @param {import("../../../../cli/base-command.js").default} command - Command building the context.
+ * @param {number} argsOffset - Number of process args to omit.
+ * @returns {CliCommandContext} - Runtime context passed to CLI command scripts.
+ */
+export default function buildCliCommandContext(command, argsOffset) {
+  const configuration = command.getConfiguration()
+  const dbs = configuration.getCurrentConnections()
+  const identifiers = Object.keys(dbs)
+  /**
+   * Process args.
+    @type {string[]} */
+  const processArgs = command.processArgs || []
+
+  return {
+    configuration,
+    db: dbs.default || (identifiers.length > 0 ? dbs[identifiers[0]] : undefined),
+    dbs,
+    args: processArgs.slice(argsOffset)
+  }
+}

package/src/environment-handlers/node/cli/commands/console.js

@@ -0,0 +1,149 @@
+import Application from "../../../../application.js"
+import BaseCommand from "../../../../cli/base-command.js"
+import path from "node:path"
+import repl from "node:repl"
+
+/**
+ * Defines this typedef.
+  @typedef {{application: import("../../../../application.js").default, configuration: import("../../../../configuration.js").default}} ConsoleContextArgs */
+
+/**
+ * Runs build console context.
+ * @param {ConsoleContextArgs} args - Options object.
+ * @returns {Record<string, ?>} - The console context.
+ */
+function buildConsoleContext({application, configuration}) {
+  /**
+   * Dbs.
+    @type {Record<string, import("../../../../database/drivers/base.js").default>} */
+  const dbs = configuration.getCurrentConnections()
+
+  for (const identifier of configuration.getDatabaseIdentifiers()) {
+    if (dbs[identifier]) continue
+
+    const pool = configuration.getDatabasePool(identifier)
+    const poolWithGlobal = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {{getGlobalConnection?: () => import("../../../../database/drivers/base.js").default | undefined}} */ (pool)
+    const globalConnection = poolWithGlobal.getGlobalConnection?.()
+
+    if (globalConnection) {
+      dbs[identifier] = globalConnection
+      continue
+    }
+
+    try {
+      dbs[identifier] = pool.getCurrentConnection()
+    } catch (error) {
+      if (configuration.isMissingCurrentConnectionError(error)) {
+        // Ignore missing connections here; they can be established lazily.
+      } else {
+        throw error
+      }
+    }
+  }
+
+  const dbIdentifiers = Object.keys(dbs)
+
+  return {
+    app: application,
+    application,
+    configuration,
+    db: dbs.default || (dbIdentifiers.length > 0 ? dbs[dbIdentifiers[0]] : undefined),
+    dbs,
+    models: {...configuration.modelClasses}
+  }
+}
+
+/**
+ * Runs assign console context.
+ * @param {object} args - Options object.
+ * @param {Record<string, ?>} args.context - The base context.
+ * @param {import("node:repl").REPLServer} args.replServer - The REPL server.
+ * @returns {void} - No return value.
+ */
+function assignConsoleContext({context, replServer}) {
+  Object.assign(replServer.context, context)
+
+  const modelClasses = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {Record<string, typeof import("../../../../database/record/index.js").default>} */ (
+    context.models || {}
+  )
+
+  for (const [name, modelClass] of Object.entries(modelClasses)) {
+    replServer.context[name] = modelClass
+  }
+}
+
+/**
+ * Runs start console repl.
+ * @param {object} args - Options object.
+ * @param {import("../../../../configuration.js").default} args.configuration - Configuration instance.
+ * @param {Record<string, ?>} args.context - REPL context.
+ * @returns {Promise<void>} - Resolves when the console exits.
+ */
+async function startConsoleRepl({configuration, context}) {
+  const environment = configuration.getEnvironment()
+
+  console.log(`Loading ${environment} environment (Velocious console)`)
+
+  const replServer = repl.start({
+    prompt: "velocious> "
+  })
+
+  assignConsoleContext({context, replServer})
+  replServer.on("reset", () => {
+    assignConsoleContext({context, replServer})
+  })
+
+  const historyPath = path.join(configuration.getDirectory(), ".velocious-console-history")
+
+  await new Promise((resolve, reject) => {
+    replServer.setupHistory(historyPath, (error) => {
+      if (error) {
+        reject(error)
+      } else {
+        resolve(undefined)
+      }
+    })
+  })
+
+  await new Promise((resolve) => {
+    replServer.on("exit", () => {
+      resolve(undefined)
+    })
+  })
+
+}
+
+/** Velocious console command. */
+export default class VelociousCliCommandsConsole extends BaseCommand{
+  /**
+   * Runs execute.
+   * @returns {Promise<?>} - Resolves with the command result.
+   */
+  async execute() {
+    const configuration = this.getConfiguration()
+    const application = new Application({
+      configuration,
+      type: "console"
+    })
+
+    await application.initialize()
+
+    try {
+      await configuration.ensureGlobalConnections()
+
+      const context = buildConsoleContext({application, configuration})
+
+      if (this.cli.getTesting()) {
+        return {modelNames: Object.keys(context.models || {})}
+      }
+
+      return await startConsoleRepl({configuration, context})
+    } finally {
+      await configuration.closeDatabaseConnections()
+    }
+  }
+}

package/src/environment-handlers/node/cli/commands/db/schema/dump.js

@@ -0,0 +1,43 @@
+import BaseCommand from "../../../../../../cli/base-command.js"
+import fileExists from "../../../../../../utils/file-exists.js"
+import path from "path"
+
+/** Node CLI command for dumping DB structure SQL files. */
+export default class DbSchemaDump extends BaseCommand {
+  /**
+   * Runs execute.
+    @returns {Promise<void>} */
+  async execute() {
+    await this.getConfiguration().ensureConnections({name: "DB schema dump"}, async (dbs) => {
+      const shouldGenerate = await this.shouldGenerateStructureSql({dbs})
+
+      if (!shouldGenerate) return
+
+      await this.getEnvironmentHandler().afterMigrations({dbs, reason: "schemaDump"})
+    })
+  }
+
+  /**
+   * Runs should generate structure sql.
+   * @param {object} args - Options object.
+   * @param {Record<string, import("../../../../../../database/drivers/base.js").default>} args.dbs - Active DB connections by identifier.
+   * @returns {Promise<boolean>} - Whether structure SQL should be generated.
+   */
+  async shouldGenerateStructureSql({dbs}) {
+    if (!this.getConfiguration().shouldWriteStructureSql({reason: "schemaDump"})) return false
+
+    const dbDir = path.join(this.directory(), "db")
+
+    for (const identifier of Object.keys(dbs)) {
+      const db = dbs[identifier]
+
+      if (typeof db.structureSql !== "function") continue
+
+      const structureFilePath = path.join(dbDir, `structure-${identifier}.sql`)
+
+      if (!await fileExists(structureFilePath)) return true
+    }
+
+    return false
+  }
+}