feat(reat): allow compilable query as hook argument (#150)

Co-authored-by: DominicGBauer <dominic@nomanini.com>

Author: DominicGBauer

.changeset/khaki-apples-hunt.md

@@ -0,0 +1,6 @@
+---
+"@powersync/common": minor
+"@powersync/react": minor
+---
+
+Allow compilable queries to be used as hook arguments

demos/django-react-native-todolist/library/widgets/HeaderWidget.tsx

@@ -39,8 +39,7 @@ export const HeaderWidget: React.FC<{
           onPress={() => {
             Alert.alert(
               'Status',
-              `${status.connected ? 'Connected' : 'Disconnected'}. \nLast Synced at ${
-                status.lastSyncedAt?.toISOString() ?? '-'
+              `${status.connected ? 'Connected' : 'Disconnected'}. \nLast Synced at ${status.lastSyncedAt?.toISOString() ?? '-'
               }\nVersion: ${powersync.sdkVersion}`
             );
           }}

demos/react-native-supabase-group-chat/src/app/(app)/contacts/index.tsx

@@ -112,7 +112,7 @@ export default function ContactsIndex() {
           icon={<Search size="$1.5" />}
           backgroundColor="$brand1"
           borderRadius="$3"
-          // circular
+        // circular
         />
       </XStack>
 

packages/common/package.json

@@ -23,7 +23,8 @@
   "homepage": "https://docs.powersync.com/resources/api-reference",
   "scripts": {
     "build": "tsc -b",
-    "clean": "rm -rf lib tsconfig.tsbuildinfo"
+    "clean": "rm -rf lib tsconfig.tsbuildinfo",
+    "test": "vitest"
   },
   "dependencies": {
     "async-mutex": "^0.4.0",
@@ -37,6 +38,7 @@
     "@types/lodash": "^4.14.197",
     "@types/node": "^20.5.9",
     "@types/uuid": "^9.0.1",
-    "typescript": "^5.1.3"
+    "typescript": "^5.1.3",
+    "vitest": "^1.5.2"
   }
 }

packages/common/src/index.ts

@@ -30,3 +30,6 @@ export * from './db/schema/TableV2';
 export * from './utils/AbortOperation';
 export * from './utils/BaseObserver';
 export * from './utils/strings';
+export * from './utils/parseQuery';
+
+export * from './types/types';

packages/common/src/types/types.ts

@@ -0,0 +1,9 @@
+export interface CompilableQuery<T> {
+  execute(): Promise<T[]>;
+  compile(): CompiledQuery;
+}
+
+export interface CompiledQuery {
+  readonly sql: string;
+  readonly parameters: ReadonlyArray<unknown>;
+}

packages/common/src/utils/parseQuery.ts

@@ -0,0 +1,25 @@
+import type { CompilableQuery } from '../types/types';
+
+export interface ParsedQuery {
+  sqlStatement: string;
+  parameters: any[];
+}
+
+export const parseQuery = <T>(query: string | CompilableQuery<T>, parameters: any[]): ParsedQuery => {
+  let sqlStatement: string;
+
+  if (typeof query == 'string') {
+    sqlStatement = query;
+  } else {
+    const hasAdditionalParameters = parameters.length > 0;
+    if (hasAdditionalParameters) {
+      throw new Error('You cannot pass parameters to a compiled query.');
+    }
+
+    const compiled = query.compile();
+    sqlStatement = compiled.sql;
+    parameters = compiled.parameters as any[];
+  }
+
+  return { sqlStatement, parameters: parameters };
+};

packages/common/tests/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "baseUrl": "./",
+    "esModuleInterop": true,
+    "jsx": "react",
+    "rootDir": "../",
+    "composite": true,
+    "outDir": "./lib",
+    "lib": ["esnext", "DOM"],
+    "module": "esnext",
+    "sourceMap": true,
+    "moduleResolution": "node",
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    "noImplicitUseStrict": false,
+    "noStrictGenericChecks": false,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "target": "esnext"
+  },
+  "include": ["../src/**/*"]
+}

packages/common/tests/utils/parseQuery.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import * as SUT from '../../src/utils/parseQuery';
+
+describe('parseQuery', () => {
+  it('should do nothing if the query is a string', () => {
+    const query = 'SELECT * FROM table';
+    const parameters = ['one'];
+    const result = SUT.parseQuery(query, parameters);
+
+    expect(result).toEqual({ sqlStatement: query, parameters: ['one'] });
+  });
+
+  it('should compile the query and return the sql statement and parameters if the query is compilable', () => {
+    const sqlStatement = 'SELECT * FROM table';
+    const parameters = [];
+    const query = {
+      compile: () => ({ sql: sqlStatement, parameters: ['test'] }),
+      execute: () => Promise.resolve([])
+    };
+    const result = SUT.parseQuery(query, parameters);
+
+    expect(result).toEqual({ sqlStatement, parameters: ['test'] });
+  });
+
+  it('should throw an error if there is an additional parameter included in a compiled query', () => {
+    const sqlStatement = 'SELECT * FROM table';
+    const parameters = ['additional parameter'];
+    const query = {
+      compile: () => ({ sql: sqlStatement, parameters: ['test'] }),
+      execute: () => Promise.resolve([])
+    };
+    const result = () => SUT.parseQuery(query, parameters);
+
+    expect(result).toThrowError('You cannot pass parameters to a compiled query.');
+  });
+});

packages/react/README.md

@@ -63,14 +63,14 @@ const Component = () => {
 
 ### Queries
 
-Queries will automatically update when a dependant table is updated unless you set the `runQueryOnce` flag.
+Queries will automatically update when a dependant table is updated unless you set the `runQueryOnce` flag. You are also able to use a compilable query (e.g. [Kysely queries](https://github.com/powersync-ja/powersync-js/tree/main/packages/kysely-driver)) as a query argument in place of a SQL statement string.
 
 ```JSX
 // TodoListDisplay.jsx
 import { useQuery } from "@powersync/react";
 
 export const TodoListDisplay = () => {
-    const { data: todoLists } = useQuery('SELECT * from lists');
+    const { data: todoLists } = useQuery('SELECT * FROM lists WHERE id = ?', ['id-1'], {runQueryOnce: false});
 
     return <View>
       {todoLists.map((l) => (