cleanup docs. More readonly work.

Author: stevensJourney

docs/.gitignore

@@ -19,6 +19,7 @@ npm-debug.log*
 
 docs/attachments-sdk/
 docs/common-sdk/
+docs/node-sdk/
 docs/react-native-sdk/
 docs/react-sdk/
 docs/vue-sdk/

packages/common/src/client/AbstractPowerSyncDatabase.ts

@@ -891,18 +891,18 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
 
   /**
    * Allows defining a query which can be used to build a {@link WatchedQuery}.
-   * The defined query will be executed with {@link AbstractPowerSyncDatabase.getAll}.
+   * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
    * An optional mapper function can be provided to transform the results.
    *
    * @example
    * ```javascript
    * const watchedTodos = powersync.query({
-   *    sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
-   *    parameters: [],
-   *    mapper: (row) => ({
-   *      ...row,
-   *      created_at: new Date(row.created_at as string)
-   *    })
+   *  sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
+   *  parameters: [],
+   *  mapper: (row) => ({
+   *    ...row,
+   *    created_at: new Date(row.created_at as string)
+   *  })
    * })
    * .watch()
    * // OR use .differentialWatch() for fine-grained watches.

packages/common/src/client/Query.ts

@@ -7,7 +7,7 @@ import { ComparisonWatchedQuery } from './watched/processors/OnChangeQueryProces
 import { WatchedQueryOptions } from './watched/WatchedQuery.js';
 
 /**
- * Query parameters for {@link ArrayQueryDefinition.parameters}
+ * Query parameters for {@link ArrayQueryDefinition#parameters}
  */
 export type QueryParam = string | number | boolean | null | undefined | bigint | Uint8Array;
 
@@ -17,7 +17,7 @@ export type QueryParam = string | number | boolean | null | undefined | bigint |
  */
 export interface ArrayQueryDefinition<RowType = unknown> {
   sql: string;
-  parameters?: ReadonlyArray<QueryParam>;
+  parameters?: ReadonlyArray<Readonly<QueryParam>>;
   /**
    * Maps the raw SQLite row to a custom typed object.
    * @example
@@ -63,14 +63,14 @@ export interface Query<RowType> {
    * By default the returned watched query will emit changes whenever a change to the underlying SQLite tables is made.
    * These changes might not be relevant to the query, but the query will emit a new result set.
    *
-   * A {@link StandardWatchedQueryOptions.comparator} can be provided to limit the data emissions. The watched query will still
+   * A {@link StandardWatchedQueryOptions#comparator} can be provided to limit the data emissions. The watched query will still
    * query the underlying DB on a underlying table changes, but the result will only be emitted if the comparator detects a change in the results.
    *
    * The comparator in this method is optimized and returns early as soon as it detects a change. Each data emission will correlate to a change in the result set,
    * but note that the result set will not maintain internal object references to the previous result set. If internal object references are needed,
-   * consider using {@link Query.differentialWatch} instead.
+   * consider using {@link Query#differentialWatch} instead.
    */
-  watch(options?: StandardWatchedQueryOptions<RowType>): ComparisonWatchedQuery<RowType[]>;
+  watch(options?: StandardWatchedQueryOptions<RowType>): ComparisonWatchedQuery<ReadonlyArray<Readonly<RowType>>>;
 
   /**
    * Creates a {@link WatchedQuery} which watches and emits results of the linked query.
@@ -81,8 +81,8 @@ export interface Query<RowType> {
    * If the result set is different, the watched query will emit the new result set and provide a detailed diff of the changes.
    *
    * The deep differentiation allows maintaining result set object references between result emissions.
-   * The {@link DifferentialWatchedQuery.state.data} array will contain the previous row references for unchanged rows.
-   * A detailed diff of the changes can be accessed via {@link DifferentialWatchedQuery.state.diff}.
+   * The {@link DifferentialWatchedQuery#state} `data` array will contain the previous row references for unchanged rows.
+   * A detailed diff of the changes can be accessed via {@link DifferentialWatchedQuery#state} `diff`.
    */
   differentialWatch(options?: DifferentialWatchedQueryOptions<RowType>): DifferentialWatchedQuery<RowType>;
 }

packages/common/src/client/watched/processors/DifferentialQueryProcessor.ts

@@ -20,7 +20,7 @@ export interface WatchedQueryRowDifferential<RowType> {
  * {@link WatchedQueryState.data} is of the {@link WatchedQueryDifferential} form when using the {@link IncrementalWatchMode.DIFFERENTIAL} mode.
  */
 export interface WatchedQueryDifferential<RowType> {
-  readonly added: ReadonlyArray<RowType>;
+  readonly added: ReadonlyArray<Readonly<RowType>>;
   /**
    * The entire current result set.
    * Array item object references are preserved between updates if the item is unchanged.
@@ -35,10 +35,10 @@ export interface WatchedQueryDifferential<RowType> {
    * the updated result set will be contain the same object reference, to item A, as the previous result set.
    * This is regardless of the item A's position in the updated result set.
    */
-  readonly all: ReadonlyArray<RowType>;
-  readonly removed: ReadonlyArray<RowType>;
-  readonly updated: ReadonlyArray<WatchedQueryRowDifferential<RowType>>;
-  readonly unchanged: ReadonlyArray<RowType>;
+  readonly all: ReadonlyArray<Readonly<RowType>>;
+  readonly removed: ReadonlyArray<Readonly<RowType>>;
+  readonly updated: ReadonlyArray<WatchedQueryRowDifferential<Readonly<RowType>>>;
+  readonly unchanged: ReadonlyArray<Readonly<RowType>>;
 }
 
 /**
@@ -83,7 +83,7 @@ export interface DifferentialWatchedQuerySettings<RowType> extends DifferentialW
   query: WatchCompatibleQuery<RowType[]>;
 }
 
-export interface DifferentialWatchedQueryState<RowType> extends WatchedQueryState<RowType[]> {
+export interface DifferentialWatchedQueryState<RowType> extends WatchedQueryState<ReadonlyArray<Readonly<RowType>>> {
   /**
    * The difference between the current and previous result set.
    */
@@ -96,7 +96,7 @@ type MutableDifferentialWatchedQueryState<RowType> = MutableWatchedQueryState<Ro
 };
 
 export interface DifferentialWatchedQuery<RowType>
-  extends WatchedQuery<RowType[], DifferentialWatchedQuerySettings<RowType>> {
+  extends WatchedQuery<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>> {
   readonly state: DifferentialWatchedQueryState<RowType>;
 }
 
@@ -143,7 +143,7 @@ export const DEFAULT_WATCHED_QUERY_DIFFERENTIATOR: WatchedQueryDifferentiator<an
  * @internal
  */
 export class DifferentialQueryProcessor<RowType>
-  extends AbstractQueryProcessor<RowType[], DifferentialWatchedQuerySettings<RowType>>
+  extends AbstractQueryProcessor<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>>
   implements DifferentialWatchedQuery<RowType>
 {
   readonly state: DifferentialWatchedQueryState<RowType>;

packages/react/src/QueryStore.ts

@@ -19,11 +19,7 @@ export class QueryStore {
 
   constructor(private db: AbstractPowerSyncDatabase) {}
 
-  getQuery<RowType>(
-    key: string,
-    query: WatchCompatibleQuery<RowType[]>,
-    options: AdditionalOptions
-  ): WatchedQuery<RowType[]> {
+  getQuery<RowType>(key: string, query: WatchCompatibleQuery<RowType[]>, options: AdditionalOptions) {
     if (this.cache.has(key)) {
       return this.cache.get(key) as WatchedQuery<RowType[]>;
     }

packages/react/src/hooks/suspense/useWatchedSuspenseQuery.ts

@@ -30,5 +30,10 @@ export const useWatchedSuspenseQuery = <T = any>(
   const store = getQueryStore(powerSync);
   const watchedQuery = store.getQuery(key, parsedQuery, options);
 
-  return useWatchedQuerySuspenseSubscription(watchedQuery);
+  const result = useWatchedQuerySuspenseSubscription(watchedQuery);
+  return {
+    ...result,
+    // The result above is readonly, but this API expects a mutable array
+    data: [...result.data]
+  };
 };

packages/react/src/hooks/watched/useWatchedQuery.ts

@@ -41,5 +41,11 @@ export const useWatchedQuery = <RowType = unknown>(
     }
   }, [queryChanged]);
 
-  return useWatchedQuerySubscription(watchedQuery);
+  const result = useWatchedQuerySubscription(watchedQuery);
+  return {
+    ...result,
+    // The Watched Query API returns readonly arrays,
+    // This allows compatibility with the hook API.
+    data: [...result.data]
+  };
 };

packages/react/tests/useQuery.test.tsx

@@ -315,7 +315,9 @@ describe('useQuery', () => {
     // This query can be instantiated once and reused.
     // The query retains it's state and will not re-fetch the data unless the result changes.
     // This is useful for queries that are used in multiple components.
-    const listsQuery = db.query({ sql: `SELECT * FROM lists`, parameters: [] }).differentialWatch();
+    const listsQuery = db
+      .query<{ id: string; name: string }>({ sql: `SELECT * FROM lists`, parameters: [] })
+      .differentialWatch();
 
     const wrapper = ({ children }) => <PowerSyncContext.Provider value={db}>{children}</PowerSyncContext.Provider>;
     const { result } = renderHook(() => useWatchedQuerySubscription(listsQuery), {

packages/vue/src/composables/useWatchedQuery.ts

@@ -72,7 +72,8 @@ export const useWatchedQuery = <T = any>(
       onStateChange: (state) => {
         isLoading.value = state.isLoading;
         isFetching.value = state.isFetching;
-        data.value = state.data;
+        // The watched query state is readonly
+        data.value = [...state.data];
         if (state.error) {
           const wrappedError = new Error('PowerSync failed to fetch data: ' + state.error.message);
           wrappedError.cause = state.error;