Fix nippy README, and add storage README

Author: bobby

nippy/README.md

@@ -1,85 +1,40 @@
-# converge/transit
+# converge/nippy
 
-transit-(clj|cljs) handlers for Converge
+Nippy serialization support for Converge in Clojure.
 
 ## Usage
 
-### Clojure + transit-clj
-
-This is the transit-clj Usage example, modified to include a
-ConvergentRef and the read/write handlers provided by this library.
+Nippy provides a global extension mechanism for supporting custom
+types. Simply requiring the `converge.nippy` namespace adds support
+for Converge types:
 
 ``` clojure
-(require '[cognitect.transit :as transit]
-         '[converge.transit :as converge-transit]
+(require '[taoensso.nippy :as nippy]
+         'converge.nippy
          '[converge.api :as convergent])
-(import [java.io ByteArrayInputStream ByteArrayOutputStream])
-
-;; Write data to a stream
-(def out (ByteArrayOutputStream. 4096))
-(def writer
-  (transit/writer out :json
-                  {:handlers (merge transit/default-write-handlers
-                                    converge-transit/write-handlers)}))
-(def cref (convergent/ref {:foo :bar
-                           :a   [1 2]}))
-(transit/write writer cref)
-
-cref
-
-;; Take a peek at the JSON
-(.toString out)
-;; => "[\"~#opset/ref\", <snip a bunch of operations ...>]"
-
-;; Read data from a stream
-(def in (ByteArrayInputStream. (.toByteArray out)))
-(def reader
-  (transit/reader in :json
-                  {:handlers (merge transit/default-read-handlers
-                                    converge-transit/read-handlers)}))
-(def read-ref (transit/read reader))
-(prn read-ref)
-;; => #converge.opset.ref.OpsetConvergentRef[{:status :ready, :val {:a [1 2], :foo :bar}} 0x3bd98fc8]
-(prn @read-ref)
-;; => {:a [1 2], :foo :bar}
-```
-
-### ClojureScript + transit-cljs
-
-This is the transit-cljs Usage example, modified to include a
-ConvergentRef and the read/write handlers provided by this library.
-
-
 
-## Development
+(def r (convergent/ref {:foo [:bar #{:baz}]}))
 
-Invoke a library API function from the command-line:
+(def nippy-bytes (nippy/freeze r))
 
-    $ clojure -X converge.transit/foo :a 1 :b '"two"'
-    {:a 1, :b "two"} "Hello, World!"
+(def roundtripped (nippy/thaw nippy-bytes))
 
-Run the project's tests (they'll fail until you edit them):
+@roundtripped
+;=> {:foo [:bar #{:baz}]}
 
-    $ clojure -T:build test
+(def r2 (convergent/ref-from-ops (convergent/ref-log r)))
 
-Run the project's CI pipeline and build a JAR (this will fail until you edit the tests to pass):
+(swap! r assoc :baz :quux)
 
-    $ clojure -T:build ci
+(def patch (convergent/patch-from-clock r (convergent/clock r2)))
 
-This will produce an updated `pom.xml` file with synchronized dependencies inside the `META-INF`
-directory inside `target/classes` and the JAR in `target`. You can update the version (and SCM tag)
-information in generated `pom.xml` by updating `build.clj`.
+(nippy/thaw (nippy/freeze patch))
+;=> <the patch>
 
-Install it locally (requires the `ci` task be run first):
-
-    $ clojure -T:build install
-
-Deploy it to Clojars -- needs `CLOJARS_USERNAME` and `CLOJARS_PASSWORD` environment
-variables (requires the `ci` task be run first):
-
-    $ clojure -T:build deploy
-
-Your library will be deployed to net.clojars.converge/transit on clojars.org by default.
+(def clock (convergent/clock r1))
+(nippy/thaw (nippy/freeze clock))
+;=> <the clock>
+```
 
 ## License
 

storage/README.md

@@ -0,0 +1,46 @@
+# converge/storage
+
+An API for persisting convergent refs to the filesystem in a Git-friendly way.
+
+## Usage
+
+Convergent refs are stored on disk as a directory of Nippy serialized
+patch files, which together comprise the OpSet of the ref.
+
+``` clojure
+(def dirname "a-ref-dir")
+
+(def r (convergent/ref {:foo :bar :baz :quux}))
+
+(sync-directory r dirname)
+;=> returns the name of the patch file added to the directory to bring the
+;   on-disk ref to (at least) the same clock point as the in-memory ref, or
+;   nil if no file was needed/written. If directory doesn't contain a ref,
+;   creates the root file and returns its name. Patch filenames are SHA256-3
+;   hashes of their contents, so writing patches is idempotent.
+
+(def r (from-directory dirname))
+;=> returns a ConvergentRef having the same clock state as on-disk
+
+@r
+
+(swap! r assoc :quux [1 2 :lalala #{:a 'nice "set"} {:of [2 'things]}])
+
+(sync-directory r dirname)
+```
+
+## License
+
+Copyright 2020 Evident Systems LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.