Add useWatchedQuerySubscription for Vue package

Author: stevensJourney

.changeset/nine-pens-ring.md

@@ -15,3 +15,29 @@ const { data } = useQuery('SELECT * FROM lists WHERE name = ?', ['aname'], {
   }
 });
 ```
+
+- 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/swift-guests-explain.md

@@ -13,3 +13,27 @@ const { data } = useQuery('SELECT * FROM lists WHERE name = ?', ['aname'], {
   }
 });
 ```
+
+- 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>
+  );
+};
+```

packages/vue/src/composables/useWatchedQuerySubscription.ts

@@ -1,34 +1,44 @@
-// import { WatchedQuery } from '@powersync/common';
-// import { reactive, Ref, ref, UnwrapRef, watchEffect } from 'vue';
+import { WatchedQuery } from '@powersync/common';
+import { reactive, UnwrapNestedRefs, watchEffect } from 'vue';
 
-// /**
-//  * A composable to access and subscribe to the results of an existing {@link WatchedQuery} instance.
-//  * @example
-//  * ```vue
-//  * <script setup>
-//  * import { useQuery } from '@powersync/vue';
-//  *
-//  * const { data, isLoading, isFetching, error} = useQuery(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>
-//  * ```
-//  */
-// export const useWatchedQuerySubscription = <
-//   ResultType = unknown,
-//   Query extends WatchedQuery<ResultType> = WatchedQuery<ResultType>
-// >(
-//   query: Query
-// ) => {
-//   const state = reactive(query.state);
+/**
+ * A composable to access and subscribe to the results of an existing {@link WatchedQuery} instance.
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useWatchedQuerySubscription } from '@powersync/vue';
+ *
+ * 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>
+ * ```
+ */
+export const useWatchedQuerySubscription = <
+  ResultType = unknown,
+  Query extends WatchedQuery<ResultType> = WatchedQuery<ResultType>
+>(
+  query: Query
+): UnwrapNestedRefs<Query['state']> => {
+  // Creates a reactive variable which will proxy the state
+  const state = reactive(query.state) as UnwrapNestedRefs<Query['state']>;
 
-//   return state;
-// };
+  watchEffect((onCleanup) => {
+    const dispose = query.registerListener({
+      onStateChange: (updatedState) => {
+        Object.assign(state, updatedState);
+      }
+    });
+    onCleanup(() => dispose());
+  });
+
+  return state;
+};

packages/vue/src/index.ts

@@ -4,3 +4,4 @@ export { usePowerSyncStatus } from './composables/usePowerSyncStatus';
 export { usePowerSyncWatchedQuery } from './composables/usePowerSyncWatchedQuery';
 export { useQuery } from './composables/useQuery';
 export { useStatus } from './composables/useStatus';
+export { useWatchedQuerySubscription } from './composables/useWatchedQuerySubscription';

packages/vue/tests/useQuery.test.ts

@@ -5,6 +5,7 @@ import { describe, expect, it, onTestFinished, vi } from 'vitest';
 import { isProxy, isRef, ref } from 'vue';
 import { createPowerSyncPlugin } from '../src/composables/powerSync';
 import { useQuery } from '../src/composables/useQuery';
+import { useWatchedQuerySubscription } from '../src/composables/useWatchedQuerySubscription';
 import { withSetup } from './utils';
 
 export const openPowerSync = () => {
@@ -106,6 +107,34 @@ describe('useQuery', () => {
     );
   });
 
+  it('should use an existing WatchedQuery instance', async () => {
+    // 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 = powersync!
+      .query<{ id: string; name: string }>({ sql: `SELECT * FROM lists`, parameters: [] })
+      .differentialWatch();
+
+    const [state] = withPowerSyncSetup(() => useWatchedQuerySubscription(listsQuery));
+
+    await powersync!.execute(
+      /* sql */ `
+        INSERT INTO
+          lists (id, name)
+        VALUES
+          (uuid (), ?)
+      `,
+      ['test']
+    );
+
+    await vi.waitFor(
+      () => {
+        expect(state.data.length).eq(1);
+      },
+      { timeout: 1000 }
+    );
+  });
+
   it('should rerun the query when refresh is used', async () => {
     const getAllSpy = vi.spyOn(powersync!, 'getAll');