@powersync/node 0.0.0-dev-20260503073249 → 0.0.0-dev-20260630141119

package/src/db/PowerSyncDatabase.ts

@@ -1,91 +1,59 @@
 import {
-  AbstractPowerSyncDatabase,
-  AbstractRemoteOptions,
-  AbstractStreamingSyncImplementation,
-  AdditionalConnectionOptions,
-  BucketStorageAdapter,
+  BasePowerSyncDatabaseOptions,
+  CommonPowerSyncDatabase,
+  DatabaseSource,
   DBAdapter,
   PowerSyncBackendConnector,
-  PowerSyncConnectionOptions,
-  PowerSyncDatabaseOptions,
-  PowerSyncDatabaseOptionsWithSettings,
-  RequiredAdditionalConnectionOptions,
-  SqliteBucketStorage,
-  SQLOpenFactory
+  PowerSyncDatabaseConstructor
 } from '@powersync/common';
+import {
+  BasePowerSyncDatabase,
+  AbstractStreamingSyncImplementation,
+  BucketStorageAdapter,
+  CreateSyncImplementationOptions,
+  SqliteBucketStorage,
+  openDatabase
+} from '@powersync/shared-internals';
 
-import { NodeCustomConnectionOptions, NodeRemote } from '../sync/stream/NodeRemote.js';
+import { NodeRemote, NodeRemoteOptions } from '../sync/stream/NodeRemote.js';
 import { NodeStreamingSyncImplementation } from '../sync/stream/NodeStreamingSyncImplementation.js';
 
-import { WorkerPoolDatabaseAdapter } from './WorkerConnectionPool.js';
+import { WorkerConnectionPool } from './WorkerConnectionPool.js';
 import { NodeSQLOpenOptions } from './options.js';
 
-export type NodePowerSyncDatabaseOptions = PowerSyncDatabaseOptions & {
-  database: DBAdapter | SQLOpenFactory | NodeSQLOpenOptions;
-  /**
-   * Options to override how the SDK will connect to the sync service.
-   *
-   * This option is intended to be used for internal tests.
-   */
-  remoteOptions?: Partial<AbstractRemoteOptions>;
-};
-
-export type NodeAdditionalConnectionOptions = AdditionalConnectionOptions & NodeCustomConnectionOptions;
-
-export type NodePowerSyncConnectionOptions = PowerSyncConnectionOptions & NodeAdditionalConnectionOptions;
+export type NodePowerSyncDatabaseOptions = BasePowerSyncDatabaseOptions &
+  DatabaseSource<NodeSQLOpenOptions> & {
+    /**
+     * Options to override how the SDK will connect to the sync service.
+     */
+    remoteOptions?: NodeRemoteOptions;
+  };
 
-/**
- * A PowerSync database which provides SQLite functionality
- * which is automatically synced.
- *
- * @example
- * ```typescript
- * export const db = new PowerSyncDatabase({
- *  schema: AppSchema,
- *  database: {
- *    dbFilename: 'example.db'
- *  }
- * });
- * ```
- */
-export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
+class NodePowerSyncDatabase extends BasePowerSyncDatabase<NodePowerSyncDatabaseOptions> {
   constructor(options: NodePowerSyncDatabaseOptions) {
     super(options);
   }
 
   async _initialize(): Promise<void> {
     if ('initialize' in this.database) {
-      await (this.database as WorkerPoolDatabaseAdapter).initialize();
+      await (this.database as WorkerConnectionPool).initialize();
     }
   }
 
-  /**
-   * Opens a DBAdapter using better-sqlite3 as the default SQLite open factory.
-   */
-  protected openDBAdapter(options: PowerSyncDatabaseOptionsWithSettings): DBAdapter {
-    return new WorkerPoolDatabaseAdapter(options.database);
+  protected openDBAdapter(): DBAdapter {
+    return openDatabase(this.options, (open) => new WorkerConnectionPool(open));
   }
 
   protected generateBucketStorageAdapter(): BucketStorageAdapter {
     return new SqliteBucketStorage(this.database, this.logger);
   }
 
-  connect(
-    connector: PowerSyncBackendConnector,
-    options?: PowerSyncConnectionOptions & NodeCustomConnectionOptions
-  ): Promise<void> {
-    return super.connect(connector, options);
-  }
-
   protected generateSyncStreamImplementation(
     connector: PowerSyncBackendConnector,
-    options: RequiredAdditionalConnectionOptions & NodeAdditionalConnectionOptions
+    options: CreateSyncImplementationOptions
   ): AbstractStreamingSyncImplementation {
     const logger = this.logger;
-    const remote = new NodeRemote(connector, logger, {
-      dispatcher: options.dispatcher,
-      ...(this.options as NodePowerSyncDatabaseOptions).remoteOptions
-    });
+    const remote = new NodeRemote(connector, logger, this.options.remoteOptions);
 
     return new NodeStreamingSyncImplementation({
       adapter: this.bucketStorageAdapter,
@@ -100,3 +68,22 @@ export class PowerSyncDatabase extends AbstractPowerSyncDatabase {
     });
   }
 }
+
+/**
+ * A PowerSync database which provides SQLite functionality
+ * which is automatically synced.
+ *
+ * @example
+ * ```typescript
+ * export const db = new PowerSyncDatabase({
+ *  schema: AppSchema,
+ *  database: {
+ *    dbFilename: 'example.db'
+ *  }
+ * });
+ * ```
+ */
+// Typed constructor to avoid leaking AbstractPowerSyncDatabase into the public interface
+export const PowerSyncDatabase: PowerSyncDatabaseConstructor<NodePowerSyncDatabaseOptions> = NodePowerSyncDatabase;
+
+export interface PowerSyncDatabase extends CommonPowerSyncDatabase {}

package/src/db/RemoteConnection.ts

@@ -1,18 +1,13 @@
-import {
-  ConnectionClosedError,
-  DBGetUtilsDefaultMixin,
-  QueryResult,
-  SqlExecutor,
-  LockContext
-} from '@powersync/common';
+import { QueryResult, LockContext, RawQueryResult, SqliteRecord, queryResultFromMapped } from '@powersync/common';
 import { releaseProxy, Remote } from 'comlink';
 import { Worker } from 'node:worker_threads';
-import { AsyncDatabase, AsyncDatabaseOpener, ProxiedQueryResult } from './AsyncDatabase.js';
+import { AsyncDatabase, AsyncDatabaseOpener } from './AsyncDatabase.js';
+import { ConnectionClosedError } from '@powersync/shared-internals';
 
 /**
  * A PowerSync database connection implemented with RPC calls to a background worker.
  */
-class BaseRemoteConnection implements SqlExecutor {
+export class RemoteConnection extends LockContext {
   private readonly worker: Worker;
   private readonly comlink: Remote<AsyncDatabaseOpener>;
   private readonly database: Remote<AsyncDatabase>;
@@ -20,6 +15,7 @@ class BaseRemoteConnection implements SqlExecutor {
   private readonly notifyWorkerClosed = new AbortController();
 
   constructor(worker: Worker, comlink: Remote<AsyncDatabaseOpener>, database: Remote<AsyncDatabase>) {
+    super();
     this.worker = worker;
     this.comlink = comlink;
     this.database = database;
@@ -66,28 +62,27 @@ class BaseRemoteConnection implements SqlExecutor {
     });
   }
 
-  executeBatch(query: string, params: any[][] = []): Promise<QueryResult> {
+  execute<T = SqliteRecord>(query: string, params?: any[] | undefined): Promise<QueryResult<T>> {
     return this.withRemote(async () => {
-      const result = await this.database.executeBatch(query, params ?? []);
-      return BaseRemoteConnection.wrapQueryResult(result);
+      const results = await this.database.execute(query, params ?? []);
+      return queryResultFromMapped(results, results.rows as T[] | undefined);
     });
   }
 
-  execute(query: string, params?: any[] | undefined): Promise<QueryResult> {
+  executeBatch(query: string, params: any[][] = []): Promise<QueryResult<never>> {
     return this.withRemote(async () => {
-      const result = await this.database.execute(query, params ?? []);
-      return BaseRemoteConnection.wrapQueryResult(result);
+      return await this.database.executeBatch(query, params ?? []);
     });
   }
 
-  executeRaw(query: string, params?: any[] | undefined): Promise<any[][]> {
+  executeRaw(query: string, params?: any[] | undefined): Promise<RawQueryResult> {
     return this.withRemote(async () => {
       return await this.database.executeRaw(query, params ?? []);
     });
   }
 
   async refreshSchema() {
-    await this.execute("pragma table_info('sqlite_master')");
+    await this.executeRaw("pragma table_info('sqlite_master')");
   }
 
   async close() {
@@ -96,21 +91,4 @@ class BaseRemoteConnection implements SqlExecutor {
     this.comlink[releaseProxy]();
     await this.worker.terminate();
   }
-
-  static wrapQueryResult(result: ProxiedQueryResult): QueryResult {
-    let rows: QueryResult['rows'] | undefined = undefined;
-    if (result.rows) {
-      rows = {
-        ...result.rows,
-        item: (idx) => result.rows?._array[idx]
-      } satisfies QueryResult['rows'];
-    }
-
-    return {
-      ...result,
-      rows
-    };
-  }
 }
-
-export class RemoteConnection extends DBGetUtilsDefaultMixin(BaseRemoteConnection) implements LockContext {}

package/src/db/SqliteWorker.ts

@@ -1,9 +1,7 @@
 import * as Comlink from 'comlink';
 import OS from 'node:os';
-import * as path from 'node:path';
 import url from 'node:url';
 import { parentPort } from 'node:worker_threads';
-import { dynamicImport, isBundledToCommonJs } from '../utils/modules.js';
 import { AsyncDatabase, AsyncDatabaseOpenOptions, AsyncDatabaseOpener } from './AsyncDatabase.js';
 import { openDatabase as openBetterSqliteDatabase } from './BetterSqliteWorker.js';
 import { openDatabase as openNodeDatabase } from './NodeSqliteWorker.js';
@@ -71,21 +69,13 @@ export function getPowerSyncExtensionFilename() {
 export function startPowerSyncWorker(options?: Partial<PowerSyncWorkerOptions>) {
   const resolvedOptions: PowerSyncWorkerOptions = {
     extensionPath() {
-      const isCommonJsModule = isBundledToCommonJs;
       const extensionFilename = getPowerSyncExtensionFilename();
-      let resolved: string;
-      if (isCommonJsModule) {
-        resolved = path.resolve(__dirname, '../lib/', extensionFilename);
-      } else {
-        resolved = url.fileURLToPath(new URL(`../${extensionFilename}`, import.meta.url));
-      }
-
+      const resolved = url.fileURLToPath(new URL(`../${extensionFilename}`, import.meta.url));
       return resolved;
     },
     async loadBetterSqlite3() {
-      const module = await dynamicImport('better-sqlite3');
-      // require() gives us the default directly, for an ESM import() we need to use the default export.
-      return isBundledToCommonJs ? module : module.default;
+      const module = await import('better-sqlite3');
+      return module.default;
     },
     ...options
   };

package/src/db/WorkerConnectionPool.ts

@@ -4,20 +4,15 @@ import * as path from 'node:path';
 import { Worker } from 'node:worker_threads';
 
 import {
-  BaseObserver,
   BatchedUpdateNotification,
-  ConnectionPool,
-  DBAdapterDefaultMixin,
-  DBAdapterListener,
+  DBAdapter,
   DBLockOptions,
   LockContext,
   QueryResult,
-  Semaphore,
-  timeoutSignal,
   Transaction
 } from '@powersync/common';
+import { Semaphore, timeoutSignal } from '@powersync/shared-internals';
 import { Remote } from 'comlink';
-import { isBundledToCommonJs } from '../utils/modules.js';
 import { AsyncDatabase, AsyncDatabaseOpener } from './AsyncDatabase.js';
 import { RemoteConnection } from './RemoteConnection.js';
 import { NodeDatabaseImplementation, NodeSQLOpenOptions } from './options.js';
@@ -37,12 +32,12 @@ const defaultDatabaseImplementation: NodeDatabaseImplementation = {
 /**
  * Adapter for better-sqlite3
  */
-export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implements ConnectionPool {
+export class WorkerConnectionPool extends DBAdapter {
   private readonly options: NodeSQLOpenOptions;
   public readonly name: string;
 
-  private writeConnection: Semaphore<RemoteConnection>;
-  private readConnections: Semaphore<RemoteConnection>;
+  private writeConnection?: Semaphore<RemoteConnection>;
+  private readConnections?: Semaphore<RemoteConnection>;
 
   constructor(options: NodeSQLOpenOptions) {
     super();
@@ -77,21 +72,15 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
     }
 
     const openWorker = async (isWriter: boolean) => {
-      const isCommonJsModule = isBundledToCommonJs;
-      let worker: Worker;
       const workerName = isWriter ? `write ${dbFilePath}` : `read ${dbFilePath}`;
 
       const workerFactory = this.options.openWorker ?? ((...args) => new Worker(...args));
-      if (isCommonJsModule) {
-        worker = workerFactory(path.resolve(__dirname, 'DefaultWorker.cjs'), { name: workerName });
-      } else {
-        worker = workerFactory(new URL('./DefaultWorker.js', import.meta.url), { name: workerName });
-      }
+      const worker = workerFactory(new URL('./DefaultWorker.js', import.meta.url), { name: workerName });
 
       const listeners = new WeakMap<EventListenerOrEventListenerObject, (e: any) => void>();
 
       const comlink = Comlink.wrap<AsyncDatabaseOpener>({
-        postMessage: worker.postMessage.bind(worker),
+        postMessage: worker.postMessage.bind(worker) as any,
         addEventListener: (type, listener) => {
           let resolved: (event: any) => void =
             'handleEvent' in listener ? listener.handleEvent.bind(listener) : listener;
@@ -127,16 +116,14 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
         implementation: this.options.implementation ?? defaultDatabaseImplementation
       })) as Remote<AsyncDatabase>;
       if (isWriter) {
-        await database.execute("SELECT powersync_update_hooks('install');", []);
+        await database.executeRaw("SELECT powersync_update_hooks('install');", []);
       }
 
       const connection = new RemoteConnection(worker, comlink, database);
       if (this.options.initializeConnection) {
         await this.options.initializeConnection(connection, isWriter);
       }
-      if (!isWriter) {
-        await connection.execute('pragma query_only = true');
-      } else {
+      if (isWriter) {
         // We only need to enable this on the writer connection.
         // We can get `database is locked` errors if we enable this on concurrently opening read connections.
         await connection.execute('pragma journal_mode = WAL');
@@ -156,8 +143,8 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
   }
 
   async close() {
-    const { item: writeConnection, release: returnWrite } = await this.writeConnection.requestOne();
-    const { items: readers, release: returnReaders } = await this.readConnections.requestAll();
+    const { item: writeConnection, release: returnWrite } = await this.writeConnection!.requestOne();
+    const { items: readers, release: returnReaders } = await this.readConnections!.requestAll();
 
     try {
       await writeConnection.close();
@@ -169,7 +156,7 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
   }
 
   async readLock<T>(fn: (tx: RemoteConnection) => Promise<T>, options?: DBLockOptions | undefined): Promise<T> {
-    const lease = await this.readConnections.requestOne(timeoutSignal(options?.timeoutMs));
+    const lease = await this.readConnections!.requestOne(timeoutSignal(options?.timeoutMs));
     try {
       return await fn(lease.item);
     } finally {
@@ -178,20 +165,18 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
   }
 
   async writeLock<T>(fn: (tx: RemoteConnection) => Promise<T>, options?: DBLockOptions | undefined): Promise<T> {
-    const { item, release } = await this.writeConnection.requestOne(timeoutSignal(options?.timeoutMs));
+    const { item, release } = await this.writeConnection!.requestOne(timeoutSignal(options?.timeoutMs));
 
     try {
       try {
         return await fn(item);
       } finally {
-        const serializedUpdates = await item.executeRaw("SELECT powersync_update_hooks('get');", []);
+        const { rawRows: serializedUpdates } = await item.executeRaw("SELECT powersync_update_hooks('get');", []);
         const updates = JSON.parse(serializedUpdates[0][0] as string) as string[];
 
         if (updates.length > 0) {
           const event: BatchedUpdateNotification = {
-            tables: updates,
-            groupedUpdates: {},
-            rawUpdates: []
+            tables: updates
           };
           this.iterateListeners((cb) => cb.tablesUpdated?.(event));
         }
@@ -204,7 +189,7 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
   async refreshSchema() {
     await this.writeLock((l) => l.refreshSchema());
 
-    const { items, release } = await this.readConnections.requestAll();
+    const { items, release } = await this.readConnections!.requestAll();
     try {
       await Promise.all(items.map((c) => c.refreshSchema()));
     } finally {
@@ -212,5 +197,3 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
     }
   }
 }
-
-export class WorkerPoolDatabaseAdapter extends DBAdapterDefaultMixin(WorkerConnectionPool) {}

package/src/index.ts

@@ -2,5 +2,6 @@
 export * from '@powersync/common';
 
 export * from './db/PowerSyncDatabase.js';
+export * from './db/options.js';
 
-export * from './attachments/NodeFileSystemAdapter.js';
+export * from './attachments/NodeFileSystemAdapter.js';

package/src/sync/stream/NodeRemote.ts

@@ -1,34 +1,18 @@
 import * as os from 'node:os';
 
-import {
-  type ILogger,
-  AbstractRemote,
-  AbstractRemoteOptions,
-  BSONImplementation,
-  DEFAULT_REMOTE_LOGGER,
-  FetchImplementation,
-  FetchImplementationProvider,
-  RemoteConnector
-} from '@powersync/common';
-import { BSON } from 'bson';
-import {
-  Dispatcher,
-  EnvHttpProxyAgent,
-  ErrorEvent,
-  getGlobalDispatcher,
-  ProxyAgent,
-  WebSocket as UndiciWebSocket
-} from 'undici';
+import { AbstractRemote, FetchOptions, RemoteConnector } from '@powersync/shared-internals';
+import { Dispatcher, EnvHttpProxyAgent, getGlobalDispatcher, ProxyAgent, WebSocket as UndiciWebSocket } from 'undici';
+import { PowerSyncLogger } from '@powersync/common';
+import type { WebSocketSyncStreamPlatform, WebSocketSupport } from '@powersync/shared-internals/websockets';
 
 export const STREAMING_POST_TIMEOUT_MS = 30_000;
 
-class NodeFetchProvider extends FetchImplementationProvider {
-  getFetch(): FetchImplementation {
-    return fetch.bind(globalThis);
-  }
-}
+export interface NodeRemoteOptions {
+  /**
+   * @internal Only meant to be used for tests.
+   */
+  customFetch?: typeof fetch;
 
-export type NodeCustomConnectionOptions = {
   /**
    * Optional custom dispatcher for HTTP or WEB_SOCKET connections.
    *
@@ -36,32 +20,49 @@ export type NodeCustomConnectionOptions = {
    * or other connection options.
    */
   dispatcher?: Dispatcher;
-};
-
-export type NodeRemoteOptions = AbstractRemoteOptions & NodeCustomConnectionOptions;
+}
 
 export class NodeRemote extends AbstractRemote {
   private wsDispatcher: Dispatcher | undefined;
+  private fetchImpl: typeof fetch;
 
   constructor(
     protected connector: RemoteConnector,
-    protected logger: ILogger = DEFAULT_REMOTE_LOGGER,
-    options?: Partial<NodeRemoteOptions>
+    logger: PowerSyncLogger,
+    options?: NodeRemoteOptions
   ) {
-    const fetchDispatcher = options?.dispatcher ?? defaultFetchDispatcher();
-
-    super(connector, logger, {
-      fetchImplementation: options?.fetchImplementation ?? new NodeFetchProvider(),
-      fetchOptions: {
-        dispatcher: fetchDispatcher
-      },
-      ...(options ?? {})
-    });
+    super(connector, logger);
+
+    this.fetchImpl =
+      options?.customFetch ??
+      ((resource, init) => {
+        const dispatcher = options?.dispatcher ?? defaultFetchDispatcher();
+
+        return fetch(resource, {
+          // @ts-expect-error
+          dispatcher,
+          ...init
+        });
+      });
 
     this.wsDispatcher = options?.dispatcher;
   }
 
-  protected createSocket(url: string): globalThis.WebSocket {
+  protected fetch({ resource, request }: FetchOptions): Promise<Response> {
+    return this.fetchImpl(resource, request);
+  }
+
+  protected async loadWebSocketSupport(platform: WebSocketSyncStreamPlatform): Promise<WebSocketSupport> {
+    if (!websockets) {
+      // loadWebSocketSupport being called concurrently is safe, the import resolves to the same module in that case.
+      const module = await import('@powersync/shared-internals/websockets');
+      websockets = new module.WebSocketSupport(platform);
+    }
+
+    return websockets;
+  }
+
+  createSocket(url: string): globalThis.WebSocket {
     // Create dedicated dispatcher for this WebSocket
     const baseDispatcher = this.getWebsocketDispatcher(url);
 
@@ -98,10 +99,6 @@ export class NodeRemote extends AbstractRemote {
       `${os.platform()}/${os.release()}`
     ].join(' ');
   }
-
-  async getBSON(): Promise<BSONImplementation> {
-    return BSON;
-  }
 }
 
 function defaultFetchDispatcher(): Dispatcher {
@@ -121,3 +118,5 @@ function getProxyForProtocol(protocol: string): string | undefined {
     process.env[`ALL_PROXY`]
   );
 }
+
+let websockets: WebSocketSupport | undefined;

package/src/sync/stream/NodeStreamingSyncImplementation.ts

@@ -4,7 +4,7 @@ import {
   LockOptions,
   LockType,
   Mutex
-} from '@powersync/common';
+} from '@powersync/shared-internals';
 
 /**
  * Global locks which prevent multiple instances from syncing
@@ -13,7 +13,7 @@ import {
 const LOCKS = new Map<string, Map<LockType, Mutex>>();
 
 export class NodeStreamingSyncImplementation extends AbstractStreamingSyncImplementation {
-  locks: Map<LockType, Mutex>;
+  locks!: Map<LockType, Mutex>; // initialized by initLocks()
 
   constructor(options: AbstractStreamingSyncImplementationOptions) {
     super(options);