Improve readmes across the packages and bump to 1.0.0

README.md

@@ -1,46 +1,60 @@
 # React Native Replicache
 
-Plug-in React Native compatibility bindings for Replicache.
+> Plug-in React Native compatibility bindings for [Replicache](https://replicache.dev/).
 
-https://user-images.githubusercontent.com/5165963/219898954-f5e94045-69bf-4c33-84e8-7d152c6f2c32.mov
+<https://user-images.githubusercontent.com/5165963/219898954-f5e94045-69bf-4c33-84e8-7d152c6f2c32.mov>
 
 ## Why is this needed?
 
-By default, Replicache uses IndexedDB in the web-browser. This technology isn't available in React Native, but luckily Replicache is generic enough to allow us to provide our own local persistance provider.
+Replicache enables us to build applications that are performant, offline-capable and collaborative. By default, it uses [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) for client-side persistance. Unfortunately, this technology is not available in React Native and is only supported in web-browsers.
 
-## What's the strategy?
+Thankfully, Replicache allows us to provide our own transactional data-store via [`experimentalCreateKVStore`](https://doc.replicache.dev/api/interfaces/ReplicacheOptions#experimentalcreatekvstore). The goal of this project is to provide some implementations of such a store, along with some guidance in getting up and running with Replicache in React Native.
 
-Currently, the strategy is to provide an implementation of Replicache's `ExperimentalCreateKVStore` backed by  [`react-native-quick-sqlite`](https://github.com/ospfranco/react-native-quick-sqlite) or [`expo-sqlite`](https://docs.expo.dev/versions/latest/sdk/sqlite/#sqltransaction).
+## What are the strategies?
 
-Additionally, some configuration is required to received poke events from the server.
+React Native has relatively good support for SQLite - which provides the [strict serializable](https://jepsen.io/consistency/models/strict-serializable) transactions that we require.
+
+In particular, we provide the choice between two SQLite bindings:
+
+1. [`@react-native-replicache/react-native-expo-sqlite`](https://github.com/Braden1996/react-native-replicache/tree/master/packages/react-native-expo-sqlite)
+   - Backed by [`expo-sqlite`](https://docs.expo.dev/versions/latest/sdk/sqlite/)
+   - Supported in [Expo Go](https://expo.dev/client).
+2. [`@react-native-replicache/react-native-quick-sqlite`](https://github.com/Braden1996/react-native-replicache/tree/master/packages/react-native-quick-sqlite)
+   - Backed by [`react-native-quick-sqlite`](https://github.com/ospfranco/react-native-quick-sqlite)
+   - Better performance.
+
+### Any additional considerations?
+
+Some configuration is required to receive [poke](https://doc.replicache.dev/byob/poke) events from the server. In our example, [seen here](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts), we use a polyfill for Server Sent Events. These aren't built into React Native, but are really handy for a demo.
+
+You most likely want to use web-sockets for this. This is relatively trivial with Pusher/Ably etc and similar to the web-app so we won't discuss that further here.
 
 ## How can I install this?
 
 1. Install the following in your React Native project:
-    - `yarn add @react-native-replicache/react-native-quick-sqlite react-native-quick-sqlite expo-crypto`
-    - or
-    - `yarn add @react-native-replicache/react-native-expo-sqlite expo-sqlite expo-crypto`
+   - `yarn add expo-crypto`
+   - Decide which SQLite binding is for you and install one of the following:
+     - `yarn add react-native-quick-sqlite @react-native-replicache/react-native-quick-sqlite`
+     - `yarn add expo-sqlite @react-native-replicache/expo-sqlite`
 2. Ensure that you've polyfilled `crypto.getRandomValues` on the global namespace.
-  - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/crypto-polyfill.ts).
-3. Pass `createReplicacheReactNativeQuickSQLiteExperimentalCreateKVStore` or `createReplicacheReactNativeExpoSQLiteExperimentalCreateKVStore` into Replicache's `experimentalCreateKVStore` option.
-  - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts).
-
-## What else will I need to do?
-
-- Configure a poke mechanism.
-  - You will likely want to use web-sockets for this, managed via Pusher/Ably/etc
-  - In our example, [seen here](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts), we use a polyfill for Server Sent Events.
-    - These aren't built into React Native, but are really handy for a demo.
+   - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/crypto-polyfill.ts).
+3. Pass in your chosen SQLite binding's React Native Replicache binding into Replicache's `experimentalCreateKVStore` option.
+   - This will be one of the following, depending on the binding you chose:
+     - `createReplicacheQuickSQLiteExperimentalCreateKVStore`
+     - `createReplicacheExpoSQLiteExperimentalCreateKVStore`
+   - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts).
 
 ## How can I experiment with this locally?
 
-### Prerequisites:
+### Prerequisites
 
 - Environment capable of developing iOS/Android applications (iOS is likely preferred).
-  - See https://dev-yakuza.posstree.com/en/react-native/install-on-mac/
-    - or: https://reactnative.dev/docs/environment-setup
-    - Note: Installing [Xcode](https://developer.apple.com/xcode/) from the [Mac App Store](https://apps.apple.com/us/app/xcode/id497799835?mt=12) tends to be unusually slow and buggy.
-      - Try the `Download -> Website` approach instead, [found here](https://developer.apple.com/xcode/).
+  - See [How to install React Native on Mac](https://dev-yakuza.posstree.com/en/react-native/install-on-mac/)
+    - or: [Setting up the development environment](https://reactnative.dev/docs/environment-setup)
+  - Note: Installing [Xcode](https://developer.apple.com/xcode/) from the [Mac App Store](https://apps.apple.com/us/app/xcode/id497799835?mt=12) tends to be unusually slow and buggy.
+    - Try download it from the [Apple website](https://developer.apple.com/xcode/) instead.
+
+### Instructions
 
 1. Clone the repository: `git clone https://github.com/braden1996/react-native-replicache.git`
 2. Install yarn dependencies from repo root: `yarn install`

packages/deep-freeze/README.md

@@ -0,0 +1,5 @@
+# Deep Freeze
+
+## Why is this needed?
+
+This package includes some snippets taken from Replicache's internals. It provides a mechanism for us to enforce immutability on the data that comes out of our Replicache store, by giving us stricter types along with some checks when in development mode. In production, it does nothing meaningful.

packages/deep-freeze/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-replicache/deep-freeze",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "main": "./dist/commonjs/index.js",
   "module": "./dist/module/index.js",
   "react-native": "./src/index.ts",

packages/example/mobile-react-native/package.json

@@ -20,8 +20,8 @@
   "dependencies": {
     "@react-native-replicache/example-client-shared": "0.0.0",
     "@react-native-replicache/example-shared": "0.0.0",
-    "@react-native-replicache/react-native-expo-sqlite": "0.0.4",
-    "@react-native-replicache/react-native-quick-sqlite": "0.0.4",
+    "@react-native-replicache/react-native-expo-sqlite": "1.0.0",
+    "@react-native-replicache/react-native-quick-sqlite": "1.0.0",
     "expo": "~48.0.1",
     "expo-build-properties": "0.5.1",
     "expo-crypto": "^12.0.0",

packages/react-native-expo-sqlite/README.md

@@ -0,0 +1,32 @@
+# React Native Replicache
+
+> Plug-in React Native compatibility bindings for [Replicache](https://replicache.dev/).
+
+<https://user-images.githubusercontent.com/5165963/219898954-f5e94045-69bf-4c33-84e8-7d152c6f2c32.mov>
+
+## Why is this needed?
+
+Replicache enables us to build applications that are performant, offline-capable and collaborative. By default, it uses [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) for client-side persistance. Unfortunately, this technology is not available in React Native and is only supported in web-browsers.
+
+Thankfully, Replicache allows us to provide our own transactional data-store via [`experimentalCreateKVStore`](https://doc.replicache.dev/api/interfaces/ReplicacheOptions#experimentalcreatekvstore). The goal of this project is to provide some implementations of such a store, along with some guidance in getting up and running with Replicache in React Native.
+
+## What are the strategies?
+
+React Native has relatively good support for SQLite - which provides the [strict serializable](https://jepsen.io/consistency/models/strict-serializable) transactions that we require.
+
+Here we provide a store implementation backed by [`expo-sqlite`](https://docs.expo.dev/versions/latest/sdk/sqlite/). However, we also offer [more bindings here](https://github.com/Braden1996/react-native-replicache). Be sure to see what best fits your project!
+
+### Any additional considerations?
+
+Some configuration is required to receive [poke](https://doc.replicache.dev/byob/poke) events from the server. In our example, [seen here](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts), we use a polyfill for Server Sent Events. These aren't built into React Native, but are really handy for a demo.
+
+You most likely want to use web-sockets for this. This is relatively trivial with Pusher/Ably etc and similar to the web-app so we won't discuss that further here.
+
+## How can I install this?
+
+1. Install the following in your React Native project:
+   - `yarn add expo-crypto expo-sqlite @react-native-replicache/react-native-expo-sqlite`
+2. Ensure that you've polyfilled `crypto.getRandomValues` on the global namespace.
+   - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/crypto-polyfill.ts).
+3. Pass in `createReplicacheExpoSQLiteExperimentalCreateKVStore` to Replicache's `experimentalCreateKVStore` option.
+   - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts).

packages/react-native-expo-sqlite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-replicache/react-native-expo-sqlite",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "main": "./dist/commonjs/index.js",
   "module": "./dist/module/index.js",
   "react-native": "./src/index.ts",
@@ -34,7 +34,7 @@
     "clean": "rm -rf dist .turbo"
   },
   "dependencies": {
-    "@react-native-replicache/replicache-generic-sqlite": "0.0.4"
+    "@react-native-replicache/replicache-generic-sqlite": "1.0.0"
   },
   "devDependencies": {
     "@braden1996/tsconfig": "^0.0.1",

packages/react-native-quick-sqlite/README.md

@@ -0,0 +1,32 @@
+# React Native Replicache
+
+> Plug-in React Native compatibility bindings for [Replicache](https://replicache.dev/).
+
+<https://user-images.githubusercontent.com/5165963/219898954-f5e94045-69bf-4c33-84e8-7d152c6f2c32.mov>
+
+## Why is this needed?
+
+Replicache enables us to build applications that are performant, offline-capable and collaborative. By default, it uses [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) for client-side persistance. Unfortunately, this technology is not available in React Native and is only supported in web-browsers.
+
+Thankfully, Replicache allows us to provide our own transactional data-store via [`experimentalCreateKVStore`](https://doc.replicache.dev/api/interfaces/ReplicacheOptions#experimentalcreatekvstore). The goal of this project is to provide some implementations of such a store, along with some guidance in getting up and running with Replicache in React Native.
+
+## What are the strategies?
+
+React Native has relatively good support for SQLite - which provides the [strict serializable](https://jepsen.io/consistency/models/strict-serializable) transactions that we require.
+
+Here we provide a store implementation backed by [`react-native-quick-sqlite`](https://github.com/ospfranco/react-native-quick-sqlite). However, we also offer [more bindings here](https://github.com/Braden1996/react-native-replicache). Be sure to see what best fits your project!
+
+### Any additional considerations?
+
+Some configuration is required to receive [poke](https://doc.replicache.dev/byob/poke) events from the server. In our example, [seen here](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts), we use a polyfill for Server Sent Events. These aren't built into React Native, but are really handy for a demo.
+
+You most likely want to use web-sockets for this. This is relatively trivial with Pusher/Ably etc and similar to the web-app so we won't discuss that further here.
+
+## How can I install this?
+
+1. Install the following in your React Native project:
+   - `yarn add expo-crypto react-native-quick-sqlite @react-native-replicache/react-native-quick-sqlite`
+2. Ensure that you've polyfilled `crypto.getRandomValues` on the global namespace.
+   - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/crypto-polyfill.ts).
+3. Pass in `createReplicacheQuickSQLiteExperimentalCreateKVStore` to Replicache's `experimentalCreateKVStore` option.
+   - See [here for an example](https://github.com/Braden1996/react-native-replicache/blob/master/packages/example/mobile-react-native/src/use-replicache.ts).

packages/react-native-quick-sqlite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-replicache/react-native-quick-sqlite",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "main": "./dist/commonjs/index.js",
   "module": "./dist/module/index.js",
   "react-native": "./src/index.ts",
@@ -34,7 +34,7 @@
     "clean": "rm -rf dist .turbo"
   },
   "dependencies": {
-    "@react-native-replicache/replicache-generic-sqlite": "0.0.4"
+    "@react-native-replicache/replicache-generic-sqlite": "1.0.0"
   },
   "devDependencies": {
     "@braden1996/tsconfig": "^0.0.1",

packages/replicache-generic-sqlite/README.md

@@ -0,0 +1,9 @@
+# React Native Replicache - Generic SQLite
+
+> Plug-in React Native compatibility bindings for [Replicache](https://replicache.dev/).
+
+<https://user-images.githubusercontent.com/5165963/219898954-f5e94045-69bf-4c33-84e8-7d152c6f2c32.mov>
+
+## Why is this needed?
+
+This package provides a generic SQLite implementation of [`experimentalCreateKVStore`](https://doc.replicache.dev/api/interfaces/ReplicacheOptions#experimentalcreatekvstore) that is agnostic of the underlying SQLite binding. This abstraction enables us to easily support multiple SQLite bindings. It isn't coupled to React Native either, so could work on other platforms - but that remains to be explored.

packages/replicache-generic-sqlite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-replicache/replicache-generic-sqlite",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "main": "./dist/commonjs/index.js",
   "module": "./dist/module/index.js",
   "react-native": "./src/index.ts",
@@ -36,7 +36,7 @@
     "clean": "rm -rf dist .turbo"
   },
   "dependencies": {
-    "@react-native-replicache/deep-freeze": "0.0.4"
+    "@react-native-replicache/deep-freeze": "1.0.0"
   },
   "devDependencies": {
     "@braden1996/tsconfig": "^0.0.1",

yarn.lock

@@ -2517,7 +2517,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@react-native-replicache/deep-freeze@0.0.4, @react-native-replicache/deep-freeze@workspace:packages/deep-freeze":
+"@react-native-replicache/deep-freeze@1.0.0, @react-native-replicache/deep-freeze@workspace:packages/deep-freeze":
   version: 0.0.0-use.local
   resolution: "@react-native-replicache/deep-freeze@workspace:packages/deep-freeze"
   dependencies:
@@ -2554,8 +2554,8 @@ __metadata:
     "@braden1996/tsconfig": ^0.0.1
     "@react-native-replicache/example-client-shared": 0.0.0
     "@react-native-replicache/example-shared": 0.0.0
-    "@react-native-replicache/react-native-expo-sqlite": 0.0.4
-    "@react-native-replicache/react-native-quick-sqlite": 0.0.4
+    "@react-native-replicache/react-native-expo-sqlite": 1.0.0
+    "@react-native-replicache/react-native-quick-sqlite": 1.0.0
     "@types/react": ^18.0.28
     "@types/react-native": ~0.71.2
     "@types/react-native__assets": ^1.0.0
@@ -2652,12 +2652,12 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@react-native-replicache/react-native-expo-sqlite@0.0.4, @react-native-replicache/react-native-expo-sqlite@workspace:packages/react-native-expo-sqlite":
+"@react-native-replicache/react-native-expo-sqlite@1.0.0, @react-native-replicache/react-native-expo-sqlite@workspace:packages/react-native-expo-sqlite":
   version: 0.0.0-use.local
   resolution: "@react-native-replicache/react-native-expo-sqlite@workspace:packages/react-native-expo-sqlite"
   dependencies:
     "@braden1996/tsconfig": ^0.0.1
-    "@react-native-replicache/replicache-generic-sqlite": 0.0.4
+    "@react-native-replicache/replicache-generic-sqlite": 1.0.0
     "@types/react": ^18.0.28
     eslint: 8.32.0
     eslint-config-universe: ^11.1.1
@@ -2670,12 +2670,12 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@react-native-replicache/react-native-quick-sqlite@0.0.4, @react-native-replicache/react-native-quick-sqlite@workspace:packages/react-native-quick-sqlite":
+"@react-native-replicache/react-native-quick-sqlite@1.0.0, @react-native-replicache/react-native-quick-sqlite@workspace:packages/react-native-quick-sqlite":
   version: 0.0.0-use.local
   resolution: "@react-native-replicache/react-native-quick-sqlite@workspace:packages/react-native-quick-sqlite"
   dependencies:
     "@braden1996/tsconfig": ^0.0.1
-    "@react-native-replicache/replicache-generic-sqlite": 0.0.4
+    "@react-native-replicache/replicache-generic-sqlite": 1.0.0
     "@types/react": ^18.0.28
     eslint: 8.32.0
     eslint-config-universe: ^11.1.1
@@ -2687,12 +2687,12 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@react-native-replicache/replicache-generic-sqlite@0.0.4, @react-native-replicache/replicache-generic-sqlite@workspace:packages/replicache-generic-sqlite":
+"@react-native-replicache/replicache-generic-sqlite@1.0.0, @react-native-replicache/replicache-generic-sqlite@workspace:packages/replicache-generic-sqlite":
   version: 0.0.0-use.local
   resolution: "@react-native-replicache/replicache-generic-sqlite@workspace:packages/replicache-generic-sqlite"
   dependencies:
     "@braden1996/tsconfig": ^0.0.1
-    "@react-native-replicache/deep-freeze": 0.0.4
+    "@react-native-replicache/deep-freeze": 1.0.0
     eslint: 8.32.0
     eslint-config-universe: ^11.1.1
     prettier: ^2.8.3