packages feed

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 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+[![Hackage](https://img.shields.io/hackage/v/datomlite)](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
+ test/Shared.hs view
@@ -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))