@powersync/common 1.57.1 → 2.0.0

package/lib/client/{AbstractPowerSyncDatabase.d.ts → CommonPowerSyncDatabase.d.ts}

@@ -1,23 +1,21 @@
-import { ILogger } from 'js-logger';
-import { DBAdapter, LockContext, QueryResult, Transaction } from '../db/DBAdapter.js';
+import { DBAdapter, DBGetUtils, LockContext, SqlExecutor, Transaction } from '../db/DBAdapter.js';
 import { SyncStatus } from '../db/crud/SyncStatus.js';
-import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
-import { BaseObserver } from '../utils/BaseObserver.js';
-import { ConnectionManager, CreateSyncImplementationOptions } from './ConnectionManager.js';
-import { ArrayQueryDefinition, Query } from './Query.js';
-import { SQLOpenFactory, SQLOpenOptions } from './SQLOpenFactory.js';
+import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
+import { WatchedQueryComparator } from './watched/processors/comparators.js';
+import { PowerSyncLogger } from '../utils/Logger.js';
+import { DatabaseSource } from './SQLOpenFactory.js';
+import { TriggerManager } from './triggers/TriggerManager.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
-import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
+import { SyncOptions } from './sync/options.js';
+import { SyncStream } from './sync/sync-streams.js';
+import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
-import { InternalConnectionOptions, StreamingSyncImplementation, StreamingSyncImplementationListener, type AdditionalConnectionOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
-import { SyncStream } from './sync/sync-streams.js';
-import { TriggerManager, TriggerManagerConfig } from './triggers/TriggerManager.js';
-import { TriggerManagerImpl } from './triggers/TriggerManagerImpl.js';
+import { ArrayQueryDefinition, Query } from './Query.js';
 import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
-import { WatchedQueryComparator } from './watched/processors/comparators.js';
 import { Mutex } from '../utils/mutex.js';
+import { QueryResult } from '../db/QueryResult.js';
 /**
  * @public
  */
@@ -26,49 +24,19 @@ export interface DisconnectAndClearOptions {
     clearLocal?: boolean;
 }
 /**
+ * Options required regardless of how a PowerSync database is opened.
+ *
  * @public
  */
-export interface BasePowerSyncDatabaseOptions extends AdditionalConnectionOptions {
+export interface BasePowerSyncDatabaseOptions {
     /** Schema used for the local database. */
     schema: Schema;
-    /**
-     * @deprecated Use {@link AdditionalConnectionOptions.retryDelayMs} instead as this will be removed in future
-     * releases.
-     */
-    retryDelay?: number;
-    logger?: ILogger;
-}
-/**
- * @public
- */
-export interface PowerSyncDatabaseOptions extends BasePowerSyncDatabaseOptions {
-    /**
-     * Source for a SQLite database connection.
-     * This can be either:
-     *  - A {@link DBAdapter} if providing an instantiated SQLite connection
-     *  - A {@link SQLOpenFactory} which will be used to open a SQLite connection
-     *  - {@link SQLOpenOptions} for opening a SQLite connection with a default {@link SQLOpenFactory}
-     */
-    database: DBAdapter | SQLOpenFactory | SQLOpenOptions;
-}
-/**
- * @public
- */
-export interface PowerSyncDatabaseOptionsWithDBAdapter extends BasePowerSyncDatabaseOptions {
-    database: DBAdapter;
-}
-/**
- * @public
- */
-export interface PowerSyncDatabaseOptionsWithOpenFactory extends BasePowerSyncDatabaseOptions {
-    database: SQLOpenFactory;
+    logger?: PowerSyncLogger;
 }
 /**
  * @public
  */
-export interface PowerSyncDatabaseOptionsWithSettings extends BasePowerSyncDatabaseOptions {
-    database: SQLOpenOptions;
-}
+export type PowerSyncDatabaseOptions = BasePowerSyncDatabaseOptions & DatabaseSource;
 /**
  * @public
  */
@@ -77,14 +45,6 @@ export interface SQLOnChangeOptions {
     tables?: string[];
     /** The minimum interval between queries. */
     throttleMs?: number;
-    /**
-     * @deprecated All tables specified in {@link SQLOnChangeOptions.tables} will be watched, including PowerSync tables
-     * with prefixes.
-     *
-     * Allows for watching any SQL table
-     * by not removing PowerSync table name prefixes
-     */
-    rawTableNames?: boolean;
     /**
      * Emits an empty result set immediately
      */
@@ -118,14 +78,14 @@ export interface WatchHandler {
  */
 export interface WatchOnChangeHandler {
     onChange: (event: WatchOnChangeEvent) => Promise<void> | void;
-    onError?: (error: Error) => void;
 }
 /**
  * @public
  */
-export interface PowerSyncDBListener extends StreamingSyncImplementationListener {
+export interface PowerSyncDBListener extends BaseListener {
     initialized: () => void;
     schemaChanged: (schema: Schema) => void;
+    statusChanged?: (status: SyncStatus) => void;
     closing: () => Promise<void> | void;
     closed: () => Promise<void> | void;
 }
@@ -141,89 +101,44 @@ export interface PowerSyncCloseOptions {
     disconnect?: boolean;
 }
 /**
- * @internal
- */
-export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
-/**
- * @internal
- */
-export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
-    retryDelayMs: number;
-    crudUploadThrottleMs: number;
-};
-/**
- * @internal
- */
-export declare const DEFAULT_CRUD_BATCH_LIMIT = 100;
-/**
- * Requesting nested or recursive locks can block the application in some circumstances.
- * This default lock timeout will act as a failsafe to throw an error if a lock cannot
- * be obtained.
- *
- * @internal
+ * @public
  */
-export declare const DEFAULT_LOCK_TIMEOUT_MS = 120000;
+export interface PowerSyncDatabaseConstructor<Options> {
+    new (options: Options): CommonPowerSyncDatabase;
+}
 /**
- * Tests if the input is a {@link PowerSyncDatabaseOptionsWithSettings}
- * @internal
+ * @public
+ * @deprecated Use {@link CommonPowerSyncDatabase} instead.
  */
-export declare const isPowerSyncDatabaseOptionsWithSettings: (test: any) => test is PowerSyncDatabaseOptionsWithSettings;
+export type AbstractPowerSyncDatabase = CommonPowerSyncDatabase;
 /**
  * @public
  */
-export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDBListener> {
-    protected options: PowerSyncDatabaseOptions;
+export interface CommonPowerSyncDatabase extends BaseObserverInterface<PowerSyncDBListener>, SqlExecutor, DBGetUtils {
     /**
      * Returns true if the connection is closed.
      */
-    closed: boolean;
-    ready: boolean;
+    readonly closed: boolean;
+    readonly ready: boolean;
     /**
      * Current connection status.
      */
-    currentStatus: SyncStatus;
-    sdkVersion: string;
-    protected bucketStorageAdapter: BucketStorageAdapter;
-    protected _isReadyPromise: Promise<void>;
-    protected connectionManager: ConnectionManager;
-    private subscriptions;
-    get syncStreamImplementation(): StreamingSyncImplementation | null;
-    /**
-     * The connector used to connect to the PowerSync service.
-     *
-     * @returns The connector used to connect to the PowerSync service or null if `connect()` has not been called.
-     */
-    get connector(): PowerSyncBackendConnector | null;
-    /**
-     * The resolved connection options used to connect to the PowerSync service.
-     *
-     * @returns The resolved connection options used to connect to the PowerSync service or null if `connect()` has not been called.
-     */
-    get connectionOptions(): InternalConnectionOptions | null;
-    protected _schema: Schema;
-    private _database;
-    protected runExclusiveMutex: Mutex;
+    readonly currentStatus: SyncStatus;
+    readonly sdkVersion: string;
     /**
-     * @experimental
+     * @experimental @alpha
      * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
      */
     readonly triggers: TriggerManager;
-    protected triggersImpl: TriggerManagerImpl;
-    logger: ILogger;
-    constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
-    constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
-    constructor(options: PowerSyncDatabaseOptionsWithSettings);
-    constructor(options: PowerSyncDatabaseOptions);
+    readonly logger: PowerSyncLogger;
     /**
      * Schema used for the local database.
      */
-    get schema(): Schema<{
-        [x: string]: import("../index.js").Table<any>;
-    }>;
+    readonly schema: Schema;
     /**
      * The underlying database.
      *
-     * For the most part, behavior is the same whether querying on the underlying database, or on {@link AbstractPowerSyncDatabase}.
+     * For the most part, behavior is the same whether querying on the underlying database, or on {@link CommonPowerSyncDatabase}.
      */
     get database(): DBAdapter;
     /**
@@ -231,17 +146,6 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     get connected(): boolean;
     get connecting(): boolean;
-    /**
-     * Opens the DBAdapter given open options using a default open factory
-     */
-    protected abstract openDBAdapter(options: PowerSyncDatabaseOptionsWithSettings): DBAdapter;
-    /**
-     * Generates a base configuration for {@link TriggerManagerImpl}.
-     * Implementations should override this if necessary.
-     */
-    protected generateTriggerManagerConfig(): TriggerManagerConfig;
-    protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector, options: CreateSyncImplementationOptions & RequiredAdditionalConnectionOptions): StreamingSyncImplementation;
-    protected abstract generateBucketStorageAdapter(): BucketStorageAdapter;
     /**
      * @returns A promise which will resolve once initialization is completed.
      */
@@ -263,22 +167,10 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Waits for the first sync status for which the `status` callback returns a truthy value.
      */
     waitForStatus(predicate: (status: SyncStatus) => any, signal?: AbortSignal): Promise<void>;
-    /**
-     * Allows for extended implementations to execute custom initialization
-     * logic as part of the total init process
-     */
-    abstract _initialize(): Promise<void>;
-    /**
-     * Entry point for executing initialization logic.
-     * This is to be automatically executed in the constructor.
-     */
-    protected initialize(): Promise<void>;
-    protected loadVersion(): Promise<void>;
-    protected resolveOfflineSyncStatus(): Promise<void>;
     /**
      * Replace the schema with a new version. This is for advanced use cases - typically the schema should just be specified once in the constructor.
      *
-     * Cannot be used while connected - this should only be called before {@link AbstractPowerSyncDatabase.connect}.
+     * Cannot be used while connected - this should only be called before {@link CommonPowerSyncDatabase.connect}.
      */
     updateSchema(schema: Schema): Promise<void>;
     /**
@@ -286,25 +178,14 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * While initializing is automatic, this helps to catch and report initialization errors.
      */
     init(): Promise<void>;
-    protected resolvedConnectionOptions(options: CreateSyncImplementationOptions): CreateSyncImplementationOptions & RequiredAdditionalConnectionOptions;
-    /**
-     * @deprecated Use {@link AbstractPowerSyncDatabase#close} instead.
-     * Clears all listeners registered by {@link AbstractPowerSyncDatabase#registerListener}.
-     */
-    dispose(): void;
-    /**
-     * Locking mechanism for exclusively running critical portions of connect/disconnect operations.
-     * Locking here is mostly only important on web for multiple tab scenarios.
-     */
-    protected runExclusive<T>(callback: () => Promise<T>): Promise<T>;
     /**
      * Connects to stream of events from the PowerSync instance.
      */
-    connect(connector: PowerSyncBackendConnector, options?: PowerSyncConnectionOptions): Promise<void>;
+    connect(connector: PowerSyncBackendConnector, options?: SyncOptions): Promise<void>;
     /**
      * Close the sync connection.
      *
-     * Use {@link AbstractPowerSyncDatabase.connect} to connect again.
+     * Use {@link CommonPowerSyncDatabase.connect} to connect again.
      */
     disconnect(): Promise<void>;
     /**
@@ -322,7 +203,6 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * @param name - The name of the stream to subscribe to.
      * @param params - Optional parameters for the stream subscription.
      * @returns A {@link SyncStream} instance that can be subscribed to.
-     * @experimental Sync streams are currently in alpha.
      */
     syncStream(name: string, params?: Record<string, any>): SyncStream;
     /**
@@ -369,7 +249,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Once the data have been successfully uploaded, call {@link CrudTransaction.complete} before
      * requesting the next transaction.
      *
-     * Unlike {@link AbstractPowerSyncDatabase.getCrudBatch}, this only returns data from a single transaction at a time.
+     * Unlike {@link CommonPowerSyncDatabase.getCrudBatch}, this only returns data from a single transaction at a time.
      * All data for the transaction is loaded into memory.
      *
      * @returns A transaction of CRUD operations to upload, or null if there are none
@@ -381,7 +261,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * This is typically used from the {@link PowerSyncBackendConnector.uploadData} callback. Each entry emitted by the
      * returned iterator is a full transaction containing all local writes made while that transaction was active.
      *
-     * Unlike {@link AbstractPowerSyncDatabase.getNextCrudTransaction}, which always returns the oldest transaction that hasn't been
+     * Unlike {@link CommonPowerSyncDatabase.getNextCrudTransaction}, which always returns the oldest transaction that hasn't been
      * {@link CrudTransaction.complete}d yet, this iterator can be used to receive multiple transactions. Calling
      * {@link CrudTransaction.complete} will mark that and all prior transactions emitted by the iterator as completed.
      *
@@ -415,73 +295,14 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * @returns A unique identifier for the database instance
      */
     getClientId(): Promise<string>;
-    private handleCrudCheckpoint;
-    /**
-     * Execute a SQL write (INSERT/UPDATE/DELETE) query
-     * and optionally return results.
-     *
-     * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
-     * the returned result's `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
-     * Use a `RETURNING` clause and inspect `result.rows` when you need to confirm which rows changed.
-     *
-     * @param sql - The SQL query to execute
-     * @param parameters - Optional array of parameters to bind to the query
-     * @returns The query result as an object with structured key-value pairs
-     */
-    execute(sql: string, parameters?: any[]): Promise<QueryResult>;
-    /**
-     * Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing.
-     * This bypasses certain PowerSync abstractions and is useful for accessing the raw database results.
-     *
-     * @param sql - The SQL query to execute
-     * @param parameters - Optional array of parameters to bind to the query
-     * @returns The raw query result from the underlying database as a nested array of raw values, where each row is
-     * represented as an array of column values without field names.
-     */
-    executeRaw(sql: string, parameters?: any[]): Promise<any[][]>;
-    /**
-     * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
-     * and optionally return results.
-     * This is faster than executing separately with each parameter set.
-     *
-     * @param sql - The SQL query to execute
-     * @param parameters - Optional 2D array of parameter sets, where each inner array is a set of parameters for one execution
-     * @returns The query result
-     */
-    executeBatch(sql: string, parameters?: any[][]): Promise<QueryResult>;
-    /**
-     *  Execute a read-only query and return results.
-     *
-     * @param sql - The SQL query to execute
-     * @param parameters - Optional array of parameters to bind to the query
-     * @returns An array of results
-     */
-    getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
-    /**
-     * Execute a read-only query and return the first result, or null if the ResultSet is empty.
-     *
-     * @param sql - The SQL query to execute
-     * @param parameters - Optional array of parameters to bind to the query
-     * @returns The first result if found, or null if no results are returned
-     */
-    getOptional<T>(sql: string, parameters?: any[]): Promise<T | null>;
-    /**
-     * Execute a read-only query and return the first result, error if the ResultSet is empty.
-     *
-     * @param sql - The SQL query to execute
-     * @param parameters - Optional array of parameters to bind to the query
-     * @returns The first result matching the query
-     * @throws Error if no rows are returned
-     */
-    get<T>(sql: string, parameters?: any[]): Promise<T>;
     /**
      * Takes a read lock, without starting a transaction.
-     * In most cases, {@link AbstractPowerSyncDatabase.readTransaction} should be used instead.
+     * In most cases, {@link CommonPowerSyncDatabase.readTransaction} should be used instead.
      */
     readLock<T>(callback: (db: LockContext) => Promise<T>): Promise<T>;
     /**
      * Takes a global lock, without starting a transaction.
-     * In most cases, {@link AbstractPowerSyncDatabase.writeTransaction} should be used instead.
+     * In most cases, {@link CommonPowerSyncDatabase.writeTransaction} should be used instead.
      */
     writeLock<T>(callback: (db: LockContext) => Promise<T>): Promise<T>;
     /**
@@ -507,8 +328,8 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     writeTransaction<T>(callback: (tx: Transaction) => Promise<T>, lockTimeout?: number): Promise<T>;
     /**
-     * This version of `watch` uses `AsyncGenerator`, for documentation see {@link AbstractPowerSyncDatabase.watchWithAsyncGenerator}.
-     * Can be overloaded to use a callback handler instead, for documentation see {@link AbstractPowerSyncDatabase.watchWithCallback}.
+     * This version of `watch` uses `AsyncGenerator`, for documentation see {@link CommonPowerSyncDatabase.watchWithAsyncGenerator}.
+     * Can be overloaded to use a callback handler instead, for documentation see {@link CommonPowerSyncDatabase.watchWithCallback}.
      *
      * @example
      * ```javascript
@@ -524,7 +345,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     watch(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult>;
     /**
-     * See {@link AbstractPowerSyncDatabase.watchWithCallback}.
+     * See {@link CommonPowerSyncDatabase.watchWithCallback}.
      *
      * @example
      * ```javascript
@@ -542,7 +363,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     watch(sql: string, parameters?: any[], handler?: WatchHandler, options?: SQLWatchOptions): void;
     /**
      * Allows defining a query which can be used to build a {@link WatchedQuery}.
-     * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+     * The defined query will be executed with {@link CommonPowerSyncDatabase#getAll}.
      * An optional mapper function can be provided to transform the results.
      *
      * @example
@@ -612,8 +433,8 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     resolveTables(sql: string, parameters?: any[], options?: SQLWatchOptions): Promise<string[]>;
     /**
-     * This version of `onChange` uses `AsyncGenerator`, for documentation see {@link AbstractPowerSyncDatabase.onChangeWithAsyncGenerator}.
-     * Can be overloaded to use a callback handler instead, for documentation see {@link AbstractPowerSyncDatabase.onChangeWithCallback}.
+     * This version of `onChange` uses `AsyncGenerator`, for documentation see {@link CommonPowerSyncDatabase.onChangeWithAsyncGenerator}.
+     * Can be overloaded to use a callback handler instead, for documentation see {@link CommonPowerSyncDatabase.onChangeWithCallback}.
      *
      * @example
      * ```javascript
@@ -626,7 +447,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     onChange(options?: SQLOnChangeOptions): AsyncIterable<WatchOnChangeEvent>;
     /**
-     * See {@link AbstractPowerSyncDatabase.onChangeWithCallback}.
+     * See {@link CommonPowerSyncDatabase.onChangeWithCallback}.
      *
      * @example
      * ```javascript
@@ -643,7 +464,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * Invoke the provided callback on any changes to any of the specified tables.
      *
-     * This is preferred over {@link AbstractPowerSyncDatabase.watchWithCallback} when multiple queries need to be performed
+     * This is preferred over {@link CommonPowerSyncDatabase.watchWithCallback} when multiple queries need to be performed
      * together when data is changed.
      *
      * Note that the `onChange` callback member of the handler is required.
@@ -656,14 +477,17 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * Create a Stream of changes to any of the specified tables.
      *
-     * This is preferred over {@link AbstractPowerSyncDatabase.watchWithAsyncGenerator} when multiple queries need to be
+     * This is preferred over {@link CommonPowerSyncDatabase.watchWithAsyncGenerator} when multiple queries need to be
      * performed together when data is changed.
      *
+     * Note: do not declare this as `async *onChange` as it will not work in React Native.
+     *
      * @param options - Options for configuring watch behavior
      * @returns An AsyncIterable that yields change events whenever the specified tables change
      */
     onChangeWithAsyncGenerator(options?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent>;
-    private handleTableChanges;
-    private processTableUpdates;
-    private executeReadOnly;
+    /**
+     * @internal
+     */
+    createMutex(): Mutex;
 }

package/lib/client/CommonPowerSyncDatabase.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CommonPowerSyncDatabase.js.map

package/lib/client/CommonPowerSyncDatabase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommonPowerSyncDatabase.js","sourceRoot":"","sources":["../../src/client/CommonPowerSyncDatabase.ts"],"names":[],"mappings":""}

package/lib/client/SQLOpenFactory.d.ts

@@ -35,20 +35,42 @@ export interface SQLOpenFactory {
     openDB(): DBAdapter;
 }
 /**
- * Tests if the input is a {@link SQLOpenOptions}
+ * A source describing how to open databases.
  *
- * @internal
- */
-export declare const isSQLOpenOptions: (test: any) => test is SQLOpenOptions;
-/**
- * Tests if input is a {@link SQLOpenFactory}
+ * - A {@link DBAdapter} providing access to an opened SQLite connection pool.
+ * - A {@link SQLOpenFactory} which will be used to open a SQLite connection pool lazily.
+ * - A {@link SQLOpenOptions} for opening a SQLite connection with a default {@link SQLOpenFactory} for the current
+ *   platform.
  *
- * @internal
- */
-export declare const isSQLOpenFactory: (test: any) => test is SQLOpenFactory;
-/**
- * Tests if input is a {@link DBAdapter}
+ * For most apps, using the `database` key with {@link SQLOpenOptions} is the easiest and recommended option.
  *
- * @internal
+ * @public
  */
-export declare const isDBAdapter: (test: any) => test is DBAdapter;
+export type DatabaseSource<OpenOptions extends SQLOpenOptions = SQLOpenOptions> = {
+    /**
+     * Wrap an opened {@link DBAdapter} as a PowerSync database instance.
+     *
+     * This is primarily useful for testing. On most platforms, PowerSync would open a pool of SQLite connections by
+     * default. This option allows using a single in-memory instance instead. It can also be used to customize the
+     * database used by default, e.g. to install additional logging on SQL statements by intercepting methods.
+     */
+    opened: DBAdapter;
+} | {
+    /**
+     * Construct a PowerSync database that will call {@link SQLOpenFactory.openDB} when opened.
+     *
+     * On most SDKs, passing {@link SQLOpenOptions} is a better option. An exception is React Native, where using an
+     * [OP-SQLite factory](https://docs.powersync.com/client-sdks/reference/react-native-and-expo#op-sqlite) is
+     * recommended.
+     */
+    factory: SQLOpenFactory;
+} | {
+    /**
+     * Construct a PowerSync database opening a connection pool from the {@link SQLOpenOptions}.
+     *
+     * At the very least, options include the {@link SQLOpenOptions.dbFilename} to open. Depending on the PowerSync
+     * SDK used, additional options are available. For example, the web SDK allows configuring the virtual file system
+     * implementation used to persist files on the web too.
+     */
+    database: OpenOptions;
+};

package/lib/client/SQLOpenFactory.js

@@ -1,26 +1,2 @@
-/**
- * Tests if the input is a {@link SQLOpenOptions}
- *
- * @internal
- */
-export const isSQLOpenOptions = (test) => {
-    // typeof null is `object`, but you cannot use the `in` operator on `null.
-    return test && typeof test == 'object' && 'dbFilename' in test;
-};
-/**
- * Tests if input is a {@link SQLOpenFactory}
- *
- * @internal
- */
-export const isSQLOpenFactory = (test) => {
-    return typeof test?.openDB == 'function';
-};
-/**
- * Tests if input is a {@link DBAdapter}
- *
- * @internal
- */
-export const isDBAdapter = (test) => {
-    return typeof test?.writeTransaction == 'function';
-};
+export {};
 //# sourceMappingURL=SQLOpenFactory.js.map

package/lib/client/SQLOpenFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"SQLOpenFactory.js","sourceRoot":"","sources":["../../src/client/SQLOpenFactory.ts"],"names":[],"mappings":"AAwCA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAS,EAA0B,EAAE;IACpE,0EAA0E;IAC1E,OAAO,IAAI,IAAI,OAAO,IAAI,IAAI,QAAQ,IAAI,YAAY,IAAI,IAAI,CAAC;AACjE,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAAS,EAA0B,EAAE;IACpE,OAAO,OAAO,IAAI,EAAE,MAAM,IAAI,UAAU,CAAC;AAC3C,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAS,EAAqB,EAAE;IAC1D,OAAO,OAAO,IAAI,EAAE,gBAAgB,IAAI,UAAU,CAAC;AACrD,CAAC,CAAC"}
+{"version":3,"file":"SQLOpenFactory.js","sourceRoot":"","sources":["../../src/client/SQLOpenFactory.ts"],"names":[],"mappings":""}

package/lib/client/compilableQueryWatch.d.ts

@@ -1,5 +1,5 @@
 import { CompilableQuery } from './../types/types.js';
-import { AbstractPowerSyncDatabase, SQLWatchOptions } from './AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase, SQLWatchOptions } from './CommonPowerSyncDatabase.js';
 /**
  * @public
  */
@@ -10,4 +10,4 @@ export interface CompilableQueryWatchHandler<T> {
 /**
  * @public
  */
-export declare function compilableQueryWatch<T>(db: AbstractPowerSyncDatabase, query: CompilableQuery<T>, handler: CompilableQueryWatchHandler<T>, options?: SQLWatchOptions): void;
+export declare function compilableQueryWatch<T>(db: CommonPowerSyncDatabase, query: CompilableQuery<T>, handler: CompilableQueryWatchHandler<T>, options?: SQLWatchOptions): void;

package/lib/client/compilableQueryWatch.js

@@ -23,8 +23,7 @@ export function compilableQueryWatch(db, query, handler, options) {
                     catch (error) {
                         onError(error);
                     }
-                },
-                onError
+                }
             }, {
                 ...(options ?? {}),
                 tables: resolvedTables,

package/lib/client/compilableQueryWatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"compilableQueryWatch.js","sourceRoot":"","sources":["../../src/client/compilableQueryWatch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAU3D;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,EAA6B,EAC7B,KAAyB,EACzB,OAAuC,EACvC,OAAyB;IAEzB,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,CAAC,CAAQ,EAAE,EAAE,GAAE,CAAC,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAC/D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,EAAE,WAAwB,EAAE,EAAE;QACpD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,cAAc,GAAG,MAAM,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,UAAgB,EAAE,OAAO,CAAC,CAAC;YAE1F,qBAAqB;YACrB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YACrC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAEjB,EAAE,CAAC,oBAAoB,CACrB;gBACE,QAAQ,EAAE,KAAK,IAAI,EAAE;oBACnB,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;wBACrC,QAAQ,CAAC,MAAM,CAAC,CAAC;oBACnB,CAAC;oBAAC,OAAO,KAAU,EAAE,CAAC;wBACpB,OAAO,CAAC,KAAK,CAAC,CAAC;oBACjB,CAAC;gBACH,CAAC;gBACD,OAAO;aACR,EACD;gBACE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;gBAClB,MAAM,EAAE,cAAc;gBACtB,kDAAkD;gBAClD,MAAM,EAAE,WAAW;aACpB,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;IAEF,iBAAiB,CAAC,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"compilableQueryWatch.js","sourceRoot":"","sources":["../../src/client/compilableQueryWatch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAU3D;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,EAA2B,EAC3B,KAAyB,EACzB,OAAuC,EACvC,OAAyB;IAEzB,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,CAAC,CAAQ,EAAE,EAAE,GAAE,CAAC,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAC/D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,EAAE,WAAwB,EAAE,EAAE;QACpD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,cAAc,GAAG,MAAM,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,UAAgB,EAAE,OAAO,CAAC,CAAC;YAE1F,qBAAqB;YACrB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YACrC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAEjB,EAAE,CAAC,oBAAoB,CACrB;gBACE,QAAQ,EAAE,KAAK,IAAI,EAAE;oBACnB,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;wBACrC,QAAQ,CAAC,MAAM,CAAC,CAAC;oBACnB,CAAC;oBAAC,OAAO,KAAU,EAAE,CAAC;wBACpB,OAAO,CAAC,KAAK,CAAC,CAAC;oBACjB,CAAC;gBACH,CAAC;aACF,EACD;gBACE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;gBAClB,MAAM,EAAE,cAAc;gBACtB,kDAAkD;gBAClD,MAAM,EAAE,WAAW;aACpB,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;IAEF,iBAAiB,CAAC,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC"}

package/lib/client/connection/PowerSyncBackendConnector.d.ts

@@ -1,5 +1,5 @@
 import { PowerSyncCredentials } from './PowerSyncCredentials.js';
-import type { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase } from '../CommonPowerSyncDatabase.js';
 /**
  * @public
  */
@@ -18,9 +18,9 @@ export interface PowerSyncBackendConnector {
     fetchCredentials: () => Promise<PowerSyncCredentials | null>;
     /** Upload local changes to the app backend.
      *
-     * Use {@link AbstractPowerSyncDatabase.getCrudBatch} to get a batch of changes to upload.
+     * Use {@link CommonPowerSyncDatabase.getCrudBatch} to get a batch of changes to upload.
      *
      * Any thrown errors will result in a retry after the configured wait period (default: 5 seconds).
      */
-    uploadData: (database: AbstractPowerSyncDatabase) => Promise<void>;
+    uploadData: (database: CommonPowerSyncDatabase) => Promise<void>;
 }

package/lib/client/runOnSchemaChange.d.ts

@@ -1,5 +1,5 @@
-import { AbstractPowerSyncDatabase, SQLWatchOptions } from './AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase, SQLWatchOptions } from './CommonPowerSyncDatabase.js';
 /**
  * @internal
  */
-export declare function runOnSchemaChange(callback: (signal: AbortSignal) => void, db: AbstractPowerSyncDatabase, options?: SQLWatchOptions): void;
+export declare function runOnSchemaChange(callback: (signal: AbortSignal) => void, db: CommonPowerSyncDatabase, options?: SQLWatchOptions): void;

package/lib/client/runOnSchemaChange.js.map

@@ -1 +1 @@
-{"version":3,"file":"runOnSchemaChange.js","sourceRoot":"","sources":["../../src/client/runOnSchemaChange.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAuC,EACvC,EAA6B,EAC7B,OAAyB;IAEzB,MAAM,mBAAmB,GAAG,GAAG,EAAE;QAC/B,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,IAAI,qBAAqB,GAAwB,IAAI,CAAC;QACtD,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,eAAe,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACzC,qBAAqB,EAAE,EAAE,CAAC;YAC1B,qBAAqB,GAAG,IAAI,CAAC;YAC7B,kDAAkD;YAClD,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC9D,CAAC,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACzD,qBAAqB,GAAG,EAAE,CAAC,gBAAgB,CAAC;YAC1C,aAAa,EAAE,KAAK,IAAI,EAAE;gBACxB,YAAY,EAAE,CAAC;gBACf,yIAAyI;gBACzI,UAAU,CAAC,GAAG,EAAE,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7C,CAAC;SACF,CAAC,CAAC;QACH,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,mBAAmB,EAAE,CAAC;AACxB,CAAC"}
+{"version":3,"file":"runOnSchemaChange.js","sourceRoot":"","sources":["../../src/client/runOnSchemaChange.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAuC,EACvC,EAA2B,EAC3B,OAAyB;IAEzB,MAAM,mBAAmB,GAAG,GAAG,EAAE;QAC/B,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,IAAI,qBAAqB,GAAwB,IAAI,CAAC;QACtD,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,eAAe,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACzC,qBAAqB,EAAE,EAAE,CAAC;YAC1B,qBAAqB,GAAG,IAAI,CAAC;YAC7B,kDAAkD;YAClD,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC9D,CAAC,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACzD,qBAAqB,GAAG,EAAE,CAAC,gBAAgB,CAAC;YAC1C,aAAa,EAAE,KAAK,IAAI,EAAE;gBACxB,YAAY,EAAE,CAAC;gBACf,yIAAyI;gBACzI,UAAU,CAAC,GAAG,EAAE,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7C,CAAC;SACF,CAAC,CAAC;QACH,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,mBAAmB,EAAE,CAAC;AACxB,CAAC"}