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

package/src/utils/mutex.ts

@@ -1,34 +1,192 @@
-import { Mutex } from 'async-mutex';
+import { Queue } from './queue.js';
+
+export type UnlockFn = () => void;
 
 /**
- * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
+ * An asynchronous semaphore implementation with associated items per lease.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
  */
-export async function mutexRunExclusive<T>(
-  mutex: Mutex,
-  callback: () => Promise<T>,
-  options?: { timeoutMs?: number }
-): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const timeout = options?.timeoutMs;
-    let timedOut = false;
-    const timeoutId = timeout
-      ? setTimeout(() => {
-          timedOut = true;
-          reject(new Error('Timeout waiting for lock'));
-        }, timeout)
-      : undefined;
-
-    mutex.runExclusive(async () => {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
+export class Semaphore<T> {
+  // Available items that are not currently assigned to a waiter.
+  private readonly available: Queue<T>;
+
+  readonly size: number;
+  // Linked list of waiters. We don't expect the wait list to become particularly large, and this allows removing
+  // aborted waiters from the middle of the list efficiently.
+  private firstWaiter?: SemaphoreWaitNode<T>;
+  private lastWaiter?: SemaphoreWaitNode<T>;
+
+  constructor(elements: Iterable<T>) {
+    this.available = new Queue(elements);
+    this.size = this.available.length;
+  }
+
+  private addWaiter(requestedItems: number, onAcquire: () => void): SemaphoreWaitNode<T> {
+    const node: SemaphoreWaitNode<T> = {
+      isActive: true,
+      acquiredItems: [],
+      remainingItems: requestedItems,
+      onAcquire,
+      prev: this.lastWaiter
+    };
+    if (this.lastWaiter) {
+      this.lastWaiter.next = node;
+      this.lastWaiter = node;
+    } else {
+      // First waiter
+      this.lastWaiter = this.firstWaiter = node;
+    }
+
+    return node;
+  }
+
+  private deactivateWaiter(waiter: SemaphoreWaitNode<T>) {
+    const { prev, next } = waiter;
+    waiter.isActive = false;
+
+    if (prev) prev.next = next;
+    if (next) next.prev = prev;
+    if (waiter == this.firstWaiter) this.firstWaiter = next;
+    if (waiter == this.lastWaiter) this.lastWaiter = prev;
+  }
+
+  private requestPermits(amount: number, abort?: AbortSignal): Promise<{ items: T[]; release: UnlockFn }> {
+    if (amount <= 0 || amount > this.size) {
+      throw new Error(`Invalid amount of items requested (${amount}), must be between 1 and ${this.size}`);
+    }
+
+    return new Promise((resolve, reject) => {
+      function rejectAborted() {
+        reject(abort?.reason ?? new Error('Semaphore acquire aborted'));
+      }
+      if (abort?.aborted) {
+        return rejectAborted();
+      }
+
+      let waiter: SemaphoreWaitNode<T>;
+
+      const markCompleted = () => {
+        const items = waiter.acquiredItems;
+        waiter.acquiredItems = []; // Avoid releasing items twice.
+
+        for (const element of items) {
+          // Give to next waiter, if possible.
+          const nextWaiter = this.firstWaiter;
+          if (nextWaiter) {
+            nextWaiter.acquiredItems.push(element);
+            nextWaiter.remainingItems--;
+            if (nextWaiter.remainingItems == 0) {
+              nextWaiter.onAcquire();
+            }
+          } else {
+            // No pending waiter, return lease into pool.
+            this.available.addLast(element);
+          }
+        }
+      };
+
+      const onAbort = () => {
+        abort?.removeEventListener('abort', onAbort);
+
+        if (waiter.isActive) {
+          this.deactivateWaiter(waiter);
+          rejectAborted();
+        }
+      };
+
+      const resolvePromise = () => {
+        this.deactivateWaiter(waiter);
+        abort?.removeEventListener('abort', onAbort);
+
+        const items = waiter.acquiredItems;
+        resolve({ items, release: markCompleted });
+      };
+
+      waiter = this.addWaiter(amount, resolvePromise);
+
+      // If there are items in the pool that haven't been assigned, we can pull them into this waiter. Note that this is
+      // only the case if we're the first waiter (otherwise, items would have been assigned to an earlier waiter).
+      while (!this.available.isEmpty && waiter.remainingItems > 0) {
+        waiter.acquiredItems.push(this.available.removeFirst());
+        waiter.remainingItems--;
       }
-      if (timedOut) return;
 
-      try {
-        resolve(await callback());
-      } catch (ex) {
-        reject(ex);
+      if (waiter.remainingItems == 0) {
+        return resolvePromise();
       }
+
+      abort?.addEventListener('abort', onAbort);
     });
-  });
+  }
+
+  /**
+   * Requests a single item from the pool.
+   *
+   * The returned `release` callback must be invoked to return the item into the pool.
+   */
+  async requestOne(abort?: AbortSignal): Promise<{ item: T; release: UnlockFn }> {
+    const { items, release } = await this.requestPermits(1, abort);
+    return { release, item: items[0] };
+  }
+
+  /**
+   * Requests access to all items from the pool.
+   *
+   * The returned `release` callback must be invoked to return items into the pool.
+   */
+  requestAll(abort?: AbortSignal): Promise<{ items: T[]; release: UnlockFn }> {
+    return this.requestPermits(this.size, abort);
+  }
+}
+
+interface SemaphoreWaitNode<T> {
+  /**
+   * Whether the waiter is currently active (not aborted and not fullfilled).
+   */
+  isActive: boolean;
+  acquiredItems: T[];
+  remainingItems: number;
+  onAcquire: () => void;
+  prev?: SemaphoreWaitNode<T>;
+  next?: SemaphoreWaitNode<T>;
+}
+
+/**
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+export class Mutex {
+  private inner = new Semaphore([null]);
+
+  async acquire(abort?: AbortSignal): Promise<UnlockFn> {
+    const { release } = await this.inner.requestOne(abort);
+    return release;
+  }
+
+  async runExclusive<T>(fn: () => PromiseLike<T> | T, abort?: AbortSignal): Promise<T> {
+    const returnMutex = await this.acquire(abort);
+
+    try {
+      return await fn();
+    } finally {
+      returnMutex();
+    }
+  }
+}
+
+/**
+ * Creates a signal aborting after the set timeout.
+ */
+export function timeoutSignal(timeout: number): AbortSignal;
+export function timeoutSignal(timeout?: number): AbortSignal | undefined;
+
+export function timeoutSignal(timeout?: number): AbortSignal | undefined {
+  if (timeout == null) return;
+  if ('timeout' in AbortSignal) return AbortSignal.timeout(timeout);
+
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(new Error('Timeout waiting for lock')), timeout);
+  return controller.signal;
 }

package/src/utils/queue.ts

@@ -0,0 +1,48 @@
+/**
+ * A simple fixed-capacity queue implementation.
+ *
+ * Unlike a naive queue implemented by `array.push()` and `array.shift()`, this avoids moving array elements around
+ * and is `O(1)` for {@link addLast} and {@link removeFirst}.
+ */
+export class Queue<T> {
+  private table: (T | undefined)[];
+  // Index of the first element in the table.
+  private head: number;
+  // Amount of items currently in the queue.
+  private _length: number;
+
+  constructor(initialItems: Iterable<T>) {
+    this.table = [...initialItems];
+    this.head = 0;
+    this._length = this.table.length;
+  }
+
+  get isEmpty(): boolean {
+    return this.length == 0;
+  }
+
+  get length(): number {
+    return this._length;
+  }
+
+  removeFirst(): T {
+    if (this.isEmpty) {
+      throw new Error('Queue is empty');
+    }
+
+    const result = this.table[this.head] as T;
+    this._length--;
+    this.table[this.head] = undefined;
+    this.head = (this.head + 1) % this.table.length;
+    return result;
+  }
+
+  addLast(element: T) {
+    if (this.length == this.table.length) {
+      throw new Error('Queue is full');
+    }
+
+    this.table[(this.head + this._length) % this.table.length] = element;
+    this._length++;
+  }
+}

package/src/utils/stream_transform.ts

@@ -0,0 +1,252 @@
+/**
+ * An async iterator that can't be cancelled.
+ *
+ * To keep data flow simple, we always pass an explicit cancellation token when subscribing to async streams. Once the
+ * {@link AbortSignal} aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
+ * that there's no way to distinguish between streams that have completed normally and streams that have been cancelled,
+ * but that is acceptable for our uses of this.
+ */
+export type SimpleAsyncIterator<T> = Pick<AsyncIterator<T>, 'next'>;
+
+export const doneResult: IteratorReturnResult<any> = { done: true, value: undefined };
+
+export function valueResult<T>(value: T) {
+  return { done: false, value };
+}
+
+/**
+ * A variant of {@link Array.map} for async iterators.
+ */
+export function map<T1, T2>(source: SimpleAsyncIterator<T1>, map: (source: T1) => T2): SimpleAsyncIterator<T2> {
+  return {
+    next: async () => {
+      const value = await source.next();
+      if (value.done) {
+        return value;
+      } else {
+        return { value: map(value.value) };
+      }
+    }
+  };
+}
+
+export interface InjectableIterator<T> extends SimpleAsyncIterator<T> {
+  inject(event: T): void;
+}
+
+/**
+ * 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<T>(source: SimpleAsyncIterator<T>): InjectableIterator<T> {
+  type Waiter = { resolve: (t: IteratorResult<T>) => void; reject: (e: unknown) => void };
+
+  let sourceIsDone = false;
+  let waiter: Waiter | undefined = 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: ((w: Waiter) => void) | null = null;
+
+  let pendingInjectedEvents: T[] = [];
+
+  const consumeWaiter = () => {
+    const pending = waiter;
+    waiter = undefined;
+    return pending;
+  };
+
+  const fetchFromSource = () => {
+    const resolveWaiter = (propagate: (w: Waiter) => void) => {
+      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: SimpleAsyncIterator<Uint8Array>,
+  decoder: TextDecoder
+): SimpleAsyncIterator<string> {
+  let buffer = '';
+  const pendingLines: string[] = [];
+  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: SimpleAsyncIterator<Uint8Array>): SimpleAsyncIterator<Uint8Array> {
+  // Fully read but not emitted yet.
+  const completedObjects: Uint8Array[] = [];
+
+  // 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: Uint8Array | null = 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(): Promise<IteratorResult<Uint8Array>> {
+      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);
+            }
+          }
+        }
+      }
+    }
+  };
+}

package/lib/utils/DataStream.d.ts

@@ -1,62 +0,0 @@
-import { ILogger } from 'js-logger';
-import { BaseListener, BaseObserver } from './BaseObserver.js';
-export type DataStreamOptions<ParsedData, SourceData> = {
-    mapLine?: (line: SourceData) => ParsedData;
-    /**
-     * Close the stream if any consumer throws an error
-     */
-    closeOnError?: boolean;
-    pressure?: {
-        highWaterMark?: number;
-        lowWaterMark?: number;
-    };
-    logger?: ILogger;
-};
-export type DataStreamCallback<Data extends any = any> = (data: Data) => Promise<void>;
-export interface DataStreamListener<Data extends any = any> extends BaseListener {
-    data: (data: Data) => Promise<void>;
-    closed: () => void;
-    error: (error: Error) => void;
-    highWater: () => Promise<void>;
-    lowWater: () => Promise<void>;
-}
-export declare const DEFAULT_PRESSURE_LIMITS: {
-    highWater: number;
-    lowWater: number;
-};
-/**
- * A very basic implementation of a data stream with backpressure support which does not use
- * native JS streams or async iterators.
- * This is handy for environments such as React Native which need polyfills for the above.
- */
-export declare class DataStream<ParsedData, SourceData = any> extends BaseObserver<DataStreamListener<ParsedData>> {
-    protected options?: DataStreamOptions<ParsedData, SourceData> | undefined;
-    dataQueue: SourceData[];
-    protected isClosed: boolean;
-    protected processingPromise: Promise<void> | null;
-    protected notifyDataAdded: (() => void) | null;
-    protected logger: ILogger;
-    protected mapLine: (line: SourceData) => ParsedData;
-    constructor(options?: DataStreamOptions<ParsedData, SourceData> | undefined);
-    get highWatermark(): number;
-    get lowWatermark(): number;
-    get closed(): boolean;
-    close(): Promise<void>;
-    /**
-     * Enqueues data for the consumers to read
-     */
-    enqueueData(data: SourceData): void;
-    /**
-     * Reads data once from the data stream
-     * @returns a Data payload or Null if the stream closed.
-     */
-    read(): Promise<ParsedData | null>;
-    /**
-     * Executes a callback for each data item in the stream
-     */
-    forEach(callback: DataStreamCallback<ParsedData>): () => void;
-    protected processQueue(): Promise<void> | undefined;
-    protected hasDataReader(): boolean;
-    protected _processQueue(): Promise<void>;
-    protected iterateAsyncErrored(cb: (l: Partial<DataStreamListener<ParsedData>>) => Promise<void>): Promise<void>;
-}