[nop] Housekeeping

Author: ptaoussanis

README.md

@@ -22,18 +22,35 @@ See [here][GitHub releases] for earlier releases.
 
 ## Why Nippy?
 
-- Small, simple **all-Clojure** library
+- Small, simple **pure-Clojure** library
 - **Terrific performance**: the [best](#performance) for Clojure that I'm aware of
 - Comprehensive support for [all standard data types](../../wiki/1-Getting-started#deserializing)
 - Easily extendable to [custom data types](../../wiki/1-Getting-started#custom-types)
-- **Robust test suite**, incl. full coverage for every supported type
-- Auto fallback to [Java Serializable](https://taoensso.github.io/nippy/taoensso.nippy.html#var-*freeze-serializable-allowlist*) when available
-- Auto fallback to Clojure Reader for all other types (including tagged literals)
-- Pluggable **compression** with built-in [LZ4](https://code.google.com/p/lz4/), [Zstandard](https://facebook.github.io/zstd/), etc.
-- Pluggable [encryption](../../wiki/1-Getting-started#encryption) with built-in AES128
+- **Robust test suite** incl. coverage of every supported type
+- **Mature** and widely used in production for 12+ years
+- Optional auto fallback to [Java Serializable](https://taoensso.github.io/nippy/taoensso.nippy.html#var-*freeze-serializable-allowlist*) for [safe](https://cljdoc.org/d/com.taoensso/nippy/CURRENT/api/taoensso.nippy#*freeze-serializable-allowlist*) types
+- Optional auto fallback to Clojure Reader (including tagged literals)
+- Optional smart **compression** with [LZ4](https://code.google.com/p/lz4/) or [Zstandard](https://facebook.github.io/zstd/)
+- Optional [encryption](../../wiki/1-Getting-started#encryption) with AES128
 - [Tools](https://taoensso.github.io/nippy/taoensso.nippy.tools.html) for easy + robust **integration into 3rd-party libraries**, etc.
 - Powerful [thaw transducer](https://taoensso.github.io/nippy/taoensso.nippy.html#var-*thaw-xform*) for flexible data inspection and transformation
 
+## Quick example
+
+Nippy's super easy to use:
+
+```clojure
+(require '[taoensso.nippy :as nippy])
+
+;; Freeze any Clojure value
+(nippy/freeze <my-value>) ; => Serialized byte[]
+
+;; Thaw the byte[] to get back the original value:
+(nippy/thaw (nippy/freeze <my-value>)) ; => <my-value>
+```
+
+See the [wiki](https://github.com/taoensso/nippy/wiki/1-Getting-started#deserializing) for more.
+
 ## Operational considerations
 
 ### Data longevity
@@ -69,10 +86,12 @@ So starting with Nippy v3.4, Nippy's release notes will **always clearly indicat
 
 ## Performance
 
-Since its earliest versions, Nippy has consistently been the **fastest serialization library for Clojure** that I'm aware of. Latest [benchmark](../../blob/master/test/taoensso/nippy_benchmarks.clj) results:
+Since its earliest versions, Nippy has consistently been the **fastest serialization library for Clojure** that I'm aware of. Latest results:
 
 ![benchmarks-png](../../raw/master/benchmarks.png)
 
+PRs welcome to include other alternatives in the [benchmark suite](../../blob/master/test/taoensso/nippy_benchmarks.clj)!
+
 ## Documentation
 
 - [Wiki][GitHub wiki] (getting started, usage, etc.)

src/taoensso/nippy.clj

@@ -1259,7 +1259,7 @@
     - Compression is often benefitial at little/no cost
     - The performance difference between `freeze` and `fast-freeze` is
       often negligible in practice."
-  [x]
+  ^bytes [x]
   (let [baos (ByteArrayOutputStream. 64)
         dos  (DataOutputStream. baos)]
     (with-cache (-freeze-with-meta! x dos))
@@ -1268,11 +1268,13 @@
 (defn freeze
   "Serializes arg (any Clojure data type) to a byte array.
   To freeze custom types, extend the Clojure reader or see `extend-freeze`."
-  ([x] (freeze x nil))
-  ([x {:as   opts
-       :keys [compressor encryptor password serializable-allowlist incl-metadata?]
-       :or   {compressor :auto
-              encryptor  aes128-gcm-encryptor}}]
+  (^bytes [x] (freeze x nil))
+  (^bytes
+   [x
+    {:as   opts
+     :keys [compressor encryptor password serializable-allowlist incl-metadata?]
+     :or   {compressor :auto
+            encryptor  aes128-gcm-encryptor}}]
 
    (call-with-bindings :freeze opts
      (fn []

src/taoensso/nippy/compression.clj

@@ -174,8 +174,8 @@
 (def lz4-compressor
   "Default `LZ4` compressor:
     -   Compression ratio: `C`  (0.58      on reference benchmark).
-    -   Compression speed: `A`  (238 msecs on reference benchmark).
-    - Decompression speed: `A+` (31  msecs on reference benchmark).
+    -   Compression speed: `A`  (240 msecs on reference benchmark).
+    - Decompression speed: `A+` (30  msecs on reference benchmark).
 
   Good general-purpose compressor, favours speed.
   See `taoensso.nippy-benchmarks` for detailed comparative benchmarks."
@@ -184,8 +184,8 @@
 (def lzo-compressor
   "Default `LZO` compressor:
     -   Compression ratio: `C` (0.58      on reference benchmark).
-    -   Compression speed: `A` (216 msecs on reference benchmark).
-    - Decompression speed: `A` (43  msecs on reference benchmark).
+    -   Compression speed: `A` (220 msecs on reference benchmark).
+    - Decompression speed: `A` (40  msecs on reference benchmark).
 
   Good general-purpose compressor, favours speed.
   See `taoensso.nippy-benchmarks` for detailed comparative benchmarks."
@@ -195,7 +195,7 @@
   "Default `LZMA2` compressor:
     -   Compression ratio: `A+` (0.4       on reference benchmark).
     -   Compression speed: `E`  (18.5 secs on reference benchmark).
-    - Decompression speed: `D`  (11.8 secs on reference benchmark).
+    - Decompression speed: `D`  (12   secs on reference benchmark).
 
   Specialized compressor, strongly favours ratio.
   See `taoensso.nippy-benchmarks` for detailed comparative benchmarks."
@@ -204,8 +204,8 @@
 (enc/def* snappy-compressor
   "Default `Snappy` compressor:
     -   Compression ratio: `C`  (0.58      on reference benchmark).
-    -   Compression speed: `A+` (206 msecs on reference benchmark).
-    - Decompression speed: `B`  (134 msecs on reference benchmark).
+    -   Compression speed: `A+` (210 msecs on reference benchmark).
+    - Decompression speed: `B`  (130 msecs on reference benchmark).
   Good general-purpose compressor, favours speed.
   See `taoensso.nippy-benchmarks` for detailed comparative benchmarks."
   (SnappyCompressor. false))