@powersync/common 1.12.0 → 1.13.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -10,14 +10,14 @@ import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter';
 import { CrudBatch } from './sync/bucket/CrudBatch';
 import { CrudTransaction } from './sync/bucket/CrudTransaction';
 import { AbstractStreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncImplementation, PowerSyncConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation';
+import { SQLOpenFactory, SQLOpenOptions } from './SQLOpenFactory';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
 }
-export interface PowerSyncDatabaseOptions {
+export interface BasePowerSyncDatabaseOptions {
     /** Schema used for the local database. */
     schema: Schema;
-    database: DBAdapter;
     /**
      * Delay for retrying sync streaming operations
      * from the PowerSync backend after an error occurs.
@@ -31,6 +31,25 @@ export interface PowerSyncDatabaseOptions {
     crudUploadThrottleMs?: number;
     logger?: ILogger;
 }
+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;
+}
+export interface PowerSyncDatabaseOptionsWithDBAdapter extends BasePowerSyncDatabaseOptions {
+    database: DBAdapter;
+}
+export interface PowerSyncDatabaseOptionsWithOpenFactory extends BasePowerSyncDatabaseOptions {
+    database: SQLOpenFactory;
+}
+export interface PowerSyncDatabaseOptionsWithSettings extends BasePowerSyncDatabaseOptions {
+    database: SQLOpenOptions;
+}
 export interface SQLWatchOptions {
     signal?: AbortSignal;
     tables?: string[];
@@ -100,6 +119,10 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     protected _isReadyPromise: Promise<void>;
     private hasSyncedWatchDisposer?;
     protected _schema: Schema;
+    private _database;
+    constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
+    constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
+    constructor(options: PowerSyncDatabaseOptionsWithSettings);
     constructor(options: PowerSyncDatabaseOptions);
     /**
      * Schema used for the local database.
@@ -117,6 +140,10 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Whether a connection to the PowerSync service is currently open.
      */
     get connected(): boolean;
+    /**
+     * Opens the DBAdapter given open options using a default open factory
+     */
+    protected abstract openDBAdapter(options: SQLOpenOptions): DBAdapter;
     protected abstract generateSyncStreamImplementation(connector: PowerSyncBackendConnector): AbstractStreamingSyncImplementation;
     protected abstract generateBucketStorageAdapter(): BucketStorageAdapter;
     /**

package/lib/client/AbstractPowerSyncDatabase.js

@@ -14,6 +14,7 @@ import { CrudEntry } from './sync/bucket/CrudEntry';
 import { CrudTransaction } from './sync/bucket/CrudTransaction';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS } from './sync/stream/AbstractStreamingSyncImplementation';
 import { ControlledExecutor } from '../utils/ControlledExecutor';
+import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -56,9 +57,20 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     _isReadyPromise;
     hasSyncedWatchDisposer;
     _schema;
+    _database;
     constructor(options) {
         super();
         this.options = options;
+        const { database } = options;
+        if (isDBAdapter(database)) {
+            this._database = database;
+        }
+        else if (isSQLOpenFactory(database)) {
+            this._database = database.openDB();
+        }
+        else if (isSQLOpenOptions(database)) {
+            this._database = this.openDBAdapter(database);
+        }
         this.bucketStorageAdapter = this.generateBucketStorageAdapter();
         this.closed = false;
         this.currentStatus = new SyncStatus({});
@@ -81,7 +93,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * For the most part, behavior is the same whether querying on the underlying database, or on {@link AbstractPowerSyncDatabase}.
      */
     get database() {
-        return this.options.database;
+        return this._database;
     }
     /**
      * Whether a connection to the PowerSync service is currently open.
@@ -127,7 +139,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     async initialize() {
         await this._initialize();
         await this.bucketStorageAdapter.init();
-        const version = await this.options.database.execute('SELECT powersync_rs_version()');
+        const version = await this.database.execute('SELECT powersync_rs_version()');
         this.sdkVersion = version.rows?.item(0)['powersync_rs_version()'] ?? '';
         await this.updateSchema(this.options.schema);
         this.updateHasSynced();

package/lib/client/AbstractPowerSyncOpenFactory.d.ts

@@ -1,17 +1,10 @@
 import { DBAdapter } from '../db/DBAdapter';
 import { Schema } from '../db/schema/Schema';
 import { AbstractPowerSyncDatabase, PowerSyncDatabaseOptions } from './AbstractPowerSyncDatabase';
-export interface PowerSyncOpenFactoryOptions extends Partial<PowerSyncDatabaseOptions> {
+import { SQLOpenOptions } from './SQLOpenFactory';
+export interface PowerSyncOpenFactoryOptions extends Partial<PowerSyncDatabaseOptions>, SQLOpenOptions {
     /** Schema used for the local database. */
     schema: Schema;
-    /**
-     * Filename for the database.
-     */
-    dbFilename: string;
-    /**
-     * Directory where the database file is located.
-     */
-    dbLocation?: string;
 }
 export declare abstract class AbstractPowerSyncDatabaseOpenFactory {
     protected options: PowerSyncOpenFactoryOptions;

package/lib/client/SQLOpenFactory.d.ts

@@ -0,0 +1,29 @@
+import { DBAdapter } from '../db/DBAdapter';
+export interface SQLOpenOptions {
+    /**
+     * Filename for the database.
+     */
+    dbFilename: string;
+    /**
+     * Directory where the database file is located.
+     */
+    dbLocation?: string;
+}
+export interface SQLOpenFactory {
+    /**
+     * Opens a connection adapter to a SQLite DB
+     */
+    openDB(): DBAdapter;
+}
+/**
+ * Tests if the input is a {@link SQLOpenOptions}
+ */
+export declare const isSQLOpenOptions: (test: any) => test is SQLOpenOptions;
+/**
+ * Tests if input is a {@link SQLOpenFactory}
+ */
+export declare const isSQLOpenFactory: (test: any) => test is SQLOpenFactory;
+/**
+ * Tests if input is a {@link DBAdapter}
+ */
+export declare const isDBAdapter: (test: any) => test is DBAdapter;

package/lib/client/SQLOpenFactory.js

@@ -0,0 +1,18 @@
+/**
+ * Tests if the input is a {@link SQLOpenOptions}
+ */
+export const isSQLOpenOptions = (test) => {
+    return typeof test == 'object' && 'dbFilename' in test;
+};
+/**
+ * Tests if input is a {@link SQLOpenFactory}
+ */
+export const isSQLOpenFactory = (test) => {
+    return typeof test?.openDB == 'function';
+};
+/**
+ * Tests if input is a {@link DBAdapter}
+ */
+export const isDBAdapter = (test) => {
+    return typeof test?.writeTransaction == 'function';
+};

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 export * from './client/AbstractPowerSyncDatabase';
 export * from './client/AbstractPowerSyncOpenFactory';
+export * from './client/SQLOpenFactory';
 export * from './client/connection/PowerSyncBackendConnector';
 export * from './client/connection/PowerSyncCredentials';
 export * from './client/sync/bucket/BucketStorageAdapter';

package/lib/index.js

@@ -1,5 +1,6 @@
 export * from './client/AbstractPowerSyncDatabase';
 export * from './client/AbstractPowerSyncOpenFactory';
+export * from './client/SQLOpenFactory';
 export * from './client/connection/PowerSyncBackendConnector';
 export * from './client/connection/PowerSyncCredentials';
 export * from './client/sync/bucket/BucketStorageAdapter';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"