@powersync/service-core 1.20.4 → 1.21.0

package/src/storage/SyncRulesBucketStorage.ts

@@ -2,9 +2,10 @@ import { Logger, ObserverClient } from '@powersync/lib-services-framework';
 import {
   BucketDataSource,
   HydratedSyncRules,
-  ScopedParameterLookup,
-  SqliteJsonRow
+  ParameterLookupRows,
+  ScopedParameterLookup
 } from '@powersync/service-sync-rules';
+import { PerformanceTracer } from '../tracing/PerformanceTracer.js';
 import * as util from '../util/util-index.js';
 import { BucketStorageBatch, FlushedResult, SaveUpdate } from './BucketStorageBatch.js';
 import { BucketStorageFactory } from './BucketStorageFactory.js';
@@ -14,7 +15,7 @@ import { SourceTable } from './SourceTable.js';
 import { SyncStorageWriteCheckpointAPI } from './WriteCheckpointAPI.js';
 
 /**
- * Storage for a specific copy of sync rules.
+ * Storage for a specific replication stream.
  */
 export interface SyncRulesBucketStorage
   extends ObserverClient<SyncRulesBucketStorageListener>,
@@ -23,6 +24,7 @@ export interface SyncRulesBucketStorage
   readonly slot_name: string;
 
   readonly factory: BucketStorageFactory;
+  readonly logger: Logger;
 
   /**
    * Resolve a table, keeping track of it internally.
@@ -47,11 +49,11 @@ export interface SyncRulesBucketStorage
   getParsedSyncRules(options: ParseSyncRulesOptions): HydratedSyncRules;
 
   /**
-   * Terminate the sync rules.
+   * Terminate the replication stream.
    *
    * This clears the storage, and sets state to TERMINATED.
    *
-   * Must only be called on stopped sync rules.
+   * Must only be called on stopped replication streams.
    */
   terminate(options?: TerminateOptions): Promise<void>;
 
@@ -98,7 +100,7 @@ export interface SyncRulesBucketStorage
   /**
    * Yields the latest user write checkpoint whenever the sync checkpoint updates.
    *
-   * The stream stops or errors if this is not the active sync rules (anymore).
+   * The stream stops or errors if this is not the active sync config (anymore).
    */
   watchCheckpointChanges(options: WatchWriteCheckpointOptions): AsyncIterable<StorageCheckpointUpdate>;
 
@@ -196,6 +198,8 @@ export interface CreateWriterOptions extends ParseSyncRulesOptions {
    */
   markRecordUnavailable?: BucketStorageMarkRecordUnavailable;
 
+  tracer?: PerformanceTracer<'storage' | 'evaluate'>;
+
   logger?: Logger;
 }
 
@@ -265,6 +269,8 @@ export interface CompactOptions {
   compactParameterCacheLimit?: number;
 
   signal?: AbortSignal;
+
+  logger?: Logger;
 }
 
 export interface PopulateChecksumCacheOptions {
@@ -320,8 +326,41 @@ export interface ReplicationCheckpoint {
    * Used to resolve "dynamic" parameter queries.
    *
    * This gets parameter sets specific to this checkpoint.
+   *
+   * @throws {@link ParameterSetLimitExceededError}
+   * Thrown if resolved lookups in bucket storage exceed the `limit` parameter.
+   */
+  getParameterSets(lookups: ScopedParameterLookup[], limit: number): Promise<ParameterLookupRows[]>;
+}
+
+/**
+ * An exception thrown by {@link ReplicationCheckpoint} implementations if there are too many parameter results.
+ *
+ * This is not a suitable exception to show to users, `BucketParameterState` adds additional context.
+ */
+export class ParameterSetLimitExceededError extends Error {
+  constructor(
+    readonly limit: number,
+    readonly breakdown?: ParameterQueryInvocationLog[]
+  ) {
+    super(`Too many parameter results (limit was ${limit})`);
+  }
+}
+
+export interface ParameterQueryInvocationLog {
+  /**
+   * The definition for which a parameter query was invoked.
+   *
+   * The exact format of definition is unspecified, it's shown to users to help them debug this failure.
+   */
+  definition: string;
+  /**
+   * If {@link didExceedLimit} is false, the amount of rows returned by the invocation.
+   *
+   * Otherwise, the maximum amount of rows this invocation was allowed to return.
    */
-  getParameterSets(lookups: ScopedParameterLookup[]): Promise<SqliteJsonRow[]>;
+  resultsOrLimit: number;
+  didExceedLimit: boolean;
 }
 
 export interface WatchWriteCheckpointOptions {

package/src/storage/WriteCheckpointAPI.ts

@@ -1,7 +1,7 @@
 export enum WriteCheckpointMode {
   /**
    * Raw mappings of `user_id` to `write_checkpoint`s should
-   * be supplied for each set of sync rules.
+   * be supplied for each replication stream.
    */
   CUSTOM = 'custom',
   /**
@@ -21,7 +21,7 @@ export interface BaseWriteCheckpointIdentifier {
 
 export interface CustomWriteCheckpointFilters extends BaseWriteCheckpointIdentifier {
   /**
-   * Sync rules which were active when this checkpoint was created.
+   * Replication stream which was active when this checkpoint was created.
    */
   sync_rules_id: number;
 }
@@ -35,7 +35,7 @@ export interface BatchedCustomWriteCheckpointOptions extends BaseWriteCheckpoint
 
 export interface CustomWriteCheckpointOptions extends BatchedCustomWriteCheckpointOptions {
   /**
-   * Sync rules which were active when this checkpoint was created.
+   * Replication stream which was active when this checkpoint was created.
    */
   sync_rules_id: number;
 }
@@ -63,8 +63,8 @@ export interface BaseWriteCheckpointAPI {
 
 /**
  * Write Checkpoint API to be used in conjunction with a {@link SyncRulesBucketStorage}.
- * This storage corresponds with a set of sync rules. These APIs don't require specifying a
- * sync rules id.
+ * This storage corresponds with a replication stream. These APIs don't require specifying a
+ * replication stream id.
  */
 export interface SyncStorageWriteCheckpointAPI extends BaseWriteCheckpointAPI {
   lastWriteCheckpoint(filters: SyncStorageLastWriteCheckpointFilters): Promise<bigint | null>;
@@ -72,7 +72,7 @@ export interface SyncStorageWriteCheckpointAPI extends BaseWriteCheckpointAPI {
 
 /**
  * Write Checkpoint API which is interfaced directly with the storage layer. This requires
- * sync rules identifiers for custom write checkpoints.
+ * replication stream identifiers for custom write checkpoints.
  */
 export interface WriteCheckpointAPI extends BaseWriteCheckpointAPI {
   lastWriteCheckpoint(filters: LastWriteCheckpointFilters): Promise<bigint | null>;

package/src/storage/bson.ts

@@ -40,11 +40,6 @@ export const deserializeParameterLookup = (lookup: bson.Binary) => {
   return parsed;
 };
 
-export const getLookupBucketDefinitionName = (lookup: bson.Binary) => {
-  const parsed = deserializeParameterLookup(lookup);
-  return parsed[0] as string;
-};
-
 /**
  * True if this is a bson.UUID.
  *

package/src/storage/storage-index.ts

@@ -1,17 +1,17 @@
 export * from './bson.js';
 export * from './BucketStorage.js';
+export * from './BucketStorageBatch.js';
+export * from './BucketStorageFactory.js';
 export * from './ChecksumCache.js';
+export * from './PersistedSyncRulesContent.js';
 export * from './ReplicationEventPayload.js';
+export * from './ReplicationLock.js';
+export * from './ReportStorage.js';
 export * from './SourceEntity.js';
 export * from './SourceTable.js';
+export * from './storage-metrics.js';
 export * from './StorageEngine.js';
 export * from './StorageProvider.js';
-export * from './storage-metrics.js';
-export * from './WriteCheckpointAPI.js';
-export * from './BucketStorageFactory.js';
-export * from './BucketStorageBatch.js';
-export * from './SyncRulesBucketStorage.js';
-export * from './PersistedSyncRulesContent.js';
-export * from './ReplicationLock.js';
-export * from './ReportStorage.js';
 export * from './StorageVersionConfig.js';
+export * from './SyncRulesBucketStorage.js';
+export * from './WriteCheckpointAPI.js';

package/src/storage/storage-metrics.ts

@@ -1,7 +1,7 @@
-import { MetricsEngine } from '../metrics/MetricsEngine.js';
 import { logger } from '@powersync/lib-services-framework';
-import { BucketStorageFactory, StorageMetrics } from './BucketStorageFactory.js';
 import { StorageMetric } from '@powersync/service-types';
+import { MetricsEngine } from '../metrics/MetricsEngine.js';
+import { BucketStorageFactory, StorageMetrics } from './BucketStorageFactory.js';
 
 export function createCoreStorageMetrics(engine: MetricsEngine): void {
   engine.createObservableGauge({

package/src/streams/streams-index.ts

@@ -1,3 +1,3 @@
-export * from './merge.js';
-export * from './LastValueSink.js';
 export * from './BroadcastIterable.js';
+export * from './LastValueSink.js';
+export * from './merge.js';

package/src/sync/BucketChecksumState.ts

@@ -1,14 +1,13 @@
 import {
-  BucketDescription,
   BucketParameterQuerier,
   BucketPriority,
   BucketSource,
   HydratedSyncRules,
+  mergeBuckets,
   QuerierError,
   RequestedStream,
   RequestParameters,
-  ResolvedBucket,
-  mergeBuckets
+  ResolvedBucket
 } from '@powersync/service-sync-rules';
 
 import * as storage from '../storage/storage-index.js';
@@ -22,6 +21,7 @@ import {
   ServiceError
 } from '@powersync/lib-services-framework';
 import { JwtPayload } from '../auth/JwtPayload.js';
+import { ParameterSetLimitExceededError } from '../storage/storage-index.js';
 import { SyncContext } from './SyncContext.js';
 import { getIntersection, hasIntersection } from './util.js';
 
@@ -119,16 +119,38 @@ export class BucketChecksumState {
     const storage = this.bucketStorage;
 
     const update = await this.parameterState.getCheckpointUpdate(next);
-    const { buckets: allBuckets, updatedBuckets, parameterQueryResultsByDefinition } = update;
+    const { buckets: allBuckets, updatedBuckets, usedParameterResults } = update;
 
     /** Set of all buckets in this checkpoint. */
     const bucketDescriptionMap = new Map(allBuckets.map((b) => [b.bucket, b]));
 
     if (bucketDescriptionMap.size > this.context.maxBuckets) {
-      throw new ServiceError(
+      const error = new ServiceError(
         ErrorCode.PSYNC_S2305,
         `Too many buckets: ${bucketDescriptionMap.size} (limit of ${this.context.maxBuckets})`
       );
+
+      let errorMessage = error.message;
+      const logData: any = {
+        checkpoint: next.base.checkpoint,
+        user_id: this.parameterState.syncParams.userId,
+        buckets: allBuckets.length
+      };
+
+      // Count buckets per definition.
+      const bucketsByDefinition = new Map<string, number>();
+      for (const bucket of bucketDescriptionMap.values()) {
+        const definition = bucket.definition;
+        const count = bucketsByDefinition.get(definition) ?? 0;
+        bucketsByDefinition.set(definition, count + 1);
+      }
+
+      const breakdown = formatBucketDefinitionBreakdown(bucketsByDefinition);
+      errorMessage += breakdown.message;
+      logData.buckets_by_definition = breakdown.countsByDefinition;
+
+      this.logger.error(errorMessage, logData);
+      throw error;
     }
 
     let checksumMap: util.ChecksumMap;
@@ -212,13 +234,10 @@ export class BucketChecksumState {
       });
 
       deferredLog = () => {
-        const totalParamResults = computeTotalParamResults(parameterQueryResultsByDefinition);
         let message = `Updated checkpoint: ${base.checkpoint} | `;
         message += `write: ${writeCheckpoint} | `;
         message += `buckets: ${allBuckets.length} | `;
-        if (totalParamResults !== undefined) {
-          message += `param_results: ${totalParamResults} | `;
-        }
+        message += `param_results: ${usedParameterResults} | `;
         message += `updated: ${limitedBuckets(diff.updatedBuckets, 20)} | `;
         message += `removed: ${limitedBuckets(diff.removedBuckets, 20)}`;
         logCheckpoint(
@@ -231,7 +250,7 @@ export class BucketChecksumState {
             updated: diff.updatedBuckets.length,
             removed: diff.removedBuckets.length
           },
-          totalParamResults
+          usedParameterResults
         );
       };
 
@@ -245,12 +264,9 @@ export class BucketChecksumState {
       } satisfies util.StreamingSyncCheckpointDiff;
     } else {
       deferredLog = () => {
-        const totalParamResults = computeTotalParamResults(parameterQueryResultsByDefinition);
         let message = `New checkpoint: ${base.checkpoint} | write: ${writeCheckpoint} | `;
         message += `buckets: ${allBuckets.length}`;
-        if (totalParamResults !== undefined) {
-          message += ` | param_results: ${totalParamResults}`;
-        }
+        message += ` | param_results: ${usedParameterResults}`;
         message += ` ${limitedBuckets(allBuckets, 20)}`;
         logCheckpoint(
           this.logger,
@@ -260,7 +276,7 @@ export class BucketChecksumState {
             user_id: userIdForLogs,
             buckets: allBuckets.length
           },
-          totalParamResults
+          usedParameterResults
         );
       };
       bucketsToFetch = allBuckets;
@@ -393,11 +409,8 @@ export interface CheckpointUpdate {
    */
   updatedBuckets: Set<string> | typeof INVALIDATE_ALL_BUCKETS;
 
-  /**
-   * Number of parameter query results per sync stream definition (before deduplication).
-   * Map from definition name to count.
-   */
-  parameterQueryResultsByDefinition?: Map<string, number>;
+  /** The amount of rows fetched from parameters indexes. */
+  usedParameterResults: number;
 }
 
 export class BucketParameterState {
@@ -445,6 +458,7 @@ export class BucketParameterState {
         const subscription = explicitStreamSubscriptions[i];
 
         const syncRuleStream: RequestedStream = {
+          priorityOverride: subscription.override_priority as BucketPriority | null,
           parameters: subscription.parameters ?? {},
           opaque_id: i
         };
@@ -480,25 +494,9 @@ export class BucketParameterState {
    * reference default buckets by their stream index instead of duplicating the name on wire.
    */
   translateResolvedBucket(description: ResolvedBucket, lookupIndex: Map<string, number>): util.ClientBucketDescription {
-    // If the client is overriding the priority of any stream that yields this bucket, sync the bucket with that
-    // priority.
-    let priorityOverride: BucketPriority | null = null;
-    for (const reason of description.inclusion_reasons) {
-      if (reason != 'default') {
-        const requestedPriority = this.explicitStreamSubscriptions[reason.subscription]?.override_priority;
-        if (requestedPriority != null) {
-          if (priorityOverride == null) {
-            priorityOverride = requestedPriority as BucketPriority;
-          } else {
-            priorityOverride = Math.min(requestedPriority, priorityOverride) as BucketPriority;
-          }
-        }
-      }
-    }
-
     return {
       bucket: description.bucket,
-      priority: priorityOverride ?? description.priority,
+      priority: description.priority,
       subscriptions: description.inclusion_reasons.map((reason) => {
         if (reason == 'default') {
           const stream = description.definition;
@@ -518,36 +516,41 @@ export class BucketParameterState {
     const querier = this.querier;
     let update: CheckpointUpdate;
     if (querier.hasDynamicBuckets) {
-      update = await this.getCheckpointUpdateDynamic(checkpoint);
-    } else {
-      update = await this.getCheckpointUpdateStatic(checkpoint);
-    }
-
-    if (update.buckets.length > this.context.maxParameterQueryResults) {
-      // TODO: Limit number of results even before we get to this point
-      // This limit applies _before_ we get the unique set
-      const error = new ServiceError(
-        ErrorCode.PSYNC_S2305,
-        `Too many parameter query results: ${update.buckets.length} (limit of ${this.context.maxParameterQueryResults})`
-      );
+      try {
+        update = await this.getCheckpointUpdateDynamic(checkpoint);
+      } catch (e: unknown) {
+        if (e instanceof ParameterSetLimitExceededError) {
+          // Too many parameter results, create a breakdown of which streams are responsible for the most queries and
+          // then abort.
+          const error = new ServiceError(
+            ErrorCode.PSYNC_S2305,
+            `Too many parameter query results (limit of ${this.context.maxParameterQueryResults})`
+          );
+
+          let errorMessage = error.message;
+          const logData: any = {
+            checkpoint: checkpoint.base.checkpoint,
+            user_id: this.syncParams.userId
+          };
+
+          if (e.breakdown) {
+            const breakdown = formatParameterQueryBreakdown(e.breakdown);
+            if (breakdown) {
+              errorMessage += breakdown.message;
+              logData.parameterResults = breakdown.largestResults;
+            }
+          }
 
-      let errorMessage = error.message;
-      const logData: any = {
-        checkpoint: checkpoint,
-        user_id: this.syncParams.userId,
-        parameter_query_results: update.buckets.length
-      };
+          this.logger.error(errorMessage, logData);
+          throw error;
+        }
 
-      if (update.parameterQueryResultsByDefinition && update.parameterQueryResultsByDefinition.size > 0) {
-        const breakdown = formatParameterQueryBreakdown(update.parameterQueryResultsByDefinition);
-        errorMessage += breakdown.message;
-        logData.parameter_query_results_by_definition = breakdown.countsByDefinition;
+        throw e;
       }
-
-      this.logger.error(errorMessage, logData);
-
-      throw error;
+    } else {
+      update = await this.getCheckpointUpdateStatic(checkpoint);
     }
+
     return update;
   }
 
@@ -561,14 +564,16 @@ export class BucketParameterState {
     if (update.invalidateDataBuckets) {
       return {
         buckets: staticBuckets,
-        updatedBuckets: INVALIDATE_ALL_BUCKETS
+        updatedBuckets: INVALIDATE_ALL_BUCKETS,
+        usedParameterResults: 0
       };
     }
 
     const updatedBuckets = new Set<string>(getIntersection(this.staticBuckets, update.updatedDataBuckets));
     return {
       buckets: staticBuckets,
-      updatedBuckets
+      updatedBuckets,
+      usedParameterResults: 0
     };
   }
 
@@ -600,27 +605,55 @@ export class BucketParameterState {
     }
 
     let dynamicBuckets: ResolvedBucket[];
-    let parameterQueryResultsByDefinition: Map<string, number> | undefined;
+    let usedParameterResults = 0;
     if (hasParameterChange || this.cachedDynamicBuckets == null || this.cachedDynamicBucketSet == null) {
       const recordedLookups = new Set<string>();
+      const parameterLimit = this.context.maxParameterQueryResults;
+      let remainingBudget = parameterLimit;
+
+      // Log of lookups to provide a breakdown if we exceed the dynamic lookup limit.
+      // FIXME: This is horrible, Sync Streams will invoke the callback concurrently and we can't properly deal with
+      // that. We should replace queriers for Sync Streams with an explicit graph structure based on sync plans instead
+      // of adding these checks to the imperative querier interface.
+      const lookupLog: storage.ParameterQueryInvocationLog[] = [];
 
       dynamicBuckets = await querier.queryDynamicBucketDescriptions({
-        getParameterSets(lookups) {
+        getParameterSets: async (lookups, definition) => {
+          if (lookups.length > parameterLimit) {
+            // Sync Streams can chain parameter lookups, so a large output from an earlier call may become the input
+            // here. We reuse the output limit as a generous upper bound; legitimate queries are much smaller.
+            const msg = `Attempted to fetch ${lookups.length} lookups at once, a maximum of ${parameterLimit} lookups are allowed.`;
+            this.logger.error(msg, {
+              user_id: this.syncParams.userId,
+              checkpoint: checkpoint.base.checkpoint,
+              cause: definition
+            });
+            throw new ServiceError(ErrorCode.PSYNC_S2305, msg);
+          }
+
           for (const lookup of lookups) {
             recordedLookups.add(lookup.serializedRepresentation);
           }
 
-          return checkpoint.base.getParameterSets(lookups);
+          try {
+            const results = await checkpoint.base.getParameterSets(lookups, remainingBudget);
+            const numRows = results.reduce((a, b) => a + b.rows.length, 0);
+
+            lookupLog.push({ definition, resultsOrLimit: numRows, didExceedLimit: false });
+            remainingBudget -= numRows;
+            usedParameterResults += numRows;
+            return results;
+          } catch (e: unknown) {
+            if (e instanceof ParameterSetLimitExceededError) {
+              lookupLog.push({ definition, resultsOrLimit: remainingBudget, didExceedLimit: true });
+              throw new ParameterSetLimitExceededError(parameterLimit, lookupLog);
+            }
+
+            throw e;
+          }
         }
       });
 
-      // Count parameter query results per definition (before deduplication)
-      parameterQueryResultsByDefinition = new Map<string, number>();
-      for (const bucket of dynamicBuckets) {
-        const count = parameterQueryResultsByDefinition.get(bucket.definition) ?? 0;
-        parameterQueryResultsByDefinition.set(bucket.definition, count + 1);
-      }
-
       this.cachedDynamicBuckets = dynamicBuckets;
       this.cachedDynamicBucketSet = new Set<string>(dynamicBuckets.map((b) => b.bucket));
       this.lookupsFromPreviousCheckpoint = recordedLookups;
@@ -644,13 +677,13 @@ export class BucketParameterState {
         buckets: allBuckets,
         // We cannot track individual bucket updates for dynamic lookups yet
         updatedBuckets: INVALIDATE_ALL_BUCKETS,
-        parameterQueryResultsByDefinition
+        usedParameterResults
       };
     } else {
       return {
         buckets: allBuckets,
         updatedBuckets: updatedBuckets,
-        parameterQueryResultsByDefinition
+        usedParameterResults
       };
     }
   }
@@ -684,18 +717,6 @@ export interface CheckpointLine {
 // Use a more specific type to simplify testing
 export type BucketChecksumStateStorage = Pick<storage.SyncRulesBucketStorage, 'getChecksums'>;
 
-/**
- * Compute the total number of parameter query results across all definitions.
- */
-function computeTotalParamResults(
-  parameterQueryResultsByDefinition: Map<string, number> | undefined
-): number | undefined {
-  if (!parameterQueryResultsByDefinition) {
-    return undefined;
-  }
-  return Array.from(parameterQueryResultsByDefinition.values()).reduce((sum, count) => sum + count, 0);
-}
-
 /**
  * Log a checkpoint message, enriching it with parameter query result counts if available.
  *
@@ -717,20 +738,20 @@ function logCheckpoint(
 }
 
 /**
- * Format a breakdown of parameter query results by sync rule definition.
+ * Format a breakdown of dynamic bucket by sync stream definition.
  *
  * Sorts definitions by count (descending), includes the top 10, and returns both the
  * formatted message string and the counts record suitable for structured log data.
  */
-function formatParameterQueryBreakdown(parameterQueryResultsByDefinition: Map<string, number>): {
+function formatBucketDefinitionBreakdown(bucketsByDefinition: Map<string, number>): {
   message: string;
   countsByDefinition: Record<string, number>;
 } {
   // Sort definitions by count (descending) and take top 10
-  const allSorted = Array.from(parameterQueryResultsByDefinition.entries()).sort((a, b) => b[1] - a[1]);
+  const allSorted = Array.from(bucketsByDefinition.entries()).sort((a, b) => b[1] - a[1]);
   const sortedDefinitions = allSorted.slice(0, 10);
 
-  let message = '\nParameter query results by definition:';
+  let message = '\Buckets by definition:';
   const countsByDefinition: Record<string, number> = {};
   for (const [definition, count] of sortedDefinitions) {
     message += `\n  ${definition}: ${count}`;
@@ -746,6 +767,33 @@ function formatParameterQueryBreakdown(parameterQueryResultsByDefinition: Map<st
   return { message, countsByDefinition };
 }
 
+function formatParameterQueryBreakdown(log: storage.ParameterQueryInvocationLog[]) {
+  if (log.length == 0) {
+    return;
+  }
+
+  // When an exception about too many parameter results is thrown, the last entry is the one that finally exceeded the
+  // limit.
+  const results = Array.from(log);
+  const failure = results.pop()!;
+
+  let message = '\nInvoked parameter queries by definition:';
+  results.sort((a, b) => b.resultsOrLimit - a.resultsOrLimit);
+  const largestResults = results.splice(0, 9);
+
+  for (const entry of largestResults) {
+    message += `\n  ${entry.definition}: ${entry.resultsOrLimit} results.`;
+  }
+
+  if (largestResults.length < log.length) {
+    message += `\n ... and ${log.length - largestResults.length} more invocations`;
+  }
+
+  message += `\n ${failure.definition} exceeded the remaining limit of ${failure.resultsOrLimit} available results.`;
+  largestResults.push(failure);
+  return { message, largestResults };
+}
+
 function limitedBuckets(buckets: string[] | { bucket: string }[], limit: number) {
   buckets = buckets.map((b) => {
     if (typeof b != 'string') {

package/src/sync/RequestTracker.ts

@@ -1,8 +1,8 @@
 import { MetricsEngine } from '../metrics/MetricsEngine.js';
 
+import { ServiceAssertionError } from '@powersync/lib-services-framework';
 import { APIMetric } from '@powersync/service-types';
 import { SyncBucketData } from '../util/protocol-types.js';
-import { ServiceAssertionError } from '@powersync/lib-services-framework';
 
 /**
  * Record sync stats per request stream.

package/src/sync/sync-index.ts

@@ -1,6 +1,6 @@
+export * from './BucketChecksumState.js';
 export * from './RequestTracker.js';
 export * from './safeRace.js';
 export * from './sync.js';
-export * from './util.js';
-export * from './BucketChecksumState.js';
 export * from './SyncContext.js';
+export * from './util.js';

package/src/sync/sync.ts

@@ -1,11 +1,5 @@
 import { JSONBig, JsonContainer } from '@powersync/service-jsonbig';
-import {
-  BucketDescription,
-  BucketPriority,
-  HydratedSyncRules,
-  ResolvedBucket,
-  SqliteJsonValue
-} from '@powersync/service-sync-rules';
+import { BucketPriority, HydratedSyncRules, ResolvedBucket, SqliteJsonValue } from '@powersync/service-sync-rules';
 
 import { AbortError } from 'ix/aborterror.js';
 
@@ -273,7 +267,7 @@ interface BucketDataRequest {
    * This signal also fires when abort_connection fires.
    */
   abort_batch: AbortSignal;
-  /** User id for debug purposes, not for sync rules. */
+  /** User id for debug purposes, not for sync config. */
   userIdForLogs?: SqliteJsonValue;
   forPriority: BucketPriority | null;
   onRowsSent: (stats: OperationsSentStats) => void;

package/src/sync/util.ts

@@ -1,9 +1,9 @@
 import * as timers from 'timers/promises';
 
 import { SemaphoreInterface } from 'async-mutex';
+import { serialize } from 'bson';
 import * as util from '../util/util-index.js';
 import { RequestTracker } from './RequestTracker.js';
-import { serialize } from 'bson';
 
 export type TokenStreamOptions = {
   /**