velocious 1.0.489 → 1.0.492

package/src/cli/commands/db/tenants/create.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import BaseCommand from "../../../base-command.js"
+import {createTenantDatabase} from "../../../../tenants/default-tenant-database-provisioning.js"
 import TenantDatabaseCommandHelper from "../../../tenant-database-command-helper.js"
 
 export default class DbTenantsCreate extends BaseCommand {
@@ -14,13 +15,14 @@ export default class DbTenantsCreate extends BaseCommand {
       identifier: this.processArgs?.[1]
     })
     const provider = helper.provider
-
-    if (typeof provider.createDatabase !== "function") {
-      throw new Error(`Tenant database provider for ${helper.identifier} must define createDatabase to use db:tenants:create`)
-    }
+    // Providers may customize creation, but the generic driver-agnostic provisioning
+    // is the framework default so apps do not reimplement it.
+    const createDatabase = typeof provider.createDatabase === "function"
+      ? provider.createDatabase.bind(provider)
+      : createTenantDatabase
 
     const tenantCount = await helper.eachTenant(async ({databaseConfiguration, tenant}) => {
-      await provider.createDatabase?.({
+      await createDatabase({
         configuration: this.getConfiguration(),
         databaseConfiguration,
         identifier: helper.identifier,

package/src/cli/commands/db/tenants/drop.js

@@ -1,12 +1,13 @@
 // @ts-check
 
 import BaseCommand from "../../../base-command.js"
+import {dropTenantDatabase} from "../../../../tenants/default-tenant-database-provisioning.js"
 import TenantDatabaseCommandHelper from "../../../tenant-database-command-helper.js"
 
 export default class DbTenantsDrop extends BaseCommand {
   /**
    * Drops the tenant database/schema for every listed tenant through the provider's
-   * `dropDatabase` hook.
+   * `dropDatabase` hook, or the framework default when the provider defines none.
    * @returns {Promise<{identifier: string, tenantCount: number} | void>} - Result in test mode.
    */
   async execute() {
@@ -15,13 +16,12 @@ export default class DbTenantsDrop extends BaseCommand {
       identifier: this.processArgs?.[1]
     })
     const provider = helper.provider
-
-    if (typeof provider.dropDatabase !== "function") {
-      throw new Error(`Tenant database provider for ${helper.identifier} must define dropDatabase to use db:tenants:drop`)
-    }
+    const dropDatabase = typeof provider.dropDatabase === "function"
+      ? provider.dropDatabase.bind(provider)
+      : dropTenantDatabase
 
     const tenantCount = await helper.eachTenant(async ({databaseConfiguration, tenant}) => {
-      await provider.dropDatabase?.({
+      await dropDatabase({
         configuration: this.getConfiguration(),
         databaseConfiguration,
         identifier: helper.identifier,

package/src/configuration-types.js

@@ -355,9 +355,17 @@
  * @property {Record<string, FrontendModelSyncJsonValue>} [policy] - Deterministic non-secret policy inputs included in the policy hash only.
  */
 
+/**
+ * Velocious sync API endpoint configuration.
+ * @typedef {object} VelociousSyncApiConfiguration
+ * @property {string} [mountPath] - Mount path for the sync endpoints. Defaults to "/velocious/sync".
+ * @property {FrontendModelResourceClassType} resourceClass - App sync resource class served by the auto-mounted sync endpoints.
+ */
+
 /**
  * Velocious sync configuration.
  * @typedef {object} VelociousSyncConfiguration
+ * @property {VelociousSyncApiConfiguration} [api] - Auto-mounts the Velocious sync changes/replay endpoints for this resource class.
  * @property {import("./sync/device-identity.js").SyncJsonWebKey | null} [deviceCertificateBackendPublicKey] - Public backend key used to verify offline device certificates for sync replay.
  * @property {number} [changeFeedRetentionSize] - Number of accepted server changes retained before clients must refresh from snapshot.
  * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.

package/src/configuration.js

@@ -424,6 +424,7 @@ export default class VelociousConfiguration {
    * @returns {import("./configuration-types.js").VelociousSyncConfiguration} - Normalized sync configuration.
    */
   _normalizeSyncConfiguration(sync) {
+    const api = sync?.api
     const deviceCertificateBackendPublicKey = sync?.deviceCertificateBackendPublicKey || null
     const changeFeedRetentionSize = sync?.changeFeedRetentionSize
     const offlineGrantSigningKeys = sync?.offlineGrantSigningKeys || []
@@ -441,6 +442,7 @@ export default class VelociousConfiguration {
     }
 
     return {
+      api: this._normalizeSyncApiConfiguration(api),
       changeFeedRetentionSize: changeFeedRetentionSize || 10000,
       deviceCertificateBackendPublicKey,
       offlineGrantSigningKeys: offlineGrantSigningKeys.map((key) => normalizeOfflineGrantSigningKey(key)),
@@ -448,6 +450,33 @@ export default class VelociousConfiguration {
     }
   }
 
+  /**
+   * Normalizes sync API endpoint configuration.
+   * @param {import("./configuration-types.js").VelociousSyncApiConfiguration | undefined} api - Sync API configuration.
+   * @returns {import("./configuration-types.js").VelociousSyncApiConfiguration | undefined} - Normalized sync API configuration.
+   */
+  _normalizeSyncApiConfiguration(api) {
+    if (api === undefined || api === null) return undefined
+
+    if (typeof api !== "object" || Array.isArray(api)) {
+      throw new Error("sync.api must be an object with a resourceClass")
+    }
+
+    const {mountPath, resourceClass} = api
+
+    if (typeof resourceClass !== "function") {
+      throw new Error(`sync.api.resourceClass must be a resource class, got: ${String(resourceClass)}`)
+    }
+    if (!resourceClass.ModelClass) {
+      throw new Error(`sync.api.resourceClass ${resourceClass.name} must define static ModelClass`)
+    }
+    if (mountPath !== undefined && (typeof mountPath !== "string" || !mountPath.startsWith("/"))) {
+      throw new Error(`sync.api.mountPath must start with '/', got: ${String(mountPath)}`)
+    }
+
+    return {mountPath, resourceClass}
+  }
+
   /**
    * Runs get database configuration.
    * @returns {Record<string, import("./configuration-types.js").DatabaseConfigurationType>} - The database configuration.

package/src/database/query/index.js

@@ -235,18 +235,48 @@ export default class VelociousDatabaseQuery {
     return this._groups
   }
 
+  /**
+   * Runs get joins.
+   * @returns {Array<?>} - The joins.
+   */
+  getJoins() { return this._joins }
+
+  /**
+   * Runs get limit.
+   * @returns {number | null} - The limit.
+   */
+  getLimit() { return this._limit }
+
+  /**
+   * Runs get offset.
+   * @returns {number | null} - The offset.
+   */
+  getOffset() { return this._offset }
+
   /**
    * Runs get options.
    * @returns {import("../query-parser/options.js").default} - The options options.
    */
   getOptions() { return this.driver.options() }
 
+  /**
+   * Runs get orders.
+   * @returns {Array<?>} - The orders.
+   */
+  getOrders() { return this._orders }
+
   /**
    * Runs get selects.
    * @returns {Array<import("./select-base.js").default>} - The selects.
    */
   getSelects() { return this._selects }
 
+  /**
+   * Runs get wheres.
+   * @returns {Array<import("./where-base.js").default>} - The wheres.
+   */
+  getWheres() { return this._wheres }
+
   /**
    * Runs from.
    * @param {string|import("./from-base.js").default} from - From.

package/src/database/query/model-class-query.js

@@ -3,6 +3,7 @@
 import {incorporate} from "incorporator"
 import * as inflection from "inflection"
 import {isPlainObject} from "is-plain-object"
+import {currentSyncClient} from "../../sync/sync-client-registry.js"
 import Logger from "../../logger.js"
 import Preloader from "./preloader.js"
 import {normalizeQueryDataSpec, runQueryData} from "./query-data.js"
@@ -1114,6 +1115,22 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
   queryLogName(operation) {
     return `${this.getModelClass().name} ${operation}`
   }
+
+  /**
+   * Declares this query as a sync scope on the current sync client.
+   * @returns {Promise<?>} - Declared scope and pull result.
+   */
+  async sync() {
+    return await currentSyncClient().sync(this)
+  }
+
+  /**
+   * Deactivates this query's sync scope on the current sync client.
+   * @returns {Promise<void>} - Resolves when the scope is deactivated.
+   */
+  async unsync() {
+    await currentSyncClient().unsync(this)
+  }
 }
 
 /**

package/src/database/record/index.js

@@ -535,6 +535,22 @@ class VelociousDatabaseRecord {
     callbacks[callbackName].push(callback)
   }
 
+  /**
+   * Runs unregister lifecycle callback.
+   * @param {"afterCreate" | "afterDestroy" | "afterSave" | "afterUpdate" | "beforeCreate" | "beforeDestroy" | "beforeSave" | "beforeUpdate" | "beforeValidation"} callbackName - Callback type.
+   * @param {LifecycleCallbackType} callback - Previously registered callback.
+   * @returns {void}
+   */
+  static unregisterLifecycleCallback(callbackName, callback) {
+    const callbacks = this.getLifecycleCallbacksMap()[callbackName]
+
+    if (!callbacks) return
+
+    const callbackIndex = callbacks.indexOf(callback)
+
+    if (callbackIndex >= 0) callbacks.splice(callbackIndex, 1)
+  }
+
   /**
    * Runs before validation.
    * @template R

package/src/sync/query-scope.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+import stableJsonStringify from "./stable-json.js"
+
+/**
+ * Serializes a model query into a transportable sync scope.
+ *
+ * Only plain attribute equality conditions are supported: the scope must be
+ * expressible as `{resourceType, conditions}` so servers can match it against
+ * their change feeds. Anything else (raw SQL, negations, joins, orders,
+ * limits, offsets, groups) fails loudly.
+ * @param {import("../database/query/model-class-query.js").default<?>} query - Model query declaring the sync scope.
+ * @returns {import("./sync-client-types.js").SerializedSyncScope} Serialized sync scope.
+ */
+export function serializedScopeFromQuery(query) {
+  if (query.getJoins().length > 0) throw new Error("sync(query) does not support joins")
+  if (query.getOrders().length > 0) throw new Error("sync(query) does not support orders")
+  if (query.getLimit() !== null && query.getLimit() !== undefined) throw new Error("sync(query) does not support limit")
+  if (query.getOffset() !== null && query.getOffset() !== undefined) throw new Error("sync(query) does not support offset")
+  if (query.getGroups().length > 0) throw new Error("sync(query) does not support groups")
+
+  const modelClass = query.getModelClass()
+  const conditions = /** @type {Record<string, ?>} */ ({})
+
+  for (const where of query.getWheres()) {
+    const whereHash = /** @type {{hash?: Record<string, ?>}} */ (where).hash
+
+    if (!whereHash || typeof whereHash !== "object" || Array.isArray(whereHash) || /** @type {{where?: ?}} */ (where).where) {
+      throw new Error(`sync(query) only supports plain attribute conditions, got: ${where.constructor.name}`)
+    }
+
+    for (const [attributeName, value] of Object.entries(whereHash)) {
+      const conditionValue = scalarConditionValue(attributeName, value)
+
+      if (attributeName in conditions && stableJsonStringify(conditions[attributeName]) !== stableJsonStringify(conditionValue)) {
+        throw new Error(`sync(query) got conflicting conditions for: ${attributeName}`)
+      }
+
+      conditions[attributeName] = conditionValue
+    }
+  }
+
+  return {conditions, resourceType: modelClass.getModelName()}
+}
+
+/**
+ * Returns a stable canonical key identifying a sync scope.
+ * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+ * @returns {string} Stable scope key.
+ */
+export function scopeKey(scope) {
+  return `${scope.resourceType}:${stableJsonStringify(scope.conditions)}`
+}
+
+/**
+ * Validates one scope condition value as a scalar or array of scalars.
+ * @param {string} attributeName - Condition attribute name for error messages.
+ * @param {?} value - Condition value.
+ * @returns {?} Validated condition value.
+ */
+function scalarConditionValue(attributeName, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) validateScalar(attributeName, item)
+
+    return value
+  }
+
+  validateScalar(attributeName, value)
+
+  return value
+}
+
+/**
+ * Validates one scalar condition value.
+ * @param {string} attributeName - Condition attribute name for error messages.
+ * @param {?} value - Condition value.
+ * @returns {void}
+ */
+function validateScalar(attributeName, value) {
+  if (value === null) return
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return
+
+  throw new Error(`sync(query) condition values must be scalar, got ${typeof value} for: ${attributeName}`)
+}

package/src/sync/server-change-feed.js

@@ -2,6 +2,7 @@
 
 import {randomUUID} from "crypto"
 import TableData from "../database/table-data/index.js"
+import stableJsonStringify from "./stable-json.js"
 
 const DEFAULT_RETENTION_SIZE = 10000
 const DEFAULT_PAGE_SIZE = 100
@@ -464,31 +465,6 @@ function scopesEqual(changeScope, requestedScope) {
   return stableJsonStringify(changeScope || null) === stableJsonStringify(requestedScope)
 }
 
-/**
- * Stable JSON serialization for persisted sync scopes.
- * @param {?} value - JSON-compatible value.
- * @returns {string} - Stable JSON representation.
- */
-function stableJsonStringify(value) {
-  return JSON.stringify(stableJsonValue(value))
-}
-
-/**
- * Produces a recursively key-sorted JSON value.
- * @param {?} value - JSON-compatible value.
- * @returns {?} - Stable JSON-compatible value.
- */
-function stableJsonValue(value) {
-  if (Array.isArray(value)) return value.map((item) => stableJsonValue(item))
-  if (!value || typeof value !== "object") return value
-
-  return Object.keys(value).sort().reduce((memo, key) => {
-    memo[key] = stableJsonValue(value[key])
-
-    return memo
-  }, /** @type {Record<string, ?>} */ ({}))
-}
-
 /**
  * @typedef {object} ServerChangeFeedEntry
  * @property {string | null} actorDeviceId - Signed mutation actor device id when available.

package/src/sync/stable-json.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * Serializes a JSON-compatible value with recursively sorted object keys, so
+ * equal values always produce byte-identical strings (used for sync scope and
+ * change-feed identity comparisons).
+ * @param {?} value - JSON-compatible value.
+ * @returns {string} - Stable JSON string.
+ */
+export default function stableJsonStringify(value) {
+  return JSON.stringify(stableJsonValue(value))
+}
+
+/**
+ * Produces a recursively key-sorted JSON value.
+ * @param {?} value - JSON-compatible value.
+ * @returns {?} - Stable JSON-compatible value.
+ */
+function stableJsonValue(value) {
+  if (Array.isArray(value)) return value.map((item) => stableJsonValue(item))
+  if (!value || typeof value !== "object") return value
+
+  return Object.keys(value).sort().reduce((memo, key) => {
+    memo[key] = stableJsonValue(value[key])
+
+    return memo
+  }, /** @type {Record<string, ?>} */ ({}))
+}