@powersync/common 1.57.1 → 2.0.0

package/src/db/QueryResult.ts

@@ -0,0 +1,195 @@
+/**
+ * A SQLite value, either text, a number, a blob value or null.
+ *
+ * @public
+ */
+export type SqliteValue = string | number | bigint | number[] | Uint8Array | null;
+
+/**
+ * A record of SQLite values representing a row.
+ *
+ * @public
+ */
+export type SqliteRecord = Record<string, SqliteValue>;
+
+/**
+ * A representation of query results as JavaScript object.
+ *
+ * @public
+ */
+export interface ResultSet {
+  /**
+   * The amount of rows in the result set.
+   */
+  get length(): number;
+
+  /**
+   * @deprecated Use {@link QueryResult.array} instead.
+   */
+  get _array(): any[];
+
+  /**
+   * @deprecated Use {@link QueryResult.array} instead.
+   */
+  item<T>(idx: number): T;
+}
+
+/**
+ * Shared superinterface for {@link QueryResult} and {@link RawQueryResult}.
+ *
+ * @public
+ */
+export interface BaseQueryResult {
+  /** Represents the auto-generated row id if applicable. */
+  insertId?: number;
+  /**
+   * Number of affected rows reported by SQLite for a write query.
+   *
+   * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
+   * `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
+   * Use a `RETURNING` clause and inspect `rows` when you need to confirm which rows changed.
+   */
+  rowsAffected?: number;
+}
+
+/**
+ * Object returned by SQL Query executions.
+ *
+ * @public
+ */
+export interface QueryResult<T = SqliteRecord> extends BaseQueryResult, Iterable<T, undefined> {
+  /**
+   * If the query returned rows, the result set containing returned values.
+   */
+  rows?: ResultSet;
+  /**
+   * Rows in this result set.
+   */
+  array: T[];
+}
+
+/**
+ * A raw array-based result set representing rows returned by SQLite.
+ *
+ * @public
+ */
+export interface RawQueryResult extends BaseQueryResult {
+  /**
+   * Names of columns in this result set. Every column has a name, so the length of this array is always equal to the
+   * amount of columns in the result set.
+   *
+   * Note that column names are not necessarily unique, e.g. a `SELECT foo.user, bar.user FROM ...` will have
+   * `['user', 'user']` in this array.
+   */
+  columnNames: string[];
+
+  /**
+   * Rows in the result set.
+   *
+   * Each row has a length equal to {@link RawQueryResult.columnNames}.
+   */
+  rawRows: SqliteValue[][];
+}
+
+function rowToRecord<T>(columnNames: string[], row: SqliteValue[]) {
+  const record: SqliteRecord = {};
+  columnNames.forEach((name, idx) => (record[name] = row[idx]));
+  return record as T;
+}
+
+/**
+ * Creates a query result by mapping raw rows to JavaScript.
+ *
+ * This should not be used with libraries doing this mapping natively, as that is typically more performant.
+ *
+ * @public
+ */
+export function queryResultFromRaw<T>(raw: RawQueryResult): QueryResult<T> {
+  const { insertId, rowsAffected, columnNames, rawRows } = raw;
+  let array: any[] | undefined;
+
+  function loadAsArray() {
+    if (array) return array;
+
+    return (array = rawRows.map((row) => rowToRecord(columnNames, row)));
+  }
+
+  function getRow<T>(idx: number) {
+    if (array) return array[idx];
+    return rowToRecord(columnNames, rawRows[idx]);
+  }
+
+  return {
+    insertId,
+    rowsAffected,
+    get array() {
+      return loadAsArray();
+    },
+    rows: {
+      length: rawRows.length,
+      get _array() {
+        return loadAsArray();
+      },
+      item: getRow
+    } satisfies ResultSet,
+    [Symbol.iterator](): Iterator<T> {
+      let nextIndex = 0;
+
+      return {
+        next: function (): IteratorResult<T, any> {
+          if (nextIndex >= rawRows.length) {
+            return { done: true, value: undefined };
+          }
+
+          const row = getRow(nextIndex);
+          nextIndex++;
+          return { done: false, value: row };
+        }
+      };
+    }
+  };
+}
+
+/**
+ * Creates a query result from rows that have already been mapped to JavaScript.
+ *
+ * @public
+ */
+export function queryResultFromMapped<T>(base: BaseQueryResult, rows?: T[]): QueryResult<T> {
+  if (rows == null) return queryResultWithoutRows(base);
+
+  return {
+    insertId: base.insertId,
+    rowsAffected: base.rowsAffected,
+    array: rows ?? [],
+    rows: {
+      length: rows.length,
+      _array: rows,
+      item(i: number) {
+        return rows[i] as any;
+      }
+    } satisfies ResultSet,
+    [Symbol.iterator](): Iterator<T> {
+      return rows[Symbol.iterator]();
+    }
+  };
+}
+
+/**
+ * Creates a {@link QueryResult} not containing any rows.
+ *
+ * @public
+ */
+export function queryResultWithoutRows(result: BaseQueryResult): QueryResult<never> {
+  return {
+    ...result,
+    array: [],
+    [Symbol.iterator](): Iterator<never> {
+      return {
+        next() {
+          return { done: true, value: undefined };
+        }
+      };
+    }
+  };
+}

package/src/db/crud/SyncProgress.ts

@@ -1,15 +1,5 @@
-import type { BucketProgress } from '../../client/sync/stream/core-instruction.js';
 import type { SyncStatus } from './SyncStatus.js';
 
-// (bucket, progress) pairs
-/** @internal */
-export type InternalProgressInformation = Record<string, BucketProgress>;
-
-/**
- * @internal The priority used by the core extension to indicate that a full sync was completed.
- */
-export const FULL_SYNC_PRIORITY = 2147483647;
-
 /**
  * Information about a progressing download made by the PowerSync SDK.
  *
@@ -64,42 +54,12 @@ export interface ProgressWithOperations {
  *
  * @public
  */
-export class SyncProgress implements ProgressWithOperations {
-  totalOperations: number;
-  downloadedOperations: number;
-  downloadedFraction: number;
-
-  constructor(protected internal: InternalProgressInformation) {
-    const untilCompletion = this.untilPriority(FULL_SYNC_PRIORITY);
-
-    this.totalOperations = untilCompletion.totalOperations;
-    this.downloadedOperations = untilCompletion.downloadedOperations;
-    this.downloadedFraction = untilCompletion.downloadedFraction;
-  }
-
+export interface SyncProgress extends ProgressWithOperations {
   /**
    * Returns download progress towards all data up until the specified priority being received.
    *
    * The returned {@link ProgressWithOperations} tracks the target amount of operations that need
    * to be downloaded in total and how many of them have already been received.
    */
-  untilPriority(priority: number): ProgressWithOperations {
-    let total = 0;
-    let downloaded = 0;
-
-    for (const progress of Object.values(this.internal)) {
-      // Include higher-priority buckets, which are represented by lower numbers.
-      if (progress.priority <= priority) {
-        downloaded += progress.since_last;
-        total += progress.target_count - progress.at_last;
-      }
-    }
-
-    let progress = total == 0 ? 0.0 : downloaded / total;
-    return {
-      totalOperations: total,
-      downloadedOperations: downloaded,
-      downloadedFraction: progress
-    };
-  }
+  untilPriority(priority: number): ProgressWithOperations;
 }

package/src/db/crud/SyncStatus.ts

@@ -1,12 +1,11 @@
-import { SyncClientImplementation } from '../../client/sync/stream/AbstractStreamingSyncImplementation.js';
-import { CoreStreamSubscription } from '../../client/sync/stream/core-instruction.js';
 import { SyncStreamDescription, SyncSubscriptionDescription } from '../../client/sync/sync-streams.js';
-import { InternalProgressInformation, ProgressWithOperations, SyncProgress } from './SyncProgress.js';
+import { ProgressWithOperations, SyncProgress } from './SyncProgress.js';
 
 /**
  * @public
+ * @deprecated All fields are available on {@link SyncStatus} directly.
  */
-export type SyncDataFlowStatus = Partial<{
+export interface SyncDataFlowStatus {
   downloading: boolean;
   uploading: boolean;
   /**
@@ -20,17 +19,7 @@ export type SyncDataFlowStatus = Partial<{
    * Cleared on the next successful upload.
    */
   uploadError?: Error;
-  /**
-   * Internal information about how far we are downloading operations in buckets.
-   *
-   * @internal Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
-   */
-  downloadProgress: InternalProgressInformation | null;
-  /**
-   * @internal
-   */
-  internalStreamSubscriptions: CoreStreamSubscription[] | null;
-}>;
+}
 
 /**
  * @public
@@ -42,56 +31,51 @@ export interface SyncPriorityStatus {
 }
 
 /**
- * @internal
+ * @public
  */
-export type SyncStatusOptions = {
-  connected?: boolean;
-  connecting?: boolean;
-  dataFlow?: SyncDataFlowStatus;
-  lastSyncedAt?: Date;
-  hasSynced?: boolean;
-  priorityStatusEntries?: SyncPriorityStatus[];
+export interface SyncStatus {
   /**
-   * @deprecated This field is no longer set, since {@link SyncClientImplementation.RUST} is the only option.
+   * Indicates if the client is currently connected to the PowerSync service.
+   *
+   * @returns True if connected, false otherwise. Defaults to false if not specified.
    */
-  clientImplementation?: SyncClientImplementation;
-};
-
-/**
- * @public
- */
-export class SyncStatus {
-  constructor(protected options: SyncStatusOptions) {}
+  get connected(): boolean;
 
   /**
-   * Returns the used sync client implementation (either the one implemented in JavaScript or the newer Rust-based
-   * implementation).
-   *
-   * This information is only available after a connection has been requested.
+   * Indicates if the client is in the process of establishing a connection to the PowerSync service.
    *
-   * @deprecated This always returns the Rust client (the only option).
+   * @returns True if connecting, false otherwise. Defaults to false if not specified.
    */
-  get clientImplementation() {
-    return this.options.clientImplementation;
-  }
+  get connecting(): boolean;
 
   /**
-   * Indicates if the client is currently connected to the PowerSync service.
-   *
-   * @returns True if connected, false otherwise. Defaults to false if not specified.
+   * Whether the PowerSync SDK is currently downloading data from the connected PowerSync service.
    */
-  get connected(): boolean {
-    return this.options.connected ?? false;
-  }
+  get downloading(): boolean;
 
   /**
-   * Indicates if the client is in the process of establishing a connection to the PowerSync service.
+   * Whether the PowerSync SDK is currently uploading local mutations through the configured
+   * {@link PowerSyncBackendConnector}.
+   */
+  get uploading(): boolean;
+
+  /**
+   * An error that occurred during downloads (including connection establishment errors).
    *
-   * @returns True if connecting, false otherwise. Defaults to false if not specified.
+   * A download error will be reported on all sync status entries until the next successful sync.
    */
-  get connecting(): boolean {
-    return this.options.connecting ?? false;
-  }
+  get downloadError(): Error | undefined;
+
+  /**
+   * Error during uploading.
+   * Cleared on the next successful upload.
+   */
+  get uploadError(): Error | undefined;
+
+  /**
+   * @deprecated All fields on {@link SyncDataFlowStatus} are available on {@link SyncStatus} directly.
+   */
+  get dataFlowStatus(): SyncDataFlowStatus;
 
   /**
    * Time that a last sync has fully completed, if any.
@@ -99,9 +83,7 @@ export class SyncStatus {
    *
    * @returns The timestamp of the last successful sync, or undefined if no sync has completed.
    */
-  get lastSyncedAt(): Date | undefined {
-    return this.options.lastSyncedAt;
-  }
+  get lastSyncedAt(): Date | undefined;
 
   /**
    * Indicates whether there has been at least one full sync completed since initialization.
@@ -109,33 +91,7 @@ export class SyncStatus {
    * @returns True if at least one sync has completed, false if no sync has completed,
    * or undefined when the state is still being loaded from the database.
    */
-  get hasSynced(): boolean | undefined {
-    return this.options.hasSynced;
-  }
-
-  /**
-   * Provides the current data flow status regarding uploads and downloads.
-   *
-   * @returns An object containing:
-   * - downloading: True if actively downloading changes (only when connected is also true)
-   * - uploading: True if actively uploading changes
-   * Defaults to `{downloading: false, uploading: false}` if not specified.
-   */
-  get dataFlowStatus(): SyncDataFlowStatus {
-    return (
-      this.options.dataFlow ?? {
-        /**
-         * true if actively downloading changes.
-         * This is only true when {@link connected} is also true.
-         */
-        downloading: false,
-        /**
-         * true if uploading changes.
-         */
-        uploading: false
-      }
-    );
-  }
+  get hasSynced(): boolean | undefined;
 
   /**
    * All sync streams currently being tracked in the database.
@@ -143,21 +99,12 @@ export class SyncStatus {
    * This returns null when the database is currently being opened and we don't have reliable information about all
    * included streams yet.
    */
-  get syncStreams(): SyncStreamStatus[] | undefined {
-    return this.options.dataFlow?.internalStreamSubscriptions?.map((core) => new SyncStreamStatusView(this, core));
-  }
+  get syncStreams(): SyncStreamStatus[] | undefined;
 
   /**
    * If the `stream` appears in {@link SyncStatus.syncStreams}, returns the current status for that stream.
    */
-  forStream(stream: SyncStreamDescription): SyncStreamStatus | undefined {
-    const asJson = JSON.stringify(stream.parameters);
-    const raw = this.options.dataFlow?.internalStreamSubscriptions?.find(
-      (r) => r.name == stream.name && asJson == JSON.stringify(r.parameters)
-    );
-
-    return raw && new SyncStreamStatusView(this, raw);
-  }
+  forStream(stream: SyncStreamDescription): SyncStreamStatus | undefined;
 
   /**
    * Provides sync status information for all bucket priorities, sorted by priority (highest first).
@@ -165,24 +112,15 @@ export class SyncStatus {
    * @returns An array of status entries for different sync priority levels,
    * sorted with highest priorities (lower numbers) first.
    */
-  get priorityStatusEntries(): SyncPriorityStatus[] {
-    return (this.options.priorityStatusEntries ?? []).slice().sort(SyncStatus.comparePriorities);
-  }
+  get priorityStatusEntries(): SyncPriorityStatus[] | undefined;
 
   /**
    * A realtime progress report on how many operations have been downloaded and
    * how many are necessary in total to complete the next sync iteration.
    *
-   * This field is only set when {@link SyncDataFlowStatus#downloading} is also true.
+   * This field is only set when {@link SyncStatus#downloading} is also true.
    */
-  get downloadProgress(): SyncProgress | null {
-    const internalProgress = this.options.dataFlow?.downloadProgress;
-    if (internalProgress == null) {
-      return null;
-    }
-
-    return new SyncProgress(internalProgress);
-  }
+  get downloadProgress(): SyncProgress | null;
 
   /**
    * Reports the sync status (a pair of {@link SyncStatus#hasSynced} and {@link SyncStatus#lastSyncedAt} fields)
@@ -203,22 +141,7 @@ export class SyncStatus {
    * @param priority - The bucket priority for which the status should be reported
    * @returns Status information for the requested priority level or the next higher level with available status
    */
-  statusForPriority(priority: number): SyncPriorityStatus {
-    // priorityStatusEntries are sorted by ascending priorities (so higher numbers to lower numbers).
-    for (const known of this.priorityStatusEntries) {
-      // We look for the first entry that doesn't have a higher priority.
-      if (known.priority >= priority) {
-        return known;
-      }
-    }
-
-    // If we have a complete sync, that necessarily includes all priorities.
-    return {
-      priority,
-      lastSyncedAt: this.lastSyncedAt,
-      hasSynced: this.hasSynced
-    };
-  }
+  statusForPriority(priority: number): SyncPriorityStatus | undefined;
 
   /**
    * Compares this SyncStatus instance with another to determine if they are equal.
@@ -227,20 +150,7 @@ export class SyncStatus {
    * @param status - The SyncStatus instance to compare against
    * @returns True if the instances are considered equal, false otherwise
    */
-  isEqual(status: SyncStatus) {
-    /**
-     * By default Error object are serialized to an empty object.
-     * This replaces Errors with more useful information before serialization.
-     */
-    const replacer = (_: string, value: any) => {
-      if (value instanceof Error) {
-        return this.serializeError(value);
-      }
-      return value;
-    };
-
-    return JSON.stringify(this.options, replacer) == JSON.stringify(status.options, replacer);
-  }
+  isEqual(status: SyncStatus): boolean;
 
   /**
    * Creates a human-readable string representation of the current sync status.
@@ -248,56 +158,7 @@ export class SyncStatus {
    *
    * @returns A string representation of the sync status
    */
-  getMessage() {
-    const dataFlow = this.dataFlowStatus;
-    return `SyncStatus<connected: ${this.connected} connecting: ${this.connecting} lastSyncedAt: ${this.lastSyncedAt} hasSynced: ${this.hasSynced}. Downloading: ${dataFlow.downloading}. Uploading: ${dataFlow.uploading}. UploadError: ${dataFlow.uploadError}, DownloadError?: ${dataFlow.downloadError}>`;
-  }
-
-  /**
-   * Serializes the SyncStatus instance to a plain object.
-   *
-   * @returns A plain object representation of the sync status
-   */
-  toJSON(): SyncStatusOptions {
-    return {
-      connected: this.connected,
-      connecting: this.connecting,
-      dataFlow: {
-        ...this.dataFlowStatus,
-        uploadError: this.serializeError(this.dataFlowStatus.uploadError),
-        downloadError: this.serializeError(this.dataFlowStatus.downloadError)
-      },
-      lastSyncedAt: this.lastSyncedAt,
-      hasSynced: this.hasSynced,
-      priorityStatusEntries: this.priorityStatusEntries
-    };
-  }
-
-  /**
-   * 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): Error | undefined {
-    if (typeof error == 'undefined') {
-      return undefined;
-    }
-    const serialized: Error = {
-      name: error.name,
-      message: error.message,
-      stack: error.stack
-    };
-    // `Error.cause` can be any value (the spec types it as unknown). Preserve it
-    // so consumers reading uploadError/downloadError keep the failure context.
-    // Recurse for Error causes so the whole chain is flattened the same way.
-    if (typeof error.cause != 'undefined') {
-      serialized.cause = error.cause instanceof Error ? this.serializeError(error.cause) : error.cause;
-    }
-    return serialized;
-  }
-
-  private static comparePriorities(a: SyncPriorityStatus, b: SyncPriorityStatus) {
-    return b.priority - a.priority; // Reverse because higher priorities have lower numbers
-  }
+  getMessage(): string;
 }
 
 /**
@@ -310,39 +171,3 @@ export interface SyncStreamStatus {
   subscription: SyncSubscriptionDescription;
   priority: number | null;
 }
-
-class SyncStreamStatusView implements SyncStreamStatus {
-  subscription: SyncSubscriptionDescription;
-
-  constructor(
-    private status: SyncStatus,
-    private core: CoreStreamSubscription
-  ) {
-    this.subscription = {
-      name: core.name,
-      parameters: core.parameters,
-      active: core.active,
-      isDefault: core.is_default,
-      hasExplicitSubscription: core.has_explicit_subscription,
-      expiresAt: core.expires_at != null ? new Date(core.expires_at * 1000) : null,
-      hasSynced: core.last_synced_at != null,
-      lastSyncedAt: core.last_synced_at != null ? new Date(core.last_synced_at * 1000) : null
-    };
-  }
-
-  get progress() {
-    if (this.status.dataFlowStatus.downloadProgress == null) {
-      // Don't make download progress public if we're not currently downloading.
-      return null;
-    }
-
-    const { total, downloaded } = this.core.progress;
-    const progress = total == 0 ? 0.0 : downloaded / total;
-
-    return { totalOperations: total, downloadedOperations: downloaded, downloadedFraction: progress };
-  }
-
-  get priority() {
-    return this.core.priority;
-  }
-}

package/src/db/schema/Column.ts

@@ -45,14 +45,6 @@ const real: BaseColumnType<number | null> = {
   type: ColumnType.REAL
 };
 
-/**
- * powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
- * In earlier versions this was limited to 63.
- *
- * @internal
- */
-export const MAX_AMOUNT_OF_COLUMNS = 1999;
-
 /**
  * @public
  */

package/src/db/schema/Index.ts

@@ -1,5 +1,5 @@
 import { IndexedColumn } from './IndexedColumn.js';
-import { Table } from './Table.js';
+import { ResolvedTable } from './Table.js';
 
 /**
  * @public
@@ -9,10 +9,7 @@ export interface IndexOptions {
   columns?: IndexedColumn[];
 }
 
-/**
- * @internal
- */
-export const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions> = {
+const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions> = {
   columns: []
 };
 
@@ -39,7 +36,7 @@ export class Index {
     return this.options.columns ?? [];
   }
 
-  toJSON(table: Table) {
+  toJSON(table: ResolvedTable) {
     return {
       name: this.name,
       columns: this.columns.map((c) => c.toJSON(table))

package/src/db/schema/IndexedColumn.ts

@@ -1,5 +1,5 @@
 import { ColumnType } from './Column.js';
-import { Table } from './Table.js';
+import { ResolvedTable } from './Table.js';
 
 /**
  * @public
@@ -9,10 +9,7 @@ export interface IndexColumnOptions {
   ascending?: boolean;
 }
 
-/**
- * @internal
- */
-export const DEFAULT_INDEX_COLUMN_OPTIONS: Partial<IndexColumnOptions> = {
+const DEFAULT_INDEX_COLUMN_OPTIONS: Partial<IndexColumnOptions> = {
   ascending: true
 };
 
@@ -41,7 +38,7 @@ export class IndexedColumn {
     return this.options.ascending;
   }
 
-  toJSON(table: Table) {
+  toJSON(table: ResolvedTable) {
     return {
       name: this.name,
       ascending: this.ascending,