postgresql-types-algebra 0.1.0.1 → 0.2

raw patch · 3 files changed

+41/−22 lines, 3 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• README.md +19/−11
• postgresql-types-algebra.cabal +1/−1
• src/library/PostgresqlTypes/Algebra.hs +21/−10

@@ -16,31 +16,39 @@  ## Type Classes -### `IsScalar`+### `IsPrimitive`  The core type class for types that map to PostgreSQL values:  ```haskell-class IsScalar a where+class IsPrimitive a where   -- Type metadata   typeName :: Tagged a Text   baseOid :: Tagged a (Maybe Word32)   arrayOid :: Tagged a (Maybe Word32)   typeParams :: Tagged a [Text]   typeSignature :: Tagged a Text-  -  -- Binary format-  binaryEncoder :: a -> Write.Write-  binaryDecoder :: PtrPeeker.Variable (Either DecodingError a)-  +   -- Textual format   textualEncoder :: a -> TextBuilder.TextBuilder   textualDecoder :: Attoparsec.Parser a ``` -This class enables:-- **Binary encoding/decoding** using PostgreSQL's native binary format-- **Textual encoding/decoding** using PostgreSQL's text representation  +### `IsBinaryPrimitive`++Evidence that a type additionally has a PostgreSQL binary wire format. Not every PostgreSQL type+supports binary transmission — some only have textual `send`/`receive` functions registered on the+server — so this is a separate, optional subclass rather than part of `IsPrimitive` itself:++```haskell+class (IsPrimitive a) => IsBinaryPrimitive a where+  binaryEncoder :: a -> Write.Write+  binaryDecoder :: PtrPeeker.Variable (Either DecodingError a)+```++These classes enable:+- **Binary encoding/decoding** using PostgreSQL's native binary format, where supported+- **Textual encoding/decoding** using PostgreSQL's text representation - **Type metadata** including OIDs and type signatures for parameterized types - **Round-trip fidelity** through all encoding combinations @@ -51,7 +59,7 @@ Use this package to: - Define custom PostgreSQL type mappings compatible with the "postgresql-types" ecosystem - Create adapter libraries for different PostgreSQL client libraries-- Build generic tools that work with any `IsScalar` instance+- Build generic tools that work with any `IsPrimitive` (and, where applicable, `IsBinaryPrimitive`) instance  ### For Application Developers 

@@ -1,6 +1,6 @@ cabal-version: 3.0 name: postgresql-types-algebra-version: 0.1.0.1+version: 0.2 category: PostgreSQL, Codecs synopsis: Type classes for PostgreSQL type mappings description:

@@ -11,8 +11,8 @@ import qualified TextBuilder import Prelude --- | Evidence that a type maps to a PostgreSQL scalar value.-class IsScalar a where+-- | Evidence that a type maps to a PostgreSQL primitive type.+class IsPrimitive a where   -- | PostgreSQL schema name, if applicable.   schemaName :: Tagged a (Maybe Text) @@ -34,7 +34,12 @@   -- | Get the PostgreSQL type signature for a given Haskell type.   --   -- In case of parameterized types, the type parameters are included in the signature.-  -- For example, for @'PostgresqlTypes.Types.Bpchar.Bpchar' 10@, the signature will be @bpchar(10)@.+  --+  -- Examples:+  --+  -- - @int8@+  -- - @bpchar(10)@+  -- - @"char"@   typeSignature :: Tagged a Text   typeSignature =     let params = untag (typeParams @a)@@ -52,20 +57,26 @@                     ]                 ) -  -- | Encode the value in PostgreSQL binary format.-  binaryEncoder :: a -> Write.Write--  -- | Decode the value from PostgreSQL binary format.-  binaryDecoder :: PtrPeeker.Variable (Either DecodingError a)-   -- | Represent the value in PostgreSQL textual format.   textualEncoder :: a -> TextBuilder.TextBuilder    -- | Decode the value from PostgreSQL textual format.   textualDecoder :: Attoparsec.Parser a +-- | Evidence that a type has a PostgreSQL binary wire format.+--+-- Not every PostgreSQL type supports binary transmission — some only have+-- textual @send@\/@receive@ functions registered on the server. The absence+-- of an instance of this class signals that the type is textual-only.+class (IsPrimitive a) => IsBinaryPrimitive a where+  -- | Encode the value in PostgreSQL binary format.+  binaryEncoder :: a -> Write.Write++  -- | Decode the value from PostgreSQL binary format.+  binaryDecoder :: PtrPeeker.Variable (Either DecodingError a)+ -- | Evidence that a type can be used as an element of a PostgreSQL range type.-class (IsScalar a, Ord a) => IsRangeElement a where+class (IsPrimitive a, Ord a) => IsRangeElement a where   -- | PostgreSQL range type name.   rangeTypeName :: Tagged a Text