packages feed

relay-pagination-hasql 0.1.1.2 → 0.2.0.0

raw patch · 15 files changed

+193/−52 lines, 15 filesdep ~relay-paginationPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: relay-pagination

API changes (from Hackage documentation)

+ Relay.Pagination.Hasql: CountedPage :: !Statement () (Connection row) -> !Statement () Natural -> CountedPage row
+ Relay.Pagination.Hasql: [countStatement] :: CountedPage row -> !Statement () Natural
+ Relay.Pagination.Hasql: [pageStatement] :: CountedPage row -> !Statement () (Connection row)
+ Relay.Pagination.Hasql: data CountedPage row
+ Relay.Pagination.Hasql: paginateCounted :: SortSpec row -> PageRequest -> Snippet -> Row row -> Either CursorError (CountedPage row)
+ Relay.Pagination.Hasql: totalCountStatement :: Snippet -> Statement () Natural
+ Relay.Pagination.Hasql.Sql: totalCountSnippet :: Snippet -> Snippet

Files

CHANGELOG.md view
@@ -2,6 +2,16 @@  Versioning follows the [Haskell Package Versioning Policy](https://pvp.haskell.org/). +## 0.2.0.0 — 2026-11-18++### Added++- `paginateCounted` returns a page statement and a count statement from the same filtered base query. `totalCountStatement` provides the count alone. Use one `REPEATABLE READ` transaction when the two results must describe the same snapshot.++### Other changes++- Align the core dependency with 0.2.0.0. Code that constructs `Connection` directly needs `totalCount = Nothing` to keep the uncounted response.+ ## 0.1.1.2 — 2026-10-06  ### Fixed
relay-pagination-hasql.cabal view
@@ -1,6 +1,6 @@-cabal-version:   3.0-name:            relay-pagination-hasql-version:         0.1.1.2+cabal-version: 3.0+name: relay-pagination-hasql+version: 0.2.0.0 synopsis:   Keyset-pagination engine producing Relay connections from hasql queries @@ -10,26 +10,32 @@   BY/LIMIT clauses with all cursor values as typed SQL parameters, and   assembly of spec-correct Connection responses. -license:         BSD-3-Clause-license-file:    LICENSE-author:          Nadeem Bitar-maintainer:      Nadeem Bitar-category:        Database, Web-build-type:      Simple+license: BSD-3-Clause+license-file: LICENSE+author: Nadeem Bitar+maintainer: Nadeem Bitar+category: Database, Web+build-type: Simple extra-doc-files: CHANGELOG.md+extra-source-files: test/golden/*.sql  source-repository head-  type:     git+  type: git   location: https://github.com/shinzui/relay-pagination  common warnings   ghc-options:-    -Wall -Wcompat -Widentities -Wincomplete-record-updates-    -Wincomplete-uni-patterns -Wredundant-constraints -Wunused-packages+    -Wall+    -Wcompat+    -Widentities+    -Wincomplete-record-updates+    -Wincomplete-uni-patterns+    -Wredundant-constraints+    -Wunused-packages  common lang-  import:             warnings-  default-language:   GHC2024+  import: warnings+  default-language: GHC2024   default-extensions:     DeriveAnyClass     DuplicateRecordFields@@ -38,8 +44,8 @@     OverloadedStrings  library-  import:          lang-  hs-source-dirs:  src+  import: lang+  hs-source-dirs: src   exposed-modules:     Relay.Pagination.Hasql     Relay.Pagination.Hasql.Connection@@ -48,20 +54,23 @@     Relay.Pagination.Hasql.Sql    build-depends:-    , base                      >=4.21     && <5-    , bytestring                >=0.11     && <0.13-    , hasql                     >=1.10     && <1.11-    , hasql-dynamic-statements  >=0.5.1    && <0.6-    , relay-pagination          ^>=0.1.1.2-    , text                      >=2.0      && <2.2-    , time                      >=1.12     && <1.15-    , uuid                      >=1.3      && <1.4+    base >=4.21 && <5,+    bytestring >=0.11 && <0.13,+    hasql >=1.10 && <1.11,+    hasql-dynamic-statements >=0.5.1 && <0.6,+    relay-pagination ^>=0.2.0.0,+    text >=2.0 && <2.2,+    time >=1.12 && <1.15,+    uuid >=1.3 && <1.4,  test-suite relay-pagination-hasql-tests-  import:         lang-  type:           exitcode-stdio-1.0-  hs-source-dirs: test test-support-  main-is:        Main.hs+  import: lang+  type: exitcode-stdio-1.0+  hs-source-dirs:+    test+    test-support++  main-is: Main.hs   other-modules:     Relay.Pagination.Test.Postgres     Test.Codec@@ -71,19 +80,19 @@     Test.SqlGolden    build-depends:-    , base-    , bytestring-    , directory-    , ephemeral-pg              >=0.3.1    && <0.4-    , hasql-    , hasql-dynamic-statements-    , relay-pagination          ^>=0.1.1.2-    , relay-pagination-hasql-    , tasty-    , tasty-golden-    , tasty-hunit-    , tasty-quickcheck-    , text-    , time-    , unix-    , uuid+    base,+    bytestring,+    directory,+    ephemeral-pg >=0.3.1 && <0.4,+    hasql,+    hasql-dynamic-statements,+    relay-pagination ^>=0.2.0.0,+    relay-pagination-hasql,+    tasty,+    tasty-golden,+    tasty-hunit,+    tasty-quickcheck,+    text,+    time,+    unix,+    uuid,
src/Relay/Pagination/Hasql.hs view
@@ -7,6 +7,13 @@ -- spec-correct 'Connection'. Cursor values always travel as typed SQL -- parameters; malformed cursors surface as 'CursorError' before any SQL -- runs.+--+-- Use 'paginateCounted' to also count every row that matches the base query,+-- independently of cursor, direction, and page size. Counting can be slow+-- on large collections, so it is opt-in. Run both statements in one+-- @REPEATABLE READ@ or @SERIALIZABLE@ transaction to read the same snapshot.+-- With separate statements or @READ COMMITTED@, a concurrent write can+-- make the page and count reflect different snapshots. module Relay.Pagination.Hasql   ( -- * Sort specifications     SortDirection (..),@@ -24,6 +31,9 @@      -- * Engine     paginate,+    paginateCounted,+    CountedPage (..),+    totalCountStatement,     paginateSnippet,     mkConnection,     mintCursor,@@ -34,6 +44,7 @@ import Hasql.DynamicStatements.Snippet (Snippet) import Hasql.DynamicStatements.Snippet qualified as Snippet import Hasql.Statement (Statement)+import Numeric.Natural (Natural) import Relay.Pagination (Connection, CursorError, PageRequest) import Relay.Pagination.Hasql.Connection (mintCursor, mkConnection) import Relay.Pagination.Hasql.KeyCodec@@ -50,7 +61,7 @@     SortSpec (..),     sortSpecFingerprint,   )-import Relay.Pagination.Hasql.Sql (paginateSnippet)+import Relay.Pagination.Hasql.Sql (paginateSnippet, totalCountSnippet)  -- | The whole engine in one function: validate the request's cursor against -- the sort specification, generate the keyset query, and post-process the@@ -72,3 +83,28 @@ paginate spec req base rowDecoder = do   snippet <- paginateSnippet spec req base   Right (mkConnection spec req <$> Snippet.toStatement snippet (Decoders.rowList rowDecoder))++-- | The page statement and the count statement for its filtered collection.+-- Attach their results with 'Relay.Pagination.countedConnection'.+data CountedPage row = CountedPage+  { pageStatement :: !(Statement () (Connection row)),+    countStatement :: !(Statement () Natural)+  }++-- | Build an unprepared statement that counts the rows of the base query.+totalCountStatement :: Snippet -> Statement () Natural+totalCountStatement base =+  Snippet.toStatement (totalCountSnippet base) $+    fromIntegral <$> Decoders.singleRow (Decoders.column (Decoders.nonNullable Decoders.int8))++-- | Validate and build the page statement as in 'paginate', and derive a+-- count statement from the same base query.+paginateCounted ::+  SortSpec row ->+  PageRequest ->+  Snippet ->+  Decoders.Row row ->+  Either CursorError (CountedPage row)+paginateCounted spec req base rowDecoder = do+  page <- paginate spec req base rowDecoder+  pure CountedPage {pageStatement = page, countStatement = totalCountStatement base}
src/Relay/Pagination/Hasql/Connection.hs view
@@ -59,7 +59,7 @@ -- cursor was minted from is itself behind you). mkConnection :: SortSpec row -> PageRequest -> [row] -> Connection row mkConnection spec PageRequest {pageSize, direction, cursor} rows =-  Connection {edges, pageInfo}+  Connection {edges, pageInfo, totalCount = Nothing}   where     probe = length rows > pageSize     kept = take pageSize rows
src/Relay/Pagination/Hasql/Sql.hs view
@@ -11,6 +11,7 @@ -- byte-stable. module Relay.Pagination.Hasql.Sql   ( paginateSnippet,+    totalCountSnippet,   ) where @@ -33,6 +34,11 @@   ) import Relay.Pagination.Hasql.KeyCodec (KeyCodec (..)) import Relay.Pagination.Hasql.SortSpec (KeyColumn (..), SortDirection (..), SortSpec (..), sortSpecFingerprint)++-- | Count the rows of the filtered base query, preserving its parameters.+totalCountSnippet :: Snippet -> Snippet+totalCountSnippet base =+  Snippet.sql "SELECT count(*) FROM (" <> base <> Snippet.sql ") AS rp_base"  -- | Wrap a base query with the keyset predicate, order clause, and -- @LIMIT pageSize+1@ for the given page request.
test/Test/Integration.hs view
@@ -5,6 +5,7 @@ -- final page that is exactly full), walked forward and backward. module Test.Integration (tests, demo) where +import Control.Exception (bracket, finally, onException) import Control.Monad (forM_) import Data.Int (Int64) import Data.List (sortBy)@@ -22,6 +23,7 @@ import Hasql.Encoders qualified as Encoders import Hasql.Session qualified as Session import Hasql.Statement (Statement)+import Numeric.Natural (Natural) import Relay.Pagination   ( Connection (..),     CursorPayload (..),@@ -33,11 +35,13 @@     decodeCursor,   ) import Relay.Pagination.Hasql-  ( KeyColumn (..),+  ( CountedPage (..),+    KeyColumn (..),     SortDirection (..),     SortSpec (..),     mintCursor,     paginate,+    paginateCounted,     sortSpecFingerprint,     textKey,     timestamptzKey,@@ -94,10 +98,74 @@           (t, i) <- case keys payload of             [KvTimestampMicros us, KvText i] -> pure (microsToUtcTime us, i)             other -> fail ("unexpected cursor keys: " <> show other)-          n <- run conn (Session.statement () (countStatement t i))-          n @?= 1+          n <- run conn (Session.statement () (exactKeyCountStatement t i))+          n @?= 1,+      totalCountTests getDb     ] +totalCountTests :: IO (Pg.Database, Connection.Connection) -> TestTree+totalCountTests getDb =+  testGroup+    "total count"+    [ check "first page" itemsBase "" first 25 (take 5 canonical),+      check "middle page" itemsBase "" (atCursor Forward (canonical !! 4)) 25 (take 5 (drop 5 canonical)),+      check+        "backward page"+        itemsBase+        ""+        (atCursor Backward (canonical !! 10))+        25+        (take 5 (drop 5 canonical)),+      check "zero page size" itemsBase "" (first {pageSize = 0}) 25 [],+      check "past the end" itemsBase "" (atCursor Forward (last canonical)) 25 [],+      check "empty collection" (itemsBase <> Snippet.sql " WHERE false") " WHERE false" first 0 [],+      check "filtered base query" filteredBase boundaryFilter first 2 (filter (\(i, _) -> i == "i21" || i == "i22") canonical),+      -- A separate database isolates the concurrent insert from all other cases.+      withResource acquire release \getSnapshotDb ->+        testCase "repeatable read uses one snapshot across a concurrent insert" do+          (db, reader) <- getSnapshotDb+          p <- build itemsBase (first {pageSize = 25})+          let sqlCount = Session.statement () (countStatement p)+              sqlPage = Session.statement () (pageStatement p)+              rollback = run reader (Session.script "ROLLBACK")+          bracket+            (either (fail . show) pure =<< Connection.acquire (Pg.connectionSettings db))+            Connection.release+            \writer -> do+              let readSnapshot = do+                    n <- run reader (Session.script "BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY" *> sqlCount)+                    -- The inserted row would sort first in a fresh snapshot.+                    run writer (insertRow ("new", microsToUtcTime 1767323045123457))+                    page <- run reader (sqlPage <* Session.script "COMMIT")+                    pure (n, page)+                  checkSnapshot = do+                    (n, page) <- readSnapshot `onException` rollback+                    n @?= 25+                    nodesOf page @?= canonical+                    run reader sqlCount >>= (@?= 26)+              checkSnapshot `finally` run writer (Session.script "DELETE FROM items WHERE item_id = 'new'")+    ]+  where+    first = PageRequest {pageSize = 5, direction = Forward, cursor = Nothing}+    atCursor dir row = PageRequest {pageSize = 5, direction = dir, cursor = Just (mintCursor spec row)}+    boundaryFilter = " WHERE item_id IN ('i21', 'i22')"+    filteredBase = itemsBase <> Snippet.sql boundaryFilter+    build base req = either (fail . show) pure (paginateCounted spec req base rowDecoder)+    referenceCount predicate =+      Snippet.toStatement+        (Snippet.sql ("SELECT count(*) FROM items" <> predicate))+        (Decoders.singleRow (Decoders.column (Decoders.nonNullable Decoders.int8)))+    check name base predicate req expectedCount expectedNodes = testCase name do+      (_, conn) <- getDb+      p <- build base req+      actualCount <- run conn (Session.statement () (countStatement p))+      actualCount @?= (expectedCount :: Natural)+      directCount <- run conn (Session.statement () (referenceCount predicate))+      toInteger actualCount @?= toInteger directCount+      page <- run conn (Session.statement () (pageStatement p))+      totalCount page @?= Nothing+      nodesOf page @?= expectedNodes+ -- * Engine wiring  spec :: SortSpec (Text, UTCTime)@@ -145,8 +213,8 @@ nodesOf :: Connection (Text, UTCTime) -> [(Text, UTCTime)] nodesOf page = [n | Edge {node = n} <- edges page] -countStatement :: UTCTime -> Text -> Statement () Int64-countStatement t i =+exactKeyCountStatement :: UTCTime -> Text -> Statement () Int64+exactKeyCountStatement t i =   Snippet.toStatement     ( Snippet.sql "SELECT count(*) FROM items WHERE updated_at = "         <> Snippet.encoderAndParam (Encoders.nonNullable Encoders.timestamptz) t
test/Test/SqlGolden.hs view
@@ -27,7 +27,7 @@ import Relay.Pagination.Hasql.Connection (mintCursor) import Relay.Pagination.Hasql.KeyCodec (microsToUtcTime, textKey, timestamptzKey) import Relay.Pagination.Hasql.SortSpec (KeyColumn (..), SortDirection (..), SortSpec (..), sortSpecFingerprint)-import Relay.Pagination.Hasql.Sql (paginateSnippet)+import Relay.Pagination.Hasql.Sql (paginateSnippet, totalCountSnippet) import Test.Tasty import Test.Tasty.Golden (goldenVsString) import Test.Tasty.HUnit@@ -46,6 +46,8 @@         (PageRequest {pageSize = 5, direction = Forward, cursor = Just propertyCursor})         propertyBase,       golden "members-forward-cursor-parameterized-base" (page Forward (Just membersCursor)) parameterizedBase,+      countGolden "members-count" membersBase,+      countGolden "members-count-parameterized-base" parameterizedBase,       errorPathTests     ]   where@@ -53,6 +55,8 @@     goldenWith spec name req base =       goldenVsString name ("test/golden/" <> name <> ".sql") do         either (assertFailure . show) (pure . renderSql) (paginateSnippet spec req base)+    countGolden name =+      goldenVsString name ("test/golden/" <> name <> ".sql") . pure . renderSql . totalCountSnippet     renderSql = LBS.fromStrict . Text.encodeUtf8 . Snippet.toSql     page dir mc = PageRequest {pageSize = 5, direction = dir, cursor = mc} 
+ test/golden/members-backward-cursor.sql view
@@ -0,0 +1,1 @@+SELECT * FROM (SELECT member_id, updated_at FROM members) AS rp_base WHERE (updated_at > $1) OR (updated_at = $2 AND member_id < $3) ORDER BY updated_at ASC, member_id DESC LIMIT $4
+ test/golden/members-backward-no-cursor.sql view
@@ -0,0 +1,1 @@+SELECT * FROM (SELECT member_id, updated_at FROM members) AS rp_base ORDER BY updated_at ASC, member_id DESC LIMIT $1
+ test/golden/members-count-parameterized-base.sql view
@@ -0,0 +1,1 @@+SELECT count(*) FROM (SELECT member_id, updated_at FROM members WHERE mls = $1) AS rp_base
+ test/golden/members-count.sql view
@@ -0,0 +1,1 @@+SELECT count(*) FROM (SELECT member_id, updated_at FROM members) AS rp_base
+ test/golden/members-forward-cursor-parameterized-base.sql view
@@ -0,0 +1,1 @@+SELECT * FROM (SELECT member_id, updated_at FROM members WHERE mls = $1) AS rp_base WHERE (updated_at < $2) OR (updated_at = $3 AND member_id > $4) ORDER BY updated_at DESC, member_id ASC LIMIT $5
+ test/golden/members-forward-cursor.sql view
@@ -0,0 +1,1 @@+SELECT * FROM (SELECT member_id, updated_at FROM members) AS rp_base WHERE (updated_at < $1) OR (updated_at = $2 AND member_id > $3) ORDER BY updated_at DESC, member_id ASC LIMIT $4
+ test/golden/members-forward-no-cursor.sql view
@@ -0,0 +1,1 @@+SELECT * FROM (SELECT member_id, updated_at FROM members) AS rp_base ORDER BY updated_at DESC, member_id ASC LIMIT $1
+ test/golden/property-forward-cursor.sql view
@@ -0,0 +1,1 @@+SELECT * FROM (SELECT property_id FROM properties) AS rp_base WHERE (property_id > $1) ORDER BY property_id ASC LIMIT $2