@powersync/common 1.40.0 → 1.41.1

package/src/client/triggers/sanitizeSQL.ts

@@ -0,0 +1,66 @@
+function sanitizeString(input: string): string {
+  return `'${input.replace(/'/g, "''")}'`;
+}
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export function sanitizeUUID(uuid: string): string {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  const isValid = uuidRegex.test(uuid);
+  if (!isValid) {
+    throw new Error(`${uuid} is not a valid UUID`);
+  }
+  return uuid;
+}
+
+/**
+ * SQL string template function for {@link TrackDiffOptions#when} and {@link CreateDiffTriggerOptions#when}.
+ *
+ * This function performs basic string interpolation for SQLite WHEN clauses.
+ *
+ * **String placeholders:**
+ * - All string values passed as placeholders are automatically wrapped in single quotes (`'`).
+ * - Do not manually wrap placeholders in single quotes in your template string; the function will handle quoting and escaping for you.
+ * - Any single quotes within the string value are escaped by doubling them (`''`), as required by SQL syntax.
+ *
+ * **Other types:**
+ * - `null` and `undefined` are converted to SQL `NULL`.
+ * - Objects are stringified using `JSON.stringify()` and wrapped in single quotes, with any single quotes inside the stringified value escaped.
+ * - Numbers and other primitive types are inserted directly.
+ *
+ * **Usage example:**
+ * ```typescript
+ * const myID = "O'Reilly";
+ * const clause = sanitizeSQL`New.id = ${myID}`;
+ * // Result: "New.id = 'O''Reilly'"
+ * ```
+ *
+ * Avoid manually quoting placeholders:
+ * ```typescript
+ * // Incorrect:
+ * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
+ * ```
+ */
+export function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string {
+  let result = '';
+  strings.forEach((str, i) => {
+    result += str;
+    if (i < values.length) {
+      // For SQL, escape single quotes in string values
+      const value = values[i];
+      if (typeof value == 'string') {
+        result += sanitizeString(value);
+      } else if (value == null) {
+        result += 'NULL';
+      } else if (typeof value == 'object') {
+        // Stringify the object and escape single quotes in the result
+        const stringified = JSON.stringify(value);
+        result += sanitizeString(stringified);
+      } else {
+        result += value;
+      }
+    }
+  });
+  return result;
+}

package/src/client/watched/GetAllQuery.ts

@@ -0,0 +1,46 @@
+import { CompiledQuery } from '../../types/types.js';
+import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { WatchCompatibleQuery } from './WatchedQuery.js';
+
+/**
+ * Options for {@link GetAllQuery}.
+ */
+export type GetAllQueryOptions<RowType = unknown> = {
+  sql: string;
+  parameters?: ReadonlyArray<unknown>;
+  /**
+   * Optional mapper function to convert raw rows into the desired RowType.
+   * @example
+   * ```javascript
+   * (rawRow) => ({
+   *   id: rawRow.id,
+   *   created_at: new Date(rawRow.created_at),
+   * })
+   * ```
+   */
+  mapper?: (rawRow: Record<string, unknown>) => RowType;
+};
+
+/**
+ * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ */
+export class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowType[]> {
+  constructor(protected options: GetAllQueryOptions<RowType>) {}
+
+  compile(): CompiledQuery {
+    return {
+      sql: this.options.sql,
+      parameters: this.options.parameters ?? []
+    };
+  }
+
+  async execute(options: { db: AbstractPowerSyncDatabase }): Promise<RowType[]> {
+    const { db } = options;
+    const { sql, parameters = [] } = this.compile();
+    const rawResult = await db.getAll<unknown>(sql, [...parameters]);
+    if (this.options.mapper) {
+      return rawResult.map(this.options.mapper);
+    }
+    return rawResult as RowType[];
+  }
+}

package/src/client/watched/WatchedQuery.ts

@@ -0,0 +1,121 @@
+import { CompiledQuery } from '../../types/types.js';
+import { BaseListener } from '../../utils/BaseObserver.js';
+import { MetaBaseObserverInterface } from '../../utils/MetaBaseObserver.js';
+import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+
+/**
+ * State for {@link WatchedQuery} instances.
+ */
+export interface WatchedQueryState<Data> {
+  /**
+   * Indicates the initial loading state (hard loading).
+   * Loading becomes false once the first set of results from the watched query is available or an error occurs.
+   */
+  readonly isLoading: boolean;
+  /**
+   * Indicates whether the query is currently fetching data, is true during the initial load
+   * and any time when the query is re-evaluating (useful for large queries).
+   */
+  readonly isFetching: boolean;
+  /**
+   * The last error that occurred while executing the query.
+   */
+  readonly error: Error | null;
+  /**
+   * The last time the query was updated.
+   */
+  readonly lastUpdated: Date | null;
+  /**
+   * The last data returned by the query.
+   */
+  readonly data: Data;
+}
+
+/**
+ * Options provided to the `execute` method of a {@link WatchCompatibleQuery}.
+ */
+export interface WatchExecuteOptions {
+  sql: string;
+  parameters: any[];
+  db: AbstractPowerSyncDatabase;
+}
+
+/**
+ * Similar to {@link CompatibleQuery}, except the `execute` method
+ * does not enforce an Array result type.
+ */
+export interface WatchCompatibleQuery<ResultType> {
+  execute(options: WatchExecuteOptions): Promise<ResultType>;
+  compile(): CompiledQuery;
+}
+
+export interface WatchedQueryOptions {
+  /** The minimum interval between queries. */
+  throttleMs?: number;
+  /**
+   * If true (default) the watched query will update its state to report
+   * on the fetching state of the query.
+   * Setting to false reduces the number of state changes if the fetch status
+   * is not relevant to the consumer.
+   */
+  reportFetching?: boolean;
+
+  /**
+   * By default, watched queries requery the database on any change to any dependent table of the query.
+   * Supplying an override here can be used to limit the tables which trigger querying the database.
+   */
+  triggerOnTables?: string[];
+}
+
+export enum WatchedQueryListenerEvent {
+  ON_DATA = 'onData',
+  ON_ERROR = 'onError',
+  ON_STATE_CHANGE = 'onStateChange',
+  SETTINGS_WILL_UPDATE = 'settingsWillUpdate',
+  CLOSED = 'closed'
+}
+
+export interface WatchedQueryListener<Data> extends BaseListener {
+  [WatchedQueryListenerEvent.ON_DATA]?: (data: Data) => void | Promise<void>;
+  [WatchedQueryListenerEvent.ON_ERROR]?: (error: Error) => void | Promise<void>;
+  [WatchedQueryListenerEvent.ON_STATE_CHANGE]?: (state: WatchedQueryState<Data>) => void | Promise<void>;
+  [WatchedQueryListenerEvent.SETTINGS_WILL_UPDATE]?: () => void;
+  [WatchedQueryListenerEvent.CLOSED]?: () => void | Promise<void>;
+}
+
+export const DEFAULT_WATCH_THROTTLE_MS = 30;
+
+export const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions = {
+  throttleMs: DEFAULT_WATCH_THROTTLE_MS,
+  reportFetching: true
+};
+
+export interface WatchedQuery<
+  Data = unknown,
+  Settings extends WatchedQueryOptions = WatchedQueryOptions,
+  Listener extends WatchedQueryListener<Data> = WatchedQueryListener<Data>
+> extends MetaBaseObserverInterface<Listener> {
+  /**
+   * Current state of the watched query.
+   */
+  readonly state: WatchedQueryState<Data>;
+
+  readonly closed: boolean;
+
+  /**
+   * Subscribe to watched query events.
+   * @returns A function to unsubscribe from the events.
+   */
+  registerListener(listener: Listener): () => void;
+
+  /**
+   * Updates the underlying query options.
+   * This will trigger a re-evaluation of the query and update the state.
+   */
+  updateSettings(options: Settings): Promise<void>;
+
+  /**
+   * Close the watched query and end all subscriptions.
+   */
+  close(): Promise<void>;
+}

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

@@ -0,0 +1,226 @@
+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);
+      }
+    }
+  }
+}