relay-pagination 0.1.1.2 → 0.2.0.0
raw patch · 4 files changed
+134/−50 lines, 4 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
+ Relay.Pagination.Connection: [totalCount] :: Connection a -> !Maybe Natural
+ Relay.Pagination.Connection: countedConnection :: Natural -> Connection a -> CountedConnection a
+ Relay.Pagination.Connection: countedTotal :: CountedConnection a -> Natural
+ Relay.Pagination.Connection: data CountedConnection a
+ Relay.Pagination.Connection: fromConnection :: Connection a -> Maybe (CountedConnection a)
+ Relay.Pagination.Connection: instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON (Relay.Pagination.Connection.CountedConnection a)
+ Relay.Pagination.Connection: instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON (Relay.Pagination.Connection.CountedConnection a)
+ Relay.Pagination.Connection: instance GHC.Classes.Eq a => GHC.Classes.Eq (Relay.Pagination.Connection.CountedConnection a)
+ Relay.Pagination.Connection: instance GHC.Internal.Base.Functor Relay.Pagination.Connection.CountedConnection
+ Relay.Pagination.Connection: instance GHC.Internal.Data.Foldable.Foldable Relay.Pagination.Connection.CountedConnection
+ Relay.Pagination.Connection: instance GHC.Internal.Data.Traversable.Traversable Relay.Pagination.Connection.CountedConnection
+ Relay.Pagination.Connection: instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Relay.Pagination.Connection.CountedConnection a)
+ Relay.Pagination.Connection: toConnection :: CountedConnection a -> Connection a
- Relay.Pagination.Connection: Connection :: ![Edge a] -> !PageInfo -> Connection a
+ Relay.Pagination.Connection: Connection :: ![Edge a] -> !PageInfo -> !Maybe Natural -> Connection a
Files
- CHANGELOG.md +10/−0
- relay-pagination.cabal +40/−35
- src/Relay/Pagination/Connection.hs +52/−6
- test/Main.hs +32/−9
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++- `CountedConnection` guarantees a non-negative count in JSON. Use `countedConnection` to attach it.++### Breaking changes++- `Connection` has a strict `totalCount :: Maybe Natural` field. Set `totalCount = Nothing` when constructing an uncounted connection. The uncounted JSON bytes are unchanged.+ ## 0.1.1.2 — 2026-10-06 ### Fixed
relay-pagination.cabal view
@@ -1,6 +1,6 @@-cabal-version: 3.0-name: relay-pagination-version: 0.1.1.2+cabal-version: 3.0+name: relay-pagination+version: 0.2.0.0 synopsis: Relay-style cursor pagination wire types and opaque cursor codec @@ -10,26 +10,31 @@ first/after/last/before request validation, and a versioned, fingerprinted, base64url-encoded opaque cursor with an exact, golden-tested wire format. -license: BSD-3-Clause-license-file: LICENSE-author: Nadeem Bitar-maintainer: Nadeem Bitar-category: Web, Database-build-type: Simple+license: BSD-3-Clause+license-file: LICENSE+author: Nadeem Bitar+maintainer: Nadeem Bitar+category: Web, Database+build-type: Simple extra-doc-files: CHANGELOG.md 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@@ -37,8 +42,8 @@ OverloadedStrings library- import: lang- hs-source-dirs: src+ import: lang+ hs-source-dirs: src exposed-modules: Relay.Pagination Relay.Pagination.Connection@@ -46,26 +51,26 @@ Relay.Pagination.Request build-depends:- , aeson >=2.2 && <2.3- , base >=4.21 && <5- , base64-bytestring >=1.2 && <1.3- , bytestring >=0.11 && <0.13- , http-api-data >=0.6 && <0.8- , text >=2.0 && <2.2- , uuid-types >=1.0 && <1.1+ aeson >=2.2 && <2.3,+ base >=4.21 && <5,+ base64-bytestring >=1.2 && <1.3,+ bytestring >=0.11 && <0.13,+ http-api-data >=0.6 && <0.8,+ text >=2.0 && <2.2,+ uuid-types >=1.0 && <1.1, test-suite relay-pagination-test- import: lang- type: exitcode-stdio-1.0+ import: lang+ type: exitcode-stdio-1.0 hs-source-dirs: test- main-is: Main.hs+ main-is: Main.hs build-depends:- , aeson- , base- , http-api-data- , quickcheck-instances >=0.3 && <0.4- , relay-pagination- , tasty >=1.4 && <1.6- , tasty-hunit >=0.10 && <0.11- , tasty-quickcheck >=0.10 && <0.12- , uuid-types+ aeson,+ base,+ http-api-data,+ quickcheck-instances >=0.3 && <0.4,+ relay-pagination,+ tasty >=1.4 && <1.6,+ tasty-hunit >=0.10 && <0.11,+ tasty-quickcheck >=0.10 && <0.12,+ uuid-types,
src/Relay/Pagination/Connection.hs view
@@ -3,10 +3,15 @@ -- | The Relay connection response envelope. JSON encoding follows the Relay -- convention exactly: {"edges":[{"node":...,"cursor":"..."}],"pageInfo": -- {"hasNextPage":...,"hasPreviousPage":...,"startCursor":...,"endCursor":...}}--- with null cursors on empty pages. Encodings are hand-written with fixed--- field order so tests can pin exact bytes.+-- with null cursors on empty pages. When present, the optional count is+-- encoded last as @totalCount@. Encodings use a fixed field order. module Relay.Pagination.Connection ( Connection (..),+ CountedConnection,+ countedConnection,+ fromConnection,+ toConnection,+ countedTotal, Edge (..), PageInfo (..), )@@ -15,6 +20,7 @@ import Data.Aeson ((.:), (.:?), (.=)) import Data.Aeson qualified as Aeson import GHC.Generics (Generic)+import Numeric.Natural (Natural) import Relay.Pagination.Cursor (Cursor) -- | One returned row ('node') plus the cursor that addresses its position.@@ -69,14 +75,54 @@ -- endpoint's canonical sort order regardless of paging direction. data Connection a = Connection { edges :: ![Edge a],- pageInfo :: !PageInfo+ pageInfo :: !PageInfo,+ -- | The size of the whole filtered collection, when requested.+ totalCount :: !(Maybe Natural) } deriving stock (Eq, Show, Functor, Foldable, Traversable, Generic) instance (Aeson.ToJSON a) => Aeson.ToJSON (Connection a) where- toJSON c = Aeson.object ["edges" .= edges c, "pageInfo" .= pageInfo c]- toEncoding c = Aeson.pairs ("edges" .= edges c <> "pageInfo" .= pageInfo c)+ toJSON c =+ Aeson.object $+ ["edges" .= edges c, "pageInfo" .= pageInfo c]+ <> maybe [] (pure . ("totalCount" .=)) (totalCount c)+ toEncoding c =+ Aeson.pairs+ ( "edges" .= edges c+ <> "pageInfo" .= pageInfo c+ <> foldMap ("totalCount" .=) (totalCount c)+ ) instance (Aeson.FromJSON a) => Aeson.FromJSON (Connection a) where parseJSON = Aeson.withObject "Connection" \o ->- Connection <$> o .: "edges" <*> o .: "pageInfo"+ Connection <$> o .: "edges" <*> o .: "pageInfo" <*> o .:? "totalCount"++-- | A connection with a required total count.+newtype CountedConnection a = CountedConnection (Connection a)+ deriving stock (Eq, Show, Functor, Foldable, Traversable)++-- | Attach a count, replacing any existing count.+countedConnection :: Natural -> Connection a -> CountedConnection a+countedConnection n c = CountedConnection (c {totalCount = Just n})++-- | Require a count on an existing connection.+fromConnection :: Connection a -> Maybe (CountedConnection a)+fromConnection c = CountedConnection c <$ totalCount c++-- | Recover the connection, whose 'totalCount' is always 'Just'.+toConnection :: CountedConnection a -> Connection a+toConnection (CountedConnection c) = c++-- | The size of the whole filtered collection.+countedTotal :: CountedConnection a -> Natural+countedTotal (CountedConnection Connection {totalCount = Just n}) = n+countedTotal _ = error "CountedConnection invariant violated: missing totalCount"++instance (Aeson.ToJSON a) => Aeson.ToJSON (CountedConnection a) where+ toJSON = Aeson.toJSON . toConnection+ toEncoding = Aeson.toEncoding . toConnection++instance (Aeson.FromJSON a) => Aeson.FromJSON (CountedConnection a) where+ parseJSON value = do+ c <- Aeson.parseJSON value+ maybe (fail "CountedConnection requires totalCount") pure (fromConnection c)
test/Main.hs view
@@ -3,6 +3,7 @@ module Main (main) where import Data.Aeson qualified as Aeson+import Data.List (isInfixOf) import Data.Maybe (fromJust) import Data.UUID.Types qualified as UUID import Relay.Pagination@@ -53,27 +54,49 @@ "Connection JSON" [ testCase "Relay-conventional shape, exact bytes" $ Aeson.encode exampleConnection- @?= "{\"edges\":[\- \{\"node\":\"first\",\"cursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjF9XX0\"},\- \{\"node\":\"second\",\"cursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjJ9XX0\"}],\- \\"pageInfo\":{\"hasNextPage\":true,\"hasPreviousPage\":false,\- \\"startCursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjF9XX0\",\- \\"endCursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjJ9XX0\"}}",+ @?= exampleJsonPrefix <> "}", testCase "empty page has null cursors" $- Aeson.encode (Connection {edges = [], pageInfo = PageInfo False False Nothing Nothing} :: Connection Bool)+ Aeson.encode (Connection {edges = [], pageInfo = PageInfo False False Nothing Nothing, totalCount = Nothing} :: Connection Bool) @?= "{\"edges\":[],\"pageInfo\":{\"hasNextPage\":false,\"hasPreviousPage\":false,\ \\"startCursor\":null,\"endCursor\":null}}", testCase "Connection JSON round-trips" $- Aeson.decode (Aeson.encode exampleConnection) @?= Just exampleConnection+ Aeson.decode (Aeson.encode exampleConnection) @?= Just exampleConnection,+ testCase "count is appended in the counted encoding" $ do+ Aeson.encode counted @?= withCount "42"+ Aeson.decode (withCount "42") @?= Just (exampleConnection {totalCount = Just 42})+ Aeson.decode (withCount "42") @?= Just counted,+ testCase "null totalCount decodes as absent" $+ Aeson.decode (withCount "null") @?= Just exampleConnection,+ testCase "negative and fractional counts are rejected" $ do+ Aeson.decode @(Connection String) (withCount "-1") @?= Nothing+ Aeson.decode @(Connection String) (withCount "1.5") @?= Nothing,+ testCase "CountedConnection requires totalCount" $ do+ fromConnection exampleConnection @?= Nothing+ countedTotal counted @?= 42+ fromConnection (toConnection counted) @?= Just counted+ mapM_ assertMissing [Aeson.encode exampleConnection, withCount "null"] ] where c1 = encodeCursor (CursorPayload 1 7 [KvInt 1]) c2 = encodeCursor (CursorPayload 1 7 [KvInt 2])+ counted = countedConnection 42 exampleConnection+ exampleJsonPrefix =+ "{\"edges\":[\+ \{\"node\":\"first\",\"cursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjF9XX0\"},\+ \{\"node\":\"second\",\"cursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjJ9XX0\"}],\+ \\"pageInfo\":{\"hasNextPage\":true,\"hasPreviousPage\":false,\+ \\"startCursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjF9XX0\",\+ \\"endCursor\":\"eyJ2IjoxLCJmIjo3LCJrIjpbeyJ0IjoiaSIsInYiOjJ9XX0\"}"+ withCount value = exampleJsonPrefix <> ",\"totalCount\":" <> value <> "}"+ assertMissing bytes = case Aeson.eitherDecode @(CountedConnection String) bytes of+ Left err -> assertBool err ("totalCount" `isInfixOf` err)+ Right result -> assertFailure ("unexpected counted connection: " <> show result) exampleConnection :: Connection String exampleConnection = Connection { edges = [Edge "first" c1, Edge "second" c2],- pageInfo = PageInfo True False (Just c1) (Just c2)+ pageInfo = PageInfo True False (Just c1) (Just c2),+ totalCount = Nothing } -- * Cursor codec (M4)