re-write gotchaes

Author: ospfranco

docs/docs/gotchas.md

@@ -4,11 +4,13 @@ sidebar_position: 3
 
 # Gotchas
 
-SQLite being a C library and React Native being a JS framework with native parts some times create conflicts. Here are the most common problems.
+SQLite being a C library and React Native being a JS framework, sometimes create conflicts. You should take these into account when using the library.
 
-## JavaScript and Numbers
+## JavaScript Numbers
 
-JavaScript represents every number internally as a `double`. This means you can only have integers represented up to 2^53 bits(`Number.MAX_SAFE_INTEGER`). Although sqlite supports long long (2^64 bits) the numbers will be truncated when you query a value bigger than what a JS number can represent. If you need to store larger numbers you should use a `BigInt` object, however, such a type is not natively supported by sqlite, so you will have to serialize and deserialize from/to strings when you do your queries:
+Every JS number is a `double`. This means you can only have integers represented up to `2^53` bits (`Number.MAX_SAFE_INTEGER`). Although sqlite supports 64 bit ints (`long long`), the numbers returned to JS will be truncated when you query a value bigger than what a JS number can represent.
+
+If you need to store larger numbers you should use a `BigInt` object, however, such a type is not natively supported by sqlite, so you will have to serialize and deserialize from/to strings when you do your queries:
 
 ```ts
 // Create your table with the correct types AND USE STRICT TYPING
@@ -30,35 +32,37 @@ let myBigint = BigInt(res.rows[0].myBigInt);
 
 ### Strictness
 
-SQLite by default does not strictly check for types. if you want true type safety when you declare your tables you need to use the `STRICT` keyword.
+Sqlite by default does not strictly check for types. If you want type safety, you need to use the `STRICT` keyword.
 
 ```tsx
 await db.execute('CREATE TABLE Test (id INT PRIMARY KEY, name TEXT) STRICT;');
 ```
 
-If you don't set it, SQLite will happily write whatever you insert in your table, independetly of the declared type (it will try to cast it though, e.g. a `"1"` string might be turned to a `1` int).
+Otherwise, sqlite does a weak attempt at casting and if it fails it inserts whatever you passed into your table, independetly of the declared type. e.g. If you try to insert a string `"1"` into a `INTEGER` column, it will be casted to an int before insertion and behave as a number (see above) when the table is queried.
+
+[Read the sqlite docs on data types and their loose typing and how it can be the source of subtle bugs](https://sqlite.org/datatype3.html).
 
 ### Foreign constraints
 
-When SQLite evaluates your query and you have forgein key constraints, it keeps track of the satisfied relations via a counter. Once your statement finishes executing and the counter is not 0, it throws a foreign key constraint failed error. Unfortunately, this simple design means it is impossible to catch which foreign constraint is failed and you will receive a generic error. Nothing op-sqlite can do about it, it's a design flaw in SQLite.
+When sqlite evaluates your query and you have forgein key constraints, it keeps track of the satisfied relations via a simple counter. Once your statement finishes executing and the counter is not 0, it then throws a `foreign key constraint failed` error, with no information whatsoever of which foreign constraint failed. Unfortunately, this simple design means it is impossible to catch which foreign constraint has failed and you will receive a generic error. Nothing op-sqlite can do about it, it's a design flaw in SQLite.
 
-In order to catch foreign key errors, you also need to execute the pragma when you open your connection:
+Additionaly, the default behavior is not to enforce foreign key constraints. You need to turn the constraint checking on, after opening your connection:
 
 ```tsx
-await db.execute('PRAGMA foreign_keys = true');
+db.executeSync('PRAGMA foreign_keys = true');
 ```
 
 ### Error codes
 
-Sometimes you might be using valid SQL syntax for other engines or you might be doing something else wrong. The errors returned by op-sqlite contain the raw error code returned by SQLite and you should check [the reference](https://www.sqlite.org/rescode.html) for more detailed information.
+Sometimes you might be using valid SQL syntax for other engines or you might be doing something else wrong. The errors returned by op-sqlite contain the raw error code returned by SQLite and you should check [the sqlite error reference](https://www.sqlite.org/rescode.html) for more detailed information.
 
 ### Other Quirks
 
-See the [full list of SQLite quirks](https://www.sqlite.org/quirks.html).
+See the [full list of SQLite quirks](https://www.sqlite.org/quirks.html) that also apply to op-sqlite.
 
 ## HostObjects Quirks
 
-op-sqlite can return HostObjects via the `executeWithHostObjects` API, basically C++ instances exposed to the JS context. They are super fast to create at the cost of runtime access. However, this means some operations won't work.
+op-sqlite can return HostObjects via the `executeWithHostObjects` API, basically C++ objects exposed to JS. They are super fast to create at the cost of runtime access. However, by them being C++ objects, it means some JS operations won't work.
 
 You can write single properties with scalars, for example: