@powersync/common 0.0.0-dev-20260504100448 → 0.0.0-dev-20260630141119

package/src/db/crud/SyncProgress.ts

@@ -1,20 +1,12 @@
-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.
  *
  * To obtain these values, use {@link SyncProgress}, available through
  * {@link SyncStatus#downloadProgress}.
+ *
+ * @public
  */
 export interface ProgressWithOperations {
   /**
@@ -28,7 +20,8 @@ export interface ProgressWithOperations {
   downloadedOperations: number;
 
   /**
-   * Relative progress, as {@link downloadedOperations} of {@link totalOperations}.
+   * Relative progress, as {@link ProgressWithOperations.downloadedOperations} of
+   * {@link ProgressWithOperations.totalOperations}.
    *
    * This will be a number between `0.0` and `1.0` (inclusive).
    *
@@ -58,43 +51,15 @@ export interface ProgressWithOperations {
  *
  * Also note that data is downloaded in bulk, which means that individual counters are unlikely
  * to be updated one-by-one.
+ *
+ * @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,9 +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';
 
-export type SyncDataFlowStatus = Partial<{
+/**
+ * @public
+ * @deprecated All fields are available on {@link SyncStatus} directly.
+ */
+export interface SyncDataFlowStatus {
   downloading: boolean;
   uploading: boolean;
   /**
@@ -17,105 +19,79 @@ export type SyncDataFlowStatus = Partial<{
    * Cleared on the next successful upload.
    */
   uploadError?: Error;
-  /**
-   * Internal information about how far we are downloading operations in buckets.
-   *
-   * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
-   */
-  downloadProgress: InternalProgressInformation | null;
-  internalStreamSubscriptions: CoreStreamSubscription[] | null;
-}>;
+}
 
+/**
+ * @public
+ */
 export interface SyncPriorityStatus {
   priority: number;
   lastSyncedAt?: Date;
   hasSynced?: boolean;
 }
 
-export type SyncStatusOptions = {
-  connected?: boolean;
-  connecting?: boolean;
-  dataFlow?: SyncDataFlowStatus;
-  lastSyncedAt?: Date;
-  hasSynced?: boolean;
-  priorityStatusEntries?: SyncPriorityStatus[];
-  clientImplementation?: SyncClientImplementation;
-};
-
-export class SyncStatus {
-  constructor(protected options: SyncStatusOptions) {}
-
+/**
+ * @public
+ */
+export interface SyncStatus {
   /**
-   * Returns the used sync client implementation (either the one implemented in JavaScript or the newer Rust-based
-   * implementation).
+   * Indicates if the client is currently connected to the PowerSync service.
    *
-   * This information is only available after a connection has been requested.
+   * @returns True if connected, false otherwise. Defaults to false if not specified.
    */
-  get clientImplementation() {
-    return this.options.clientImplementation;
-  }
+  get connected(): boolean;
 
   /**
-   * Indicates if the client is currently connected to the PowerSync service.
+   * Indicates if the client is in the process of establishing a connection to the PowerSync service.
    *
-   * @returns {boolean} True if connected, false otherwise. Defaults to false if not specified.
+   * @returns True if connecting, false otherwise. Defaults to false if not specified.
    */
-  get connected() {
-    return this.options.connected ?? false;
-  }
+  get connecting(): boolean;
 
   /**
-   * Indicates if the client is in the process of establishing a connection to the PowerSync service.
+   * Whether the PowerSync SDK is currently downloading data from the connected PowerSync service.
+   */
+  get downloading(): boolean;
+
+  /**
+   * 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 {boolean} 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 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 connecting() {
-    return this.options.connecting ?? false;
-  }
+  get dataFlowStatus(): SyncDataFlowStatus;
 
   /**
    * Time that a last sync has fully completed, if any.
    * This timestamp is reset to null after a restart of the PowerSync service.
    *
-   * @returns {Date | undefined} The timestamp of the last successful sync, or undefined if no sync has completed.
+   * @returns The timestamp of the last successful sync, or undefined if no sync has completed.
    */
-  get lastSyncedAt() {
-    return this.options.lastSyncedAt;
-  }
+  get lastSyncedAt(): Date | undefined;
 
   /**
    * Indicates whether there has been at least one full sync completed since initialization.
    *
-   * @returns {boolean | undefined} True if at least one sync has completed, false if no sync has completed,
+   * @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() {
-    return this.options.hasSynced;
-  }
-
-  /**
-   * Provides the current data flow status regarding uploads and downloads.
-   *
-   * @returns {SyncDataFlowStatus} 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() {
-    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 teh database.
@@ -123,46 +99,28 @@ 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 syncStreams}, returns the current status for that stream.
+   * 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).
    *
-   * @returns {SyncPriorityStatus[]} An array of status entries for different sync priority levels,
+   * @returns An array of status entries for different sync priority levels,
    * sorted with highest priorities (lower numbers) first.
    */
-  get priorityStatusEntries() {
-    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)
@@ -180,144 +138,36 @@ export class SyncStatus {
    * For example, if PowerSync just finished synchronizing buckets in priority level 3, calling this method
    * with a priority of 1 may return information for priority level 3.
    *
-   * @param {number} priority The bucket priority for which the status should be reported
-   * @returns {SyncPriorityStatus} Status information for the requested priority level or the next higher level with available status
+   * @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.
    * Equality is determined by comparing the serialized JSON representation of both instances.
    *
-   * @param {SyncStatus} status The SyncStatus instance to compare against
-   * @returns {boolean} True if the instances are considered equal, false otherwise
+   * @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 {
-          name: value.name,
-          message: value.message,
-          stack: value.stack
-        };
-      }
-      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.
    * Includes information about connection state, sync completion, and data flow.
    *
-   * @returns {string} 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 {SyncStatusOptions} A plain object representation of the sync status
+   * @returns A string 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) {
-    if (typeof error == 'undefined') {
-      return undefined;
-    }
-    return {
-      name: error.name,
-      message: error.message,
-      stack: error.stack
-    };
-  }
-
-  private static comparePriorities(a: SyncPriorityStatus, b: SyncPriorityStatus) {
-    return b.priority - a.priority; // Reverse because higher priorities have lower numbers
-  }
+  getMessage(): string;
 }
 
 /**
  * Information about a sync stream subscription.
+ *
+ * @public
  */
 export interface SyncStreamStatus {
   progress: ProgressWithOperations | null;
   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/crud/UploadQueueStatus.ts

@@ -1,3 +1,6 @@
+/**
+ * @public
+ */
 export class UploadQueueStats {
   constructor(
     /**

package/src/db/schema/Column.ts

@@ -1,21 +1,36 @@
-// https://www.sqlite.org/lang_expr.html#castexpr
+/**
+ * @see https://www.sqlite.org/lang_expr.html#castexpr
+ * @public
+ */
 export enum ColumnType {
   TEXT = 'TEXT',
   INTEGER = 'INTEGER',
   REAL = 'REAL'
 }
 
+/**
+ * @public
+ */
 export interface ColumnOptions {
   name: string;
   type?: ColumnType;
 }
 
+/**
+ * @public
+ */
 export type BaseColumnType<T extends number | string | null> = {
   type: ColumnType;
 };
 
+/**
+ * @public
+ */
 export type ColumnsType = Record<string, BaseColumnType<any>>;
 
+/**
+ * @public
+ */
 export type ExtractColumnValueType<T extends BaseColumnType<any>> = T extends BaseColumnType<infer R> ? R : unknown;
 
 const text: BaseColumnType<string | null> = {
@@ -30,16 +45,18 @@ 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.
-export const MAX_AMOUNT_OF_COLUMNS = 1999;
-
+/**
+ * @public
+ */
 export const column = {
   text,
   integer,
   real
 };
 
+/**
+ * @public
+ */
 export class Column {
   constructor(protected options: ColumnOptions) {}
 

package/src/db/schema/Index.ts

@@ -1,15 +1,21 @@
 import { IndexedColumn } from './IndexedColumn.js';
-import { Table } from './Table.js';
+import { ResolvedTable } from './Table.js';
 
+/**
+ * @public
+ */
 export interface IndexOptions {
   name: string;
   columns?: IndexedColumn[];
 }
 
-export const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions> = {
+const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions> = {
   columns: []
 };
 
+/**
+ * @public
+ */
 export class Index {
   static createAscending(options: IndexOptions, columnNames: string[]) {
     return new Index({
@@ -30,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,15 +1,21 @@
 import { ColumnType } from './Column.js';
-import { Table } from './Table.js';
+import { ResolvedTable } from './Table.js';
 
+/**
+ * @public
+ */
 export interface IndexColumnOptions {
   name: string;
   ascending?: boolean;
 }
 
-export const DEFAULT_INDEX_COLUMN_OPTIONS: Partial<IndexColumnOptions> = {
+const DEFAULT_INDEX_COLUMN_OPTIONS: Partial<IndexColumnOptions> = {
   ascending: true
 };
 
+/**
+ * @public
+ */
 export class IndexedColumn {
   protected options: IndexColumnOptions;
 
@@ -32,7 +38,7 @@ export class IndexedColumn {
     return this.options.ascending;
   }
 
-  toJSON(table: Table) {
+  toJSON(table: ResolvedTable) {
     return {
       name: this.name,
       ascending: this.ascending,

package/src/db/schema/RawTable.ts

@@ -7,8 +7,10 @@ import { TableOrRawTableOptions } from './Table.js';
  * using client-side table and column constraints.
  *
  * To collect local writes to raw tables with PowerSync, custom triggers are required. See
- * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables} for details and an example on
  * using raw tables.
+ *
+ * @public
  */
 export type RawTableType = RawTableTypeWithStatements | InferredRawTableType;
 
@@ -70,11 +72,15 @@ interface InferredRawTableType extends Partial<RawTableTypeWithStatements> {
  * `{Column: 'name'}`.
  * The `"Rest"` parameter gets resolved to a JSON object covering all values from the synced row that haven't been
  * covered by a `Column` parameter.
+ *
+ * @public
  */
 export type PendingStatementParameter = 'Id' | { Column: string } | 'Rest';
 
 /**
  * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
+ *
+ * @public
  */
 export type PendingStatement = {
   sql: string;

package/src/db/schema/Schema.ts

@@ -1,26 +1,31 @@
 import { encodeTableOptions } from './internal.js';
 import { RawTable, RawTableType } from './RawTable.js';
-import { RowType, Table } from './Table.js';
+import { ResolvedTable, RowType, Table } from './Table.js';
 
 type SchemaType = Record<string, Table<any>>;
 
+/**
+ * @public
+ */
 export type SchemaTableType<S extends SchemaType> = {
   [K in keyof S]: RowType<S[K]>;
 };
 
 /**
  * A schema is a collection of tables. It is used to define the structure of a database.
+ *
+ * @public
  */
 export class Schema<S extends SchemaType = SchemaType> {
   /*
     Only available when constructing with mapped typed definition columns
   */
-  readonly types: SchemaTableType<S>;
-  readonly props: S;
-  readonly tables: Table[];
+  readonly types!: SchemaTableType<S>;
+  readonly props!: S;
+  readonly tables: ResolvedTable[];
   readonly rawTables: RawTable[];
 
-  constructor(tables: Table[] | S) {
+  constructor(tables: ResolvedTable[] | S) {
     if (Array.isArray(tables)) {
       /*
         We need to validate that the tables have a name here because a user could pass in an array
@@ -52,7 +57,7 @@ export class Schema<S extends SchemaType = SchemaType> {
    * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
    * using client-side table and column constraints.
    *
-   * @param tables An object of (table name, raw table definition) entries.
+   * @param tables - An object of (table name, raw table definition) entries.
    */
   withRawTables(tables: Record<string, RawTableType>) {
     for (const [name, rawTableDefinition] of Object.entries(tables)) {
@@ -66,7 +71,7 @@ export class Schema<S extends SchemaType = SchemaType> {
     }
   }
 
-  toJSON() {
+  toJSON(): unknown {
     return {
       tables: this.tables.map((t) => t.toJSON()),
       raw_tables: this.rawTables.map(Schema.rawTableToJson)