From b3bcf01561b4f3e4a56c506e1b5beb67a25576db Mon Sep 17 00:00:00 2001
From: benitav <benita@journeyapps.com>
Date: Thu, 8 Feb 2024 13:17:36 +0200
Subject: [PATCH 1/9] First pass of porting comments from FLutter into
 sdk-common

---
 .../src/client/AbstractPowerSyncDatabase.ts   | 45 ++++++++++++++++++-
 .../client/AbstractPowerSyncOpenFactory.ts    |  3 ++
 .../src/client/sync/bucket/CrudBatch.ts       | 12 +++++
 .../src/client/sync/bucket/CrudEntry.ts       | 27 +++++++++++
 .../src/client/sync/bucket/CrudTransaction.ts | 12 +++++
 .../client/sync/bucket/SqliteBucketStorage.ts |  2 -
 .../src/db/crud/SyncStatus.ts                 |  9 ++++
 .../src/db/crud/UploadQueueStatus.ts          |  6 +++
 8 files changed, 112 insertions(+), 4 deletions(-)

diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index bad6431b..958cbce6 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -114,14 +114,25 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     this._isReadyPromise = this.initialize();
   }
 
+  /**
+   * Schema used for the local database.
+   */
   get schema() {
     return this._schema;
   }
 
+  /**
+   * The underlying database.
+   * 
+   * For the most part, behavior is the same whether querying on the underlying database, or on [AbstractPowerSyncDatabase]. The main difference is in update notifications: the underlying database reports updates to the underlying tables, while AbstractPowerSyncDatabase reports updates to the higher-level views.
+   */
   protected get database() {
     return this.options.database;
   }
 
+  /**
+   * Whether a connection to the PowerSync service is currently open.
+   */
   get connected() {
     return this.currentStatus?.connected || false;
   }
@@ -163,6 +174,11 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     this.iterateListeners((cb) => cb.initialized?.());
   }
 
+  /**
+   * Replace the schema with a new version. This is for advanced use cases - typically the schema should just be specified once in the constructor.
+   * 
+   * Cannot be used while connected - this should only be called before [AbstractPowerSyncDatabase.connect].
+   */
   async updateSchema(schema: Schema) {
     if (this.abortController) {
       throw new Error('Cannot update schema while connected');
@@ -226,6 +242,11 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     this.watchCrudUploads();
   }
 
+  /**
+   * Close the sync connection.
+   * 
+   * Use [connect] to connect again.
+   */
   async disconnect() {
     this.abortController?.abort();
     this.syncStatusListenerDisposer?.();
@@ -237,6 +258,8 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    *  Use this when logging out.
    *  The database can still be queried after this is called, but the tables
    *  would be empty.
+   * 
+   * To preserve data in local-only tables, set clearLocal to false.
    */
   async disconnectAndClear(options = DEFAULT_DISCONNECT_CLEAR_OPTIONS) {
     await this.disconnect();
@@ -307,7 +330,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    *
    * Returns null if there is no data to upload.
    *
-   * Use this from the [PowerSyncBackendConnector.uploadData]` callback.
+   * Use this from the [PowerSyncBackendConnector.uploadData] callback.
    *
    * Once the data have been successfully uploaded, call [CrudBatch.complete] before
    * requesting the next batch.
@@ -446,7 +469,6 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * Takes a read lock, without starting a transaction.
-   *
    * In most cases, [readTransaction] should be used instead.
    */
   async readLock<T>(callback: (db: DBAdapter) => Promise<T>) {
@@ -466,6 +488,12 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     });
   }
 
+  /**
+   * Open a read-only transaction.
+   * TODO: Up to maxReaders read transactions can run concurrently. After that, read transactions are queued.
+   * Read transactions can run concurrently to a write transaction.
+   * Changes from any write transaction are not visible to read transactions started before it.
+   */
   async readTransaction<T>(
     callback: (tx: Transaction) => Promise<T>,
     lockTimeout: number = DEFAULT_LOCK_TIMEOUT_MS
@@ -481,6 +509,11 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     );
   }
 
+  /**
+   * Open a read-write transaction.
+   * This takes a global lock - only one write transaction can execute against the database at a time.
+   * TODO: Statements within the transaction must be done on the provided SqliteWriteContext - attempting statements on the SqliteConnection instance will error.
+   */
   async writeTransaction<T>(
     callback: (tx: Transaction) => Promise<T>,
     lockTimeout: number = DEFAULT_LOCK_TIMEOUT_MS
@@ -496,6 +529,11 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     );
   }
 
+  /**
+   * Execute a read query every time the source tables are modified.
+   * TODO: Use throttle to specify the minimum interval between queries.
+   * TODO: Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
+   */
   async *watch(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult> {
     //Fetch initial data
     yield await this.executeReadOnly(sql, parameters);
@@ -582,6 +620,9 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     });
   }
 
+  /**
+   * TODO
+   */
   private async executeReadOnly(sql: string, params: any[]) {
     await this.waitForReady();
     return this.database.readLock((tx) => tx.execute(sql, params));
diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts
index 7d7e8ab0..dfaa1e9d 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts
@@ -20,6 +20,9 @@ export abstract class AbstractPowerSyncDatabaseOpenFactory {
     options.logger = options.logger ?? Logger.get(`PowerSync ${this.options.dbFilename}`);
   }
 
+  /**
+   * Schema used for the local database.
+   */
   get schema() {
     return this.options.schema;
   }
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
index 51ac45fc..683f56fb 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
@@ -1,9 +1,21 @@
 import { CrudEntry } from './CrudEntry';
 
+/**
+ * TODO
+ */
 export class CrudBatch {
   constructor(
+    /**
+     * List of client-side changes.
+     */
     public crud: CrudEntry[],
+    /**
+     * true if there are more changes in the local queue.
+     */
     public haveMore: boolean,
+    /**
+     * Call to remove the changes from the local queue, once successfully uploaded.
+     */
     public complete: (writeCheckpoint?: string) => Promise<void>
   ) {}
 }
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts
index 25732ae7..a12fe3d0 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts
@@ -38,12 +38,33 @@ export type CrudEntryOutputJSON = {
   data: Record<string, any>;
 };
 
+/**
+ * A single client-side change.
+ */
 export class CrudEntry {
+  /**
+   * Auto-incrementing client-side id.
+   */
   clientId: number;
+  /**
+   * ID of the changed row.
+   */
   id: string;
+  /**
+   * Type of change.
+   */
   op: UpdateType;
+  /**
+   * Data associated with the change.
+   */
   opData?: Record<string, any>;
+  /**
+   * Table that contained the change.
+   */
   table: string;
+  /**
+   * Auto-incrementing transaction id. This is the same for all operations within the same transaction.
+   */
   transactionId?: number;
 
   static fromRow(dbRow: CrudEntryJSON) {
@@ -67,6 +88,9 @@ export class CrudEntry {
     this.transactionId = transactionId;
   }
 
+  /**
+   * TODO: Converts the change to JSON format, as required by the dev crud API.
+   */
   toJSON(): CrudEntryOutputJSON {
     return {
       op_id: this.clientId,
@@ -78,6 +102,9 @@ export class CrudEntry {
     };
   }
 
+  /**
+   * The hash code for this object.
+   */
   hashCode() {
     return hash([this.transactionId, this.clientId, this.op, this.table, this.id, this.opData]);
   }
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
index 1a726b23..ad5f6ee9 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
@@ -1,10 +1,22 @@
 import { CrudBatch } from './CrudBatch';
 import { CrudEntry } from './CrudEntry';
 
+/**
+ * TODO
+ */
 export class CrudTransaction extends CrudBatch {
   constructor(
+    /**
+     * List of client-side changes.
+     */
     public crud: CrudEntry[],
+    /**
+     * Call to remove the changes from the local queue, once successfully uploaded.
+     */
     public complete: (checkpoint?: string) => Promise<void>,
+    /**
+     * Unique transaction id.
+     */
     public transactionId?: number
   ) {
     super(crud, false, complete);
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/SqliteBucketStorage.ts b/packages/powersync-sdk-common/src/client/sync/bucket/SqliteBucketStorage.ts
index 6a0310d2..0c727ee9 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/SqliteBucketStorage.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/SqliteBucketStorage.ts
@@ -80,8 +80,6 @@ export class SqliteBucketStorage implements BucketStorageAdapter {
 
   /**
    * Mark a bucket for deletion.
-   *
-   * @param bucket
    */
   private async deleteBucket(bucket: string) {
     // Delete a bucket, but allow it to be re-created.
diff --git a/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts b/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
index e4d5e14f..a5f30bf1 100644
--- a/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
+++ b/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
@@ -14,14 +14,23 @@ export type SyncStatusOptions = {
 export class SyncStatus {
   constructor(protected options: SyncStatusOptions) {}
 
+  /**
+   * true if currently connected.
+   */
   get connected() {
     return this.options.connected ?? false;
   }
 
+  /**
+   * TODO
+   */
   get lastSyncedAt() {
     return this.options.lastSyncedAt;
   }
 
+  /**
+   * TODO
+   */
   get dataFlowStatus() {
     return (
       this.options.dataFlow ?? {
diff --git a/packages/powersync-sdk-common/src/db/crud/UploadQueueStatus.ts b/packages/powersync-sdk-common/src/db/crud/UploadQueueStatus.ts
index 8ad7e5d2..53fcde73 100644
--- a/packages/powersync-sdk-common/src/db/crud/UploadQueueStatus.ts
+++ b/packages/powersync-sdk-common/src/db/crud/UploadQueueStatus.ts
@@ -1,6 +1,12 @@
 export class UploadQueueStats {
   constructor(
+    /**
+     * Number of records in the upload queue.
+     */
     public count: number,
+    /**
+     * Size of the upload queue in bytes.
+     */
     public size: number = null
   ) {}
 

From 9142c2c2f773f678fce0e970a9955ac228b875e8 Mon Sep 17 00:00:00 2001
From: benitav <benitav@users.noreply.github.com>
Date: Thu, 8 Feb 2024 14:48:25 +0200
Subject: [PATCH 2/9] Update
 packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts

---
 .../powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts
index a12fe3d0..481104c9 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudEntry.ts
@@ -89,7 +89,7 @@ export class CrudEntry {
   }
 
   /**
-   * TODO: Converts the change to JSON format, as required by the dev crud API.
+   * Converts the change to JSON format.
    */
   toJSON(): CrudEntryOutputJSON {
     return {

From 2af28217602b73f358dccc81384002c5a6361b9c Mon Sep 17 00:00:00 2001
From: benitav <benita@journeyapps.com>
Date: Thu, 8 Feb 2024 15:41:01 +0200
Subject: [PATCH 3/9] More JSDoc comments

---
 .../src/hooks/usePowerSyncQuery.ts            |  2 +-
 .../src/client/AbstractPowerSyncDatabase.ts   |  6 ++++--
 .../client/AbstractPowerSyncOpenFactory.ts    |  1 +
 .../connection/PowerSyncBackendConnector.ts   |  2 +-
 .../powersync-sdk-common/src/db/DBAdapter.ts  | 20 +++++++++++--------
 5 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/packages/powersync-react/src/hooks/usePowerSyncQuery.ts b/packages/powersync-react/src/hooks/usePowerSyncQuery.ts
index 0fed38d0..955736dd 100644
--- a/packages/powersync-react/src/hooks/usePowerSyncQuery.ts
+++ b/packages/powersync-react/src/hooks/usePowerSyncQuery.ts
@@ -3,7 +3,7 @@ import { usePowerSync } from './PowerSyncContext';
 
 /**
  * A hook to access a single static query.
- * For an updated result, use usePowerSyncWatchedQuery instead
+ * For an updated result, use {@link usePowerSyncWatchedQuery} instead
  */
 export const usePowerSyncQuery = <T = any>(sqlStatement: string, parameters: any[] = []): T[] => {
   const powerSync = usePowerSync();
diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index 958cbce6..425af11d 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -21,10 +21,12 @@ import { EventIterator } from 'event-iterator';
 import { quoteIdentifier } from '../utils/strings';
 
 export interface DisconnectAndClearOptions {
+  /** When set to false, data in local-only tables is preserved. */
   clearLocal?: boolean;
 }
 
 export interface PowerSyncDatabaseOptions {
+  /** Schema used for the local database. */
   schema: Schema;
   database: DBAdapter;
   /**
@@ -436,7 +438,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   }
 
   /**
-   * Execute a statement and optionally return results
+   * Execute a statement and optionally return results.
    */
   async execute(sql: string, parameters?: any[]) {
     await this.waitForReady();
@@ -444,7 +446,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   }
 
   /**
-   *  Execute a read-only query and return results
+   *  Execute a read-only query and return results.
    */
   async getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
     await this.waitForReady();
diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts
index dfaa1e9d..2273605e 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncOpenFactory.ts
@@ -4,6 +4,7 @@ import { Schema } from '../db/schema/Schema';
 import { AbstractPowerSyncDatabase, PowerSyncDatabaseOptions } from './AbstractPowerSyncDatabase';
 
 export interface PowerSyncOpenFactoryOptions extends Partial<PowerSyncDatabaseOptions> {
+  /** Schema used for the local database. */
   schema: Schema;
   /**
    * Filename for the database.
diff --git a/packages/powersync-sdk-common/src/client/connection/PowerSyncBackendConnector.ts b/packages/powersync-sdk-common/src/client/connection/PowerSyncBackendConnector.ts
index 10c9ae11..131f3024 100644
--- a/packages/powersync-sdk-common/src/client/connection/PowerSyncBackendConnector.ts
+++ b/packages/powersync-sdk-common/src/client/connection/PowerSyncBackendConnector.ts
@@ -16,7 +16,7 @@ export interface PowerSyncBackendConnector {
 
   /** Upload local changes to the app backend.
    *
-   * Use [PowerSyncDatabase.getCrudBatch] to get a batch of changes to upload. See [DevConnector] for an example implementation.
+   * Use {@link AbstractPowerSyncDatabase.getCrudBatch} to get a batch of changes to upload. 
    *
    * Any thrown errors will result in a retry after the configured wait period (default: 5 seconds).
    */
diff --git a/packages/powersync-sdk-common/src/db/DBAdapter.ts b/packages/powersync-sdk-common/src/db/DBAdapter.ts
index 26aba198..159c2aed 100644
--- a/packages/powersync-sdk-common/src/db/DBAdapter.ts
+++ b/packages/powersync-sdk-common/src/db/DBAdapter.ts
@@ -11,18 +11,14 @@ import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver';
  */
 
 /**
- * Object returned by SQL Query executions {
- *  insertId: Represent the auto-generated row id if applicable
- *  rowsAffected: Number of affected rows if result of a update query
- *  message: if status === 1, here you will find error description
- *  rows: if status is undefined or 0 this object will contain the query results
- * }
- *
- * @interface QueryResult
+ * Object returned by SQL Query executions.
  */
 export type QueryResult = {
+  /** Represents the auto-generated row id if applicable. */
   insertId?: number;
+  /** Number of affected rows if result of a update query. */
   rowsAffected: number;
+  /** if status is undefined or 0 this object will contain the query results */
   rows?: {
     /** Raw array with all dataset */
     _array: any[];
@@ -37,12 +33,16 @@ export type QueryResult = {
 };
 
 export interface DBGetUtils {
+  /** Execute a read-only query and return results. */
   getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
+  /** Execute a read-only query and return the first result, or null if the ResultSet is empty. */
   getOptional<T>(sql: string, parameters?: any[]): Promise<T | null>;
+  /** Execute a read-only query and return the first result, error if the ResultSet is empty. */
   get<T>(sql: string, parameters?: any[]): Promise<T>;
 }
 
 export interface LockContext extends DBGetUtils {
+  /** Execute a statement and optionally return results. */
   execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
 }
 
@@ -63,6 +63,10 @@ export interface TableUpdateOperation {
   opType: RowUpdateType;
   rowId: number;
 }
+
+/**
+ * Notification of an update to one or more tables, for the purpose of realtime change notifications.
+ */
 export interface UpdateNotification extends TableUpdateOperation {
   table: string;
 }

From 2fbded17fa3d4068266e16374257beac15f8bbc6 Mon Sep 17 00:00:00 2001
From: benitav <benita@journeyapps.com>
Date: Thu, 8 Feb 2024 16:01:34 +0200
Subject: [PATCH 4/9] Valid JSdoc links

---
 .../src/client/AbstractPowerSyncDatabase.ts   | 22 +++++++++----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index 425af11d..31594596 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -247,7 +247,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   /**
    * Close the sync connection.
    * 
-   * Use [connect] to connect again.
+   * Use {@link connect} to connect again.
    */
   async disconnect() {
     this.abortController?.abort();
@@ -295,7 +295,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   /*
    * Close the database, releasing resources.
    *
-   * Also [disconnect]s any active connection.
+   * Also disconnects any active connection.
    *
    * Once close is called, this connection cannot be used again - a new one
    * must be constructed.
@@ -332,12 +332,12 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    *
    * Returns null if there is no data to upload.
    *
-   * Use this from the [PowerSyncBackendConnector.uploadData] callback.
+   * Use this from the {@link PowerSyncBackendConnector.uploadData} callback.
    *
-   * Once the data have been successfully uploaded, call [CrudBatch.complete] before
+   * Once the data have been successfully uploaded, call {@link CrudBatch.complete} before
    * requesting the next batch.
    *
-   * Use [limit] to specify the maximum number of updates to return in a single
+   * Use {@link limit} to specify the maximum number of updates to return in a single
    * batch.
    *
    * This method does include transaction ids in the result, but does not group
@@ -383,12 +383,12 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    *
    * Returns null if there is no data to upload.
    *
-   * Use this from the [PowerSyncBackendConnector.uploadData]` callback.
+   * Use this from the {@link PowerSyncBackendConnector.uploadData} callback.
    *
-   * Once the data have been successfully uploaded, call [CrudTransaction.complete] before
+   * Once the data have been successfully uploaded, call {@link CrudTransaction.complete} before
    * requesting the next transaction.
    *
-   * Unlike [getCrudBatch], this only returns data from a single transaction at a time.
+   * Unlike {@link getCrudBatch}, this only returns data from a single transaction at a time.
    * All data for the transaction is loaded into memory.
    */
   async getNextCrudTransaction(): Promise<CrudTransaction> {
@@ -471,7 +471,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * Takes a read lock, without starting a transaction.
-   * In most cases, [readTransaction] should be used instead.
+   * In most cases, {@link readTransaction} should be used instead.
    */
   async readLock<T>(callback: (db: DBAdapter) => Promise<T>) {
     await this.waitForReady();
@@ -480,7 +480,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * Takes a global lock, without starting a transaction.
-   * In most cases, [writeTransaction] should be used instead.
+   * In most cases, {@link writeTransaction} should be used instead.
    */
   async writeLock<T>(callback: (db: DBAdapter) => Promise<T>) {
     await this.waitForReady();
@@ -564,7 +564,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   /**
    * Create a Stream of changes to any of the specified tables.
    *
-   * This is preferred over [watch] when multiple queries need to be performed
+   * This is preferred over {@link watch} when multiple queries need to be performed
    * together when data is changed.
    *
    * Note, do not declare this as `async *onChange` as it will not work in React Native

From 2c1a0ab418459f38fa9d9d152a2300c1e33653b5 Mon Sep 17 00:00:00 2001
From: benitav <benita@journeyapps.com>
Date: Thu, 8 Feb 2024 16:10:17 +0200
Subject: [PATCH 5/9] Another link

---
 .../src/client/AbstractPowerSyncDatabase.ts                   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index 31594596..92df3c43 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -126,7 +126,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   /**
    * The underlying database.
    * 
-   * For the most part, behavior is the same whether querying on the underlying database, or on [AbstractPowerSyncDatabase]. The main difference is in update notifications: the underlying database reports updates to the underlying tables, while AbstractPowerSyncDatabase reports updates to the higher-level views.
+   * For the most part, behavior is the same whether querying on the underlying database, or on {@link AbstractPowerSyncDatabase}. The main difference is in update notifications: the underlying database reports updates to the underlying tables, while AbstractPowerSyncDatabase reports updates to the higher-level views.
    */
   protected get database() {
     return this.options.database;
@@ -179,7 +179,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   /**
    * Replace the schema with a new version. This is for advanced use cases - typically the schema should just be specified once in the constructor.
    * 
-   * Cannot be used while connected - this should only be called before [AbstractPowerSyncDatabase.connect].
+   * Cannot be used while connected - this should only be called before {@link AbstractPowerSyncDatabase.connect}.
    */
   async updateSchema(schema: Schema) {
     if (this.abortController) {

From 4d46bd0196d94e0bc0c8da2eed97adb700c0c123 Mon Sep 17 00:00:00 2001
From: benitav <benitav@users.noreply.github.com>
Date: Thu, 8 Feb 2024 17:37:04 +0200
Subject: [PATCH 6/9] Apply suggestions from code review

Co-authored-by: stevensJourney <51082125+stevensJourney@users.noreply.github.com>
---
 .../src/client/AbstractPowerSyncDatabase.ts                    | 2 +-
 .../powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts   | 2 +-
 .../src/client/sync/bucket/CrudTransaction.ts                  | 2 +-
 packages/powersync-sdk-common/src/db/crud/SyncStatus.ts        | 3 ++-
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index 92df3c43..c395f820 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -126,7 +126,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   /**
    * The underlying database.
    * 
-   * For the most part, behavior is the same whether querying on the underlying database, or on {@link AbstractPowerSyncDatabase}. The main difference is in update notifications: the underlying database reports updates to the underlying tables, while AbstractPowerSyncDatabase reports updates to the higher-level views.
+   * For the most part, behavior is the same whether querying on the underlying database, or on {@link AbstractPowerSyncDatabase}.
    */
   protected get database() {
     return this.options.database;
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
index 683f56fb..4aa2b328 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
@@ -1,7 +1,7 @@
 import { CrudEntry } from './CrudEntry';
 
 /**
- * TODO
+* A batch of client-side changes.
  */
 export class CrudBatch {
   constructor(
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
index ad5f6ee9..7b81ec8c 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
@@ -15,7 +15,7 @@ export class CrudTransaction extends CrudBatch {
      */
     public complete: (checkpoint?: string) => Promise<void>,
     /**
-     * Unique transaction id.
+     * If null, this contains a list of changes recorded without an explicit transaction associated.
      */
     public transactionId?: number
   ) {
diff --git a/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts b/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
index a5f30bf1..1241ab42 100644
--- a/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
+++ b/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
@@ -22,7 +22,8 @@ export class SyncStatus {
   }
 
   /**
-   * TODO
+   *  Time that a last sync has fully completed, if any.
+   *  Currently this is reset to null after a restart.
    */
   get lastSyncedAt() {
     return this.options.lastSyncedAt;

From c6639d3c705d41a1dab38d83d13f475418750a21 Mon Sep 17 00:00:00 2001
From: benitav <benita@journeyapps.com>
Date: Thu, 8 Feb 2024 17:48:22 +0200
Subject: [PATCH 7/9] Resolve TODOs

---
 .../src/client/AbstractPowerSyncDatabase.ts              | 8 +++-----
 .../src/client/sync/bucket/CrudTransaction.ts            | 3 ---
 packages/powersync-sdk-common/src/db/crud/SyncStatus.ts  | 9 ++++++++-
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index c395f820..7cfa8901 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -46,6 +46,7 @@ export interface PowerSyncDatabaseOptions {
 export interface SQLWatchOptions {
   signal?: AbortSignal;
   tables?: string[];
+  /** The minimum interval between queries. */
   throttleMs?: number;
   /**
    * Allows for watching any SQL table
@@ -533,8 +534,8 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * Execute a read query every time the source tables are modified.
-   * TODO: Use throttle to specify the minimum interval between queries.
-   * TODO: Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
+   * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
+   * Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
    */
   async *watch(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult> {
     //Fetch initial data
@@ -622,9 +623,6 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     });
   }
 
-  /**
-   * TODO
-   */
   private async executeReadOnly(sql: string, params: any[]) {
     await this.waitForReady();
     return this.database.readLock((tx) => tx.execute(sql, params));
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
index 7b81ec8c..8b2955f8 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudTransaction.ts
@@ -1,9 +1,6 @@
 import { CrudBatch } from './CrudBatch';
 import { CrudEntry } from './CrudEntry';
 
-/**
- * TODO
- */
 export class CrudTransaction extends CrudBatch {
   constructor(
     /**
diff --git a/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts b/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
index 1241ab42..49047503 100644
--- a/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
+++ b/packages/powersync-sdk-common/src/db/crud/SyncStatus.ts
@@ -30,12 +30,19 @@ export class SyncStatus {
   }
 
   /**
-   * TODO
+   *  Upload/download status
    */
   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
       }
     );

From 1158be11c5fac05b4831a91b9265fa9061f49643 Mon Sep 17 00:00:00 2001
From: benitav <benitav@users.noreply.github.com>
Date: Thu, 8 Feb 2024 17:49:32 +0200
Subject: [PATCH 8/9] Update
 packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts

---
 .../powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index 7cfa8901..d911e683 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -493,7 +493,6 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * Open a read-only transaction.
-   * TODO: Up to maxReaders read transactions can run concurrently. After that, read transactions are queued.
    * Read transactions can run concurrently to a write transaction.
    * Changes from any write transaction are not visible to read transactions started before it.
    */

From 74e966d74e9d96b88e32525638e2ed5045ffb98e Mon Sep 17 00:00:00 2001
From: benitav <benita@journeyapps.com>
Date: Thu, 8 Feb 2024 17:52:51 +0200
Subject: [PATCH 9/9] More polishes

---
 .../src/client/AbstractPowerSyncDatabase.ts                     | 2 +-
 .../powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
index 7cfa8901..33d33b24 100644
--- a/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
+++ b/packages/powersync-sdk-common/src/client/AbstractPowerSyncDatabase.ts
@@ -515,7 +515,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
   /**
    * Open a read-write transaction.
    * This takes a global lock - only one write transaction can execute against the database at a time.
-   * TODO: Statements within the transaction must be done on the provided SqliteWriteContext - attempting statements on the SqliteConnection instance will error.
+   * Statements within the transaction must be done on the provided {@link Transaction} interface.
    */
   async writeTransaction<T>(
     callback: (tx: Transaction) => Promise<T>,
diff --git a/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts b/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
index 4aa2b328..6891f24e 100644
--- a/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
+++ b/packages/powersync-sdk-common/src/client/sync/bucket/CrudBatch.ts
@@ -1,7 +1,7 @@
 import { CrudEntry } from './CrudEntry';
 
 /**
-* A batch of client-side changes.
+ * A batch of client-side changes.
  */
 export class CrudBatch {
   constructor(