stripe-experiment-sync 1.0.18 → 1.0.19

package/dist/cli/lib.cjs

@@ -117,7 +117,7 @@ async function loadConfig(options) {
 // package.json
 var package_default = {
   name: "stripe-experiment-sync",
-  version: "1.0.18",
+  version: "1.0.19",
   private: false,
   description: "Stripe Sync Engine to sync Stripe data to Postgres",
   type: "module",
@@ -594,7 +594,8 @@ var PostgresClient = class {
       `UPDATE "${this.config.schema}"."_sync_obj_runs" o
        SET status = 'error',
            error_message = 'Auto-cancelled: stale (no update in 5 min)',
-           completed_at = now()
+           completed_at = now(),
+           page_cursor = NULL
        WHERE o."_account_id" = $1
          AND o.status = 'running'
          AND o.updated_at < now() - interval '5 minutes'`,
@@ -740,7 +741,7 @@ var PostgresClient = class {
    */
   async getObjectRun(accountId, runStartedAt, object) {
     const result = await this.query(
-      `SELECT object, status, processed_count, cursor
+      `SELECT object, status, processed_count, cursor, page_cursor
        FROM "${this.config.schema}"."_sync_obj_runs"
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object]
@@ -751,7 +752,8 @@ var PostgresClient = class {
       object: row.object,
       status: row.status,
       processedCount: row.processed_count,
-      cursor: row.cursor
+      cursor: row.cursor,
+      pageCursor: row.page_cursor
     };
   }
   /**
@@ -766,6 +768,23 @@ var PostgresClient = class {
       [accountId, runStartedAt, object, count]
     );
   }
+  /**
+   * Update the pagination page_cursor used for backfills using Stripe list calls.
+   */
+  async updateObjectPageCursor(accountId, runStartedAt, object, pageCursor) {
+    await this.query(
+      `UPDATE "${this.config.schema}"."_sync_obj_runs"
+       SET page_cursor = $4, updated_at = now()
+       WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
+      [accountId, runStartedAt, object, pageCursor]
+    );
+  }
+  /**
+   * Clear the pagination page_cursor for an object sync.
+   */
+  async clearObjectPageCursor(accountId, runStartedAt, object) {
+    await this.updateObjectPageCursor(accountId, runStartedAt, object, null);
+  }
   /**
    * Update the cursor for an object sync.
    * Only updates if the new cursor is higher than the existing one (cursors should never decrease).
@@ -798,9 +817,10 @@ var PostgresClient = class {
   }
   /**
    * Get the highest cursor from previous syncs for an object type.
-   * This considers completed, error, AND running runs to ensure recovery syncs
-   * don't re-process data that was already synced before a crash.
-   * A 'running' status with a cursor means the process was killed mid-sync.
+   * Uses only completed object runs.
+   * - During the initial backfill we page through history, but we also update the cursor as we go.
+   *   If we crash mid-backfill and reuse that cursor, we can accidentally switch into incremental mode
+   *   too early and only ever fetch the newest page (breaking the historical backfill).
    *
    * Handles two cursor formats:
    * - Numeric: compared as bigint for correct ordering
@@ -815,11 +835,31 @@ var PostgresClient = class {
        FROM "${this.config.schema}"."_sync_obj_runs" o
        WHERE o."_account_id" = $1
          AND o.object = $2
-         AND o.cursor IS NOT NULL`,
+         AND o.cursor IS NOT NULL
+         AND o.status = 'complete'`,
       [accountId, object]
     );
     return result.rows[0]?.cursor ?? null;
   }
+  /**
+   * Get the highest cursor from previous syncs for an object type, excluding the current run.
+   */
+  async getLastCursorBeforeRun(accountId, object, runStartedAt) {
+    const result = await this.query(
+      `SELECT CASE
+         WHEN BOOL_OR(o.cursor !~ '^\\d+$') THEN MAX(o.cursor COLLATE "C")
+         ELSE MAX(CASE WHEN o.cursor ~ '^\\d+$' THEN o.cursor::bigint END)::text
+       END as cursor
+       FROM "${this.config.schema}"."_sync_obj_runs" o
+       WHERE o."_account_id" = $1
+         AND o.object = $2
+         AND o.cursor IS NOT NULL
+         AND o.status = 'complete'
+         AND o.run_started_at < $3`,
+      [accountId, object, runStartedAt]
+    );
+    return result.rows[0]?.cursor ?? null;
+  }
   /**
    * Delete all sync runs and object runs for an account.
    * Useful for testing or resetting sync state.
@@ -840,7 +880,7 @@ var PostgresClient = class {
   async completeObjectSync(accountId, runStartedAt, object) {
     await this.query(
       `UPDATE "${this.config.schema}"."_sync_obj_runs"
-       SET status = 'complete', completed_at = now()
+       SET status = 'complete', completed_at = now(), page_cursor = NULL
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object]
     );
@@ -856,7 +896,7 @@ var PostgresClient = class {
   async failObjectSync(accountId, runStartedAt, object, errorMessage) {
     await this.query(
       `UPDATE "${this.config.schema}"."_sync_obj_runs"
-       SET status = 'error', error_message = $4, completed_at = now()
+       SET status = 'error', error_message = $4, completed_at = now(), page_cursor = NULL
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object, errorMessage]
     );
@@ -2157,57 +2197,74 @@ var StripeSync = class {
    * ```
    */
   async processNext(object, params) {
-    await this.getCurrentAccount();
-    const accountId = await this.getAccountId();
-    const resourceName = this.getResourceName(object);
-    let runStartedAt;
-    if (params?.runStartedAt) {
-      runStartedAt = params.runStartedAt;
-    } else {
-      const { runKey } = await this.joinOrCreateSyncRun(params?.triggeredBy ?? "processNext");
-      runStartedAt = runKey.runStartedAt;
-    }
-    await this.postgresClient.createObjectRuns(accountId, runStartedAt, [resourceName]);
-    const objRun = await this.postgresClient.getObjectRun(accountId, runStartedAt, resourceName);
-    if (objRun?.status === "complete" || objRun?.status === "error") {
-      return {
-        processed: 0,
-        hasMore: false,
-        runStartedAt
-      };
-    }
-    if (objRun?.status === "pending") {
-      const started = await this.postgresClient.tryStartObjectSync(
-        accountId,
-        runStartedAt,
-        resourceName
-      );
-      if (!started) {
+    try {
+      await this.getCurrentAccount();
+      const accountId = await this.getAccountId();
+      const resourceName = this.getResourceName(object);
+      let runStartedAt;
+      if (params?.runStartedAt) {
+        runStartedAt = params.runStartedAt;
+      } else {
+        const { runKey } = await this.joinOrCreateSyncRun(params?.triggeredBy ?? "processNext");
+        runStartedAt = runKey.runStartedAt;
+      }
+      await this.postgresClient.createObjectRuns(accountId, runStartedAt, [resourceName]);
+      const objRun = await this.postgresClient.getObjectRun(accountId, runStartedAt, resourceName);
+      if (objRun?.status === "complete" || objRun?.status === "error") {
         return {
           processed: 0,
-          hasMore: true,
+          hasMore: false,
           runStartedAt
         };
       }
-    }
-    let cursor = null;
-    if (!params?.created) {
-      if (objRun?.cursor) {
-        cursor = objRun.cursor;
-      } else {
-        const lastCursor = await this.postgresClient.getLastCompletedCursor(accountId, resourceName);
+      if (objRun?.status === "pending") {
+        const started = await this.postgresClient.tryStartObjectSync(
+          accountId,
+          runStartedAt,
+          resourceName
+        );
+        if (!started) {
+          return {
+            processed: 0,
+            hasMore: true,
+            runStartedAt
+          };
+        }
+      }
+      let cursor = null;
+      if (!params?.created) {
+        const lastCursor = await this.postgresClient.getLastCursorBeforeRun(
+          accountId,
+          resourceName,
+          runStartedAt
+        );
         cursor = lastCursor ?? null;
       }
+      const result = await this.fetchOnePage(
+        object,
+        accountId,
+        resourceName,
+        runStartedAt,
+        cursor,
+        objRun?.pageCursor ?? null,
+        params
+      );
+      return result;
+    } catch (error) {
+      throw this.appendMigrationHint(error);
     }
-    const result = await this.fetchOnePage(
-      object,
-      accountId,
-      resourceName,
-      runStartedAt,
-      cursor,
-      params
-    );
-    return result;
+  }
+  appendMigrationHint(error) {
+    const hint = "Error occurred. Make sure you are up to date with DB migrations which can sometimes help with this. Details:";
+    const withHint = (message) => message.includes(hint) ? message : `${hint}
+${message}`;
+    if (error instanceof Error) {
+      const { stack } = error;
+      error.message = withHint(error.message);
+      if (stack) error.stack = stack;
+      return error;
+    }
+    return new Error(withHint(String(error)));
   }
   /**
    * Get the database resource name for a SyncObject type
@@ -2239,7 +2296,7 @@ var StripeSync = class {
    * Uses resourceRegistry for DRY list/upsert operations.
    * Uses the observable sync system for tracking progress.
    */
-  async fetchOnePage(object, accountId, resourceName, runStartedAt, cursor, params) {
+  async fetchOnePage(object, accountId, resourceName, runStartedAt, cursor, pageCursor, params) {
     const limit = 100;
     if (object === "payment_method" || object === "tax_id") {
       this.config.logger?.warn(`processNext for ${object} requires customer context`);
@@ -2267,7 +2324,16 @@ var StripeSync = class {
           listParams.created = created;
         }
       }
+      if (pageCursor) {
+        listParams.starting_after = pageCursor;
+      }
       const response = await config.listFn(listParams);
+      if (response.data.length === 0 && response.has_more) {
+        const message = `Stripe returned has_more=true with empty page for ${resourceName}. Aborting to avoid infinite loop.`;
+        this.config.logger?.warn(message);
+        await this.postgresClient.failObjectSync(accountId, runStartedAt, resourceName, message);
+        return { processed: 0, hasMore: false, runStartedAt };
+      }
       if (response.data.length > 0) {
         this.config.logger?.info(`processNext: upserting ${response.data.length} ${resourceName}`);
         await config.upsertFn(response.data, accountId, params?.backfillRelatedEntities);
@@ -2288,6 +2354,15 @@ var StripeSync = class {
             String(maxCreated)
           );
         }
+        const lastId = response.data[response.data.length - 1].id;
+        if (response.has_more) {
+          await this.postgresClient.updateObjectPageCursor(
+            accountId,
+            runStartedAt,
+            resourceName,
+            lastId
+          );
+        }
       }
       if (!response.has_more) {
         await this.postgresClient.completeObjectSync(accountId, runStartedAt, resourceName);

package/dist/cli/lib.js

@@ -6,10 +6,10 @@ import {
   migrateCommand,
   syncCommand,
   uninstallCommand
-} from "../chunk-HV64EIZU.js";
-import "../chunk-K4JQHI7Y.js";
-import "../chunk-M5TTM27L.js";
-import "../chunk-XO57OJUE.js";
+} from "../chunk-HZ2OIPQ5.js";
+import "../chunk-XKBCLBFT.js";
+import "../chunk-4P6TAP7L.js";
+import "../chunk-CMGFQCD7.js";
 export {
   backfillCommand,
   createTunnel,

package/dist/index.cjs

@@ -46,7 +46,7 @@ var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 // package.json
 var package_default = {
   name: "stripe-experiment-sync",
-  version: "1.0.18",
+  version: "1.0.19",
   private: false,
   description: "Stripe Sync Engine to sync Stripe data to Postgres",
   type: "module",
@@ -523,7 +523,8 @@ var PostgresClient = class {
       `UPDATE "${this.config.schema}"."_sync_obj_runs" o
        SET status = 'error',
            error_message = 'Auto-cancelled: stale (no update in 5 min)',
-           completed_at = now()
+           completed_at = now(),
+           page_cursor = NULL
        WHERE o."_account_id" = $1
          AND o.status = 'running'
          AND o.updated_at < now() - interval '5 minutes'`,
@@ -669,7 +670,7 @@ var PostgresClient = class {
    */
   async getObjectRun(accountId, runStartedAt, object) {
     const result = await this.query(
-      `SELECT object, status, processed_count, cursor
+      `SELECT object, status, processed_count, cursor, page_cursor
        FROM "${this.config.schema}"."_sync_obj_runs"
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object]
@@ -680,7 +681,8 @@ var PostgresClient = class {
       object: row.object,
       status: row.status,
       processedCount: row.processed_count,
-      cursor: row.cursor
+      cursor: row.cursor,
+      pageCursor: row.page_cursor
     };
   }
   /**
@@ -695,6 +697,23 @@ var PostgresClient = class {
       [accountId, runStartedAt, object, count]
     );
   }
+  /**
+   * Update the pagination page_cursor used for backfills using Stripe list calls.
+   */
+  async updateObjectPageCursor(accountId, runStartedAt, object, pageCursor) {
+    await this.query(
+      `UPDATE "${this.config.schema}"."_sync_obj_runs"
+       SET page_cursor = $4, updated_at = now()
+       WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
+      [accountId, runStartedAt, object, pageCursor]
+    );
+  }
+  /**
+   * Clear the pagination page_cursor for an object sync.
+   */
+  async clearObjectPageCursor(accountId, runStartedAt, object) {
+    await this.updateObjectPageCursor(accountId, runStartedAt, object, null);
+  }
   /**
    * Update the cursor for an object sync.
    * Only updates if the new cursor is higher than the existing one (cursors should never decrease).
@@ -727,9 +746,10 @@ var PostgresClient = class {
   }
   /**
    * Get the highest cursor from previous syncs for an object type.
-   * This considers completed, error, AND running runs to ensure recovery syncs
-   * don't re-process data that was already synced before a crash.
-   * A 'running' status with a cursor means the process was killed mid-sync.
+   * Uses only completed object runs.
+   * - During the initial backfill we page through history, but we also update the cursor as we go.
+   *   If we crash mid-backfill and reuse that cursor, we can accidentally switch into incremental mode
+   *   too early and only ever fetch the newest page (breaking the historical backfill).
    *
    * Handles two cursor formats:
    * - Numeric: compared as bigint for correct ordering
@@ -744,11 +764,31 @@ var PostgresClient = class {
        FROM "${this.config.schema}"."_sync_obj_runs" o
        WHERE o."_account_id" = $1
          AND o.object = $2
-         AND o.cursor IS NOT NULL`,
+         AND o.cursor IS NOT NULL
+         AND o.status = 'complete'`,
       [accountId, object]
     );
     return result.rows[0]?.cursor ?? null;
   }
+  /**
+   * Get the highest cursor from previous syncs for an object type, excluding the current run.
+   */
+  async getLastCursorBeforeRun(accountId, object, runStartedAt) {
+    const result = await this.query(
+      `SELECT CASE
+         WHEN BOOL_OR(o.cursor !~ '^\\d+$') THEN MAX(o.cursor COLLATE "C")
+         ELSE MAX(CASE WHEN o.cursor ~ '^\\d+$' THEN o.cursor::bigint END)::text
+       END as cursor
+       FROM "${this.config.schema}"."_sync_obj_runs" o
+       WHERE o."_account_id" = $1
+         AND o.object = $2
+         AND o.cursor IS NOT NULL
+         AND o.status = 'complete'
+         AND o.run_started_at < $3`,
+      [accountId, object, runStartedAt]
+    );
+    return result.rows[0]?.cursor ?? null;
+  }
   /**
    * Delete all sync runs and object runs for an account.
    * Useful for testing or resetting sync state.
@@ -769,7 +809,7 @@ var PostgresClient = class {
   async completeObjectSync(accountId, runStartedAt, object) {
     await this.query(
       `UPDATE "${this.config.schema}"."_sync_obj_runs"
-       SET status = 'complete', completed_at = now()
+       SET status = 'complete', completed_at = now(), page_cursor = NULL
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object]
     );
@@ -785,7 +825,7 @@ var PostgresClient = class {
   async failObjectSync(accountId, runStartedAt, object, errorMessage) {
     await this.query(
       `UPDATE "${this.config.schema}"."_sync_obj_runs"
-       SET status = 'error', error_message = $4, completed_at = now()
+       SET status = 'error', error_message = $4, completed_at = now(), page_cursor = NULL
        WHERE "_account_id" = $1 AND run_started_at = $2 AND object = $3`,
       [accountId, runStartedAt, object, errorMessage]
     );
@@ -2086,57 +2126,74 @@ var StripeSync = class {
    * ```
    */
   async processNext(object, params) {
-    await this.getCurrentAccount();
-    const accountId = await this.getAccountId();
-    const resourceName = this.getResourceName(object);
-    let runStartedAt;
-    if (params?.runStartedAt) {
-      runStartedAt = params.runStartedAt;
-    } else {
-      const { runKey } = await this.joinOrCreateSyncRun(params?.triggeredBy ?? "processNext");
-      runStartedAt = runKey.runStartedAt;
-    }
-    await this.postgresClient.createObjectRuns(accountId, runStartedAt, [resourceName]);
-    const objRun = await this.postgresClient.getObjectRun(accountId, runStartedAt, resourceName);
-    if (objRun?.status === "complete" || objRun?.status === "error") {
-      return {
-        processed: 0,
-        hasMore: false,
-        runStartedAt
-      };
-    }
-    if (objRun?.status === "pending") {
-      const started = await this.postgresClient.tryStartObjectSync(
-        accountId,
-        runStartedAt,
-        resourceName
-      );
-      if (!started) {
+    try {
+      await this.getCurrentAccount();
+      const accountId = await this.getAccountId();
+      const resourceName = this.getResourceName(object);
+      let runStartedAt;
+      if (params?.runStartedAt) {
+        runStartedAt = params.runStartedAt;
+      } else {
+        const { runKey } = await this.joinOrCreateSyncRun(params?.triggeredBy ?? "processNext");
+        runStartedAt = runKey.runStartedAt;
+      }
+      await this.postgresClient.createObjectRuns(accountId, runStartedAt, [resourceName]);
+      const objRun = await this.postgresClient.getObjectRun(accountId, runStartedAt, resourceName);
+      if (objRun?.status === "complete" || objRun?.status === "error") {
         return {
           processed: 0,
-          hasMore: true,
+          hasMore: false,
           runStartedAt
         };
       }
-    }
-    let cursor = null;
-    if (!params?.created) {
-      if (objRun?.cursor) {
-        cursor = objRun.cursor;
-      } else {
-        const lastCursor = await this.postgresClient.getLastCompletedCursor(accountId, resourceName);
+      if (objRun?.status === "pending") {
+        const started = await this.postgresClient.tryStartObjectSync(
+          accountId,
+          runStartedAt,
+          resourceName
+        );
+        if (!started) {
+          return {
+            processed: 0,
+            hasMore: true,
+            runStartedAt
+          };
+        }
+      }
+      let cursor = null;
+      if (!params?.created) {
+        const lastCursor = await this.postgresClient.getLastCursorBeforeRun(
+          accountId,
+          resourceName,
+          runStartedAt
+        );
         cursor = lastCursor ?? null;
       }
+      const result = await this.fetchOnePage(
+        object,
+        accountId,
+        resourceName,
+        runStartedAt,
+        cursor,
+        objRun?.pageCursor ?? null,
+        params
+      );
+      return result;
+    } catch (error) {
+      throw this.appendMigrationHint(error);
     }
-    const result = await this.fetchOnePage(
-      object,
-      accountId,
-      resourceName,
-      runStartedAt,
-      cursor,
-      params
-    );
-    return result;
+  }
+  appendMigrationHint(error) {
+    const hint = "Error occurred. Make sure you are up to date with DB migrations which can sometimes help with this. Details:";
+    const withHint = (message) => message.includes(hint) ? message : `${hint}
+${message}`;
+    if (error instanceof Error) {
+      const { stack } = error;
+      error.message = withHint(error.message);
+      if (stack) error.stack = stack;
+      return error;
+    }
+    return new Error(withHint(String(error)));
   }
   /**
    * Get the database resource name for a SyncObject type
@@ -2168,7 +2225,7 @@ var StripeSync = class {
    * Uses resourceRegistry for DRY list/upsert operations.
    * Uses the observable sync system for tracking progress.
    */
-  async fetchOnePage(object, accountId, resourceName, runStartedAt, cursor, params) {
+  async fetchOnePage(object, accountId, resourceName, runStartedAt, cursor, pageCursor, params) {
     const limit = 100;
     if (object === "payment_method" || object === "tax_id") {
       this.config.logger?.warn(`processNext for ${object} requires customer context`);
@@ -2196,7 +2253,16 @@ var StripeSync = class {
           listParams.created = created;
         }
       }
+      if (pageCursor) {
+        listParams.starting_after = pageCursor;
+      }
       const response = await config.listFn(listParams);
+      if (response.data.length === 0 && response.has_more) {
+        const message = `Stripe returned has_more=true with empty page for ${resourceName}. Aborting to avoid infinite loop.`;
+        this.config.logger?.warn(message);
+        await this.postgresClient.failObjectSync(accountId, runStartedAt, resourceName, message);
+        return { processed: 0, hasMore: false, runStartedAt };
+      }
       if (response.data.length > 0) {
         this.config.logger?.info(`processNext: upserting ${response.data.length} ${resourceName}`);
         await config.upsertFn(response.data, accountId, params?.backfillRelatedEntities);
@@ -2217,6 +2283,15 @@ var StripeSync = class {
             String(maxCreated)
           );
         }
+        const lastId = response.data[response.data.length - 1].id;
+        if (response.has_more) {
+          await this.postgresClient.updateObjectPageCursor(
+            accountId,
+            runStartedAt,
+            resourceName,
+            lastId
+          );
+        }
       }
       if (!response.has_more) {
         await this.postgresClient.completeObjectSync(accountId, runStartedAt, resourceName);

package/dist/index.d.cts

@@ -157,12 +157,21 @@ declare class PostgresClient {
         status: string;
         processedCount: number;
         cursor: string | null;
+        pageCursor: string | null;
     } | null>;
     /**
      * Update progress for an object sync.
      * Also touches updated_at for stale detection.
      */
     incrementObjectProgress(accountId: string, runStartedAt: Date, object: string, count: number): Promise<void>;
+    /**
+     * Update the pagination page_cursor used for backfills using Stripe list calls.
+     */
+    updateObjectPageCursor(accountId: string, runStartedAt: Date, object: string, pageCursor: string | null): Promise<void>;
+    /**
+     * Clear the pagination page_cursor for an object sync.
+     */
+    clearObjectPageCursor(accountId: string, runStartedAt: Date, object: string): Promise<void>;
     /**
      * Update the cursor for an object sync.
      * Only updates if the new cursor is higher than the existing one (cursors should never decrease).
@@ -172,15 +181,20 @@ declare class PostgresClient {
     updateObjectCursor(accountId: string, runStartedAt: Date, object: string, cursor: string | null): Promise<void>;
     /**
      * Get the highest cursor from previous syncs for an object type.
-     * This considers completed, error, AND running runs to ensure recovery syncs
-     * don't re-process data that was already synced before a crash.
-     * A 'running' status with a cursor means the process was killed mid-sync.
+     * Uses only completed object runs.
+     * - During the initial backfill we page through history, but we also update the cursor as we go.
+     *   If we crash mid-backfill and reuse that cursor, we can accidentally switch into incremental mode
+     *   too early and only ever fetch the newest page (breaking the historical backfill).
      *
      * Handles two cursor formats:
      * - Numeric: compared as bigint for correct ordering
      * - Composite cursors: compared as strings with COLLATE "C"
      */
     getLastCompletedCursor(accountId: string, object: string): Promise<string | null>;
+    /**
+     * Get the highest cursor from previous syncs for an object type, excluding the current run.
+     */
+    getLastCursorBeforeRun(accountId: string, object: string, runStartedAt: Date): Promise<string | null>;
     /**
      * Delete all sync runs and object runs for an account.
      * Useful for testing or resetting sync state.
@@ -587,6 +601,7 @@ declare class StripeSync {
      * ```
      */
     processNext(object: Exclude<SyncObject, 'all' | 'customer_with_entitlements'>, params?: ProcessNextParams): Promise<ProcessNextResult>;
+    private appendMigrationHint;
     /**
      * Get the database resource name for a SyncObject type
      */