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

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 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) {
-      // 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) {
-      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,23 +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.
- */
-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,9 +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.
-*/
-export class TableV2<Columns extends ColumnsType = ColumnsType> extends Table<Columns> {}

package/src/utils/AbortOperation.ts

@@ -1,17 +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.
- */
-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,72 +0,0 @@
-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;
-}
-
-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);
-    await this.runningTask;
-    this.runningTask = undefined;
-
-    if (this.pendingTaskParam) {
-      const pendingParam = this.pendingTaskParam;
-      this.pendingTaskParam = undefined;
-
-      this.execute(pendingParam);
-    }
-  }
-}

package/src/utils/async.ts

@@ -1,50 +0,0 @@
-/**
- * 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);
-    }
-  };
-}
-
-/**
- * Throttle a function to be called at most once every "wait" milliseconds,
- * on the leading and trailing edge.
- *
- * Roughly equivalent to lodash/throttle with {leading: true, trailing: true}
- */
-export function throttleLeadingTrailing(func: () => void, wait: number) {
-  let timeoutId: ReturnType<typeof setTimeout> | null = null;
-  let lastCallTime: number = 0;
-
-  const invokeFunction = () => {
-    func();
-    lastCallTime = Date.now();
-    timeoutId = null;
-  };
-
-  return function () {
-    const now = Date.now();
-    const timeToWait = wait - (now - lastCallTime);
-
-    if (timeToWait <= 0) {
-      // Leading edge: Call the function immediately if enough time has passed
-      invokeFunction();
-    } else if (!timeoutId) {
-      // Set a timeout for the trailing edge if not already set
-      timeoutId = setTimeout(invokeFunction, timeToWait);
-    }
-  };
-}

package/src/utils/parseQuery.ts

@@ -1,25 +0,0 @@
-import type { CompilableQuery } from '../types/types.js';
-
-export interface ParsedQuery {
-  sqlStatement: string;
-  parameters: any[];
-}
-
-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++;
-  }
-}