@powersync/common 1.53.1 → 1.54.0

package/src/client/triggers/TriggerManager.ts

@@ -2,7 +2,8 @@ import { LockContext } from '../../db/DBAdapter.js';
 
 /**
  * SQLite operations to track changes for with {@link TriggerManager}
- * @experimental
+ *
+ * @experimental @alpha
  */
 export enum DiffTriggerOperation {
   INSERT = 'INSERT',
@@ -11,7 +12,7 @@ export enum DiffTriggerOperation {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
  * This is the base record structure for all diff records.
  *
@@ -42,7 +43,7 @@ export interface BaseTriggerDiffRecord<TOperationId extends string | number = nu
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite UPDATE operation.
  * This record contains the new value and optionally the previous value.
  * Values are stored as JSON strings.
@@ -62,7 +63,7 @@ export interface TriggerDiffUpdateRecord<
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite INSERT operation.
  * This record contains the new value represented as a JSON string.
  */
@@ -77,7 +78,7 @@ export interface TriggerDiffInsertRecord<
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite DELETE operation.
  * This record contains the new value represented as a JSON string.
  */
@@ -92,7 +93,7 @@ export interface TriggerDiffDeleteRecord<
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
  * This is the record structure for all diff records.
  *
@@ -121,7 +122,7 @@ export type TriggerDiffRecord<TOperationId extends string | number = number> =
   | TriggerDiffDeleteRecord<TOperationId>;
 
 /**
- * @experimental
+ * @experimental @alpha
  * Querying the DIFF table directly with {@link TriggerDiffHandlerContext#withExtractedDiff} will return records
  * with the tracked columns extracted from the JSON value.
  * This type represents the structure of such records.
@@ -150,7 +151,7 @@ export type ExtractedTriggerDiffRecord<T, TOperationId extends string | number =
 };
 
 /**
- * @experimental
+ * @experimental @alpha
  * Hooks used in the creation of a table diff trigger.
  */
 export interface TriggerCreationHooks {
@@ -213,7 +214,7 @@ interface BaseCreateDiffTriggerOptions {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerManager#createDiffTrigger}.
  */
 export interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
@@ -232,7 +233,7 @@ export interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerRemoveCallback}.
  */
 export interface TriggerRemoveCallbackOptions {
@@ -240,12 +241,12 @@ export interface TriggerRemoveCallbackOptions {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Callback to drop a trigger after it has been created.
  */
 export type TriggerRemoveCallback = (options?: TriggerRemoveCallbackOptions) => Promise<void>;
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerDiffHandlerContext#withDiff}.
  */
 export interface WithDiffOptions {
@@ -260,7 +261,7 @@ export interface WithDiffOptions {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Context for the `onChange` handler provided to {@link TriggerManager#trackTableDiff}.
  */
 export interface TriggerDiffHandlerContext extends LockContext {
@@ -317,7 +318,7 @@ export interface TriggerDiffHandlerContext extends LockContext {
    * Allows querying the database with access to the table containing diff records.
    * The diff table is accessible via the `DIFF` accessor.
    *
-   * This is similar to {@link withDiff} but extracts the row columns from the tracked JSON value. The diff operation
+   * This is similar to {@link TriggerDiffHandlerContext#withDiff} but extracts the row columns from the tracked JSON value. The diff operation
    * data is aliased as `__` columns to avoid column conflicts.
    *
    * For {@link DiffTriggerOperation#DELETE} operations the previous_value columns are extracted for convenience.
@@ -349,7 +350,7 @@ export interface TriggerDiffHandlerContext extends LockContext {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Options for tracking changes to a table with {@link TriggerManager#trackTableDiff}.
  */
 export interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
@@ -361,14 +362,14 @@ export interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
   onChange: (context: TriggerDiffHandlerContext) => Promise<void>;
 
   /**
-   * The minimum interval, in milliseconds, between {@link onChange} invocations.
+   * The minimum interval, in milliseconds, between {@link TrackDiffOptions.onChange} invocations.
    *  @default {@link DEFAULT_WATCH_THROTTLE_MS}
    */
   throttleMs?: number;
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  */
 export interface TriggerManager {
   /**
@@ -417,7 +418,7 @@ export interface TriggerManager {
   /**
    * @experimental
    * Tracks changes for a table. Triggering a provided handler on changes.
-   * Uses {@link createDiffTrigger} internally to create a temporary destination table.
+   * Uses {@link TriggerManager.createDiffTrigger} internally to create a temporary destination table.
    *
    * @returns A callback to cleanup the trigger and stop tracking changes.
    *

package/src/client/triggers/TriggerManagerImpl.ts

@@ -97,8 +97,8 @@ export class TriggerManagerImpl implements TriggerManager {
     return this.options.db;
   }
 
-  protected async getUUID() {
-    const { id: uuid } = await this.db.get<{ id: string }>(/* sql */ `
+  protected async getUUID(ctx?: LockContext) {
+    const { id: uuid } = await (ctx ?? this.db).get<{ id: string }>(/* sql */ `
       SELECT
         uuid () as id
     `);
@@ -237,7 +237,7 @@ export class TriggerManagerImpl implements TriggerManager {
     const internalSource = sourceDefinition.internalName;
     const triggerIds: string[] = [];
 
-    const id = await this.getUUID();
+    const id = await this.getUUID(setupContext);
 
     const releaseStorageClaim = useStorage ? await this.options.claimManager.obtainClaim(id) : null;
 
@@ -421,7 +421,7 @@ export class TriggerManagerImpl implements TriggerManager {
             const callbackResult = await options.onChange({
               ...tx,
               destinationTable: destination,
-              withDiff: async <T>(query, params, options?: WithDiffOptions) => {
+              withDiff: async <T>(query: string, params: any, options?: WithDiffOptions) => {
                 // Wrap the query to expose the destination table
                 const operationIdSelect = options?.castOperationIdAsText
                   ? 'id, operation, CAST(operation_id AS TEXT) as operation_id, timestamp, value, previous_value'
@@ -439,7 +439,7 @@ export class TriggerManagerImpl implements TriggerManager {
                 `;
                 return tx.getAll<T>(wrappedQuery, params);
               },
-              withExtractedDiff: async <T>(query, params) => {
+              withExtractedDiff: async <T>(query: string, params: any) => {
                 // Wrap the query to expose the destination table
                 const wrappedQuery = /* sql */ `
                   WITH

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';