@powersync/common 0.0.0-dev-20260311103504 → 0.0.0-dev-20260503073249

package/lib/utils/stream_transform.js

@@ -0,0 +1,206 @@
+export const doneResult = { done: true, value: undefined };
+export function valueResult(value) {
+    return { done: false, value };
+}
+/**
+ * A variant of {@link Array.map} for async iterators.
+ */
+export function map(source, map) {
+    return {
+        next: async () => {
+            const value = await source.next();
+            if (value.done) {
+                return value;
+            }
+            else {
+                return { value: map(value.value) };
+            }
+        }
+    };
+}
+/**
+ * Expands a source async iterator by allowing to inject events asynchronously.
+ *
+ * The resulting iterator will emit all events from its source. Additionally though, events can be injected. These
+ * events are dropped once the main iterator completes, but are otherwise forwarded.
+ *
+ * The iterator completes when its source completes, and it supports backpressure by only calling `next()` on the source
+ * in response to a `next()` call from downstream if no pending injected events can be dispatched.
+ */
+export function injectable(source) {
+    let sourceIsDone = false;
+    let waiter = undefined; // An active, waiting next() call.
+    // A pending upstream event that couldn't be dispatched because inject() has been called before it was resolved.
+    let pendingSourceEvent = null;
+    let pendingInjectedEvents = [];
+    const consumeWaiter = () => {
+        const pending = waiter;
+        waiter = undefined;
+        return pending;
+    };
+    const fetchFromSource = () => {
+        const resolveWaiter = (propagate) => {
+            const active = consumeWaiter();
+            if (active) {
+                propagate(active);
+            }
+            else {
+                pendingSourceEvent = propagate;
+            }
+        };
+        const nextFromSource = source.next();
+        nextFromSource.then((value) => {
+            sourceIsDone = value.done == true;
+            resolveWaiter((w) => w.resolve(value));
+        }, (error) => {
+            resolveWaiter((w) => w.reject(error));
+        });
+    };
+    return {
+        next: () => {
+            return new Promise((resolve, reject) => {
+                // First priority: Dispatch ready upstream events.
+                if (sourceIsDone) {
+                    return resolve(doneResult);
+                }
+                if (pendingSourceEvent) {
+                    pendingSourceEvent({ resolve, reject });
+                    pendingSourceEvent = null;
+                    return;
+                }
+                // Second priority: Dispatch injected events
+                if (pendingInjectedEvents.length) {
+                    return resolve(valueResult(pendingInjectedEvents.shift()));
+                }
+                // Nothing pending? Fetch from source
+                waiter = { resolve, reject };
+                return fetchFromSource();
+            });
+        },
+        inject: (event) => {
+            const pending = consumeWaiter();
+            if (pending != null) {
+                pending.resolve(valueResult(event));
+            }
+            else {
+                pendingInjectedEvents.push(event);
+            }
+        }
+    };
+}
+/**
+ * Splits a byte stream at line endings, emitting each line as a string.
+ */
+export function extractJsonLines(source, decoder) {
+    let buffer = '';
+    const pendingLines = [];
+    let isFinalEvent = false;
+    return {
+        next: async () => {
+            while (true) {
+                if (isFinalEvent) {
+                    return doneResult;
+                }
+                {
+                    const first = pendingLines.shift();
+                    if (first) {
+                        return { done: false, value: first };
+                    }
+                }
+                const { done, value } = await source.next();
+                if (done) {
+                    const remaining = buffer.trim();
+                    if (remaining.length != 0) {
+                        isFinalEvent = true;
+                        return { done: false, value: remaining };
+                    }
+                    return doneResult;
+                }
+                const data = decoder.decode(value, { stream: true });
+                buffer += data;
+                const lines = buffer.split('\n');
+                for (let i = 0; i < lines.length - 1; i++) {
+                    const l = lines[i].trim();
+                    if (l.length > 0) {
+                        pendingLines.push(l);
+                    }
+                }
+                buffer = lines[lines.length - 1];
+            }
+        }
+    };
+}
+/**
+ * Splits a concatenated stream of BSON objects by emitting individual objects.
+ */
+export function extractBsonObjects(source) {
+    // Fully read but not emitted yet.
+    const completedObjects = [];
+    // Whether source has returned { done: true }. We do the same once completed objects have been emitted.
+    let isDone = false;
+    const lengthBuffer = new DataView(new ArrayBuffer(4));
+    let objectBody = null;
+    // If we're parsing the length field, a number between 1 and 4 (inclusive) describing remaining bytes in the header.
+    // If we're consuming a document, the bytes remaining.
+    let remainingLength = 4;
+    return {
+        async next() {
+            while (true) {
+                // Before fetching new data from upstream, return completed objects.
+                if (completedObjects.length) {
+                    return valueResult(completedObjects.shift());
+                }
+                if (isDone) {
+                    return doneResult;
+                }
+                const upstreamEvent = await source.next();
+                if (upstreamEvent.done) {
+                    isDone = true;
+                    if (objectBody || remainingLength != 4) {
+                        throw new Error('illegal end of stream in BSON object');
+                    }
+                    return doneResult;
+                }
+                const chunk = upstreamEvent.value;
+                for (let i = 0; i < chunk.length;) {
+                    const availableInData = chunk.length - i;
+                    if (objectBody) {
+                        // We're in the middle of reading a BSON document.
+                        const bytesToRead = Math.min(availableInData, remainingLength);
+                        const copySource = new Uint8Array(chunk.buffer, chunk.byteOffset + i, bytesToRead);
+                        objectBody.set(copySource, objectBody.length - remainingLength);
+                        i += bytesToRead;
+                        remainingLength -= bytesToRead;
+                        if (remainingLength == 0) {
+                            completedObjects.push(objectBody);
+                            // Prepare to read another document, starting with its length
+                            objectBody = null;
+                            remainingLength = 4;
+                        }
+                    }
+                    else {
+                        // Copy up to 4 bytes into lengthBuffer, depending on how many we still need.
+                        const bytesToRead = Math.min(availableInData, remainingLength);
+                        for (let j = 0; j < bytesToRead; j++) {
+                            lengthBuffer.setUint8(4 - remainingLength + j, chunk[i + j]);
+                        }
+                        i += bytesToRead;
+                        remainingLength -= bytesToRead;
+                        if (remainingLength == 0) {
+                            // Transition from reading length header to reading document. Subtracting 4 because the length of the
+                            // header is included in length.
+                            const length = lengthBuffer.getInt32(0, true /* little endian */);
+                            remainingLength = length - 4;
+                            if (remainingLength < 1) {
+                                throw new Error(`invalid length for bson: ${length}`);
+                            }
+                            objectBody = new Uint8Array(length);
+                            new DataView(objectBody.buffer).setInt32(0, length, true);
+                        }
+                    }
+                }
+            }
+        }
+    };
+}
+//# sourceMappingURL=stream_transform.js.map

package/lib/utils/stream_transform.js.map

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

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@powersync/common",
-  "version": "0.0.0-dev-20260311103504",
+  "version": "0.0.0-dev-20260503073249",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "description": "API definitions for JourneyApps PowerSync",
+  "description": "API definitions for PowerSync",
   "type": "module",
   "main": "dist/bundle.mjs",
   "module": "dist/bundle.mjs",
@@ -32,7 +32,7 @@
       }
     }
   },
-  "author": "JOURNEYAPPS",
+  "author": "PowerSync",
   "license": "Apache-2.0",
   "files": [
     "lib",
@@ -48,7 +48,6 @@
   },
   "homepage": "https://docs.powersync.com",
   "dependencies": {
-    "async-mutex": "^0.5.0",
     "event-iterator": "^2.0.0"
   },
   "devDependencies": {
@@ -58,14 +57,16 @@
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@types/node": "^24.0.0",
     "@types/uuid": "^9.0.6",
+    "bson": "^6.10.4",
     "buffer": "^6.0.3",
-    "rollup": "^4.52.5",
-    "rollup-plugin-dts": "^6.2.1",
     "cross-fetch": "^4.1.0",
+    "estree-walker": "^3.0.3",
     "js-logger": "^1.6.1",
+    "magic-string": "^0.30.21",
+    "rollup": "^4.52.5",
+    "rollup-plugin-dts": "^6.2.1",
     "rsocket-core": "1.0.0-alpha.3",
-    "rsocket-websocket-client": "1.0.0-alpha.3",
-    "bson": "^6.10.4"
+    "rsocket-websocket-client": "1.0.0-alpha.3"
   },
   "scripts": {
     "build": "tsc -b && rollup -c rollup.config.mjs",

package/src/attachments/AttachmentQueue.ts

@@ -51,10 +51,16 @@ export class AttachmentQueue {
   /** Logger instance for diagnostic information */
   readonly logger: ILogger;
 
-  /** Interval in milliseconds between periodic sync operations. Default: 30000 (30 seconds) */
+  /** Interval in milliseconds between periodic sync operations. Acts as a polling timer to retry
+   *  failed uploads/downloads, especially after the app goes offline. Default: 30000 (30 seconds) */
   readonly syncIntervalMs: number = 30 * 1000;
 
-  /** Duration in milliseconds to throttle sync operations */
+  /** Throttle duration in milliseconds for the reactive watch query on the attachments table.
+   *  When attachment records change, a watch query detects the change and triggers a sync.
+   *  This throttle prevents the sync from firing too rapidly when many changes happen in
+   *  quick succession (e.g., bulk inserts). This is distinct from syncIntervalMs — it controls
+   *  how quickly the queue reacts to changes, while syncIntervalMs controls how often it polls
+   *  for retries. Default: 30 (from DEFAULT_WATCH_THROTTLE_MS) */
   readonly syncThrottleDuration: number;
 
   /** Whether to automatically download remote attachments. Default: true */
@@ -86,8 +92,8 @@ export class AttachmentQueue {
    * @param options.watchAttachments - Callback for monitoring attachment changes in your data model
    * @param options.tableName - Name of the table to store attachment records. Default: 'ps_attachment_queue'
    * @param options.logger - Logger instance. Defaults to db.logger
-   * @param options.syncIntervalMs - Interval between automatic syncs in milliseconds. Default: 30000
-   * @param options.syncThrottleDuration - Throttle duration for sync operations in milliseconds. Default: 1000
+   * @param options.syncIntervalMs - Periodic polling interval in milliseconds for retrying failed uploads/downloads. Default: 30000
+   * @param options.syncThrottleDuration - Throttle duration in milliseconds for the reactive watch query that detects attachment changes. Prevents rapid-fire syncs during bulk changes. Default: 30
    * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
    * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
    */

package/src/attachments/AttachmentService.ts

@@ -1,8 +1,7 @@
-import { Mutex } from 'async-mutex';
 import { AbstractPowerSyncDatabase } from '../client/AbstractPowerSyncDatabase.js';
 import { DifferentialWatchedQuery } from '../client/watched/processors/DifferentialQueryProcessor.js';
 import { ILogger } from '../utils/Logger.js';
-import { mutexRunExclusive } from '../utils/mutex.js';
+import { Mutex } from '../utils/mutex.js';
 import { AttachmentContext } from './AttachmentContext.js';
 import { AttachmentRecord, AttachmentState } from './Schema.js';
 
@@ -55,7 +54,7 @@ export class AttachmentService {
    * Executes a callback with exclusive access to the attachment context.
    */
   async withContext<T>(callback: (context: AttachmentContext) => Promise<T>): Promise<T> {
-    return mutexRunExclusive(this.mutex, async () => {
+    return this.mutex.runExclusive(async () => {
       return callback(this.context);
     });
   }

package/src/attachments/README.md

@@ -289,8 +289,8 @@ new AttachmentQueue(options: AttachmentQueueOptions)
 | `watchAttachments` | `(onUpdate: (attachments: WatchedAttachmentItem[]) => Promise<void>) => void` | Yes | - | Callback to determine which attachments to handle by the queue from your user defined query |
 | `tableName` | `string` | No | `'attachments'` | Name of the attachments table |
 | `logger` | `ILogger` | No | `db.logger` | Logger instance for diagnostic output |
-| `syncIntervalMs` | `number` | No | `30000` | Interval between automatic syncs in milliseconds |
-| `syncThrottleDuration` | `number` | No | `30` | Throttle duration for sync operations in milliseconds |
+| `syncIntervalMs` | `number` | No | `30000` | Periodic polling interval (in milliseconds) for retrying failed uploads/downloads. A `setInterval` timer that calls `syncStorage()` on this cadence, ensuring operations are retried even if no database changes occur (e.g., after coming back online). |
+| `syncThrottleDuration` | `number` | No | `30` | Throttle duration (in milliseconds) for the reactive watch query on the attachments table. When attachment records change (e.g., a new file is queued), a watch query detects the change and triggers a sync. This throttle prevents the sync from firing too rapidly when many changes happen in quick succession (e.g., bulk inserts). This is distinct from `syncIntervalMs` — it controls how quickly the queue *reacts* to changes, while `syncIntervalMs` controls how often it *polls* for retries. |
 | `downloadAttachments` | `boolean` | No | `true` | Whether to automatically download remote attachments |
 | `archivedCacheLimit` | `number` | No | `100` | Maximum number of archived attachments before cleanup |
 | `errorHandler` | `AttachmentErrorHandler` | No | `undefined` | Custom error handler for upload/download/delete operations |
@@ -676,11 +676,13 @@ Adjust sync frequency based on your needs:
 ```typescript
 const queue = new AttachmentQueue({
   // ... other options
-  syncIntervalMs: 60000, // Sync every 60 seconds instead of 30
+  syncIntervalMs: 60000, // Poll for retries every 60 seconds instead of 30
+  syncThrottleDuration: 100, // React to attachment changes within 100ms (default: 30ms)
 });
 ```
 
-Set to `0` to disable periodic syncing (manual `syncStorage()` calls only).
+- **`syncIntervalMs`** controls the periodic polling timer — how often the queue retries failed operations.
+- **`syncThrottleDuration`** controls how quickly the queue reacts to attachment table changes. The default (30ms) is fast enough for most use cases. Increase it if you see performance issues during bulk attachment operations.
 
 ### Archive and Cache Management
 

package/src/attachments/SyncingService.ts

@@ -54,7 +54,7 @@ export class SyncingService {
           updatedAttachments.push(downloaded);
           break;
         case AttachmentState.QUEUED_DELETE:
-          const deleted = await this.deleteAttachment(attachment);
+          const deleted = await this.deleteAttachment(attachment, context);
           updatedAttachments.push(deleted);
           break;
 
@@ -143,18 +143,17 @@ export class SyncingService {
    * On failure, defers to error handler or archives.
    *
    * @param attachment - The attachment record to delete
+   * @param context - Attachment context for database operations
    * @returns Updated attachment record
    */
-  async deleteAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord> {
+  async deleteAttachment(attachment: AttachmentRecord, context: AttachmentContext): Promise<AttachmentRecord> {
     try {
       await this.remoteStorage.deleteFile(attachment);
       if (attachment.localUri) {
         await this.localStorage.deleteFile(attachment.localUri);
       }
 
-      await this.attachmentService.withContext(async (ctx) => {
-        await ctx.deleteAttachment(attachment.id);
-      });
+      await context.deleteAttachment(attachment.id);
 
       return {
         ...attachment,

package/src/client/AbstractPowerSyncDatabase.ts

@@ -1,4 +1,3 @@
-import { Mutex } from 'async-mutex';
 import { EventIterator } from 'event-iterator';
 import Logger, { ILogger } from 'js-logger';
 import {
@@ -14,7 +13,7 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
-import { symbolAsyncIterator, throttleTrailing } from '../utils/async.js';
+import { throttleTrailing } from '../utils/async.js';
 import {
   ConnectionManager,
   CreateSyncImplementationOptions,
@@ -46,6 +45,7 @@ import { TriggerManagerImpl } from './triggers/TriggerManagerImpl.js';
 import { DEFAULT_WATCH_THROTTLE_MS, WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 import { WatchedQueryComparator } from './watched/processors/comparators.js';
+import { Mutex } from '../utils/mutex.js';
 
 export interface DisconnectAndClearOptions {
   /** When set to false, data in local-only tables is preserved. */
@@ -704,7 +704,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    * @returns A transaction of CRUD operations to upload, or null if there are none
    */
   async getNextCrudTransaction(): Promise<CrudTransaction | null> {
-    const iterator = this.getCrudTransactions()[symbolAsyncIterator]();
+    const iterator = this.getCrudTransactions()[Symbol.asyncIterator]();
     return (await iterator.next()).value;
   }
 
@@ -741,7 +741,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    */
   getCrudTransactions(): AsyncIterable<CrudTransaction, null> {
     return {
-      [symbolAsyncIterator]: () => {
+      [Symbol.asyncIterator]: () => {
         let lastCrudItemId = -1;
         const sql = `
 WITH RECURSIVE crud_entries AS (
@@ -813,6 +813,10 @@ SELECT * FROM crud_entries;
    * Execute a SQL write (INSERT/UPDATE/DELETE) query
    * and optionally return results.
    *
+   * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
+   * the returned result's `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
+   * Use a `RETURNING` clause and inspect `result.rows` when you need to confirm which rows changed.
+   *
    * @param sql The SQL query to execute
    * @param parameters Optional array of parameters to bind to the query
    * @returns The query result as an object with structured key-value pairs
@@ -921,7 +925,7 @@ SELECT * FROM crud_entries;
     await this.waitForReady();
     return this.database.readTransaction(
       async (tx) => {
-        const res = await callback({ ...tx });
+        const res = await callback(tx);
         await tx.rollback();
         return res;
       },