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 +10/−0
- relay-pagination-hasql.cabal +53/−44
- src/Relay/Pagination/Hasql.hs +37/−1
- src/Relay/Pagination/Hasql/Connection.hs +1/−1
- src/Relay/Pagination/Hasql/Sql.hs +6/−0
- test/Test/Integration.hs +73/−5
- test/Test/SqlGolden.hs +5/−1
- test/golden/members-backward-cursor.sql +1/−0
- test/golden/members-backward-no-cursor.sql +1/−0
- test/golden/members-count-parameterized-base.sql +1/−0
- test/golden/members-count.sql +1/−0
- test/golden/members-forward-cursor-parameterized-base.sql +1/−0
- test/golden/members-forward-cursor.sql +1/−0
- test/golden/members-forward-no-cursor.sql +1/−0
- test/golden/property-forward-cursor.sql +1/−0
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