@powersync/common 1.53.2 → 1.54.0

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> {}

package/src/index.ts

@@ -35,7 +35,7 @@ export * from './db/DBAdapter.js';
 export * from './db/schema/Column.js';
 export * from './db/schema/Index.js';
 export * from './db/schema/IndexedColumn.js';
-export { RawTableType, PendingStatementParameter, PendingStatement } from './db/schema/RawTable.js';
+export { PendingStatement, PendingStatementParameter, RawTableType } from './db/schema/RawTable.js';
 export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';

package/src/types/types.ts

@@ -1,8 +1,14 @@
+/**
+ * @public
+ */
 export interface CompilableQuery<T> {
   execute(): Promise<T[]>;
   compile(): CompiledQuery;
 }
 
+/**
+ * @public
+ */
 export interface CompiledQuery {
   readonly sql: string;
   readonly parameters: ReadonlyArray<unknown>;

package/src/utils/AbortOperation.ts

@@ -2,6 +2,8 @@
  * Calls to Abortcontroller.abort(reason: any) will result in the
  * `reason` being thrown. This is not necessarily an error,
  *  but extends error for better logging purposes.
+ *
+ * @internal
  */
 export class AbortOperation extends Error {
   constructor(protected reason: string) {

package/src/utils/BaseObserver.ts

@@ -1,13 +1,25 @@
+/**
+ * @public
+ */
 export interface Disposable {
   dispose: () => Promise<void> | void;
 }
 
+/**
+ * @public
+ */
 export type BaseListener = Record<string, ((...event: any) => any) | undefined>;
 
+/**
+ * @public
+ */
 export interface BaseObserverInterface<T extends BaseListener> {
   registerListener(listener: Partial<T>): () => void;
 }
 
+/**
+ * @internal
+ */
 export class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
   protected listeners = new Set<Partial<T>>();
 

package/src/utils/ControlledExecutor.ts

@@ -1,3 +1,6 @@
+/**
+ * @internal
+ */
 export interface ControlledExecutorOptions {
   /**
    * If throttling is enabled, it ensures only one task runs at a time,
@@ -7,6 +10,9 @@ export interface ControlledExecutorOptions {
   throttleEnabled?: boolean;
 }
 
+/**
+ * @internal
+ */
 export class ControlledExecutor<T> {
   private task: (param: T) => Promise<void> | void;
 

package/src/utils/Logger.ts

@@ -4,6 +4,9 @@ export { GlobalLogger, ILogger, ILoggerOpts, ILogHandler, ILogLevel } from 'js-l
 
 const TypedLogger: ILogger = Logger as any;
 
+/**
+ * @public
+ */
 export const LogLevel = {
   TRACE: TypedLogger.TRACE,
   DEBUG: TypedLogger.DEBUG,
@@ -14,6 +17,9 @@ export const LogLevel = {
   OFF: TypedLogger.OFF
 };
 
+/**
+ * @public
+ */
 export interface CreateLoggerOptions {
   logLevel?: ILogLevel;
 }
@@ -25,6 +31,7 @@ export interface CreateLoggerOptions {
  * across all loggers created with `createLogger`. Adjusting settings on this
  * base logger affects all loggers derived from it unless explicitly overridden.
  *
+ * @public
  */
 export function createBaseLogger() {
   return Logger;
@@ -36,6 +43,8 @@ export function createBaseLogger() {
  * Named loggers allow specific modules or areas of your application to have
  * their own logging levels and behaviors. These loggers inherit configuration
  * from the base logger by default but can override settings independently.
+ *
+ * @public
  */
 export function createLogger(name: string, options: CreateLoggerOptions = {}): ILogger {
   const logger = Logger.get(name);

package/src/utils/mutex.ts

@@ -1,5 +1,8 @@
 import { Queue } from './queue.js';
 
+/**
+ * @internal
+ */
 export type UnlockFn = () => void;
 
 /**
@@ -178,10 +181,19 @@ export class Mutex {
 
 /**
  * Creates a signal aborting after the set timeout.
+ *
+ * @internal
  */
 export function timeoutSignal(timeout: number): AbortSignal;
+
+/**
+ * @internal
+ */
 export function timeoutSignal(timeout?: number): AbortSignal | undefined;
 
+/**
+ * @internal
+ */
 export function timeoutSignal(timeout?: number): AbortSignal | undefined {
   if (timeout == null) return;
   if ('timeout' in AbortSignal) return AbortSignal.timeout(timeout);

package/src/utils/parseQuery.ts

@@ -1,10 +1,16 @@
 import type { CompilableQuery } from '../types/types.js';
 
+/**
+ * @internal
+ */
 export interface ParsedQuery {
   sqlStatement: string;
   parameters: any[];
 }
 
+/**
+ * @internal
+ */
 export const parseQuery = <T>(query: string | CompilableQuery<T>, parameters: any[]): ParsedQuery => {
   let sqlStatement: string;
 

package/src/utils/stream_transform.ts

@@ -2,9 +2,11 @@
  * An async iterator that can't be cancelled.
  *
  * To keep data flow simple, we always pass an explicit cancellation token when subscribing to async streams. Once the
- * {@link AbortSignal} aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
+ * `AbortSignal` aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
  * that there's no way to distinguish between streams that have completed normally and streams that have been cancelled,
  * but that is acceptable for our uses of this.
+ *
+ * @internal
  */
 export type SimpleAsyncIterator<T> = Pick<AsyncIterator<T>, 'next'>;