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

package/src/db/schema/Table.ts

@@ -1,18 +1,18 @@
-import {
-  BaseColumnType,
-  Column,
-  ColumnsType,
-  ColumnType,
-  ExtractColumnValueType,
-  MAX_AMOUNT_OF_COLUMNS
-} from './Column.js';
+import { Column, ColumnsType, ExtractColumnValueType } from './Column.js';
 import { Index } from './Index.js';
 import { IndexedColumn } from './IndexedColumn.js';
 import { encodeTableOptions } from './internal.js';
-import { TableV2 } from './TableV2.js';
+
+/**
+ * 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.
+ */
+const MAX_AMOUNT_OF_COLUMNS = 1999;
 
 /**
  * Options that apply both to JSON-based tables and raw tables.
+ *
+ * @public
  */
 export interface TableOrRawTableOptions {
   localOnly?: boolean;
@@ -30,6 +30,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,7 +40,10 @@ export interface TrackPreviousOptions {
   onlyWhenChanged?: boolean;
 }
 
-export interface TableOptions extends SharedTableOptions {
+/**
+ * @public
+ */
+export interface ResolvedTableOptions extends SharedTableOptions {
   /**
    * The synced table name, matching sync rules
    */
@@ -47,19 +52,27 @@ export interface TableOptions extends SharedTableOptions {
   indexes?: Index[];
 }
 
-export type RowType<T extends TableV2<any>> = {
-  [K in keyof T['columnMap']]: ExtractColumnValueType<T['columnMap'][K]>;
-} & {
-  id: string;
-};
+/**
+ * @public
+ */
+export type RowType<T extends Table<any>> =
+  T extends Table<infer Columns>
+    ? { [K in keyof Columns]: ExtractColumnValueType<Columns[K]> } & { id: string }
+    : never;
 
-export type IndexShorthand = Record<string, string[]>;
+/**
+ * @public
+ */
+export type IndexShorthand = Record<string, (string | IndexedColumn)[]>;
 
-export interface TableV2Options extends SharedTableOptions {
+/**
+ * @public
+ */
+export interface TableOptions extends SharedTableOptions {
   indexes?: IndexShorthand;
 }
 
-export const DEFAULT_TABLE_OPTIONS = {
+const DEFAULT_TABLE_OPTIONS = {
   indexes: [],
   insertOnly: false,
   localOnly: false,
@@ -68,160 +81,18 @@ export const DEFAULT_TABLE_OPTIONS = {
   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
-    });
-  }
+const InvalidSQLCharacters = /["'%,.#\s[\]]/;
 
-  /**
-   * 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
-    };
+/**
+ * A resolved table in the PowerSync schema, with all columns, index definitions and options.
+ *
+ * When constructing tables for your schema, consider using {@link Table} instead.
+ *
+ * @public
+ */
+export class ResolvedTable {
+  constructor(readonly options: ResolvedTableOptions) {
     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() {
@@ -240,16 +111,6 @@ export class Table<Columns extends ColumnsType = ColumnsType> {
     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 ?? [];
   }
@@ -356,4 +217,93 @@ export class Table<Columns extends ColumnsType = ColumnsType> {
       ...encodeTableOptions(this)
     };
   }
+
+  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;
+  }
+}
+
+/**
+ * A table with a statically-typed `Columns` record structure.
+ *
+ * This is the recommended way to declare tables in PowerSync schemas.
+ *
+ * @public
+ */
+export class Table<Columns extends ColumnsType = ColumnsType> extends ResolvedTable {
+  protected _mappedColumns!: Columns;
+
+  static createLocalOnly<Columns extends ColumnsType = ColumnsType>(columns: Columns, options?: TableOptions) {
+    return new Table(columns, { localOnly: true, insertOnly: false, ...options });
+  }
+
+  static createInsertOnly<Columns extends ColumnsType = ColumnsType>(columns: Columns, options?: TableOptions) {
+    return new Table(columns, { localOnly: false, insertOnly: true, ...options });
+  }
+
+  /**
+   * Creates a new Table instance.
+   *
+   * @param columns - A Columns object (a record of column names to column types).
+   * @param options - Optional configuration options for the table.
+   *
+   * @example
+   * ```javascript
+   * const table = new Table(
+   *   {
+   *     name: column.text,
+   *     age: column.integer
+   *   },
+   *   { indexes: { nameIndex: ['name'] } }
+   * );
+   *```
+   */
+  constructor(columns: Columns, options?: TableOptions) {
+    super(Table.optionsFromColumns<Columns>(columns, options));
+    this._mappedColumns = columns;
+  }
+
+  copyWithName(name: string): ResolvedTable {
+    return new ResolvedTable({ ...this.options, name });
+  }
+
+  private static optionsFromColumns<Columns extends ColumnsType>(
+    columns: Columns,
+    options?: TableOptions
+  ): ResolvedTableOptions {
+    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((nameOrIndexedColumn) =>
+            typeof nameOrIndexedColumn === 'string'
+              ? new IndexedColumn({
+                  name: nameOrIndexedColumn.replace(/^-/, ''),
+                  ascending: !nameOrIndexedColumn.startsWith('-')
+                })
+              : nameOrIndexedColumn
+          )
+        })
+    );
+
+    return {
+      name: '',
+      columns: convertedColumns,
+      indexes: convertedIndexes,
+      viewName: options?.viewName,
+      insertOnly: options?.insertOnly,
+      localOnly: options?.localOnly,
+      trackPrevious: options?.trackPrevious,
+      trackMetadata: options?.trackMetadata,
+      ignoreEmptyUpdates: options?.ignoreEmptyUpdates
+    };
+  }
 }

package/src/index.ts

@@ -1,63 +1,47 @@
 export * from './attachments/AttachmentContext.js';
 export * from './attachments/AttachmentErrorHandler.js';
 export * from './attachments/AttachmentQueue.js';
-export * from './attachments/AttachmentService.js';
 export * from './attachments/LocalStorageAdapter.js';
 export * from './attachments/RemoteStorageAdapter.js';
 export * from './attachments/Schema.js';
-export * from './attachments/SyncingService.js';
 export * from './attachments/WatchedAttachmentItem.js';
 
-export * from './client/AbstractPowerSyncDatabase.js';
-export * from './client/AbstractPowerSyncOpenFactory.js';
+export * from './client/CommonPowerSyncDatabase.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/SqliteBucketStorage.js';
-export * from './client/sync/stream/AbstractRemote.js';
-export * from './client/sync/stream/AbstractStreamingSyncImplementation.js';
 export * from './client/sync/stream/JsonValue.js';
 export * from './client/sync/sync-streams.js';
+export { SyncOptions, SyncStreamConnectionMethod, FetchStrategy } from './client/sync/options.js';
 
-export * from './client/ConnectionManager.js';
-export * from './db/ConnectionClosedError.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/QueryResult.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';
 
 export * from './client/Query.js';
-export { MEMORY_TRIGGER_CLAIM_MANAGER } from './client/triggers/MemoryTriggerClaimManager.js';
 export * from './client/triggers/sanitizeSQL.js';
 export * from './client/triggers/TriggerManager.js';
-export { TriggerManagerImpl } from './client/triggers/TriggerManagerImpl.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 { type Mutex } from './utils/mutex.js';
 export * from './utils/BaseObserver.js';
-export * from './utils/ControlledExecutor.js';
+export * from './utils/MetaBaseObserver.js';
 export * from './utils/Logger.js';
-export * from './utils/mutex.js';
-export * from './utils/parseQuery.js';
-export type { SimpleAsyncIterator } from './utils/stream_transform.js';
 
 export * from './types/types.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/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;
 }
 
+/**
+ * @public
+ */
 export class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
   protected listeners = new Set<Partial<T>>();
 

package/src/utils/Logger.ts

@@ -1,47 +1,102 @@
-import Logger, { type ILogger, type ILogLevel } from 'js-logger';
-
-export { GlobalLogger, ILogger, ILoggerOpts, ILogHandler, ILogLevel } from 'js-logger';
+/**
+ * @public
+ */
+export const LogLevels = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50
+} as const;
 
-const TypedLogger: ILogger = Logger as any;
+/**
+ * A log record passed to a {@link PowerSyncLogger}.
+ *
+ * @public
+ */
+export interface LogRecord {
+  /**
+   * The log level (see {@link LogLevels} for preconfigured values) for the message. Depending on how a receiving logger
+   * has been configured, messages below a configured minimum level may be ignored.
+   */
+  level: number;
 
-export const LogLevel = {
-  TRACE: TypedLogger.TRACE,
-  DEBUG: TypedLogger.DEBUG,
-  INFO: TypedLogger.INFO,
-  TIME: TypedLogger.TIME,
-  WARN: TypedLogger.WARN,
-  ERROR: TypedLogger.ERROR,
-  OFF: TypedLogger.OFF
-};
+  /**
+   * The main message to log.
+   */
+  message: string;
 
-export interface CreateLoggerOptions {
-  logLevel?: ILogLevel;
+  /**
+   * When the log message contains an error, the error causing the log.
+   *
+   * This is not guaranteed to be an `Error` instance. On the web, we might have to serialize objects across message
+   * channels and represent them as a string.
+   */
+  error?: unknown;
 }
 
 /**
- * Retrieves the base (default) logger instance.
+ * A logger used by the PowerSync SDK.
+ *
+ * This is deliberately a very simple interface, and it's not a designed to be a general-purpose logger you would use in
+ * your application. Instead, you can provide an implementation of this to PowerSync to make it use your preferred
+ * logging libraries.
  *
- * This base logger controls the default logging configuration and is shared
- * across all loggers created with `createLogger`. Adjusting settings on this
- * base logger affects all loggers derived from it unless explicitly overridden.
+ * By default, the SDK uses a {@link createConsoleLogger} instance forwarding messages to `console.log`.
  *
+ * @public
  */
-export function createBaseLogger() {
-  return Logger;
+export interface PowerSyncLogger {
+  log(record: LogRecord): void;
 }
 
 /**
- * Creates and configures a new named logger based on the base logger.
+ * @public
+ */
+export interface CreateLoggerOptions {
+  /**
+   * A prefix for messages emitted by {@link createConsoleLogger} to make them more recognizable.
+   *
+   * Defaults to `'PowerSync'`.
+   */
+  prefix: string;
+
+  /**
+   * The minimum log level to consider for messages. Defaults to {@link LogLevels.info}.
+   */
+  minLevel: number;
+}
+
+/**
+ * A very simple {@link PowerSyncLogger} implementation forwarding messages to `console.log`.
  *
- * 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.
+ * @param options - Options to configure a minimum severity of the logger or a prefix to make messages more recognizable.
+ * @public
  */
-export function createLogger(name: string, options: CreateLoggerOptions = {}): ILogger {
-  const logger = Logger.get(name);
-  if (options.logLevel) {
-    logger.setLevel(options.logLevel);
-  }
+export function createConsoleLogger(options?: Partial<CreateLoggerOptions>): PowerSyncLogger & CreateLoggerOptions {
+  const { prefix = 'PowerSync', minLevel = LogLevels.info } = options ?? {};
+
+  return {
+    prefix,
+    minLevel,
+    log({ level, message, error }) {
+      if (level < this.minLevel) return;
+
+      let emitter = console.log;
+      if (level >= LogLevels.error) {
+        emitter = console.error;
+      } else if (level >= LogLevels.warn) {
+        emitter = console.warn;
+      } else if (level >= LogLevels.info) {
+        emitter = console.info;
+      }
 
-  return logger;
+      const messageWithPrefix = `[${prefix}]: ${message}`;
+      if (error) {
+        emitter(messageWithPrefix, error);
+      } else {
+        emitter(messageWithPrefix);
+      }
+    }
+  };
 }