@powersync/common 1.40.0 → 1.41.1

package/src/db/schema/Schema.ts

@@ -0,0 +1,76 @@
+import { RawTable, RawTableType } from './RawTable.js';
+import { RowType, Table } from './Table.js';
+
+type SchemaType = Record<string, Table<any>>;
+
+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.
+ */
+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 rawTables: RawTable[];
+
+  constructor(tables: Table[] | S) {
+    if (Array.isArray(tables)) {
+      /*
+        We need to validate that the tables have a name here because a user could pass in an array
+        of Tables that don't have a name because they are using the V2 syntax.
+        Therefore, 'convertToClassicTables' won't be called on the tables resulting in a runtime error.
+      */
+      for (const table of tables) {
+        if (table.name === '') {
+          throw new Error(
+            "It appears you are trying to create a new Schema with an array instead of an object. Passing in an object instead of an array into 'new Schema()' may resolve your issue."
+          );
+        }
+      }
+      this.tables = tables;
+    } else {
+      // Update the table entries with the provided table name key
+      this.props = Object.fromEntries(
+        Object.entries(tables).map(([tableName, table]) => [tableName, table.copyWithName(tableName)])
+      ) as S;
+      this.tables = Object.values(this.props);
+    }
+
+    this.rawTables = [];
+  }
+
+  /**
+   * Adds raw tables to this schema. Raw tables are identified by their name, but entirely managed by the application
+   * developer instead of automatically by PowerSync.
+   * 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.
+   * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+   *
+   * @param tables An object of (table name, raw table definition) entries.
+   * @experimental Note that the raw tables API is still experimental and may change in the future.
+   */
+  withRawTables(tables: Record<string, RawTableType>) {
+    for (const [name, rawTableDefinition] of Object.entries(tables)) {
+      this.rawTables.push(new RawTable(name, rawTableDefinition));
+    }
+  }
+
+  validate() {
+    for (const table of this.tables) {
+      table.validate();
+    }
+  }
+
+  toJSON() {
+    return {
+      tables: this.tables.map((t) => t.toJSON()),
+      raw_tables: this.rawTables
+    };
+  }
+}

package/src/db/schema/Table.ts

@@ -0,0 +1,359 @@
+import {
+  BaseColumnType,
+  Column,
+  ColumnsType,
+  ColumnType,
+  ExtractColumnValueType,
+  MAX_AMOUNT_OF_COLUMNS
+} from './Column.js';
+import { Index } from './Index.js';
+import { IndexedColumn } from './IndexedColumn.js';
+import { TableV2 } from './TableV2.js';
+
+interface SharedTableOptions {
+  localOnly?: boolean;
+  insertOnly?: boolean;
+  viewName?: string;
+  trackPrevious?: boolean | TrackPreviousOptions;
+  trackMetadata?: boolean;
+  ignoreEmptyUpdates?: boolean;
+}
+
+/** Whether to include previous column values when PowerSync tracks local changes.
+ *
+ * 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.
+ */
+export interface TrackPreviousOptions {
+  /** When defined, a list of column names for which old values should be tracked. */
+  columns?: string[];
+  /** When enabled, only include values that have actually been changed by an update. */
+  onlyWhenChanged?: boolean;
+}
+
+export interface TableOptions extends SharedTableOptions {
+  /**
+   * The synced table name, matching sync rules
+   */
+  name: string;
+  columns: Column[];
+  indexes?: Index[];
+}
+
+export type RowType<T extends TableV2<any>> = {
+  [K in keyof T['columnMap']]: ExtractColumnValueType<T['columnMap'][K]>;
+} & {
+  id: string;
+};
+
+export type IndexShorthand = Record<string, string[]>;
+
+export interface TableV2Options extends SharedTableOptions {
+  indexes?: IndexShorthand;
+}
+
+export const DEFAULT_TABLE_OPTIONS = {
+  indexes: [],
+  insertOnly: false,
+  localOnly: false,
+  trackPrevious: false,
+  trackMetadata: false,
+  ignoreEmptyUpdates: false
+};
+
+export const InvalidSQLCharacters = /["'%,.#\s[\]]/;
+
+export class Table<Columns extends ColumnsType = ColumnsType> {
+  protected options: TableOptions;
+
+  protected _mappedColumns: Columns;
+
+  static createLocalOnly(options: TableOptions) {
+    return new Table({ ...options, localOnly: true, insertOnly: false });
+  }
+
+  static createInsertOnly(options: TableOptions) {
+    return new Table({ ...options, localOnly: false, insertOnly: true });
+  }
+
+  /**
+   * Create a table.
+   * @deprecated This was only only included for TableV2 and is no longer necessary.
+   * Prefer to use new Table() directly.
+   *
+   * TODO remove in the next major release.
+   */
+  static createTable(name: string, table: Table) {
+    return new Table({
+      name,
+      columns: table.columns,
+      indexes: table.indexes,
+      localOnly: table.options.localOnly,
+      insertOnly: table.options.insertOnly,
+      viewName: table.options.viewName
+    });
+  }
+
+  /**
+   * Creates a new Table instance.
+   *
+   * This constructor supports two different versions:
+   * 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
+   *
+   * @example
+   * ```javascript
+   * // New Constructor
+   * const table = new Table(
+   *   {
+   *     name: column.text,
+   *     age: column.integer
+   *   },
+   *   { indexes: { nameIndex: ['name'] } }
+   * );
+   *```
+   *
+   *
+   * @example
+   * ```javascript
+   * // Deprecated Constructor
+   * const table = new Table({
+   *   name: 'users',
+   *   columns: [
+   *     new Column({ name: 'name', type: ColumnType.TEXT }),
+   *     new Column({ name: 'age', type: ColumnType.INTEGER })
+   *   ]
+   * });
+   *```
+   */
+  constructor(columns: Columns, options?: TableV2Options);
+  /**
+   * @deprecated This constructor will be removed in the next major release.
+   * Use the new constructor shown below instead as this does not show types.
+   * @example
+   * <caption>Use this instead</caption>
+   * ```javascript
+   *   const table = new Table(
+   *     {
+   *      name: column.text,
+   *      age: column.integer
+   *     },
+   *     { indexes: { nameIndex: ['name'] } }
+   *   );
+   *```
+   */
+  constructor(options: TableOptions);
+  constructor(optionsOrColumns: Columns | TableOptions, v2Options?: TableV2Options) {
+    if (this.isTableV1(optionsOrColumns)) {
+      this.initTableV1(optionsOrColumns);
+    } else {
+      this.initTableV2(optionsOrColumns, v2Options);
+    }
+  }
+
+  copyWithName(name: string): Table {
+    return new Table({
+      ...this.options,
+      name
+    });
+  }
+
+  private isTableV1(arg: TableOptions | Columns): arg is TableOptions {
+    return 'columns' in arg && Array.isArray(arg.columns);
+  }
+
+  private initTableV1(options: TableOptions) {
+    this.options = {
+      ...options,
+      indexes: options.indexes || []
+    };
+    this.applyDefaultOptions();
+  }
+
+  private initTableV2(columns: Columns, options?: TableV2Options) {
+    const convertedColumns = Object.entries(columns).map(
+      ([name, columnInfo]) => new Column({ name, type: columnInfo.type })
+    );
+
+    const convertedIndexes = Object.entries(options?.indexes ?? {}).map(
+      ([name, columnNames]) =>
+        new Index({
+          name,
+          columns: columnNames.map(
+            (name) =>
+              new IndexedColumn({
+                name: name.replace(/^-/, ''),
+                ascending: !name.startsWith('-')
+              })
+          )
+        })
+    );
+
+    this.options = {
+      name: '',
+      columns: convertedColumns,
+      indexes: convertedIndexes,
+      viewName: options?.viewName,
+      insertOnly: options?.insertOnly,
+      localOnly: options?.localOnly,
+      trackPrevious: options?.trackPrevious,
+      trackMetadata: options?.trackMetadata,
+      ignoreEmptyUpdates: options?.ignoreEmptyUpdates
+    };
+    this.applyDefaultOptions();
+
+    this._mappedColumns = columns;
+  }
+
+  private applyDefaultOptions() {
+    this.options.insertOnly ??= DEFAULT_TABLE_OPTIONS.insertOnly;
+    this.options.localOnly ??= DEFAULT_TABLE_OPTIONS.localOnly;
+    this.options.trackPrevious ??= DEFAULT_TABLE_OPTIONS.trackPrevious;
+    this.options.trackMetadata ??= DEFAULT_TABLE_OPTIONS.trackMetadata;
+    this.options.ignoreEmptyUpdates ??= DEFAULT_TABLE_OPTIONS.ignoreEmptyUpdates;
+  }
+
+  get name() {
+    return this.options.name;
+  }
+
+  get viewNameOverride() {
+    return this.options.viewName;
+  }
+
+  get viewName() {
+    return this.viewNameOverride ?? this.name;
+  }
+
+  get columns() {
+    return this.options.columns;
+  }
+
+  get columnMap(): Columns {
+    return (
+      this._mappedColumns ??
+      this.columns.reduce((hash: Record<string, BaseColumnType<any>>, column) => {
+        hash[column.name] = { type: column.type ?? ColumnType.TEXT };
+        return hash;
+      }, {} as Columns)
+    );
+  }
+
+  get indexes() {
+    return this.options.indexes ?? [];
+  }
+
+  get localOnly() {
+    return this.options.localOnly!;
+  }
+
+  get insertOnly() {
+    return this.options.insertOnly!;
+  }
+
+  get trackPrevious() {
+    return this.options.trackPrevious!;
+  }
+
+  get trackMetadata() {
+    return this.options.trackMetadata!;
+  }
+
+  get ignoreEmptyUpdates() {
+    return this.options.ignoreEmptyUpdates!;
+  }
+
+  get internalName() {
+    if (this.options.localOnly) {
+      return `ps_data_local__${this.name}`;
+    }
+
+    return `ps_data__${this.name}`;
+  }
+
+  get validName() {
+    if (InvalidSQLCharacters.test(this.name)) {
+      return false;
+    }
+    if (this.viewNameOverride != null && InvalidSQLCharacters.test(this.viewNameOverride)) {
+      return false;
+    }
+    return true;
+  }
+
+  validate() {
+    if (InvalidSQLCharacters.test(this.name)) {
+      throw new Error(`Invalid characters in table name: ${this.name}`);
+    }
+
+    if (this.viewNameOverride && InvalidSQLCharacters.test(this.viewNameOverride!)) {
+      throw new Error(`Invalid characters in view name: ${this.viewNameOverride}`);
+    }
+
+    if (this.columns.length > MAX_AMOUNT_OF_COLUMNS) {
+      throw new Error(`Table has too many columns. The maximum number of columns is ${MAX_AMOUNT_OF_COLUMNS}.`);
+    }
+
+    if (this.trackMetadata && this.localOnly) {
+      throw new Error(`Can't include metadata for local-only tables.`);
+    }
+    if (this.trackPrevious != false && this.localOnly) {
+      throw new Error(`Can't include old values for local-only tables.`);
+    }
+
+    const columnNames = new Set<string>();
+    columnNames.add('id');
+    for (const column of this.columns) {
+      const { name: columnName } = column;
+      if (column.name === 'id') {
+        throw new Error(`An id column is automatically added, custom id columns are not supported`);
+      }
+      if (columnNames.has(columnName)) {
+        throw new Error(`Duplicate column ${columnName}`);
+      }
+      if (InvalidSQLCharacters.test(columnName)) {
+        throw new Error(`Invalid characters in column name: ${column.name}`);
+      }
+      columnNames.add(columnName);
+    }
+
+    const indexNames = new Set<string>();
+    for (const index of this.indexes) {
+      if (indexNames.has(index.name)) {
+        throw new Error(`Duplicate index ${index.name}`);
+      }
+      if (InvalidSQLCharacters.test(index.name)) {
+        throw new Error(`Invalid characters in index name: ${index.name}`);
+      }
+
+      for (const column of index.columns) {
+        if (!columnNames.has(column.name)) {
+          throw new Error(`Column ${column.name} not found for index ${index.name}`);
+        }
+      }
+
+      indexNames.add(index.name);
+    }
+  }
+
+  toJSON() {
+    const trackPrevious = this.trackPrevious;
+
+    return {
+      name: this.name,
+      view_name: this.viewName,
+      local_only: this.localOnly,
+      insert_only: this.insertOnly,
+      include_old: trackPrevious && ((trackPrevious as any).columns ?? true),
+      include_old_only_when_changed: typeof trackPrevious == 'object' && trackPrevious.onlyWhenChanged == true,
+      include_metadata: this.trackMetadata,
+      ignore_empty_update: this.ignoreEmptyUpdates,
+      columns: this.columns.map((c) => c.toJSON()),
+      indexes: this.indexes.map((e) => e.toJSON(this))
+    };
+  }
+}

package/src/db/schema/TableV2.ts

@@ -0,0 +1,9 @@
+import { ColumnsType } from './Column.js';
+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.
+*/
+export class TableV2<Columns extends ColumnsType = ColumnsType> extends Table<Columns> {}

package/src/index.ts

@@ -0,0 +1,52 @@
+export * from './client/AbstractPowerSyncDatabase.js';
+export * from './client/AbstractPowerSyncOpenFactory.js';
+export { compilableQueryWatch, CompilableQueryWatchHandler } from './client/compilableQueryWatch.js';
+export * from './client/connection/PowerSyncBackendConnector.js';
+export * from './client/connection/PowerSyncCredentials.js';
+export { MAX_OP_ID } from './client/constants.js';
+export { runOnSchemaChange } from './client/runOnSchemaChange.js';
+export * from './client/SQLOpenFactory.js';
+export * from './client/sync/bucket/BucketStorageAdapter.js';
+export * from './client/sync/bucket/CrudBatch.js';
+export { CrudEntry, OpId, UpdateType } from './client/sync/bucket/CrudEntry.js';
+export * from './client/sync/bucket/CrudTransaction.js';
+export * from './client/sync/bucket/OplogEntry.js';
+export * from './client/sync/bucket/OpType.js';
+export * from './client/sync/bucket/SqliteBucketStorage.js';
+export * from './client/sync/bucket/SyncDataBatch.js';
+export * from './client/sync/bucket/SyncDataBucket.js';
+export * from './client/sync/stream/AbstractRemote.js';
+export * from './client/sync/stream/AbstractStreamingSyncImplementation.js';
+export * from './client/sync/stream/streaming-sync-types.js';
+export * from './client/sync/sync-streams.js';
+
+export * from './client/ConnectionManager.js';
+export { ProgressWithOperations, SyncProgress } from './db/crud/SyncProgress.js';
+export * from './db/crud/SyncStatus.js';
+export * from './db/crud/UploadQueueStatus.js';
+export * from './db/DBAdapter.js';
+export * from './db/schema/Column.js';
+export * from './db/schema/Index.js';
+export * from './db/schema/IndexedColumn.js';
+export * from './db/schema/Schema.js';
+export * from './db/schema/Table.js';
+export * from './db/schema/TableV2.js';
+
+export * from './client/Query.js';
+export * from './client/triggers/sanitizeSQL.js';
+export * from './client/triggers/TriggerManager.js';
+export * from './client/watched/GetAllQuery.js';
+export * from './client/watched/processors/AbstractQueryProcessor.js';
+export * from './client/watched/processors/comparators.js';
+export * from './client/watched/processors/DifferentialQueryProcessor.js';
+export * from './client/watched/processors/OnChangeQueryProcessor.js';
+export * from './client/watched/WatchedQuery.js';
+
+export * from './utils/AbortOperation.js';
+export * from './utils/BaseObserver.js';
+export * from './utils/ControlledExecutor.js';
+export * from './utils/DataStream.js';
+export * from './utils/Logger.js';
+export * from './utils/parseQuery.js';
+
+export * from './types/types.js';

package/src/types/types.ts

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

package/src/utils/AbortOperation.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export class AbortOperation extends Error {
+  constructor(protected reason: string) {
+    super(reason);
+    // Set the prototype explicitly
+    Object.setPrototypeOf(this, AbortOperation.prototype);
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AbortOperation);
+    }
+  }
+}

package/src/utils/BaseObserver.ts

@@ -0,0 +1,41 @@
+export interface Disposable {
+  dispose: () => Promise<void> | void;
+}
+
+export type BaseListener = Record<string, ((...event: any) => any) | undefined>;
+
+export interface BaseObserverInterface<T extends BaseListener> {
+  registerListener(listener: Partial<T>): () => void;
+}
+
+export class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
+  protected listeners = new Set<Partial<T>>();
+
+  constructor() {}
+
+  dispose(): void {
+    this.listeners.clear();
+  }
+
+  /**
+   * Register a listener for updates to the PowerSync client.
+   */
+  registerListener(listener: Partial<T>): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  iterateListeners(cb: (listener: Partial<T>) => any) {
+    for (const listener of this.listeners) {
+      cb(listener);
+    }
+  }
+
+  async iterateAsyncListeners(cb: (listener: Partial<T>) => Promise<any>) {
+    for (let i of Array.from(this.listeners.values())) {
+      await cb(i);
+    }
+  }
+}

package/src/utils/ControlledExecutor.ts

@@ -0,0 +1,72 @@
+export interface ControlledExecutorOptions {
+  /**
+   * If throttling is enabled, it ensures only one task runs at a time,
+   * and only one additional task can be scheduled to run after the current task completes. The pending task will be overwritten by the latest task.
+   * Enabled by default.
+   */
+  throttleEnabled?: boolean;
+}
+
+export class ControlledExecutor<T> {
+  private task: (param: T) => Promise<void> | void;
+
+  /**
+   * Represents the currently running task, which could be a Promise or undefined if no task is running.
+   */
+  private runningTask: undefined | (Promise<void> | void);
+
+  private pendingTaskParam: T | undefined;
+
+  /**
+   * Flag to determine if throttling is enabled, which controls whether tasks are queued or run immediately.
+   */
+  private isThrottling: boolean;
+
+  private closed: boolean;
+
+  constructor(task: (param: T) => Promise<void> | void, options?: ControlledExecutorOptions) {
+    this.task = task;
+    const { throttleEnabled = true } = options ?? {};
+    this.isThrottling = throttleEnabled;
+    this.closed = false;
+  }
+
+  schedule(param: T) {
+    if (this.closed) {
+      return;
+    }
+    if (!this.isThrottling) {
+      this.task(param);
+      return;
+    }
+
+    if (this.runningTask) {
+      // set or replace the pending task param with latest one
+      this.pendingTaskParam = param;
+      return;
+    }
+
+    this.execute(param);
+  }
+
+  dispose() {
+    this.closed = true;
+
+    if (this.runningTask) {
+      this.runningTask = undefined;
+    }
+  }
+
+  private async execute(param: T) {
+    this.runningTask = this.task(param);
+    await this.runningTask;
+    this.runningTask = undefined;
+
+    if (this.pendingTaskParam) {
+      const pendingParam = this.pendingTaskParam;
+      this.pendingTaskParam = undefined;
+
+      this.execute(pendingParam);
+    }
+  }
+}