datomlite (empty) → 0.1.0.0
raw patch · 9 files changed
+4620/−0 lines, 9 filesdep +basedep +bytestringdep +containers
Dependencies added: base, bytestring, containers, datomlite, stm, tasty, tasty-hunit, text, time
Files
- CHANGELOG.md +16/−0
- Datomlite.hs +1613/−0
- LICENSE +201/−0
- README.md +1265/−0
- datomlite.cabal +56/−0
- test/Demo.hs +183/−0
- test/Helpers.hs +9/−0
- test/Shared.hs +170/−0
- test/Test.hs +1107/−0
+ CHANGELOG.md view
@@ -0,0 +1,16 @@+# Changelog++## 0.1.0.0++Initial release.++- Immutable database value: an append-only log of datoms, indexed two ways+- Your plain Haskell records are the schema. Unique fields are declared at the type level+- Bad schemas fail at compile time+- Atomic transactions, either as a list of writes or a do-block+- Lookup refs, so you can point at an entity by its unique field+- Queries are do-blocks, with joins, negation and recursion+- Window functions (rank, lag, running totals...)+- Time travel: read the db as it was at any transaction or point in time, or see a fact's history+- A connection type for the IO side, with change listeners+- The whole library is one file. Copy it into your project and you're done
+ Datomlite.hs view
@@ -0,0 +1,1613 @@+{-# LANGUAGE AllowAmbiguousTypes #-}+{-# LANGUAGE ConstraintKinds #-}+{-# LANGUAGE DataKinds #-}+{-# LANGUAGE DefaultSignatures #-}+{-# LANGUAGE FlexibleContexts #-}+{-# LANGUAGE FlexibleInstances #-}+{-# LANGUAGE GADTs #-}+{-# LANGUAGE MultiParamTypeClasses #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE PolyKinds #-}+{-# LANGUAGE RoleAnnotations #-}+{-# LANGUAGE ScopedTypeVariables #-}+{-# LANGUAGE TypeApplications #-}+{-# LANGUAGE TypeFamilies #-}+{-# LANGUAGE TypeOperators #-}+{-# LANGUAGE UndecidableInstances #-}++-- |+-- A lightweight immutable database. The 'Db' is a plain value... 'commit'+-- hands back a new one and every past state stays queryable.+--+-- Records are the schema. A field's type says how it is stored and+-- 'Identity' names the fields that identify an entity:+--+-- @+-- \{\-\# LANGUAGE DeriveGeneric, DeriveAnyClass, DataKinds, TypeFamilies \#\-\}+-- \{\-\# LANGUAGE OverloadedRecordDot, OverloadedStrings \#\-\}+-- import Datomlite+--+-- data Department = Department { code :: Text, deptName :: Text }+-- deriving Generic+-- instance Entity Department where+-- type Identity Department = '[\"code\"]+--+-- data Employee = Employee+-- { email :: Text -- one value+-- , name :: Text+-- , dept :: Ref Department -- another entity+-- , skills :: Set Text -- many values+-- , nick :: Maybe Text -- optional+-- } deriving Generic+-- instance Entity Employee where+-- type Identity Employee = '[\"email\"] -- unique, and what 'upsert' goes by+-- @+--+-- Writes are a list of 'Write's that commit all at once. A 'ref' names an+-- entity by its identity, so records in one list can point at each other:+--+-- @+-- commit_ db+-- [ Upsert (Department \"ENG\" \"Engineering\")+-- , Upsert (Employee \"m\@x.io\" \"Max\" (ref \@Department \"ENG\") mempty Nothing)+-- ]+-- @+--+-- A 'Tx' do-block ('insert', 'upsert', 'update', 'retract') is for steps that+-- need each other's results. 'commit' takes either.+--+-- Every read ('load', 'every', 'find' and queries) hands back a 'Stored'+-- record: @p.name@ reads a field and 'refOf' gives its 'Ref'.+--+-- Queries are do-blocks over those records:+--+-- @+-- query db $ do+-- e <- match \@Employee+-- d <- follow e.dept+-- guard (d.deptName == \"Engineering\")+-- pure (e.email, e.name)+-- @+--+-- A wrong field or type is a compile error. 'match' scans... 'follow' and+-- 'matchBy' go straight to the entity.+--+-- The log is open: 'history' and 'datoms' hand back every 'Datom', and+-- 'fromHistory' builds a 'Db' from them.+module Datomlite+ ( -- * The database value+ Db+ , emptyDb+ , TxId (..)+ , basisT+ , asOf+ , asOfTime+ , txTime+ , since++ -- * The log: every fact+ , history+ , fromHistory+ , datoms+ , Datom (..)+ , Op (..)+ , refId++ -- * Schema: records are the schema+ , Entity (Identity, ename)+ , Ref+ , ref+ , refBy+ , ToValue (..)+ , FromValue (..)++ -- * Writing: build a Tx, then commit it+ , Tx+ , insert+ , insert_+ , upsert+ , upsert_+ , update+ , setField+ , retract+ , txDb+ , abort+ , Write (..)+ , Writes (Result)+ , commit+ , commit_+ , commitAt+ , TxError (..)+ , Attr+ , Value (..)+ , EntityId (..)++ -- * Reading records+ , Stored+ , refOf+ , recordOf+ , load+ , every+ , find+ , findBy+ , LoadError (..)++ -- * Querying: do-blocks over records+ , Query+ , query+ , match+ , matchBy+ , follow+ , oneOf+ , closure+ , exists+ , none++ -- * Window functions over results+ , Window+ , window+ , rowNumber+ , rank+ , denseRank+ , lag+ , lead+ , whole+ , running++ -- * The IO edge+ , Conn+ , connect+ , snapshot+ , transact++ -- * Reacting to commits+ , listen+ , watch+ , awaitAfter+ , TxReport (..)+ ) where++import Control.Applicative (Alternative (..))+import Control.Concurrent (forkIO)+import Control.Concurrent.MVar (MVar, newMVar, withMVar)+import Control.Concurrent.STM (STM, TVar, atomically, check, newTVarIO, orElse,+ readTVar, readTVarIO, writeTVar)+import Control.Exception (Exception (..), SomeAsyncException, SomeException,+ catch, evaluate, fromException, throw, throwIO)+import Control.Monad (MonadPlus, ap, forM_, unless, void, when)+import Data.ByteString (ByteString)+import qualified Data.ByteString as BS+import Data.Foldable (toList, traverse_)+import Data.IORef (newIORef, readIORef, writeIORef)+import Data.Kind (Constraint, Type)+import Data.List (group, inits, nub, sortBy, sortOn)+import qualified Data.List as List+import Data.Map.Strict (Map)+import qualified Data.Map.Strict as Map+import Data.Maybe (isJust)+import Data.Ord (comparing)+import Data.Proxy (Proxy (..))+import Data.Sequence (Seq (..), (><))+import qualified Data.Sequence as Seq+import Data.Set (Set)+import qualified Data.Set as Set+import Data.Text (Text)+import qualified Data.Text as T+import qualified Data.Text.Encoding as T+import Data.Time (Day, UTCTime (..), getCurrentTime)+import Data.Type.Bool (If, type (&&), type (||))+import GHC.Generics+import GHC.Records (HasField (..))+import GHC.TypeLits (ErrorMessage (..), KnownSymbol, Symbol, TypeError,+ symbolVal)+import System.IO (stderr)++--------------------------------------------------------------------------------+-- The log and the Db++-- | An entity's id. 'insert' hands them out and they're never reused. The+-- constructor is there for writing your own encoding of the log.+newtype EntityId = EntityId Int+ deriving (Eq, Ord, Show, Read)++-- | An attribute name, e.g. @"Employee/email"@.+type Attr = Text++-- | What a 'Datom' can hold. Strict so a value that throws does so on commit+-- and not on some later read.+--+-- Values key the AVET index so they need an order. @NaN@ equals @NaN@ and+-- sorts above every other double... so it can be stored and retracted like+-- any value.+data Value+ = VInt !Int+ | VText !Text+ | VBool !Bool+ | VRef !EntityId+ | VDouble !Double+ | VInteger !Integer+ | VBytes !ByteString+ | VInstant !UTCTime+ | VDay !Day+ -- | The entity holding a value for an identity attribute. Only in writes:+ -- 'ref' makes one and commit swaps in the 'VRef' it names, so it's never+ -- stored.+ | VLookup !Attr !Value+ deriving (Show, Read)++instance Eq Value where+ x == y = compare x y == EQ++instance Ord Value where+ compare (VInt a) (VInt b) = compare a b+ compare (VText a) (VText b) = compare a b+ compare (VBool a) (VBool b) = compare a b+ compare (VRef a) (VRef b) = compare a b+ compare (VDouble a) (VDouble b) = compareDouble a b+ compare (VInteger a) (VInteger b) = compare a b+ compare (VBytes a) (VBytes b) = compare a b+ compare (VInstant a) (VInstant b) = compare a b+ compare (VDay a) (VDay b) = compare a b+ compare (VLookup a v) (VLookup b w) = compare (a, v) (b, w)+ compare a b = compare (tag a) (tag b)+ where+ tag :: Value -> Int+ tag v = case v of+ VInt _ -> 0+ VText _ -> 1+ VBool _ -> 2+ VRef _ -> 3+ VDouble _ -> 4+ VInteger _ -> 5+ VBytes _ -> 6+ VInstant _ -> 7+ VDay _ -> 8+ VLookup _ _ -> 9++-- A total order on doubles: NaN equals NaN and sorts last+compareDouble :: Double -> Double -> Ordering+compareDouble a b+ | isNaN a = if isNaN b then EQ else GT+ | isNaN b = LT+ | otherwise = compare a b++-- | A transaction id. Always increasing and what 'asOf' and 'since' take.+newtype TxId = TxId Int+ deriving (Eq, Ord, Show, Read)++-- | Whether a datom asserts or retracts a fact.+data Op = Assert | Retract+ deriving (Eq, Ord, Show, Read)++-- | One fact. 'Show' and 'Read' round-trip so one datom per line is already a+-- file format (see 'fromHistory').+data Datom = Datom+ { dEntity :: !EntityId+ , dAttr :: !Attr+ , dValue :: !Value+ , dTx :: !TxId+ , dOp :: !Op+ } deriving (Eq, Show, Read)++-- | The log plus the live indexes built from it and the id counters. Abstract+-- so the indexes can't drift from the log.+--+-- Strict: a 'Db' in WHNF has every datom indexed... so every 'Value' in it is+-- evaluated.+data Db = Db+ { dbLog :: ![Datom] -- newest first+ , dbEavt :: !(Map EntityId (Map Attr [Datom])) -- live, oldest first+ , dbAvet :: !(Map Attr (Map Value (Set EntityId))) -- live+ , dbBasis :: !TxId -- last tx seen+ , dbNextTx :: !Int+ , dbNextE :: !Int+ , dbPartial :: !Bool -- a 'since' window+ , dbTimes :: !(Map TxId UTCTime) -- from the db/txInstant datoms+ } deriving (Eq, Show)++-- | The empty database.+emptyDb :: Db+emptyDb = Db { dbLog = [], dbEavt = Map.empty, dbAvet = Map.empty+ , dbBasis = TxId 0, dbNextTx = 1, dbNextE = 1, dbPartial = False+ , dbTimes = Map.empty }++-- | Whether this is a 'since' view. Those can hold just part of an entity.+partialView :: Db -> Bool+partialView = dbPartial++-- | The last transaction in this 'Db'. Hold on to it to come back with 'asOf':+--+-- @+-- let t = basisT db -- remember now+-- ...+-- query (asOf t db') q -- ask then+-- @+basisT :: Db -> TxId+basisT = dbBasis++-- | Hand out a new entity id.+freshEntity :: Db -> (EntityId, Db)+freshEntity db = (EntityId (dbNextE db), db { dbNextE = dbNextE db + 1 })++-- | When a transaction was committed, if it was stamped (see 'commitAt').+txTime :: TxId -> Db -> Maybe UTCTime+txTime tx db = Map.lookup tx (dbTimes db)++-- The attribute a tx's wall-clock time is logged under+txInstant :: Attr+txInstant = "db/txInstant"++-- Fold one datom into the live indexes. Asserting a live fact again or+-- retracting a dead one is a no-op. A tx time goes to 'dbTimes' and not the+-- indexes... it's about the tx and not an entity+index :: Db -> Datom -> Db+index db d@(Datom e a v tx op)+ | a == txInstant, VInstant t <- v = db { dbTimes = Map.insert tx t (dbTimes db) }+ | otherwise = case op of+ Assert | not live -> db { dbEavt = addFact (dbEavt db), dbAvet = addHolder (dbAvet db) }+ Retract | live -> db { dbEavt = dropFact (dbEavt db), dbAvet = dropHolder (dbAvet db) }+ _ -> db+ where+ live = e `Set.member` holders a v db+ addFact = Map.insertWith (Map.unionWith (flip (++))) e (Map.singleton a [d])+ addHolder = Map.insertWith (Map.unionWith Set.union) a (Map.singleton v (Set.singleton e))+ dropFact = Map.update (nonEmpty . Map.update (nonEmpty . filter ((/= v) . dValue)) a) e+ dropHolder = Map.update (nonEmpty . Map.update (nonEmpty . Set.delete e) v) a++-- Map.update and friends delete a key whose value comes back Nothing+nonEmpty :: Foldable t => t x -> Maybe (t x)+nonEmpty xs+ | null xs = Nothing+ | otherwise = Just xs++-- Rebuild a database from a log (newest first). The id counters are kept+reindex :: [Datom] -> Db -> Db+reindex lg db =+ List.foldl' index db { dbLog = lg, dbEavt = Map.empty, dbAvet = Map.empty, dbTimes = Map.empty }+ (reverse lg)++-- Datoms still missing their tx id. Commit stamps it on+type TxData = [(EntityId, Attr, Value, Op)]++-- | A committed transaction: its id, its time if it was stamped and the+-- datoms it wrote.+data TxReport = TxReport+ { trTxId :: TxId+ , trTime :: Maybe UTCTime+ , trDatoms :: [Datom]+ } deriving (Eq, Show)++-- The id the next commit will get+pendingTx :: Db -> TxId+pendingTx db = TxId (dbNextTx db)++-- Write datoms under the pending tx without closing it. A transaction can be+-- built in steps and still commit as one+stage :: TxData -> Db -> Db+stage ops db = List.foldl' index db { dbLog = reverse ds ++ dbLog db } ds+ where ds = [ Datom e a v (pendingTx db) o | (e, a, v, o) <- ops ]++-- | Log a wall-clock time for the pending transaction. Never earlier than the+-- last one so times only go forward even if the clock doesn't.+stampTime :: UTCTime -> Db -> Db+stampTime t db = stage [(EntityId 0, txInstant, VInstant t', Assert)] db+ where t' = maybe t (max t . snd) (Map.lookupMax (dbTimes db))++-- | Close the pending transaction: everything staged becomes that tx.+closeTx :: Db -> Db+closeTx db = db { dbBasis = pendingTx db, dbNextTx = dbNextTx db + 1 }++-- | The database as of a transaction (that one included).+asOf :: TxId -> Db -> Db+asOf tx db = (reindex (filter ((<= tx) . dTx) (dbLog db)) db) { dbBasis = min tx (dbBasis db) }++-- | The database as of a wall-clock time: up to the last transaction stamped+-- at or before @t@. An unstamped one (a pure 'commit') goes with the stamp+-- before it.+asOfTime :: UTCTime -> Db -> Db+asOfTime t db = case [ tx | (tx, u) <- Map.toAscList (dbTimes db), u > t ] of+ (TxId k : _) -> asOf (TxId (k - 1)) db+ [] -> db++-- | Only the facts written after a transaction.+--+-- An entity written before @tx@ and changed after only has part of its facts+-- here... so 'load' and queries just see the entities that are whole in the+-- window. It's read only: 'commit' on one fails with 'SinceView'.+since :: TxId -> Db -> Db+since tx db = (reindex (filter ((> tx) . dTx) (dbLog db)) db) { dbPartial = True }++-- | Every datom ever asserted or retracted, oldest first.+history :: Db -> [Datom]+history = reverse . dbLog++-- | Rebuild a database from its log. The inverse of 'history' and how you+-- restore a saved one:+--+-- @+-- writeFile \"db.log\" (unlines (map show (history db)))+-- db <- fromHistory . map read . lines \<$\> readFile \"db.log\"+-- @+--+-- Datoms replay in tx order and keep their order within a tx. New entity ids+-- start past every id in the log (refs included). A trailing empty transaction+-- is lost... so 'basisT' is the last one that wrote something.+fromHistory :: [Datom] -> Db+fromHistory ds =+ db { dbBasis = TxId lastTx, dbNextTx = lastTx + 1, dbNextE = lastE + 1 }+ where+ db = reindex (reverse (sortOn dTx ds)) emptyDb+ lastTx = maximum (0 : [ t | Datom { dTx = TxId t } <- ds ])+ lastE = maximum (0 : concat [ e : refTo (dValue d)+ | d@Datom { dEntity = EntityId e } <- ds ])+ refTo (VRef (EntityId r)) = [r]+ refTo _ = []++-- | The live datoms grouped by entity.+datoms :: Db -> [Datom]+datoms db = concatMap (concat . Map.elems) (Map.elems (dbEavt db))++-- | An entity's live values by attribute. A many-valued attribute lists its+-- values in the order they were asserted.+entityAttrs :: EntityId -> Db -> Map Attr [Value]+entityAttrs e db = maybe Map.empty (Map.map (map dValue)) (Map.lookup e (dbEavt db))++-- | All of an entity's values for an attribute.+lookupValues :: EntityId -> Attr -> Db -> [Value]+lookupValues e a db = Map.findWithDefault [] a (entityAttrs e db)++-- | The entities holding a value for an attribute. An AVET lookup.+entitiesWith :: Attr -> Value -> Db -> [EntityId]+entitiesWith a v db = Set.toList (holders a v db)++holders :: Attr -> Value -> Db -> Set EntityId+holders a v db = maybe Set.empty (Map.findWithDefault Set.empty v) (Map.lookup a (dbAvet db))++-- | The entities holding any attribute in a namespace (any @Employee\/…@ for+-- @"Employee"@). In creation order.+entitiesInNamespace :: Text -> Db -> [EntityId]+entitiesInNamespace ns db =+ Set.toList . Set.unions . concatMap Map.elems . Map.elems+ . Map.takeWhileAntitone (prefix `T.isPrefixOf`)+ . Map.dropWhileAntitone (< prefix)+ $ dbAvet db+ where prefix = ns <> "/"++-- | The entity holding a value for an attribute. Meant for unique attributes+-- where there's at most one.+uniqueAt :: Attr -> Value -> Db -> Maybe EntityId+uniqueAt a v db = Set.lookupMin (holders a v db)++-- | A connection: the current 'Db' in a 'TVar' for readers and a lock writers+-- take turns on.+data Conn = Conn (TVar Db) (MVar ())++-- | Open a connection on a starting 'Db'.+connect :: Db -> IO Conn+connect db = Conn <$> newTVarIO db <*> newMVar ()++-- | The connection's 'Db' right now. A value, so later commits don't touch it.+snapshot :: Conn -> IO Db+snapshot (Conn v _) = readTVarIO v++-- | Run a pure step on the connection's 'Db' and swap in the result. 'transact'+-- is built on this.+--+-- Writers take turns and the step is fully evaluated before the swap. A step+-- never re-runs and readers only ever see a finished 'Db'. A step that throws+-- leaves the connection as it was.+atomicUpdate :: Conn -> (Db -> (Db, r)) -> IO r+atomicUpdate (Conn v lock) f = withMVar lock $ \() -> do+ (db', r) <- f <$> readTVarIO v+ _ <- evaluate db'+ r' <- evaluate r+ atomically (writeTVar v db')+ pure r'++-- | Block until the connection is past a transaction and return its 'Db'.+-- It's just 'STM' so it composes with 'Control.Concurrent.STM.orElse' or a+-- timeout.+--+-- @+-- db' <- atomically (awaitAfter conn (basisT db))+-- @+awaitAfter :: Conn -> TxId -> STM Db+awaitAfter (Conn v _) t = do+ db <- readTVar v+ check (dbBasis db > t)+ pure db++-- | One 'TxReport' per transaction after the given one (oldest first). An empty+-- transaction gets an empty report.+txsAfter :: TxId -> Db -> [TxReport]+txsAfter t@(TxId after) db = [ report (TxId i) | i <- [after + 1 .. latest] ]+ where+ TxId latest = dbBasis db+ report tx = TxReport tx (txTime tx db) (Map.findWithDefault [] tx byTx)+ -- walking the newest-first log and prepending puts each tx's datoms back in order+ byTx = Map.fromListWith (++) [ (dTx d, [d]) | d <- takeWhile ((> t) . dTx) (dbLog db) ]++--------------------------------------------------------------------------------+-- Schema++-- Records as the schema. Field types give cardinality and 'Identity' names+-- the unique fields... a Generic-derived 'Entity' shreds a record into datoms+-- and back.++-- | A typed reference to another entity: @dept :: Ref Department@.+--+-- One from the database ('insert', 'upsert', a read) holds the entity's id so+-- it always points at the type it claims. 'ref' makes a lookup ref instead:+-- the entity holding an 'Identity' value, found when it's written or read.+-- Its role is nominal so 'coerce' can't cheat either.+--+-- Refs compare by what they hold, so a lookup ref never equals the id it+-- resolves to. Compare refs from the database: @guard (e.dept == refOf d)@.+data Ref a+ = Ref EntityId+ | LookupRef Attr Value+ deriving (Eq, Ord, Show)+type role Ref nominal++-- | The 'EntityId' behind a 'Ref' from the database. A lookup ref has none+-- until it's resolved, so this throws on one: read it first with 'load'.+refId :: Ref a -> EntityId+refId (Ref e) = e+refId (LookupRef a v) =+ error ("datomlite: refId of the lookup ref " <> T.unpack a <> " " <> show v+ <> ", which has no id until it's resolved. load it and use refOf")++-- The entity a ref names in a database, if any+resolve :: Ref a -> Db -> Maybe EntityId+resolve (Ref e) _ = Just e+resolve (LookupRef a v) db = uniqueAt a v db++-- | Scalars that can be stored as a 'Value'. Enums derive one (stored by+-- constructor name) and newtypes can borrow the wrapped type's:+--+-- @+-- data Status = Active | Banned+-- deriving stock (Generic, Eq, Ord)+-- deriving anyclass (ToValue, FromValue)+--+-- newtype Email = Email Text+-- deriving newtype (Eq, Ord, ToValue, FromValue)+-- @+class ToValue a where+ toValue :: a -> Value+ default toValue :: (Generic a, GEnum (Rep a)) => a -> Value+ toValue = VText . genumName . from++-- | The inverse of 'toValue'.+class FromValue a where+ fromValue :: Value -> Maybe a+ default fromValue :: (Generic a, GEnum (Rep a)) => Value -> Maybe a+ fromValue (VText t) = to <$> genumFrom t+ fromValue _ = Nothing++instance ToValue Text where toValue = VText+instance FromValue Text where+ fromValue (VText t) = Just t+ fromValue _ = Nothing++instance ToValue Int where toValue = VInt+instance FromValue Int where+ fromValue (VInt n) = Just n+ fromValue _ = Nothing++instance ToValue Bool where toValue = VBool+instance FromValue Bool where+ fromValue (VBool b) = Just b+ fromValue _ = Nothing++instance ToValue (Ref t) where+ toValue (Ref e) = VRef e+ toValue (LookupRef a v) = VLookup a v+instance FromValue (Ref t) where+ fromValue (VRef e) = Just (Ref e)+ fromValue _ = Nothing++instance ToValue Double where toValue = VDouble+instance FromValue Double where+ fromValue (VDouble d) = Just d+ fromValue _ = Nothing++instance ToValue Integer where toValue = VInteger+instance FromValue Integer where+ fromValue (VInteger n) = Just n+ fromValue _ = Nothing++instance ToValue ByteString where toValue = VBytes+instance FromValue ByteString where+ fromValue (VBytes b) = Just b+ fromValue _ = Nothing++-- 'UTCTime''s fields are lazy. Force them since everything in a 'Db' is+-- evaluated+instance ToValue UTCTime where+ toValue t@(UTCTime d s) = d `seq` s `seq` VInstant t+instance FromValue UTCTime where+ fromValue (VInstant t) = Just t+ fromValue _ = Nothing++instance ToValue Day where toValue = VDay+instance FromValue Day where+ fromValue (VDay d) = Just d+ fromValue _ = Nothing++-- Generic enums: a constructor with no fields is stored as its name+class GEnum f where+ genumName :: f p -> Text+ genumFrom :: Text -> Maybe (f p)++instance GEnum f => GEnum (M1 D d f) where+ genumName (M1 x) = genumName x+ genumFrom t = M1 <$> genumFrom t++instance (GEnum f, GEnum g) => GEnum (f :+: g) where+ genumName (L1 x) = genumName x+ genumName (R1 y) = genumName y+ genumFrom t = L1 <$> genumFrom t <|> R1 <$> genumFrom t++instance Constructor c => GEnum (M1 C c U1) where+ genumName _ = T.pack (conName (undefined :: M1 C c U1 p))+ genumFrom t+ | t == genumName (undefined :: M1 C c U1 p) = Just (M1 U1)+ | otherwise = Nothing++instance TypeError (NotEnum name) => GEnum (M1 C ('MetaCons name fx s) (M1 S m f)) where+ genumName = error "unreachable"; genumFrom = error "unreachable"+instance TypeError (NotEnum name) => GEnum (M1 C ('MetaCons name fx s) (f :*: g)) where+ genumName = error "unreachable"; genumFrom = error "unreachable"++type NotEnum name =+ 'Text "datomlite: only enums derive ToValue/FromValue, and constructor "+ ':<>: 'Text name ':<>: 'Text " has fields."+ ':$$: 'Text "Store a record as its own Entity and point at it with a Ref."++-- Without this a 'String' field reads as many 'Char's... and fails with a+-- confusing missing instance+type NoChar =+ 'Text "datomlite: String/Char fields aren't supported; use Data.Text.Text"++instance TypeError NoChar => ToValue Char where+ toValue = error "unreachable"+instance TypeError NoChar => FromValue Char where+ fromValue = error "unreachable"++-- | How a single field is split into datoms.+data Shape+ = ShapeOne -- ^ exactly one value+ | ShapeOptional -- ^ zero or one value+ | ShapeMany -- ^ zero or more values+ deriving (Eq, Show)++-- | How a field type is stored: its 'Shape' and how to turn it into 'Value's+-- and back. Instances cover 'Maybe', 'Set' and plain scalars (including+-- 'Ref').+class Field a where+ shape :: Proxy a -> Shape+ shred :: a -> [Value]+ unshred :: [Value] -> Maybe a++-- A plain scalar. Overlappable so the instances below win for 'Maybe', 'Set'+-- and lists+instance {-# OVERLAPPABLE #-} (ToValue a, FromValue a) => Field a where+ shape _ = ShapeOne+ shred a = [toValue a]+ unshred (v:_) = fromValue v+ unshred [] = Nothing++instance (ToValue a, FromValue a) => Field (Maybe a) where+ shape _ = ShapeOptional+ shred Nothing = []+ shred (Just a) = [toValue a]+ unshred [] = Just Nothing+ unshred (v:_) = Just <$> fromValue v++instance (Ord a, ToValue a, FromValue a) => Field (Set a) where+ shape _ = ShapeMany+ shred = map toValue . Set.toList+ unshred = fmap Set.fromList . traverse fromValue++-- A many-valued field keeps no order or duplicates... so a list would promise+-- more than the store gives back. Point at 'Set' instead (or 'Text' for a+-- 'String')+instance TypeError (ListField a) => Field [a] where+ shape = error "unreachable"+ shred = error "unreachable"+ unshred = error "unreachable"++type family ListField a :: ErrorMessage where+ ListField Char = NoChar+ ListField a =+ 'Text "datomlite: a many-valued field is a set, so declare it as (Set "+ ':<>: 'ShowType a ':<>: 'Text "), not [" ':<>: 'ShowType a ':<>: 'Text "]"++-- | A record that can be stored as datoms and read back. Derive it:+--+-- @+-- \{\-\# LANGUAGE DeriveGeneric, DeriveAnyClass \#\-\}+--+-- data Employee = Employee { email :: Text, name :: Text, ... }+-- deriving (Generic, Entity)+-- @+--+-- or write an @instance Entity Employee@ to name its 'Identity' fields:+--+-- @+-- instance Entity Employee where+-- type Identity Employee = '[\"email\"]+-- @+class Entity a where+ -- | The fields that identify an entity. Each one is unique on its own: no+ -- two entities hold the same value and 'upsert' finds the entity by it. A+ -- name the record doesn't have is a compile error. Defaults to none.+ type Identity a :: [Symbol]+ type Identity a = '[]++ -- | The @Type@ in its @Type\/field@ attributes. Defaults to the type name.+ ename :: Proxy a -> Text+ default ename :: (Generic a, GName (Rep a)) => Proxy a -> Text+ ename _ = gname (Proxy @(Rep a))++ -- | Shred a record into (attribute, values, shape) triples.+ decompose :: a -> [(Attr, [Value], Shape)]+ default decompose+ :: (Generic a, GEntity (Rep a)) => a -> [(Attr, [Value], Shape)]+ decompose = gdecompose (ename (Proxy @a)) . from++ -- | Rebuild a record from an entity's values or say which field didn't+ -- decode.+ reconstruct :: EntityId -> Map.Map Attr [Value] -> Either LoadError a+ default reconstruct+ :: (Generic a, GEntity (Rep a))+ => EntityId -> Map.Map Attr [Value] -> Either LoadError a+ reconstruct e m = to <$> greconstruct (ename (Proxy @a)) e m++ -- | The attributes of the 'Identity' fields:+ -- @["Employee/email"]@.+ identityAttrs :: Proxy a -> [Attr]+ default identityAttrs+ :: (IdentityFields (Identity a) a, KnownSymbols (Identity a))+ => Proxy a -> [Attr]+ identityAttrs p = map (attrName (ename p)) (symbolVals @(Identity a))++-- Every name in an 'Identity' list is a field of the record+type family IdentityFields (names :: [Symbol]) a :: Constraint where+ IdentityFields '[] a = ()+ IdentityFields (n ': ns) a =+ (IdentityField (HasSel n (Rep a)) n a, IdentityFields ns a)++type family IdentityField (found :: Bool) (name :: Symbol) a :: Constraint where+ IdentityField 'True name a = ()+ IdentityField 'False name a = TypeError+ ('Text "datomlite: Identity " ':<>: 'ShowType a ':<>: 'Text " names "+ ':<>: 'ShowType name ':<>: 'Text " but " ':<>: 'ShowType a+ ':<>: 'Text " has no such field")++-- A type-level list of names, read back as strings+class KnownSymbols (names :: [Symbol]) where+ symbolVals :: [String]++instance KnownSymbols '[] where+ symbolVals = []++instance (KnownSymbol n, KnownSymbols ns) => KnownSymbols (n ': ns) where+ symbolVals = symbolVal (Proxy @n) : symbolVals @ns++-- Datatype name+class GName f where+ gname :: Proxy f -> Text++instance (Datatype d) => GName (M1 D d f) where+ gname _ = T.pack (datatypeName (undefined :: M1 D d f p))++-- Shredding and rebuilding over the generic representation+class GEntity f where+ gdecompose :: Text -> f p -> [(Attr, [Value], Shape)]+ greconstruct :: Text -> EntityId -> Map.Map Attr [Value] -> Either LoadError (f p)++instance (OneRecord ty f, GEntity f) => GEntity (M1 D ('MetaData ty m p nt) f) where+ gdecompose n (M1 x) = gdecompose n x+ greconstruct n e m = M1 <$> greconstruct n e m++-- Shapes 'OneRecord' rules out. Never used since the check fails to compile+-- first+instance GEntity (f :+: g) where+ gdecompose = error "unreachable"; greconstruct = error "unreachable"+instance GEntity U1 where+ gdecompose = error "unreachable"; greconstruct = error "unreachable"+instance GEntity V1 where+ gdecompose = error "unreachable"; greconstruct = error "unreachable"++-- An entity is one constructor with named fields since each name is an+-- attribute. Anything else gets a type error that says so+type family OneRecord (ty :: Symbol) (f :: Type -> Type) :: Constraint where+ OneRecord ty (M1 C c U1) = TypeError+ ('Text "datomlite: " ':<>: 'Text ty ':<>: 'Text " has no fields to store.")+ OneRecord ty (M1 C c f) = If (AllNamed f) (() :: Constraint) (TypeError+ ('Text "datomlite: " ':<>: 'Text ty ':<>: 'Text "'s fields need names, since each one is an attribute."+ ':$$: 'Text "Declare it with record syntax: data " ':<>: 'Text ty ':<>: 'Text " = "+ ':<>: 'Text ty ':<>: 'Text " { field :: ..., ... }"))+ OneRecord ty V1 = TypeError+ ('Text "datomlite: " ':<>: 'Text ty ':<>: 'Text " has no constructors to store.")+ OneRecord ty f = TypeError+ ('Text "datomlite: " ':<>: 'Text ty ':<>: 'Text " has several constructors; an entity is one record."+ ':$$: 'Text "Split it into one record per case, or store the case in an enum field.")++type family AllNamed (f :: Type -> Type) :: Bool where+ AllNamed (f :*: g) = AllNamed f && AllNamed g+ AllNamed (M1 S ('MetaSel ('Just n) su ss ds) f) = 'True+ AllNamed f = 'False++instance GEntity f => GEntity (M1 C c f) where+ gdecompose n (M1 x) = gdecompose n x+ greconstruct n e m = M1 <$> greconstruct n e m++instance (GEntity f, GEntity g) => GEntity (f :*: g) where+ gdecompose n (x :*: y) = gdecompose n x ++ gdecompose n y+ greconstruct n e m = (:*:) <$> greconstruct n e m <*> greconstruct n e m++instance (Selector s, Field a) => GEntity (M1 S s (K1 i a)) where+ gdecompose n s@(M1 (K1 x)) = [(attrName n (selName s), shred x, shape (Proxy @a))]++ greconstruct n e m = case unshred vs of+ Just x -> Right (M1 (K1 x))+ Nothing | null vs -> Left (MissingField attr e)+ | otherwise -> Left (BadValue attr vs e)+ where+ attr = attrName n (selName (undefined :: M1 S s (K1 i a) p))+ vs = Map.findWithDefault [] attr m++-- | The attribute for a field: @Type\/field@.+attrName :: Text -> String -> Attr+attrName ty fld = ty <> "/" <> T.pack fld++--------------------------------------------------------------------------------+-- Writing++-- A record's fields with every lookup ref swapped for the entity it names+fieldsIn :: Entity a => Db -> a -> Either TxError [(Attr, [Value], Shape)]+fieldsIn db = traverse resolveField . decompose+ where+ resolveField (attr, vs, sh) = (\vs' -> (attr, nub vs', sh)) <$> traverse resolveValue vs+ resolveValue (VLookup a v) = VRef <$> holderOf a v db+ resolveValue v = Right v++-- The entity a ref names, or why there isn't one+target :: Ref a -> Db -> Either TxError EntityId+target (Ref e) _ = Right e+target (LookupRef a v) db = holderOf a v db++-- The entity holding an identity value+holderOf :: Attr -> Value -> Db -> Either TxError EntityId+holderOf a v db = maybe (Left (UnknownIdentity a v)) Right (uniqueAt a v db)++-- Make entity @e@ match a record's fields: stage only the difference and+-- claim the identity values it newly holds+write :: [Attr] -> EntityId -> [(Attr, [Value], Shape)] -> TxState -> TxState+write ids e fields s = emit (retracts ++ asserts) claims s+ where+ changes = [ (attr, lookupValues e attr (txView s), new) | (attr, new, _) <- fields ]+ retracts = [ (e, attr, v, Retract) | (attr, old, new) <- changes, v <- old, v `notElem` new ]+ asserts = [ (e, attr, v, Assert) | (attr, old, new) <- changes, v <- new, v `notElem` old ]+ claims = [ (attr, v) | (_, attr, v, _) <- asserts, attr `elem` ids ]++-- | Why a commit failed. Nothing is written.+data TxError+ = -- | Several entities would hold the same 'Identity' value.+ UniqueViolation+ { uvAttr :: Attr -- ^ the identity attribute, e.g. @"Employee/email"@+ , uvValue :: Value -- ^ the value they would share+ , uvEntities :: [EntityId] -- ^ the entities holding it, oldest first+ }+ -- | A lookup ref (see 'ref') that no entity holds.+ | UnknownIdentity Attr Value+ -- | 'update' on an entity with no facts.+ | UnknownEntity EntityId+ -- | The transaction gave up through 'abort' or a failed pattern match.+ | Aborted Text+ -- | A commit on a 'since' view, which only holds part of the log.+ | SinceView+ deriving (Eq, Show)++-- | A transaction. The 'Ref' from 'insert' works right away in later steps and+-- the whole thing commits at once:+--+-- @+-- Right (empRef, db') = 'commit' db $ do+-- eng <- 'insert' (Department { code = \"ENG\", deptName = \"Engineering\" })+-- 'insert' (Employee { email = \"m\@x.io\", dept = eng, ... })+-- @+--+-- When nothing needs passing along, a list of 'Write's says the same thing+-- more plainly.+--+-- Each step sees the ones before it and 'txDb' reads that in-progress+-- database. Small 'Tx's compose into bigger ones (it's a 'Monad' and a+-- 'Monoid' when the result is).+--+-- Inside it's the 'Db' being written (every step staged under one+-- pending tx) and the identity claims to check on commit. Ids get handed out+-- as you go... so a tempid is just a real 'EntityId'.+newtype Tx a = Tx { runTx :: TxState -> Either TxError (a, TxState) }++data TxState = TxState+ { txView :: Db -- the db with this tx's writes so far staged+ , txClaims :: [(Attr, Value)] -- identity values that must end up unique+ }++instance Functor Tx where+ fmap f (Tx g) = Tx $ \s -> fmap (\(a, s') -> (f a, s')) (g s)++instance Applicative Tx where+ pure x = Tx $ \s -> Right (x, s)+ (<*>) = ap++instance Monad Tx where+ Tx g >>= k = Tx $ \s -> g s >>= \(a, s') -> runTx (k a) s'++-- | A failed pattern match aborts the whole transaction.+instance MonadFail Tx where+ fail = abort . T.pack++instance Semigroup a => Semigroup (Tx a) where+ x <> y = (<>) <$> x <*> y++instance Monoid a => Monoid (Tx a) where+ mempty = pure mempty++-- Stage datoms and record unique claims+emit :: TxData -> [(Attr, Value)] -> TxState -> TxState+emit ops claims s = TxState (stage ops (txView s)) (claims ++ txClaims s)++-- | Insert a record as a new entity. The 'Ref' it returns works right away.+-- An 'Identity' value another entity already holds fails the commit with+-- 'UniqueViolation' (use 'upsert' to update that one instead).+insert :: forall a. Entity a => a -> Tx (Ref a)+insert a = Tx $ \s -> do+ fields <- fieldsIn (txView s) a+ let (e, view) = freshEntity (txView s)+ pure (Ref e, write (identityAttrs (Proxy @a)) e fields s { txView = view })++-- | 'insert' without the 'Ref'. For a do-block of writes.+insert_ :: Entity a => a -> Tx ()+insert_ = void . insert++-- | Insert, or update the entity already holding one of the record's+-- 'Identity' values. Either way you get the 'Ref' back:+--+-- @+-- commit db $ upsert (Department \"ENG\" \"Platform Engineering\")+-- @+--+-- Only the difference is written. A record with no 'Identity' is always+-- inserted. Identity values held by two different entities fail with+-- 'UniqueViolation'.+upsert :: forall a. Entity a => a -> Tx (Ref a)+upsert a = Tx $ \s -> do+ fields <- fieldsIn (txView s) a+ let ids = identityAttrs (Proxy @a)+ owners = [ e | (attr, vs, _) <- fields, attr `elem` ids+ , v <- vs, e <- entitiesWith attr v (txView s) ]+ case owners of+ [] -> runTx (insert a) s+ (e:_) -> pure (Ref e, write ids e fields s)++-- | 'upsert' without the 'Ref'. For a do-block of writes.+upsert_ :: Entity a => a -> Tx ()+upsert_ = void . upsert++-- | Change an entity with a function on its record:+--+-- @+-- commit_ db $ update maxRef (\\e -> e { name = \"Maximilian\" })+-- @+--+-- Only the difference is written so a one-valued field gets replaced (not+-- doubled up). Changed 'Identity' fields are checked for uniqueness. Fails with+-- 'UnknownEntity' if the entity has no facts (or 'UnknownIdentity' for a+-- 'ref' nothing holds).+update :: forall a. Entity a => Ref a -> (a -> a) -> Tx ()+update r f = Tx $ \s -> do+ e <- target r (txView s)+ old <- maybe (Left (UnknownEntity e)) Right (loadRecord e (txView s))+ fields <- fieldsIn (txView s) (f old)+ pure ((), write (identityAttrs (Proxy @a)) e fields s)++-- | Set one field by name. Handy with 'update':+--+-- @+-- commit_ db $ update maxRef (setField \@\"name\" \"Maximilian\")+-- @+--+-- Record-update syntax works too but gets ambiguous when two records share a+-- field name. Here the record type comes from the 'Ref'. Field and type are+-- checked like @e.name@.+setField+ :: forall name a t+ . (HasNamedField name a, HasField name a t, Generic a, GSetField name t (Rep a))+ => t -> a -> a+setField v = to . gsetField @name v . from++-- Replace the field called @name@ in a generic representation+class GSetField (name :: Symbol) t (f :: Type -> Type) where+ gsetField :: t -> f p -> f p++instance GSetField name t f => GSetField name t (M1 D m f) where+ gsetField v (M1 x) = M1 (gsetField @name v x)++instance GSetField name t f => GSetField name t (M1 C m f) where+ gsetField v (M1 x) = M1 (gsetField @name v x)++instance t ~ u => GSetField name t (M1 S ('MetaSel ('Just name) su ss ds) (K1 i u)) where+ gsetField v _ = M1 (K1 v)++instance GSetProduct (HasSel name f) name t f g => GSetField name t (f :*: g) where+ gsetField = gsetProduct @(HasSel name f) @name++-- | @a@ has a field called @name@. If not you get a readable type error.+type family HasNamedField (name :: Symbol) a :: Constraint where+ HasNamedField name a = FieldFound (HasSel name (Rep a)) name a++type family FieldFound (found :: Bool) (name :: Symbol) a :: Constraint where+ FieldFound 'True name a = ()+ FieldFound 'False name a = TypeError+ ('Text "datomlite: " ':<>: 'ShowType a ':<>: 'Text " has no field " ':<>: 'ShowType name)++-- Whether a generic representation (or which side of a product) holds the field+type family HasSel (name :: Symbol) (f :: Type -> Type) :: Bool where+ HasSel name (M1 S ('MetaSel ('Just name) su ss ds) f) = 'True+ HasSel name (M1 D m f) = HasSel name f+ HasSel name (M1 C m f) = HasSel name f+ HasSel name (f :*: g) = HasSel name f || HasSel name g+ HasSel name f = 'False++class GSetProduct (left :: Bool) (name :: Symbol) t f g where+ gsetProduct :: t -> (f :*: g) p -> (f :*: g) p++instance GSetField name t f => GSetProduct 'True name t f g where+ gsetProduct v (x :*: y) = gsetField @name v x :*: y++instance GSetField name t g => GSetProduct 'False name t f g where+ gsetProduct v (x :*: y) = x :*: gsetField @name v y++-- | Retract every fact an entity holds. It drops out of reads and queries,+-- and 'history' keeps what it was:+--+-- @+-- commit_ db $ retract empRef+-- commit_ db $ retract (ref \@Employee \"m\@x.io\")+-- @+--+-- An entity with no facts has nothing to retract. A 'ref' nothing holds fails+-- with 'UnknownIdentity'. Only facts of the ref's type go, like 'load'.+retract :: forall a. Entity a => Ref a -> Tx ()+retract r = Tx $ \s -> do+ e <- target r (txView s)+ let own = ownAttrs (ename (Proxy @a)) e (txView s)+ facts = [ (e, at, v, Retract) | (at, vs) <- Map.toList own, v <- vs ]+ pure ((), emit facts [] s)++-- | The database as this transaction sees it so far. Query it to decide what+-- to write next:+--+-- @+-- commit db $ do+-- Just acct <- load acctRef \<$\> txDb+-- when (acct.balance < amount) $ abort \"insufficient funds\"+-- update acctRef (\\a -> a { balance = a.balance - amount })+-- @+txDb :: Tx Db+txDb = Tx $ \s -> Right (txView s, s)++-- | Give up: the commit fails with 'Aborted' and nothing is written.+abort :: Text -> Tx a+abort msg = Tx $ \_ -> Left (Aborted msg)++-- | One write, for committing a list of them:+--+-- @+-- commit_ db+-- [ Upsert (Department \"ENG\" \"Engineering\")+-- , Upsert (Employee \"m\@x.io\" \"Max\" (ref \@Department \"ENG\") ...)+-- , Delete (ref \@Employee \"old\@x.io\")+-- ]+-- @+--+-- They run in order as one transaction, each seeing the ones before it.+data Write where+ -- | 'insert' the record as a new entity.+ Insert :: Entity a => a -> Write+ -- | 'upsert' it: update the entity holding one of its identities, or insert.+ Upsert :: Entity a => a -> Write+ -- | 'update' an entity with a function on its record.+ Update :: Entity a => Ref a -> (a -> a) -> Write+ -- | 'retract' every fact the entity holds ('history' keeps them).+ Delete :: Entity a => Ref a -> Write++-- | What 'commit' takes: a 'Tx' do-block, or a list of 'Write's.+class Writes w where+ -- | What committing it hands back: the 'Tx' result, or @()@ for a list.+ type Result w+ toTx :: w -> Tx (Result w)++instance Writes (Tx a) where+ type Result (Tx a) = a+ toTx = id++-- For any list so an empty one (@commit db []@) needs no annotation+instance w ~ Write => Writes [w] where+ type Result [w] = ()+ toTx = traverse_ step+ where+ step (Insert a) = insert_ a+ step (Upsert a) = upsert_ a+ step (Update r f) = update r f+ step (Delete r) = retract r++-- | Commit a list of 'Write's or a 'Tx', all or nothing, and check 'Identity'+-- uniqueness. Fails with 'UniqueViolation' if two entities would hold the+-- same identity value (whether the other was already there or made in this+-- transaction). Nothing is written on failure.+--+-- The 'Db' comes first so the writes can go last: @commit db [...]@ or+-- @commit db $ do ...@.+--+-- Strict: a value that throws does so here... so a 'Right' never holds a 'Db'+-- that blows up later.+commit :: Writes w => Db -> w -> Either TxError (Result w, Db)+commit = commitWith id++-- | 'commit' with a wall-clock time on the transaction, for 'asOfTime' and+-- 'trTime'. It's logged as a @db\/txInstant@ datom so it survives a save and+-- restore. A time before the last stamp is moved up to it.+--+-- 'transact' stamps with the clock. This is for tests or a clock of your own.+commitAt :: Writes w => UTCTime -> Db -> w -> Either TxError (Result w, Db)+commitAt t = commitWith (stampTime t)++commitWith :: Writes w => (Db -> Db) -> Db -> w -> Either TxError (Result w, Db)+commitWith finish db w = do+ when (partialView db) (Left SinceView)+ (a, s) <- runTx (toTx w) (TxState db [])+ let db' = closeTx (finish (txView s))+ checkUnique (txClaims s) db'+ db' `seq` pure (a, db')++-- | 'commit' but keep only the new database.+commit_ :: Writes w => Db -> w -> Either TxError Db+commit_ db = fmap snd . commit db++-- Fail if a claimed identity value ends up on more than one entity. We check+-- the result and not each step... so a transaction can move one between+-- entities or retract and reuse it+checkUnique :: [(Attr, Value)] -> Db -> Either TxError ()+checkUnique claims db = mapM_ unique claims+ where+ unique (a, v) = case entitiesWith a v db of+ es@(_:_:_) -> Left (UniqueViolation a v es)+ _ -> Right ()++-- | 'commit' on a connection: the same writes, the same result and new 'Db'+-- back, and the connection now holds that 'Db'. A 'TxError' or an exception+-- leaves the connection as it was.+--+-- @+-- conn <- connect emptyDb+-- Right (empRef, db) <- transact conn $ do+-- eng <- insert (Department \"ENG\" \"Engineering\")+-- insert (Employee \"m\@x.io\" \"Max\" eng 120000 mempty Nothing)+-- @+--+-- The 'Db' is the one this commit made, even if another thread has committed+-- since. 'snapshot' reads whatever the connection holds now.+--+-- The transaction is stamped with the current time (see 'commitAt').+transact :: Writes w => Conn -> w -> IO (Either TxError (Result w, Db))+transact conn w = do+ now <- getCurrentTime+ atomicUpdate conn $ \db -> case commitAt now db w of+ Left err -> (db, Left err)+ Right (a, db') -> (db', Right (a, db'))++--------------------------------------------------------------------------------+-- Reading records++-- | A record read from the database along with its 'Ref'. Every read hands+-- one back ('load', 'every', 'find', 'match', 'follow'). Read its fields with+-- @p.name@, its ref with 'refOf' and the plain record with 'recordOf'.+data Stored a = Stored (Ref a) a+ deriving (Eq, Show)++-- | The 'Ref' of a stored record. Always the entity's id, never a lookup ref,+-- so it's what to compare with a ref field: @guard (e.dept == refOf d)@.+refOf :: Stored a -> Ref a+refOf (Stored r _) = r++-- | The plain record.+recordOf :: Stored a -> a+recordOf (Stored _ a) = a++-- | @p.field@ is the record's own field.+instance HasField name a t => HasField (name :: Symbol) (Stored a) t where+ getField (Stored _ a) = getField @name a++-- | Read a record through its 'Ref' (a lookup ref works too). Its own ref+-- fields stay 'Ref's:+--+-- @+-- load empRef db -- :: Maybe (Stored Employee)+-- @+--+-- 'Nothing' means no facts of this type. Either it was retracted or never+-- written (a record of only 'Nothing' and empty fields writes no datoms). An+-- entity that is there but doesn't decode throws a 'LoadError'... except in a+-- 'since' view which just skips it.+load :: forall a. Entity a => Ref a -> Db -> Maybe (Stored a)+load r db = do+ e <- resolve r db+ Stored (Ref e) <$> loadRecord e db++-- | Every entity of a type (in creation order). Throws like 'load' on one+-- that doesn't decode.+--+-- @+-- [ p.name | p <- every \@Person db ]+-- @+every :: forall a. Entity a => Db -> [Stored a]+every db =+ [ Stored (Ref e) a | e <- entitiesInNamespace (ename (Proxy @a)) db+ , Just a <- [loadRecord e db] ]++-- | The entity holding an 'Identity' value:+--+-- @+-- find \@Person \"m\@x.io\" db -- :: Maybe (Stored Person)+-- @+--+-- Checked like 'ref': the value has the field's type, and a record with+-- several identities says which with 'findBy'.+find+ :: forall a name t. (name ~ SoleIdentity a (Identity a), ByIdentity a name t)+ => FieldValue t -> Db -> Maybe (Stored a)+find = findBy @a @name++-- | 'find' by a named 'Identity' field: @findBy \@User \@\"handle\" \"max\" db@.+findBy :: forall a name t. ByIdentity a name t => FieldValue t -> Db -> Maybe (Stored a)+findBy v = load (refBy @a @name v)++-- | A lookup ref: the entity holding an 'Identity' value. Put one in a record+-- and commit finds the entity, even one written earlier in the same commit:+--+-- @+-- commit_ db+-- [ Upsert (Department \"ENG\" \"Engineering\")+-- , Upsert (Employee \"m\@x.io\" \"Max\" (ref \@Department \"ENG\") ...)+-- ]+-- @+--+-- 'load', 'follow', 'update' and 'retract' take one too. If no entity holds+-- the value, a write fails with 'UnknownIdentity' and a read finds nothing.+-- The value has the field's type ('Maybe' and 'Set' fields take the value+-- inside). A record with several identities says which with 'refBy'.+ref+ :: forall a name t. (name ~ SoleIdentity a (Identity a), ByIdentity a name t)+ => FieldValue t -> Ref a+ref = refBy @a @name++-- | 'ref' by a named 'Identity' field: @refBy \@User \@\"handle\" \"max\"@.+refBy :: forall a name t. ByIdentity a name t => FieldValue t -> Ref a+refBy v = LookupRef (attrName (ename (Proxy @a)) (symbolVal (Proxy @name))) (toValue v)++-- What 'ref', 'find' and their @By@ versions need: @name@ is one of @a@'s+-- identities and @t@ its field's type+type ByIdentity a name t =+ ( Entity a, IdentityNamed name a (Identity a), KnownSymbol name+ , HasField name a t, ToValue (FieldValue t) )++-- | What a field takes as a value to look up or match: the value inside a+-- 'Maybe' or 'Set'.+type family FieldValue t where+ FieldValue (Maybe a) = a+ FieldValue (Set a) = a+ FieldValue t = t++-- The one 'Identity' of a record+type family SoleIdentity a (ids :: [Symbol]) :: Symbol where+ SoleIdentity a '[n] = n+ SoleIdentity a '[] = TypeError+ ('Text "datomlite: " ':<>: 'ShowType a ':<>: 'Text " has no Identity to look up by"+ ':$$: 'Text "Name one in its Entity instance, or use matchBy")+ SoleIdentity a ids = TypeError+ ('Text "datomlite: " ':<>: 'ShowType a ':<>: 'Text " has several identities, "+ ':<>: 'ShowType ids+ ':$$: 'Text "Say which one: findBy @" ':<>: 'ShowType a ':<>: 'Text " @\"field\" (or refBy)")++type family IdentityNamed (name :: Symbol) a (ids :: [Symbol]) :: Constraint where+ IdentityNamed name a (name ': ids) = ()+ IdentityNamed name a (n ': ids) = IdentityNamed name a ids+ IdentityNamed name a '[] = TypeError+ ('Text "datomlite: " ':<>: 'ShowType name ':<>: 'Text " isn't an Identity of "+ ':<>: 'ShowType a+ ':$$: 'Text "Match on it with matchBy, or add it to Identity " ':<>: 'ShowType a)++-- An entity's record of type @a@, if it has facts of that type+loadRecord :: forall a. Entity a => EntityId -> Db -> Maybe a+loadRecord e db+ | Map.null own = Nothing+ | otherwise = case reconstruct e own of+ Right a -> Just a+ Left err+ | partialView db -> Nothing+ | otherwise -> throw err+ where own = ownAttrs (ename (Proxy @a)) e db++-- An entity's values for the attributes in one type's namespace+ownAttrs :: Text -> EntityId -> Db -> Map Attr [Value]+ownAttrs ty e db = Map.filterWithKey (\k _ -> (ty <> "/") `T.isPrefixOf` k) (entityAttrs e db)++-- | A stored entity that doesn't decode as the record asked for. Thrown by+-- reads, since it means the data and the record type have drifted apart.+data LoadError+ = MissingField Attr EntityId+ | BadValue Attr [Value] EntityId+ deriving (Eq, Show)++instance Exception LoadError where+ displayException (MissingField a (EntityId e)) =+ "datomlite: entity " <> show e <> " has no value for required field "+ <> T.unpack a <> " (added after it was written? make it a Maybe)"+ displayException (BadValue a vs (EntityId e)) =+ "datomlite: entity " <> show e <> " holds " <> show vs <> " for "+ <> T.unpack a <> ", which doesn't decode as the field's type"++--------------------------------------------------------------------------------+-- Queries++-- Queries are a list monad over a fixed 'Db'. 'match' scans, 'guard'+-- filters, and 'follow' and 'matchBy' look the entity up directly.++-- | Each bind ranges over candidates and 'Control.Monad.guard' prunes them.+-- A failed pattern match (@Just n <- pure e.nick@) drops the candidate too.+newtype Query a = Query { runQ :: Db -> [a] }++instance Functor Query where+ fmap f (Query g) = Query (map f . g)++instance Applicative Query where+ pure x = Query (const [x])+ (<*>) = ap++instance Monad Query where+ Query g >>= k = Query (\db -> concat [ runQ (k x) db | x <- g db ])++instance MonadFail Query where+ fail _ = empty++instance Alternative Query where+ empty = Query (const [])+ Query f <|> Query g = Query (\db -> f db ++ g db)++instance MonadPlus Query++-- | Run a query against any 'Db'... @query (asOf t db)@ asks the past.+query :: Db -> Query a -> [a]+query db (Query f) = f db++-- | Range over every entity of a type ('every' inside a query).+match :: forall a. Entity a => Query (Stored a)+match = Query (every @a)++-- | Like 'match' but only the entities whose field holds a value. Goes through+-- the index:+--+-- @+-- e <- matchBy \@Employee \@\"email\" \"m\@x.io\" -- an identity+-- e <- matchBy \@Employee \@\"dept\" (refOf d) -- a reverse ref+-- e <- matchBy \@Employee \@\"skills\" haskell -- one of many+-- e <- matchBy \@Employee \@\"dept\" (ref \@Department \"ENG\")+-- @+--+-- The field and value type are checked against the record. For a 'Maybe' or+-- 'Set' field just pass the value inside.+matchBy+ :: forall a name t+ . ( Entity a, HasNamedField name a, KnownSymbol name, HasField name a t+ , ToValue (FieldValue t) )+ => FieldValue t -> Query (Stored a)+matchBy v = Query $ \db ->+ [ s | w <- resolved db (toValue v)+ , e <- entitiesWith attr w db+ , Just s <- [load (Ref e) db] ]+ where+ attr = attrName (ename (Proxy @a)) (symbolVal (Proxy @name))+ -- a lookup ref matches the entity it names, or nothing+ resolved db (VLookup a w) = maybe [] (pure . VRef) (uniqueAt a w db)+ resolved _ w = [w]++-- | Walk a 'Ref' to its entity (or to nothing if it was retracted). The cheap+-- join: @d <- follow e.dept@. A lookup ref works too:+-- @d <- follow (ref \@Department \"ENG\")@.+follow :: Entity a => Ref a -> Query (Stored a)+follow r = Query $ \db -> maybe [] pure (load r db)++-- | Range over a 'Data.Set.Set' or 'Maybe' field: @s <- oneOf e.skills@.+oneOf :: Foldable f => f a -> Query a+oneOf xs = Query (const (toList xs))++-- | Everything reachable from @x@ in one or more steps, each entity once. The+-- fixed point of a recursive rule... so it's fine on cycles where plain+-- recursion would loop forever:+--+-- @+-- next p = do+-- r <- matchBy \@Road \@\"from\" (refOf p)+-- follow r.to+--+-- p <- closure next paris -- paris too if a road loops back+-- @+--+-- Breadth first, nearest first. Lazy so 'exists' stops at the first hit.+closure :: (Stored a -> Query (Stored a)) -> Stored a -> Query (Stored a)+closure step x = Query $ \db ->+ let next v = Seq.fromList (runQ (step v) db)+ go _ Empty = []+ go seen (v :<| queue)+ | refOf v `Set.member` seen = go seen queue+ | otherwise = v : go (Set.insert (refOf v) seen) (queue >< next v)+ in go Set.empty (next x)++-- | Keep the row if the subquery has a result (a semi-join). It runs against+-- the same 'Db' as the query around it:+--+-- @+-- o <- match \@Order+-- exists (matchBy \@Employee \@\"email\" o.buyer)+-- @+exists :: Query a -> Query ()+exists (Query f) = Query $ \db -> [ () | not (null (f db)) ]++-- | Keep the row if the subquery has no result (an anti-join):+--+-- @+-- e <- match \@Employee+-- none (matchBy \@Order \@\"buyer\" e.email)+-- @+none :: Query a -> Query ()+none (Query f) = Query $ \db -> [ () | null (f db) ]++--------------------------------------------------------------------------------+-- Window functions++-- | A value for each row of a sorted group. Rows are paired with their sort+-- key @o@.+--+-- An 'Applicative' so several run over the same groups in one go:+--+-- @+-- (,) \<$\> rank \<*\> whole (sum . map salary)+-- @+newtype Window o r b = Window ([(o, r)] -> [b])++instance Functor (Window o r) where+ fmap f (Window g) = Window (map f . g)++instance Applicative (Window o r) where+ pure x = Window (map (const x))+ Window f <*> Window g = Window (\rs -> zipWith ($) (f rs) (g rs))++-- | Group rows by @part@, sort each group by @ord@ and pair every row with+-- what @w@ gives it. SQL's @w OVER (PARTITION BY part ORDER BY ord)@:+--+-- @+-- window dept (Down . salary) rank rows+-- @+--+-- Groups come out in @part@ order and ties keep the order they came in.+-- @const ()@ makes one group of everything.+window :: (Ord p, Ord o) => (r -> p) -> (r -> o) -> Window o r b -> [r] -> [(r, b)]+window part ord (Window w) rows = concat [ zip (map snd g) (w g) | g <- Map.elems groups ]+ where+ -- fromListWith conses, so reverse to put each group back in input order+ groups = Map.map (sortBy (comparing fst) . reverse)+ (Map.fromListWith (++) [ (part r, [(ord r, r)]) | r <- rows ])++-- | 1, 2, 3... ties get different numbers.+rowNumber :: Window o r Int+rowNumber = Window (zipWith const [1 ..])++-- | Ties share a rank and the next one skips: 1, 1, 3.+rank :: Eq o => Window o r Int+rank = Window $ \g ->+ let sizes = map length (group (map fst g))+ in concat (zipWith replicate sizes (scanl (+) 1 sizes))++-- | Ties share a rank and the next one doesn't skip: 1, 1, 2.+denseRank :: Eq o => Window o r Int+denseRank = Window $ \g ->+ concat (zipWith replicate (map length (group (map fst g))) [1 ..])++-- | @f@ of the row @n@ before this one in its group. 'Nothing' near the start.+lag :: Int -> (r -> a) -> Window o r (Maybe a)+lag n f = Window $ \g -> take (length g) (replicate n Nothing ++ map (Just . f . snd) g)++-- | @f@ of the row @n@ after this one in its group. 'Nothing' near the end.+lead :: Int -> (r -> a) -> Window o r (Maybe a)+lead n f = Window $ \g -> take (length g) (drop n (map (Just . f . snd) g) ++ repeat Nothing)++-- | @f@ of the whole group, on every row of it: @whole (sum . map salary)@.+whole :: ([r] -> a) -> Window o r a+whole f = Window $ \g -> let x = f (map snd g) in map (const x) g++-- | @f@ of the group up to and including this row: @running (sum . map salary)@.+running :: ([r] -> a) -> Window o r a+running f = Window $ \g -> map f (drop 1 (inits (map snd g)))++--------------------------------------------------------------------------------+-- Reacting to commits++-- A subscriber is a thread that blocks until the basis moves, then catches up+-- from the log... Writers never wait on subscribers and a slow callback only+-- holds up its own thread.++-- | Call @f@ with every commit from now on, in tx order.+--+-- One 'TxReport' per commit even when several land at once. @f@ runs on its+-- own thread so it can read or commit. If it throws the error goes to stderr+-- and the listener keeps going.+--+-- Returns the action that stops it. Safe to call twice or from inside @f@.+--+-- @+-- stop <- listen conn $ \\r -> putStrLn (show (length (trDatoms r)) <> " datoms")+-- @+listen :: Conn -> (TxReport -> IO ()) -> IO (IO ())+listen conn f = subscribe conn (const []) (\seen db -> map f (txsAfter seen db))++-- | A live query. Calls @f@ with @q@'s result now... then again whenever it+-- changes.+--+-- @q@ runs on the latest 'Db' so if commits outpace @f@ it just skips to the+-- current answer. Errors are handled as in 'listen'.+--+-- @+-- stop <- watch conn (length . every \@Employee) $ \\n -> putStrLn (show n <> " employees")+-- @+watch :: Eq a => Conn -> (Db -> a) -> (a -> IO ()) -> IO (IO ())+watch conn q f = do+ lastSeen <- newIORef Nothing -- only the watch's own thread touches it+ let notify db = do+ r <- evaluate (q db)+ prev <- readIORef lastSeen+ when (prev /= Just r) $ writeIORef lastSeen (Just r) >> f r+ subscribe conn (\db -> [notify db]) (\_ db -> [notify db])++-- Fork a thread that runs @start@ on the current 'Db', then @step@ on each+-- newer one... until stopped. The start is read before returning, so no later+-- commit is missed+subscribe :: Conn -> (Db -> [IO ()]) -> (TxId -> Db -> [IO ()]) -> IO (IO ())+subscribe conn start step = do+ stop <- newTVarIO False+ db0 <- snapshot conn+ let deliver = mapM_ $ \act -> do+ stopped <- readTVarIO stop+ unless stopped (guarded act)+ loop seen = do+ next <- atomically $ (Nothing <$ (readTVar stop >>= check))+ `orElse` (Just <$> awaitAfter conn seen)+ forM_ next $ \db -> deliver (step seen db) >> loop (basisT db)+ _ <- forkIO (deliver (start db0) >> loop (basisT db0))+ pure (atomically (writeTVar stop True))++-- Report and swallow a callback's exception. Async exceptions still end the+-- thread. One write... so it can't interleave with other output on stderr+guarded :: IO () -> IO ()+guarded act = act `catch` \e ->+ if isAsync e then throwIO e+ else BS.hPut stderr . T.encodeUtf8 . T.pack $+ "datomlite: subscriber threw: " <> displayException e <> "\n"+ where+ isAsync :: SomeException -> Bool+ isAsync e = isJust (fromException e :: Maybe SomeAsyncException)
+ LICENSE view
@@ -0,0 +1,201 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work+ (an example is provided in the Appendix below).++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONS++ APPENDIX: How to apply the Apache License to your work.++ To apply the Apache License to your work, attach the following+ boilerplate notice, with the fields enclosed by brackets "[]"+ replaced with your own identifying information. (Don't include+ the brackets!) The text should be enclosed in the appropriate+ comment syntax for the file format. We also recommend that a+ file or class name and description of purpose be included on the+ same "printed page" as the copyright notice for easier+ identification within third-party archives.++ Copyright [yyyy] [name of copyright owner]++ 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.
+ README.md view
@@ -0,0 +1,1265 @@+<div align="right">+ <sub><em>part of <a href="https://github.com/mattlianje/cabinet6"><img src="https://raw.githubusercontent.com/mattlianje/cabinet6/master/pix/d4.png" width="20" align="top" hspace="4">c6</a></em></sub>+</div>++# <img src="https://raw.githubusercontent.com/mattlianje/d4/refs/heads/master/pix/datomlite.png" width="60"> datomlite++**Lightweight, immutable database**++**datomlite** is zero-dep "DB-as-a-value" for storing and retrieving records in your Haskell (GHC 9.2+) apps. It's a single file: you can drop [Datomlite.hs](https://github.com/mattlianje/datomlite/blob/master/datomlite-hs/Datomlite.hs) into your project like a header file.++<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-repl-hs-2.png" width="650">+</p>++## Features+- Pure Haskell, zero-deps+- The `Db` is a plain immutable value+- Records are "the schema"+- Append-only log+ - Every past state stays queryable+- Queries are plain do-blocks, compile-time checked+ - Joins, refs, indexed lookups, negation, and recursive rules as recursive functions+- Easy time travel & speculative transactions+- IO only at the edge++## Installation+[](https://hackage.haskell.org/package/datomlite)+```haskell+build-depends: datomlite+```+Or try it in a REPL:+```bash+cabal repl --build-depends datomlite+```++<details>+<summary>REPL extensions</summary>++```haskell+:set -XOverloadedStrings+:set -XOverloadedRecordDot+:set -XDuplicateRecordFields+:set -XDeriveGeneric+:set -XDeriveAnyClass+:set -XDataKinds+:set -XTypeApplications+:set -XTypeFamilies+```++</details>++All you need is one import:+```haskell+import Datomlite+```++## Contents+- [Quick start](#quick-start)+- [Cheatsheet](#cheatsheet)+- [How it works](#how-it-works)+- [FAQ](#faq)+- [Example schema](#example-schema)+- [Model your data](#model-your-data)+ - [Mark unique fields with `Identity`](#mark-unique-fields-with-identity)+ - [Look up entities by identity](#look-up-entities-by-identity)+ - [Link entities with refs](#link-entities-with-refs)+ - [Leave fields out with `Maybe`](#leave-fields-out-with-maybe)+ - [Store enums, newtypes and other values](#store-enums-newtypes-and-other-values)+- [Write data](#write-data)+ - [Add data](#add-data)+ - [Update data](#update-data)+ - [Remove data](#remove-data)+ - [Chain dependent steps in a `Tx` block](#chain-dependent-steps-in-a-tx-block)+- [Read data](#read-data)+ - [Get one entity](#get-one-entity)+ - [List, filter and count entities](#list-filter-and-count-entities)+ - [Run queries](#run-queries)+ - [Join in a do-block](#join-in-a-do-block)+ - [Look up rows through the index](#look-up-rows-through-the-index)+ - [Read fields with their real types](#read-fields-with-their-real-types)+ - [Follow refs backwards](#follow-refs-backwards)+ - [Aggregate rows](#aggregate-rows)+ - [Sort and page results](#sort-and-page-results)+ - [Exclude matches with `none`](#exclude-matches-with-none)+ - [Check that a match exists](#check-that-a-match-exists)+ - [Rank and total with window functions](#rank-and-total-with-window-functions)+ - [Reuse logic with rules](#reuse-logic-with-rules)+ - [Write recursive rules](#write-recursive-rules)+ - [Walk graphs with cycles (`closure`)](#walk-graphs-with-cycles-closure)+- [Travel back in time](#travel-back-in-time)+ - [See every change to an entity](#see-every-change-to-an-entity)+ - [Diff two dbs](#diff-two-dbs)+- [Share a changing db with `Conn`](#share-a-changing-db-with-conn)+ - [React to every commit](#react-to-every-commit)+ - [Keep a query result up to date](#keep-a-query-result-up-to-date)+ - [Save and restore a db](#save-and-restore-a-db)+ - [Read and write from many threads](#read-and-write-from-many-threads)+- [Build / Contribute](#build--contribute)++## Quick start++<details>+<summary>Pragmas and imports</summary>++```haskell+{-# LANGUAGE DeriveGeneric #-}+{-# LANGUAGE DeriveAnyClass #-}+{-# LANGUAGE DuplicateRecordFields #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE OverloadedRecordDot #-}+{-# LANGUAGE DataKinds #-}+{-# LANGUAGE TypeApplications #-}+{-# LANGUAGE TypeFamilies #-}+import Control.Monad (guard)+import Data.Text (Text)+import GHC.Generics (Generic)+import Datomlite+```++</details>++```haskell+import Datomlite++-- Your records are the schema. `Identity` names the unique fields+data Person = Person { email :: Text, name :: Text }+ deriving (Show, Generic)++instance Entity Person where+ type Identity Person = '["email"]++-- Start from `emptyDb`. Commit a list of writes and get a new db back+Right db = commit_ emptyDb+ [ Insert (Person "m@x.io" "Matt")+ , Insert (Person "a@x.io" "Alice")+ ]++-- Your db feels like a collection+[ p.name | p <- every @Person db ] -- ["Matt","Alice"]+length (every @Person db) -- 2+(.name) <$> find @Person "a@x.io" db -- Just "Alice", by identity++-- Upsert by identity+Right db' = commit_ db [Upsert (Person "m@x.io" "Matthieu")]++-- Queries are plain do-blocks+query db' $ do+ p <- match @Person+ guard (p.email == "m@x.io")+ pure p.name+-- ["Matthieu"]++Right db'' = commit_ db' [Delete (ref @Person "m@x.io")]+```++## Cheatsheet+```+every @A db / find @A v db rows of A, like a collection+query db $ do ... joins, lookups, negation, rules+commit_ db [Insert r, ...] writes, each hands back a new db+commit db $ do ... a Tx block, for steps that need each other+asOf / history / datoms past states+connect db one shared db: transact, listen, watch+history / fromHistory save and restore+```++## How it works+Under the hood, **datomlite** is an append-only log of (entity, attribute, value)+datoms with a couple of in-memory indices on top. GHC.Generics splits your+records into datoms on write and rebuilds them on read, so you only ever see+your own types.++The indices maintained are EAVT and AVET.+That's why `matchBy` is fast and `match` + `guard` is a scan: `guard` only+filters rows after they're produced.++Say we add two pugilists, Jet Li and Masvidal:++```haskell+data Fighter = Fighter+ { fName :: Text+ , lName :: Text+ , nickname :: Maybe Text+ } deriving (Show, Generic)++instance Entity Fighter where+ type Identity Fighter = '["lName"]++Right db = commit_ emptyDb+ [ Insert (Fighter "Jorge" "Masvidal" (Just "Street Judas"))+ , Insert (Fighter "Jet" "Li" Nothing)+ ]+```++<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-masvi1.svg" width="550">+</p>++Unsurprisingly, we want to retract Masvidal:+```haskell+Right db' = commit_ db [Delete (ref @Fighter "Masvidal")]+map recordOf (every @Fighter db')+-- [Fighter {fName = "Jet", lName = "Li", nickname = Nothing}]+```+Masvidal is gone from the live state, but not from the log. `history db'` still+has all 8 datoms (5 asserts, 3 retracts), while `datoms db'` only has Jet Li's 2.++<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-masvi2.svg" width="550">+</p>++## FAQ++**Is the Db really a value?**<br>+Yes. It's an ordinary immutable Haskell value and `commit` is a pure function.+A snapshot is just the value you're already holding.++**Does it support all of Datalog?**<br>+No, there's no Datalog engine per-se. A query is a do-block in a list-like monad, so+joins are nested loops and recursion is plain Haskell recursion. `closure`+handles graphs with cycles.++**Differences from Datomic / Datascript?**<br>+- Records are "the schema". No `:db/ident`, no attribute registration, no+ separate cardinality or uniqueness facts.+- Queries are typed Haskell, not vectors of triples.+- It's a single process. No peer, no transactor, no client/server.++**Differences from acid-state?**<br>+At at glance, **datomlite** might seem similar to [acid-state](https://github.com/acid-state/acid-state) but its goals are very different. Datomlite has a:+- **pure core**: where `commit :: Db -> w -> Either TxError (Result w, Db)` needs no handle or monad+- **history**: of past EAV triples with functions like `asOf`, `asOfTime`, `since`, `history` are first class primitives+- **ergonomics** (subjective): but we opt to use Generics instead of Template Haskell and do-block joins+- **reactivity**: `listen`, `watch` and `awaitAfter` in plain STM.++On the other hand, unlike acid-state, **datomlite** isn't really built from the ground up to+persist things... although you can easily flush and store your triples however they so wish.++**Transaction guarantees?**<br>+- **Atomicity.** All the writes in a commit land together, or none do.+- **Purity.** `commit` returns a new db and leaves the old one alone, so there's+ nothing to lock.+- **Linearizable commits.** Writers to a Conn take turns, and each commit sees+ the one before it. A transaction that throws leaves the Conn as it was.+- **Snapshot reads.** A Db never changes. `transact` gives you back the one your+ commit made, and `snapshot` the one the Conn holds right now.++**What if I change a record?**<br>+Old datoms stay as they were and `load` reads them into the new type. If you add,+rename or retype a field, older entities won't fit and you'll get `MissingField`+or `BadValue`. There's no mechanism for migrating records on disk after you changed some field+(by design), and if you need migrations you've likely outgrown a cheap DB-as-a-value.++**What can be an entity?**<br>+A record with one constructor and named fields (each field name becomes an+attribute). Anything else is a type error that tells you what to change.++**Inspiration?**<br>+Although **datomlite** borrows ideas from [Datomic](https://www.datomic.com/),+[Datascript](https://github.com/tonsky/datascript),+[Mentat](https://github.com/mozilla/mentat) and [XTDB](https://xtdb.com/) and is+in the general orbit of Datalog flavoured triple stores, it puts particular (and+to my knowledge novel) emphasis on type-safety and feeling 100% embedded into+the host language.++## Example schema+The examples below use these plain domain entities...++```haskell+data Department = Department { code :: Text, name :: Text }+ deriving (Show, Generic)+instance Entity Department where+ type Identity Department = '["code"]++data Skill = Skill { name :: Text }+ deriving (Show, Generic)+instance Entity Skill where+ type Identity Skill = '["name"]++data Order = Order { buyer :: Text, item :: Text, price :: Int }+ deriving (Show, Generic, Entity)++data Employee = Employee+ { email :: Text+ , name :: Text+ , dept :: Ref Department+ , salary :: Int+ , skills :: Set (Ref Skill)+ , nickname :: Maybe Text+ } deriving (Show, Generic)+instance Entity Employee where+ type Identity Employee = '["email"]+```++...and this db:++```haskell+Right db = commit_ emptyDb+ [ Insert (Department "ENG" "Engineering")+ , Insert (Department "SAL" "Sales")+ , Insert (Skill "Scala")+ , Insert (Skill "Haskell")+ , Insert (Employee "m@x.io" "Matt" (deptRef "ENG") 120000 (skillRefs ["Scala", "Haskell"]) (Just "Matty"))+ , Insert (Employee "a@x.io" "Alice" (deptRef "ENG") 110000 (skillRefs ["Scala"]) Nothing)+ , Insert (Employee "b@x.io" "Bob" (deptRef "SAL") 150000 mempty Nothing)+ , Insert (Order "m@x.io" "book" 20)+ , Insert (Order "a@x.io" "lamp" 90)+ , Insert (Order "b@x.io" "chair" 60)+ ]+ where+ deptRef = ref @Department+ skillRefs = Set.fromList . map (ref @Skill)++-- Engineering's Ref, for the examples below+Just eng = refOf <$> find @Department "ENG" db+```++`ref @Department "ENG"` points at a department by its code, which is how the+employees can reference it in the same list ([more on that](#look-up-entities-by-identity)).+Records can also share field names like `name`, thanks to `DuplicateRecordFields`.++The snippets from here on assume these:++<details>+<summary>Pragmas and imports</summary>++```haskell+{-# LANGUAGE DeriveGeneric #-}+{-# LANGUAGE DeriveAnyClass #-}+{-# LANGUAGE DuplicateRecordFields #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE OverloadedRecordDot #-}+{-# LANGUAGE DataKinds #-}+{-# LANGUAGE TypeApplications #-}+{-# LANGUAGE TypeFamilies #-}+import Control.Applicative ((<|>))+import Control.Monad (guard, when)+import Data.Foldable (for_, traverse_)+import Data.List (sortOn, (\\))+import qualified Data.Map.Strict as Map+import Data.Ord (Down (..))+import Data.Set (Set)+import qualified Data.Set as Set+import Data.Text (Text)+import Data.Time (getCurrentTime)+import GHC.Generics (Generic)+import Datomlite+```++</details>++## Model your data+Your records are the schema. List the identity fields in `Identity` and let the+field types do the rest.++## Mark unique fields with `Identity`+List a record's unique fields in its `Identity`. That's also how `find`, `ref`+and `Upsert` know which entity you mean.+```+type Identity t = '["f", ...] each field unique on its own (default: none)+Upsert r find by identity and write only the difference+ename override the attribute prefix+```++The record itself stays plain, `email` is still just Text. A typo in the list+won't compile:+```+datomlite: Identity User names "emial" but User has no such field+```++Each field in the list is unique on its own (like Datomic's+`:db.unique/identity`). A duplicate fails with `UniqueViolation` and nothing+gets written.++```haskell+data User = User+ { email :: Text+ , handle :: Text+ , name :: Text+ } deriving (Show, Generic)++instance Entity User where+ type Identity User = '["email", "handle"]++Right udb = commit_ emptyDb [Insert (User "a@x.io" "shared" "Alice")]++commit_ udb [Insert (User "b@x.io" "shared" "Bob")]+-- Left (UniqueViolation { uvAttr = "User/handle", uvValue = VText "shared"+-- , uvEntities = [EntityId 1,EntityId 2] })+```++The check looks at the end result of the commit, so retracting an entity and+reusing its identity in the same commit is fine.++`Upsert` updates in place, so refs to it keep working:+```haskell+commit_ db [Upsert (Department "ENG" "Platform")]+-- Matt's and Alice's dept now reads "Platform"+```++Two records with the same name in different modules will clash. Use `ename` to+tell them apart:+```haskell+instance Entity Person where+ type Identity Person = '["email"]+ ename _ = "a.Person"+```++## Look up entities by identity+`find` reads an entity by its identity. `ref` just points at it without reading+anything:+```+find @A v db Maybe (Stored A), the A whose Identity is v+ref @A v a Ref A to whichever entity holds v+findBy @A @"f" v db find, for a record with several identities+refBy @A @"f" v ref, likewise+```++```haskell+find @Department "ENG" db -- Just (Stored (Ref (EntityId 1)) (Department ...))+findBy @User @"handle" "shared" udb -- Just (Stored ...)+```++A `ref` is resolved on commit, so it can point at something written earlier in+the same list:++```haskell+Right db2 = commit_ db+ [ Upsert (Department "OPS" "Operations")+ , Upsert (Skill "Nix")+ , Upsert (Employee "o@x.io" "Olga" (ref @Department "OPS") 105000+ (Set.fromList [ref @Skill "Nix", ref @Skill "Haskell"]) Nothing)+ ]+```++And you can use it anywhere a Ref goes:++```haskell+commit_ db+ [ Update (ref @Employee "m@x.io") (setField @"salary" 125000)+ , Delete (ref @Employee "b@x.io")+ ]++query db $ do+ e <- matchBy @Employee @"dept" (ref @Department "ENG")+ pure e.name+-- ["Matt","Alice"]+```++A few things to know:+- The value is typed like the field. If a record has several identities, `find`+ won't compile, so say which one with `findBy`.+- A write through a ref to nothing fails with `UnknownIdentity`. A read just+ comes back empty.+- A `ref` never equals a stored Ref, since they hold different things. To+ compare, use `refOf d` rather than `ref @Department "ENG"`.++## Link entities with refs+To point one entity at another, give it a `Ref t` field. Cardinality comes from+the field's type, there's nothing to declare:++```+a one datom+Maybe a one datom on Just, nothing on Nothing+Set a one datom per element+Ref t one datom, value is the target's entity id+```++So `Maybe (Ref t)` and `Set (Ref t)` just work. Many-valued fields have to be+Sets (facts have no order or duplicates), a list field won't compile. In a+query, `follow` walks a ref and `oneOf` goes through a Set or Maybe:++```haskell+query db $ do+ e <- match @Employee+ d <- follow e.dept+ guard (d.name == "Engineering")+ s <- follow =<< oneOf e.skills+ pure (e.email, s.name)+-- [("m@x.io","Scala"),("m@x.io","Haskell"),("a@x.io","Scala")]+```++If you already have the Ref, just compare: `guard (e.dept == eng)`.++## Leave fields out with `Maybe`+Use Maybe for fields that can be missing. Nothing just means no datom gets+written, there's no stored null.++```haskell+query db $ do+ e <- match @Employee+ guard (e.nickname == Just "Matty")+ pure e.email+-- ["m@x.io"]++query db $ do+ e <- match @Employee+ guard (e.nickname == Nothing)+ pure e.email+-- ["a@x.io","b@x.io"]+```++`oneOf` unwraps it and skips the Nothings:++```haskell+query db $ do+ e <- match @Employee+ n <- oneOf e.nickname+ pure (e.email, n)+-- [("m@x.io","Matty")]+```++## Store enums, newtypes and other values+A field can be any of these, on its own or in a Maybe or Set:++```+Text, Int, Integer, Double, Bool+ByteString strict, from bytestring+UTCTime, Day from time+Ref t another entity+your enums stored as the constructor's name+your newtypes stored as the type they wrap+```++Your own enums and newtypes need one deriving line:++<details>+<summary>Extra pragmas and imports</summary>++```haskell+{-# LANGUAGE DerivingStrategies #-}+{-# LANGUAGE GeneralizedNewtypeDeriving #-}+import Data.Time (Day)+```++</details>++```haskell+data Level = Junior | Senior+ deriving stock (Show, Eq, Ord, Generic)+ deriving anyclass (ToValue, FromValue) -- "Junior" / "Senior"++newtype Email = Email Text+ deriving newtype (Show, Eq, Ord, ToValue, FromValue)++data Hire = Hire { email :: Email, level :: Level, started :: Day }+ deriving (Show, Generic, Entity)+```++`Ord` is only needed for Sets. If you rename an enum constructor, old entities+with the old name will throw `BadValue` on read. A constructor with fields can't+be a value, so make it its own entity and point at it with a Ref instead.++## Write data+To write, commit a list of writes. They're applied in order, all-or-nothing, and+you get a new db back. The old one stays as it was.++```+Insert r insert a record as a new entity+Upsert r insert, or update the entity already holding r's Identity+Update ref f change an entity with a function on its record+Delete ref retract every fact the entity holds+setField @"f" v a record -> record function that sets field f+commit_ db [w, ...] Either TxError db'+commit db [w, ...] Either TxError ((), db')+```++If a step needs the result of an earlier one, use a [Tx+block](#chain-dependent-steps-in-a-tx-block) instead.++## Add data+`Insert` adds a record as a new entity. Everything in the list lands in one tx:++```haskell+Right db1 = commit_ db [Insert (Employee "c@x.io" "Carol" eng 100000 mempty Nothing)]+Right db2 = commit_ db1+ [ Insert (Employee "d@x.io" "Dan" eng 90000 mempty Nothing)+ , Insert (Employee "e@x.io" "Eve" eng 95000 mempty Nothing)+ ]+```++If the identity is already taken it fails with `UniqueViolation`. Use `Upsert`+if you want to replace.++## Update data+If you have the whole new record, `Upsert` it. It updates whatever has the same+identity (or inserts if there's nothing), and refs to it keep working:++```haskell+commit_ db [Upsert (Department "ENG" "Platform")]+-- Matt's and Alice's dept now reads "Platform"+```++To change a few fields, `Update` takes a ref and a function on the record.+`setField` is the easy way to write that function:++```haskell+commit_ db [Update (ref @Employee "m@x.io") (setField @"salary" 125000)]++commit_ db+ [ Update (ref @Employee "m@x.io")+ (setField @"name" "Matthieu" . setField @"salary" 125000) ]+```++Any `a -> a` works, so a plain record update is fine too. `setField` is mostly+there for when two records share a field name and `e { name = … }` gets+ambiguous. Only the changed fields get written.++## Remove data+`Delete` retracts everything an entity holds:++```haskell+Right db3 = commit_ db2 [Delete (ref @Employee "c@x.io")]+```++To remove everything a query matches, turn the results into Deletes:++```haskell+-- remove every order Matt placed+commit_ db [ Delete (refOf o) | o <- query db (matchBy @Order @"buyer" "m@x.io") ]+```++On a Conn, someone else could commit between your query and your delete. If+that matters, do both in a [Tx block](#chain-dependent-steps-in-a-tx-block).++Removed entities stay in the log, so you can still get at them with+[time travel](#travel-back-in-time).++## Chain dependent steps in a `Tx` block+A list covers most writes. Reach for a Tx do-block when a step needs an earlier+step's result, the db so far, or a way to bail out:+```+insert r / upsert r Insert / Upsert, returning the entity's Ref+update ref f Update+retract ref Delete+txDb the in-progress db, earlier steps included+abort msg give up with Aborted msg+Just x <- ... a failed pattern aborts too (MonadFail)+commit db tx Either TxError (the block's result, db')+```++Steps run in order and commit all-or-nothing, and you get back whatever the+block returns:++```haskell+Right (carol, _) = commit db $ insert (Employee "c@x.io" "Carol" eng 100000 mempty Nothing)+-- carol :: Ref Employee+```++`txDb` is the db so far, so you can read and write based on what's there:+```haskell+Right db' = commit_ db $ do+ now <- txDb+ for_ (find @Employee "m@x.io" now) $ \e ->+ update (refOf e) (setField @"name" "Matthieu")+ insert (Order "m@x.io" "book" 20)+```++Reads and writes in a block are atomic, so a bank transfer is easy:++```haskell+data Account = Account { owner :: Text, balance :: Int }+ deriving (Show, Generic)++instance Entity Account where+ type Identity Account = '["owner"]++transfer :: Ref Account -> Ref Account -> Int -> Tx ()+transfer from to amount = do+ Just a <- load from <$> txDb -- no such account: aborts+ when (a.balance < amount) $ abort "insufficient funds"+ update from (\x -> x { balance = x.balance - amount })+ update to (\x -> x { balance = x.balance + amount })++Right adb = commit_ emptyDb [Insert (Account "alice" 100), Insert (Account "bob" 0)]++alice = ref @Account "alice"+bob = ref @Account "bob"++commit_ adb (transfer alice bob 30) -- Right adb', alice 70 and bob 30+commit_ adb (transfer alice bob 500)+-- Left (Aborted "insufficient funds")+```++Writes and Tx blocks are plain values, so you can build them now and commit later:+```haskell+orders :: [Write]+orders = [Insert (Order "m@x.io" "book" 20), Insert (Order "m@x.io" "pen" 5)]++commit_ db orders+```++When a transaction fails you get one of these:+```+UniqueViolation attr v es an Identity value the entities es would share+UnknownIdentity attr v a ref nothing holds+UnknownEntity eid update on an entity with no facts+Aborted msg abort, or a failed pattern+SinceView a commit on a since view+```++## Read data+Every read takes a db value, so nothing changes under you and reads on the same+db always agree.++```+load ref db Maybe (Stored A)+every @A db [Stored A], in creation order+find @A v db Maybe (Stored A), by its Identity+query db q [a], run a Query+```++You get back a `Stored A`, which is the record plus its Ref. `p.name` reads a+field, `refOf p` gives the Ref and `recordOf p` the plain record.++## Get one entity+Use `find` with the identity, or `load` if you already have a Ref:++```haskell+(.name) <$> find @Employee "c@x.io" db2 -- Just "Carol"+find @Employee "zz@x.io" db2 -- Nothing+(.name) <$> load eng db -- Just "Engineering"+```++## List, filter and count entities+`every` lists all entities of a type, and a [query](#run-queries) filters them.+Results are plain lists, so counting is just `length`:++```haskell+map recordOf (every @Employee db2) -- [Employee]++query db2 $ do -- [Employee]+ e <- match @Employee+ guard (e.email == "m@x.io")+ pure (recordOf e)++length (every @Employee db3) -- 5+not (null (query db3 (byEmail "m@x.io"))) -- True+```++To reuse a lookup, write a function. `matchBy` goes through the index instead+of scanning:++```haskell+byEmail :: Text -> Query (Ref Employee)+byEmail em = refOf <$> matchBy @Employee @"email" em+```++## Run queries+A query is just a do-block. `guard`, `pure` and `<|>` are the usual Haskell, and+these are the only new pieces:+```+match @A every entity of type A+matchBy @A @"f" v the A's whose field f holds v, via the index+follow ref the entity a Ref (or a lookup ref) points at+oneOf xs each value of a Set or Maybe field+exists q / none q keep the row if subquery q has rows / has none+closure step x everything reachable by repeating step, safe on cycles+```++### Join in a do-block+Stitch entities together on a shared field, no DSL. Each row is whatever you+`pure`:++```haskell+query db $ do+ e <- match @Employee+ o <- match @Order+ guard (o.buyer == e.email)+ pure (e.name, o.item)+-- [("Matt","book"),("Alice","lamp"),("Bob","chair")]+```++> [!NOTE]+> `match` plus `guard` is a nested loop. `follow` and `matchBy` use the index.++### Look up rows through the index+`matchBy @A @"f" v` finds the A's whose field f holds v, straight from the+index. It works on Maybe, Set and Ref fields too:++```haskell+query db $ do+ e <- match @Employee+ o <- matchBy @Order @"buyer" e.email+ pure (e.name, o.item)+-- [("Matt","book"),("Alice","lamp"),("Bob","chair")]++query db $ do+ s <- matchBy @Skill @"name" "Scala"+ e <- matchBy @Employee @"skills" (refOf s)+ pure e.name+-- ["Matt","Alice"]+```++Field names and value types are checked, so a typo won't compile.++### Read fields with their real types+`e.name` is the record's own field with its real type (`e.nickname` is a+`Maybe Text`), so `e.emial` or `e.name == 5` won't compile.++### Follow refs backwards+To go from a department to its employees, pass the department's Ref to+`matchBy`:++```haskell+query db $ do+ d <- matchBy @Department @"code" "ENG"+ e <- matchBy @Employee @"dept" (refOf d)+ pure e.name+-- ["Matt","Alice"]+```++### Aggregate rows+Results are lists, so this is just Haskell:++```haskell+Map.fromListWith (+) $ query db $ do+ e <- match @Employee+ o <- matchBy @Order @"buyer" e.email+ pure (e.name, o.price)+-- fromList [("Alice",90),("Bob",60),("Matt",20)]+```++### Sort and page results+Same here:++```haskell+take 2 . sortOn (Down . snd) $ query db $ do+ e <- match @Employee+ guard (e.salary > 100000)+ pure (e.name, e.salary)+-- [("Bob",150000),("Matt",120000)]+```++## Exclude matches with `none`+`none` keeps a row only when a subquery comes back empty (an anti-join):++```haskell+-- employees with no orders+query db2 $ do+ e <- match @Employee+ none (matchBy @Order @"buyer" e.email)+ pure e.name+-- ["Carol","Dan","Eve"]+```++## Check that a match exists+Sometimes you only care that a match exists, not what it is (a semi-join).+`exists` keeps the row once, however many matches there are:++```haskell+-- orders whose buyer exists as a registered Employee+query db $ do+ o <- match @Order+ exists (byEmail o.buyer)+ pure o.item+-- ["book","lamp","chair"]+```++## Rank and total with window functions+Like SQL's `rank() OVER (PARTITION BY ...)`, but as plain functions on the result+list:++```+window part ord w rows group by part, sort by ord, run w on each group+rowNumber 1, 2, 3...+rank ties share a rank and the next one skips: 1, 1, 3+denseRank ties share a rank with no skip: 1, 1, 2+lag n f / lead n f f of the row n before / after, Nothing past the edge+whole f f of the whole group, on each row+running f f of the group up to this row+```++```haskell+pay = query db $ do+ e <- match @Employee+ d <- follow e.dept+ pure (d.name, e.name, e.salary)++deptOf (d, _, _) = d+salaryOf (_, _, s) = s++window deptOf (Down . salaryOf) ((,) <$> rank <*> whole (sum . map salaryOf)) pay+-- [ (("Engineering","Matt",120000), (1,230000))+-- , (("Engineering","Alice",110000), (2,230000))+-- , (("Sales","Bob",150000), (1,150000)) ]++-- top earner per dept+[ (d, n) | ((d, n, _), 1) <- window deptOf (Down . salaryOf) rowNumber pay ]+-- [("Engineering","Matt"),("Sales","Bob")]+```++Windows combine with `<*>`. Pass `const ()` as the partition for one big group.++## Reuse logic with rules+A rule is just a function returning a Query. `<|>` means either branch, and a+rule that calls itself is recursive.++### Write recursive rules++Say we have a chain of command...+<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-tree-ex1.svg" width="500">+</p>++```haskell+data Off = Off+ { officer :: Text+ , boss :: Maybe (Ref Off)+ } deriving (Generic)++instance Entity Off where+ type Identity Off = '["officer"]++Right db = commit_ emptyDb+ [ Insert (Off "Napoléon" Nothing)+ , Insert (Off "Davout" (under "Napoléon"))+ , Insert (Off "Ney" (under "Napoléon"))+ , Insert (Off "Murat" (under "Napoléon"))+ , Insert (Off "Friant" (under "Davout"))+ , Insert (Off "Gudin" (under "Davout"))+ , Insert (Off "Lasalle" (under "Murat"))+ , Insert (Off "Marchand" (under "Ney"))+ ]+ where under = Just . ref @Off++-- a direct report, or anyone below one+subordinates :: Stored Off -> Query (Stored Off)+subordinates o = do+ s <- matchBy @Off @"boss" (refOf o)+ pure s <|> subordinates s++-- their boss, or anyone above them+bosses :: Stored Off -> Query (Stored Off)+bosses o = do+ b <- follow =<< oneOf o.boss+ pure b <|> bosses b++named :: Text -> Query (Stored Off)+named = matchBy @Off @"officer"+```++**Find everyone under Davout:**+<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-tree-ex2.svg" width="500">+</p>++```haskell+query db $ do+ s <- subordinates =<< named "Davout"+ pure s.officer+-- ["Friant","Gudin"]+```++**Find everyone above Lasalle:**+<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-tree-ex3.svg" width="500">+</p>++```haskell+query db $ do+ b <- bosses =<< named "Lasalle"+ pure b.officer+-- ["Murat","Napoléon"]+```++In SQL, the first one is a recursive CTE:++```sql+WITH RECURSIVE ancestor(anc, desc) AS (+ SELECT boss, name FROM off WHERE boss IS NOT NULL+ UNION+ SELECT a.anc, o.name+ FROM ancestor a JOIN off o ON o.boss = a.desc+)+SELECT desc FROM ancestor WHERE anc = 'Davout';+```++> [!NOTE]+> This is plain recursion, which is fine on trees but loops forever on a cycle.+> Use `closure` for those.++### Walk graphs with cycles (`closure`)+`closure step x` finds everything reachable from x, each entity once, so cycles+are fine.++#### Find every reachable city (directed graph)++<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-roads.svg" width="350">+</p>++```haskell+data Place = Place { code :: Text } deriving (Generic)+data Road = Road { from :: Ref Place, to :: Ref Place } deriving (Generic, Entity)++instance Entity Place where+ type Identity Place = '["code"]++Right db = commit_ emptyDb $+ [ Insert (Place c) | c <- ["PAR", "LYO", "MAR", "NCE", "BOR"] ]+ ++ [ Insert (Road (at a) (at b))+ | (a, b) <- [("PAR", "LYO"), ("LYO", "MAR"), ("MAR", "PAR") {- cycle -}, ("LYO", "NCE"), ("PAR", "BOR")] ]+ where at = ref @Place++-- one road away+next :: Stored Place -> Query (Stored Place)+next p = do+ r <- matchBy @Road @"from" (refOf p)+ follow r.to++-- everywhere reachable from Paris. The cycle means PAR reaches itself+query db $ do+ t <- closure next =<< matchBy @Place @"code" "PAR"+ pure t.code+-- ["LYO","BOR","MAR","NCE","PAR"]+```++#### Find everyone in a friend group (undirected graph)+Each friendship is stored once, and `knows` reads it both ways:++<p align="center">+ <img src="https://raw.githubusercontent.com/mattlianje/datomlite/refs/heads/master/pix/datomlite-friends.svg" width="500">+</p>++```haskell+data Person = Person { handle :: Text } deriving (Generic)+data Friend = Friend { a :: Ref Person, b :: Ref Person } deriving (Generic, Entity)++instance Entity Person where+ type Identity Person = '["handle"]++Right db = commit_ emptyDb $+ [ Insert (Person h) | h <- ["alice", "bob", "carol", "dave", "erin", "frank", "grace"] ]+ ++ [ Insert (Friend (who x) (who y))+ | (x, y) <- [ ("alice", "bob"), ("alice", "carol"), ("bob", "dave")+ , ("carol", "dave"), ("dave", "erin"), ("frank", "grace") ] ]+ where who = ref @Person++knows :: Stored Person -> Query (Stored Person)+knows x = (follow . (.b) =<< matchBy @Friend @"a" (refOf x))+ <|> (follow . (.a) =<< matchBy @Friend @"b" (refOf x))++handleIs :: Text -> Query (Stored Person)+handleIs = matchBy @Person @"handle"++-- Alice's cluster...+query db $ do+ y <- closure knows =<< handleIs "alice"+ pure y.handle+-- ["bob","carol","dave","alice","erin"]++-- Frank is in a separate component+query db $ do+ y <- closure knows =<< handleIs "alice"+ guard (y.handle == "frank")+-- []+```++Results come out nearest first, and since `closure` is lazy, `exists (closure ...)`+stops at the first hit.++## Travel back in time+Queries run on any db value, so you can look at the db as it was at any point,+or try a change and just not keep it.++```+basisT db the tx a db value reflects+asOf t db rewind to tx t+asOfTime t db rewind to a wall-clock time+txTime tx db when tx was committed+since t db only the facts added after tx t+db a snapshot is the value you already hold+commit db tx a what-if branch is a commit you don't keep+```++```haskell+names :: Query Text+names = do+ e <- match @Employee+ pure e.name++-- db' is db after the "Matthieu" rename from the Tx block section+query db' names -- ["Matthieu","Alice","Bob"]+query (asOf (basisT db) db') names -- ["Matt","Alice","Bob"]+query (since (basisT db) db2) names -- ["Carol","Dan","Eve"]+```++Rewinding by wall-clock time needs timestamps. `transact` adds them, `commit`+doesn't (it's pure), and `commitAt t` uses the time you give it:++```haskell+conn <- connect db+before <- getCurrentTime+Right (_, now) <- transact conn [Insert (Employee "d@x.io" "Dan" eng 90000 mempty Nothing)]++length (every @Employee (asOfTime before now)) -- 3, before Dan+length (every @Employee now) -- 4+```++An unstamped transaction counts as happening at the stamp before it, which is why+the pure seed shows up at any time. Times never go backwards, even if the clock+does.++A `since` view only has the newer facts, so an entity created before `t` and+changed after is only partly there. Typed reads skip it, but `datoms` shows+everything.++A what-if:+```haskell+let whatIf = commit_ db2 [Insert (Employee "z@x.io" "Zed" eng 1 mempty Nothing)]++length (every @Employee db2) -- 6+length . every @Employee <$> whatIf -- Right 7, includes Zed+length (every @Employee db2) -- 6, still+```++## See every change to an entity+`history` gives you every datom ever written. Filter by `refId` for one entity.++```+history db every datom, oldest first+datoms db just the live facts+refId ref a Ref's EntityId, to filter a trail by+```++Each datom has its tx and whether it was an assert or a retract. Nothing gets+overwritten, so the trail is still there after a delete:++```haskell+Just carol = refOf <$> find @Employee "c@x.io" db2++[ (dAttr d, dValue d, dTx d, dOp d) | d <- history db3, dEntity d == refId carol ]+-- [ ("Employee/email", VText "c@x.io", TxId 2, Assert)+-- , ("Employee/name", VText "Carol", TxId 2, Assert)+-- , ("Employee/dept", VRef (EntityId 1), TxId 2, Assert)+-- , ("Employee/salary", VInt 100000, TxId 2, Assert)+-- , ("Employee/dept", VRef (EntityId 1), TxId 4, Retract)+-- , ... ]+```++It's all plain data underneath. `fromHistory` builds a db from any list of+datoms, even hand-made ones (but then you skip the checks a commit does).++## Diff two dbs+An unchanged fact is the same datom in both dbs, so a diff is just list+difference:++```haskell+-- db' is db after the Tx block example: a rename plus a new order+[ dValue d | d <- datoms db' \\ datoms db ] -- added+-- [VText "Matthieu",VText "m@x.io",VText "book",VInt 20]+[ dValue d | d <- datoms db \\ datoms db' ] -- retracted+-- [VText "Matt"]+```++## Share a changing db with `Conn`+A Db never changes. When several threads need one shared db, put it in a Conn+(a mutable cell). `transact` is just `commit` on that cell, with the same writes,+the same checks and the same result:++```+commit db w Either TxError (r, Db) pure, the db is yours+transact conn w IO (Either TxError (r, Db)) the Conn holds the new db+connect db IO Conn+snapshot conn IO Db, whatever the Conn holds right now+```++`r` is `()` for a list, or whatever a Tx block returns.++```haskell+conn <- connect emptyDb+Right ((), db) <- transact conn+ [ Insert (Department "ENG" "Engineering")+ , Insert (Employee "m@x.io" "Matt" (ref @Department "ENG") 120000 mempty Nothing)+ ]++(.name) <$> find @Employee "m@x.io" db -- Just "Matt"+```++## React to every commit+`listen` runs a callback after every commit. Each subscriber is its own thread,+so writers never wait on it:++```+listen conn f IO (IO ()), f gets one TxReport per commit+awaitAfter conn t STM Db, blocks until a commit newer than t+```++```haskell+stop <- listen conn $ \r ->+ putStrLn (show (trTxId r) <> ": " <> show (length (trDatoms r)) <> " datoms")++stop -- unsubscribe+```++- You see every commit, in order. A slow listener catches up from the log.+- Callbacks can read or commit. If one throws, it's printed to stderr and+ `transact` never sees it.+- It's async, so a callback may not have run yet when `transact` returns. To+ wait for a commit yourself, use `awaitAfter` (it's plain STM).++## Keep a query result up to date+`listen` tells you *that* something changed, `watch` tells you *what* a query+returns now. It runs once right away, then again on every change:++```+watch conn q f IO (IO ()), f gets q's result, up front and on change+```++```haskell+stopWatch <- watch conn (length . every @Employee) $ \n ->+ putStrLn (show n <> " employees")+```++It always runs on the newest db, so if commits come in faster than your callback,+you skip straight to the latest result. Otherwise it works like `listen`.++## Save and restore a db+The log is the database. Save the datoms and `fromHistory` rebuilds the db,+history and all. `Show` and `Read` round-trip, so one datom per line is a+perfectly good file format:++```+history db [Datom], every fact, oldest first+fromHistory datoms Db, rebuilt from them+```++<details>+<summary>Extra imports</summary>++```haskell+import System.IO (readFile')+```++</details>++```haskell+restore :: FilePath -> IO Db+restore path = fromHistory . map read . lines <$> readFile' path++-- open the log (an empty file for a new db), then append each commit to it+conn <- connect =<< restore "app.log"+stop <- listen conn $ \r -> appendFile "app.log" (unlines (map show (trDatoms r)))+```++A restored db picks up right where the old one stopped, past included.++Two caveats. `listen` is async, so a crash right after a commit can lose it. If+that matters, append the datoms yourself after `transact` returns. And `Show`+is simple, not fast, so for a big log you'll want your own encoding (all the+constructors are exported).++## Read and write from many threads+A Db is just a value, so pass it around and read it from any thread. The db you+get back from `transact` is the one your commit made, even if someone else has+committed since. `snapshot conn` gives you whatever is current.++## Build / Contribute+PRs welcome, just stick to boot-library deps.+```+make build+make test+make repl+```
+ datomlite.cabal view
@@ -0,0 +1,56 @@+cabal-version: 3.0+name: datomlite+version: 0.1.0.0+synopsis: Lightweight, immutable "DB-as-a-value"+description: An append-only EAV log where the whole database is a pure value.+ Plain records are the schema, queries are typed, and time travel+ is just a pure function over the log.+homepage: https://github.com/mattlianje/datomlite+bug-reports: https://github.com/mattlianje/datomlite/issues+license: Apache-2.0+license-file: LICENSE+author: Matthieu Court+maintainer: matthieu.court@protonmail.com+copyright: 2026 Matthieu Court+category: Database+build-type: Simple++extra-doc-files:+ README.md+ CHANGELOG.md++source-repository head+ type: git+ location: https://github.com/mattlianje/datomlite+ subdir: datomlite-hs++library+ exposed-modules: Datomlite+ build-depends: base >= 4.7 && < 5+ , text >= 2.1.2 && < 2.2+ , containers >= 0.5 && < 0.9+ , stm >= 2.5 && < 2.6+ , bytestring >= 0.11 && < 0.13+ , time >= 1.9 && < 1.15+ hs-source-dirs: .+ default-language: Haskell2010+ ghc-options: -Wall++test-suite datomlite-tests+ type: exitcode-stdio-1.0+ main-is: Test.hs+ other-modules: Demo+ Helpers+ Shared+ build-depends: base >= 4.7 && < 5+ , datomlite+ , bytestring+ , containers+ , time+ , text+ , stm+ , tasty >= 1.4+ , tasty-hunit >= 0.10+ hs-source-dirs: test+ default-language: Haskell2010+ ghc-options: -Wall -threaded -rtsopts -with-rtsopts=-N
+ test/Demo.hs view
@@ -0,0 +1,183 @@+{-# LANGUAGE DataKinds #-}+{-# LANGUAGE DeriveGeneric #-}+{-# LANGUAGE OverloadedRecordDot #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE TypeApplications #-}+{-# LANGUAGE TypeFamilies #-}++module Demo (demoTests) where++import Control.Applicative ((<|>))+import Control.Concurrent (newEmptyMVar, putMVar, takeMVar)+import Control.Concurrent.STM (atomically)+import Control.Monad (guard, when)+import Data.List (sort, sortOn, (\\))+import qualified Data.Map.Strict as Map+import Data.Ord (Down (..))+import Data.Text (Text)+import GHC.Generics (Generic)+import System.Timeout (timeout)++import Test.Tasty+import Test.Tasty.HUnit++import Datomlite++import Helpers++-- Records are the schema, refs are just fields+data Fighter = Fighter { name :: Text, style :: Text, country :: Text }+ deriving (Show, Generic)+instance Entity Fighter where+ type Identity Fighter = '["name"]++data Bout = Bout+ { code :: Text+ , red :: Ref Fighter+ , blue :: Ref Fighter+ , winner :: Ref Fighter+ } deriving (Show, Generic)+instance Entity Bout where+ type Identity Bout = '["code"]++-- A db is a value. One commit, refs point at fighters by name+db :: Db+db = must $ commit_ emptyDb+ [ Insert (Fighter "Jet Li" "Wushu" "China")+ , Insert (Fighter "Gegard Mousasi" "Mixed" "Netherlands")+ , Insert (Fighter "Rory MacDonald" "Pankration" "Canada")+ , Insert (Bout "B1" li gegard li)+ , Insert (Bout "B2" li rory li)+ , Insert (Bout "B3" gegard rory gegard)+ , Insert (Bout "B4" rory li li)+ ]+ where+ li = ref @Fighter "Jet Li"+ gegard = ref @Fighter "Gegard Mousasi"+ rory = ref @Fighter "Rory MacDonald"++-- Who beat whom: a join across both corners of every bout+results :: Query (Text, Text)+results = do+ b <- match @Bout+ w <- follow b.winner+ l <- follow (if b.winner == b.red then b.blue else b.red)+ pure (w.name, l.name)++-- Rollups are plain Haskell over the rows+standings :: Db -> [(Text, Int)]+standings d = sortOn (Down . snd) . Map.toList . Map.fromListWith (+) $ query d $ do+ b <- match @Bout+ w <- follow b.winner+ pure (w.name, 1)++-- A rule is a function returning a Query+beat :: Stored Fighter -> Query (Stored Fighter)+beat f = do+ b <- matchBy @Bout @"winner" (refOf f)+ l <- follow b.red <|> follow b.blue+ guard (refOf l /= refOf f)+ pure l++named :: Text -> Query (Stored Fighter)+named = matchBy @Fighter @"name"++-- A Tx block: steps that can check and bail+book :: Text -> Text -> Text -> Text -> Tx (Ref Bout)+book c r b w = do+ when (r == b) $ abort "can't fight yourself"+ when (w /= r && w /= b) $ abort "winner must be in the bout"+ insert (Bout c (ref @Fighter r) (ref @Fighter b) (ref @Fighter w))++-- Rory gets his revenge, on a branch we may not keep+upset :: Db+upset = must $ commit_ db (book "B5" "Jet Li" "Rory MacDonald" "Rory MacDonald")++demoTests :: TestTree+demoTests = testGroup "Demo (a fight db tour)"+ [ testCase "reads feel like a collection" $ do+ length (every @Fighter db) @?= 3+ [ f.name | f <- every @Fighter db, f.country == "China" ] @?= ["Jet Li"]+ (.style) <$> find @Fighter "Gegard Mousasi" db @?= Just "Mixed"++ , testCase "joins are do-blocks that follow refs" $+ query db results @?=+ [ ("Jet Li", "Gegard Mousasi")+ , ("Jet Li", "Rory MacDonald")+ , ("Gegard Mousasi", "Rory MacDonald")+ , ("Jet Li", "Rory MacDonald")+ ]++ , testCase "reverse refs are index lookups" $+ query db (do f <- named "Jet Li"+ b <- matchBy @Bout @"winner" (refOf f)+ pure b.code)+ @?= ["B1", "B2", "B4"]++ , testCase "aggregations are plain Haskell" $+ standings db @?= [("Jet Li", 3), ("Gegard Mousasi", 1)]++ , testCase "window functions rank with ties" $+ window (const ()) (Down . snd) rank (standings upset) @?=+ [ (("Jet Li", 3), 1)+ , (("Gegard Mousasi", 1), 2)+ , (("Rory MacDonald", 1), 2)+ ]++ , testCase "negation: fighters who never won" $+ query db (do f <- match @Fighter+ none (matchBy @Bout @"winner" (refOf f))+ pure f.name)+ @?= ["Rory MacDonald"]++ , testCase "recursive rules: everyone Jet Li beat, transitively" $+ sort (query db (do t <- closure beat =<< named "Jet Li"; pure t.name))+ @?= ["Gegard Mousasi", "Rory MacDonald"]++ , testCase "closure is safe on cycles" $ do+ -- after the upset, Rory > Li > Gegard > Rory+ query db (do t <- closure beat =<< named "Rory MacDonald"; pure t.name) @?= []+ sort (query upset (do t <- closure beat =<< named "Rory MacDonald"; pure t.name))+ @?= ["Gegard Mousasi", "Jet Li", "Rory MacDonald"]++ , testCase "Tx blocks commit all-or-nothing" $ do+ case commit_ db (book "B5" "Jet Li" "Jet Li" "Jet Li") of+ Left (Aborted m) -> m @?= "can't fight yourself"+ other -> assertFailure (show (fmap basisT other))+ case commit_ db (book "B5" "Jet Li" "Bruce Lee" "Jet Li") of+ Left (UnknownIdentity _ _) -> pure ()+ other -> assertFailure (show (fmap basisT other))++ , testCase "what-if branches leave db untouched" $ do+ standings upset @?= [("Jet Li", 3), ("Gegard Mousasi", 1), ("Rory MacDonald", 1)]+ standings db @?= [("Jet Li", 3), ("Gegard Mousasi", 1)]++ , testCase "upsert keeps refs, time travel and diff see the change" $ do+ let db' = must $ commit_ db [Upsert (Fighter "Gegard Mousasi" "Kickboxing" "Netherlands")]+ gegardStyle d = query d $ do+ b <- matchBy @Bout @"code" "B3"+ w <- follow b.winner+ pure w.style+ gegardStyle db' @?= ["Kickboxing"]+ gegardStyle (asOf (basisT db) db') @?= ["Mixed"]+ [ dValue d | d <- datoms db' \\ datoms db ] @?= [VText "Kickboxing"]+ [ dValue d | d <- datoms db \\ datoms db' ] @?= [VText "Mixed"]++ , testCase "the log is the database: save and restore" $ do+ let saved = unlines (map show (history upset))+ fromHistory (map read (lines saved)) @?= upset++ , testCase "a Conn shares one changing db, watchers see each commit" $ do+ conn <- connect db+ seen <- newEmptyMVar+ stop <- watch conn standings (putMVar seen)+ first <- timeout 1000000 (takeMVar seen)+ first @?= Just [("Jet Li", 3), ("Gegard Mousasi", 1)]+ (_, db') <- expectRight =<<+ transact conn (book "B5" "Jet Li" "Rory MacDonald" "Rory MacDonald")+ next <- timeout 1000000 (takeMVar seen)+ next @?= Just (standings db')+ now <- atomically (awaitAfter conn (basisT db))+ basisT now @?= basisT db'+ stop+ ]
+ test/Helpers.hs view
@@ -0,0 +1,9 @@+module Helpers (expectRight, must) where++import Test.Tasty.HUnit (assertFailure)++expectRight :: Show e => Either e a -> IO a+expectRight = either (assertFailure . show) pure++must :: Show e => Either e a -> a+must = either (error . show) id
@@ -0,0 +1,170 @@+{-# LANGUAGE DataKinds #-}+{-# LANGUAGE DeriveAnyClass #-}+{-# LANGUAGE DeriveGeneric #-}+{-# LANGUAGE DuplicateRecordFields #-}+{-# LANGUAGE OverloadedRecordDot #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE TypeApplications #-}+{-# LANGUAGE TypeFamilies #-}++module Shared (sharedTests) where++import Control.Monad (guard)+import Data.Set (Set)+import qualified Data.Set as Set+import Data.Text (Text)+import GHC.Generics (Generic)++import Test.Tasty+import Test.Tasty.HUnit++import Datomlite++import Helpers++data Team = Team { code :: Text, name :: Text }+ deriving (Generic, Show, Eq)+instance Entity Team where+ type Identity Team = '["code"]++data Tag = Tag { name :: Text }+ deriving (Generic, Show, Eq)+instance Entity Tag where+ type Identity Tag = '["name"]++data Member = Member+ { email :: Text+ , name :: Text+ , team :: Ref Team+ , tags :: Set (Ref Tag)+ , nickname :: Maybe Text+ , level :: Int+ } deriving (Generic, Show, Eq)+instance Entity Member where+ type Identity Member = '["email"]++data Purchase = Purchase { buyer :: Text, item :: Text }+ deriving (Generic, Show, Eq, Entity)++-- A record stored under a custom prefix.+data Renamed = Renamed { label :: Text }+ deriving (Generic, Show, Eq)+instance Entity Renamed where+ type Identity Renamed = '["label"]+ ename _ = "x.Renamed"++data World = World+ { db :: Db, eng :: Ref Team, sal :: Ref Team, hs :: Ref Tag, mx :: Ref Member }++world :: World+world = must $ do+ ((e, s, h, m), d) <- commit emptyDb $ do+ e <- insert (Team "ENG" "Engineering")+ s <- insert (Team "SAL" "Sales")+ [h, sc] <- traverse insert [Tag "haskell", Tag "scala"]+ m <- insert (Member "m@x.io" "Max" e (Set.fromList [h, sc]) (Just "mx") 3)+ _ <- insert (Member "a@x.io" "Ann" e (Set.singleton sc) Nothing 2)+ _ <- insert (Member "s@x.io" "Sam" s mempty Nothing 3)+ _ <- insert (Purchase "m@x.io" "book")+ _ <- insert (Purchase "z@x.io" "lamp")+ pure (e, s, h, m)+ pure (World d e s h m)++sharedTests :: TestTree+sharedTests = testGroup "Shared field names (setField, matchBy, exists, none)"+ [ setFieldTests, matchByTests, subqueryTests ]++setFieldTests :: TestTree+setFieldTests = testGroup "setField"+ [ testCase "reads of a shared field name are unambiguous" $ do+ query world.db (do m <- match @Member; t <- follow m.team; pure (m.name, t.name))+ @?= [("Max", "Engineering"), ("Ann", "Engineering"), ("Sam", "Sales")]++ , testCase "sets a field whose name another record shares" $ do+ db' <- expectRight $ commit_ world.db $ do+ update world.mx (setField @"name" "Maximilian")+ update world.eng (setField @"name" "Platform")+ (.name) <$> load world.mx db' @?= Just "Maximilian"+ (.name) <$> load world.eng db' @?= Just "Platform"++ , testCase "composes, and leaves the other fields alone" $ do+ db' <- expectRight $ commit_ world.db $+ update world.mx (setField @"level" 4 . setField @"nickname" Nothing)+ let was = load world.mx world.db+ now = load world.mx db'+ ((.level) <$> now, (.nickname) <$> now) @?= (Just 4, Just Nothing)+ ((.name) <$> now, (.tags) <$> now) @?= ((.name) <$> was, (.tags) <$> was)++ , testCase "an identity field stays unique" $ do+ db' <- expectRight $ commit_ world.db (update world.mx (setField @"email" "max@x.io"))+ (.email) <$> load world.mx db' @?= Just "max@x.io"+ Just ann <- pure (find @Member "a@x.io" world.db)+ commit_ world.db (update world.mx (setField @"email" "a@x.io"))+ @?= Left (UniqueViolation "Member/email" (VText "a@x.io") (map refId [world.mx, refOf ann]))+ ]++matchByTests :: TestTree+matchByTests = testGroup "matchBy"+ [ testCase "by identity" $ do+ query world.db (do m <- matchBy @Member @"email" "a@x.io"; pure m.name) @?= ["Ann"]+ query world.db (do m <- matchBy @Member @"email" "nobody"; pure m.name) @?= []++ , testCase "by a plain field, in creation order" $ do+ query world.db (do m <- matchBy @Member @"level" 3; pure m.name) @?= ["Max", "Sam"]++ , testCase "by a ref: a reverse lookup" $ do+ query world.db (do m <- matchBy @Member @"team" world.eng; pure m.name) @?= ["Max", "Ann"]+ query world.db (do t <- matchBy @Team @"code" "SAL"+ m <- matchBy @Member @"team" (refOf t)+ pure m.name) @?= ["Sam"]++ , testCase "by one element of a Set field" $ do+ query world.db (do m <- matchBy @Member @"tags" world.hs; pure m.name) @?= ["Max"]++ , testCase "by the value inside a Maybe field" $ do+ query world.db (do m <- matchBy @Member @"nickname" "mx"; pure m.name) @?= ["Max"]++ , testCase "agrees with match + guard, and tracks updates and retracts" $ do+ db' <- expectRight $ commit_ world.db $ do+ update world.mx (setField @"team" world.sal)+ now <- txDb+ [ann] <- pure (query now (refOf <$> matchBy @Member @"name" "Ann"))+ retract ann+ let viaIndex = query db' (do m <- matchBy @Member @"team" world.sal; pure m.name)+ viaScan = query db' (do m <- match @Member; guard (m.team == world.sal); pure m.name)+ viaIndex @?= ["Max", "Sam"]+ viaIndex @?= viaScan+ query db' (matchBy @Member @"email" "a@x.io") @?= []+ -- and the past is still there+ query (asOf (basisT world.db) db') (do m <- matchBy @Member @"email" "a@x.io"; pure m.name)+ @?= ["Ann"]++ , testCase "respects a custom ename" $ do+ (r, d) <- expectRight $ commit emptyDb (insert (Renamed "x"))+ query d (refOf <$> matchBy @Renamed @"label" "x") @?= [r]+ ]++subqueryTests :: TestTree+subqueryTests = testGroup "exists / none"+ [ testCase "none: an anti-join" $ do+ query world.db (do m <- match @Member+ none (matchBy @Purchase @"buyer" m.email)+ pure m.name) @?= ["Ann", "Sam"]++ , testCase "exists: a semi-join, one row however many matches" $ do+ query world.db (do p <- match @Purchase+ exists (matchBy @Member @"email" p.buyer)+ pure p.item) @?= ["book"]+ query world.db (do t <- match @Team+ exists (matchBy @Member @"team" (refOf t))+ pure t.name) @?= ["Engineering", "Sales"]++ , testCase "subqueries see the same db as the outer query" $ do+ db' <- expectRight $ commit_ world.db (insert (Purchase "a@x.io" "pen"))+ let buyers d = query d $ do+ m <- match @Member+ exists (matchBy @Purchase @"buyer" m.email)+ pure m.name+ (buyers world.db, buyers db', buyers (asOf (basisT world.db) db'))+ @?= (["Max"], ["Max", "Ann"], ["Max"])+ ]
+ test/Test.hs view
@@ -0,0 +1,1107 @@+{-# LANGUAGE DataKinds #-}+{-# LANGUAGE DeriveAnyClass #-}+{-# LANGUAGE DeriveGeneric #-}+{-# LANGUAGE DerivingStrategies #-}+{-# LANGUAGE GeneralizedNewtypeDeriving #-}+{-# LANGUAGE OverloadedRecordDot #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE TypeApplications #-}+{-# LANGUAGE TypeFamilies #-}++import Control.Applicative ((<|>))+import Control.Concurrent (forkIO, newEmptyMVar, putMVar, readMVar, takeMVar,+ threadDelay)+import Control.Concurrent.STM (TVar, atomically, check, modifyTVar',+ newTVarIO, readTVar, readTVarIO)+import Control.Exception (ErrorCall (..), evaluate, throwIO, try)+import Control.Monad (forM_, guard, join, replicateM_, void, when)+import qualified Data.ByteString as BS+import Data.List (sort)+import Data.Maybe (isJust)+import Data.Ord (Down (..))+import Data.Set (Set)+import qualified Data.Set as Set+import Data.String (fromString)+import Data.Text (Text)+import Data.Time (Day, UTCTime (..), fromGregorian)+import GHC.Generics (Generic)+import System.Timeout (timeout)++import Test.Tasty+import Test.Tasty.HUnit hiding (assert)++import Datomlite++import Demo (demoTests)+import Helpers+import Shared (sharedTests)++data Department = Department+ { code :: Text+ , deptName :: Text+ } deriving (Generic, Show, Eq)+instance Entity Department where+ type Identity Department = '["code"]++data Skill = Skill+ { skillName :: Text+ } deriving (Generic, Show, Eq)+instance Entity Skill where+ type Identity Skill = '["skillName"]++data Employee = Employee+ { email :: Text+ , name :: Text+ , nick :: Maybe Text+ , dept :: Ref Department+ , skills :: Set (Ref Skill)+ } deriving (Generic, Show, Eq)+instance Entity Employee where+ type Identity Employee = '["email"]++-- Two identities, each unique on its own+data Account = Account+ { handle :: Text+ , mail :: Text+ } deriving (Generic, Show, Eq)+instance Entity Account where+ type Identity Account = '["handle", "mail"]++data Badge = Badge+ { owner :: Text+ , serial :: Maybe Text+ } deriving (Generic, Show, Eq)+instance Entity Badge where+ type Identity Badge = '["serial"]++data Person = Person+ { pname :: Text+ , boss :: Maybe (Ref Person)+ } deriving (Generic, Show, Eq)+instance Entity Person where+ type Identity Person = '["pname"]++-- Two small graphs for closure: roads one way, friendships both ways+data Place = Place { place :: Text } deriving (Generic, Show, Eq)+instance Entity Place where+ type Identity Place = '["place"]++data Road = Road { from :: Ref Place, to :: Ref Place }+ deriving (Generic, Show, Eq, Entity)++data Pal = Pal { pal :: Text } deriving (Generic, Show, Eq)+instance Entity Pal where+ type Identity Pal = '["pal"]++data Friend = Friend { fa :: Ref Pal, fb :: Ref Pal }+ deriving (Generic, Show, Eq, Entity)++data Counter = Counter+ { counter :: Text+ , hits :: Int+ } deriving (Generic, Show, Eq)+instance Entity Counter where+ type Identity Counter = '["counter"]++data Note = Note+ { body :: Maybe Text+ } deriving (Generic, Show, Eq, Entity)++-- Every type of scalar+data Level = Low | High+ deriving stock (Generic, Show, Eq, Ord)+ deriving anyclass (ToValue, FromValue)++newtype Sensor = Sensor Text+ deriving newtype (Show, Eq, Ord, ToValue, FromValue)++data Reading = Reading+ { sensor :: Sensor+ , level :: Level+ , celsius :: Double+ , ticks :: Integer+ , payload :: BS.ByteString+ , takenAt :: UTCTime+ , takenOn :: Day+ , levels :: Set Level+ } deriving (Generic, Show, Eq)+instance Entity Reading where+ type Identity Reading = '["sensor"]++reading :: Reading+reading = Reading+ { sensor = Sensor "s1"+ , level = High+ , celsius = 21.5+ , ticks = 2 ^ (80 :: Int)+ , payload = BS.pack [0, 255, 10]+ , takenAt = UTCTime (fromGregorian 2026 10 13) 3600.25+ , takenOn = fromGregorian 2026 10 13+ , levels = Set.fromList [Low, High]+ }++main :: IO ()+main = defaultMain tests++tests :: TestTree+tests = testGroup "Datomlite"+ [ coreTests+ , schemaTests+ , loadTests+ , valueTests+ , restoreTests+ , updateTests+ , upsertTests+ , txTests+ , timeTests+ , uniqueTests+ , lookupTests+ , writeListTests+ , queryTests+ , ioTests+ , listenTests+ , closureTests+ , windowTests+ , sharedTests+ , demoTests+ ]++coreTests :: TestTree+coreTests = testGroup "Core (EAV log)"+ [ testCase "transact is pure; input db unchanged" $ do+ let db = rawTx [assert e "x" (VInt 1)] emptyDb+ history emptyDb @?= []+ length (history db) @?= 1++ , testCase "asOf hides later transactions" $ do+ let db = rawTx [assert e "b" (VText "two")] (rawTx [assert e "a" (VText "one")] emptyDb)+ valuesOf e "b" (asOf (TxId 1) db) @?= []+ valuesOf e "a" (asOf (TxId 1) db) @?= [VText "one"]++ , testCase "retraction removes a fact" $ do+ let db1 = rawTx [assert e "a" (VText "one")] emptyDb+ db2 = rawTx [retractFact e "a" (VText "one")] db1+ valuesOf e "a" db2 @?= []++ , testCase "who holds a value follows asserts and retracts" $ do+ let (a, b) = (EntityId 1, EntityId 2)+ db1 = rawTx [assert a "k" (VInt 7), assert b "k" (VInt 7)] emptyDb+ db2 = rawTx [retractFact a "k" (VInt 7)] db1+ holdersOf "k" (VInt 7) db1 @?= [a, b]+ holdersOf "k" (VInt 7) db2 @?= [b]+ holdersOf "k" (VInt 7) (asOf (TxId 1) db2) @?= [a, b]++ , testCase "a fact asserted twice is one fact" $ do+ let db1 = rawTx [assert e "a" (VInt 1), assert e "a" (VInt 1)] emptyDb+ db2 = rawTx [retractFact e "a" (VInt 1)] db1+ valuesOf e "a" db1 @?= [VInt 1]+ valuesOf e "a" db2 @?= []++ , testCase "many values keep the order they were asserted in" $ do+ let db1 = rawTx [assert e "a" (VInt 3), assert e "a" (VInt 1)] emptyDb+ db2 = rawTx [assert e "a" (VInt 2)] db1+ valuesOf e "a" db2 @?= [VInt 3, VInt 1, VInt 2]++ , testCase "every matches the type name exactly, not as a prefix" $ do+ let db = rawTx [ assert (EntityId 3) "Dept/code" (VText "D")+ , assert (EntityId 2) "Department/code" (VText "SAL")+ , assert (EntityId 2) "Department/deptName" (VText "Sales")+ , assert (EntityId 1) "Department/code" (VText "ENG")+ , assert (EntityId 1) "Department/deptName" (VText "Engineering")+ , assert (EntityId 4) "Departmental/code" (VText "X")+ ] emptyDb+ map (refId . refOf) (every @Department db) @?= [EntityId 1, EntityId 2]+ ]+ where+ e = EntityId 1++schemaTests :: TestTree+schemaTests = testGroup "Schema (records are the schema)"+ [ testCase "insert then load round-trips a record" $ do+ let d = Department "ENG" "Engineering"+ (dRef, db) <- expectRight $ commit emptyDb (insert d)+ loadR dRef db @?= Just d++ , testCase "each Identity field is unique on its own, and there are none by default" $ do+ db <- expectRight $ commit_ emptyDb [Insert (Account "max" "m@x.io")]+ case commit_ db [Insert (Account "maxi" "m@x.io")] of+ Left (UniqueViolation a _ _) -> a @?= "Account/mail"+ other -> assertFailure (show (fmap basisT other))+ notes <- expectRight $ commit_ emptyDb [Insert (Note (Just "hi")), Insert (Note (Just "hi"))]+ length (every @Note notes) @?= 2++ , testCase "retract removes every fact of an entity" $ do+ (dRef, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ db2 <- expectRight $ commit_ db1 (retract dRef)+ loadR dRef db2 @?= Nothing+ length (every @Department db2) @?= 0+ assertBool "history retains the retracted facts" (not (null (history db2)))++ , testCase "attribute names are Type/field prefixed" $ do+ let d = Department "ENG" "Engineering"+ db <- expectRight $ commit_ emptyDb [Insert d]+ sort (map dAttr (datoms db)) @?= ["Department/code", "Department/deptName"]++ , testCase "Tx do-block: tempid ref used in a later entity" $ do+ let txn = do+ eng <- insert (Department "ENG" "Engineering")+ emp <- insert (Employee "m@x.io" "Max" (Just "mx") eng mempty)+ pure (eng, emp)+ ((engRef, empRef), db) <- expectRight $ commit emptyDb txn+ (dept <$> loadR empRef db) @?= Just engRef+ (name <$> loadR empRef db) @?= Just "Max"++ , testCase "Maybe field: Nothing writes no datom" $ do+ (dRef, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ let emp = Employee "a@x.io" "Ann" Nothing dRef mempty+ (eRef, db2) <- expectRight $ commit db1 (insert emp)+ loadR eRef db2 @?= Just emp++ , testCase "cardinality-many round-trips" $ do+ (dRef, dbA) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ (sRef, dbB) <- expectRight $ commit dbA (insert (Skill "haskell"))+ let emp = Employee "m@x.io" "Max" (Just "mx") dRef (Set.singleton sRef)+ (eRef, dbC) <- expectRight $ commit dbB (insert emp)+ (skills <$> loadR eRef dbC) @?= Just (Set.singleton sRef)++ , testCase "Maybe (Ref t): an optional reference round-trips" $ do+ ((ann, bob), db) <- expectRight $ commit emptyDb $ do+ ann <- insert (Person "ann" Nothing)+ bob <- insert (Person "bob" (Just ann))+ pure (ann, bob)+ loadR ann db @?= Just (Person "ann" Nothing)+ loadR bob db @?= Just (Person "bob" (Just ann))+ query db (do p <- match @Person; b <- follow =<< oneOf p.boss; pure (p.pname, b.pname))+ @?= [("bob", "ann")]++ , testCase "every pairs each record with its Ref" $ do+ ([eng, sal], db) <- expectRight $ commit emptyDb $ traverse insert+ [ Department "ENG" "Engineering", Department "SAL" "Sales" ]+ map refOf (every @Department db) @?= [eng, sal]+ ]++loadTests :: TestTree+loadTests = testGroup "Reading back (load)"+ [ testCase "a record that writes no datoms leaves nothing to load" $ do+ (n, db) <- expectRight $ commit emptyDb (insert (Note Nothing))+ loadR n db @?= Nothing+ every @Note db @?= []++ , testCase "a Ref only loads facts of its own type" $ do+ (eng, db) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ Just asNote <- pure (fromValue (VRef (refId eng)) :: Maybe (Ref Note))+ loadR asNote db @?= Nothing+ db2 <- expectRight $ commit_ db (retract asNote)+ loadR eng db2 @?= Just (Department "ENG" "Engineering")++ , testCase "a required field added later throws MissingField" $ do+ let db = rawTx [assert (EntityId 1) "Department/code" (VText "ENG")] emptyDb+ r <- try (evaluate (length (every @Department db)))+ r @?= Left (MissingField "Department/deptName" (EntityId 1))++ , testCase "a Maybe or Set field added later reads as empty" $ do+ let db = rawTx [ assert (EntityId 1) "Department/code" (VText "ENG")+ , assert (EntityId 1) "Department/deptName" (VText "Engineering")+ , assert (EntityId 2) "Employee/email" (VText "m@x.io")+ , assert (EntityId 2) "Employee/name" (VText "Max")+ , assert (EntityId 2) "Employee/dept" (VRef (EntityId 1))+ ] emptyDb+ Just eng <- pure (find @Department "ENG" db)+ map recordOf (every @Employee db) @?= [Employee "m@x.io" "Max" Nothing (refOf eng) mempty]++ , testCase "a field whose type changed throws BadValue" $ do+ let db = rawTx [ assert (EntityId 1) "Department/code" (VInt 7)+ , assert (EntityId 1) "Department/deptName" (VText "Eng")+ ] emptyDb+ r <- try (evaluate (length (every @Department db)))+ r @?= Left (BadValue "Department/code" [VInt 7] (EntityId 1))++ , testCase "a since view skips entities only partly inside it" $ do+ (eng, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ db2 <- expectRight $ commit_ db1 $ do+ update eng (\d -> d { deptName = "Platform" })+ insert (Department "SAL" "Sales")+ map recordOf (every @Department (since (basisT db1) db2)) @?= [Department "SAL" "Sales"]++ , testCase "a since view can't be committed to" $ do+ db <- expectRight $ commit_ emptyDb (insert (Department "ENG" "Engineering"))+ fmap basisT (commit_ (since (TxId 0) db) [Upsert (Department "ENG" "Eng")]) @?= Left SinceView+ ]++valueTests :: TestTree+valueTests = testGroup "Value types"+ [ testCase "every scalar kind round-trips" $ do+ (r, db) <- expectRight $ commit emptyDb (insert reading)+ loadR r db @?= Just reading++ , testCase "an enum is stored as its constructor's name, and matches by value" $ do+ (r, db) <- expectRight $ commit emptyDb (insert reading)+ valuesOf (refId r) "Reading/level" db @?= [VText "High"]+ map refOf (query db (matchBy @Reading @"level" High)) @?= [r]+ map refOf (query db (matchBy @Reading @"levels" Low)) @?= [r]+ map refOf (query db (matchBy @Reading @"level" Low)) @?= []++ , testCase "an enum constructor that no longer exists throws BadValue" $ do+ (r, db1) <- expectRight $ commit emptyDb (insert reading)+ let db2 = rawTx [ retractFact (refId r) "Reading/level" (VText "High")+ , assert (refId r) "Reading/level" (VText "Medium")+ ] db1+ res <- try (evaluate (loadR r db2))+ res @?= Left (BadValue "Reading/level" [VText "Medium"] (refId r))++ , testCase "a NaN can be stored, found, and replaced" $ do+ let nan = 0 / 0 :: Double+ (r, db1) <- expectRight $ commit emptyDb (insert reading { celsius = nan })+ fmap (isNaN . celsius) (loadR r db1) @?= Just True+ map refOf (query db1 (matchBy @Reading @"celsius" nan)) @?= [r]+ db2 <- expectRight $ commit_ db1 (update r (\x -> x { celsius = 1.5 }))+ fmap celsius (loadR r db2) @?= Just 1.5+ map refOf (query db2 (matchBy @Reading @"celsius" nan)) @?= []++ , testCase "a time with a bottom inside fails its commit" $ do+ let bad = reading { takenAt = UTCTime (fromGregorian 2026 10 13) (error "boom") }+ expectBoom (evaluate (commit_ emptyDb (insert bad)))+ ]++restoreTests :: TestTree+restoreTests = testGroup "Restoring (fromHistory)"+ [ testCase "fromHistory . history gives back the same db" $ do+ fromHistory (history fixture) @?= fixture+ db <- expectRight $ commit_ fixture $ do+ m : _ <- every @Employee <$> txDb+ update (refOf m) (\e -> e { name = "Maximilian" })+ fromHistory (history db) @?= db+ basisT (fromHistory (history db)) @?= basisT db++ , testCase "a datom per line survives show and read" $ do+ db <- expectRight $ commit_ emptyDb (insert reading)+ let file = unlines (map show (history db))+ fromHistory (map read (lines file)) @?= db++ , testCase "a restored db keeps its past" $ do+ db1 <- expectRight $ commit_ fixture (retract (ref @Employee "m@x.io"))+ let restored = fromHistory (history db1)+ every @Employee restored @?= []+ every @Employee (asOf (basisT fixture) restored) @?= every @Employee fixture++ , testCase "inserts after a restore never reuse an id the log mentions" $ do+ -- entity 9 only appears as a ref target+ let db = rawTx [ assert (EntityId 1) "Person/pname" (VText "ann")+ , assert (EntityId 1) "Person/boss" (VRef (EntityId 9))+ ] emptyDb+ (bob, db') <- expectRight $ commit (fromHistory (history db)) (insert (Person "bob" Nothing))+ refId bob @?= EntityId 10+ basisT db' @?= TxId 2++ , testCase "datoms out of order are replayed in tx order" $ do+ db <- expectRight $ commit_ fixture $+ update (ref @Department "ENG") (setField @"deptName" "Platform")+ every @Department (fromHistory (reverse (history db))) @?= every @Department db+ ]++updateTests :: TestTree+updateTests = testGroup "update (record-update syntax)"+ [ testCase "replaces a cardinality-one field rather than adding to it" $ do+ (mx, db1) <- expectRight $ commit emptyDb $ do+ eng <- insert (Department "ENG" "Engineering")+ insert (Employee "m@x.io" "Max" Nothing eng mempty)+ db2 <- expectRight $ commit_ db1 (update mx (\e -> e { name = "Maximilian" }))+ (name <$> loadR mx db2) @?= Just "Maximilian"+ valuesOf (refId mx) "Employee/name" db2 @?= [VText "Maximilian"]+ (name <$> loadR mx db1) @?= Just "Max"++ , testCase "Maybe and Set fields: values come and go" $ do+ ((mx, hs), db1) <- expectRight $ commit emptyDb $ do+ eng <- insert (Department "ENG" "Engineering")+ hs <- insert (Skill "haskell")+ mx <- insert (Employee "m@x.io" "Max" (Just "mx") eng (Set.singleton hs))+ pure (mx, hs)+ (sc, db2) <- expectRight $ commit db1 (insert (Skill "scala"))+ db3 <- expectRight $ commit_ db2 $+ update mx (\e -> e { nick = Nothing, skills = Set.singleton sc })+ (nick <$> loadR mx db3) @?= Just Nothing+ (skills <$> loadR mx db3) @?= Just (Set.singleton sc)+ assertBool "haskell skill no longer listed" (hs `notElem` maybe mempty skills (loadR mx db3))++ , testCase "sees an entity created earlier in the same Tx" $ do+ (eng, db) <- expectRight $ commit emptyDb $ do+ eng <- insert (Department "ENG" "Engineering")+ update eng (\d -> d { deptName = "Platform" })+ pure eng+ (deptName <$> loadR eng db) @?= Just "Platform"++ , testCase "changing an identity to one already taken is rejected" $ do+ ([_, sal], db) <- expectRight $ commit emptyDb $ traverse insert+ [ Department "ENG" "Engineering", Department "SAL" "Sales" ]+ commit_ db (update sal (\d -> d { code = "ENG" }))+ @?= Left (UniqueViolation "Department/code" (VText "ENG") [EntityId 1, EntityId 2])++ , testCase "updating a retracted entity fails" $ do+ (eng, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ db2 <- expectRight $ commit_ db1 (retract eng)+ commit_ db2 (update eng id) @?= Left (UnknownEntity (refId eng))+ ]++upsertTests :: TestTree+upsertTests = testGroup "upsert (by Identity)"+ [ testCase "inserts when no entity holds the identity" $ do+ (eng, db) <- expectRight $ commit emptyDb (upsert (Department "ENG" "Engineering"))+ loadR eng db @?= Just (Department "ENG" "Engineering")++ , testCase "updates the entity holding the identity; refs to it survive" $ do+ ((eng, mx), db1) <- expectRight $ commit emptyDb $ do+ eng <- insert (Department "ENG" "Engineering")+ mx <- insert (Employee "m@x.io" "Max" Nothing eng mempty)+ pure (eng, mx)+ (eng', db2) <- expectRight $ commit db1 (upsert (Department "ENG" "Platform"))+ eng' @?= eng+ (deptName <$> loadR eng db2) @?= Just "Platform"+ length (every @Department db2) @?= 1+ valuesOf (refId eng) "Department/deptName" db2 @?= [VText "Platform"]+ query db2 (do e <- follow mx; d <- follow e.dept; pure d.deptName) @?= ["Platform"]++ , testCase "saving an unchanged record writes nothing" $ do+ (_, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ db2 <- expectRight $ commit_ db1 (upsert (Department "ENG" "Engineering"))+ history db2 @?= history db1++ , testCase "sees an entity created earlier in the same Tx" $ do+ ((a, b), db) <- expectRight $ commit emptyDb $ do+ a <- upsert (Department "ENG" "Engineering")+ b <- upsert (Department "ENG" "Platform")+ pure (a, b)+ a @?= b+ map recordOf (every db) @?= [Department "ENG" "Platform"]++ , testCase "identities held by two different entities are rejected" $ do+ (_, db1) <- expectRight $ commit emptyDb $ traverse insert+ [ Account "max" "m@x.io", Account "sam" "s@x.io" ]+ commit_ db1 (upsert (Account "max" "s@x.io"))+ @?= Left (UniqueViolation "Account/mail" (VText "s@x.io") [EntityId 1, EntityId 2])++ , testCase "works over a Conn" $ do+ conn <- connect emptyDb+ (eng, _) <- expectRight =<< transact conn (upsert (Department "ENG" "Engineering"))+ (eng', db) <- expectRight =<< transact conn (upsert (Department "ENG" "Platform"))+ eng' @?= eng+ map recordOf (every db) @?= [Department "ENG" "Platform"]+ ]++txTests :: TestTree+txTests = testGroup "Tx (txDb, abort)"+ [ testCase "txDb sees the transaction's own writes" $ do+ (counts, db) <- expectRight $ commit emptyDb $ do+ let departments = length . every @Department <$> txDb+ n0 <- departments+ insert_ (Department "ENG" "Engineering")+ n1 <- departments+ pure (n0, n1)+ counts @?= (0, 1)+ length (every @Department db) @?= 1++ , testCase "abort fails the commit and writes nothing" $ do+ let txn = do+ _ <- insert (Department "ENG" "Engineering")+ abort "changed my mind" :: Tx ()+ commit_ emptyDb txn @?= Left (Aborted "changed my mind")++ , testCase "read-modify-write: a failed pattern aborts" $ do+ (eng, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ db2 <- expectRight $ commit_ db1 (retract eng)+ let rename = do+ Just d <- loadR eng <$> txDb+ update eng (const d { deptName = d.deptName <> " (renamed)" })+ db3 <- expectRight $ commit_ db1 rename+ (deptName <$> loadR eng db3) @?= Just "Engineering (renamed)"+ case commit_ db2 rename of+ Left (Aborted _) -> pure ()+ other -> assertFailure (show other)+ ]++timeTests :: TestTree+timeTests = testGroup "Time travel (basisT, asOf)"+ [ testCase "each commit advances basisT" $ do+ (_, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ db2 <- expectRight $ commit_ db1 []+ assertBool "basisT increases" (basisT emptyDb < basisT db1 && basisT db1 < basisT db2)++ , testCase "asOf (basisT db) brings back that value" $ do+ (eng, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ let t = basisT db1+ db2 <- expectRight $ commit_ db1 (update eng (\d -> d { deptName = "Platform" }))+ (deptName <$> loadR eng (asOf t db2)) @?= Just "Engineering"+ (deptName <$> loadR eng db2) @?= Just "Platform"+ basisT (asOf t db2) @?= t++ , testCase "commitAt stamps the tx and asOfTime rewinds to it" $ do+ (eng, db1) <- expectRight $ commitAt (at 9) emptyDb (insert (Department "ENG" "Engineering"))+ (_, db2) <- expectRight $ commitAt (at 12) db1 (update eng (\d -> d { deptName = "Platform" }))+ txTime (basisT db1) db2 @?= Just (at 9)+ txTime (basisT db2) db2 @?= Just (at 12)+ (deptName <$> loadR eng (asOfTime (at 10) db2)) @?= Just "Engineering"+ (deptName <$> loadR eng (asOfTime (at 12) db2)) @?= Just "Platform"+ loadR eng (asOfTime (at 8) db2) @?= Nothing++ , testCase "an unstamped commit goes with the stamp before it" $ do+ (_, db1) <- expectRight $ commitAt (at 9) emptyDb (insert (Skill "one"))+ db2 <- expectRight $ commit_ db1 (insert (Skill "two"))+ (_, db3) <- expectRight $ commitAt (at 12) db2 (insert (Skill "three"))+ txTime (basisT db2) db3 @?= Nothing+ map (skillName . recordOf) (every (asOfTime (at 10) db3)) @?= ["one", "two"]++ , testCase "tx times never go backwards" $ do+ (_, db1) <- expectRight $ commitAt (at 12) emptyDb []+ (_, db2) <- expectRight $ commitAt (at 9) db1 []+ txTime (basisT db2) db2 @?= Just (at 12)++ , testCase "tx times survive saving and restoring the log" $ do+ (_, db1) <- expectRight $ commitAt (at 9) emptyDb (insert (Skill "one"))+ let db' = fromHistory (map (read . show) (history db1))+ txTime (basisT db1) db' @?= Just (at 9)+ datoms db' @?= datoms db1+ ]+ where+ at h = UTCTime (fromGregorian 2026 10 13) (h * 3600)++uniqueTests :: TestTree+uniqueTests = testGroup "Uniqueness (Identity)"+ [ testCase "duplicate identity vs existing db is rejected" $ do+ (_, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ commit db1 (insert (Department "ENG" "Engineering (dup)"))+ @?= Left (UniqueViolation "Department/code" (VText "ENG") [EntityId 1, EntityId 2])++ , testCase "distinct identities are fine" $ do+ (refs, _) <- expectRight $ commit emptyDb $ traverse insert+ [ Department "ENG" "Engineering", Department "SAL" "Sales" ]+ length refs @?= 2++ , testCase "duplicate identities within one transaction are rejected" $ do+ let txn = do+ _ <- insert (Department "ENG" "Engineering")+ insert (Department "ENG" "Engineering again")+ commit_ emptyDb txn+ @?= Left (UniqueViolation "Department/code" (VText "ENG") [EntityId 1, EntityId 2])++ , testCase "failed transaction writes nothing" $ do+ (_, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ let bad = do+ _ <- insert (Skill "haskell")+ insert (Department "ENG" "dup")+ commit_ db1 bad+ @?= Left (UniqueViolation "Department/code" (VText "ENG") [EntityId 1, EntityId 3])+ length (every @Skill db1) @?= 0++ , testCase "an identity can be retracted and reused in one transaction" $ do+ (old, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ (new', db2) <- expectRight $ commit db1 $ do+ retract old+ insert (Department "ENG" "Engineering, reborn")+ (deptName <$> loadR new' db2) @?= Just "Engineering, reborn"+ loadR old db2 @?= Nothing++ , testCase "two entities can swap identities in one transaction" $ do+ ([eng, sal], db1) <- expectRight $ commit emptyDb $ traverse insert+ [ Department "ENG" "Engineering", Department "SAL" "Sales" ]+ db2 <- expectRight $ commit_ db1 $ do+ update eng (setField @"code" "SAL")+ update sal (setField @"code" "ENG")+ refOf <$> find @Department "ENG" db2 @?= Just sal+ refOf <$> find @Department "SAL" db2 @?= Just eng++ , testCase "each identity is unique on its own" $ do+ (_, db1) <- expectRight $ commit emptyDb (insert (Account "max" "m@x.io"))+ commit_ db1 (insert (Account "max" "other@x.io"))+ @?= Left (UniqueViolation "Account/handle" (VText "max") [EntityId 1, EntityId 2])+ commit_ db1 (insert (Account "other" "m@x.io"))+ @?= Left (UniqueViolation "Account/mail" (VText "m@x.io") [EntityId 1, EntityId 2])++ , testCase "an optional identity is unique only when set" $ do+ (_, db1) <- expectRight $ commit emptyDb $ traverse insert+ [ Badge "max" Nothing, Badge "sam" Nothing, Badge "ann" (Just "B-1") ]+ length (every @Badge db1) @?= 3+ commit_ db1 (insert (Badge "eve" (Just "B-1")))+ @?= Left (UniqueViolation "Badge/serial" (VText "B-1") [EntityId 3, EntityId 4])+ db2 <- expectRight $ commit_ db1 (upsert (Badge "eve" (Just "B-1")))+ map (owner . recordOf) (every @Badge db2) @?= ["max", "sam", "eve"]+ db3 <- expectRight $ commit_ db1 (upsert (Badge "eve" Nothing))+ length (every @Badge db3) @?= 4+ ]++lookupTests :: TestTree+lookupTests = testGroup "Reads and lookups (Stored, every, find, ref)"+ [ testCase "load and every hand back the record with its ref" $ do+ ([eng, sal], db) <- expectRight $ commit emptyDb $ traverse insert+ [ Department "ENG" "Engineering", Department "SAL" "Sales" ]+ Just d <- pure (load eng db)+ (refOf d, d.deptName, recordOf d) @?= (eng, "Engineering", Department "ENG" "Engineering")+ [ (refOf x, x.code) | x <- every @Department db ] @?= [(eng, "ENG"), (sal, "SAL")]++ , testCase "find goes by the Identity" $ do+ (eng, db) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ refOf <$> find @Department "ENG" db @?= Just eng+ find @Department "NOPE" db @?= Nothing++ , testCase "findBy says which Identity" $ do+ (mx, db) <- expectRight $ commit emptyDb (insert (Account "max" "m@x.io"))+ refOf <$> findBy @Account @"mail" "m@x.io" db @?= Just mx+ refOf <$> findBy @Account @"handle" "max" db @?= Just mx+ findBy @Account @"handle" "m@x.io" db @?= Nothing++ , testCase "refBy says which Identity" $ do+ (mx, db1) <- expectRight $ commit emptyDb (insert (Account "max" "m@x.io"))+ refOf <$> load (refBy @Account @"mail" "m@x.io") db1 @?= Just mx+ db2 <- expectRight $ commit_ db1 $+ update (refBy @Account @"handle" "max") (setField @"mail" "max@x.io")+ (.mail) <$> load mx db2 @?= Just "max@x.io"+ commit_ db2 (retract (refBy @Account @"mail" "m@x.io"))+ @?= Left (UnknownIdentity "Account/mail" (VText "m@x.io"))++ , testCase "an optional identity is found by the value inside" $ do+ (b, db) <- expectRight $ commit emptyDb (insert (Badge "ann" (Just "B-1")))+ refOf <$> find @Badge "B-1" db @?= Just b++ , testCase "a ref in a record finds an entity written earlier in the same Tx" $ do+ db <- expectRight $ commit_ emptyDb $ do+ upsert_ (Department "ENG" "Engineering")+ upsert_ (Skill "haskell")+ upsert_ (Employee "m@x.io" "Max" Nothing (ref @Department "ENG")+ (Set.singleton (ref @Skill "haskell")))+ query db (do e <- match @Employee+ d <- follow e.dept+ s <- follow =<< oneOf e.skills+ pure (e.name, d.code, s.skillName))+ @?= [("Max", "ENG", "haskell")]+ -- stored as the entity's id, not as the lookup+ Just eng <- pure (find @Department "ENG" db)+ ((.dept) <$> find @Employee "m@x.io" db) @?= Just (refOf eng)++ , testCase "a ref nothing holds fails the commit" $ do+ let noEng = Left (UnknownIdentity "Department/code" (VText "ENG"))+ commit_ emptyDb (insert (Employee "m@x.io" "Max" Nothing (ref @Department "ENG") mempty))+ @?= noEng+ commit_ emptyDb (update (ref @Department "ENG") id) @?= noEng+ commit_ emptyDb (retract (ref @Department "ENG")) @?= noEng++ , testCase "load, follow, matchBy, update and retract take a ref" $ do+ let db = fixture+ Just eng <- pure (find @Department "ENG" db)+ (refOf <$> load (ref @Department "ENG") db) @?= Just (refOf eng)+ query db (do d <- follow (ref @Department "ENG"); pure d.deptName) @?= ["Engineering"]+ query db (do e <- matchBy @Employee @"dept" (ref @Department "ENG"); pure e.email)+ @?= ["m@x.io"]+ query db (do e <- matchBy @Employee @"dept" (ref @Department "NOPE"); pure e.email)+ @?= []+ db2 <- expectRight $ commit_ db $+ update (ref @Department "ENG") (setField @"deptName" "Platform")+ ((.deptName) <$> find @Department "ENG" db2) @?= Just "Platform"+ db3 <- expectRight $ commit_ db (retract (ref @Employee "m@x.io"))+ find @Employee "m@x.io" db3 @?= Nothing++ , testCase "an id and a ref to one entity in a Set store it once" $ do+ ((hs, mx), db) <- expectRight $ commit emptyDb $ do+ hs <- insert (Skill "haskell")+ d <- insert (Department "ENG" "Engineering")+ mx <- insert (Employee "m@x.io" "Max" Nothing d (Set.fromList [hs, ref @Skill "haskell"]))+ pure (hs, mx)+ ((.skills) <$> load mx db) @?= Just (Set.singleton hs)+ length (valuesOf (refId mx) "Employee/skills" db) @?= 1+ ]++writeListTests :: TestTree+writeListTests = testGroup "Lists of writes (Insert, Upsert, Update, Delete)"+ [ testCase "a list commits in order, each write seeing the ones before" $ do+ db <- expectRight $ commit_ emptyDb+ [ Upsert (Department "ENG" "Engineering")+ , Upsert (Skill "haskell")+ , Insert (Employee "m@x.io" "Max" Nothing (ref @Department "ENG")+ (Set.singleton (ref @Skill "haskell")))+ , Upsert (Department "ENG" "Platform")+ ]+ query db (do e <- match @Employee; d <- follow e.dept; pure (e.name, d.deptName))+ @?= [("Max", "Platform")]+ basisT db @?= TxId 1++ , testCase "Update and Delete take refs" $ do+ db <- expectRight $ commit_ fixture+ [ Update (ref @Employee "m@x.io") (setField @"name" "Maximilian")+ , Delete (ref @Skill "haskell")+ ]+ (.name) <$> find @Employee "m@x.io" db @?= Just "Maximilian"+ find @Skill "haskell" db @?= Nothing++ , testCase "Insert is strict about identities, Upsert isn't" $ do+ commit_ fixture [Insert (Department "ENG" "dup")]+ @?= Left (UniqueViolation "Department/code" (VText "ENG") [EntityId 1, EntityId 4])+ db <- expectRight $ commit_ fixture [Upsert (Department "ENG" "Platform")]+ length (every @Department db) @?= 1++ , testCase "a failing write fails the whole list" $ do+ commit_ fixture+ [ Upsert (Skill "scala")+ , Delete (ref @Department "NOPE")+ ] @?= Left (UnknownIdentity "Department/code" (VText "NOPE"))+ commit_ fixture [] @?= commit_ fixture (pure () :: Tx ())++ , testCase "transact takes a list too" $ do+ conn <- connect emptyDb+ ((), db) <- expectRight =<< transact conn [Upsert (Department "ENG" "Engineering")]+ (.deptName) <$> find @Department "ENG" db @?= Just "Engineering"+ ]++queryTests :: TestTree+queryTests = testGroup "Query (do-blocks over records)"+ [ testCase "join by following a ref" $ do+ let result = query fixture $ do+ e <- match @Employee+ d <- follow e.dept+ guard (d.deptName == "Engineering")+ pure (e.email, d.deptName)+ result @?= [("m@x.io", "Engineering")]++ , testCase "join with match + guard against ref" $ do+ let result = query fixture $ do+ d <- match @Department+ e <- match @Employee+ guard (e.dept == refOf d)+ pure (d.code, e.name)+ result @?= [("ENG", "Max")]++ , testCase "oneOf ranges over a cardinality-many field" $ do+ let result = query fixture $ do+ e <- match @Employee+ s <- follow =<< oneOf e.skills+ pure (e.email, s.skillName)+ result @?= [("m@x.io", "haskell")]++ , testCase "literal filter narrows results" $ do+ let result = query fixture $ do+ e <- match @Employee+ guard (e.name == "Max" && e.nick == Just "mx")+ pure e.email+ result @?= ["m@x.io"]++ , testCase "absent Maybe drops the row (oneOf, or a failed pattern)" $ do+ (dRef, db1) <- expectRight $ commit emptyDb (insert (Department "ENG" "Engineering"))+ (_, db2) <- expectRight $ commit db1 $ traverse insert+ [ Employee "m@x.io" "Max" (Just "mx") dRef mempty+ , Employee "a@x.io" "Ann" Nothing dRef mempty ]+ query db2 (do e <- match @Employee; oneOf e.nick) @?= ["mx"]+ query db2 (do e <- match @Employee; Just n <- pure e.nick; pure n) @?= ["mx"]++ , testCase "compare a ref field to a Ref held outside the query" $ do+ ((eng, sal), db) <- expectRight $ commit emptyDb $ do+ eng <- insert (Department "ENG" "Engineering")+ sal <- insert (Department "SAL" "Sales")+ _ <- insert (Employee "m@x.io" "Max" Nothing eng mempty)+ _ <- insert (Employee "s@x.io" "Sam" Nothing sal mempty)+ pure (eng, sal)+ let inDept r = query db $ do+ e <- match @Employee+ guard (e.dept == r)+ pure e.name+ (inDept eng, inDept sal) @?= (["Max"], ["Sam"])++ , testCase "return whole records and refs" $ do+ let result = query fixture $ do+ d <- match @Department+ pure (refOf d, recordOf d)+ map snd result @?= [Department "ENG" "Engineering"]+ map fst result @?= map refOf (every @Department fixture)++ , testCase "querying an older db value time-travels" $ do+ [mx] <- pure (map refOf (every @Employee fixture))+ db2 <- expectRight $ commit_ fixture (update mx (\e -> e { name = "Maximilian" }))+ let names db = query db (do e <- match @Employee; pure e.name)+ (names fixture, names db2) @?= (["Max"], ["Maximilian"])+ ]++ioTests :: TestTree+ioTests = testGroup "IO edge (Conn + transact)"+ [ testCase "transact commits a Tx and returns its result and new db" $ do+ conn <- connect emptyDb+ let hire = do+ eng <- insert (Department "ENG" "Engineering")+ insert (Employee "m@x.io" "Max" Nothing eng mempty)+ (empRef, db) <- expectRight =<< transact conn hire+ (name <$> loadR empRef db) @?= Just "Max"+ now <- snapshot conn+ now @?= db++ , testCase "transact's db is its own commit's, whatever came after" $ do+ conn <- connect emptyDb+ (_, db1) <- expectRight =<< transact conn (insert (Skill "one"))+ (_, db2) <- expectRight =<< transact conn (insert (Skill "two"))+ map (skillName . recordOf) (every db1) @?= ["one"]+ map (skillName . recordOf) (every db2) @?= ["one", "two"]+ now <- snapshot conn+ now @?= db2++ , testCase "transact enforces Identity uniqueness and writes nothing on clash" $ do+ conn <- connect emptyDb+ _ <- transact conn (insert (Department "ENG" "Engineering"))+ bad <- transact conn (insert (Department "ENG" "dup"))+ bad @?= Left (UniqueViolation "Department/code" (VText "ENG") [EntityId 1, EntityId 2])+ db <- snapshot conn+ length (every @Department db) @?= 1++ , testCase "concurrent read-modify-writes never lose an update" $ do+ conn <- connect emptyDb+ (c, _) <- expectRight =<< transact conn (insert (Counter "c" 0))+ done <- newEmptyMVar+ forM_ [1 .. 50 :: Int] $ \_ -> forkIO $ do+ _ <- transact conn $ do+ Just now <- load c <$> txDb+ update c (setField @"hits" (now.hits + 1))+ putMVar done ()+ replicateM_ 50 (takeMVar done)+ db <- snapshot conn+ (.hits) <$> load c db @?= Just 50++ , testCase "commit is strict: a bottom value fails the commit, not a later read" $+ expectBoom (evaluate (commit_ emptyDb (insert (Department "ENG" (error "boom")))))++ , testCase "a transact that throws leaves the Conn untouched" $ do+ conn <- connect emptyDb+ expectBoom (transact conn (insert (Department "ENG" (error "boom"))))+ expectBoom (transact conn (txDb >> error "boom" :: Tx ()))+ _ <- expectRight =<< transact conn (insert (Department "SAL" "Sales"))+ db <- snapshot conn+ basisT db @?= TxId 1+ map (deptName . recordOf) (every @Department db) @?= ["Sales"]+ ]++listenTests :: TestTree+listenTests = testGroup "Listen and watch"+ [ testCase "listen sees each commit from now on, in tx order, with its datoms" $ do+ conn <- connect emptyDb+ _ <- transact conn (insert (Skill "before"))+ (seen, rec) <- recorder+ _ <- listen conn rec+ _ <- transact conn (insert (Department "ENG" "Engineering"))+ _ <- transact conn []+ rs <- waitFor seen ((== 2) . length)+ map trTxId rs @?= [TxId 2, TxId 3]+ map (sort . map dAttr . trDatoms) rs+ @?= [["Department/code", "Department/deptName", "db/txInstant"], ["db/txInstant"]]+ assertBool "every tx is stamped" (all (isJust . trTime) rs)++ , testCase "concurrent commits reach a listener once each, in tx order" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ _ <- listen conn rec+ forM_ [1 .. 50 :: Int] $ \i ->+ forkIO $ void $ transact conn (insert (Skill (fromString (show i))))+ rs <- waitFor seen ((== 50) . length)+ map trTxId rs @?= map TxId [1 .. 50]++ , testCase "unsubscribing stops delivery" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ stop <- listen conn rec+ _ <- transact conn (insert (Skill "one"))+ _ <- waitFor seen ((== 1) . length)+ stop >> stop+ _ <- transact conn (insert (Skill "two"))+ threadDelay 50000+ length <$> readTVarIO seen >>= (@?= 1)++ , testCase "a listener that throws never fails the commit, and keeps listening" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ _ <- listen conn $ \r -> do+ rec r+ when (trTxId r == TxId 1) (throwIO (userError "expected in test"))+ _ <- expectRight =<< transact conn (insert (Skill "one"))+ _ <- transact conn (insert (Skill "two"))+ map trTxId <$> waitFor seen ((== 2) . length) >>= (@?= [TxId 1, TxId 2])++ , testCase "a listener can commit" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ _ <- listen conn $ \r -> do+ rec r+ when (trTxId r == TxId 1) (void (transact conn (insert (Skill "audit"))))+ _ <- transact conn (insert (Department "ENG" "Engineering"))+ _ <- waitFor seen ((== 2) . length)+ db <- snapshot conn+ map (skillName . recordOf) (every db) @?= ["audit"]++ , testCase "watch fires up front, then only when the result changes" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ _ <- watch conn (length . every @Department) rec+ _ <- waitFor seen (== [0])+ _ <- transact conn (insert (Skill "haskell"))+ _ <- transact conn (insert (Department "ENG" "Engineering"))+ _ <- waitFor seen ((== Just 1) . lastMay)+ (eng, _) <- expectRight =<< transact conn (upsert (Department "ENG" "Platform"))+ _ <- transact conn (retract eng)+ waitFor seen ((== Just 0) . lastMay) >>= (@?= [0, 1, 0])++ , testCase "a watch whose query throws keeps watching" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ _ <- watch conn (\db -> let n = length (every @Skill db)+ in if n == 1 then error "expected in test" else n) rec+ _ <- transact conn (insert (Skill "one"))+ _ <- transact conn (insert (Skill "two"))+ waitFor seen ((== Just 2) . lastMay) >>= (@?= [0, 2])++ , testCase "stopping a watch stops it" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ stop <- watch conn (length . every @Skill) rec+ _ <- waitFor seen (== [0])+ stop+ _ <- transact conn (insert (Skill "one"))+ threadDelay 50000+ readTVarIO seen >>= (@?= [0])++ , testCase "a listener can stop itself" $ do+ conn <- connect emptyDb+ (seen, rec) <- recorder+ stopVar <- newEmptyMVar+ stop <- listen conn (\r -> rec r >> join (readMVar stopVar))+ putMVar stopVar stop+ _ <- transact conn (insert (Skill "one"))+ _ <- waitFor seen ((== 1) . length)+ _ <- transact conn (insert (Skill "two"))+ threadDelay 50000+ map trTxId <$> readTVarIO seen >>= (@?= [TxId 1])++ , testCase "awaitAfter blocks until a newer commit" $ do+ conn <- connect emptyDb+ t <- basisT <$> snapshot conn+ _ <- forkIO (threadDelay 10000 >> void (transact conn (insert (Skill "late"))))+ db <- atomically (awaitAfter conn t)+ map (skillName . recordOf) (every db) @?= ["late"]+ ]+ where+ lastMay xs = if null xs then Nothing else Just (last xs)++closureTests :: TestTree+closureTests = testGroup "closure (recursion on cycles)"+ [ testCase "roads: a directed graph with a cycle" $ do+ let next p = do+ r <- matchBy @Road @"from" (refOf p)+ follow r.to+ from' c = sort $ query roads $ do+ t <- closure next =<< matchBy @Place @"place" c+ pure t.place+ from' "PAR" @?= ["BOR", "LYO", "MAR", "NCE", "PAR"]+ from' "NCE" @?= []+ from' "MAR" @?= ["BOR", "LYO", "MAR", "NCE", "PAR"]++ , testCase "friends: an undirected graph, two components" $ do+ let knows x = (matchBy @Friend @"fa" (refOf x) >>= \f -> follow f.fb)+ <|> (matchBy @Friend @"fb" (refOf x) >>= \f -> follow f.fa)+ cluster h = sort $ query friends $ do+ y <- closure knows =<< matchBy @Pal @"pal" h+ pure y.pal+ cluster "alice" @?= ["alice", "bob", "carol", "dave", "erin"]+ cluster "frank" @?= ["frank", "grace"]+ query friends (do a <- matchBy @Pal @"pal" "alice"+ y <- closure knows a+ guard (y.pal == "frank")) @?= []++ , testCase "a 2000 place ring terminates" $ do+ let ring = must $ commit_ emptyDb $ do+ ps <- traverse (insert . Place . fromString . show) [1 .. 2000 :: Int]+ mapM_ (\(a, b) -> insert (Road a b)) (zip ps (drop 1 ps ++ ps))+ next p = matchBy @Road @"from" (refOf p) >>= \r -> follow r.to+ length (query ring (matchBy @Place @"place" "1" >>= \p -> exists (closure next p))) @?= 1+ ]+ where+ roads = must $ commit_ emptyDb $ do+ [par, lyo, mar, nce, bor] <- traverse (insert . Place) ["PAR", "LYO", "MAR", "NCE", "BOR"]+ mapM_ (insert . uncurry Road) [(par, lyo), (lyo, mar), (mar, par), (lyo, nce), (par, bor)]+ friends = must $ commit_ emptyDb $ do+ [alice, bob, carol, dave, erin, frank, grace] <-+ traverse (insert . Pal) ["alice", "bob", "carol", "dave", "erin", "frank", "grace"]+ mapM_ (insert . uncurry Friend)+ [(alice, bob), (alice, carol), (bob, dave), (carol, dave), (dave, erin), (frank, grace)]++windowTests :: TestTree+windowTests = testGroup "Window functions"+ [ testCase "rowNumber, rank and denseRank per group" $ do+ let w f = [ (n, x) | ((_, n, _), x) <- window team (Down . pts) f scores ]+ w rowNumber @?= [("a",1),("b",2),("c",3),("d",4),("e",1),("f",2)]+ w rank @?= [("a",1),("b",2),("c",2),("d",4),("e",1),("f",2)]+ w denseRank @?= [("a",1),("b",2),("c",2),("d",3),("e",1),("f",2)]++ , testCase "lag and lead stop at the group's edge" $ do+ let w f = map snd (window team (Down . pts) f scores)+ w (lag 1 pts) @?= [Nothing, Just 9, Just 7, Just 7, Nothing, Just 5]+ w (lead 1 pts) @?= [Just 7, Just 7, Just 3, Nothing, Just 2, Nothing]+ w (lag 5 pts) @?= replicate 6 Nothing++ , testCase "whole and running, several at once" $ do+ let total = sum . map pts+ map snd (window team (Down . pts) ((,) <$> whole total <*> running total) scores)+ @?= [(26,9),(26,16),(26,23),(26,26),(7,5),(7,7)]++ , testCase "const () is one group, ties keep their order" $+ map (\((_, n, _), r) -> (n, r)) (window (const ()) pts rowNumber scores)+ @?= [("f",1),("d",2),("e",3),("b",4),("c",5),("a",6)]+ ]+ where+ scores = [ ("x", "b", 7), ("y", "e", 5), ("x", "a", 9), ("x", "c", 7)+ , ("x", "d", 3), ("y", "f", 2) ] :: [(Text, Text, Int)]+ team (t, _, _) = t+ pts (_, _, p) = p++-- Helpers++-- An action that should die with @error "boom"@+expectBoom :: IO a -> Assertion+expectBoom act = do+ r <- try act+ case r of+ Left (ErrorCall msg) -> msg @?= "boom"+ Right _ -> assertFailure "expected it to throw, but it returned"++-- Facts written straight into the log as one more transaction, for states the+-- typed API won't make: data from an older schema, say+rawTx :: [(EntityId, Attr, Value, Op)] -> Db -> Db+rawTx facts db = fromHistory (history db ++ [ Datom e a v next op | (e, a, v, op) <- facts ])+ where next = case basisT db of TxId n -> TxId (n + 1)++assert, retractFact :: EntityId -> Attr -> Value -> (EntityId, Attr, Value, Op)+assert e a v = (e, a, v, Assert)+retractFact e a v = (e, a, v, Retract)++-- An entity's live values for an attribute, oldest first+valuesOf :: EntityId -> Attr -> Db -> [Value]+valuesOf e a db = [ dValue d | d <- datoms db, dEntity d == e, dAttr d == a ]++-- The entities holding a value for an attribute+holdersOf :: Attr -> Value -> Db -> [EntityId]+holdersOf a v db = [ dEntity d | d <- datoms db, dAttr d == a, dValue d == v ]++-- The plain record behind a ref+loadR :: Entity a => Ref a -> Db -> Maybe a+loadR r = fmap recordOf . load r++-- A callback that appends what it's given, and the list it appends to+recorder :: IO (TVar [a], a -> IO ())+recorder = do+ seen <- newTVarIO []+ pure (seen, \x -> atomically (modifyTVar' seen (++ [x])))++-- Wait (up to 2s) for the recorded list to look right+waitFor :: Show a => TVar [a] -> ([a] -> Bool) -> IO [a]+waitFor v ok = do+ r <- timeout 2000000 $ atomically $ do+ xs <- readTVar v+ check (ok xs)+ pure xs+ case r of+ Just xs -> pure xs+ Nothing -> readTVarIO v >>= \xs -> assertFailure ("timed out; saw " <> show xs)++-- One department, one skill, one employee with both+fixture :: Db+fixture = must $ commit_ emptyDb $ do+ eng <- insert (Department "ENG" "Engineering")+ hs <- insert (Skill "haskell")+ insert_ (Employee "m@x.io" "Max" (Just "mx") eng (Set.singleton hs))