velocious 1.0.485 → 1.0.487

package/src/environment-handlers/node.js

@@ -31,6 +31,8 @@ import * as inflection from "inflection"
 import path from "path"
 import {AsyncLocalStorage as NodeAsyncLocalStorage} from "node:async_hooks"
 import {timingSafeEqual} from "node:crypto"
+import requireContext from "require-context"
+import InitializerFromRequireContext from "../database/initializer-from-require-context.js"
 import toImportSpecifier from "../utils/to-import-specifier.js"
 import {validateTimeZone} from "../time-zone.js"
 
@@ -103,7 +105,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     for (const backendProject of backendProjects) {
       if (backendProject.frontendModels) continue
 
-      const resourcesDir = path.join(backendProject.path, "src", "resources")
+      const resourcesDir = backendProject.resourcesPath || path.join(backendProject.path, "src", "resources")
       let files
 
       try {
@@ -145,6 +147,43 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     }
   }
 
+  /**
+   * Loads models contributed by registered packages into the model registry,
+   * after the app's own `initializeModels` hook. A package whose models directory
+   * is absent is skipped; a package model whose name collides with an
+   * already-registered different class throws. Node-only (uses the filesystem), so
+   * it lives here rather than in the browser-bundled Configuration.
+   * @param {import("../configuration.js").default} configuration - Configuration instance.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async initializePackageModels(configuration) {
+    for (const velociousPackage of configuration.getPackages()) {
+      const modelsPath = velociousPackage.getModelsPath()
+
+      try {
+        await fs.access(modelsPath)
+      } catch {
+        continue
+      }
+
+      const packageRequireContext = /** @type {import("../database/initializer-from-require-context.js").ModelClassRequireContextType} */ (requireContext(modelsPath, true, /^(.+)\.js$/))
+      const modelClasses = configuration.getModelClasses()
+
+      for (const fileName of packageRequireContext.keys()) {
+        const modelClass = packageRequireContext(fileName)?.default
+        const existing = modelClass && modelClasses[modelClass.getModelName()]
+
+        if (existing && existing !== modelClass) {
+          throw new Error(`Package "${velociousPackage.getName()}" model "${modelClass.getModelName()}" collides with an already-registered model.`)
+        }
+      }
+
+      await configuration.ensureConnections({name: `Initialize ${velociousPackage.getName()} package models`}, async () => {
+        await new InitializerFromRequireContext({requireContext: packageRequireContext}).initialize({configuration})
+      })
+    }
+  }
+
   /**
    * Runs set configuration.
    * @param {import("../configuration.js").default} newConfiguration - New configuration.
@@ -761,32 +800,79 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @returns {Promise<Array<import("./base.js").MigrationObjectType>>} - Resolves with the migrations.
    */
   async findMigrations() {
-    const migrationsPath = `${this.getConfiguration().getDirectory()}/src/database/migrations`
-    const glob = await fs.glob(`${migrationsPath}/**/*.js`)
-    let files = []
+    const configuration = this.getConfiguration()
+    const migrationDirectories = [`${configuration.getDirectory()}/src/database/migrations`]
+
+    for (const velociousPackage of configuration.getPackages()) {
+      migrationDirectories.push(velociousPackage.getMigrationsPath())
+    }
 
-    for await (const fullPath of glob) {
-      const file = await path.basename(fullPath)
+    /** @type {Array<import("./base.js").MigrationObjectType>} */
+    const files = []
 
-      const match = file.match(/^(\d{14})-(.+)\.js$/)
+    for (const migrationsPath of migrationDirectories) {
+      await this._collectMigrationsFromDirectory(migrationsPath, files)
+    }
 
-      if (!match) continue
+    this._ensureNoMigrationTimestampCollisions(files)
 
-      const date = parseInt(match[1])
-      const migrationName = match[2]
-      const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
+    return files.sort((migration1, migration2) => migration1.date - migration2.date)
+  }
 
-      files.push({
-        file,
-        fullPath: `${migrationsPath}/${file}`,
-        date,
-        migrationClassName
-      })
+  /**
+   * Collects migration files from one directory into `files`, preserving each
+   * file's real absolute path (so app and package migrations keep their own
+   * source location). A missing directory is skipped.
+   * @param {string} migrationsPath - Directory to scan.
+   * @param {Array<import("./base.js").MigrationObjectType>} files - Accumulator to push into.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async _collectMigrationsFromDirectory(migrationsPath, files) {
+    const glob = await fs.glob(`${migrationsPath}/**/*.js`)
+
+    try {
+      for await (const fullPath of glob) {
+        const file = await path.basename(fullPath)
+        const match = file.match(/^(\d{14})-(.+)\.js$/)
+
+        if (!match) continue
+
+        const date = parseInt(match[1])
+        const migrationName = match[2]
+        const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
+
+        files.push({file, fullPath, date, migrationClassName})
+      }
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error)?.code !== "ENOENT") {
+        throw error
+      }
     }
+  }
 
-    files = files.sort((migration1, migration2) => migration1.date - migration2.date)
+  /**
+   * Throws if two migrations from different files share the same 14-digit
+   * timestamp. The `schema_migrations` ledger keys on the timestamp, so a silent
+   * collision (e.g. between the app and a package, or two packages) would leave
+   * the second migration un-run — a data bug. Fail loudly instead.
+   * @param {Array<import("./base.js").MigrationObjectType>} files - Collected migrations.
+   * @returns {void} - No return value.
+   */
+  _ensureNoMigrationTimestampCollisions(files) {
+    /** @type {Map<number, string>} */
+    const pathsByDate = new Map()
 
-    return files
+    for (const migration of files) {
+      if (!migration.fullPath) continue
+
+      const existing = pathsByDate.get(migration.date)
+
+      if (existing && existing !== migration.fullPath) {
+        throw new Error(`Two migrations share the timestamp ${migration.date}: ${existing} and ${migration.fullPath}. Migration timestamps must be unique across the app and all packages.`)
+      }
+
+      pathsByDate.set(migration.date, migration.fullPath)
+    }
   }
 
   /**

package/src/packages/velocious-package.js

@@ -0,0 +1,115 @@
+// @ts-check
+
+import restArgsError from "../utils/rest-args-error.js"
+
+/**
+ * A Velocious package (engine): an external npm package that contributes data
+ * models, frontend-model resources and migrations to a consuming app. The app
+ * lists packages in `Configuration({packages: [...]})`; the framework then loads
+ * the package's `src/models`, discovers its `src/resources`, runs its
+ * `src/database/migrations`, and generates its frontend models into the app.
+ */
+export default class VelociousPackage {
+  /**
+   * Wraps a plain descriptor as a VelociousPackage (or returns it unchanged when
+   * it already is one), so packages can be listed without importing this class.
+   * @param {VelociousPackage | import("../configuration-types.js").VelociousPackageDescriptor} descriptor - Package or plain descriptor.
+   * @returns {VelociousPackage} - The package instance.
+   */
+  static from(descriptor) {
+    if (descriptor instanceof VelociousPackage) {
+      return descriptor
+    }
+
+    return new VelociousPackage(descriptor)
+  }
+
+  /**
+   * Derives the containing directory of a module url without Node's `path`/`url`
+   * modules, so this class stays safe to import in browser/Expo bundles.
+   * @param {string} url - A module url (usually `import.meta.url`).
+   * @returns {string} - The directory path that contains the module.
+   */
+  static _directoryFromUrl(url) {
+    const directoryUrl = new URL(".", url)
+
+    return decodeURIComponent(directoryUrl.pathname).replace(/\/$/, "")
+  }
+
+  /**
+   * Runs constructor.
+   * @param {import("../configuration-types.js").VelociousPackageDescriptor} args - Package descriptor.
+   */
+  constructor({name, url, path, modelsPath, resourcesPath, migrationsPath, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!name) {
+      throw new Error("A velocious package requires a name.")
+    }
+
+    if (!path && !url) {
+      throw new Error(`Velocious package "${name}" requires a "path" or a "url" (usually import.meta.url).`)
+    }
+
+    this._name = name
+    this._path = path || VelociousPackage._directoryFromUrl(/** @type {string} */ (url))
+    this._modelsPath = modelsPath
+    this._resourcesPath = resourcesPath
+    this._migrationsPath = migrationsPath
+  }
+
+  /**
+   * Runs get name.
+   * @returns {string} - The package name.
+   */
+  getName() {
+    return this._name
+  }
+
+  /**
+   * Runs get path.
+   * @returns {string} - The package root directory (the one that contains `src`).
+   */
+  getPath() {
+    return this._path
+  }
+
+  /**
+   * Runs get models path.
+   * @returns {string} - The package's models directory.
+   */
+  getModelsPath() {
+    return this._modelsPath || `${this._path}/src/models`
+  }
+
+  /**
+   * Runs get resources path.
+   * @returns {string} - The package's frontend-model resources directory.
+   */
+  getResourcesPath() {
+    return this._resourcesPath || `${this._path}/src/resources`
+  }
+
+  /**
+   * Runs get migrations path.
+   * @returns {string} - The package's migrations directory.
+   */
+  getMigrationsPath() {
+    return this._migrationsPath || `${this._path}/src/database/migrations`
+  }
+
+  /**
+   * Derives the internal backend-project entry the framework appends so the
+   * existing resource-discovery + frontend-model generation machinery picks up
+   * this package. Generated frontend models are written to the app's output.
+   * @param {{frontendModelsOutputPath: string | undefined}} args - The app's frontend-models output path.
+   * @returns {import("../configuration-types.js").BackendProjectConfiguration} - The derived backend project.
+   */
+  toBackendProjectConfiguration({frontendModelsOutputPath}) {
+    return {
+      frontendModelsOutputPath,
+      path: this.getPath(),
+      resourcesPath: this.getResourcesPath()
+    }
+  }
+}