Merge pull request #2 from journeyapps/sdk-readme-examples

[Documentation] Added More SDK Examples

Author: stevensJourney

.github/workflows/build-packages.yaml

@@ -37,7 +37,7 @@ jobs:
     name: Publish Production Packages
     runs-on: ubuntu-latest
     needs: build
-    if: github.ref == 'refs/heads/master'
+    if: github.ref == 'refs/heads/main'
     steps:
       - uses: actions/checkout@v3
         with:
@@ -46,7 +46,7 @@ jobs:
       - name: Setup NodeJS
         uses: actions/setup-node@v2
         with:
-          node-version: 16
+          node-version: 18
 
       - name: Setup Yarn
         run: |

.github/workflows/dev-packages.yaml

@@ -17,7 +17,7 @@ jobs:
       - name: Setup NodeJS
         uses: actions/setup-node@v2
         with:
-          node-version: 16
+          node-version: 18
 
       - name: Setup Yarn
         run: |

README.md

@@ -40,7 +40,7 @@ yarn build:packages
 ## Testing Supabase example app
 
 ``` bash
-cd apps/example
+cd apps/supabase-todolist
 ```
 
 Test on either Android or iOS

lerna.json

@@ -1,8 +1,6 @@
 {
   "$schema": "node_modules/lerna/schemas/lerna-schema.json",
-  "version": "0.0.1-alpha.0",
-  "packages": [
-    "packages/*"
-  ],
+  "version": "independent",
+  "packages": ["packages/*"],
   "npmClient": "yarn"
 }

packages/powersync-sdk-react-native/README.md

@@ -254,50 +254,77 @@ export const setupPowerSync = async () => {
 
 Once the PowerSync instance is configured you can start using the SQLite DB functions
 
+### Fetching an Item
+
+```JSX
+// TodoItemWidget.jsx
+import {Text} from 'react-native';
+
+export const TodoItemWidget = ({id}) => {
+    const [todoItem, setTodoItem] = React.useState([]);
+    const [error, setError] = React.useState([]);
+
+    React.useEffect(() => {
+        // .get returns the first item of the result. Throws an exception if no result is found.
+        PowerSync.get('SELECT * from todos WHERE id = ?', [id])
+          .then(setTodoItem)
+          .catch(ex => setError(ex.message))
+    }, []);
+
+    return <Text>{error || todoItem.description}</Text>
+}
+```
+
 ### Querying Items
 
 ```JSX
-// ListWidget.jsx
-export const ListWidget = () => {
+// ListsWidget.jsx
+import {FlatList, Text} from 'react-native';
+
+export const ListsWidget = () => {
     const [lists, setLists] = React.useState([]);
 
     React.useEffect(() => {
         PowerSync.getAll('SELECT * from lists').then(setLists)
     }, []);
 
-    return <ul>
-        {lists.map(list => <li key={list.id}>{list.name}</li>)}
-    </ul>
+    return (<FlatList
+        data={lists.map(list => ({key: list.id, ...list}))}
+        renderItem={({item}) => <Text>{item.name}</Text>}
+    />)
 }
 ```
 
 ### Querying with React Query
 The PowerSync instance can be used with [React Query](https://tanstack.com/query/v3/docs/react/quick-start). The example below omits the necessary provider setup (see Quickstart).
 
 ```JSX
-// ListWidget.jsx
+// ListsWidget.jsx
 import {useQuery} from 'react-query';
+import {FlatList, Text} from 'react-native';
 
-export const ListWidget = () => {
+export const ListsWidget = () => {
     const {data: lists} = useQuery({
         queryKey: 'lists',
         queryFn: async () => PowerSync.getAll('SELECT * from lists'),
     });
 
-    return <ul>
-        {lists.map(list => <li key={list.id}>{list.name}</li>)}
-    </ul>
+    return (<FlatList
+        data={lists.map(list => ({key: list.id, ...list}))}
+        renderItem={({item}) => <Text>{item.name}</Text>}
+    />)
 }
 ```
 
-
 ### Watching Queries
 
 A watch API allows for queries to be executed whenever a change to a dependant table is made.
 
 ```JSX
-// ListWidget.jsx
- export const ListWidget = () => {
+// ListsWidget.jsx
+import {FlatList, Text} from 'react-native';
+
+ export const ListsWidget = () => {
   const [lists, setLists] = React.useState([]);
 
   React.useEffect(() => {
@@ -313,12 +340,129 @@ A watch API allows for queries to be executed whenever a change to a dependant t
       }
   }, []);
 
-  return <ul>
-      {lists.map(list => <li key={list.id}>{list.name}</li>)}
-  </ul>
+  return (<FlatList
+        data={lists.map(list => ({key: list.id, ...list}))}
+        renderItem={({item}) => <Text>{item.name}</Text>}
+    />)
 }
 ```
 
+### Mutations
+
+The `execute` method can be used for executing single SQLite statements. 
+
+```JSX
+// ListsWidget.jsx
+import {Alert, Button, FlatList, Text, View} from 'react-native';
+
+export const ListsWidget = () => {
+  // Populate lists with one of methods listed above
+  const [lists, setLists] = React.useState([]);
+
+  return (
+    <View>
+      <FlatList
+        data={lists.map(list => ({key: list.id, ...list}))}
+        renderItem={({item}) => (<View>
+          <Text>{item.name}</Text>
+           <Button
+              title="Delete"
+              onPress={async () => {
+                  try {
+                    await PowerSync.execute(`DELETE FROM lists WHERE id = ?`, [item.id])
+                    // Watched queries should automatically reload after mutation
+                  } catch (ex) {
+                    Alert('Error', ex.message)
+                  }
+                }}
+            />
+        </View>)}
+      />
+      <Button
+        title="Create List"
+        color="#841584"
+        onPress={async () => {
+            try {
+              await PowerSync.execute('INSERT INTO lists (id, created_at, name, owner_id) VALUES (uuid(), datetime(), ?, ?) RETURNING *', [
+                'A list name',
+                "[The user's uuid]"
+              ])
+              // Watched queries should automatically reload after mutation
+            } catch (ex) {
+              Alert.alert('Error', ex.message)
+            }
+          }}
+      />
+    </View>
+    )
+}
+```
+
+### Transactions
+
+Read and write transactions present a context where multiple changes can be made then finally committed to the DB or rolled back. This ensures that either all the changes get persisted, or no change is made to the DB (in the case of a rollback or exception).
+
+`PowerSync.writeTransaction(callback)` automatically commits changes after the transaction callback is completed if `tx.rollback()` has not explicitly been called. If an exception is thrown in the callback then changes are automatically rolled back. 
+
+`PowerSync.readTransaction(callback)` automatically rolls back any attempted changes made in the transaction callback.
+
+
+```JSX
+// ListsWidget.jsx
+import {Alert, Button, FlatList, Text, View} from 'react-native';
+
+export const ListsWidget = () => {
+  // Populate lists with one of methods listed above
+  const [lists, setLists] = React.useState([]);
+
+  return (
+    <View>
+      <FlatList
+        data={lists.map(list => ({key: list.id, ...list}))}
+        renderItem={({item}) => (<View>
+          <Text>{item.name}</Text>
+           <Button
+              title="Delete"
+              onPress={async () => {
+                  try {
+                    await PowerSync.writeTransaction(async (tx) => {
+                        // Delete the main list
+                        await tx.executeAsync(`DELETE FROM lists WHERE id = ?`, [item.id]);
+                        // Delete any children of the list
+                        await tx.executeAsync(`DELETE FROM todos WHERE list_id = ?`, [item.id]);
+
+                        // Transactions are automatically committed at the end of execution
+                        // Transactions are automatically rolled back if an exception ocurred
+                      })
+                    // Watched queries should automatically reload after mutation
+                  } catch (ex) {
+                    Alert.alert('Error', ex.message)
+                  }
+                }}
+            />
+        </View>)}
+      />
+      <Button
+        title="Create List"
+        color="#841584"
+        onPress={async () => {
+            try {
+              await PowerSync.execute('INSERT INTO lists (id, created_at, name, owner_id) VALUES (uuid(), datetime(), ?, ?) RETURNING *', [
+                'A list name',
+                "[The user's uuid]"
+              ])
+              // Watched queries should automatically reload after mutation
+            } catch (ex) {
+              Alert.alert('Error', ex.message)
+            }
+          }}
+      />
+    </View>
+    )
+}
+```
+
+
 ### Using Hooks
 
 Configure a PowerSync DB connection and add it to a context provider

packages/powersync-sdk-react-native/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeyapps/powersync-sdk-react-native",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

yarn.lock

@@ -1959,6 +1959,15 @@
     "@types/yargs" "^17.0.8"
     chalk "^4.0.0"
 
+"@journeyapps/powersync-sdk-react-native@0.0.1-alpha.0":
+  version "0.0.1-alpha.0"
+  resolved "https://registry.npmjs.org/@journeyapps/powersync-sdk-react-native/-/powersync-sdk-react-native-0.0.1-alpha.0.tgz#f5cef94d61c9e910f1a197f8da147f996acdd78f"
+  integrity sha512-FcQW+ei899RO2vFXV4qF+tHCxAEdYmGFZCQEePtzXQ66KrMhpH5Pz31+97JAkFCw0TDsrq0l++4SDwvYV7JrQg==
+  dependencies:
+    "@journeyapps/powersync-react" "^0.0.1-alpha.0"
+    "@journeyapps/powersync-sdk-common" "^0.0.1-alpha.0"
+    async-lock "^1.4.0"
+
 "@jridgewell/gen-mapping@^0.3.0", "@jridgewell/gen-mapping@^0.3.2":
   version "0.3.3"
   resolved "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.3.tgz#7e02e6eb5df901aaedb08514203b096614024098"