@powersync/common 0.0.0-dev-20251203144301 → 0.0.0-dev-20260112083235

package/src/client/AbstractPowerSyncDatabase.ts

@@ -38,13 +38,13 @@ import {
   type PowerSyncConnectionOptions,
   type RequiredAdditionalConnectionOptions
 } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { CoreSyncStatus, coreStatusToJs } from './sync/stream/core-instruction.js';
+import { SyncStream } from './sync/sync-streams.js';
 import { TriggerManager } from './triggers/TriggerManager.js';
 import { TriggerManagerImpl } from './triggers/TriggerManagerImpl.js';
 import { DEFAULT_WATCH_THROTTLE_MS, WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 import { WatchedQueryComparator } from './watched/processors/comparators.js';
-import { coreStatusToJs, CoreSyncStatus } from './sync/stream/core-instruction.js';
-import { SyncStream } from './sync/sync-streams.js';
 
 export interface DisconnectAndClearOptions {
   /** When set to false, data in local-only tables is preserved. */
@@ -195,7 +195,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * 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() {
@@ -204,7 +204,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * 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() {
@@ -416,7 +416,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   protected async initialize() {
     await this._initialize();
     await this.bucketStorageAdapter.init();
-    await this._loadVersion();
+    await this.loadVersion();
     await this.updateSchema(this.options.schema);
     await this.resolveOfflineSyncStatus();
     await this.database.execute('PRAGMA RECURSIVE_TRIGGERS=TRUE');
@@ -424,7 +424,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     this.iterateListeners((cb) => cb.initialized?.());
   }
 
-  private async _loadVersion() {
+  protected async loadVersion() {
     try {
       const { version } = await this.database.get<{ version: string }>('SELECT powersync_rs_version() as version');
       this.sdkVersion = version;
@@ -438,13 +438,13 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
         .map((n) => parseInt(n));
     } catch (e) {
       throw new Error(
-        `Unsupported powersync extension version. Need >=0.4.5 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`
+        `Unsupported powersync extension version. Need >=0.4.10 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`
       );
     }
 
-    // Validate >=0.4.5 <1.0.0
-    if (versionInts[0] != 0 || versionInts[1] < 4 || (versionInts[1] == 4 && versionInts[2] < 5)) {
-      throw new Error(`Unsupported powersync extension version. Need >=0.4.5 <1.0.0, got: ${this.sdkVersion}`);
+    // Validate >=0.4.10 <1.0.0
+    if (versionInts[0] != 0 || versionInts[1] < 4 || (versionInts[1] == 4 && versionInts[2] < 10)) {
+      throw new Error(`Unsupported powersync extension version. Need >=0.4.10 <1.0.0, got: ${this.sdkVersion}`);
     }
   }
 

package/src/client/sync/stream/AbstractStreamingSyncImplementation.ts

@@ -129,6 +129,11 @@ export interface InternalConnectionOptions extends BaseConnectionOptions, Additi
 
 /** @internal */
 export interface BaseConnectionOptions {
+  /**
+   * A set of metadata to be included in service logs.
+   */
+  appMetadata?: Record<string, string>;
+
   /**
    * Whether to use a JavaScript implementation to handle received sync lines from the sync
    * service, or whether this work should be offloaded to the PowerSync core extension.
@@ -223,6 +228,7 @@ export const DEFAULT_STREAMING_SYNC_OPTIONS = {
 export type RequiredPowerSyncConnectionOptions = Required<BaseConnectionOptions>;
 
 export const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptions = {
+  appMetadata: {},
   connectionMethod: SyncStreamConnectionMethod.WEB_SOCKET,
   clientImplementation: DEFAULT_SYNC_CLIENT_IMPLEMENTATION,
   fetchStrategy: FetchStrategy.Buffered,
@@ -658,6 +664,16 @@ The next upload iteration will be delayed.`);
           ...DEFAULT_STREAM_CONNECTION_OPTIONS,
           ...(options ?? {})
         };
+
+        // Validate app metadata
+        const invalidMetadata = Object.entries(resolvedOptions.appMetadata).filter(
+          ([_, value]) => typeof value != 'string'
+        );
+        if (invalidMetadata.length > 0) {
+          throw new Error(
+            `Invalid appMetadata provided. Only string values are allowed. Invalid values: ${invalidMetadata.map(([key, value]) => `${key}: ${value}`).join(', ')}`
+          );
+        }
         const clientImplementation = resolvedOptions.clientImplementation;
         this.updateSyncStatus({ clientImplementation });
 
@@ -699,6 +715,7 @@ The next upload iteration will be delayed.`);
         include_checksum: true,
         raw_data: true,
         parameters: resolvedOptions.params,
+        app_metadata: resolvedOptions.appMetadata,
         client_id: clientId
       }
     };
@@ -1088,6 +1105,7 @@ The next upload iteration will be delayed.`);
     try {
       const options: any = {
         parameters: resolvedOptions.params,
+        app_metadata: resolvedOptions.appMetadata,
         active_streams: this.activeStreams,
         include_defaults: resolvedOptions.includeDefaultStreams
       };

package/src/client/sync/stream/streaming-sync-types.ts

@@ -90,6 +90,11 @@ export interface StreamingSyncRequest {
    */
   parameters?: Record<string, StreamingSyncRequestParameterType>;
 
+  /**
+   * Application metadata to be included in service logs.
+   */
+  app_metadata?: Record<string, string>;
+
   client_id?: string;
 }
 

package/src/db/ConnectionClosedError.ts

@@ -0,0 +1,23 @@
+/**
+ * Thrown when an underlying database connection is closed.
+ * This is particularly relevant when worker connections are marked as closed while
+ * operations are still in progress.
+ */
+export class ConnectionClosedError extends Error {
+  static NAME = 'ConnectionClosedError';
+
+  static MATCHES(input: any) {
+    /**
+     * If there are weird package issues which cause multiple versions of classes to be present, the instanceof
+     * check might fail. This also performs a failsafe check.
+     * This might also happen if the Error is serialized and parsed over a bridging channel like a MessagePort.
+     */
+    return (
+      input instanceof ConnectionClosedError || (input instanceof Error && input.name == ConnectionClosedError.NAME)
+    );
+  }
+  constructor(message: string) {
+    super(message);
+    this.name = ConnectionClosedError.NAME;
+  }
+}

package/src/db/crud/SyncStatus.ts

@@ -261,6 +261,10 @@ export class SyncStatus {
     };
   }
 
+  /**
+   * Not all errors are serializable over a MessagePort. E.g. some `DomExceptions` fail to be passed across workers. 
+   * This explicitly serializes errors in the SyncStatus.
+   */
   protected serializeError(error?: Error) {
     if (typeof error == 'undefined') {
       return undefined;

package/src/index.ts

@@ -21,6 +21,7 @@ export * from './client/sync/stream/streaming-sync-types.js';
 export * from './client/sync/sync-streams.js';
 
 export * from './client/ConnectionManager.js';
+export * from './db/ConnectionClosedError.js';
 export { ProgressWithOperations, SyncProgress } from './db/crud/SyncProgress.js';
 export * from './db/crud/SyncStatus.js';
 export * from './db/crud/UploadQueueStatus.js';