@powersync/common 1.53.1 → 1.54.0

package/src/db/DBAdapter.ts

@@ -12,6 +12,8 @@ import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
 
 /**
  * Object returned by SQL Query executions.
+ *
+ * @public
  */
 export type QueryResult = {
   /** Represents the auto-generated row id if applicable. */
@@ -31,13 +33,16 @@ export type QueryResult = {
     /** The length of the dataset */
     length: number;
     /** A convenience function to acess the index based the row object
-     * @param idx the row index
+     * @param idx - the row index
      * @returns the row structure identified by column names
      */
     item: (idx: number) => any;
   };
 };
 
+/**
+ * @public
+ */
 export interface DBGetUtils {
   /** Execute a read-only query and return results. */
   getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
@@ -47,6 +52,9 @@ export interface DBGetUtils {
   get<T>(sql: string, parameters?: any[]): Promise<T>;
 }
 
+/**
+ * @public
+ */
 export interface SqlExecutor {
   /** Execute a single write statement. */
   execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
@@ -58,17 +66,24 @@ export interface SqlExecutor {
    *
    * Example result:
    *
-   * ```[ [ '1', 'list 1', '33', 'Post content', '1' ] ]```
+   * ```JavaScript
+   * [ [ '1', 'list 1', '33', 'Post content', '1' ] ]
+   * ```
    *
    * Where as `execute`'s `rows._array` would have been:
    *
-   * ```[ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]```
+   * ```JavaScript
+   * [ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]
+   * ```
    */
   executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
 
   executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
 }
 
+/**
+ * @public
+ */
 export interface LockContext extends SqlExecutor, DBGetUtils {
   /**
    * How the connection has been opened.
@@ -82,7 +97,9 @@ export interface LockContext extends SqlExecutor, DBGetUtils {
 }
 
 /**
- * Implements {@link DBGetUtils} on a {@link SqlRunner}.
+ * Implements {@link DBGetUtils} on a {@link SqlExecutor}.
+ *
+ * @internal
  */
 export function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Omit<SqlExecutor, 'executeBatch'>>(
   Base: TBase
@@ -132,6 +149,9 @@ export function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Omi
   };
 }
 
+/**
+ * @public
+ */
 export interface Transaction extends LockContext {
   /** Commit multiple changes to the local DB using the Transaction context. */
   commit: () => Promise<QueryResult>;
@@ -141,29 +161,44 @@ export interface Transaction extends LockContext {
 
 /**
  * Update table operation numbers from SQLite
+ *
+ * @public
  */
 export enum RowUpdateType {
   SQLITE_INSERT = 18,
   SQLITE_DELETE = 9,
   SQLITE_UPDATE = 23
 }
+
+/**
+ * @public
+ */
 export interface TableUpdateOperation {
   opType: RowUpdateType;
   rowId: number;
 }
 /**
  * Notification of an update to one or more tables, for the purpose of realtime change notifications.
+ *
+ * @public
  */
 export interface UpdateNotification extends TableUpdateOperation {
   table: string;
 }
 
+/**
+ * @public
+ */
 export interface BatchedUpdateNotification {
+  // TODO (breaking change): Normalize to only including tables
   rawUpdates: UpdateNotification[];
   tables: string[];
   groupedUpdates: Record<string, TableUpdateOperation[]>;
 }
 
+/**
+ * @public
+ */
 export interface DBAdapterListener extends BaseListener {
   /**
    * Listener for table updates.
@@ -174,10 +209,16 @@ export interface DBAdapterListener extends BaseListener {
   tablesUpdated: (updateNotification: BatchedUpdateNotification | UpdateNotification) => void;
 }
 
+/**
+ * @public
+ */
 export interface DBLockOptions {
   timeoutMs?: number;
 }
 
+/**
+ * @public
+ */
 export interface ConnectionPool extends BaseObserverInterface<DBAdapterListener> {
   name: string;
   close: () => void | Promise<void>;
@@ -190,14 +231,19 @@ export interface ConnectionPool extends BaseObserverInterface<DBAdapterListener>
   refreshSchema: () => Promise<void>;
 }
 
+/**
+ * @public
+ */
 export interface DBAdapter extends ConnectionPool, SqlExecutor, DBGetUtils {
   readTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
   writeTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
 }
 
 /**
- * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool.readLock} and
- * {@link ConnectionPool.writeLock}.
+ * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool#readLock} and
+ * {@link ConnectionPool#writeLock}.
+ *
+ * @internal
  */
 export function DBAdapterDefaultMixin<TBase extends new (...args: any[]) => ConnectionPool>(Base: TBase) {
   return class extends Base implements DBAdapter {
@@ -299,12 +345,18 @@ class TransactionImplementation extends DBGetUtilsDefaultMixin(BaseTransaction)
   }
 }
 
+/**
+ * @internal
+ */
 export function isBatchedUpdateNotification(
   update: BatchedUpdateNotification | UpdateNotification
 ): update is BatchedUpdateNotification {
   return 'tables' in update;
 }
 
+/**
+ * @internal
+ */
 export function extractTableUpdates(update: BatchedUpdateNotification | UpdateNotification) {
   return isBatchedUpdateNotification(update) ? update.tables : [update.table];
 }

package/src/db/crud/SyncProgress.ts

@@ -15,6 +15,8 @@ export const FULL_SYNC_PRIORITY = 2147483647;
  *
  * To obtain these values, use {@link SyncProgress}, available through
  * {@link SyncStatus#downloadProgress}.
+ *
+ * @public
  */
 export interface ProgressWithOperations {
   /**
@@ -28,7 +30,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,6 +61,8 @@ 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;

package/src/db/crud/SyncStatus.ts

@@ -3,6 +3,9 @@ import { CoreStreamSubscription } from '../../client/sync/stream/core-instructio
 import { SyncStreamDescription, SyncSubscriptionDescription } from '../../client/sync/sync-streams.js';
 import { InternalProgressInformation, ProgressWithOperations, SyncProgress } from './SyncProgress.js';
 
+/**
+ * @public
+ */
 export type SyncDataFlowStatus = Partial<{
   downloading: boolean;
   uploading: boolean;
@@ -20,18 +23,27 @@ export type SyncDataFlowStatus = Partial<{
   /**
    * Internal information about how far we are downloading operations in buckets.
    *
-   * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
+   * @internal Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
    */
   downloadProgress: InternalProgressInformation | null;
+  /**
+   * @internal
+   */
   internalStreamSubscriptions: CoreStreamSubscription[] | null;
 }>;
 
+/**
+ * @public
+ */
 export interface SyncPriorityStatus {
   priority: number;
   lastSyncedAt?: Date;
   hasSynced?: boolean;
 }
 
+/**
+ * @internal
+ */
 export type SyncStatusOptions = {
   connected?: boolean;
   connecting?: boolean;
@@ -45,6 +57,9 @@ export type SyncStatusOptions = {
   clientImplementation?: SyncClientImplementation;
 };
 
+/**
+ * @public
+ */
 export class SyncStatus {
   constructor(protected options: SyncStatusOptions) {}
 
@@ -53,6 +68,8 @@ export class SyncStatus {
    * implementation).
    *
    * This information is only available after a connection has been requested.
+   *
+   * @deprecated This always returns the Rust client (the only option).
    */
   get clientImplementation() {
     return this.options.clientImplementation;
@@ -61,18 +78,18 @@ export class SyncStatus {
   /**
    * Indicates if the client is currently connected to the PowerSync service.
    *
-   * @returns {boolean} True if connected, false otherwise. Defaults to false if not specified.
+   * @returns True if connected, false otherwise. Defaults to false if not specified.
    */
-  get connected() {
+  get connected(): boolean {
     return this.options.connected ?? false;
   }
 
   /**
    * Indicates if the client is in the process of establishing a connection to the PowerSync service.
    *
-   * @returns {boolean} True if connecting, false otherwise. Defaults to false if not specified.
+   * @returns True if connecting, false otherwise. Defaults to false if not specified.
    */
-  get connecting() {
+  get connecting(): boolean {
     return this.options.connecting ?? false;
   }
 
@@ -80,31 +97,31 @@ export class SyncStatus {
    * 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() {
+  get lastSyncedAt(): Date | undefined {
     return this.options.lastSyncedAt;
   }
 
   /**
    * 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() {
+  get hasSynced(): boolean | undefined {
     return this.options.hasSynced;
   }
 
   /**
    * Provides the current data flow status regarding uploads and downloads.
    *
-   * @returns {SyncDataFlowStatus} An object containing:
+   * @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.
+   * Defaults to `{downloading: false, uploading: false}` if not specified.
    */
-  get dataFlowStatus() {
+  get dataFlowStatus(): SyncDataFlowStatus {
     return (
       this.options.dataFlow ?? {
         /**
@@ -131,7 +148,7 @@ export class SyncStatus {
   }
 
   /**
-   * 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);
@@ -145,10 +162,10 @@ export class SyncStatus {
   /**
    * 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() {
+  get priorityStatusEntries(): SyncPriorityStatus[] {
     return (this.options.priorityStatusEntries ?? []).slice().sort(SyncStatus.comparePriorities);
   }
 
@@ -183,8 +200,8 @@ 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).
@@ -207,8 +224,8 @@ export class SyncStatus {
    * 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) {
     /**
@@ -233,7 +250,7 @@ export class SyncStatus {
    * 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
+   * @returns A string representation of the sync status
    */
   getMessage() {
     const dataFlow = this.dataFlowStatus;
@@ -243,7 +260,7 @@ export class SyncStatus {
   /**
    * Serializes the SyncStatus instance to a plain object.
    *
-   * @returns {SyncStatusOptions} A plain object representation of the sync status
+   * @returns A plain object representation of the sync status
    */
   toJSON(): SyncStatusOptions {
     return {
@@ -282,6 +299,8 @@ export class SyncStatus {
 
 /**
  * Information about a sync stream subscription.
+ *
+ * @public
  */
 export interface SyncStreamStatus {
   progress: ProgressWithOperations | null;

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,26 @@ 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.
+/**
+ * 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
+ */
 export const column = {
   text,
   integer,
   real
 };
 
+/**
+ * @public
+ */
 export class Column {
   constructor(protected options: ColumnOptions) {}
 

package/src/db/schema/Index.ts

@@ -1,15 +1,24 @@
 import { IndexedColumn } from './IndexedColumn.js';
 import { Table } from './Table.js';
 
+/**
+ * @public
+ */
 export interface IndexOptions {
   name: string;
   columns?: IndexedColumn[];
 }
 
+/**
+ * @internal
+ */
 export const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions> = {
   columns: []
 };
 
+/**
+ * @public
+ */
 export class Index {
   static createAscending(options: IndexOptions, columnNames: string[]) {
     return new Index({

package/src/db/schema/IndexedColumn.ts

@@ -1,15 +1,24 @@
 import { ColumnType } from './Column.js';
 import { Table } from './Table.js';
 
+/**
+ * @public
+ */
 export interface IndexColumnOptions {
   name: string;
   ascending?: boolean;
 }
 
+/**
+ * @internal
+ */
 export const DEFAULT_INDEX_COLUMN_OPTIONS: Partial<IndexColumnOptions> = {
   ascending: true
 };
 
+/**
+ * @public
+ */
 export class IndexedColumn {
   protected options: IndexColumnOptions;
 

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

@@ -4,19 +4,24 @@ import { 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 types!: SchemaTableType<S>;
+  readonly props!: S;
   readonly tables: Table[];
   readonly rawTables: RawTable[];
 
@@ -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)) {

package/src/db/schema/Table.ts

@@ -13,6 +13,8 @@ import { TableV2 } from './TableV2.js';
 
 /**
  * Options that apply both to JSON-based tables and raw tables.
+ *
+ * @public
  */
 export interface TableOrRawTableOptions {
   localOnly?: boolean;
@@ -30,6 +32,8 @@ interface SharedTableOptions extends TableOrRawTableOptions {
  *
  * Including old values may be helpful for some backend connector implementations, which is
  * why it can be enabled on per-table or per-columm basis.
+ *
+ * @public
  */
 export interface TrackPreviousOptions {
   /** When defined, a list of column names for which old values should be tracked. */
@@ -38,6 +42,9 @@ export interface TrackPreviousOptions {
   onlyWhenChanged?: boolean;
 }
 
+/**
+ * @public
+ */
 export interface TableOptions extends SharedTableOptions {
   /**
    * The synced table name, matching sync rules
@@ -47,18 +54,31 @@ export interface TableOptions extends SharedTableOptions {
   indexes?: Index[];
 }
 
+/**
+ * @public
+ */
 export type RowType<T extends TableV2<any>> = {
   [K in keyof T['columnMap']]: ExtractColumnValueType<T['columnMap'][K]>;
 } & {
   id: string;
 };
 
+/**
+ * @public
+ */
 export type IndexShorthand = Record<string, string[]>;
 
+/**
+ * @public
+ */
+
 export interface TableV2Options extends SharedTableOptions {
   indexes?: IndexShorthand;
 }
 
+/**
+ * @internal
+ */
 export const DEFAULT_TABLE_OPTIONS = {
   indexes: [],
   insertOnly: false,
@@ -68,12 +88,18 @@ export const DEFAULT_TABLE_OPTIONS = {
   ignoreEmptyUpdates: false
 };
 
+/**
+ * @internal
+ */
 export const InvalidSQLCharacters = /["'%,.#\s[\]]/;
 
+/**
+ * @public
+ */
 export class Table<Columns extends ColumnsType = ColumnsType> {
-  protected options: TableOptions;
+  protected options!: TableOptions;
 
-  protected _mappedColumns: Columns;
+  protected _mappedColumns!: Columns;
 
   static createLocalOnly(options: TableOptions) {
     return new Table({ ...options, localOnly: true, insertOnly: false });
@@ -108,9 +134,8 @@ export class Table<Columns extends ColumnsType = ColumnsType> {
    * 1. New constructor: Using a Columns object and an optional TableV2Options object
    * 2. Deprecated constructor: Using a TableOptions object (will be removed in the next major release)
    *
-   * @constructor
-   * @param {Columns | TableOptions} optionsOrColumns - Either a Columns object (for V2 syntax) or a TableOptions object (for V1 syntax)
-   * @param {TableV2Options} [v2Options] - Optional configuration options for V2 syntax
+   * @param columns - Either a Columns object (for V2 syntax) or a TableOptions object (for V1 syntax)
+   * @param options - Optional configuration options for V2 syntax
    *
    * @example
    * ```javascript

package/src/db/schema/TableV2.ts

@@ -5,5 +5,7 @@ import { Table } from './Table.js';
   Generate a new table from the columns and indexes
   @deprecated You should use {@link Table} instead as it now allows TableV2 syntax.
   This will be removed in the next major release.
+
+  @public
 */
 export class TableV2<Columns extends ColumnsType = ColumnsType> extends Table<Columns> {}