diff --git a/README.md b/README.md index f140104..3252500 100644 --- a/README.md +++ b/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 ) ; => Serialized byte[] + +;; Thaw the byte[] to get back the original value: +(nippy/thaw (nippy/freeze )) ; => +``` + +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.) diff --git a/src/taoensso/nippy.clj b/src/taoensso/nippy.clj index daf067c..c8a1aaf 100644 --- a/src/taoensso/nippy.clj +++ b/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 [] diff --git a/src/taoensso/nippy/compression.clj b/src/taoensso/nippy/compression.clj index d9bf1b9..562ab6a 100644 --- a/src/taoensso/nippy/compression.clj +++ b/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))