diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +# New in 0.3.1 +- Support path declaration of new `RedisByteString` primitive in core. + # New in 0.3 - Generalized path declarations to any `Store` from `IsIdentifier`. diff --git a/README.md b/README.md deleted file mode 100644 --- a/README.md +++ /dev/null @@ -1,138 +0,0 @@ -# High-level Redis Database - -HLRDB is an opinionated, high-level, type-driven library for modeling Redis-backed database architecture. - -This package provides an easy API for you to declare your data paths in Redis, but in doing so makes many decisions for you about how to serialize and deserialize values, construct identifiers, and define path names. If you want more control over these aspects, you may instead use the HLRDB Core package, which simply defines the commands and the abstract API without opining on these matters. - -## Overview - -Redis is a hash table database with several builtin primitive data structures. It does not use SQL, but instead uses [its own system of primitive commands](https://redis.io/commands). You may find primitive Haskell bindings for these commands [in the Hedis library](https://hackage.haskell.org/package/hedis), on which this library depends. HLRDB provides a type-driven, high-level abstraction on top of this. - -```haskell --- minimal end-to-end, runnable example -import Data.Store -import Database.Redis (checkedConnect,defaultConnectInfo,runRedis) -import HLRDB - -newtype CommentId = CommentId Identifier deriving (Eq,Ord,Show,Store,IsIdentifier) -newtype Comment = Comment String deriving (Eq,Ord,Show,Store) - -cidToComment :: RedisBasic CommentId (Maybe Comment) -cidToComment = declareBasic "canonical mapping from CommentId to Comment" - -main :: IO () -main = do - -- connect to Redis - rconn <- checkedConnect defaultConnectInfo - - cid :: CommentId <- genId - - c :: Maybe Comment <- runRedis rconn $ do - -- create a comment - set' cidToComment cid $ Comment "hi" - -- read it back - get cidToComment cid - - print c - -``` - -## Identifiers - -Use newtypes for `Identifier` for your various data types: - -```haskell - -newtype CommentId = CommentId Identifier deriving (Eq,Ord,Show,Store,IsIdentifier) - --- use genId to create new identifiers: -example :: IO CommentId -example = genId -``` - -## Data structures - -Redis structures are mostly indexed by two types: their identifier and their value. When you declare a structure, you need to provide a unique description, which serves two purposes: first, it helps document what the purpose of the path is, and second, the hash of this string is how HLRDB distinguishes between multiple paths of the same type. - -### Basic - -```haskell --- RedisBasic is used when for standard key-value storage. -cidToComment :: RedisBasic CommentId (Maybe Comment) -cidToComment = declareBasic "canonical mapping from CommentId to Comment" - --- RedisIntegral will treat a non-existent value as 0 -cidToScore :: RedisIntegral CommentId Integer -cidToScore = declareIntegral "comment score" - --- Use `declareBasicZero` to choose your own "zero" for the data type -threadIdToComments :: RedisBasic ThreadId (RoseTree CommentId) -threadIdToComments = declareBasicZero "reddit-style comment threads" Empty -``` - -### Other Redis structures - -For lists and sorted sets, you may optionally provide a `TrimScheme` (a record with two fields, `softCardinality :: Integer` and `trimProbability :: Double`). When provided, HLRDB will automatically trim the structures in Redis to their proper size whenever data is added. - -```haskell --- hset, basically a sub-hash table with a few extra primitive commands -voteHSet :: RedisStructure (HSET CommentId) UserId Vote -voteHSet = declareHSet "whether a user has voted a comment up or down" - --- list, with automatic max-length management with TrimScheme -tidToComments :: RedisList ThreadId CommentId -tidToComments = declareList "non-recursive comment threads" $ Just $ TrimScheme 1000 0.1 - --- sorted sets store items by golf score - lower is better. supports TrimScheme -popularItems :: RedisSSet UserId PostId -popularItems = declareSSet "popular content" $ Just $ TrimScheme 1000 0.01 -- 1k max; trim with probability 0.01 - --- set is intuitive -blockedUsers :: RedisSet UserId UserId -blockedUsers = declareSet "a user's block list" - -``` - -### Global paths - -You may use the global variants of the above to declare paths indexed simply on `()`, rather than an `Identifier` newtype: - -```haskell -bannedUsers :: RedisSet () UserId -bannedUsers = declareGlobalSet "global ban list" -``` - -Once you've declared any of the above structures, you may use the Redis monad to perform operations on them. You may find the operations available for each structure defined in the [HLRDB/Structures](https://github.com/identicalsnowflake/hlrdb-core/tree/master/src/HLRDB/Structures) folder (found in hlrdb-core) for that particular structure. The commands are similar to the original Redis API, but have been cleaned up and re-imagined to support more of a Haskell dialect (e.g., list commands do not crash when passed `[]` as they do in Redis). - -## Lookup Aggregation - -You may lift `RedisBasic i v` (and `RedisIntegral i v`, which is a subtype) paths to `i ⟿ v` queries, which can be combined together in several ways, resulting in a single `mget` command being executed in Redis. This allows constructing detailed data views in an efficient manner. - -If you prefer, `Query i v` is a non-infix alias for `i ⟿ v`. You may also use the ASCII version, `~~>`. - -```haskell - -newtype Views = Views Integer deriving (Show,Eq,Ord,Num,Enum,Real,Integral) -newtype Likes = Likes Integer deriving (Show,Eq,Ord,Num,Enum,Real,Integral) - - -cidToViews :: RedisIntegral CommentId Views -cidToViews = declareIntegral "comment views" - -cidToLikes :: RedisIntegral CommentId Likes -cidToLikes = declareIntegral "comment likes" - - -queryBoth :: CommentId ⟿ (Views , Likes) -queryBoth = (,) <$> liftq cidToViews <*> liftq cidToLikes - -reifyToRedis :: CommentId -> Redis (Views , Likes) -reifyToRedis = mget queryBoth - -``` - -I've written an [in-depth article discussing aggregation here](https://identicalsnowflake.github.io/QueryAggregation.html), but the two most important takeaways are that `⟿` is a `Traversing` `Profunctor` and an `Applicative`. - -## Demo - -There is a [simple demo repository](https://github.com/identicalsnowflake/hlrdb-demo) demonstrating the end-to-end process of defining data models and performing read/write actions. diff --git a/hlrdb.cabal b/hlrdb.cabal --- a/hlrdb.cabal +++ b/hlrdb.cabal @@ -1,5 +1,5 @@ name: hlrdb -version: 0.3.0.0 +version: 0.3.1.0 synopsis: High-level Redis Database description: A library for type-driven interaction with Redis license: MIT @@ -11,9 +11,7 @@ cabal-version: 2.0 homepage: https://github.com/identicalsnowflake/hlrdb bug-reports: https://github.com/identicalsnowflake/hlrdb/issues -extra-source-files: - CHANGELOG.md - README.md +extra-source-files: CHANGELOG.md source-repository head type: git @@ -23,15 +21,15 @@ exposed-modules: HLRDB build-depends: base >= 4.9 && < 5.0 - , base64-bytestring ^>= 1.0.0.1 - , bytestring ^>= 0.10.8.1 - , cryptonite (>= 0.24 && < 0.26) || ^>= 0.26 + , base64-bytestring >= 1.0.0.1 && < 1.1 + , bytestring + , cryptonite >= 0.24 && < 0.27 , hashable , hedis - , hlrdb-core >= 0.1.1 && < 0.2 - , memory (>= 0.14.8 && <=0.14.18) || ^>= 0.14.18 - , random ^>= 1.1 - , store ^>= 0.5.1.1 + , hlrdb-core >= 0.1.6 && < 0.2 + , memory >= 0.14.8 && < 0.16 + , random >= 1.1 && < 1.2 + , store >= 0.5.1.1 && < 0.7.3 , time , unordered-containers hs-source-dirs: src diff --git a/src/HLRDB.hs b/src/HLRDB.hs --- a/src/HLRDB.hs +++ b/src/HLRDB.hs @@ -39,8 +39,7 @@ -- module HLRDB - ( - -- * Identifiers + ( -- * Identifiers Identifier , IsIdentifier(..) , genId @@ -49,6 +48,7 @@ -- * Indexed path declaration , declareBasic , declareIntegral + , declareByteString , declareBasicZero , declareList , declareSet @@ -57,6 +57,7 @@ -- * Global path declaration , declareGlobalBasic , declareGlobalIntegral + , declareGlobalByteString , declareGlobalBasicZero , declareGlobalList , declareGlobalSet @@ -226,6 +227,12 @@ declareIntegral p = RKeyValueInteger (encodePath p) toInteger fromIntegral +-- | Standard key-value store, but backed by no encoding, thus permitting bitwise operations like @getrange@, @setrange@, @getbit@, and @setbit@. +{-# INLINE declareByteString #-} +declareByteString :: Store i => PathName -> RedisByteString i ByteString +declareByteString p = + RKeyValueByteString (encodePath p) + -- | Allows defining your own "zero" value. An example might be RoseTree, where a non-existant value in Redis can be mapped to a sensible empty value in Haskell. {-# INLINE declareBasicZero #-} declareBasicZero :: (Store i, Store v) => PathName -> v -> RedisBasic i v @@ -274,6 +281,11 @@ {-# INLINE declareGlobalIntegral #-} declareGlobalIntegral :: Integral b => PathName -> RedisIntegral () b declareGlobalIntegral (PathName p) = RKeyValueInteger (const p) toInteger fromIntegral + +-- | A global version of @declareByteString@ +{-# INLINE declareGlobalByteString #-} +declareGlobalByteString :: PathName -> RedisByteString () ByteString +declareGlobalByteString (PathName p) = RKeyValueByteString (const p) -- | A global version of @declareZero@ {-# INLINE declareGlobalBasicZero #-}