packages feed

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 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)