Destroy all GADTs; Removes the From GADT and SqlExpr GADT

changelog.md

@@ -1,14 +1,17 @@
-3.4.1.0
+3.5.0.0
 =======- 
 - @belevy
   - [#228](https://github.com/bitemyapp/esqueleto/pull/228)
         - Destroy all GADTs; Removes the From GADT and SqlExpr GADT 
-        - From GADT is replaced with a From typeclass
+        - From GADT is replaced with a From data type and FromRaw 
         - SqlExpr is now all defined in terms of ERaw
         - Modified ERaw to contain a SqlExprMeta with any extra information 
           that may be needed
         - Experimental top level is now strictly for documentation and all the 
           implementation details are in Experimental.* modules
+
+3.4.1.0
+=======
 - @Vlix
   - [#232](https://github.com/bitemyapp/esqueleto/pull/232)
     - Export the `ValidOnClauseValue` type family

esqueleto.cabal

@@ -1,7 +1,7 @@
 cabal-version: 1.12
 
 name:           esqueleto
-version:        3.4.1.0
+version:        3.5.0.0
 synopsis:       Type-safe EDSL for SQL queries on persistent backends.
 description:    @esqueleto@ is a bare bones, type-safe EDSL for SQL queries that works with unmodified @persistent@ SQL backends.  Its language closely resembles SQL, so you don't have to learn new concepts, just new syntax, and it's fairly easy to predict the generated SQL and optimize it for your backend. Most kinds of errors committed when writing SQL are caught as compile-time errors---although it is possible to write type-checked @esqueleto@ queries that fail at runtime.
                 .

src/Database/Esqueleto/Experimental.hs

@@ -18,13 +18,24 @@ module Database.Esqueleto.Experimental
 
       -- * Documentation
 
-      Table(..)
+    -- ** Basic Queries
+      from
     , table
-    , from
+    , Table(..)
     , SubQuery(..)
     , selectQuery
+
+    -- ** Joins
     , (:&)(..)
     , on
+    , innerJoin
+    , innerJoinLateral
+    , leftJoin
+    , leftJoinLateral
+    , rightJoin
+    , fullOuterJoin
+    , crossJoin
+    , crossJoinLateral
 
       -- ** Set Operations
       -- $sql-set-operations
@@ -42,16 +53,7 @@ module Database.Esqueleto.Experimental
     , with
     , withRecursive
 
-    , innerJoin
-    , innerJoinLateral
-    , leftJoin
-    , leftJoinLateral
-    , rightJoin
-    , fullOuterJoin
-    , crossJoin
-    , crossJoinLateral
-
-      -- * Internals
+      -- ** Internals
     , From(..)
     , ToMaybe(..)
     , ToAlias(..)
@@ -60,8 +62,8 @@ module Database.Esqueleto.Experimental
     , ToAliasReferenceT
     , ToSqlSetOperation(..)
     , ValidOnClauseValue
-    -- * The Normal Stuff
 
+    -- * The Normal Stuff
     , where_
     , groupBy
     , orderBy
@@ -174,6 +176,7 @@ module Database.Esqueleto.Experimental
     , DistinctOn
     , LockingKind(..)
     , SqlString
+
       -- ** Joins
     , InnerJoin(..)
     , CrossJoin(..)
@@ -182,7 +185,8 @@ module Database.Esqueleto.Experimental
     , FullOuterJoin(..)
     , JoinKind(..)
     , OnClauseWithoutMatchingJoinException(..)
-      -- * SQL backend
+
+      -- ** SQL backend
     , SqlQuery
     , SqlExpr
     , SqlEntity
@@ -196,22 +200,20 @@ module Database.Esqueleto.Experimental
     , insertSelectCount
     , (<#)
     , (<&>)
+
     -- ** Rendering Queries
     , renderQueryToText
     , renderQuerySelect
     , renderQueryUpdate
     , renderQueryDelete
     , renderQueryInsertInto
-    -- * Internal.Language
-    -- * RDBMS-specific modules
-    -- $rdbmsSpecificModules
 
-    -- * Helpers
+    -- ** Helpers
     , valkey
     , valJ
     , associateJoin
 
-      -- * Re-exports
+      -- ** Re-exports
       -- $reexports
     , deleteKey
     , module Database.Esqueleto.Internal.PersistentImport
@@ -316,7 +318,7 @@ import Database.Esqueleto.Experimental.ToMaybe
 --
 -- @
 -- select $ do
--- people <- from $ Table \@Person
+-- people <- from $ table \@Person
 -- where_ (people ^. PersonName ==. val \"John\")
 -- pure people
 -- @
@@ -344,8 +346,8 @@ import Database.Esqueleto.Experimental.ToMaybe
 -- @
 -- select $ do
 -- (people :& blogPosts) <-
---     from $ Table \@Person
---     \`LeftOuterJoin\` Table \@BlogPost
+--     from $ table \@Person
+--     \`leftJoin\` table \@BlogPost
 --     \`on\` (\\(people :& blogPosts) ->
 --             people ^. PersonId ==. blogPosts ?. BlogPostAuthorId)
 -- where_ (people ^. PersonAge >. val 18)
@@ -376,19 +378,19 @@ import Database.Esqueleto.Experimental.ToMaybe
 --
 -- In this version, with each successive 'on' clause, only the tables
 -- we have already joined into are in scope, so we must pattern match
--- accordingly. In this case, in the second 'InnerJoin', we do not use
+-- accordingly. In this case, in the second 'innerJoin', we do not use
 -- the first `Person` reference, so we use @_@ as a placeholder to
 -- ignore it. This prevents a possible runtime error where a table
 -- is referenced before it appears in the sequence of 'JOIN's.
 --
 -- @
 -- select $ do
 -- (people1 :& followers :& people2) <-
---     from $ Table \@Person
---     \`InnerJoin` Table \@Follow
+--     from $ table \@Person
+--     \`innerJoin` table \@Follow
 --     \`on\` (\\(people1 :& followers) ->
 --             people1 ^. PersonId ==. followers ^. FollowFollowed)
---     \`InnerJoin` Table \@Person
+--     \`innerJoin` table \@Person
 --     \`on\` (\\(_ :& followers :& people2) ->
 --             followers ^. FollowFollower ==. people2 ^. PersonId)
 -- where_ (people1 ^. PersonName ==. val \"John\")
@@ -420,8 +422,8 @@ import Database.Esqueleto.Experimental.ToMaybe
 -- peopleWithPosts <-
 --   from $ do
 --     (people :& blogPosts) <-
---       from $ Table \@Person
---       \`InnerJoin\` Table \@BlogPost
+--       from $ table \@Person
+--       \`innerJoin\` table \@BlogPost
 --       \`on\` (\\(p :& bP) ->
 --               p ^. PersonId ==. bP ^. BlogPostAuthorId)
 --     groupBy (people ^. PersonId)
@@ -451,8 +453,8 @@ import Database.Esqueleto.Experimental.ToMaybe
 -- (authors, blogPosts) <- from $
 --   (do
 --     (author :& blogPost) <-
---       from $ Table \@Person
---       \`InnerJoin\` Table \@BlogPost
+--       from $ table \@Person
+--       \`innerJoin\` table \@BlogPost
 --       \`on\` (\\(a :& bP) ->
 --               a ^. PersonId ==. bP ^. BlogPostAuthorId)
 --     where_ (author ^. PersonId ==. val currentPersonId)
@@ -461,11 +463,11 @@ import Database.Esqueleto.Experimental.ToMaybe
 --   \`union_\`
 --   (do
 --     (follow :& blogPost :& author) <-
---       from $ Table \@Follow
---       \`InnerJoin\` Table \@BlogPost
+--       from $ table \@Follow
+--       \`innerJoin\` table \@BlogPost
 --       \`on\` (\\(f :& bP) ->
 --               f ^. FollowFollowed ==. bP ^. BlogPostAuthorId)
---       \`InnerJoin\` Table \@Person
+--       \`innerJoin\` table \@Person
 --       \`on\` (\\(_ :& bP :& a) ->
 --               bP ^. BlogPostAuthorId ==. a ^. PersonId)
 --     where_ (follow ^. FollowFollower ==. val currentPersonId)
@@ -484,14 +486,14 @@ import Database.Esqueleto.Experimental.ToMaybe
 -- @
 -- select $ do
 -- (salesPerson :& maxSaleAmount :& maxSaleCustomerName) <-
---   from $ Table \@SalesPerson
---   \`CrossJoin\` (\\salesPerson -> do
---         sales <- from $ Table \@Sale
+--   from $ table \@SalesPerson
+--   \`crossJoinLateral\` (\\salesPerson -> do
+--         sales <- from $ table \@Sale
 --         where_ $ sales ^. SaleSalesPersonId ==. salesPerson ^. SalesPersonId
 --         pure $ max_ (sales ^. SaleAmount)
 --         )
---   \`CrossJoin\` (\\(salesPerson :& maxSaleAmount) -> do
---         sales <- from $ Table \@Sale
+--   \`crossJoinLateral\` (\\(salesPerson :& maxSaleAmount) -> do
+--         sales <- from $ table \@Sale
 --         where_ $ sales ^. SaleSalesPersonId ==. salesPerson ^. SalesPersonId
 --              &&. sales ^. SaleAmount ==. maxSaleAmount
 --         pure $ sales ^. SaleCustomerName)
@@ -539,12 +541,12 @@ import Database.Esqueleto.Experimental.ToMaybe
 -- @
 -- select $ from $
 --   (do
---      a <- from Table @A
+--      a <- from $ table @A
 --      pure $ a ^. ASomeCol
 --   )
 --   \`union_\`
 --   (do
---      b <- from Table @B
+--      b <- from $ table @B
 --      pure $ b ^. BSomeCol
 --   )
 -- @

src/Database/Esqueleto/Experimental/From.hs

@@ -30,11 +30,11 @@ import Database.Esqueleto.Internal.PersistentImport
 
 -- | 'FROM' clause, used to bring entities into scope.
 --
--- Internally, this function uses the `From` datatype and the
--- `From` typeclass. Unlike the old `Database.Esqueleto.from`,
--- this does not take a function as a parameter, but rather
--- a value that represents a 'JOIN' tree constructed out of
--- instances of `From`. This implementation eliminates certain
+-- Internally, this function uses the `From` datatype.
+-- Unlike the old `Database.Esqueleto.from`, this does not
+-- take a function as a parameter, but rather a value that
+-- represents a 'JOIN' tree constructed out of instances of `From`.
+-- This implementation eliminates certain
 -- types of runtime errors by preventing the construction of
 -- invalid SQL (e.g. illegal nested-@from@).
 from :: ToFrom a a' => a -> SqlQuery a'
@@ -44,23 +44,44 @@ from f = do
     pure a
 
 type RawFn = NeedParens -> IdentInfo -> (TLB.Builder, [PersistValue])
+
+-- | Data type defining the "From" language. This should not
+-- constructed directly in application code.
+--
+-- A @From@ is a SqlQuery which returns a reference to the result of calling from
+-- and a function that produces a portion of a FROM clause. This gets passed to
+-- the FromRaw FromClause constructor directly when converting
+-- from a @From@ to a @SqlQuery@ using @from@
+--
+-- /Since: 3.5.0.0/
 newtype From a = From
     { unFrom :: SqlQuery (a, RawFn)}
 
+
+-- | A helper class primarily designed to allow using @SqlQuery@ directly in
+-- a From expression. This is also useful for embedding a @SqlSetOperation@,
+-- as well as supporting backwards compatibility for the
+-- data constructor join tree used prior to /3.5.0.0/
+--
+-- /Since: 3.5.0.0/
 class ToFrom a r | a -> r where
     toFrom :: a -> From r
 instance ToFrom (From a) a where
     toFrom = id
 
--- | Data type for bringing a Table into scope in a JOIN tree
---
--- @
--- select $ from $ Table \@People
--- @
+{-# DEPRECATED Table "/Since: 3.5.0.0/ - use 'table' instead" #-}
 data Table a = Table
+
 instance PersistEntity ent => ToFrom (Table ent) (SqlExpr (Entity ent)) where
     toFrom _ = table
 
+-- | Bring a PersistEntity into scope from a table
+--
+-- @
+-- select $ from $ table \@People
+-- @
+--
+-- /Since: 3.5.0.0/
 table :: forall ent. PersistEntity ent => From (SqlExpr (Entity ent))
 table = From $ do
     let ed = entityDef (Proxy @ent)
@@ -85,6 +106,21 @@ instance (SqlSelect a r, ToAlias a, ToAliasReference a) => ToFrom (SubQuery (Sql
 instance (SqlSelect a r, ToAlias a, ToAliasReference a) => ToFrom (SqlQuery a) a where
     toFrom = selectQuery
 
+-- | Select from a subquery, often used in conjuction with joins but can be
+-- used without any joins. Because @SqlQuery@ has a @ToFrom@ instance you probably
+-- dont need to use this function directly.
+--
+-- @
+-- select $
+--      p <- from $
+--              selectQuery do
+--              p <- from $ table \@Person
+--              limit 5
+--              orderBy [ asc p ^. PersonAge ]
+--      ...
+-- @
+--
+-- /Since: 3.5.0.0/
 selectQuery :: (SqlSelect a r, ToAlias a, ToAliasReference a) => SqlQuery a -> From a
 selectQuery subquery = From $ do
     -- We want to update the IdentState without writing the query to side data

src/Database/Esqueleto/Experimental/From/CommonTableExpression.hs

@@ -56,21 +56,21 @@ with query = do
 -- @
 -- select $ do
 -- cte <- withRecursive
---          (do $
---              person <- from $ Table \@Person
+--          (do
+--              person <- from $ table \@Person
 --              where_ $ person ^. PersonId ==. val personId
 --              pure person
 --          )
 --          unionAll_
---          (\\self -> do $
+--          (\\self -> do
 --              (p :& f :& p2 :& pSelf) <- from self
---                       \`InnerJoin\` $ Table \@Follow
+--                       \`innerJoin\` $ table \@Follow
 --                       \`on\` (\\(p :& f) ->
 --                               p ^. PersonId ==. f ^. FollowFollower)
---                       \`InnerJoin\` $ Table \@Person
+--                       \`innerJoin\` $ table \@Person
 --                       \`on\` (\\(p :& f :& p2) ->
 --                               f ^. FollowFollowed ==. p2 ^. PersonId)
---                       \`LeftOuterJoin\` self
+--                       \`leftJoin\` self
 --                       \`on\` (\\(_ :& _ :& p2 :& pSelf) ->
 --                               just (p2 ^. PersonId) ==. pSelf ?. PersonId)
 --              where_ $ isNothing (pSelf ?. PersonId)