@powersync/common 0.0.0-dev-20260630144038 → 0.0.0-dev-20261015114518

package/lib/attachments/Schema.d.ts

@@ -1,4 +1,4 @@
-import { Table } from '../db/schema/Table.js';
+import { RowType, Table } from '../db/schema/Table.js';
 import { TableOptions } from '../db/schema/Table.js';
 /**
  * The default name of the local table storing attachment data.
@@ -48,11 +48,30 @@ export declare enum AttachmentState {
  */
 export interface AttachmentTableOptions extends Omit<TableOptions, 'name' | 'columns'> {
 }
+/**
+ * @alpha
+ */
+export declare const ATTACHMENT_TABLE_COLUMNS: {
+    filename: import("../db/schema/Column.js").BaseColumnType<string | null>;
+    local_uri: import("../db/schema/Column.js").BaseColumnType<string | null>;
+    timestamp: import("../db/schema/Column.js").BaseColumnType<number | null>;
+    size: import("../db/schema/Column.js").BaseColumnType<number | null>;
+    media_type: import("../db/schema/Column.js").BaseColumnType<string | null>;
+    state: import("../db/schema/Column.js").BaseColumnType<number | null>;
+    has_synced: import("../db/schema/Column.js").BaseColumnType<number | null>;
+    meta_data: import("../db/schema/Column.js").BaseColumnType<string | null>;
+};
 /**
  * AttachmentTable defines the schema for the attachment queue table.
  *
  * @alpha
  */
-export declare class AttachmentTable extends Table {
+export declare class AttachmentTable extends Table<typeof ATTACHMENT_TABLE_COLUMNS> {
     constructor(options?: AttachmentTableOptions);
 }
+/**
+ * AttachmentTableRecord represents the row type of the attachment table.
+ *
+ * @alpha
+ */
+export type AttachmentTableRecord = RowType<AttachmentTable>;

package/lib/attachments/Schema.js

@@ -40,6 +40,19 @@ export var AttachmentState;
     AttachmentState[AttachmentState["SYNCED"] = 3] = "SYNCED";
     AttachmentState[AttachmentState["ARCHIVED"] = 4] = "ARCHIVED"; // Attachment has been orphaned, i.e. the associated record has been deleted
 })(AttachmentState || (AttachmentState = {}));
+/**
+ * @alpha
+ */
+export const ATTACHMENT_TABLE_COLUMNS = {
+    filename: column.text,
+    local_uri: column.text,
+    timestamp: column.integer,
+    size: column.integer,
+    media_type: column.text,
+    state: column.integer, // Corresponds to AttachmentState
+    has_synced: column.integer,
+    meta_data: column.text
+};
 /**
  * AttachmentTable defines the schema for the attachment queue table.
  *
@@ -47,16 +60,7 @@ export var AttachmentState;
  */
 export class AttachmentTable extends Table {
     constructor(options) {
-        super({
-            filename: column.text,
-            local_uri: column.text,
-            timestamp: column.integer,
-            size: column.integer,
-            media_type: column.text,
-            state: column.integer, // Corresponds to AttachmentState
-            has_synced: column.integer,
-            meta_data: column.text
-        }, {
+        super(ATTACHMENT_TABLE_COLUMNS, {
             ...options,
             viewName: options?.viewName ?? ATTACHMENT_TABLE,
             localOnly: true,

package/lib/attachments/Schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"Schema.js","sourceRoot":"","sources":["../../src/attachments/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAG9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAmB9C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ;IACxC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,SAAS,EAAE,GAAG,CAAC,UAAU,KAAK,CAAC;QAC/B,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,uEAAiB,CAAA;IACjB,2EAAmB,CAAA;IACnB,uEAAiB,CAAA;IACjB,yDAAU,CAAA;IACV,6DAAY,CAAA,CAAC,4EAA4E;AAC3F,CAAC,EANW,eAAe,KAAf,eAAe,QAM1B;AAOD;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAgC;QAC1C,KAAK,CACH;YACE,QAAQ,EAAE,MAAM,CAAC,IAAI;YACrB,SAAS,EAAE,MAAM,CAAC,IAAI;YACtB,SAAS,EAAE,MAAM,CAAC,OAAO;YACzB,IAAI,EAAE,MAAM,CAAC,OAAO;YACpB,UAAU,EAAE,MAAM,CAAC,IAAI;YACvB,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,iCAAiC;YACxD,UAAU,EAAE,MAAM,CAAC,OAAO;YAC1B,SAAS,EAAE,MAAM,CAAC,IAAI;SACvB,EACD;YACE,GAAG,OAAO;YACV,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,gBAAgB;YAC/C,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,KAAK;SAClB,CACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"Schema.js","sourceRoot":"","sources":["../../src/attachments/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAW,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAmB9C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ;IACxC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,SAAS,EAAE,GAAG,CAAC,UAAU,KAAK,CAAC;QAC/B,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,uEAAiB,CAAA;IACjB,2EAAmB,CAAA;IACnB,uEAAiB,CAAA;IACjB,yDAAU,CAAA;IACV,6DAAY,CAAA,CAAC,4EAA4E;AAC3F,CAAC,EANW,eAAe,KAAf,eAAe,QAM1B;AAOD;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,QAAQ,EAAE,MAAM,CAAC,IAAI;IACrB,SAAS,EAAE,MAAM,CAAC,IAAI;IACtB,SAAS,EAAE,MAAM,CAAC,OAAO;IACzB,IAAI,EAAE,MAAM,CAAC,OAAO;IACpB,UAAU,EAAE,MAAM,CAAC,IAAI;IACvB,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,iCAAiC;IACxD,UAAU,EAAE,MAAM,CAAC,OAAO;IAC1B,SAAS,EAAE,MAAM,CAAC,IAAI;CACvB,CAAC;AAEF;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAsC;IACzE,YAAY,OAAgC;QAC1C,KAAK,CAAC,wBAAwB,EAAE;YAC9B,GAAG,OAAO;YACV,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,gBAAgB;YAC/C,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,KAAK;SAClB,CAAC,CAAC;IACL,CAAC;CACF"}

package/lib/attachments/SyncingService.d.ts

@@ -1,7 +1,7 @@
 import { PowerSyncLogger } from '../utils/Logger.js';
 import { AttachmentService } from './AttachmentService.js';
+import { AttachmentTransportAdapter } from './AttachmentTransportAdapter.js';
 import { LocalStorageAdapter } from './LocalStorageAdapter.js';
-import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
 import { AttachmentRecord } from './Schema.js';
 import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
 import { AttachmentContext } from './AttachmentContext.js';
@@ -9,24 +9,37 @@ import { AttachmentContext } from './AttachmentContext.js';
  * Orchestrates attachment synchronization between local and remote storage.
  * Handles uploads, downloads, deletions, and state transitions.
  *
+ * Remote operations (upload/download/delete) go through the {@link AttachmentTransportAdapter};
+ * local file operations use the {@link LocalStorageAdapter}.
+ *
  * @internal
  */
 export declare class SyncingService {
     private attachmentService;
     private localStorage;
-    private remoteStorage;
+    private transport;
     private logger;
     private errorHandler?;
-    constructor(attachmentService: AttachmentService, localStorage: LocalStorageAdapter, remoteStorage: RemoteStorageAdapter, logger: PowerSyncLogger, errorHandler?: AttachmentErrorHandler);
+    constructor(attachmentService: AttachmentService, localStorage: LocalStorageAdapter, transport: AttachmentTransportAdapter, logger: PowerSyncLogger, errorHandler?: AttachmentErrorHandler);
     /**
      * Processes attachments based on their state (upload, download, or delete).
-     * All updates are saved in a single batch after processing.
+     *
+     * Each attachment's I/O runs outside the attachment-service mutex, and the row's
+     * state transition is persisted immediately after it completes. This keeps the
+     * mutex available to concurrent `saveFile` / `deleteFile` / watched-attachment
+     * processing while a batch is in flight, and means consumer queries against the
+     * attachments queue see incremental progress instead of one atomic commit at the
+     * end of the batch.
      *
      * @param attachments - Array of attachment records to process
-     * @param context - Attachment context for database operations
-     * @returns Promise that resolves when all attachments have been processed and saved
+     * @param options - Optional controls. Pass `signal` (an `AbortSignal`) to interrupt
+     *                  the batch: it is checked between attachments and, once aborted, the
+     *                  loop exits early — letting `stopSync` stop a running batch within
+     *                  one attachment's processing time.
      */
-    processAttachments(attachments: AttachmentRecord[], context: AttachmentContext): Promise<void>;
+    processAttachments(attachments: AttachmentRecord[], options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /**
      * Uploads an attachment from local storage to remote storage.
      * On success, marks as SYNCED. On failure, defers to error handler or archives.
@@ -38,7 +51,7 @@ export declare class SyncingService {
     uploadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord>;
     /**
      * Downloads an attachment from remote storage to local storage.
-     * Retrieves the file, converts to base64, and saves locally.
+     * The destination `localUri` is assigned here and the transport writes the file to it.
      * On success, marks as SYNCED. On failure, defers to error handler or archives.
      *
      * @param attachment - The attachment record to download

package/lib/attachments/SyncingService.js

@@ -4,50 +4,81 @@ import { AttachmentState } from './Schema.js';
  * Orchestrates attachment synchronization between local and remote storage.
  * Handles uploads, downloads, deletions, and state transitions.
  *
+ * Remote operations (upload/download/delete) go through the {@link AttachmentTransportAdapter};
+ * local file operations use the {@link LocalStorageAdapter}.
+ *
  * @internal
  */
 export class SyncingService {
     attachmentService;
     localStorage;
-    remoteStorage;
+    transport;
     logger;
     errorHandler;
-    constructor(attachmentService, localStorage, remoteStorage, logger, errorHandler) {
+    constructor(attachmentService, localStorage, transport, logger, errorHandler) {
         this.attachmentService = attachmentService;
         this.localStorage = localStorage;
-        this.remoteStorage = remoteStorage;
+        this.transport = transport;
         this.logger = logger;
         this.errorHandler = errorHandler;
     }
     /**
      * Processes attachments based on their state (upload, download, or delete).
-     * All updates are saved in a single batch after processing.
+     *
+     * Each attachment's I/O runs outside the attachment-service mutex, and the row's
+     * state transition is persisted immediately after it completes. This keeps the
+     * mutex available to concurrent `saveFile` / `deleteFile` / watched-attachment
+     * processing while a batch is in flight, and means consumer queries against the
+     * attachments queue see incremental progress instead of one atomic commit at the
+     * end of the batch.
      *
      * @param attachments - Array of attachment records to process
-     * @param context - Attachment context for database operations
-     * @returns Promise that resolves when all attachments have been processed and saved
+     * @param options - Optional controls. Pass `signal` (an `AbortSignal`) to interrupt
+     *                  the batch: it is checked between attachments and, once aborted, the
+     *                  loop exits early — letting `stopSync` stop a running batch within
+     *                  one attachment's processing time.
      */
-    async processAttachments(attachments, context) {
-        const updatedAttachments = [];
+    async processAttachments(attachments, options) {
+        const signal = options?.signal;
+        this.logger.log({
+            level: LogLevels.info,
+            message: `Starting processAttachments with ${attachments.length} attachments`
+        });
         for (const attachment of attachments) {
-            switch (attachment.state) {
-                case AttachmentState.QUEUED_UPLOAD:
-                    const uploaded = await this.uploadAttachment(attachment);
-                    updatedAttachments.push(uploaded);
-                    break;
-                case AttachmentState.QUEUED_DOWNLOAD:
-                    const downloaded = await this.downloadAttachment(attachment);
-                    updatedAttachments.push(downloaded);
-                    break;
-                case AttachmentState.QUEUED_DELETE:
-                    const deleted = await this.deleteAttachment(attachment, context);
-                    updatedAttachments.push(deleted);
-                    break;
-                default:
-                    break;
+            if (signal?.aborted) {
+                this.logger.log({
+                    level: LogLevels.info,
+                    message: 'Sync cancelled; stopping iteration early'
+                });
+                return;
+            }
+            try {
+                let updated;
+                switch (attachment.state) {
+                    case AttachmentState.QUEUED_UPLOAD:
+                        updated = await this.uploadAttachment(attachment);
+                        break;
+                    case AttachmentState.QUEUED_DOWNLOAD:
+                        updated = await this.downloadAttachment(attachment);
+                        break;
+                    case AttachmentState.QUEUED_DELETE:
+                        // `deleteAttachment` needs a context (it removes the row in a
+                        // transaction); briefly re-acquire the mutex for just this row.
+                        updated = await this.attachmentService.withContext((ctx) => this.deleteAttachment(attachment, ctx));
+                        break;
+                    default:
+                        continue;
+                }
+                await this.attachmentService.withContext((ctx) => ctx.saveAttachments([updated]));
+            }
+            catch (error) {
+                this.logger.log({
+                    level: LogLevels.warn,
+                    message: `Error during sync for ${attachment.id}`,
+                    error
+                });
             }
         }
-        await context.saveAttachments(updatedAttachments);
     }
     /**
      * Uploads an attachment from local storage to remote storage.
@@ -63,8 +94,7 @@ export class SyncingService {
             if (attachment.localUri == null) {
                 throw new Error(`No localUri for attachment ${attachment.id}`);
             }
-            const fileBlob = await this.localStorage.readFile(attachment.localUri);
-            await this.remoteStorage.uploadFile(fileBlob, attachment);
+            await this.transport.upload({ ...attachment, localUri: attachment.localUri });
             return {
                 ...attachment,
                 state: AttachmentState.SYNCED,
@@ -84,7 +114,7 @@ export class SyncingService {
     }
     /**
      * Downloads an attachment from remote storage to local storage.
-     * Retrieves the file, converts to base64, and saves locally.
+     * The destination `localUri` is assigned here and the transport writes the file to it.
      * On success, marks as SYNCED. On failure, defers to error handler or archives.
      *
      * @param attachment - The attachment record to download
@@ -93,9 +123,8 @@ export class SyncingService {
     async downloadAttachment(attachment) {
         this.logger.log({ level: LogLevels.info, message: `Downloading attachment ${attachment.filename}` });
         try {
-            const fileData = await this.remoteStorage.downloadFile(attachment);
             const localUri = this.localStorage.getLocalUri(attachment.filename);
-            await this.localStorage.saveFile(localUri, fileData);
+            await this.transport.download({ ...attachment, localUri });
             return {
                 ...attachment,
                 state: AttachmentState.SYNCED,
@@ -125,7 +154,7 @@ export class SyncingService {
      */
     async deleteAttachment(attachment, context) {
         try {
-            await this.remoteStorage.deleteFile(attachment);
+            await this.transport.delete(attachment);
             if (attachment.localUri) {
                 await this.localStorage.deleteFile(attachment.localUri);
             }

package/lib/attachments/SyncingService.js.map

@@ -1 +1 @@
-{"version":3,"file":"SyncingService.js","sourceRoot":"","sources":["../../src/attachments/SyncingService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SyncingService.js","sourceRoot":"","sources":["../../src/attachments/SyncingService.ts"],"names":[],"mappings":"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"}

package/lib/client/CommonPowerSyncDatabase.d.ts

@@ -16,12 +16,24 @@ import { ArrayQueryDefinition, Query } from './Query.js';
 import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { Mutex } from '../utils/mutex.js';
 import { QueryResult } from '../db/QueryResult.js';
+import { CheckpointRequest } from './sync/CheckpointRequest.js';
 /**
+ * Options passed to {@link CommonPowerSyncDatabase#disconnectAndClear}.
+ *
  * @public
  */
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
+    /**
+     * A [soft] clear deletes publicly visible tables, but keeps internal copies of data synced in the database.
+     *
+     * This usually means that if {@link CommonPowerSyncDatabase#connect} is later called again with a JWT from the same
+     * user, the first sync is very fast because all internal data is still available. When a different user  logs in, no
+     * old data would be visible at any point. Using soft deletes is recommended where it's not a security issue that old
+     * data could be reconstructed from internal database tables.
+     */
+    soft?: boolean;
 }
 /**
  * Options required regardless of how a PowerSync database is opened.
@@ -205,6 +217,18 @@ export interface CommonPowerSyncDatabase extends BaseObserverInterface<PowerSync
      * @returns A {@link SyncStream} instance that can be subscribed to.
      */
     syncStream(name: string, params?: Record<string, any>): SyncStream;
+    /**
+     * Requests a checkpoint from the PowerSync service.
+     *
+     * The returned request can be awaited (using {@link CheckpointRequest#waitForSync}) to confirm that the local
+     * database has applied server-side changes up to the checkpoint. This method requires an active or connecting sync
+     * client connected with a {@link CheckpointMode} set to `requests` and PowerSync service version 1.24.0 or later.
+     *
+     * It can throw for connection, mode, authentication, or service request failures.
+     *
+     * @alpha
+     */
+    requestCheckpoint(): Promise<CheckpointRequest>;
     /**
      * Close the database, releasing resources.
      *
@@ -307,7 +331,7 @@ export interface CommonPowerSyncDatabase extends BaseObserverInterface<PowerSync
     writeLock<T>(callback: (db: LockContext) => Promise<T>): Promise<T>;
     /**
      * Open a read-only transaction.
-     * Read transactions can run concurrently to a write transaction.
+     * When multiple connections are available, read transactions can run concurrently to a write transaction.
      * Changes from any write transaction are not visible to read transactions started before it.
      *
      * @param callback - Function to execute within the transaction

package/lib/client/connection/PowerSyncBackendConnector.d.ts

@@ -23,4 +23,15 @@ export interface PowerSyncBackendConnector {
      * Any thrown errors will result in a retry after the configured wait period (default: 5 seconds).
      */
     uploadData: (database: CommonPowerSyncDatabase) => Promise<void>;
+    /**
+     * Posts a client-generated checkpoint request to the backend and returns the effective checkpoint request state.
+     *
+     * This method is optional. It only needs to be implemented when the selected {@link CheckpointMode} is `requests`
+     * and [asynchronous backend uploads](https://docs.powersync.com/client-sdks/advanced/checkpoint-requests#asynchronous-upload-backends)
+     * are used. In any other case, this method should not be present on backend connectors.
+     *
+     * @param requestId - The client-generated checkpoint request ID (a positive 64-bit integer encoded as a string).
+     * @param clientId - The PowerSync client ID for the current device.
+     */
+    postCheckpointRequest?(clientId: string, requestId: string): Promise<string>;
 }

package/lib/client/connection/PowerSyncCredentials.d.ts

@@ -4,5 +4,5 @@
 export interface PowerSyncCredentials {
     endpoint: string;
     token: string;
-    expiresAt?: Date;
+    expiresAt?: Date | undefined;
 }

package/lib/client/runOnSchemaChange.js

@@ -3,6 +3,8 @@
  */
 export function runOnSchemaChange(callback, db, options) {
     const triggerWatchedQuery = () => {
+        if (options?.signal?.aborted)
+            return;
         const abortController = new AbortController();
         let disposeSchemaListener = null;
         const stopWatching = () => {

package/lib/client/runOnSchemaChange.js.map

@@ -1 +1 @@
-{"version":3,"file":"runOnSchemaChange.js","sourceRoot":"","sources":["../../src/client/runOnSchemaChange.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAuC,EACvC,EAA2B,EAC3B,OAAyB;IAEzB,MAAM,mBAAmB,GAAG,GAAG,EAAE;QAC/B,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,IAAI,qBAAqB,GAAwB,IAAI,CAAC;QACtD,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,eAAe,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACzC,qBAAqB,EAAE,EAAE,CAAC;YAC1B,qBAAqB,GAAG,IAAI,CAAC;YAC7B,kDAAkD;YAClD,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC9D,CAAC,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACzD,qBAAqB,GAAG,EAAE,CAAC,gBAAgB,CAAC;YAC1C,aAAa,EAAE,KAAK,IAAI,EAAE;gBACxB,YAAY,EAAE,CAAC;gBACf,yIAAyI;gBACzI,UAAU,CAAC,GAAG,EAAE,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7C,CAAC;SACF,CAAC,CAAC;QACH,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,mBAAmB,EAAE,CAAC;AACxB,CAAC"}
+{"version":3,"file":"runOnSchemaChange.js","sourceRoot":"","sources":["../../src/client/runOnSchemaChange.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAuC,EACvC,EAA2B,EAC3B,OAAyB;IAEzB,MAAM,mBAAmB,GAAG,GAAG,EAAE;QAC/B,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO;YAAE,OAAO;QAErC,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,IAAI,qBAAqB,GAAwB,IAAI,CAAC;QACtD,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,eAAe,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACzC,qBAAqB,EAAE,EAAE,CAAC;YAC1B,qBAAqB,GAAG,IAAI,CAAC;YAC7B,kDAAkD;YAClD,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC9D,CAAC,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACzD,qBAAqB,GAAG,EAAE,CAAC,gBAAgB,CAAC;YAC1C,aAAa,EAAE,KAAK,IAAI,EAAE;gBACxB,YAAY,EAAE,CAAC;gBACf,yIAAyI;gBACzI,UAAU,CAAC,GAAG,EAAE,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7C,CAAC;SACF,CAAC,CAAC;QACH,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,mBAAmB,EAAE,CAAC;AACxB,CAAC"}

package/lib/client/sync/CheckpointRequest.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A checkpoint request created by {@link CommonPowerSyncDatabase#requestCheckpoint}.
+ *
+ * Use this value to wait until the local database has applied server-side changes up to the requested checkpoint. This
+ * is useful for explicit refresh flows where the caller wants confirmation that the local view has caught up to the
+ * service.
+ *
+ * Checkpoint requests are backed by request ids tracked in the local database, so they are reusable across disconnect
+ * and reconnect cycles. A wait interrupted by a disconnect throws an error, but the same request can be awaited again
+ * once a new connection is established.
+ *
+ * Requests do not survive {@link CommonPowerSyncDatabase#disconnectAndClear}, instances created before a clear should
+ * be discarded and requested again.
+ *
+ * @alpha
+ */
+export interface CheckpointRequest {
+    /**
+     * Whether this checkpoint request has synced before.
+     */
+    readonly hasSynced: boolean;
+    /**
+     * Waits until this checkpoint has been synced locally.
+     *
+     * This method fails on sync errors: If a download or upload error occurs before this checkpoint request has synced,
+     * that error is rethrown here. This makes it easier to observe sync errors when relying on checkpoints. Once sync has
+     * recovered, it is valid to call this method again to await the checkpoint.
+     */
+    waitForSync(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}

package/lib/client/sync/CheckpointRequest.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CheckpointRequest.js.map

package/lib/client/sync/CheckpointRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckpointRequest.js","sourceRoot":"","sources":["../../../src/client/sync/CheckpointRequest.ts"],"names":[],"mappings":""}

package/lib/client/sync/options.d.ts

@@ -40,6 +40,18 @@ export interface SyncOptions {
      * milliseconds.
      */
     crudUploadThrottleMs?: number;
+    /**
+     * The mode used to request checkpoints from the service (used after uploading local data).
+     */
+    checkpointMode?: CheckpointMode;
+    /**
+     * Enables the core extension's diagnostics event stream: detailed per-bucket download stats,
+     * including each bucket's `target_count`, and inferred column types. Off by default.
+     *
+     * The events are internal. No public API exposes them; only PowerSync DevTools reads them, to show
+     * per-bucket totals. See https://docs.powersync.com/tools/devtools-overview.
+     */
+    diagnostics?: boolean;
 }
 /**
  * @public
@@ -63,3 +75,33 @@ export declare enum FetchStrategy {
      */
     Sequential = "sequential"
 }
+/**
+ * The mechanism to request checkpoints from the PowerSync service.
+ *
+ * Checkpoint requests are used after a client uploads local mutations. The PowerSync service later references them in
+ * downloaded data, allowing the SDK to assume that uploaded data has been synced down again.
+ *
+ * There are two ways to send checkpoint requests: A legacy (but default and stable) format supported by all PowerSync
+ * service versions, and a newer (`requests`) method which is only available from PowerSync service version 1.24.0 or
+ * later.
+ *
+ * Note that the requests checkpoint mode is an alpha API.
+ *
+ * @public
+ */
+export type CheckpointMode = 'legacy' | 'requests' | {
+    requests: CheckpointRequestsOptions;
+};
+/**
+ * Options associated with a {@link CheckpointMode} when the requests-based checkpoint option is used.
+ *
+ * @public
+ */
+export interface CheckpointRequestsOptions {
+    /**
+     * The delay, in milliseconds, to wait before re-sending a checkpoint request when it hasn't been applied in time.
+     *
+     * The minimum value for this is 10 seconds, lower values will be ignored.
+     */
+    retryDelay: number;
+}

package/lib/client/sync/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/client/sync/options.ts"],"names":[],"mappings":"AAqDA;;GAEG;AACH,MAAM,CAAN,IAAY,0BAGX;AAHD,WAAY,0BAA0B;IACpC,2CAAa,CAAA;IACb,uDAAyB,CAAA;AAC3B,CAAC,EAHW,0BAA0B,KAA1B,0BAA0B,QAGrC;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,aAYX;AAZD,WAAY,aAAa;IACvB;;;OAGG;IACH,sCAAqB,CAAA;IAErB;;;OAGG;IACH,0CAAyB,CAAA;AAC3B,CAAC,EAZW,aAAa,KAAb,aAAa,QAYxB"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/client/sync/options.ts"],"names":[],"mappings":"AAmEA;;GAEG;AACH,MAAM,CAAN,IAAY,0BAGX;AAHD,WAAY,0BAA0B;IACpC,2CAAa,CAAA;IACb,uDAAyB,CAAA;AAC3B,CAAC,EAHW,0BAA0B,KAA1B,0BAA0B,QAGrC;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,aAYX;AAZD,WAAY,aAAa;IACvB;;;OAGG;IACH,sCAAqB,CAAA;IAErB;;;OAGG;IACH,0CAAyB,CAAA;AAC3B,CAAC,EAZW,aAAa,KAAb,aAAa,QAYxB"}

package/lib/db/crud/SyncStatus.d.ts

@@ -82,7 +82,7 @@ export interface SyncStatus {
      */
     get hasSynced(): boolean | undefined;
     /**
-     * All sync streams currently being tracked in teh database.
+     * All sync streams currently being tracked in the database.
      *
      * This returns null when the database is currently being opened and we don't have reliable information about all
      * included streams yet.

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 export * from './attachments/AttachmentContext.js';
 export * from './attachments/AttachmentErrorHandler.js';
 export * from './attachments/AttachmentQueue.js';
+export * from './attachments/AttachmentTransportAdapter.js';
 export * from './attachments/LocalStorageAdapter.js';
 export * from './attachments/RemoteStorageAdapter.js';
 export * from './attachments/Schema.js';
@@ -13,9 +14,10 @@ export * from './client/SQLOpenFactory.js';
 export * from './client/sync/bucket/CrudBatch.js';
 export { CrudEntry, OpId, UpdateType } from './client/sync/bucket/CrudEntry.js';
 export * from './client/sync/bucket/CrudTransaction.js';
+export * from './client/sync/CheckpointRequest.js';
 export * from './client/sync/stream/JsonValue.js';
 export * from './client/sync/sync-streams.js';
-export { SyncOptions, SyncStreamConnectionMethod, FetchStrategy } from './client/sync/options.js';
+export { SyncOptions, SyncStreamConnectionMethod, FetchStrategy, CheckpointMode, CheckpointRequestsOptions } from './client/sync/options.js';
 export { ProgressWithOperations, SyncProgress } from './db/crud/SyncProgress.js';
 export * from './db/crud/SyncStatus.js';
 export * from './db/crud/UploadQueueStatus.js';

package/lib/index.js

@@ -1,6 +1,7 @@
 export * from './attachments/AttachmentContext.js';
 export * from './attachments/AttachmentErrorHandler.js';
 export * from './attachments/AttachmentQueue.js';
+export * from './attachments/AttachmentTransportAdapter.js';
 export * from './attachments/LocalStorageAdapter.js';
 export * from './attachments/RemoteStorageAdapter.js';
 export * from './attachments/Schema.js';
@@ -13,6 +14,7 @@ export * from './client/SQLOpenFactory.js';
 export * from './client/sync/bucket/CrudBatch.js';
 export { UpdateType } from './client/sync/bucket/CrudEntry.js';
 export * from './client/sync/bucket/CrudTransaction.js';
+export * from './client/sync/CheckpointRequest.js';
 export * from './client/sync/stream/JsonValue.js';
 export * from './client/sync/sync-streams.js';
 export { SyncStreamConnectionMethod, FetchStrategy } from './client/sync/options.js';

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAEvD,cAAc,qCAAqC,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAA+B,MAAM,kCAAkC,CAAC;AACrG,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAmB,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAChF,cAAc,yCAAyC,CAAC;AACxD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAAe,0BAA0B,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGlG,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AAErC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2DAA2D,CAAC;AAC1E,cAAc,uDAAuD,CAAC;AACtE,cAAc,kCAAkC,CAAC;AAGjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAElC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAEvD,cAAc,qCAAqC,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAA+B,MAAM,kCAAkC,CAAC;AACrG,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAmB,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAChF,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAEL,0BAA0B,EAC1B,aAAa,EAGd,MAAM,0BAA0B,CAAC;AAGlC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AAErC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2DAA2D,CAAC;AAC1E,cAAc,uDAAuD,CAAC;AACtE,cAAc,kCAAkC,CAAC;AAGjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAElC,cAAc,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "0.0.0-dev-20260630144038",
+  "version": "0.0.0-dev-20261015114518",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -32,13 +32,14 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@types/uuid": "^9.0.6",
-    "@microsoft/api-extractor": "^7.58.7"
+    "@microsoft/api-extractor": "^7.59.0"
   },
   "scripts": {
     "build": "tsc -b",
     "build:prod": "tsc -b",
     "clean": "rm -rf lib dist tsconfig.tsbuildinfo",
     "test": "vitest",
-    "test:exports": "attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm"
+    "test:exports": "attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm",
+    "api-diff": "api-extractor run --verbose"
   }
 }

package/src/attachments/AttachmentContext.ts

@@ -231,7 +231,8 @@ export class AttachmentContext {
     );
 
     const archivedAttachments = results.map(attachmentFromSql);
-    if (archivedAttachments.length === 0) return false;
+    // Nothing above the cache limit, so the paginated cleanup in `expireCache` is complete.
+    if (archivedAttachments.length === 0) return true;
 
     await callback?.(archivedAttachments);
     this.logger.log({