Merge pull request #41 from ospfranco/transactions

Author: Oscar Franco

.editorconfig

@@ -1,5 +1,3 @@
-<h1 align="center">React Native Quick SQLite</h1>
-
 ![screenshot](https://raw.githubusercontent.com/ospfranco/react-native-quick-sqlite/main/header.png)
 
 <div align="center">
@@ -24,7 +22,7 @@
 </div>
 <br />
 
-This library embeds the latest version of SQLite and provides a low-level API to execute SQL queries, fast bindings via [JSI](https://formidable.com/blog/2019/jsi-jsc-part-2). By using the latest version of SQLite instead of the phone's you get all the latest security fixes and also all new features.
+Quick SQLite embeds the latest version of SQLite and provides a low-level API to execute SQL queries, uses fast bindings via [JSI](https://formidable.com/blog/2019/jsi-jsc-part-2). By using an embedded SQLite you get access the latest security patches and latest features.
 
 Inspired/compatible with [react-native-sqlite-storage](https://github.com/andpor/react-native-sqlite-storage) and [react-native-sqlite2](https://github.com/craftzdog/react-native-sqlite-2).
 
@@ -57,14 +55,11 @@ interface QueryResult {
 /**
  * Column metadata
  * Describes some information about columns fetched by the query
+ * columnDeclaredType - declared column type for this column, when fetched directly from a table or a View resulting from a table column. "UNKNOWN" for dynamic values, like function returned ones.
  */
-declare type ColumnMetadata = {
-  /** The name used for this column for this resultset */
+interface ColumnMetadata = {
   columnName: string;
-  /** The declared column type for this column, when fetched directly from a table or a View resulting from a table column. "UNKNOWN" for dynamic values, like function returned ones. */
   columnDeclaredType: string;
-  /**
-   * The index for this column for this resultset*/
   columnIndex: number;
 };
 
@@ -108,13 +103,13 @@ interface ISQLite {
 
 # Usage
 
+Import as early as possible, auto-installs bindings in a thread-safe manner.
+
 ```typescript
-// Import as early as possible, auto-installs bindings.
 // Thanks to @mrousavy for this installation method, see one example: https://github.com/mrousavy/react-native-mmkv/blob/75b425db530e26cf10c7054308583d03ff01851f/src/createMMKV.ts#L56
 import 'react-native-quick-sqlite';
 
-// `sqlite` is a globally registered object, so you can directly call it from anywhere in your javascript
-// the import on the top of the file only registers typescript types but it is not mandatory
+// Afterwards `sqlite` is a globally registered object, so you can directly call it from anywhere in your javascript
 const dbOpenResult = sqlite.open('myDatabase', 'databases');
 
 // status === 1, operation failed
@@ -123,51 +118,56 @@ if (dbOpenResult.status) {
 }
 ```
 
-### Example queries
+### Simple queries
+
+The basic query is **synchronous**, it will block rendering on large operations, below there are async versions.
 
 ```typescript
-let result = sqlite.executeSql('myDatabase', 'SELECT somevalue FROM sometable');
-if (!result.status) {
-  // result.status undefined or 0 === sucess
-  for (let i = 0; i < result.rows.length; i++) {
-    const row = result.rows.item(i);
-    console.log(row.somevalue);
-  }
+let { status, rows } = sqlite.executeSql(
+  'myDatabase',
+  'SELECT somevalue FROM sometable'
+);
+if (!status) {
+  rows.forEach((row) => {
+    console.log(row);
+  });
 }
 
-result = sqlite.executeSql(
+let { status, rowsAffected } = sqlite.executeSql(
   'myDatabase',
-  'UPDATE sometable set somecolumn = ? where somekey = ?',
+  'UPDATE sometable SET somecolumn = ? where somekey = ?',
   [0, 1]
 );
-if (!result.status) {
-  // result.status undefined or 0 === sucess
-  console.log(`Update affected ${result.rowsAffected} rows`);
+if (!status) {
+  console.log(`Update affected ${rowsAffected} rows`);
 }
 ```
 
-In some scenarios, dynamic applications may need to get some metadata information about the returned resultset.
-This can be done testing the returned data directly, but in some cases may not be enough, like when data is stored outside
-storage datatypes, like booleans or datetimes. When fetching data directly from tables or views linked to table columns, SQLite is able
-to identify the table declared types:
+### Transactions
+
+Transactions are supported. However, due to the library being opionionated and mostly not throwing errors you need to return a boolean (true for correct exceution, false for incorrect execution) to either commit or rollback the transaction.
+
+JSI bindings are fast but there is still some overhead calling `executeSql` for single queries, if you want to execute a large set of commands as fast as possible you should use the `executeSqlBatch` method below, it still uses transactions, but only transmits data between JS and native once.
 
 ```typescript
-let result = sqlite.executeSql(
-  'myDatabase',
-  'SELECT int_column_1, bol_column_2 FROM sometable'
-);
-if (!result.status) {
-  // result.status undefined or 0 === sucess
-  for (let i = 0; i < result.metadata.length; i++) {
-    const column = result.metadata[i];
-    console.log(`${column.columnName} - ${column.columnDeclaredType}`);
-    // Output:
-    // int_column_1 - INTEGER
-    // bol_column_2 - BOOLEAN
+sqlite.transaction('myDatabase', (tx) => {
+  const {
+    status,
+  } = tx.executeSql('UPDATE sometable SET somecolumn = ? where somekey = ?', [
+    0,
+    1,
+  ]);
+
+  if (status) {
+    return false;
   }
-}
+
+  return true;
+});
 ```
 
+### Batch operation
+
 Batch execution allows transactional execution of a set of commands
 
 ```typescript
@@ -184,14 +184,44 @@ if (!result.status) {
 }
 ```
 
-Async versions are also available if you have too much SQL to execute
+### Dynamic Column Metadata
+
+In some scenarios, dynamic applications may need to get some metadata information about the returned result set.
+
+This can be done testing the returned data directly, but in some cases may not be enough, for example when data is stored outside
+sqlite datatypes. When fetching data directly from tables or views linked to table columns, SQLite is able
+to identify the table declared types:
+
+```typescript
+let { status, metadata } = sqlite.executeSql(
+  'myDatabase',
+  'SELECT int_column_1, bol_column_2 FROM sometable'
+);
+if (!status) {
+  metadata.forEach((column) => {
+    // Output:
+    // int_column_1 - INTEGER
+    // bol_column_2 - BOOLEAN
+    console.log(`${column.columnName} - ${column.columnDeclaredType}`);
+  });
+}
+```
+
+### Async operations
+
+You might have too much SQL too process and it will cause your application to freeze. There are async versions for some of the operations. This will offload the SQLite processing to a different thread.
 
 ```ts
-sqlite.asyncExecuteSql('myDatabase', 'SELECT * FROM "User";', [], (result) => {
-  if (result.status === 0) {
-    console.log('users', result.rows);
+sqlite.asyncExecuteSql(
+  'myDatabase',
+  'SELECT * FROM "User";',
+  [],
+  ({ status, rows }) => {
+    if (status === 0) {
+      console.log('users', rows);
+    }
   }
-});
+);
 ```
 
 ## Use TypeORM

README.md

@@ -10,6 +10,6 @@ public class MainActivity extends ReactActivity {
    */
   @Override
   protected String getMainComponentName() {
-    return "SequelExample";
+    return "QuickSQLiteExample";
   }
 }

example/android/app/src/main/java/com/example/reactnativesequel/MainActivity.java

@@ -1,4 +1,4 @@
 {
-  "name": "SequelExample",
-  "displayName": "Sequel Example"
+  "name": "QuickSQLiteExample",
+  "displayName": "Quick SQLite Example"
 }

example/app.json

@@ -228,7 +228,7 @@ PODS:
   - React-jsinspector (0.67.3)
   - React-logger (0.67.3):
     - glog
-  - react-native-quick-sqlite (3.0.2):
+  - react-native-quick-sqlite (3.0.4):
     - React
     - React-callinvoker
     - React-Core
@@ -431,7 +431,7 @@ SPEC CHECKSUMS:
   React-jsiexecutor: 15ea57ead631a11fad57634ff69f78e797113a39
   React-jsinspector: 1e1e03345cf6d47779e2061d679d0a87d9ae73d8
   React-logger: 1e10789cb84f99288479ba5f20822ce43ced6ffe
-  react-native-quick-sqlite: d8d711b42c9df78e1983a02d5f29cd541a78b713
+  react-native-quick-sqlite: 6e2ccab68e66b0a09f1ce5b7eeae097d32230ec5
   React-perflogger: 93d3f142d6d9a46e635f09ba0518027215a41098
   React-RCTActionSheet: 87327c3722203cc79cf79d02fb83e7332aeedd18
   React-RCTAnimation: 009c87c018d50e0b38692699405ebe631ff4872d
@@ -446,6 +446,6 @@ SPEC CHECKSUMS:
   ReactCommon: 650e33cde4fb7d36781cd3143f5276da0abb2f96
   Yoga: 90dcd029e45d8a7c1ff059e8b3c6612ff409061a
 
-PODFILE CHECKSUM: 23fbb34cc9cd3db2810e5bb10e37bce3ce025dee
+PODFILE CHECKSUM: 21282804cb7b559416f2717812c3f6c182daa539
 
-COCOAPODS: 1.11.2
+COCOAPODS: 1.11.3

example/ios/Podfile.lock

@@ -297,7 +297,7 @@
 					"-ObjC",
 					"-lc++",
 				);
-				PRODUCT_BUNDLE_IDENTIFIER = com.example.reactnativequicksqlite;
+				PRODUCT_BUNDLE_IDENTIFIER = com.ospfranco.quicksqlite;
 				PRODUCT_NAME = SequelExample;
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 				SWIFT_VERSION = 5.0;
@@ -321,7 +321,7 @@
 					"-ObjC",
 					"-lc++",
 				);
-				PRODUCT_BUNDLE_IDENTIFIER = com.example.reactnativequicksqlite;
+				PRODUCT_BUNDLE_IDENTIFIER = com.ospfranco.quicksqlite;
 				PRODUCT_NAME = SequelExample;
 				SWIFT_VERSION = 5.0;
 				VERSIONING_SYSTEM = "apple-generic";

example/ios/SequelExample.xcodeproj/project.pbxproj

@@ -10,7 +10,7 @@ - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(
 {
   RCTBridge *bridge = [[RCTBridge alloc] initWithDelegate:self launchOptions:launchOptions];
   RCTRootView *rootView = [[RCTRootView alloc] initWithBridge:bridge
-                                                   moduleName:@"SequelExample"
+                                                   moduleName:@"QuickSQLiteExample"
                                             initialProperties:nil];
 
   rootView.backgroundColor = [[UIColor alloc] initWithRed:1.0f green:1.0f blue:1.0f alpha:1];

example/ios/SequelExample/AppDelegate.m

@@ -1,38 +1,62 @@
 {
   "images" : [
     {
+      "filename" : "Icon-20@2x.png",
       "idiom" : "iphone",
-      "size" : "29x29",
-      "scale" : "2x"
+      "scale" : "2x",
+      "size" : "20x20"
     },
     {
+      "filename" : "Icon-20@3x.png",
       "idiom" : "iphone",
-      "size" : "29x29",
-      "scale" : "3x"
+      "scale" : "3x",
+      "size" : "20x20"
     },
     {
+      "filename" : "Icon-29@2x.png",
       "idiom" : "iphone",
-      "size" : "40x40",
-      "scale" : "2x"
+      "scale" : "2x",
+      "size" : "29x29"
     },
     {
+      "filename" : "Icon-29@3x.png",
       "idiom" : "iphone",
-      "size" : "40x40",
-      "scale" : "3x"
+      "scale" : "3x",
+      "size" : "29x29"
     },
     {
+      "filename" : "Icon-40@2x.png",
       "idiom" : "iphone",
-      "size" : "60x60",
-      "scale" : "2x"
+      "scale" : "2x",
+      "size" : "40x40"
     },
     {
+      "filename" : "Icon-40@3x.png",
       "idiom" : "iphone",
-      "size" : "60x60",
-      "scale" : "3x"
+      "scale" : "3x",
+      "size" : "40x40"
+    },
+    {
+      "filename" : "Icon-60@2x.png",
+      "idiom" : "iphone",
+      "scale" : "2x",
+      "size" : "60x60"
+    },
+    {
+      "filename" : "Icon-60@3x.png",
+      "idiom" : "iphone",
+      "scale" : "3x",
+      "size" : "60x60"
+    },
+    {
+      "filename" : "Icon-1024.png",
+      "idiom" : "ios-marketing",
+      "scale" : "1x",
+      "size" : "1024x1024"
     }
   ],
   "info" : {
-    "version" : 1,
-    "author" : "xcode"
+    "author" : "xcode",
+    "version" : 1
   }
-}
+}