@powersync/service-core 0.0.0-dev-20250117095455 → 0.0.0-dev-20250214100224

package/package.json

@@ -5,7 +5,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.0-dev-20250117095455",
+  "version": "0.0.0-dev-20250214100224",
   "main": "dist/index.js",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
@@ -32,11 +32,11 @@
     "uuid": "^9.0.1",
     "winston": "^3.13.0",
     "yaml": "^2.3.2",
-    "@powersync/lib-services-framework": "0.0.0-dev-20250117095455",
+    "@powersync/lib-services-framework": "0.5.1",
     "@powersync/service-jsonbig": "0.17.10",
-    "@powersync/service-rsocket-router": "0.0.0-dev-20250117095455",
-    "@powersync/service-sync-rules": "0.23.1",
-    "@powersync/service-types": "0.0.0-dev-20250117095455"
+    "@powersync/service-rsocket-router": "0.0.18",
+    "@powersync/service-sync-rules": "0.23.4",
+    "@powersync/service-types": "0.8.0"
   },
   "devDependencies": {
     "@types/async": "^3.2.24",

package/src/api/RouteAPI.ts

@@ -54,6 +54,14 @@ export interface RouteAPI {
    */
   getReplicationHead(): Promise<string>;
 
+  /**
+   * Get the current LSN or equivalent replication HEAD position identifier.
+   *
+   * The position is provided to the callback. After the callback returns,
+   * the replication head or a greater one will be streamed on the replication stream.
+   */
+  createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T>;
+
   /**
    * @returns The schema for tables inside the connected database. This is typically
    *          used to validate sync rules.
@@ -76,3 +84,5 @@ export interface RouteAPI {
    */
   getParseSyncRulesOptions(): ParseSyncRulesOptions;
 }
+
+export type ReplicationHeadCallback<T> = (head: string) => Promise<T>;

package/src/auth/RemoteJWKSCollector.ts

@@ -3,7 +3,13 @@ import * as https from 'https';
 import * as jose from 'jose';
 import fetch from 'node-fetch';
 
-import { LookupOptions, makeHostnameLookupFunction } from '@powersync/lib-services-framework';
+import {
+  ErrorCode,
+  LookupOptions,
+  makeHostnameLookupFunction,
+  ServiceAssertionError,
+  ServiceError
+} from '@powersync/lib-services-framework';
 import { KeyCollector, KeyResult } from './KeyCollector.js';
 import { KeySpec } from './KeySpec.js';
 
@@ -24,14 +30,17 @@ export class RemoteJWKSCollector implements KeyCollector {
   ) {
     try {
       this.url = new URL(url);
-    } catch (e) {
-      throw new Error(`Invalid jwks_uri: ${url}`);
+    } catch (e: any) {
+      throw new ServiceError(ErrorCode.PSYNC_S3102, `Invalid jwks_uri: ${JSON.stringify(url)} Details: ${e.message}`);
     }
 
     // We do support http here for self-hosting use cases.
     // Management service restricts this to https for hosted versions.
     if (this.url.protocol != 'https:' && this.url.protocol != 'http:') {
-      throw new Error(`Only http(s) is supported for jwks_uri, got: ${url}`);
+      throw new ServiceError(
+        ErrorCode.PSYNC_S3103,
+        `Only http(s) is supported for jwks_uri, got: ${JSON.stringify(url)}`
+      );
     }
 
     this.agent = this.resolveAgent();
@@ -96,6 +105,9 @@ export class RemoteJWKSCollector implements KeyCollector {
 
   /**
    * Agent that uses a custom lookup function.
+   *
+   * This will synchronously raise an error if the URL contains an IP in the reject list.
+   * For domain names resolving to a rejected IP, that will fail when making the request.
    */
   resolveAgent(): http.Agent | https.Agent {
     const lookupOptions = this.options?.lookupOptions ?? { reject_ip_ranges: [] };
@@ -111,6 +123,7 @@ export class RemoteJWKSCollector implements KeyCollector {
       case 'https:':
         return new https.Agent(options);
     }
-    throw new Error('http or or https is required for protocol');
+    // Already validated the URL before, so this is not expected
+    throw new ServiceAssertionError('http or or https is required for JWKS protocol');
   }
 }

package/src/entry/cli-entry.ts

@@ -6,6 +6,7 @@ import { registerCompactAction } from './commands/compact-action.js';
 import { registerMigrationAction } from './commands/migrate-action.js';
 import { registerStartAction } from './commands/start-action.js';
 import { registerTearDownAction } from './commands/teardown-action.js';
+import { registerTestConnectionAction } from './commands/test-connection-action.js';
 
 /**
  * Generates a Commander program which serves as the entry point
@@ -20,6 +21,7 @@ export function generateEntryProgram(startHandlers?: Record<utils.ServiceRunner,
   registerTearDownAction(entryProgram);
   registerMigrationAction(entryProgram);
   registerCompactAction(entryProgram);
+  registerTestConnectionAction(entryProgram);
 
   if (startHandlers) {
     registerStartAction(entryProgram, startHandlers);

package/src/entry/commands/teardown-action.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 
 import { teardown } from '../../runner/teardown.js';
 import { extractRunnerOptions, wrapConfigCommand } from './config-command.js';
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 
 const COMMAND_NAME = 'teardown';
 
@@ -15,7 +16,7 @@ export function registerTearDownAction(program: Command) {
     .description('Terminate all replicating sync rules, clear remote configuration and remove all data')
     .action(async (ack, options) => {
       if (ack !== 'TEARDOWN') {
-        throw new Error('TEARDOWN was not acknowledged.');
+        throw new ServiceError(ErrorCode.PSYNC_S0102, 'TEARDOWN was not acknowledged.');
       }
 
       await teardown(extractRunnerOptions(options));

package/src/entry/commands/test-connection-action.ts

@@ -0,0 +1,41 @@
+import { Command } from 'commander';
+
+import { container, logger } from '@powersync/lib-services-framework';
+import * as system from '../../system/system-index.js';
+import * as utils from '../../util/util-index.js';
+
+import { modules, ReplicationEngine } from '../../index.js';
+import { extractRunnerOptions, wrapConfigCommand } from './config-command.js';
+
+const COMMAND_NAME = 'test-connection';
+
+export function registerTestConnectionAction(program: Command) {
+  const testConnectionCommand = program.command(COMMAND_NAME);
+
+  wrapConfigCommand(testConnectionCommand);
+
+  return testConnectionCommand.description('Test connection').action(async (options) => {
+    try {
+      const config = await utils.loadConfig(extractRunnerOptions(options));
+      const serviceContext = new system.ServiceContextContainer(config);
+
+      const replication = new ReplicationEngine();
+      serviceContext.register(ReplicationEngine, replication);
+
+      // Register modules in order to load the correct config
+      const moduleManager = container.getImplementation(modules.ModuleManager);
+      await moduleManager.initialize(serviceContext);
+
+      // Start the storage engine in order to create the appropriate BucketStorage
+      await serviceContext.lifeCycleEngine.start();
+
+      logger.info('Testing connection...');
+      const results = await replication.testConnection();
+      logger.info(`Connection succeeded to ${results.map((r) => r.connectionDescription).join(', ')}`);
+      process.exit(0);
+    } catch (e) {
+      logger.error(`Connection failed: ${e.message}`);
+      process.exit(1);
+    }
+  });
+}

package/src/metrics/Metrics.ts

@@ -3,7 +3,7 @@ import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
 import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
 import { Resource } from '@opentelemetry/resources';
 import { MeterProvider, MetricReader, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
-import { logger } from '@powersync/lib-services-framework';
+import { logger, ServiceAssertionError } from '@powersync/lib-services-framework';
 import * as storage from '../storage/storage-index.js';
 import * as util from '../util/util-index.js';
 
@@ -132,7 +132,7 @@ export class Metrics {
 
   public static getInstance(): Metrics {
     if (!Metrics.instance) {
-      throw new Error('Metrics have not been initialised');
+      throw new ServiceAssertionError('Metrics have not been initialized');
     }
 
     return Metrics.instance;

package/src/replication/AbstractReplicator.ts

@@ -6,6 +6,7 @@ import { StorageEngine } from '../storage/storage-index.js';
 import { SyncRulesProvider } from '../util/config/sync-rules/sync-rules-provider.js';
 import { AbstractReplicationJob } from './AbstractReplicationJob.js';
 import { ErrorRateLimiter } from './ErrorRateLimiter.js';
+import { ConnectionTestResult } from './ReplicationModule.js';
 
 // 5 minutes
 const PING_INTERVAL = 1_000_000_000n * 300n;
@@ -92,21 +93,27 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
 
   private async runLoop() {
     const syncRules = await this.syncRuleProvider.get();
+
     let configuredLock: storage.ReplicationLock | undefined = undefined;
     if (syncRules != null) {
       this.logger.info('Loaded sync rules');
       try {
         // Configure new sync rules, if they have changed.
         // In that case, also immediately take out a lock, so that another process doesn't start replication on it.
-        const { lock } = await this.storage.configureSyncRules(syncRules, {
-          lock: true
+
+        const { lock } = await this.storage.configureSyncRules({
+          content: syncRules,
+          lock: true,
+          validate: this.syncRuleProvider.exitOnError
         });
         if (lock) {
           configuredLock = lock;
         }
       } catch (e) {
-        // Log, but continue with previous sync rules
+        // Log and re-raise to exit.
+        // Should only reach this due to validation errors if exit_on_error is true.
         this.logger.error(`Failed to update sync rules from configuration`, e);
+        throw e;
       }
     } else {
       this.logger.info('No sync rules configured - configure via API');
@@ -225,4 +232,6 @@ export abstract class AbstractReplicator<T extends AbstractReplicationJob = Abst
       this.logger.warn(`Failed clean up replication config for sync rules: ${syncRuleStorage.group_id}`, e);
     }
   }
+
+  abstract testConnection(): Promise<ConnectionTestResult>;
 }

package/src/replication/ReplicationEngine.ts

@@ -1,5 +1,6 @@
 import { logger } from '@powersync/lib-services-framework';
 import { AbstractReplicator } from './AbstractReplicator.js';
+import { ConnectionTestResult } from './ReplicationModule.js';
 
 export class ReplicationEngine {
   private readonly replicators: Map<string, AbstractReplicator> = new Map();
@@ -40,4 +41,8 @@ export class ReplicationEngine {
     }
     logger.info('Successfully shut down Replication Engine.');
   }
+
+  public async testConnection(): Promise<ConnectionTestResult[]> {
+    return await Promise.all([...this.replicators.values()].map((replicator) => replicator.testConnection()));
+  }
 }

package/src/replication/ReplicationModule.ts

@@ -1,13 +1,19 @@
 import { DataSourceConfig } from '@powersync/service-types/dist/config/PowerSyncConfig.js';
 import * as t from 'ts-codec';
 
+import { schema } from '@powersync/lib-services-framework';
 import * as types from '@powersync/service-types';
 import * as api from '../api/api-index.js';
 import * as modules from '../modules/modules-index.js';
 import * as system from '../system/system-index.js';
-import { schema } from '@powersync/lib-services-framework';
 import { AbstractReplicator } from './AbstractReplicator.js';
-import { TearDownOptions } from '../modules/modules-index.js';
+
+export interface ConnectionTestResult {
+  /**
+   * Connection URI or hostname.
+   */
+  connectionDescription: string;
+}
 
 /**
  *  Provides a common interface for testing the connection to a DataSource.
@@ -17,7 +23,7 @@ export interface ConnectionTester<TConfig extends DataSourceConfig> {
    *  Confirm if a connection can be established to the datasource for the provided datasource configuration
    *  @param config
    */
-  testConnection(config: TConfig): Promise<void>;
+  testConnection(config: TConfig): Promise<ConnectionTestResult>;
 }
 
 export interface ReplicationModuleOptions extends modules.AbstractModuleOptions {
@@ -58,7 +64,7 @@ export abstract class ReplicationModule<TConfig extends DataSourceConfig>
    */
   protected abstract createReplicator(context: system.ServiceContext): AbstractReplicator;
 
-  public abstract testConnection(config: TConfig): Promise<void>;
+  public abstract testConnection(config: TConfig): Promise<ConnectionTestResult>;
 
   /**
    *  Register this module's Replicators and RouteAPI adapters if the required configuration is present.
@@ -81,16 +87,12 @@ export abstract class ReplicationModule<TConfig extends DataSourceConfig>
       );
     }
 
-    try {
-      const baseMatchingConfig = matchingConfig[0] as TConfig;
-      // If decoding fails, log the error and continue, no replication will happen for this data source
-      this.decodeConfig(baseMatchingConfig);
+    const baseMatchingConfig = matchingConfig[0] as TConfig;
+    // If decoding fails, this will raise a hard error, and stop the service.
+    this.decodeConfig(baseMatchingConfig);
 
-      context.replicationEngine?.register(this.createReplicator(context));
-      context.routerEngine?.registerAPI(this.createRouteAPIAdapter());
-    } catch (e) {
-      this.logger.error('Failed to initialize.', e);
-    }
+    context.replicationEngine?.register(this.createReplicator(context));
+    context.routerEngine?.registerAPI(this.createRouteAPIAdapter());
   }
 
   protected decodeConfig(config: TConfig): void {

package/src/routes/endpoints/admin.ts

@@ -1,4 +1,4 @@
-import { errors, router, schema } from '@powersync/lib-services-framework';
+import { ErrorCode, errors, router, schema } from '@powersync/lib-services-framework';
 import { SqlSyncRules, StaticSchema } from '@powersync/service-sync-rules';
 import { internal_routes } from '@powersync/service-types';
 
@@ -120,15 +120,18 @@ export const reprocess = routeDefinition({
 
     const active = await activeBucketStorage.getActiveSyncRules(apiHandler.getParseSyncRulesOptions());
     if (active == null) {
-      throw new errors.JourneyError({
+      throw new errors.ServiceError({
         status: 422,
-        code: 'NO_SYNC_RULES',
+        code: ErrorCode.PSYNC_S4104,
         description: 'No active sync rules'
       });
     }
 
     const new_rules = await activeBucketStorage.updateSyncRules({
-      content: active.sync_rules.content
+      content: active.sync_rules.content,
+      // These sync rules already passed validation. But if the rules are not valid anymore due
+      // to a service change, we do want to report the error here.
+      validate: true
     });
 
     const baseConfig = await apiHandler.getSourceConfig();

package/src/routes/endpoints/checkpointing.ts

@@ -25,7 +25,7 @@ export const writeCheckpoint = routeDefinition({
     // Since we don't use LSNs anymore, the only way to get that is to wait.
     const start = Date.now();
 
-    const head = await apiHandler.getReplicationHead();
+    const head = await apiHandler.createReplicationHead(async (head) => head);
 
     const timeout = 50_000;
 
@@ -56,25 +56,14 @@ export const writeCheckpoint2 = routeDefinition({
 
     const apiHandler = service_context.routerEngine!.getAPI();
 
-    const client_id = payload.params.client_id;
-    const full_user_id = util.checkpointUserId(user_id, client_id);
-
-    const currentCheckpoint = await apiHandler.getReplicationHead();
-    const {
-      storageEngine: { activeBucketStorage }
-    } = service_context;
-
-    const activeSyncRules = await activeBucketStorage.getActiveSyncRulesContent();
-    if (!activeSyncRules) {
-      throw new framework.errors.ValidationError(`Cannot create Write Checkpoint since no sync rules are active.`);
-    }
-
-    using syncBucketStorage = activeBucketStorage.getInstance(activeSyncRules);
-    const writeCheckpoint = await syncBucketStorage.createManagedWriteCheckpoint({
-      user_id: full_user_id,
-      heads: { '1': currentCheckpoint }
+    const { replicationHead, writeCheckpoint } = await util.createWriteCheckpoint({
+      userId: user_id,
+      clientId: payload.params.client_id,
+      api: apiHandler,
+      storage: service_context.storageEngine.activeBucketStorage
     });
-    logger.info(`Write checkpoint 2: ${JSON.stringify({ currentCheckpoint, id: String(full_user_id) })}`);
+
+    logger.info(`Write checkpoint for ${user_id}/${payload.params.client_id}: ${writeCheckpoint} | ${replicationHead}`);
 
     return {
       write_checkpoint: String(writeCheckpoint)

package/src/routes/endpoints/socket-route.ts

@@ -1,4 +1,4 @@
-import { errors, logger, schema } from '@powersync/lib-services-framework';
+import { ErrorCode, errors, logger, schema } from '@powersync/lib-services-framework';
 import { RequestParameters } from '@powersync/service-sync-rules';
 import { serialize } from 'bson';
 
@@ -34,9 +34,9 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
 
       if (routerEngine!.closed) {
         responder.onError(
-          new errors.JourneyError({
+          new errors.ServiceError({
             status: 503,
-            code: 'SERVICE_UNAVAILABLE',
+            code: ErrorCode.PSYNC_S2003,
             description: 'Service temporarily unavailable'
           })
         );
@@ -53,9 +53,9 @@ export const syncStreamReactive: SocketRouteGenerator = (router) =>
       const cp = await activeBucketStorage.getActiveCheckpoint();
       if (!cp.hasSyncRules()) {
         responder.onError(
-          new errors.JourneyError({
+          new errors.ServiceError({
             status: 500,
-            code: 'NO_SYNC_RULES',
+            code: ErrorCode.PSYNC_S2302,
             description: 'No sync rules available'
           })
         );

package/src/routes/endpoints/sync-rules.ts

@@ -1,4 +1,4 @@
-import { errors, router, schema } from '@powersync/lib-services-framework';
+import { ErrorCode, errors, router, schema } from '@powersync/lib-services-framework';
 import { SqlSyncRules, SyncRulesErrors } from '@powersync/service-sync-rules';
 import type { FastifyPluginAsync } from 'fastify';
 import * as t from 'ts-codec';
@@ -43,9 +43,9 @@ export const deploySyncRules = routeDefinition({
 
     if (service_context.configuration.sync_rules.present) {
       // If sync rules are configured via the config, disable deploy via the API.
-      throw new errors.JourneyError({
+      throw new errors.ServiceError({
         status: 422,
-        code: 'API_DISABLED',
+        code: ErrorCode.PSYNC_S4105,
         description: 'Sync rules API disabled',
         details: 'Use the management API to deploy sync rules'
       });
@@ -60,16 +60,18 @@ export const deploySyncRules = routeDefinition({
         schema: undefined
       });
     } catch (e) {
-      throw new errors.JourneyError({
+      throw new errors.ServiceError({
         status: 422,
-        code: 'INVALID_SYNC_RULES',
+        code: ErrorCode.PSYNC_R0001,
         description: 'Sync rules parsing failed',
         details: e.message
       });
     }
 
     const sync_rules = await storageEngine.activeBucketStorage.updateSyncRules({
-      content: content
+      content: content,
+      // Aready validated above
+      validate: false
     });
 
     return {
@@ -112,9 +114,9 @@ export const currentSyncRules = routeDefinition({
 
     const sync_rules = await activeBucketStorage.getActiveSyncRulesContent();
     if (!sync_rules) {
-      throw new errors.JourneyError({
+      throw new errors.ServiceError({
         status: 422,
-        code: 'NO_SYNC_RULES',
+        code: ErrorCode.PSYNC_S4104,
         description: 'No active sync rules'
       });
     }
@@ -159,15 +161,18 @@ export const reprocessSyncRules = routeDefinition({
     const apiHandler = payload.context.service_context.routerEngine!.getAPI();
     const sync_rules = await activeBucketStorage.getActiveSyncRules(apiHandler.getParseSyncRulesOptions());
     if (sync_rules == null) {
-      throw new errors.JourneyError({
+      throw new errors.ServiceError({
         status: 422,
-        code: 'NO_SYNC_RULES',
+        code: ErrorCode.PSYNC_S4104,
         description: 'No active sync rules'
       });
     }
 
     const new_rules = await activeBucketStorage.updateSyncRules({
-      content: sync_rules.sync_rules.content
+      content: sync_rules.sync_rules.content,
+      // These sync rules already passed validation. But if the rules are not valid anymore due
+      // to a service change, we do want to report the error here.
+      validate: true
     });
     return {
       slot_name: new_rules.slot_name

package/src/routes/endpoints/sync-stream.ts

@@ -1,4 +1,4 @@
-import { errors, logger, router, schema } from '@powersync/lib-services-framework';
+import { ErrorCode, errors, logger, router, schema } from '@powersync/lib-services-framework';
 import { RequestParameters } from '@powersync/service-sync-rules';
 import { Readable } from 'stream';
 
@@ -26,9 +26,9 @@ export const syncStreamed = routeDefinition({
     const clientId = payload.params.client_id;
 
     if (routerEngine!.closed) {
-      throw new errors.JourneyError({
+      throw new errors.ServiceError({
         status: 503,
-        code: 'SERVICE_UNAVAILABLE',
+        code: ErrorCode.PSYNC_S2003,
         description: 'Service temporarily unavailable'
       });
     }
@@ -39,9 +39,9 @@ export const syncStreamed = routeDefinition({
     // Sanity check before we start the stream
     const cp = await storageEngine.activeBucketStorage.getActiveCheckpoint();
     if (!cp.hasSyncRules()) {
-      throw new errors.JourneyError({
+      throw new errors.ServiceError({
         status: 500,
-        code: 'NO_SYNC_RULES',
+        code: ErrorCode.PSYNC_S2302,
         description: 'No sync rules available'
       });
     }

package/src/routes/route-register.ts

@@ -62,16 +62,16 @@ export function registerFastifyRoutes(
               });
             }
           } catch (ex) {
-            const journeyError = errors.JourneyError.isJourneyError(ex) ? ex : new errors.InternalServerError(ex);
-            logger.error(`Request failed`, journeyError);
+            const serviceError = errors.asServiceError(ex);
+            logger.error(`Request failed`, serviceError);
 
             response = new router.RouterResponse({
-              status: journeyError.errorData.status || 500,
+              status: serviceError.errorData.status || 500,
               headers: {
                 'Content-Type': 'application/json'
               },
               data: {
-                error: journeyError.errorData
+                error: serviceError.errorData
               }
             });
           }

package/src/storage/BucketStorage.ts

@@ -60,13 +60,26 @@ export interface BucketStorageFactoryListener extends DisposableListener {
   replicationEvent: (event: ReplicationEventPayload) => void;
 }
 
+export interface BucketStorageSystemIdentifier {
+  /**
+   * A unique identifier for the system used for storage.
+   * For Postgres this can be the cluster `system_identifier` and database name.
+   * For MongoDB this can be the replica set name.
+   */
+  id: string;
+  /**
+   * A unique type for the storage implementation.
+   * e.g. `mongodb`, `postgresql`.
+   */
+  type: string;
+}
+
 export interface BucketStorageFactory extends AsyncDisposableObserverClient<BucketStorageFactoryListener> {
   /**
    * Update sync rules from configuration, if changed.
    */
   configureSyncRules(
-    sync_rules: string,
-    options?: { lock?: boolean }
+    options: UpdateSyncRulesOptions
   ): Promise<{ updated: boolean; persisted_sync_rules?: PersistedSyncRulesContent; lock?: ReplicationLock }>;
 
   /**
@@ -76,6 +89,8 @@ export interface BucketStorageFactory extends AsyncDisposableObserverClient<Buck
 
   /**
    * Deploy new sync rules.
+   *
+   * Similar to configureSyncRules, but applies the update unconditionally.
    */
   updateSyncRules(options: UpdateSyncRulesOptions): Promise<PersistedSyncRulesContent>;
 
@@ -143,6 +158,11 @@ export interface BucketStorageFactory extends AsyncDisposableObserverClient<Buck
    * Get the unique identifier for this instance of Powersync
    */
   getPowerSyncInstanceId(): Promise<string>;
+
+  /**
+   * Get a unique identifier for the system used for storage.
+   */
+  getSystemIdentifier(): Promise<BucketStorageSystemIdentifier>;
 }
 
 export interface ReplicationCheckpoint {
@@ -213,6 +233,7 @@ export interface PersistedSyncRules {
 export interface UpdateSyncRulesOptions {
   content: string;
   lock?: boolean;
+  validate?: boolean;
 }
 
 export interface SyncRulesBucketStorageOptions {
@@ -367,6 +388,20 @@ export interface BucketBatchStorageListener extends DisposableListener {
   replicationEvent: (payload: ReplicationEventPayload) => void;
 }
 
+export interface BucketBatchCommitOptions {
+  /**
+   * Creates a new checkpoint even if there were no persisted operations.
+   * Defaults to true.
+   */
+  createEmptyCheckpoints?: boolean;
+}
+
+export type ResolvedBucketBatchCommitOptions = Required<BucketBatchCommitOptions>;
+
+export const DEFAULT_BUCKET_BATCH_COMMIT_OPTIONS: ResolvedBucketBatchCommitOptions = {
+  createEmptyCheckpoints: true
+};
+
 export interface BucketStorageBatch extends DisposableObserverClient<BucketBatchStorageListener> {
   /**
    * Save an op, and potentially flush.
@@ -398,11 +433,11 @@ export interface BucketStorageBatch extends DisposableObserverClient<BucketBatch
   flush(): Promise<FlushedResult | null>;
 
   /**
-   * Flush and commit any saved ops. This creates a new checkpoint.
+   * Flush and commit any saved ops. This creates a new checkpoint by default.
    *
    * Only call this after a transaction.
    */
-  commit(lsn: string): Promise<boolean>;
+  commit(lsn: string, options?: BucketBatchCommitOptions): Promise<boolean>;
 
   /**
    * Advance the checkpoint LSN position, without any associated op.