Merge pull request #893 from powersync-js/polish/jsdoc-mutation-returning-note

Add JSDoc comment to mutation return value behavior

Author: kobiebotha

packages/common/src/client/AbstractPowerSyncDatabase.ts

@@ -813,6 +813,10 @@ SELECT * FROM crud_entries;
    * Execute a SQL write (INSERT/UPDATE/DELETE) query
    * and optionally return results.
    *
+   * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
+   * the returned result's `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
+   * Use a `RETURNING` clause and inspect `result.rows` when you need to confirm which rows changed.
+   *
    * @param sql The SQL query to execute
    * @param parameters Optional array of parameters to bind to the query
    * @returns The query result as an object with structured key-value pairs

packages/common/src/db/DBAdapter.ts

@@ -16,7 +16,13 @@ import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
 export type QueryResult = {
   /** Represents the auto-generated row id if applicable. */
   insertId?: number;
-  /** Number of affected rows if result of a update query. */
+  /**
+   * Number of affected rows reported by SQLite for a write query.
+   *
+   * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
+   * `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
+   * Use a `RETURNING` clause and inspect `rows` when you need to confirm which rows changed.
+   */
   rowsAffected: number;
   /** if status is undefined or 0 this object will contain the query results */
   rows?: {