Incremental Watched Queries (#614)

Author: stevensJourney

.changeset/little-bananas-fetch.md

@@ -0,0 +1,7 @@
+---
+'@powersync/common': minor
+---
+
+- Added additional listeners for `closing` and `closed` events in `AbstractPowerSyncDatabase`.
+- Added `query` and `customQuery` APIs for enhanced watched queries.
+- Added `triggerImmediate` option to the `onChange` API. This allows emitting an initial event which can be useful for downstream use cases.

.changeset/nine-pens-ring.md

@@ -0,0 +1,43 @@
+---
+'@powersync/vue': minor
+---
+
+[Potentially breaking change] The `useQuery` hook results are now explicitly defined as readonly. These values should not be mutated.
+
+- Added the ability to limit re-renders by specifying a `rowComparator` for query results. The `useQuery` hook will only emit `data` changes when the data has changed.
+
+```javascript
+// The data here will maintain previous object references for unchanged items.
+const { data } = useQuery('SELECT * FROM lists WHERE name = ?', ['aname'], {
+  rowComparator: {
+    keyBy: (item) => item.id,
+    compareBy: (item) => JSON.stringify(item)
+  }
+});
+```
+
+- Added the ability to subscribe to an existing instance of a `WatchedQuery`
+
+```vue
+<script setup>
+import { useWatchedQuerySubscription } from '@powersync/vue';
+
+const listsQuery = powerSync
+  .query({
+    sql: `SELECT * FROM lists`
+  })
+  .differentialWatch();
+
+const { data, isLoading, isFetching, error } = useWatchedQuerySubscription(listsQuery);
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="isFetching">Updating results...</div>
+
+  <div v-if="error">{{ error }}</div>
+  <ul v-else>
+    <li v-for="l in data" :key="l.id">{{ l.name }}</li>
+  </ul>
+</template>
+```

.changeset/plenty-rice-protect.md

@@ -0,0 +1,6 @@
+---
+'@powersync/react': minor
+'@powersync/vue': minor
+---
+
+- [Internal] Updated implementation to use shared `WatchedQuery` implementation.

.changeset/stale-dots-jog.md

@@ -0,0 +1,5 @@
+---
+'@powersync/web': minor
+---
+
+Improved query behaviour when client is closed. Pending requests will be aborted, future requests will be rejected with an Error. Fixed read and write lock requests not respecting timeout parameter.

.changeset/swift-guests-explain.md

@@ -0,0 +1,39 @@
+---
+'@powersync/react': minor
+---
+
+- Added the ability to limit re-renders by specifying a `rowComparator` for query results. The `useQuery` hook will only emit `data` changes when the data has changed.
+
+```javascript
+// The data here will maintain previous object references for unchanged items.
+const { data } = useQuery('SELECT * FROM lists WHERE name = ?', ['aname'], {
+  rowComparator: {
+    keyBy: (item) => item.id,
+    compareBy: (item) => JSON.stringify(item)
+  }
+});
+```
+
+- Added the ability to subscribe to an existing instance of a `WatchedQuery`
+
+```jsx
+import { useWatchedQuerySubscription } from '@powersync/react';
+
+const listsQuery = powerSync
+  .query({
+    sql: `SELECT * FROM lists`
+  })
+  .differentialWatch();
+
+export const ListsWidget = (props) => {
+  const { data: lists } = useWatchedQuerySubscription(listsQuery);
+
+  return (
+    <div>
+      {lists.map((list) => (
+        <div key={list.id}>{list.name}</div>
+      ))}
+    </div>
+  );
+};
+```

.prettierrc

@@ -5,5 +5,6 @@
   "jsxBracketSameLine": true,
   "useTabs": false,
   "printWidth": 120,
-  "trailingComma": "none"
+  "trailingComma": "none",
+  "plugins": ["prettier-plugin-embed", "prettier-plugin-sql"]
 }

demos/react-supabase-todolist/src/app/views/sql-console/page.tsx

@@ -1,34 +1,73 @@
-import React from 'react';
-import { useQuery } from '@powersync/react';
-import { Box, Button, Grid, TextField, styled } from '@mui/material';
-import { DataGrid } from '@mui/x-data-grid';
 import { NavigationPage } from '@/components/navigation/NavigationPage';
+import { Alert, Box, Button, Grid, TextField, styled } from '@mui/material';
+import { DataGrid } from '@mui/x-data-grid';
+import { useQuery } from '@powersync/react';
+import React from 'react';
 
 export type LoginFormParams = {
   email: string;
   password: string;
 };
 
-const DEFAULT_QUERY = 'SELECT * FROM lists';
-
-export default function SQLConsolePage() {
-  const inputRef = React.useRef<HTMLInputElement>();
-  const [query, setQuery] = React.useState(DEFAULT_QUERY);
-  const { data: querySQLResult } = useQuery(query);
+const DEFAULT_QUERY = /* sql */ `
+  SELECT
+    *
+  FROM
+    lists
+`;
 
+const TableDisplay = React.memo(({ data }: { data: ReadonlyArray<any> }) => {
   const queryDataGridResult = React.useMemo(() => {
-    const firstItem = querySQLResult?.[0];
-
+    const firstItem = data?.[0];
     return {
       columns: firstItem
         ? Object.keys(firstItem).map((field) => ({
             field,
             flex: 1
           }))
         : [],
-      rows: querySQLResult
+      rows: data
     };
-  }, [querySQLResult]);
+  }, [data]);
+
+  return (
+    <S.QueryResultContainer>
+      <DataGrid
+        autoHeight={true}
+        rows={queryDataGridResult.rows.map((r, index) => ({ ...r, id: r.id ?? index })) ?? []}
+        columns={queryDataGridResult.columns}
+        initialState={{
+          pagination: {
+            paginationModel: {
+              pageSize: 20
+            }
+          }
+        }}
+        pageSizeOptions={[20]}
+        disableRowSelectionOnClick
+      />
+    </S.QueryResultContainer>
+  );
+});
+
+export default function SQLConsolePage() {
+  const inputRef = React.useRef<HTMLInputElement>();
+  const [query, setQuery] = React.useState(DEFAULT_QUERY);
+
+  const { data, error } = useQuery(query, [], {
+    /**
+     * We don't use the isFetching status here, we can avoid re-renders if we don't report on it.
+     */
+    reportFetching: false,
+    /**
+     * The query here will only emit results when the query data set changes.
+     * Result sets are compared by serializing each item to JSON and comparing the strings.
+     */
+    rowComparator: {
+      keyBy: (item: any) => JSON.stringify(item),
+      compareBy: (item: any) => JSON.stringify(item)
+    }
+  });
 
   return (
     <NavigationPage title="SQL Console">
@@ -57,33 +96,13 @@ export default function SQLConsolePage() {
                 if (queryInput) {
                   setQuery(queryInput);
                 }
-              }}
-            >
+              }}>
               Execute Query
             </Button>
           </S.CenteredGrid>
         </S.CenteredGrid>
-
-        {queryDataGridResult ? (
-          <S.QueryResultContainer>
-            {queryDataGridResult.columns ? (
-              <DataGrid
-                autoHeight={true}
-                rows={queryDataGridResult.rows?.map((r, index) => ({ ...r, id: r.id ?? index })) ?? []}
-                columns={queryDataGridResult.columns}
-                initialState={{
-                  pagination: {
-                    paginationModel: {
-                      pageSize: 20
-                    }
-                  }
-                }}
-                pageSizeOptions={[20]}
-                disableRowSelectionOnClick
-              />
-            ) : null}
-          </S.QueryResultContainer>
-        ) : null}
+        {error ? <Alert severity="error">{error.message}</Alert> : null}
+        <TableDisplay data={data} />
       </S.MainContainer>
     </NavigationPage>
   );

demos/react-supabase-todolist/src/app/views/todo-lists/edit/page.tsx

@@ -1,4 +1,7 @@
-import { usePowerSync, useQuery } from '@powersync/react';
+import { NavigationPage } from '@/components/navigation/NavigationPage';
+import { useSupabase } from '@/components/providers/SystemProvider';
+import { TodoItemWidget } from '@/components/widgets/TodoItemWidget';
+import { LISTS_TABLE, TODOS_TABLE, TodoRecord } from '@/library/powersync/AppSchema';
 import AddIcon from '@mui/icons-material/Add';
 import {
   Box,
@@ -15,12 +18,9 @@ import {
   styled
 } from '@mui/material';
 import Fab from '@mui/material/Fab';
+import { usePowerSync, useQuery } from '@powersync/react';
 import React, { Suspense } from 'react';
 import { useParams } from 'react-router-dom';
-import { useSupabase } from '@/components/providers/SystemProvider';
-import { LISTS_TABLE, TODOS_TABLE, TodoRecord } from '@/library/powersync/AppSchema';
-import { NavigationPage } from '@/components/navigation/NavigationPage';
-import { TodoItemWidget } from '@/components/widgets/TodoItemWidget';
 
 /**
  * useSearchParams causes the entire element to fall back to client side rendering
@@ -34,61 +34,53 @@ const TodoEditSection = () => {
 
   const {
     data: [listRecord]
-  } = useQuery<{ name: string }>(`SELECT name FROM ${LISTS_TABLE} WHERE id = ?`, [listID]);
+  } = useQuery<{ name: string }>(
+    /* sql */ `
+      SELECT
+        name
+      FROM
+        ${LISTS_TABLE}
+      WHERE
+        id = ?
+    `,
+    [listID]
+  );
 
   const { data: todos } = useQuery<TodoRecord>(
-    `SELECT * FROM ${TODOS_TABLE} WHERE list_id=? ORDER BY created_at DESC, id`,
+    /* sql */ `
+      SELECT
+        *
+      FROM
+        ${TODOS_TABLE}
+      WHERE
+        list_id = ?
+      ORDER BY
+        created_at DESC,
+        id
+    `,
     [listID]
   );
 
   const [showPrompt, setShowPrompt] = React.useState(false);
   const nameInputRef = React.createRef<HTMLInputElement>();
 
-  const toggleCompletion = async (record: TodoRecord, completed: boolean) => {
-    const updatedRecord = { ...record, completed: completed };
-    if (completed) {
-      const userID = supabase?.currentSession?.user.id;
-      if (!userID) {
-        throw new Error(`Could not get user ID.`);
-      }
-      updatedRecord.completed_at = new Date().toISOString();
-      updatedRecord.completed_by = userID;
-    } else {
-      updatedRecord.completed_at = null;
-      updatedRecord.completed_by = null;
-    }
-    await powerSync.execute(
-      `UPDATE ${TODOS_TABLE}
-              SET completed = ?,
-                  completed_at = ?,
-                  completed_by = ?
-              WHERE id = ?`,
-      [completed, updatedRecord.completed_at, updatedRecord.completed_by, record.id]
-    );
-  };
-
   const createNewTodo = async (description: string) => {
     const userID = supabase?.currentSession?.user.id;
     if (!userID) {
       throw new Error(`Could not get user ID.`);
     }
 
     await powerSync.execute(
-      `INSERT INTO
-                ${TODOS_TABLE}
-                    (id, created_at, created_by, description, list_id)
-                VALUES
-                    (uuid(), datetime(), ?, ?, ?)`,
+      /* sql */ `
+        INSERT INTO
+          ${TODOS_TABLE} (id, created_at, created_by, description, list_id)
+        VALUES
+          (uuid (), datetime (), ?, ?, ?)
+      `,
       [userID, description, listID!]
     );
   };
 
-  const deleteTodo = async (id: string) => {
-    await powerSync.writeTransaction(async (tx) => {
-      await tx.execute(`DELETE FROM ${TODOS_TABLE} WHERE id = ?`, [id]);
-    });
-  };
-
   if (!listRecord) {
     return (
       <Box>
@@ -106,13 +98,7 @@ const TodoEditSection = () => {
         <Box>
           <List dense={false}>
             {todos.map((r) => (
-              <TodoItemWidget
-                key={r.id}
-                description={r.description}
-                onDelete={() => deleteTodo(r.id)}
-                isComplete={r.completed == 1}
-                toggleCompletion={() => toggleCompletion(r, !r.completed)}
-              />
+              <TodoItemWidget key={r.id} id={r.id} description={r.description} isComplete={r.completed == 1} />
             ))}
           </List>
         </Box>
@@ -129,8 +115,7 @@ const TodoEditSection = () => {
               await createNewTodo(nameInputRef.current!.value);
               setShowPrompt(false);
             }
-          }}
-        >
+          }}>
           <DialogTitle id="alert-dialog-title">{'Create Todo Item'}</DialogTitle>
           <DialogContent>
             <DialogContentText id="alert-dialog-description">Enter a description for a new todo item</DialogContentText>