velocious 1.0.486 → 1.0.488

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()
+    }
+  }
+}

package/src/sync/sync-api-client-types.js

@@ -0,0 +1,77 @@
+// @ts-check
+
+/**
+ * @module sync-api-client-types
+ */
+
+/** @typedef {{id: string | null, serverSequence: number | null, updatedAt: string} | null} SyncCursor */
+
+/**
+ * @typedef {object} SyncChangeEnvelope
+ * @property {() => unknown} data - Sync data payload.
+ * @property {() => unknown} id - Sync row identifier.
+ * @property {() => unknown} resourceId - Resource identifier.
+ * @property {() => string | null} resourceType - Resource type name.
+ * @property {() => string} syncType - Sync operation type.
+ */
+
+/**
+ * @typedef {object} SyncChangeApplyResult
+ * @property {boolean} changed - Whether the local store changed.
+ * @property {string | null} [resourceType] - Applied resource type override.
+ */
+
+/**
+ * @typedef {object} SyncResourceConfig
+ * @property {(args: {attributes: Record<string, unknown>, data: Record<string, unknown>, record: ?, sync: SyncChangeEnvelope}) => Promise<boolean | void> | boolean | void} [afterApply] - Optional post-save hook.
+ * @property {(args: {data: Record<string, unknown>, record: ?, sync: SyncChangeEnvelope}) => Promise<Record<string, unknown>> | Record<string, unknown>} attributes - Allowed attributes builder.
+ * @property {boolean} enabled - Whether this resource is sync-enabled.
+ * @property {(args: {data: Record<string, unknown>, resourceId: unknown, sync: SyncChangeEnvelope}) => Promise<?> | ?} [findRecord] - Optional upsert finder.
+ * @property {(args: {resourceId: unknown, sync: SyncChangeEnvelope}) => Promise<?> | ?} [findRecordForDelete] - Optional destroy finder.
+ * @property {?} modelClass - Velocious model class.
+ */
+
+/**
+ * @typedef {object} SyncChangesRequest
+ * @property {string} authenticationToken - Auth token.
+ * @property {string | null} [afterId] - Last seen row id.
+ * @property {number} [afterServerSequence] - Last seen server sequence.
+ * @property {string} [afterUpdatedAt] - Last seen timestamp.
+ * @property {number} limit - Page size.
+ * @property {string | null} [upToId] - Snapshot upper-bound row id.
+ * @property {number} [upToServerSequence] - Snapshot upper-bound server sequence.
+ * @property {string} [upToUpdatedAt] - Snapshot upper-bound timestamp.
+ */
+
+/**
+ * @typedef {object} SyncChangesResponse
+ * @property {string} [errorMessage] - Error message.
+ * @property {SyncCursor | Record<string, ?>} [nextCursor] - Next cursor.
+ * @property {string} [status] - Response status.
+ * @property {Array<unknown>} [syncs] - Sync rows.
+ * @property {SyncCursor | Record<string, ?>} [upToCursor] - Snapshot upper-bound cursor.
+ */
+
+/**
+ * @typedef {object} SyncChangesResult
+ * @property {boolean} changed - Whether any local record changed.
+ * @property {number} pages - Applied page count.
+ * @property {Record<string, boolean>} resourceChanged - Changed flags by resource type.
+ * @property {Record<string, number>} resourceCounts - Applied counts by resource type.
+ * @property {number} syncedCount - Applied row count.
+ */
+
+/**
+ * @typedef {object} SyncReplayItem
+ * @property {string | number} id - Sync id.
+ * @property {string} syncState - Replay state.
+ */
+
+/**
+ * @typedef {object} SyncReplayResponse
+ * @property {string} [errorMessage] - Error message.
+ * @property {string} [status] - Response status.
+ * @property {Array<SyncReplayItem>} [syncs] - Replay results.
+ */
+
+export {}