velocious 1.0.512 → 1.0.514

package/src/sync/sync-client.js

@@ -356,9 +356,11 @@ export default class SyncClient {
   /**
    * Declares (or re-activates) a sync scope from a model query and pulls it when online.
    * @param {import("../database/query/model-class-query.js").default<?>} query - Query declaring the sync scope.
+   * @param {object} [options] - Sync options.
+   * @param {(progress: import("./sync-api-client-types.js").SyncPullProgress) => void} [options.onProgress] - Called per applied page of the pull this declaration triggers, so the initial import of a newly declared scope can drive a "syncedCount of total" progress bar. See `pull()`.
    * @returns {Promise<{scope: import("./sync-client-types.js").SerializedSyncScope, pulled: import("./sync-api-client-types.js").SyncChangesResult | null}>} Declared scope and pull result (null while offline).
    */
-  async sync(query) {
+  async sync(query, {onProgress} = {}) {
     const scope = serializedScopeFromQuery(query)
     const scopeStore = this.scopeStore()
     const scopeRow = await scopeStore.findOrCreateScope(scope)
@@ -370,7 +372,7 @@ export default class SyncClient {
       if (legacyCursor) await scopeStore.saveCursor(scopeRow, legacyCursor)
     }
 
-    return {pulled: await this.pull(), scope}
+    return {pulled: await this.pull({onProgress}), scope}
   }
 
   /**
@@ -384,9 +386,11 @@ export default class SyncClient {
 
   /**
    * Pulls changes for every active scope with per-scope cursors (single-flighted, online-gated).
+   * @param {object} [options] - Pull options.
+   * @param {(progress: import("./sync-api-client-types.js").SyncPullProgress) => void} [options.onProgress] - Called per applied page with cumulative `{pages, syncedCount, total}` across the pulled scopes, for rendering a "syncedCount of total" progress bar (e.g. a full-import screen). Optional; omitting it keeps the existing behavior.
    * @returns {Promise<import("./sync-api-client-types.js").SyncChangesResult | null>} Combined pull result, or null while offline.
    */
-  async pull() {
+  async pull({onProgress} = {}) {
     if (!(await this.isOnline())) return null
 
     /** @type {import("./sync-api-client-types.js").SyncChangesResult | null} */
@@ -401,15 +405,27 @@ export default class SyncClient {
         pages: 0,
         resourceChanged: /** @type {Record<string, boolean>} */ ({}),
         resourceCounts: /** @type {Record<string, number>} */ ({}),
-        syncedCount: 0
+        syncedCount: 0,
+        total: 0
       }
 
       for (const scopeRow of await scopeStore.activeScopes()) {
+        // Cumulate scope progress onto the counts of the scopes already pulled so a single
+        // scope's per-page progress reads exactly its own counts (base 0), and multi-scope
+        // pulls report a running cumulative total across every scope.
+        const basePages = result.pages
+        const baseSyncedCount = result.syncedCount
+        const baseTotal = result.total
         const scopeResult = await SyncApiClient.pullChanges({
           applySync,
           authenticationToken,
           batchSize: this.config.batchSize,
           loadCursor: async () => await scopeStore.loadCursor(scopeRow),
+          onProgress: onProgress ? (progress) => onProgress({
+            pages: basePages + progress.pages,
+            syncedCount: baseSyncedCount + progress.syncedCount,
+            total: baseTotal + progress.total
+          }) : undefined,
           postChanges: async (payload) => await this.config.postChanges({
             ...payload,
             scope: {conditions: scopeRow.conditions, resourceType: scopeRow.resourceType}
@@ -420,6 +436,7 @@ export default class SyncClient {
         result.changed ||= scopeResult.changed
         result.pages += scopeResult.pages
         result.syncedCount += scopeResult.syncedCount
+        result.total += scopeResult.total
 
         for (const [resourceType, count] of Object.entries(scopeResult.resourceCounts)) {
           result.resourceCounts[resourceType] = (result.resourceCounts[resourceType] || 0) + count

package/src/sync/sync-model-change-feed-service.js

@@ -32,15 +32,19 @@ export default class SyncModelChangeFeedService {
   }
 
   /**
-   * Builds a stable change-feed page.
-   * @returns {Promise<{status: string, nextCursor: {id: string, serverSequence: number, updatedAt: string} | null, syncs: Array<Record<string, unknown>>, upToCursor: {id: string, serverSequence: number, updatedAt: string} | null}>} Change-feed page result.
+   * Builds a stable change-feed page. The additive `total` is the scope's pending
+   * change count from the request cursor to the snapshot bound (a COUNT, not a
+   * materialized read), so a client can render a "synced of total" progress bar;
+   * older clients ignore it.
+   * @returns {Promise<{status: string, nextCursor: {id: string, serverSequence: number, updatedAt: string} | null, syncs: Array<Record<string, unknown>>, total: number, upToCursor: {id: string, serverSequence: number, updatedAt: string} | null}>} Change-feed page result.
    */
   async changes() {
     const limit = this.normalizedLimit(this.params.limit)
     const upToCursor = await this.resolveUpToCursor()
 
-    if (!upToCursor) return {status: "success", nextCursor: null, syncs: [], upToCursor: null}
+    if (!upToCursor) return {status: "success", nextCursor: null, syncs: [], total: 0, upToCursor: null}
 
+    const total = await this.totalPendingChanges({upToCursor})
     const query = this.pageQuery({limit, upToCursor})
     const records = await query.toArray()
     const nextCursor = records.length > 0 ? this.cursorForRecord(records[records.length - 1]) : upToCursor
@@ -49,6 +53,7 @@ export default class SyncModelChangeFeedService {
       status: "success",
       nextCursor,
       syncs: records.map((record) => this.serializeRecord(record)),
+      total,
       upToCursor
     }
   }
@@ -124,6 +129,34 @@ export default class SyncModelChangeFeedService {
    * @returns {import("../database/query/model-class-query.js").default} Page query.
    */
   pageQuery({limit, upToCursor}) {
+    const query = this.cursorFilteredQuery({upToCursor})
+    const driver = query.driver
+    const serverSequenceColumn = `${driver.quoteTable(this.modelClass.tableName())}.${driver.quoteColumn("server_sequence")}`
+
+    return query
+      .order(`${serverSequenceColumn} ASC`)
+      .limit(limit)
+  }
+
+  /**
+   * Counts the scope's pending change rows from the request cursor to the snapshot
+   * bound without materializing them, so the client can render a stable "of Y"
+   * progress denominator.
+   * @param {{upToCursor: {id: string, serverSequence: number, updatedAt: string}}} args - Count args.
+   * @returns {Promise<number>} Pending change count from the request cursor.
+   */
+  async totalPendingChanges({upToCursor}) {
+    return await this.cursorFilteredQuery({upToCursor}).count()
+  }
+
+  /**
+   * Builds a scoped query with the snapshot upper bound and after-cursor filters
+   * applied, but without ordering or a page limit. Shared by the page read and the
+   * total-count so both count the same set of rows.
+   * @param {{upToCursor: {id: string, serverSequence: number, updatedAt: string}}} args - Filter args.
+   * @returns {import("../database/query/model-class-query.js").default} Cursor-filtered query.
+   */
+  cursorFilteredQuery({upToCursor}) {
     const query = this.scopedQuery()
     const driver = query.driver
     const table = driver.quoteTable(this.modelClass.tableName())
@@ -131,10 +164,7 @@ export default class SyncModelChangeFeedService {
     const updatedAtColumn = `${table}.${driver.quoteColumn("updated_at")}`
     const idColumn = `${table}.${driver.quoteColumn("id")}`
 
-    query
-      .where(`${serverSequenceColumn} <= ${driver.quote(upToCursor.serverSequence)}`)
-      .order(`${serverSequenceColumn} ASC`)
-      .limit(limit)
+    query.where(`${serverSequenceColumn} <= ${driver.quote(upToCursor.serverSequence)}`)
 
     const afterServerSequence = this.optionalPositiveIntegerParam(this.params.afterServerSequence, "afterServerSequence")