@powersync/common 1.12.0 → 1.13.1

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/client/sync/bucket/SyncDataBucket.d.ts

@@ -1,3 +1,4 @@
+import { OpId } from './CrudEntry';
 import { OplogEntry, OplogEntryJSON } from './OplogEntry';
 export type SyncDataBucketJSON = {
     bucket: string;
@@ -17,11 +18,11 @@ export declare class SyncDataBucket {
     /**
      * The `after` specified in the request.
      */
-    after?: string | undefined;
+    after?: OpId | undefined;
     /**
      * Use this for the next request.
      */
-    next_after?: string | undefined;
+    next_after?: OpId | undefined;
     static fromRow(row: SyncDataBucketJSON): SyncDataBucket;
     constructor(bucket: string, data: OplogEntry[], 
     /**
@@ -31,10 +32,10 @@ export declare class SyncDataBucket {
     /**
      * The `after` specified in the request.
      */
-    after?: string | undefined, 
+    after?: OpId | undefined, 
     /**
      * Use this for the next request.
      */
-    next_after?: string | undefined);
+    next_after?: OpId | undefined);
     toJSON(): SyncDataBucketJSON;
 }

package/lib/client/sync/stream/AbstractRemote.js

@@ -180,8 +180,16 @@ export class AbstractRemote {
             socketIsClosed = true;
             rsocket.close();
         };
+        // Helps to prevent double close scenarios
+        rsocket.onClose(() => (socketIsClosed = true));
         // We initially request this amount and expect these to arrive eventually
         let pendingEventsCount = SYNC_QUEUE_REQUEST_N;
+        const disposeClosedListener = stream.registerListener({
+            closed: () => {
+                closeSocket();
+                disposeClosedListener();
+            }
+        });
         const socket = await new Promise((resolve, reject) => {
             let connectionEstablished = false;
             const res = rsocket.requestStream({
@@ -196,9 +204,8 @@ export class AbstractRemote {
                     if (e.message !== 'Closed. ') {
                         this.logger.error(e);
                     }
-                    // RSocket will close this automatically
-                    // Attempting to close multiple times causes a console warning
-                    socketIsClosed = true;
+                    // RSocket will close the RSocket stream automatically
+                    // Close the downstream stream as well - this will close the RSocket connection and WebSocket
                     stream.close();
                     // Handles cases where the connection failed e.g. auth error or connection error
                     if (!connectionEstablished) {
@@ -236,8 +243,7 @@ export class AbstractRemote {
                 }
             },
             closed: () => {
-                closeSocket();
-                l?.();
+                l();
             }
         });
         /**

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.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -20,7 +20,7 @@
   "bugs": {
     "url": "https://github.com/powersync-ja/powersync-js/issues"
   },
-  "homepage": "https://docs.powersync.com/resources/api-reference",
+  "homepage": "https://docs.powersync.com",
   "dependencies": {
     "async-mutex": "^0.4.0",
     "buffer": "^6.0.3",
@@ -36,7 +36,7 @@
     "@types/lodash": "^4.14.197",
     "@types/node": "^20.5.9",
     "@types/uuid": "^9.0.1",
-    "typescript": "^5.1.3",
+    "typescript": "^5.5.3",
     "vitest": "^1.5.2",
     "bson": "^6.6.0"
   },