@powersync/common 1.11.1 → 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/client/sync/stream/AbstractStreamingSyncImplementation.d.ts

@@ -1,4 +1,5 @@
 import { ILogger } from 'js-logger';
+import { StreamingSyncRequestParameterType } from './streaming-sync-types';
 import { AbstractRemote } from './AbstractRemote';
 import { BucketStorageAdapter } from '../bucket/BucketStorageAdapter';
 import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus';
@@ -54,6 +55,10 @@ export interface PowerSyncConnectionOptions {
      * Defaults to a HTTP streaming connection.
      */
     connectionMethod?: SyncStreamConnectionMethod;
+    /**
+     * These parameters are passed to the sync rules, and will be available under the`user_parameters` object.
+     */
+    params?: Record<string, StreamingSyncRequestParameterType>;
 }
 export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener>, Disposable {
     /**

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

@@ -22,7 +22,8 @@ export const DEFAULT_STREAMING_SYNC_OPTIONS = {
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
 export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
-    connectionMethod: SyncStreamConnectionMethod.HTTP
+    connectionMethod: SyncStreamConnectionMethod.HTTP,
+    params: {}
 };
 export class AbstractStreamingSyncImplementation extends BaseObserver {
     _lastSyncedAt;
@@ -315,7 +316,8 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
                     data: {
                         buckets: req,
                         include_checksum: true,
-                        raw_data: true
+                        raw_data: true,
+                        parameters: resolvedOptions.params
                     }
                 };
                 const stream = resolvedOptions?.connectionMethod == SyncStreamConnectionMethod.HTTP

package/lib/client/sync/stream/streaming-sync-types.d.ts

@@ -42,6 +42,12 @@ export interface SyncResponse {
     checkpoint_token?: string;
     checkpoint?: Checkpoint;
 }
+type JSONValue = string | number | boolean | null | undefined | JSONObject | JSONArray;
+interface JSONObject {
+    [key: string]: JSONValue;
+}
+type JSONArray = JSONValue[];
+export type StreamingSyncRequestParameterType = JSONValue;
 export interface StreamingSyncRequest {
     /**
      * Existing bucket states.
@@ -59,6 +65,10 @@ export interface StreamingSyncRequest {
      * Changes the response to stringified data in each OplogEntry
      */
     raw_data: boolean;
+    /**
+     * Client parameters to be passed to the sync rules.
+     */
+    parameters?: Record<string, StreamingSyncRequestParameterType>;
 }
 export interface StreamingSyncCheckpoint {
     checkpoint: Checkpoint;
@@ -114,3 +124,4 @@ export interface CrudResponse {
      */
     checkpoint?: OpId;
 }
+export {};

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.11.1",
+  "version": "1.13.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"