keyed-vals: An abstract Handle for accessing collections in stores like Redis

[ bsd3, data, library, redis ] [ Propose Tags ]

Provides an abstract Handle for accessing stored key-value collections, and useful combinators that use Handle.

One implementation of Handle accesses collections in Redis other backends are possible.

keyed-vals also provides a typed interface to the storage backend that allows the path in the storage backend to be declaratively linked to the types of data stored via a straightforward typeclass declaration.

Read this short example for an introduction its usage.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.2.0.0, 0.2.1.0, 0.2.2.0, 0.2.3.0, 0.2.3.1
Change log ChangeLog.md
Dependencies aeson (>=1.5.1 && <2.3), base (>=4.11 && <5.0), bytestring (>=0.10.8.2 && <0.11 || >=0.11.3.1 && <0.12.2), containers (>=0.6.5 && <0.8), http-api-data (>=0.5 && <0.7), redis-glob (>=0.1 && <0.2), text (>=1.2.4 && <1.3 || >=2.0) [details]
License BSD-3-Clause
Author Tim Emiola
Maintainer adetokunbo@emio.la
Category Data, Redis
Home page https://github.com/adetokunbo/keyed-vals#readme
Bug tracker https://github.com/adetokunbo/keyed-vals/issues
Source repo head: git clone https://github.com/adetokunbo/keyed-vals.git
Uploaded by adetokunbo at 2024-02-29T08:06:20Z
Distributions LTSHaskell:0.2.3.1, NixOS:0.2.3.0, Stackage:0.2.3.1
Reverse Dependencies 3 direct, 0 indirect [details]
Downloads 287 total (37 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-02-29 [all 1 reports]

Readme for keyed-vals-0.2.3.1

[back to package description]

keyed-vals

GitHubCI StackageNightly Hackage HackageDependencies BSD3

keyed-vals aims to provide a narrow client for storing key-value collections in storage services like Redis.

E.g,

  • Redis supports many other features
  • the abstract Handle declared in keyed-vals just provides combinators that operate on key-value collections stored in some backend
  • so the redis implementation of Handle accesses collections in Redis without exposing its other features.

Example

{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE DerivingVia #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE StandaloneDeriving #-}

import Data.Aeson (FromJSON, ToJSON)
import Data.Text (Text)
import GHC.Generics (Generic)
import KeyedVals.Handle.Codec.Aeson (AesonOf(..))
import KeyedVals.Handle.Codec.HttpApiData (HttpApiDataOf(..))
import qualified KeyedVals.Handle.Mem as Mem
import KeyedVals.Handle.Typed
import Web.HttpApiData (FromHttpApiData (..), ToHttpApiData (..))

{- Usage is fairly simple:

- Declare 'PathOf' and possibly a 'VaryingPathOf' instance for
  storable data types.

They describe how the data type is encoded and decoded and where in the
key-value store the data should be saved.

For example, given the following data type:
-}
data Person = Person
  { name :: Text
  , age  :: Int
  } deriving (Eq, Show, Generic)

{- Suppose each @Person@ is to be stored as JSON, via the @Generic@
implementation, e.g,
-}
instance FromJSON Person
instance ToJSON Person

{- Also suppose each Person is stored with an @Int@ key. To enable that,
define a @newtype@ of @Int@, e.g,
-}
newtype PersonID = PersonID Int
  deriving stock (Eq, Show)
  deriving (ToHttpApiData, FromHttpApiData, Num, Ord) via Int

{- And then suppose the collection of @Person@s is stored at a specific fixed path
in the key-value store. E.g, it is to be used as a runtime cache to speed up
access to person data, so the path @/runtime/cache/persons@ is used.

To specify all of this, first define @DecodeKV@ and @EncodeKV@ instances for
@Person@:
-}
deriving via (AesonOf Person) instance DecodeKV Person
deriving via (AesonOf Person) instance EncodeKV Person

{- .. and do the same for @PersonID@: -}
deriving via (HttpApiDataOf Int) instance DecodeKV PersonID
deriving via (HttpApiDataOf Int) instance EncodeKV PersonID


{- Then declare a @PathOf@ instance that binds the types together with the path: -}
instance PathOf Person where
  type KVPath Person = "/runtime/cache/persons"
  type KeyType Person = PersonID

{- Note: the @DecodeKV@ and @EncodeKV@ deriving statements above were
standalone for illustrative purposes. In most cases, they ought to be part
of the deriving clause of the data type. E.g,
-}
newtype FriendID = FriendID Int
  deriving stock (Eq, Show)
  deriving (ToHttpApiData, FromHttpApiData, Num, Ord) via Int
  deriving (DecodeKV, EncodeKV) via (HttpApiDataOf Int)

{- Now save and fetch @Person@s from a storage backend as follows:

>>> handle <- Mem.new
>>> tim = Person { name = "Tim", age = 48 }
>>> saveTo handle (key 1) tim
Right ()
>>> loadFrom handle (key 1)
Right (Person { name = "Tim", age = 48 })

-}

{- Suppose that in addition to the main collection of @Person@s, it's
necessary to store a distinct list of the friends of each @Person@.
I.e, store a small keyed collection of @Person@s per person.

One way to achieve is to store each such collection at a similar path, e.g
suppose the friends for the person with @anID@ are stored at
@/app/person/<anId>/friends@.

This can be implemented using the existing types along with another newtype
that has @PathOf@ and @VaryingPathOf@ instances as follows
-}

newtype Friend = Friend Person
  deriving stock (Eq, Show)
  deriving (FromJSON, ToJSON, EncodeKV, DecodeKV) via Person

instance PathOf Friend where
  type KVPath Friend = "/app/person/{}/friends"
  type KeyType Friend = FriendID -- as defined earlier

instance VaryingPathOf Friend where
  type PathVar Friend = PersonID
  modifyPath _ = expand -- implements modifyPath by expanding the braces to PathVar


{- This allows @Friends@ to be saved or fetched as follows:

>>> dave = Person { name = "Dave", age = 61 }
>>> saveTo handle (key 2) dave -- save in main person list
Right ()
>>> saveTo handle ( 1 // 2) (Friend dave) -- save as friend of tim (person 1)
Right ()
-}