@powersync/service-core 1.19.2 → 1.20.0

package/src/storage/BucketStorageFactory.ts

@@ -1,9 +1,16 @@
-import { ObserverClient } from '@powersync/lib-services-framework';
+import { BaseObserver, logger } from '@powersync/lib-services-framework';
 import { ParseSyncRulesOptions, PersistedSyncRules, PersistedSyncRulesContent } from './PersistedSyncRulesContent.js';
 import { ReplicationEventPayload } from './ReplicationEventPayload.js';
 import { ReplicationLock } from './ReplicationLock.js';
 import { SyncRulesBucketStorage } from './SyncRulesBucketStorage.js';
 import { ReportStorage } from './ReportStorage.js';
+import {
+  PrecompiledSyncConfig,
+  SerializedCompatibilityContext,
+  serializeSyncPlan,
+  SqlSyncRules,
+  SyncConfig
+} from '@powersync/service-sync-rules';
 
 /**
  * Represents a configured storage provider.
@@ -13,23 +20,41 @@ import { ReportStorage } from './ReportStorage.js';
  *
  * Storage APIs for a specific copy of sync rules are provided by the `SyncRulesBucketStorage` instances.
  */
-export interface BucketStorageFactory extends ObserverClient<BucketStorageFactoryListener>, AsyncDisposable {
+export abstract class BucketStorageFactory
+  extends BaseObserver<BucketStorageFactoryListener>
+  implements AsyncDisposable
+{
   /**
    * Update sync rules from configuration, if changed.
    */
-  configureSyncRules(
+  async configureSyncRules(
     options: UpdateSyncRulesOptions
-  ): Promise<{ updated: boolean; persisted_sync_rules?: PersistedSyncRulesContent; lock?: ReplicationLock }>;
+  ): Promise<{ updated: boolean; persisted_sync_rules?: PersistedSyncRulesContent; lock?: ReplicationLock }> {
+    const next = await this.getNextSyncRulesContent();
+    const active = await this.getActiveSyncRulesContent();
+
+    if (next?.sync_rules_content == options.config.yaml) {
+      logger.info('Sync rules from configuration unchanged');
+      return { updated: false };
+    } else if (next == null && active?.sync_rules_content == options.config.yaml) {
+      logger.info('Sync rules from configuration unchanged');
+      return { updated: false };
+    } else {
+      logger.info('Sync rules updated from configuration');
+      const persisted_sync_rules = await this.updateSyncRules(options);
+      return { updated: true, persisted_sync_rules, lock: persisted_sync_rules.current_lock ?? undefined };
+    }
+  }
 
   /**
    * Get a storage instance to query sync data for specific sync rules.
    */
-  getInstance(syncRules: PersistedSyncRulesContent, options?: GetIntanceOptions): SyncRulesBucketStorage;
+  abstract getInstance(syncRules: PersistedSyncRulesContent, options?: GetIntanceOptions): SyncRulesBucketStorage;
 
   /**
    * Deploy new sync rules.
    */
-  updateSyncRules(options: UpdateSyncRulesOptions): Promise<PersistedSyncRulesContent>;
+  abstract updateSyncRules(options: UpdateSyncRulesOptions): Promise<PersistedSyncRulesContent>;
 
   /**
    * Indicate that a slot was removed, and we should re-sync by creating
@@ -41,57 +66,65 @@ export interface BucketStorageFactory extends ObserverClient<BucketStorageFactor
    *
    * Replication should be restarted after this.
    */
-  restartReplication(sync_rules_group_id: number): Promise<void>;
+  abstract restartReplication(sync_rules_group_id: number): Promise<void>;
 
   /**
    * Get the sync rules used for querying.
    */
-  getActiveSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null>;
+  async getActiveSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null> {
+    const content = await this.getActiveSyncRulesContent();
+    return content?.parsed(options) ?? null;
+  }
 
   /**
    * Get the sync rules used for querying.
    */
-  getActiveSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
+  abstract getActiveSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
 
   /**
    * Get the sync rules that will be active next once done with initial replicatino.
    */
-  getNextSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null>;
+  async getNextSyncRules(options: ParseSyncRulesOptions): Promise<PersistedSyncRules | null> {
+    const content = await this.getNextSyncRulesContent();
+    return content?.parsed(options) ?? null;
+  }
 
   /**
    * Get the sync rules that will be active next once done with initial replicatino.
    */
-  getNextSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
+  abstract getNextSyncRulesContent(): Promise<PersistedSyncRulesContent | null>;
 
   /**
    * Get all sync rules currently replicating. Typically this is the "active" and "next" sync rules.
    */
-  getReplicatingSyncRules(): Promise<PersistedSyncRulesContent[]>;
+  abstract getReplicatingSyncRules(): Promise<PersistedSyncRulesContent[]>;
 
   /**
    * Get all sync rules stopped but not terminated yet.
    */
-  getStoppedSyncRules(): Promise<PersistedSyncRulesContent[]>;
+  abstract getStoppedSyncRules(): Promise<PersistedSyncRulesContent[]>;
 
   /**
    * Get the active storage instance.
    */
-  getActiveStorage(): Promise<SyncRulesBucketStorage | null>;
+  abstract getActiveStorage(): Promise<SyncRulesBucketStorage | null>;
 
   /**
    * Get storage size of active sync rules.
    */
-  getStorageMetrics(): Promise<StorageMetrics>;
+  abstract getStorageMetrics(): Promise<StorageMetrics>;
 
   /**
    * Get the unique identifier for this instance of Powersync
    */
-  getPowerSyncInstanceId(): Promise<string>;
+  abstract getPowerSyncInstanceId(): Promise<string>;
 
   /**
    * Get a unique identifier for the system used for storage.
    */
-  getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
+  abstract getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
+
+  abstract [Symbol.asyncDispose](): PromiseLike<void>;
 }
 
 export interface BucketStorageFactoryListener {
@@ -119,9 +152,67 @@ export interface StorageMetrics {
 }
 
 export interface UpdateSyncRulesOptions {
-  content: string;
+  config: {
+    yaml: string;
+    /**
+     * The serialized sync plan for the sync configuration, or `null` for configurations not using the sync stream
+     * compiler.
+     */
+    plan: SerializedSyncPlan | null;
+  };
   lock?: boolean;
-  validate?: boolean;
+  storageVersion?: number;
+}
+
+export interface SerializedSyncPlan {
+  /**
+   * The serialized plan, from {@link serializeSyncPlan}.
+   */
+  plan: unknown;
+  compatibility: SerializedCompatibilityContext;
+  /**
+   * Event descriptors are not currently represented in the sync plan because they don't use the sync streams compiler
+   * yet.
+   *
+   * We might revisit that in the future, but for now we store SQL text of their definitions here to be able to restore
+   * them.
+   */
+  eventDescriptors: Record<string, string[]>;
+}
+
+export function updateSyncRulesFromYaml(
+  content: string,
+  options?: Omit<UpdateSyncRulesOptions, 'config'> & { validate?: boolean }
+): UpdateSyncRulesOptions {
+  const { config } = SqlSyncRules.fromYaml(content, {
+    // No schema-based validation at this point
+    schema: undefined,
+    defaultSchema: 'not_applicable', // Not needed for validation
+    throwOnError: options?.validate ?? false
+  });
+
+  return updateSyncRulesFromConfig(config, options);
+}
+
+export function updateSyncRulesFromConfig(
+  parsed: SyncConfig,
+  options?: Omit<UpdateSyncRulesOptions, 'config'>
+): UpdateSyncRulesOptions {
+  let plan: SerializedSyncPlan | null = null;
+  if (parsed instanceof PrecompiledSyncConfig) {
+    const eventDescriptors: Record<string, string[]> = {};
+    for (const event of parsed.eventDescriptors) {
+      eventDescriptors[event.name] = event.sourceQueries.map((q) => q.sql);
+    }
+
+    plan = {
+      compatibility: parsed.compatibility.serialize(),
+      plan: serializeSyncPlan(parsed.plan),
+      eventDescriptors
+    };
+  }
+
+  return { config: { yaml: parsed.content, plan }, ...options };
 }
 
 export interface GetIntanceOptions {

package/src/storage/PersistedSyncRulesContent.ts

@@ -1,18 +1,36 @@
-import { HydratedSyncRules, SyncConfig, SyncConfigWithErrors } from '@powersync/service-sync-rules';
+import {
+  CompatibilityContext,
+  CompatibilityOption,
+  DEFAULT_HYDRATION_STATE,
+  deserializeSyncPlan,
+  HydratedSyncRules,
+  HydrationState,
+  javaScriptExpressionEngine,
+  PrecompiledSyncConfig,
+  SqlEventDescriptor,
+  SqlSyncRules,
+  SyncConfigWithErrors,
+  versionedHydrationState
+} from '@powersync/service-sync-rules';
 import { ReplicationLock } from './ReplicationLock.js';
+import { STORAGE_VERSION_CONFIG, StorageVersionConfig } from './StorageVersionConfig.js';
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+import { SerializedSyncPlan, UpdateSyncRulesOptions } from './BucketStorageFactory.js';
 
 export interface ParseSyncRulesOptions {
   defaultSchema: string;
 }
 
-export interface PersistedSyncRulesContent {
+export interface PersistedSyncRulesContentData {
   readonly id: number;
   readonly sync_rules_content: string;
+  readonly compiled_plan: SerializedSyncPlan | null;
   readonly slot_name: string;
   /**
    * True if this is the "active" copy of the sync rules.
    */
   readonly active: boolean;
+  readonly storageVersion: number;
 
   readonly last_checkpoint_lsn: string | null;
 
@@ -20,10 +38,102 @@ export interface PersistedSyncRulesContent {
   readonly last_fatal_error_ts?: Date | null;
   readonly last_keepalive_ts?: Date | null;
   readonly last_checkpoint_ts?: Date | null;
+}
+
+export abstract class PersistedSyncRulesContent implements PersistedSyncRulesContentData {
+  readonly id!: number;
+  readonly sync_rules_content!: string;
+  readonly compiled_plan!: SerializedSyncPlan | null;
+  readonly slot_name!: string;
+  readonly active!: boolean;
+  readonly storageVersion!: number;
+
+  readonly last_checkpoint_lsn!: string | null;
+
+  readonly last_fatal_error?: string | null;
+  readonly last_fatal_error_ts?: Date | null;
+  readonly last_keepalive_ts?: Date | null;
+  readonly last_checkpoint_ts?: Date | null;
+
+  abstract readonly current_lock: ReplicationLock | null;
+
+  constructor(data: PersistedSyncRulesContentData) {
+    Object.assign(this, data);
+  }
+
+  /**
+   * Load the storage config.
+   *
+   * This may throw if the persisted storage version is not supported.
+   */
+  getStorageConfig(): StorageVersionConfig {
+    const storageConfig = STORAGE_VERSION_CONFIG[this.storageVersion];
+    if (storageConfig == null) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_S1005,
+        `Unsupported storage version ${this.storageVersion} for sync rules ${this.id}`
+      );
+    }
+    return storageConfig;
+  }
+
+  parsed(options: ParseSyncRulesOptions): PersistedSyncRules {
+    let hydrationState: HydrationState;
+
+    // Do we have a compiled sync plan? If so, restore from there instead of parsing everything again.
+    let config: SyncConfigWithErrors;
+    if (this.compiled_plan != null) {
+      const plan = deserializeSyncPlan(this.compiled_plan.plan);
+      const compatibility = CompatibilityContext.deserialize(this.compiled_plan.compatibility);
+      const eventDefinitions: SqlEventDescriptor[] = [];
+      for (const [name, queries] of Object.entries(this.compiled_plan.eventDescriptors)) {
+        const descriptor = new SqlEventDescriptor(name, compatibility);
+        for (const query of queries) {
+          descriptor.addSourceQuery(query, options);
+        }
+
+        eventDefinitions.push(descriptor);
+      }
+
+      const precompiled = new PrecompiledSyncConfig(plan, compatibility, eventDefinitions, {
+        defaultSchema: options.defaultSchema,
+        engine: javaScriptExpressionEngine(compatibility),
+        sourceText: this.sync_rules_content
+      });
+
+      config = { config: precompiled, errors: [] };
+    } else {
+      config = SqlSyncRules.fromYaml(this.sync_rules_content, options);
+    }
+
+    const storageConfig = this.getStorageConfig();
+    if (
+      storageConfig.versionedBuckets ||
+      config.config.compatibility.isEnabled(CompatibilityOption.versionedBucketIds)
+    ) {
+      hydrationState = versionedHydrationState(this.id);
+    } else {
+      hydrationState = DEFAULT_HYDRATION_STATE;
+    }
+
+    return {
+      id: this.id,
+      slot_name: this.slot_name,
+      sync_rules: config,
+      hydratedSyncRules: () => {
+        return config.config.hydrate({ hydrationState });
+      }
+    };
+  }
 
-  parsed(options: ParseSyncRulesOptions): PersistedSyncRules;
+  asUpdateOptions(options?: Omit<UpdateSyncRulesOptions, 'config'>): UpdateSyncRulesOptions {
+    return {
+      config: { yaml: this.sync_rules_content, plan: this.compiled_plan },
+      ...options
+    };
+  }
 
-  lock(): Promise<ReplicationLock>;
+  abstract lock(): Promise<ReplicationLock>;
 }
 
 export interface PersistedSyncRules {

package/src/storage/StorageVersionConfig.ts

@@ -0,0 +1,30 @@
+export interface StorageVersionConfig {
+  /**
+   * Whether versioned bucket names are automatically enabled.
+   *
+   * If this is false, bucket names may still be versioned depending on the sync config.
+   */
+  versionedBuckets: boolean;
+}
+
+/**
+ * Oldest supported storage version.
+ */
+export const LEGACY_STORAGE_VERSION = 1;
+
+/**
+ * Default storage version for newly persisted sync rules.
+ */
+export const CURRENT_STORAGE_VERSION = 2;
+
+/**
+ * Shared storage-version behavior across storage implementations.
+ */
+export const STORAGE_VERSION_CONFIG: Record<number, StorageVersionConfig | undefined> = {
+  [LEGACY_STORAGE_VERSION]: {
+    versionedBuckets: false
+  },
+  [CURRENT_STORAGE_VERSION]: {
+    versionedBuckets: true
+  }
+};

package/src/storage/SyncRulesBucketStorage.ts

@@ -202,7 +202,8 @@ export interface CompactOptions {
    *
    * If not specified, compacts all buckets.
    *
-   * These can be individual bucket names, or bucket definition names.
+   * These must be full bucket names (e.g., "global[]", "mybucket[\"user1\"]").
+   * Bucket definition names (e.g., "global") are not supported.
    */
   compactBuckets?: string[];
 

package/src/storage/storage-index.ts

@@ -14,3 +14,4 @@ export * from './SyncRulesBucketStorage.js';
 export * from './PersistedSyncRulesContent.js';
 export * from './ReplicationLock.js';
 export * from './ReportStorage.js';
+export * from './StorageVersionConfig.js';

package/src/sync/BucketChecksumState.ts

@@ -1,8 +1,10 @@
 import {
   BucketDescription,
+  BucketParameterQuerier,
   BucketPriority,
   BucketSource,
   HydratedSyncRules,
+  QuerierError,
   RequestedStream,
   RequestParameters,
   ResolvedBucket
@@ -18,7 +20,6 @@ import {
   ServiceAssertionError,
   ServiceError
 } from '@powersync/lib-services-framework';
-import { BucketParameterQuerier, QuerierError } from '@powersync/service-sync-rules/src/BucketParameterQuerier.js';
 import { JwtPayload } from '../auth/JwtPayload.js';
 import { SyncContext } from './SyncContext.js';
 import { getIntersection, hasIntersection } from './util.js';
@@ -117,7 +118,7 @@ export class BucketChecksumState {
     const storage = this.bucketStorage;
 
     const update = await this.parameterState.getCheckpointUpdate(next);
-    const { buckets: allBuckets, updatedBuckets } = update;
+    const { buckets: allBuckets, updatedBuckets, parameterQueryResultsByDefinition } = update;
 
     /** Set of all buckets in this checkpoint. */
     const bucketDescriptionMap = new Map(allBuckets.map((b) => [b.bucket, b]));
@@ -213,18 +214,27 @@ 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 += `updated: ${limitedBuckets(diff.updatedBuckets, 20)} | `;
         message += `removed: ${limitedBuckets(diff.removedBuckets, 20)}`;
-        this.logger.info(message, {
-          checkpoint: base.checkpoint,
-          user_id: userIdForLogs,
-          buckets: allBuckets.length,
-          updated: diff.updatedBuckets.length,
-          removed: diff.removedBuckets.length
-        });
+        logCheckpoint(
+          this.logger,
+          message,
+          {
+            checkpoint: base.checkpoint,
+            user_id: userIdForLogs,
+            buckets: allBuckets.length,
+            updated: diff.updatedBuckets.length,
+            removed: diff.removedBuckets.length
+          },
+          totalParamResults
+        );
       };
 
       checkpointLine = {
@@ -237,9 +247,23 @@ export class BucketChecksumState {
       } satisfies util.StreamingSyncCheckpointDiff;
     } else {
       deferredLog = () => {
+        const totalParamResults = computeTotalParamResults(parameterQueryResultsByDefinition);
         let message = `New checkpoint: ${base.checkpoint} | write: ${writeCheckpoint} | `;
-        message += `buckets: ${allBuckets.length} ${limitedBuckets(allBuckets, 20)}`;
-        this.logger.info(message, { checkpoint: base.checkpoint, user_id: userIdForLogs, buckets: allBuckets.length });
+        message += `buckets: ${allBuckets.length}`;
+        if (totalParamResults !== undefined) {
+          message += ` | param_results: ${totalParamResults}`;
+        }
+        message += ` ${limitedBuckets(allBuckets, 20)}`;
+        logCheckpoint(
+          this.logger,
+          message,
+          {
+            checkpoint: base.checkpoint,
+            user_id: userIdForLogs,
+            buckets: allBuckets.length
+          },
+          totalParamResults
+        );
       };
       bucketsToFetch = allBuckets.map((b) => ({ bucket: b.bucket, priority: b.priority }));
 
@@ -370,6 +394,12 @@ export interface CheckpointUpdate {
    * If null, assume that any bucket in `buckets` may have been updated.
    */
   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>;
 }
 
 export class BucketParameterState {
@@ -502,11 +532,21 @@ export class BucketParameterState {
         ErrorCode.PSYNC_S2305,
         `Too many parameter query results: ${update.buckets.length} (limit of ${this.context.maxParameterQueryResults})`
       );
-      this.logger.error(error.message, {
+
+      let errorMessage = error.message;
+      const logData: any = {
         checkpoint: checkpoint,
         user_id: this.syncParams.userId,
-        buckets: update.buckets.length
-      });
+        parameter_query_results: update.buckets.length
+      };
+
+      if (update.parameterQueryResultsByDefinition && update.parameterQueryResultsByDefinition.size > 0) {
+        const breakdown = formatParameterQueryBreakdown(update.parameterQueryResultsByDefinition);
+        errorMessage += breakdown.message;
+        logData.parameter_query_results_by_definition = breakdown.countsByDefinition;
+      }
+
+      this.logger.error(errorMessage, logData);
 
       throw error;
     }
@@ -562,6 +602,7 @@ export class BucketParameterState {
     }
 
     let dynamicBuckets: ResolvedBucket[];
+    let parameterQueryResultsByDefinition: Map<string, number> | undefined;
     if (hasParameterChange || this.cachedDynamicBuckets == null || this.cachedDynamicBucketSet == null) {
       const recordedLookups = new Set<string>();
 
@@ -574,6 +615,14 @@ export class BucketParameterState {
           return checkpoint.base.getParameterSets(lookups);
         }
       });
+
+      // 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;
@@ -596,12 +645,14 @@ export class BucketParameterState {
       return {
         buckets: allBuckets,
         // We cannot track individual bucket updates for dynamic lookups yet
-        updatedBuckets: INVALIDATE_ALL_BUCKETS
+        updatedBuckets: INVALIDATE_ALL_BUCKETS,
+        parameterQueryResultsByDefinition
       };
     } else {
       return {
         buckets: allBuckets,
-        updatedBuckets: updatedBuckets
+        updatedBuckets: updatedBuckets,
+        parameterQueryResultsByDefinition
       };
     }
   }
@@ -635,6 +686,68 @@ 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.
+ *
+ * @param logger The logger instance to use
+ * @param message The base message string (param_results will NOT be appended — caller includes it if needed)
+ * @param logData The base log data object
+ * @param totalParamResults The total parameter query results count, or undefined if not applicable
+ */
+function logCheckpoint(
+  logger: Logger,
+  message: string,
+  logData: Record<string, any>,
+  totalParamResults: number | undefined
+): void {
+  if (totalParamResults !== undefined) {
+    logData.parameter_query_results = totalParamResults;
+  }
+  logger.info(message, logData);
+}
+
+/**
+ * Format a breakdown of parameter query results by sync rule 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>): {
+  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 sortedDefinitions = allSorted.slice(0, 10);
+
+  let message = '\nParameter query results by definition:';
+  const countsByDefinition: Record<string, number> = {};
+  for (const [definition, count] of sortedDefinitions) {
+    message += `\n  ${definition}: ${count}`;
+    countsByDefinition[definition] = count;
+  }
+
+  if (allSorted.length > 10) {
+    const remainingResults = allSorted.slice(10).reduce((sum, [, count]) => sum + count, 0);
+    const remainingDefinitions = allSorted.length - 10;
+    message += `\n  ... and ${remainingResults} more results from ${remainingDefinitions} definitions`;
+  }
+
+  return { message, countsByDefinition };
+}
+
 function limitedBuckets(buckets: string[] | { bucket: string }[], limit: number) {
   buckets = buckets.map((b) => {
     if (typeof b != 'string') {

package/src/util/config/collectors/config-collector.ts

@@ -40,6 +40,16 @@ export abstract class ConfigCollector {
      */
     const decoded = this.decode(serialized);
     this.validate(decoded);
+
+    /**
+     * For internal convenience, we duplicate sync_rules and sync_config. Making them interchangeable.
+     * Note, we only do this after validation (which only allows one option to be present)
+     */
+    if (decoded.sync_config) {
+      decoded.sync_rules = decoded.sync_config;
+    } else if (decoded.sync_rules) {
+      decoded.sync_config = decoded.sync_rules;
+    }
     return decoded;
   }
 
@@ -52,6 +62,12 @@ export abstract class ConfigCollector {
     if (!valid.valid) {
       throw new Error(`Failed to validate PowerSync config: ${valid.errors.join(', ')}`);
     }
+
+    if (config.sync_config && config.sync_rules) {
+      throw new Error(
+        'Both `sync_config` and `sync_rules` are present in the service configuration. Please consolidate into one sync_config.'
+      );
+    }
   }
 
   decode(encoded: configFile.SerializedPowerSyncConfig): configFile.PowerSyncConfig {