@powersync/common 1.53.2 → 1.54.0

package/src/client/triggers/sanitizeSQL.ts

@@ -1,9 +1,12 @@
 function sanitizeString(input: string): string {
   return `'${input.replace(/'/g, "''")}'`;
 }
+
 /**
  * Helper function for sanitizing UUID input strings.
  * Typically used with {@link sanitizeSQL}.
+ *
+ * @alpha
  */
 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;
@@ -41,6 +44,8 @@ export function sanitizeUUID(uuid: string): string {
  * // Incorrect:
  * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
  * ```
+ *
+ * @alpha
  */
 export function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string {
   let result = '';

package/src/client/watched/GetAllQuery.ts

@@ -4,6 +4,8 @@ import { WatchCompatibleQuery } from './WatchedQuery.js';
 
 /**
  * Options for {@link GetAllQuery}.
+ *
+ * @public
  */
 export type GetAllQueryOptions<RowType = unknown> = {
   sql: string;
@@ -23,6 +25,8 @@ export type GetAllQueryOptions<RowType = unknown> = {
 
 /**
  * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ *
+ * @public
  */
 export class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowType[]> {
   constructor(protected options: GetAllQueryOptions<RowType>) {}
@@ -37,7 +41,7 @@ export class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowT
   async execute(options: { db: AbstractPowerSyncDatabase }): Promise<RowType[]> {
     const { db } = options;
     const { sql, parameters = [] } = this.compile();
-    const rawResult = await db.getAll<unknown>(sql, [...parameters]);
+    const rawResult = await db.getAll<Record<string, unknown>>(sql, [...parameters]);
     if (this.options.mapper) {
       return rawResult.map(this.options.mapper);
     }

package/src/client/watched/WatchedQuery.ts

@@ -5,6 +5,8 @@ import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
 
 /**
  * State for {@link WatchedQuery} instances.
+ *
+ * @public
  */
 export interface WatchedQueryState<Data> {
   /**
@@ -33,6 +35,8 @@ export interface WatchedQueryState<Data> {
 
 /**
  * Options provided to the `execute` method of a {@link WatchCompatibleQuery}.
+ *
+ * @public
  */
 export interface WatchExecuteOptions {
   sql: string;
@@ -41,14 +45,17 @@ export interface WatchExecuteOptions {
 }
 
 /**
- * Similar to {@link CompatibleQuery}, except the `execute` method
- * does not enforce an Array result type.
+ *
+ * @public
  */
 export interface WatchCompatibleQuery<ResultType> {
   execute(options: WatchExecuteOptions): Promise<ResultType>;
   compile(): CompiledQuery;
 }
 
+/**
+ * @public
+ */
 export interface WatchedQueryOptions {
   /** The minimum interval between queries. */
   throttleMs?: number;
@@ -67,6 +74,9 @@ export interface WatchedQueryOptions {
   triggerOnTables?: string[];
 }
 
+/**
+ * @public
+ */
 export enum WatchedQueryListenerEvent {
   ON_DATA = 'onData',
   ON_ERROR = 'onError',
@@ -75,6 +85,9 @@ export enum WatchedQueryListenerEvent {
   CLOSED = 'closed'
 }
 
+/**
+ * @public
+ */
 export interface WatchedQueryListener<Data> extends BaseListener {
   [WatchedQueryListenerEvent.ON_DATA]?: (data: Data) => void | Promise<void>;
   [WatchedQueryListenerEvent.ON_ERROR]?: (error: Error) => void | Promise<void>;
@@ -83,13 +96,22 @@ export interface WatchedQueryListener<Data> extends BaseListener {
   [WatchedQueryListenerEvent.CLOSED]?: () => void | Promise<void>;
 }
 
+/**
+ * @internal
+ */
 export const DEFAULT_WATCH_THROTTLE_MS = 30;
 
+/**
+ * @internal
+ */
 export const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions = {
   throttleMs: DEFAULT_WATCH_THROTTLE_MS,
   reportFetching: true
 };
 
+/**
+ * @public
+ */
 export interface WatchedQuery<
   Data = unknown,
   Settings extends WatchedQueryOptions = WatchedQueryOptions,

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

@@ -45,9 +45,9 @@ type WatchedQueryProcessorListener<Data> = WatchedQueryListener<Data>;
  * @internal
  */
 export abstract class AbstractQueryProcessor<
-    Data = unknown[],
-    Settings extends WatchedQueryOptions = WatchedQueryOptions
-  >
+  Data = unknown[],
+  Settings extends WatchedQueryOptions = WatchedQueryOptions
+>
   extends MetaBaseObserver<WatchedQueryProcessorListener<Data>>
   implements WatchedQuery<Data, Settings>
 {
@@ -127,7 +127,7 @@ export abstract class AbstractQueryProcessor<
 
   /**
    * 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.
+   * This method should perform actual query watching and report results via {@link AbstractQueryProcessor.updateState} method.
    */
   protected abstract linkQuery(options: LinkQueryOptions<Data>): Promise<void>;
 
@@ -199,7 +199,7 @@ export abstract class AbstractQueryProcessor<
   protected async runWithReporting<T>(callback: () => Promise<T>): Promise<void> {
     try {
       await callback();
-    } catch (error) {
+    } catch (error: any) {
       // This will update the error on the state and iterate error listeners
       await this.updateState({ error });
     }
@@ -213,7 +213,7 @@ export abstract class AbstractQueryProcessor<
   ) {
     try {
       await this.iterateAsyncListeners(async (l) => callback(l));
-    } catch (error) {
+    } catch (error: any) {
       try {
         await this.iterateAsyncListeners(async (l) => l.onError?.(error));
       } catch (error) {

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

@@ -9,6 +9,8 @@ import {
 /**
  * Represents an updated row in a differential watched query.
  * It contains both the current and previous state of the row.
+ *
+ * @public
  */
 export interface WatchedQueryRowDifferential<RowType> {
   readonly current: RowType;
@@ -18,6 +20,8 @@ export interface WatchedQueryRowDifferential<RowType> {
 /**
  * Represents the result of a watched query that has been diffed.
  * {@link DifferentialWatchedQueryState#diff} is of the {@link WatchedQueryDifferential} form.
+ *
+ * @public
  */
 export interface WatchedQueryDifferential<RowType> {
   readonly added: ReadonlyArray<Readonly<RowType>>;
@@ -43,6 +47,8 @@ export interface WatchedQueryDifferential<RowType> {
 
 /**
  * Row comparator for differentially watched queries which keys and compares items in the result set.
+ *
+ * @public
  */
 export interface DifferentialWatchedQueryComparator<RowType> {
   /**
@@ -57,6 +63,8 @@ export interface DifferentialWatchedQueryComparator<RowType> {
 
 /**
  * Options for building a differential watched query with the {@link Query} builder.
+ *
+ * @public
  */
 export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOptions {
   /**
@@ -75,6 +83,8 @@ export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOp
 
 /**
  * Settings for differential incremental watched queries using.
+ *
+ * @public
  */
 export interface DifferentialWatchedQuerySettings<RowType> extends DifferentialWatchedQueryOptions<RowType> {
   /**
@@ -83,11 +93,18 @@ export interface DifferentialWatchedQuerySettings<RowType> extends DifferentialW
   query: WatchCompatibleQuery<RowType[]>;
 }
 
-export interface DifferentialWatchedQueryListener<RowType>
-  extends WatchedQueryListener<ReadonlyArray<Readonly<RowType>>> {
+/**
+ * @public
+ */
+export interface DifferentialWatchedQueryListener<RowType> extends WatchedQueryListener<
+  ReadonlyArray<Readonly<RowType>>
+> {
   onDiff?: (diff: WatchedQueryDifferential<RowType>) => void | Promise<void>;
 }
 
+/**
+ * @public
+ */
 export type DifferentialWatchedQuery<RowType> = WatchedQuery<
   ReadonlyArray<Readonly<RowType>>,
   DifferentialWatchedQuerySettings<RowType>,
@@ -97,8 +114,10 @@ export type DifferentialWatchedQuery<RowType> = WatchedQuery<
 /**
  * @internal
  */
-export interface DifferentialQueryProcessorOptions<RowType>
-  extends AbstractQueryProcessorOptions<RowType[], DifferentialWatchedQuerySettings<RowType>> {
+export interface DifferentialQueryProcessorOptions<RowType> extends AbstractQueryProcessorOptions<
+  RowType[],
+  DifferentialWatchedQuerySettings<RowType>
+> {
   rowComparator?: DifferentialWatchedQueryComparator<RowType>;
 }
 
@@ -107,6 +126,8 @@ type DataHashMap<RowType> = Map<string, { hash: string; item: RowType }>;
 /**
  * An empty differential result set.
  * This is used as the initial state for differential incrementally watched queries.
+ *
+ * @internal
  */
 export const EMPTY_DIFFERENTIAL = {
   added: [],
@@ -120,6 +141,8 @@ export const EMPTY_DIFFERENTIAL = {
  * Default implementation of the {@link DifferentialWatchedQueryComparator} for watched queries.
  * It keys items by their `id` property if available, alternatively it uses JSON stringification
  * of the entire item for the key and comparison.
+ *
+ * @internal
  */
 export const DEFAULT_ROW_COMPARATOR: DifferentialWatchedQueryComparator<any> = {
   keyBy: (item) => {
@@ -286,7 +309,7 @@ export class DifferentialQueryProcessor<RowType>
             if (Object.keys(partialStateUpdate).length > 0) {
               await this.updateState(partialStateUpdate);
             }
-          } catch (error) {
+          } catch (error: any) {
             await this.updateState({ error });
           }
         },

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

@@ -9,6 +9,8 @@ import { WatchedQueryComparator } from './comparators.js';
 
 /**
  * Settings for {@link WatchedQuery} instances created via {@link Query#watch}.
+ *
+ * @public
  */
 export interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
   query: WatchCompatibleQuery<DataType>;
@@ -16,14 +18,18 @@ export interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
 
 /**
  * {@link WatchedQuery} returned from {@link Query#watch}.
+ *
+ * @public
  */
 export type StandardWatchedQuery<DataType> = WatchedQuery<DataType, WatchedQuerySettings<DataType>>;
 
 /**
  * @internal
  */
-export interface OnChangeQueryProcessorOptions<Data>
-  extends AbstractQueryProcessorOptions<Data, WatchedQuerySettings<Data>> {
+export interface OnChangeQueryProcessorOptions<Data> extends AbstractQueryProcessorOptions<
+  Data,
+  WatchedQuerySettings<Data>
+> {
   comparator?: WatchedQueryComparator<Data>;
 }
 
@@ -103,7 +109,7 @@ export class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data, W
             if (Object.keys(partialStateUpdate).length > 0) {
               await this.updateState(partialStateUpdate);
             }
-          } catch (error) {
+          } catch (error: any) {
             await this.updateState({ error });
           }
         },

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

@@ -2,6 +2,8 @@
  * A basic comparator for incrementally watched queries. This performs a single comparison which
  * determines if the result set has changed. The {@link WatchedQuery} will only emit the new result
  * if a change has been detected.
+ *
+ * @public
  */
 export interface WatchedQueryComparator<Data> {
   checkEquality: (current: Data, previous: Data) => boolean;
@@ -9,6 +11,8 @@ export interface WatchedQueryComparator<Data> {
 
 /**
  * Options for {@link ArrayComparator}
+ *
+ * @public
  */
 export type ArrayComparatorOptions<ItemType> = {
   /**
@@ -20,6 +24,8 @@ export type ArrayComparatorOptions<ItemType> = {
 /**
  * An efficient comparator for {@link WatchedQuery} created with {@link Query#watch}. This has the ability to determine if a query
  * result has changes without necessarily processing all items in the result.
+ *
+ * @public
  */
 export class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemType[]> {
   constructor(protected options: ArrayComparatorOptions<ItemType>) {}
@@ -51,6 +57,8 @@ export class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemTyp
 
 /**
  * Watched query comparator that always reports changed result sets.
+ *
+ * @public
  */
 export const FalsyComparator: WatchedQueryComparator<unknown> = {
   checkEquality: () => false // Default comparator that always returns false

package/src/db/ConnectionClosedError.ts

@@ -2,6 +2,8 @@
  * 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';

package/src/db/DBAdapter.ts

@@ -12,6 +12,8 @@ import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
 
 /**
  * Object returned by SQL Query executions.
+ *
+ * @public
  */
 export type QueryResult = {
   /** Represents the auto-generated row id if applicable. */
@@ -31,13 +33,16 @@ export type QueryResult = {
     /** The length of the dataset */
     length: number;
     /** A convenience function to acess the index based the row object
-     * @param idx the row index
+     * @param idx - the row index
      * @returns the row structure identified by column names
      */
     item: (idx: number) => any;
   };
 };
 
+/**
+ * @public
+ */
 export interface DBGetUtils {
   /** Execute a read-only query and return results. */
   getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
@@ -47,6 +52,9 @@ export interface DBGetUtils {
   get<T>(sql: string, parameters?: any[]): Promise<T>;
 }
 
+/**
+ * @public
+ */
 export interface SqlExecutor {
   /** Execute a single write statement. */
   execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
@@ -58,17 +66,24 @@ export interface SqlExecutor {
    *
    * Example result:
    *
-   * ```[ [ '1', 'list 1', '33', 'Post content', '1' ] ]```
+   * ```JavaScript
+   * [ [ '1', 'list 1', '33', 'Post content', '1' ] ]
+   * ```
    *
    * Where as `execute`'s `rows._array` would have been:
    *
-   * ```[ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]```
+   * ```JavaScript
+   * [ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]
+   * ```
    */
   executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
 
   executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
 }
 
+/**
+ * @public
+ */
 export interface LockContext extends SqlExecutor, DBGetUtils {
   /**
    * How the connection has been opened.
@@ -82,7 +97,9 @@ export interface LockContext extends SqlExecutor, DBGetUtils {
 }
 
 /**
- * Implements {@link DBGetUtils} on a {@link SqlRunner}.
+ * Implements {@link DBGetUtils} on a {@link SqlExecutor}.
+ *
+ * @internal
  */
 export function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Omit<SqlExecutor, 'executeBatch'>>(
   Base: TBase
@@ -132,6 +149,9 @@ export function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Omi
   };
 }
 
+/**
+ * @public
+ */
 export interface Transaction extends LockContext {
   /** Commit multiple changes to the local DB using the Transaction context. */
   commit: () => Promise<QueryResult>;
@@ -141,29 +161,44 @@ export interface Transaction extends LockContext {
 
 /**
  * Update table operation numbers from SQLite
+ *
+ * @public
  */
 export enum RowUpdateType {
   SQLITE_INSERT = 18,
   SQLITE_DELETE = 9,
   SQLITE_UPDATE = 23
 }
+
+/**
+ * @public
+ */
 export interface TableUpdateOperation {
   opType: RowUpdateType;
   rowId: number;
 }
 /**
  * Notification of an update to one or more tables, for the purpose of realtime change notifications.
+ *
+ * @public
  */
 export interface UpdateNotification extends TableUpdateOperation {
   table: string;
 }
 
+/**
+ * @public
+ */
 export interface BatchedUpdateNotification {
+  // TODO (breaking change): Normalize to only including tables
   rawUpdates: UpdateNotification[];
   tables: string[];
   groupedUpdates: Record<string, TableUpdateOperation[]>;
 }
 
+/**
+ * @public
+ */
 export interface DBAdapterListener extends BaseListener {
   /**
    * Listener for table updates.
@@ -174,10 +209,16 @@ export interface DBAdapterListener extends BaseListener {
   tablesUpdated: (updateNotification: BatchedUpdateNotification | UpdateNotification) => void;
 }
 
+/**
+ * @public
+ */
 export interface DBLockOptions {
   timeoutMs?: number;
 }
 
+/**
+ * @public
+ */
 export interface ConnectionPool extends BaseObserverInterface<DBAdapterListener> {
   name: string;
   close: () => void | Promise<void>;
@@ -190,14 +231,19 @@ export interface ConnectionPool extends BaseObserverInterface<DBAdapterListener>
   refreshSchema: () => Promise<void>;
 }
 
+/**
+ * @public
+ */
 export interface DBAdapter extends ConnectionPool, SqlExecutor, DBGetUtils {
   readTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
   writeTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
 }
 
 /**
- * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool.readLock} and
- * {@link ConnectionPool.writeLock}.
+ * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool#readLock} and
+ * {@link ConnectionPool#writeLock}.
+ *
+ * @internal
  */
 export function DBAdapterDefaultMixin<TBase extends new (...args: any[]) => ConnectionPool>(Base: TBase) {
   return class extends Base implements DBAdapter {
@@ -299,12 +345,18 @@ class TransactionImplementation extends DBGetUtilsDefaultMixin(BaseTransaction)
   }
 }
 
+/**
+ * @internal
+ */
 export function isBatchedUpdateNotification(
   update: BatchedUpdateNotification | UpdateNotification
 ): update is BatchedUpdateNotification {
   return 'tables' in update;
 }
 
+/**
+ * @internal
+ */
 export function extractTableUpdates(update: BatchedUpdateNotification | UpdateNotification) {
   return isBatchedUpdateNotification(update) ? update.tables : [update.table];
 }

package/src/db/crud/SyncProgress.ts

@@ -15,6 +15,8 @@ export const FULL_SYNC_PRIORITY = 2147483647;
  *
  * To obtain these values, use {@link SyncProgress}, available through
  * {@link SyncStatus#downloadProgress}.
+ *
+ * @public
  */
 export interface ProgressWithOperations {
   /**
@@ -28,7 +30,8 @@ export interface ProgressWithOperations {
   downloadedOperations: number;
 
   /**
-   * Relative progress, as {@link downloadedOperations} of {@link totalOperations}.
+   * Relative progress, as {@link ProgressWithOperations.downloadedOperations} of
+   * {@link ProgressWithOperations.totalOperations}.
    *
    * This will be a number between `0.0` and `1.0` (inclusive).
    *
@@ -58,6 +61,8 @@ export interface ProgressWithOperations {
  *
  * Also note that data is downloaded in bulk, which means that individual counters are unlikely
  * to be updated one-by-one.
+ *
+ * @public
  */
 export class SyncProgress implements ProgressWithOperations {
   totalOperations: number;