@powersync/common 1.57.3 → 2.1.0

package/src/client/watched/processors/AbstractQueryProcessor.ts

@@ -1,226 +0,0 @@
-import { AbstractPowerSyncDatabase } from '../../../client/AbstractPowerSyncDatabase.js';
-import { MetaBaseObserver } from '../../../utils/MetaBaseObserver.js';
-import {
-  WatchedQuery,
-  WatchedQueryListener,
-  WatchedQueryListenerEvent,
-  WatchedQueryOptions,
-  WatchedQueryState
-} from '../WatchedQuery.js';
-
-/**
- * @internal
- */
-export interface AbstractQueryProcessorOptions<Data, Settings extends WatchedQueryOptions = WatchedQueryOptions> {
-  db: AbstractPowerSyncDatabase;
-  watchOptions: Settings;
-  placeholderData: Data;
-}
-
-/**
- * @internal
- */
-export interface LinkQueryOptions<Data, Settings extends WatchedQueryOptions = WatchedQueryOptions> {
-  abortSignal: AbortSignal;
-  settings: Settings;
-}
-
-type MutableDeep<T> =
-  T extends ReadonlyArray<infer U>
-    ? U[] // convert readonly arrays to mutable arrays
-    : T;
-
-/**
- * @internal Mutable version of {@link WatchedQueryState}.
- * This is used internally to allow updates to the state.
- */
-export type MutableWatchedQueryState<Data> = {
-  -readonly [P in keyof WatchedQueryState<Data>]: MutableDeep<WatchedQueryState<Data>[P]>;
-};
-
-type WatchedQueryProcessorListener<Data> = WatchedQueryListener<Data>;
-
-/**
- * Performs underlying watching and yields a stream of results.
- * @internal
- */
-export abstract class AbstractQueryProcessor<
-  Data = unknown[],
-  Settings extends WatchedQueryOptions = WatchedQueryOptions
->
-  extends MetaBaseObserver<WatchedQueryProcessorListener<Data>>
-  implements WatchedQuery<Data, Settings>
-{
-  readonly state: WatchedQueryState<Data>;
-
-  protected abortController: AbortController;
-  protected initialized: Promise<void>;
-  protected _closed: boolean;
-  protected disposeListeners: (() => void) | null;
-
-  get closed() {
-    return this._closed;
-  }
-
-  constructor(protected options: AbstractQueryProcessorOptions<Data, Settings>) {
-    super();
-    this.abortController = new AbortController();
-    this._closed = false;
-    this.state = this.constructInitialState();
-    this.disposeListeners = null;
-    this.initialized = this.init(this.abortController.signal);
-  }
-
-  protected constructInitialState(): WatchedQueryState<Data> {
-    return {
-      isLoading: true,
-      isFetching: this.reportFetching, // Only set to true if we will report updates in future
-      error: null,
-      lastUpdated: null,
-      data: this.options.placeholderData
-    };
-  }
-
-  protected get reportFetching() {
-    return this.options.watchOptions.reportFetching ?? true;
-  }
-
-  protected async updateSettingsInternal(settings: Settings, signal: AbortSignal) {
-    // This may have been aborted while awaiting or if multiple calls to `updateSettings` were made
-    if (this._closed || signal.aborted) {
-      return;
-    }
-
-    this.options.watchOptions = settings;
-
-    this.iterateListeners((l) => l[WatchedQueryListenerEvent.SETTINGS_WILL_UPDATE]?.());
-
-    if (!this.state.isFetching && this.reportFetching) {
-      await this.updateState({
-        isFetching: true
-      });
-    }
-
-    await this.runWithReporting(() =>
-      this.linkQuery({
-        abortSignal: signal,
-        settings
-      })
-    );
-  }
-
-  /**
-   * Updates the underlying query.
-   */
-  async updateSettings(settings: Settings) {
-    // Abort the previous request
-    this.abortController.abort();
-
-    // Keep track of this controller's abort status
-    const abortController = new AbortController();
-    // Allow this to be aborted externally
-    this.abortController = abortController;
-
-    await this.initialized;
-    return this.updateSettingsInternal(settings, abortController.signal);
-  }
-
-  /**
-   * This method is used to link a query to the subscribers of this listener class.
-   * This method should perform actual query watching and report results via {@link AbstractQueryProcessor.updateState} method.
-   */
-  protected abstract linkQuery(options: LinkQueryOptions<Data>): Promise<void>;
-
-  protected async updateState(update: Partial<MutableWatchedQueryState<Data>>) {
-    if (this._closed) {
-      return;
-    }
-
-    if (typeof update.error !== 'undefined') {
-      await this.iterateAsyncListenersWithError(async (l) => l.onError?.(update.error!));
-      // An error always stops for the current fetching state
-      update.isFetching = false;
-      update.isLoading = false;
-    }
-
-    Object.assign(this.state, { lastUpdated: new Date() } satisfies Partial<WatchedQueryState<Data>>, update);
-
-    if (typeof update.data !== 'undefined') {
-      await this.iterateAsyncListenersWithError(async (l) => l.onData?.(this.state.data));
-    }
-    await this.iterateAsyncListenersWithError(async (l) => l.onStateChange?.(this.state));
-  }
-
-  /**
-   * Configures base DB listeners and links the query to listeners.
-   */
-  protected async init(signal: AbortSignal) {
-    const { db } = this.options;
-
-    const disposeCloseListener = db.registerListener({
-      closing: async () => {
-        await this.close();
-      }
-    });
-
-    // Wait for the schema to be set before listening to changes
-    await db.waitForReady();
-    const disposeSchemaListener = db.registerListener({
-      schemaChanged: async () => {
-        await this.runWithReporting(async () => {
-          await this.updateSettings(this.options.watchOptions);
-        });
-      }
-    });
-
-    this.disposeListeners = () => {
-      disposeCloseListener();
-      disposeSchemaListener();
-    };
-
-    // Initial setup
-    await this.runWithReporting(async () => {
-      await this.updateSettingsInternal(this.options.watchOptions, signal);
-    });
-  }
-
-  async close() {
-    this._closed = true;
-    this.abortController.abort();
-    this.disposeListeners?.();
-    this.disposeListeners = null;
-    this.iterateListeners((l) => l.closed?.());
-    this.listeners.clear();
-  }
-
-  /**
-   * Runs a callback and reports errors to the error listeners.
-   */
-  protected async runWithReporting<T>(callback: () => Promise<T>): Promise<void> {
-    try {
-      await callback();
-    } catch (error: any) {
-      // This will update the error on the state and iterate error listeners
-      await this.updateState({ error });
-    }
-  }
-
-  /**
-   * Iterate listeners and reports errors to onError handlers.
-   */
-  protected async iterateAsyncListenersWithError(
-    callback: (listener: Partial<WatchedQueryProcessorListener<Data>>) => Promise<void> | void
-  ) {
-    try {
-      await this.iterateAsyncListeners(async (l) => callback(l));
-    } catch (error: any) {
-      try {
-        await this.iterateAsyncListeners(async (l) => l.onError?.(error));
-      } catch (error) {
-        // Errors here are ignored
-        // since we are already in an error state
-        this.options.db.logger.error('Watched query error handler threw an Error', error);
-      }
-    }
-  }
-}

package/src/db/ConnectionClosedError.ts

@@ -1,25 +0,0 @@
-/**
- * Thrown when an underlying database connection is closed.
- * This is particularly relevant when worker connections are marked as closed while
- * operations are still in progress.
- *
- * @internal
- */
-export class ConnectionClosedError extends Error {
-  static NAME = 'ConnectionClosedError';
-
-  static MATCHES(input: any) {
-    /**
-     * If there are weird package issues which cause multiple versions of classes to be present, the instanceof
-     * check might fail. This also performs a failsafe check.
-     * This might also happen if the Error is serialized and parsed over a bridging channel like a MessagePort.
-     */
-    return (
-      input instanceof ConnectionClosedError || (input instanceof Error && input.name == ConnectionClosedError.NAME)
-    );
-  }
-  constructor(message: string) {
-    super(message);
-    this.name = ConnectionClosedError.NAME;
-  }
-}

package/src/db/schema/TableV2.ts

@@ -1,11 +0,0 @@
-import { ColumnsType } from './Column.js';
-import { Table } from './Table.js';
-
-/**
-  Generate a new table from the columns and indexes
-  @deprecated You should use {@link Table} instead as it now allows TableV2 syntax.
-  This will be removed in the next major release.
-
-  @public
-*/
-export class TableV2<Columns extends ColumnsType = ColumnsType> extends Table<Columns> {}

package/src/utils/AbortOperation.ts

@@ -1,19 +0,0 @@
-/**
- * Calls to Abortcontroller.abort(reason: any) will result in the
- * `reason` being thrown. This is not necessarily an error,
- *  but extends error for better logging purposes.
- *
- * @internal
- */
-export class AbortOperation extends Error {
-  constructor(protected reason: string) {
-    super(reason);
-    // Set the prototype explicitly
-    Object.setPrototypeOf(this, AbortOperation.prototype);
-
-    // Capture stack trace
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, AbortOperation);
-    }
-  }
-}

package/src/utils/ControlledExecutor.ts

@@ -1,81 +0,0 @@
-/**
- * @internal
- */
-export interface ControlledExecutorOptions {
-  /**
-   * If throttling is enabled, it ensures only one task runs at a time,
-   * and only one additional task can be scheduled to run after the current task completes. The pending task will be overwritten by the latest task.
-   * Enabled by default.
-   */
-  throttleEnabled?: boolean;
-}
-
-/**
- * @internal
- */
-export class ControlledExecutor<T> {
-  private task: (param: T) => Promise<void> | void;
-
-  /**
-   * Represents the currently running task, which could be a Promise or undefined if no task is running.
-   */
-  private runningTask: undefined | (Promise<void> | void);
-
-  private pendingTaskParam: T | undefined;
-
-  /**
-   * Flag to determine if throttling is enabled, which controls whether tasks are queued or run immediately.
-   */
-  private isThrottling: boolean;
-
-  private closed: boolean;
-
-  constructor(task: (param: T) => Promise<void> | void, options?: ControlledExecutorOptions) {
-    this.task = task;
-    const { throttleEnabled = true } = options ?? {};
-    this.isThrottling = throttleEnabled;
-    this.closed = false;
-  }
-
-  schedule(param: T) {
-    if (this.closed) {
-      return;
-    }
-    if (!this.isThrottling) {
-      this.task(param);
-      return;
-    }
-
-    if (this.runningTask) {
-      // set or replace the pending task param with latest one
-      this.pendingTaskParam = param;
-      return;
-    }
-
-    this.execute(param);
-  }
-
-  dispose() {
-    this.closed = true;
-
-    if (this.runningTask) {
-      this.runningTask = undefined;
-    }
-  }
-
-  private async execute(param: T) {
-    this.runningTask = this.task(param);
-    try {
-      await this.runningTask;
-    } finally {
-      this.runningTask = undefined;
-
-      if (this.pendingTaskParam) {
-        const pendingParam = this.pendingTaskParam;
-        this.pendingTaskParam = undefined;
-
-        this.execute(pendingParam);
-      }
-    }
-  }
-}

package/src/utils/async.ts

@@ -1,185 +0,0 @@
-import { symbolAsyncIterator } from './compatibility.js';
-import { doneResult, valueResult } from './stream_transform.js';
-
-/**
- * Throttle a function to be called at most once every "wait" milliseconds,
- * on the trailing edge.
- *
- * Roughly equivalent to lodash/throttle with {leading: false, trailing: true}
- */
-export function throttleTrailing(func: () => void, wait: number) {
-  let timeoutId: ReturnType<typeof setTimeout> | null = null;
-
-  const later = () => {
-    func();
-    timeoutId = null;
-  };
-
-  return function () {
-    if (timeoutId == null) {
-      timeoutId = setTimeout(later, wait);
-    }
-  };
-}
-
-export interface AsyncNotifier {
-  /**
-   * @param signal Also resolve the promise once this signal completes.
-   * @returns A promise that resolves once {@link notify} is called after this promise was last resolved.
-   */
-  waitForNotification(signal: AbortSignal): Promise<void>;
-
-  /**
-   * Notifies a pending listener, or makes the next {@link waitForNotification} complete immediately if no listener
-   * is currently active.
-   */
-  notify(): void;
-}
-
-export function asyncNotifier(): AsyncNotifier {
-  const queue = new EventQueue<void>();
-
-  return {
-    notify() {
-      if (queue.countOutstandingEvents > 0) {
-        // Already has an outstanding event, no need to buffer another one.
-      } else {
-        queue.notify();
-      }
-    },
-    waitForNotification(signal: AbortSignal) {
-      return queue.waitForEvent(signal);
-    }
-  };
-}
-
-type QueueWaiter<T> = { resolve: (event: T) => void; reject: (error: unknown) => void };
-
-export interface QueueOptions {
-  eventDelivered?: () => void;
-}
-
-export class EventQueue<T> {
-  private waitingConsumer: QueueWaiter<T> | undefined;
-  private readonly outstandingEvents: Array<(waiter: QueueWaiter<T>) => void>;
-
-  constructor(private readonly options: QueueOptions = {}) {
-    this.outstandingEvents = [];
-  }
-
-  /**
-   * The amount of buffered events not yet dispatched to listeners.
-   */
-  get countOutstandingEvents(): number {
-    return this.outstandingEvents.length;
-  }
-
-  private notifyInner(dispatch: (waiter: QueueWaiter<T>) => void) {
-    const existing = this.waitingConsumer;
-    this.waitingConsumer = undefined;
-
-    const dispatchAndNotifyListeners = (waiter: QueueWaiter<T>) => {
-      dispatch(waiter);
-      this.options.eventDelivered?.();
-    };
-
-    if (existing) {
-      dispatchAndNotifyListeners(existing);
-    } else {
-      this.outstandingEvents.push(dispatchAndNotifyListeners);
-    }
-  }
-
-  notify(value: T) {
-    this.notifyInner((l) => l.resolve(value));
-  }
-
-  notifyError(error: unknown) {
-    this.notifyInner((l) => l.reject(error));
-  }
-
-  waitForEvent(signal: AbortSignal): Promise<T | undefined> {
-    return new Promise((resolve, reject) => {
-      if (this.waitingConsumer != null) {
-        throw new Error('Illegal call to waitForEvent, already has a waiter.');
-      }
-
-      const complete = () => {
-        signal?.removeEventListener('abort', onAbort);
-      };
-
-      const onAbort = () => {
-        complete();
-        this.waitingConsumer = undefined;
-        resolve(undefined);
-      };
-
-      const waiter: QueueWaiter<T> = {
-        resolve: (value) => {
-          complete();
-          resolve(value);
-        },
-        reject: (error) => {
-          complete();
-          reject(error);
-        }
-      };
-
-      if (signal.aborted) {
-        resolve(undefined);
-      } else if (this.countOutstandingEvents > 0) {
-        const [event] = this.outstandingEvents.splice(0, 1);
-        event(waiter);
-      } else {
-        this.waitingConsumer = waiter;
-        signal.addEventListener('abort', onAbort);
-      }
-    });
-  }
-
-  /**
-   * Creates an async iterable backed by event queues.
-   *
-   * @param run A function invoked for every new listener. It receives a queue backing the async iterator.
-   * @param abort An additional abort signal. The `run` callback will also be aborted when `AsyncIterator.return` is
-   * called.
-   * @returns An object conforming to the async iterable protocol.
-   */
-  static queueBasedAsyncIterable<T>(
-    run: (queue: EventQueue<T>, abort: AbortSignal) => void,
-    abort?: AbortSignal
-  ): AsyncIterable<T> {
-    return {
-      [symbolAsyncIterator]: () => {
-        const queue = new EventQueue<T>();
-        const controller = new AbortController();
-
-        function dispose() {
-          controller.abort();
-          abort?.removeEventListener('abort', dispose);
-        }
-
-        if (abort) {
-          if (abort.aborted) {
-            controller.abort();
-          } else {
-            abort.addEventListener('abort', dispose);
-          }
-        }
-
-        run(queue, controller.signal);
-
-        return {
-          async next(): Promise<IteratorResult<T>> {
-            const event = await queue.waitForEvent(controller.signal);
-            return event == null ? doneResult : valueResult(event);
-          },
-          async return(): Promise<IteratorResult<T>> {
-            dispose();
-            return doneResult;
-          }
-        };
-      }
-    };
-  }
-}

package/src/utils/compatibility.ts

@@ -1,9 +0,0 @@
-/**
- * Some JavaScript engines, in particular older versions of React Native, don't support Symbol.asyncIterator.
- *
- * For those, users relying on async generators typically lower them with a transpiler and [this polyfill](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/core-asynciterator-polyfill_1.0.2/sdk/core/core-asynciterator-polyfill/src/index.ts#L4-L6).
- * This definition is compatible with that polyfill, so transpiled apps can use async iterables created by the PowerSync
- * SDK.
- */
-export const symbolAsyncIterator: typeof Symbol.asyncIterator =
-  Symbol.asyncIterator ?? Symbol.for('Symbol.asyncIterator');

package/src/utils/parseQuery.ts

@@ -1,31 +0,0 @@
-import type { CompilableQuery } from '../types/types.js';
-
-/**
- * @internal
- */
-export interface ParsedQuery {
-  sqlStatement: string;
-  parameters: any[];
-}
-
-/**
- * @internal
- */
-export const parseQuery = <T>(query: string | CompilableQuery<T>, parameters: any[]): ParsedQuery => {
-  let sqlStatement: string;
-
-  if (typeof query == 'string') {
-    sqlStatement = query;
-  } else {
-    const hasAdditionalParameters = parameters.length > 0;
-    if (hasAdditionalParameters) {
-      throw new Error('You cannot pass parameters to a compiled query.');
-    }
-
-    const compiled = query.compile();
-    sqlStatement = compiled.sql;
-    parameters = compiled.parameters as any[];
-  }
-
-  return { sqlStatement, parameters: parameters };
-};

package/src/utils/queue.ts

@@ -1,48 +0,0 @@
-/**
- * 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++;
-  }
-}