velocious 1.0.499 → 1.0.501

package/src/database/tenants/data-copier.js

@@ -94,6 +94,33 @@ export default class DataCopier {
     return sourceRowsByTableName
   }
 
+  /**
+   * Deletes one tenant's rows from the target database, children before parents, with
+   * foreign keys disabled inside a single transaction. This is `copy` without the reinsert:
+   * the same plan traversal selects the tenant's current target rows and `deleteTargetRows`
+   * removes them children-first so the ordering never trips a foreign key. Multi-tenant apps
+   * use it to purge a tenant — for example clearing the tenant's master copy in the
+   * global/default database on teardown, so foreign keys stop referencing the tenant's
+   * about-to-be-removed root row.
+   *
+   * Returns the deleted rows keyed by table name so the caller can perform any app-specific
+   * post-delete work (record-location cleanup, auditing) without that policy leaking into the
+   * framework.
+   * @param {string} keyValue - Tenant key whose rows should be removed from the target.
+   * @returns {Promise<Map<string, Record<string, unknown>[]>>} - The deleted rows by table name.
+   */
+  async deleteTenantRows(keyValue) {
+    const rowsByTableName = await this.loadRows(this.targetDb, keyValue)
+
+    await this.targetDb.withDisabledForeignKeys(async () => {
+      await this.targetDb.transaction(async () => {
+        await this.deleteTargetRows(rowsByTableName)
+      })
+    })
+
+    return rowsByTableName
+  }
+
   /**
    * Loads the rows for `keyValue` for every table in the plan from `db`, resolving
    * parent-scoped tables from the ids already selected for their parent table. Used for

package/src/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -167,11 +167,10 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     }
 
     for (const [frontendModelsDir, generatedFiles] of generatedFilesByDirectory) {
-      const indexContent = this.buildIndexFileContent(generatedFiles)
-
-      await fs.writeFile(`${frontendModelsDir}/index.js`, indexContent)
-
-      console.log("create src/frontend-models/index.js")
+      // The index.js barrel is no longer generated — nothing imports it (models are
+      // imported by file path, and setup.js performs the registration side-effects).
+      // Remove any stale one left from an older generator.
+      await fs.rm(`${frontendModelsDir}/index.js`, {force: true})
 
       const setupContent = this.buildSetupFileContent(generatedFiles)
 
@@ -632,21 +631,6 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     return fileContent
   }
 
-  /**
-   * Runs build index file content.
-   * @param {Array<{className: string, fileName: string}>} generatedFiles - Generated model files.
-   * @returns {string} - Index file content that imports and re-exports all models.
-   */
-  buildIndexFileContent(generatedFiles) {
-    let content = generatedFileBanner(FRONTEND_MODELS_REGENERATE_COMMAND)
-
-    for (const {className, fileName} of generatedFiles) {
-      content += `export {default as ${className}} from "./${fileName}"\n`
-    }
-
-    return content
-  }
-
   /**
    * Runs build setup file content.
    * @param {Array<{className: string, fileName: string}>} generatedFiles - Generated model files.

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

@@ -7,6 +7,15 @@
  * @property {string} resourceType - Resource/model name the scope was declared for.
  */
 
+/**
+ * Static realtime channel declaration on a model's `static sync`, for channels
+ * whose name and params are static. Channels needing runtime params (like
+ * eventId) belong in the `sync.client.realtime.channels` callback instead.
+ * @typedef {object} ModelSyncRealtimeDeclaration
+ * @property {string} channel - Server channel name to subscribe.
+ * @property {Record<string, ?>} [params] - Static subscribe params. The framework injects `authenticationToken` automatically.
+ */
+
 /**
  * Declarative per-resource sync policy.
  * @typedef {object} SyncClientResourceConfig
@@ -20,6 +29,7 @@
  * @property {"upsert" | ((args: {operation: "create" | "update" | "destroy", record: ?}) => string)} [syncType] - Maps a mutation operation to a sync type. The "upsert" flag queues creates and updates as "update" rows (the server upserts by resource id) and destroys as "delete". Defaults to the operation name with destroy mapped to "delete".
  * @property {(args: {operation: "create" | "update" | "destroy", record: ?}) => Record<string, ?>} [trackedData] - Custom queued-payload builder for tracked mutations.
  * @property {boolean | {operations: Array<"create" | "update" | "destroy">}} [track] - Enables automatic mutation tracking through model lifecycle callbacks.
+ * @property {ModelSyncRealtimeDeclaration} [realtime] - Static realtime channel this resource subscribes through `subscribeRealtime(...)`.
  */
 
 /**
@@ -36,6 +46,7 @@
  * @property {"upsert" | ((args: {operation: "create" | "update" | "destroy", record: ?}) => string)} [syncType] - Sync type flag or mapper (see SyncClientResourceConfig).
  * @property {boolean | Array<"create" | "update" | "destroy"> | {operations: Array<"create" | "update" | "destroy">}} [track] - Enables automatic mutation tracking; an array is shorthand for {operations}.
  * @property {(args: {operation: "create" | "update" | "destroy", record: ?}) => Record<string, ?>} [trackedData] - Custom queued-payload builder for tracked mutations.
+ * @property {ModelSyncRealtimeDeclaration} [realtime] - Static realtime channel this resource subscribes through `subscribeRealtime(...)`; use the `sync.client.realtime.channels` callback for channels needing runtime params.
  */
 
 /** @typedef {boolean | ModelSyncDeclarationConfig} ModelSyncDeclaration */
@@ -63,6 +74,7 @@
  * @property {(error: Error) => void} [onError] - Reports background replay/pull failures. Defaults to rethrowing.
  * @property {(payload: import("./sync-api-client-types.js").SyncChangesRequest & {scope: SerializedSyncScope}) => Promise<import("./sync-api-client-types.js").SyncChangesResponse>} postChanges - Posts one changes request.
  * @property {(payload: {authenticationToken: string, syncs: Array<Record<string, ?>>}) => Promise<import("./sync-api-client-types.js").SyncReplayResponse>} postReplay - Posts one replay request.
+ * @property {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} [realtime] - Realtime push configuration consumed by `subscribeRealtime(...)`.
  * @property {Record<string, SyncClientResourceConfig>} resources - Derived resource policies keyed by resource/model name.
  * @property {?} syncModel - Local pending-sync model class.
  */

package/src/sync/sync-client.js

@@ -6,6 +6,7 @@ import restArgsError from "../utils/rest-args-error.js"
 
 import {serializedScopeFromQuery} from "./query-scope.js"
 import SyncApiClient from "./sync-api-client.js"
+import SyncRealtimeBridge from "./sync-realtime-bridge.js"
 import SyncScopeStore from "./sync-scope-store.js"
 import {currentSyncClient, setCurrentSyncClient} from "./sync-client-registry.js"
 
@@ -87,10 +88,13 @@ export default class SyncClient {
       onError: clientConfiguration.onError,
       postChanges: transportPoster({path: `${clientConfiguration.mountPath}/changes`, transport: clientConfiguration.transport}),
       postReplay: transportPoster({path: `${clientConfiguration.mountPath}/replay`, transport: clientConfiguration.transport}),
+      realtime: clientConfiguration.realtime,
       resources,
       syncModel: resolvedSyncModel
     }
     this._clientNumber = ++clientCounter
+    /** @type {SyncRealtimeBridge | null} */
+    this._realtimeBridge = null
     /** @type {import("./sync-scope-store.js").default | null} */
     this._scopeStore = scopeStore || null
     /** @type {Promise<void> | null} */
@@ -265,26 +269,7 @@ export default class SyncClient {
     await SyncApiClient.singleFlight(`velocious-sync-client-pull-${this._clientNumber}`, async () => {
       const authenticationToken = await this.config.authenticationToken()
       const scopeStore = this.scopeStore()
-      const pullResourceConfigs = this.pullResourceConfigs()
-      const applier = SyncApiClient.resourceApplier(pullResourceConfigs, (record) => {
-        this._remoteApplyRecords.add(record)
-
-        return () => this._remoteApplyRecords.delete(record)
-      })
-      /**
-       * Applies one pulled change, failing loudly instead of silently skipping unconfigured resources.
-       * @param {import("./sync-api-client-types.js").SyncChangeEnvelope} sync - Pulled change.
-       * @returns {Promise<import("./sync-api-client-types.js").SyncChangeApplyResult>} Apply result.
-       */
-      const applySync = async (sync) => {
-        const resourceType = sync.resourceType()
-
-        if (!resourceType || !pullResourceConfigs[resourceType]) {
-          throw new Error(`No sync resource with pull attributes configured for pulled change: ${String(resourceType)}`)
-        }
-
-        return await applier(sync)
-      }
+      const applySync = this.remoteApplySync()
       const result = {
         changed: false,
         pages: 0,
@@ -324,6 +309,78 @@ export default class SyncClient {
     return combinedResult
   }
 
+  /**
+   * Builds the derived remote-change applier shared by pulls and realtime pushes:
+   * applies through the declared resource configs, registers each written record
+   * for echo suppression (tracked resources do not re-queue applied changes), and
+   * fails loudly instead of silently skipping unconfigured resources.
+   * @param {{source?: string}} [args] - Error context describing where the change came from.
+   * @returns {(sync: import("./sync-api-client-types.js").SyncChangeEnvelope) => Promise<import("./sync-api-client-types.js").SyncChangeApplyResult>} Loud remote-change applier.
+   */
+  remoteApplySync({source = "pulled change"} = {}) {
+    const pullResourceConfigs = this.pullResourceConfigs()
+    const applier = SyncApiClient.resourceApplier(pullResourceConfigs, (record) => {
+      this._remoteApplyRecords.add(record)
+
+      return () => this._remoteApplyRecords.delete(record)
+    })
+
+    return async (sync) => {
+      const resourceType = sync.resourceType()
+
+      if (!resourceType || !pullResourceConfigs[resourceType]) {
+        throw new Error(`No sync resource with pull attributes configured for ${source}: ${String(resourceType)}`)
+      }
+
+      return await applier(sync)
+    }
+  }
+
+  /**
+   * Subscribes the derived realtime channels so pushed websocket changes apply
+   * through the same derived applier as pulls (idempotent, single-flighted).
+   * @param {?} [context] - App context passed to the `sync.client.realtime.channels` callback (runtime values like eventId).
+   * @returns {Promise<void>}
+   */
+  async subscribeRealtime(context) {
+    await this.realtimeBridge().subscribe(context)
+  }
+
+  /**
+   * Unsubscribes the realtime channels and disconnects the websocket client (idempotent).
+   * @returns {Promise<void>}
+   */
+  async unsubscribeRealtime() {
+    await this.realtimeBridge().unsubscribe()
+  }
+
+  /**
+   * Reports the realtime subscription state and per-channel readiness.
+   * @returns {ReturnType<SyncRealtimeBridge["status"]>} Realtime status.
+   */
+  realtimeStatus() {
+    return this.realtimeBridge().status()
+  }
+
+  /**
+   * Awaits all pending realtime message applies and any scheduled
+   * pull-on-reconnect (useful in tests and shutdown flows).
+   * @returns {Promise<void>}
+   */
+  async waitForRealtimeApplied() {
+    await this.realtimeBridge().waitForApplied()
+  }
+
+  /**
+   * Returns the lazily built realtime bridge.
+   * @returns {SyncRealtimeBridge} Realtime bridge.
+   */
+  realtimeBridge() {
+    this._realtimeBridge ||= new SyncRealtimeBridge({syncClient: this})
+
+    return this._realtimeBridge
+  }
+
   /**
    * Queues a local model change as a pending sync row and schedules an immediate
    * replay attempt (kept pending while offline or when the backend rejects it).
@@ -491,11 +548,11 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
     throw new Error(`${resourceType} static sync must be true or a sync declaration object, got: ${String(declaration)}`)
   }
 
-  const {afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
+  const {afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, realtime, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
   const unknownKeys = Object.keys(restDeclaration)
 
   if (unknownKeys.length > 0) {
-    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, syncType, track, trackedData)`)
+    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, realtime, syncType, track, trackedData)`)
   }
   if (syncType !== undefined && typeof syncType !== "function" && syncType !== "upsert") {
     throw new Error(`${resourceType} static sync syncType must be a function or the string "upsert", got: ${String(syncType)}`)
@@ -511,6 +568,7 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
     findRecordForDelete,
     localOnlyAttributes: mergedAttributeNames(derived.localOnlyAttributes, localOnlyAttributes),
     modelClass,
+    realtime,
     syncType,
     track: normalizedTrack(track),
     trackedData

package/src/sync/sync-realtime-bridge.js

@@ -0,0 +1,299 @@
+// @ts-check
+
+import SyncApiClient from "./sync-api-client.js"
+
+/** @typedef {import("../configuration-types.js").VelociousSyncRealtimeChannelDescriptor} VelociousSyncRealtimeChannelDescriptor */
+/** @typedef {import("../configuration-types.js").VelociousSyncRealtimeWebsocketClient} VelociousSyncRealtimeWebsocketClient */
+
+/**
+ * Derived realtime push bridge for the sync client. Subscribes the declared
+ * websocket channels (config `sync.client.realtime.channels` callback plus
+ * model-level `static sync = {realtime: {channel}}` declarations), applies
+ * pushed changes through the same derived resource applier as pulls (with echo
+ * suppression against tracked re-queueing), drops own-device messages by echo
+ * origin, and fires a coalesced `pull()` when subscriptions become ready or
+ * resume so offline gaps close.
+ */
+export default class SyncRealtimeBridge {
+  /**
+   * Builds the bridge for a sync client.
+   * @param {{syncClient: import("./sync-client.js").default}} args - Bridge args.
+   */
+  constructor({syncClient}) {
+    this.syncClient = syncClient
+    /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
+    this._channels = []
+    /** @type {VelociousSyncRealtimeWebsocketClient | null} */
+    this._client = null
+    /** @type {Promise<void>} */
+    this._applyPromise = Promise.resolve()
+    /** @type {number} Subscription generation - bumped by unsubscribe so in-flight subscribes detect they became stale. */
+    this._generation = 0
+    /** @type {Promise<void> | null} */
+    this._scheduledPull = null
+    /** @type {Promise<void> | null} */
+    this._subscribePromise = null
+    /** @type {"subscribed" | "subscribing" | "unsubscribed"} */
+    this._state = "unsubscribed"
+  }
+
+  /**
+   * Subscribes the derived realtime channels (idempotent and single-flighted):
+   * an active subscription is kept as-is and a concurrent subscribe awaits the
+   * in-flight attempt. Call `unsubscribe()` first to change the context.
+   * @param {?} [context] - App context passed to the `sync.client.realtime.channels` callback (runtime values like eventId).
+   * @returns {Promise<void>}
+   */
+  async subscribe(context) {
+    if (this._state === "subscribed") return
+
+    if (!this._subscribePromise) {
+      this._subscribePromise = this._subscribe(context).finally(() => {
+        this._subscribePromise = null
+      })
+    }
+
+    await this._subscribePromise
+  }
+
+  /**
+   * Connects the websocket client, subscribes every derived channel, and waits
+   * for each subscription's server acknowledgement before the gap-closing pull,
+   * so no change can land between the pull and the subscriptions going live.
+   * Locally created resources are only promoted to the bridge once everything
+   * is live; an unsubscribe arriving during any await marks this attempt stale
+   * and it tears its own resources down instead of resubscribing.
+   * @param {?} context - App context passed to the channels callback.
+   * @returns {Promise<void>}
+   */
+  async _subscribe(context) {
+    const generation = this._generation
+
+    this._state = "subscribing"
+
+    /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
+    const channels = []
+    /** @type {VelociousSyncRealtimeWebsocketClient | null} */
+    let client = null
+    /**
+     * Tears down everything this stale/failed subscribe attempt created itself.
+     * @returns {Promise<void>}
+     */
+    const teardown = async () => {
+      for (const {subscription} of channels) {
+        subscription.close()
+      }
+
+      if (client) await client.disconnectAndStopReconnect()
+    }
+
+    try {
+      const realtime = this.realtimeConfiguration()
+      const channelDescriptors = await this.channelDescriptors(context)
+
+      if (generation !== this._generation) return
+
+      client = await realtime.createClient()
+
+      if (generation !== this._generation) return
+
+      await client.connect()
+
+      if (generation !== this._generation) {
+        await teardown()
+        return
+      }
+
+      const authenticationToken = await this.syncClient.config.authenticationToken()
+
+      if (generation !== this._generation) {
+        await teardown()
+        return
+      }
+
+      for (const channelDescriptor of channelDescriptors) {
+        if (channelDescriptor.params && "authenticationToken" in channelDescriptor.params) {
+          throw new Error(`Realtime channel "${channelDescriptor.channel}" params must not include authenticationToken - the framework injects the sync.client authenticationToken automatically`)
+        }
+
+        const resourceType = channelDescriptor.resourceType ?? null
+        const subscription = client.subscribeChannel(channelDescriptor.channel, {
+          onMessage: (body) => this.enqueueApply({body, resourceType}),
+          onResume: () => this.schedulePull(),
+          params: {...channelDescriptor.params, authenticationToken}
+        })
+
+        channels.push({channel: channelDescriptor.channel, resourceType, subscription})
+      }
+
+      await Promise.all(channels.map(({subscription}) => subscription.waitForReady()))
+
+      if (generation !== this._generation) {
+        await teardown()
+        return
+      }
+
+      this._channels = channels
+      this._client = client
+      this._state = "subscribed"
+      this.schedulePull()
+    } catch (error) {
+      await teardown()
+
+      if (generation === this._generation) this._state = "unsubscribed"
+
+      throw error
+    }
+  }
+
+  /**
+   * Closes every channel subscription and disconnects the websocket client
+   * (idempotent). Also marks any in-flight subscribe attempt stale so it tears
+   * itself down instead of finishing the subscription afterwards.
+   * @returns {Promise<void>}
+   */
+  async unsubscribe() {
+    this._generation += 1
+
+    const channels = this._channels
+    const client = this._client
+
+    this._channels = []
+    this._client = null
+    this._state = "unsubscribed"
+
+    for (const {subscription} of channels) {
+      subscription.close()
+    }
+
+    if (client) await client.disconnectAndStopReconnect()
+  }
+
+  /**
+   * Reports the bridge subscription state and per-channel readiness.
+   * @returns {{channels: Array<{channel: string, ready: boolean, resourceType: string | null}>, state: "subscribed" | "subscribing" | "unsubscribed"}} Realtime status.
+   */
+  status() {
+    return {
+      channels: this._channels.map(({channel, resourceType, subscription}) => ({channel, ready: subscription.isReady(), resourceType})),
+      state: this._state
+    }
+  }
+
+  /**
+   * Awaits all enqueued message applies and any scheduled pull (tests, shutdown flows).
+   * @returns {Promise<void>}
+   */
+  async waitForApplied() {
+    await this._applyPromise
+    if (this._scheduledPull) await this._scheduledPull
+  }
+
+  /**
+   * Resolves the realtime configuration, failing loudly when it is missing.
+   * @returns {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} Realtime configuration.
+   */
+  realtimeConfiguration() {
+    const realtime = this.syncClient.config.realtime
+
+    if (!realtime) {
+      throw new Error("subscribeRealtime requires a sync.client.realtime configuration block with a createClient callback")
+    }
+
+    return realtime
+  }
+
+  /**
+   * Derives the channel descriptors to subscribe: model-level static realtime
+   * declarations plus the config channels callback, failing loudly when none exist.
+   * @param {?} context - App context passed to the channels callback.
+   * @returns {Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} Channel descriptors.
+   */
+  async channelDescriptors(context) {
+    const realtime = this.realtimeConfiguration()
+    /** @type {Array<VelociousSyncRealtimeChannelDescriptor>} */
+    const channelDescriptors = []
+
+    for (const [resourceType, resourceConfig] of Object.entries(this.syncClient.config.resources)) {
+      if (!resourceConfig.realtime) continue
+
+      channelDescriptors.push({channel: resourceConfig.realtime.channel, params: resourceConfig.realtime.params, resourceType})
+    }
+
+    if (realtime.channels) {
+      channelDescriptors.push(...await realtime.channels(context))
+    }
+
+    if (channelDescriptors.length === 0) {
+      throw new Error("subscribeRealtime found no realtime channels - declare sync.client.realtime.channels or static sync = {realtime: {channel}} on a model")
+    }
+
+    return channelDescriptors
+  }
+
+  /**
+   * Chains one pushed message onto the serialized apply queue so changes apply
+   * in arrival order; failures go to the sync client's error reporting.
+   * @param {{body: ?, resourceType: string | null}} args - Message args.
+   * @returns {void}
+   */
+  enqueueApply({body, resourceType}) {
+    this._applyPromise = this._applyPromise.then(async () => {
+      try {
+        await this.applyMessage({body, resourceType})
+      } catch (error) {
+        this.syncClient.reportError(/** @type {Error} */ (error))
+      }
+    })
+  }
+
+  /**
+   * Applies one pushed message through the derived resource applier: drops
+   * own-device messages by echo origin, defaults the channel's resourceType onto
+   * envelopes without one, and fails loudly on unknown resource types.
+   * @param {{body: ?, resourceType: string | null}} args - Message args.
+   * @returns {Promise<void>}
+   */
+  async applyMessage({body, resourceType}) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+      throw new Error(`Realtime sync messages must be envelope objects, got: ${JSON.stringify(body)}`)
+    }
+
+    const realtime = this.realtimeConfiguration()
+
+    if (realtime.localOrigin && body.echoOrigin !== undefined && body.echoOrigin !== null) {
+      const localOrigin = String(await realtime.localOrigin())
+
+      if (String(body.echoOrigin) === localOrigin) return
+    }
+
+    const syncPayloads = Array.isArray(body.syncs) ? body.syncs : [body]
+    const applySync = this.syncClient.remoteApplySync({source: "remote change"})
+
+    for (const syncPayload of syncPayloads) {
+      const sync = SyncApiClient.syncEnvelopeFromPayload({resourceType, ...syncPayload})
+
+      await applySync(sync)
+    }
+  }
+
+  /**
+   * Schedules a coalesced background pull closing offline gaps after
+   * (re)subscription readiness. Resumes arriving while a pull is already
+   * scheduled or in flight coalesce into that pull instead of stacking.
+   * @returns {void}
+   */
+  schedulePull() {
+    if (this.realtimeConfiguration().pullOnReconnect === false) return
+
+    this._scheduledPull ||= (async () => {
+      try {
+        await this.syncClient.pull()
+      } catch (error) {
+        this.syncClient.reportError(/** @type {Error} */ (error))
+      } finally {
+        this._scheduledPull = null
+      }
+    })()
+  }
+}