cleanup readme and docs

Author: stevensJourney

packages/common/src/client/Query.ts

@@ -12,8 +12,8 @@ import { WatchedQueryOptions } from './watched/WatchedQuery.js';
 export type QueryParam = string | number | boolean | null | undefined | bigint | Uint8Array;
 
 /**
- * Options for building a query with {@link AbstractPowerSyncDatabase.query}.
- * This query will be executed with {@link AbstractPowerSyncDatabase.getAll}.
+ * Options for building a query with {@link AbstractPowerSyncDatabase#query}.
+ * This query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
  */
 export interface ArrayQueryDefinition<RowType = unknown> {
   sql: string;
@@ -37,7 +37,7 @@ export interface ArrayQueryDefinition<RowType = unknown> {
 export interface StandardWatchedQueryOptions<RowType> extends WatchedQueryOptions {
   /**
    * Optional comparator which processes the items of an array of rows.
-   * The comparator compares the result set rows by index using the {@link ArrayComparatorOptions.compareBy} function.
+   * The comparator compares the result set rows by index using the {@link ArrayComparatorOptions#compareBy} function.
    * The comparator reports a changed result set as soon as a row does not match the previous result set.
    *
    * @example
@@ -64,7 +64,7 @@ export interface Query<RowType> {
    * 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
-   * 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.
+   * query the underlying DB on 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,

packages/react/README.md

@@ -357,7 +357,7 @@ function MyWidget() {
   return (
     // Other components
     // The data array is the same reference if no changes have occurred between fetches
-    // Note: The array is a new reference is there are any changes in the result set (individual row object references are not preserved)
+    // Note: The array is a new reference is there are any changes in the result set (individual row object references are preserved for unchanged rows)
     // Note: CatCollection requires memoization in order to prevent re-rendering (due to the parent re-rendering on fetch)
     <CatCollection cats={data}>
   )

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

@@ -23,7 +23,12 @@ import { createSuspendingPromise, useTemporaryHold } from './suspense-utils';
  * );
  * }
  */
-export const useWatchedQuerySuspenseSubscription = <ResultType>(query: WatchedQuery<ResultType>) => {
+export const useWatchedQuerySuspenseSubscription = <
+  ResultType = unknown,
+  Query extends WatchedQuery<ResultType> = WatchedQuery<ResultType>
+>(
+  query: Query
+): Query['state'] => {
   const { releaseHold } = useTemporaryHold(query);
 
   // Force update state function
@@ -53,12 +58,7 @@ export const useWatchedQuerySuspenseSubscription = <ResultType>(query: WatchedQu
     throw query.state.error;
   } else if (!query.state.isLoading) {
     // Happy path data return
-    return {
-      data: query.state.data,
-      refresh: async () => {
-        // no-op for watched queries
-      }
-    };
+    return query.state;
   } else {
     // Notify suspense is required
     throw createSuspendingPromise(query);

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

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

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

@@ -1,4 +1,4 @@
-import { WatchedQuery, WatchedQueryState } from '@powersync/common';
+import { WatchedQuery } from '@powersync/common';
 import React from 'react';
 
 /**
@@ -15,9 +15,12 @@ import React from 'react';
  * }
  *
  */
-export const useWatchedQuerySubscription = <ResultType = unknown>(
-  query: WatchedQuery<ResultType>
-): WatchedQueryState<ResultType> => {
+export const useWatchedQuerySubscription = <
+  ResultType = unknown,
+  Query extends WatchedQuery<ResultType> = WatchedQuery<ResultType>
+>(
+  query: Query
+): Query['state'] => {
   const [output, setOutputState] = React.useState(query.state);
 
   React.useEffect(() => {