-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Automatically derive javascript functions to query servant webservices.
--   
--   Automatically derive javascript functions to query servant
--   webservices.
--   
--   Supports deriving functions using vanilla javascript AJAX requests,
--   Angulari, Axios or JQuery.
--   
--   You can find an example <a>here</a> which serves the generated
--   javascript to a webpage that allows you to trigger webservice calls.
--   
--   <a>CHANGELOG</a>
@package servant-js
@version 0.9.3.2

module Servant.JS.Internal
type JavaScriptGenerator = [Req NoContent] -> Text

-- | This structure is used by specific implementations to let you
--   customize the output
data CommonGeneratorOptions
CommonGeneratorOptions :: (FunctionName -> Text) -> Text -> Text -> Text -> Text -> Text -> CommonGeneratorOptions

-- | function generating function names
[functionNameBuilder] :: CommonGeneratorOptions -> FunctionName -> Text

-- | name used when a user want to send the request body (to let you
--   redefine it)
[requestBody] :: CommonGeneratorOptions -> Text

-- | name of the callback parameter when the request was successful
[successCallback] :: CommonGeneratorOptions -> Text

-- | name of the callback parameter when the request reported an error
[errorCallback] :: CommonGeneratorOptions -> Text

-- | namespace on which we define the foreign function (empty mean local
--   var)
[moduleName] :: CommonGeneratorOptions -> Text

-- | a prefix we should add to the Url in the codegen
[urlPrefix] :: CommonGeneratorOptions -> Text

-- | Default options.
--   
--   <pre>
--   &gt; defCommonGeneratorOptions = CommonGeneratorOptions
--   &gt;   { functionNameBuilder = camelCase
--   &gt;   , requestBody = "body"
--   &gt;   , successCallback = "onSuccess"
--   &gt;   , errorCallback = "onError"
--   &gt;   , moduleName = ""
--   &gt;   , urlPrefix = ""
--   &gt;   }
--   </pre>
defCommonGeneratorOptions :: CommonGeneratorOptions
type AjaxReq = Req NoContent
jsSegments :: [Segment f] -> Text
segmentToStr :: Segment f -> Bool -> Text
segmentTypeToStr :: SegmentType f -> Text
jsParams :: [QueryArg f] -> Text
jsGParams :: Text -> [QueryArg f] -> Text
paramToStr :: QueryArg f -> Bool -> Text

-- | Attempts to reduce the function name provided to that allowed by
--   <tt><a>Foreign</a></tt>.
--   
--   <a>https://mathiasbynens.be/notes/javascript-identifiers</a> Couldn't
--   work out how to handle zero-width characters.
--   
--   @TODO: specify better default function name, or throw error?
toValidFunctionName :: Text -> Text
toJSHeader :: HeaderArg f -> Text

-- | Union of two APIs, first takes precedence in case of overlap.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   type MyApi = "books" :&gt; Get '[JSON] [Book] -- GET /books
--          :&lt;|&gt; "books" :&gt; ReqBody '[JSON] Book :&gt; Post '[JSON] () -- POST /books
--   :}
--   </pre>
data (:<|>) a b :: * -> * -> *
(:<|>) :: a -> b -> (:<|>) a b

-- | The contained API (second argument) can be found under <tt>("/" ++
--   path)</tt> (path being the first argument).
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; -- GET /hello/world
--   
--   &gt;&gt;&gt; -- returning a JSON encoded World value
--   
--   &gt;&gt;&gt; type MyApi = "hello" :&gt; "world" :&gt; Get '[JSON] World
--   </pre>
data (:>) k (path :: k) a :: forall k. () => k -> * -> *
defReq :: () => Req ftype
reqHeaders :: Functor f => ([HeaderArg f] -> f [HeaderArg f]) -> Req f -> f Req f
class HasForeign k (lang :: k) ftype api where {
    type family Foreign ftype api :: *;
}
foreignFor :: HasForeign k lang ftype api => Proxy k lang -> Proxy * ftype -> Proxy * api -> Req ftype -> Foreign ftype api

-- | <a>HasForeignType</a> maps Haskell types with types in the target
--   language of your backend. For example, let's say you're implementing a
--   backend to some language <b>X</b>, and you want a Text representation
--   of each input/output type mentioned in the API:
--   
--   <pre>
--   -- First you need to create a dummy type to parametrize your
--   -- instances.
--   data LangX
--   
--   -- Otherwise you define instances for the types you need
--   instance HasForeignType LangX Text Int where
--      typeFor _ _ _ = "intX"
--   
--   -- Or for example in case of lists
--   instance HasForeignType LangX Text a =&gt; HasForeignType LangX Text [a] where
--      typeFor lang type _ = "listX of " &lt;&gt; typeFor lang ftype (Proxy :: Proxy a)
--   </pre>
--   
--   Finally to generate list of information about all the endpoints for an
--   API you create a function of a form:
--   
--   <pre>
--   getEndpoints :: (HasForeign LangX Text api, GenerateList Text (Foreign Text api))
--                =&gt; Proxy api -&gt; [Req Text]
--   getEndpoints api = listFromAPI (Proxy :: Proxy LangX) (Proxy :: Proxy Text) api
--   </pre>
--   
--   <pre>
--   -- If language __X__ is dynamically typed then you can use
--   -- a predefined NoTypes parameter with the NoContent output type:
--   </pre>
--   
--   <pre>
--   getEndpoints :: (HasForeign NoTypes NoContent api, GenerateList Text (Foreign NoContent api))
--                =&gt; Proxy api -&gt; [Req NoContent]
--   getEndpoints api = listFromAPI (Proxy :: Proxy NoTypes) (Proxy :: Proxy NoContent) api
--   </pre>
class HasForeignType k k1 (lang :: k) ftype (a :: k1)
typeFor :: HasForeignType k k1 lang ftype a => Proxy k lang -> Proxy * ftype -> Proxy k1 a -> ftype

-- | Utility class used by <a>listFromAPI</a> which computes the data
--   needed to generate a function for each endpoint and hands it all back
--   in a list.
class GenerateList ftype reqs
generateList :: GenerateList ftype reqs => reqs -> [Req ftype]
data NoTypes :: *
data ArgType :: *
Normal :: ArgType
Flag :: ArgType
List :: ArgType
data HeaderArg f :: * -> *
HeaderArg :: Arg f -> HeaderArg f
[_headerArg] :: HeaderArg f -> Arg f
ReplaceHeaderArg :: Arg f -> Text -> HeaderArg f
[_headerArg] :: HeaderArg f -> Arg f
[_headerPattern] :: HeaderArg f -> Text
data QueryArg f :: * -> *
QueryArg :: Arg f -> ArgType -> QueryArg f
[_queryArgName] :: QueryArg f -> Arg f
[_queryArgType] :: QueryArg f -> ArgType
data Req f :: * -> *
Req :: Url f -> Method -> [HeaderArg f] -> Maybe f -> Maybe f -> FunctionName -> Req f
[_reqUrl] :: Req f -> Url f
[_reqMethod] :: Req f -> Method
[_reqHeaders] :: Req f -> [HeaderArg f]
[_reqBody] :: Req f -> Maybe f
[_reqReturnType] :: Req f -> Maybe f
[_reqFuncName] :: Req f -> FunctionName
newtype Segment f :: * -> *
Segment :: SegmentType f -> Segment f
[unSegment] :: Segment f -> SegmentType f
data SegmentType f :: * -> *

-- | a static path segment. like "/foo"
Static :: PathSegment -> SegmentType f

-- | a capture. like "/:userid"
Cap :: Arg f -> SegmentType f
data Url f :: * -> *
Url :: Path f -> [QueryArg f] -> Url f
[_path] :: Url f -> Path f
[_queryStr] :: Url f -> [QueryArg f]
type Path f = [Segment f]
data Arg f :: * -> *
Arg :: PathSegment -> f -> Arg f
[_argName] :: Arg f -> PathSegment
[_argType] :: Arg f -> f
newtype FunctionName :: *
FunctionName :: [Text] -> FunctionName
[unFunctionName] :: FunctionName -> [Text]
newtype PathSegment :: *
PathSegment :: Text -> PathSegment
[unPathSegment] :: PathSegment -> Text

-- | Function name builder that simply concat each part together
concatCase :: FunctionName -> Text

-- | Function name builder using the snake_case convention. each part is
--   separated by a single underscore character.
snakeCase :: FunctionName -> Text

-- | Function name builder using the CamelCase convention. each part begins
--   with an upper case character.
camelCase :: FunctionName -> Text

-- | Extract the request body as a value of type <tt>a</tt>.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; -- POST /books
--   
--   &gt;&gt;&gt; type MyApi = "books" :&gt; ReqBody '[JSON] Book :&gt; Post '[JSON] Book
--   </pre>
type ReqBody = ReqBody' (:) * Required (:) * Strict [] *
data JSON :: *
data FormUrlEncoded :: *

-- | <a>POST</a> with 200 status code.
type Post = Verb StdMethod POST 200

-- | <a>GET</a> with 200 status code.
type Get = Verb StdMethod GET 200

-- | Endpoint for plugging in your own Wai <tt>Application</tt>s.
--   
--   The given <tt>Application</tt> will get the request as received by the
--   server, potentially with a modified (stripped) <tt>pathInfo</tt> if
--   the <tt>Application</tt> is being routed with <a>:&gt;</a>.
--   
--   In addition to just letting you plug in your existing WAI
--   <tt>Application</tt>s, this can also be used with
--   <a>serveDirectory</a> to serve static files stored in a particular
--   directory on your filesystem
data Raw :: *

-- | Extract the given header's value as a value of type <tt>a</tt>. I.e.
--   header sent by client, parsed by server.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; newtype Referer = Referer Text deriving (Eq, Show)
--   
--   &gt;&gt;&gt; 
--   
--   &gt;&gt;&gt; -- GET /view-my-referer
--   
--   &gt;&gt;&gt; type MyApi = "view-my-referer" :&gt; Header "from" Referer :&gt; Get '[JSON] Referer
--   </pre>
type Header k = Header' k (:) * Optional (:) * Strict [] *

module Servant.JS.Axios

-- | Axios <tt>configuration</tt> type Let you customize the generation
--   using Axios capabilities
data AxiosOptions
AxiosOptions :: !Bool -> !(Maybe Text) -> !(Maybe Text) -> AxiosOptions

-- | indicates whether or not cross-site Access-Control requests should be
--   made using credentials
[withCredentials] :: AxiosOptions -> !Bool

-- | the name of the cookie to use as a value for xsrf token
[xsrfCookieName] :: AxiosOptions -> !(Maybe Text)

-- | the name of the header to use as a value for xsrf token
[xsrfHeaderName] :: AxiosOptions -> !(Maybe Text)

-- | Default instance of the AxiosOptions Defines the settings as they are
--   in the Axios documentation by default
defAxiosOptions :: AxiosOptions

-- | Generate regular javacript functions that use the axios library, using
--   default values for <a>CommonGeneratorOptions</a>.
axios :: AxiosOptions -> JavaScriptGenerator

-- | Generate regular javascript functions that use the axios library.
axiosWith :: AxiosOptions -> CommonGeneratorOptions -> JavaScriptGenerator

-- | js codegen using axios library using default options
generateAxiosJS :: AxiosOptions -> AjaxReq -> Text

-- | js codegen using axios library
generateAxiosJSWith :: AxiosOptions -> CommonGeneratorOptions -> AjaxReq -> Text

module Servant.JS.Angular

-- | Options specific to the angular code generator
data AngularOptions
AngularOptions :: Text -> (Text -> Text -> Text) -> Text -> AngularOptions

-- | When generating code with wrapInService, name of the service to
--   generate
[serviceName] :: AngularOptions -> Text

-- | beginning of the service definition
[prologue] :: AngularOptions -> Text -> Text -> Text

-- | end of the service definition
[epilogue] :: AngularOptions -> Text

-- | Default options for the Angular codegen. Used by
--   <tt>wrapInService</tt>.
defAngularOptions :: AngularOptions

-- | Instead of simply generating top level functions, generates a service
--   instance on which your controllers can depend to access your API. This
--   variant uses default <a>AngularOptions</a>.
angularService :: AngularOptions -> JavaScriptGenerator

-- | Instead of simply generating top level functions, generates a service
--   instance on which your controllers can depend to access your API
angularServiceWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator

-- | Generate regular javacript functions that use the $http service, using
--   default values for <a>CommonGeneratorOptions</a>.
angular :: AngularOptions -> JavaScriptGenerator

-- | Generate regular javascript functions that use the $http service.
angularWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator

-- | js codegen using $http service from Angular using default options
generateAngularJS :: AngularOptions -> AjaxReq -> Text

-- | js codegen using $http service from Angular
generateAngularJSWith :: AngularOptions -> CommonGeneratorOptions -> AjaxReq -> Text

module Servant.JS.JQuery

-- | Generate javascript functions that use the <i>jQuery</i> library to
--   make the AJAX calls. Uses <a>defCommonGeneratorOptions</a> for the
--   generator options.
jquery :: JavaScriptGenerator

-- | Generate javascript functions that use the <i>jQuery</i> library to
--   make the AJAX calls. Lets you specify your own
--   <a>CommonGeneratorOptions</a>.
jqueryWith :: CommonGeneratorOptions -> JavaScriptGenerator

-- | js codegen using JQuery using default options
generateJQueryJS :: AjaxReq -> Text

-- | js codegen using JQuery
generateJQueryJSWith :: CommonGeneratorOptions -> AjaxReq -> Text

module Servant.JS.Vanilla

-- | Generate vanilla javascript functions to make AJAX requests to your
--   API, using <i>XMLHttpRequest</i>. Uses
--   <a>defCommonGeneratorOptions</a> for the
--   <a>CommonGeneratorOptions</a>.
vanillaJS :: JavaScriptGenerator

-- | Generate vanilla javascript functions to make AJAX requests to your
--   API, using <i>XMLHttpRequest</i>. Lets you specify your own options.
vanillaJSWith :: CommonGeneratorOptions -> JavaScriptGenerator

-- | js codegen using XmlHttpRequest using default generation options
generateVanillaJS :: AjaxReq -> Text

-- | js codegen using XmlHttpRequest
generateVanillaJSWith :: CommonGeneratorOptions -> AjaxReq -> Text


-- | Generating Javascript code to query your APIs using vanilla
--   Javascript, Angular.js or JQuery.
--   
--   Using this package is very simple. Say you have this API type around:
--   
--   <pre>
--   type API = "users" :&gt; Get '[JSON] [Users]
--         :&lt;|&gt; "messages" :&gt; Get '[JSON] [Message]
--   </pre>
--   
--   All you need to do to generate the Javascript code is to write a
--   <a>Proxy</a> for this API type:
--   
--   <pre>
--   api :: Proxy API
--   api = Proxy
--   </pre>
--   
--   And pick one of the generators:
--   
--   <ul>
--   <li><a>vanillaJS</a> and <a>vanillaJSWith</a> generate functions that
--   use <i>XMLHttpRequest</i> to query your endpoints. The former just
--   calls the latter with default code-generation options.</li>
--   <li><a>jquery</a> and <a>jqueryWith</a> follow the same pattern except
--   that they generate functions that use <i>jQuery</i>'s AJAX
--   functions.</li>
--   <li><a>angular</a> and <a>angularWith</a> do the same but use
--   <i>Angular.js</i>'s $http service. In addition, we provide
--   <a>angularService</a> and <a>angularServiceWith</a> which produce
--   functions under an Angular service that your controlers can depend on
--   to query the API.</li>
--   </ul>
--   
--   Let's keep it simple and produce vanilla Javascript code with the
--   default options.
--   
--   <pre>
--   jsCode :: Text
--   jsCode = <a>jsForAPI</a> api <a>vanillaJS</a>
--   </pre>
--   
--   That's it! If you want to write that code to a file:
--   
--   <pre>
--   writeJSCode :: IO ()
--   writeJSCode = <a>writeJSForAPI</a> api <a>vanillaJS</a> "./my_api.js"
--   </pre>
--   
--   If you want to customize the rendering options, take a look at
--   <a>CommonGeneratorOptions</a> which are generic options common to all
--   the generators. the <i>xxxWith</i> variants all take
--   <a>CommonGeneratorOptions</a> whereas the <i>xxx</i> versions use
--   <a>defCommonGeneratorOptions</a>. Once you have some custom
--   
--   <pre>
--   myOptions :: 'CommonGeneratorOptions'
--   </pre>
--   
--   All you need to do to use it is to use <a>vanillaJSWith</a> and pass
--   it <tt>myOptions</tt>.
--   
--   <pre>
--   jsCodeWithMyOptions :: Text
--   jsCodeWithMyOptions = <a>jsForAPI</a> api (<a>vanillaJSWith</a> myOptions)
--   </pre>
--   
--   Follow the same pattern for any other generator.
--   
--   <i>Note</i>: The Angular generators take an additional type of
--   options, namely <a>AngularOptions</a>, to let you tweak aspects of the
--   code generation that are specific to <i>Angular.js</i>.
module Servant.JS

-- | Directly generate all the javascript functions for your API from a
--   <a>Proxy</a> for your API type. You can then write it to a file or
--   integrate it in a page, for example.
jsForAPI :: (HasForeign NoTypes NoContent api, GenerateList NoContent (Foreign NoContent api)) => Proxy api -> JavaScriptGenerator -> Text

-- | Directly generate all the javascript functions for your API from a
--   <a>Proxy</a> for your API type using the given generator and write the
--   resulting code to a file at the given path.
writeJSForAPI :: (HasForeign NoTypes NoContent api, GenerateList NoContent (Foreign NoContent api)) => Proxy api -> JavaScriptGenerator -> FilePath -> IO ()
type JavaScriptGenerator = [Req NoContent] -> Text

-- | This structure is used by specific implementations to let you
--   customize the output
data CommonGeneratorOptions
CommonGeneratorOptions :: (FunctionName -> Text) -> Text -> Text -> Text -> Text -> Text -> CommonGeneratorOptions

-- | function generating function names
[functionNameBuilder] :: CommonGeneratorOptions -> FunctionName -> Text

-- | name used when a user want to send the request body (to let you
--   redefine it)
[requestBody] :: CommonGeneratorOptions -> Text

-- | name of the callback parameter when the request was successful
[successCallback] :: CommonGeneratorOptions -> Text

-- | name of the callback parameter when the request reported an error
[errorCallback] :: CommonGeneratorOptions -> Text

-- | namespace on which we define the foreign function (empty mean local
--   var)
[moduleName] :: CommonGeneratorOptions -> Text

-- | a prefix we should add to the Url in the codegen
[urlPrefix] :: CommonGeneratorOptions -> Text

-- | Default options.
--   
--   <pre>
--   &gt; defCommonGeneratorOptions = CommonGeneratorOptions
--   &gt;   { functionNameBuilder = camelCase
--   &gt;   , requestBody = "body"
--   &gt;   , successCallback = "onSuccess"
--   &gt;   , errorCallback = "onError"
--   &gt;   , moduleName = ""
--   &gt;   , urlPrefix = ""
--   &gt;   }
--   </pre>
defCommonGeneratorOptions :: CommonGeneratorOptions

-- | Function name builder that simply concat each part together
concatCase :: FunctionName -> Text

-- | Function name builder using the snake_case convention. each part is
--   separated by a single underscore character.
snakeCase :: FunctionName -> Text

-- | Function name builder using the CamelCase convention. each part begins
--   with an upper case character.
camelCase :: FunctionName -> Text

-- | Generate vanilla javascript functions to make AJAX requests to your
--   API, using <i>XMLHttpRequest</i>. Uses
--   <a>defCommonGeneratorOptions</a> for the
--   <a>CommonGeneratorOptions</a>.
vanillaJS :: JavaScriptGenerator

-- | Generate vanilla javascript functions to make AJAX requests to your
--   API, using <i>XMLHttpRequest</i>. Lets you specify your own options.
vanillaJSWith :: CommonGeneratorOptions -> JavaScriptGenerator

-- | Generate javascript functions that use the <i>jQuery</i> library to
--   make the AJAX calls. Uses <a>defCommonGeneratorOptions</a> for the
--   generator options.
jquery :: JavaScriptGenerator

-- | Generate javascript functions that use the <i>jQuery</i> library to
--   make the AJAX calls. Lets you specify your own
--   <a>CommonGeneratorOptions</a>.
jqueryWith :: CommonGeneratorOptions -> JavaScriptGenerator

-- | Generate regular javacript functions that use the $http service, using
--   default values for <a>CommonGeneratorOptions</a>.
angular :: AngularOptions -> JavaScriptGenerator

-- | Generate regular javascript functions that use the $http service.
angularWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator

-- | Instead of simply generating top level functions, generates a service
--   instance on which your controllers can depend to access your API. This
--   variant uses default <a>AngularOptions</a>.
angularService :: AngularOptions -> JavaScriptGenerator

-- | Instead of simply generating top level functions, generates a service
--   instance on which your controllers can depend to access your API
angularServiceWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator

-- | Options specific to the angular code generator
data AngularOptions
AngularOptions :: Text -> (Text -> Text -> Text) -> Text -> AngularOptions

-- | When generating code with wrapInService, name of the service to
--   generate
[serviceName] :: AngularOptions -> Text

-- | beginning of the service definition
[prologue] :: AngularOptions -> Text -> Text -> Text

-- | end of the service definition
[epilogue] :: AngularOptions -> Text

-- | Default options for the Angular codegen. Used by
--   <tt>wrapInService</tt>.
defAngularOptions :: AngularOptions

-- | Generate regular javacript functions that use the axios library, using
--   default values for <a>CommonGeneratorOptions</a>.
axios :: AxiosOptions -> JavaScriptGenerator

-- | Generate regular javascript functions that use the axios library.
axiosWith :: AxiosOptions -> CommonGeneratorOptions -> JavaScriptGenerator

-- | Axios <tt>configuration</tt> type Let you customize the generation
--   using Axios capabilities
data AxiosOptions
AxiosOptions :: !Bool -> !(Maybe Text) -> !(Maybe Text) -> AxiosOptions

-- | indicates whether or not cross-site Access-Control requests should be
--   made using credentials
[withCredentials] :: AxiosOptions -> !Bool

-- | the name of the cookie to use as a value for xsrf token
[xsrfCookieName] :: AxiosOptions -> !(Maybe Text)

-- | the name of the header to use as a value for xsrf token
[xsrfHeaderName] :: AxiosOptions -> !(Maybe Text)

-- | Default instance of the AxiosOptions Defines the settings as they are
--   in the Axios documentation by default
defAxiosOptions :: AxiosOptions

-- | Generate the necessary data for codegen as a list, each <a>Req</a>
--   describing one endpoint from your API type.
listFromAPI :: (HasForeign k lang ftype api, GenerateList ftype Foreign ftype api) => Proxy k lang -> Proxy * ftype -> Proxy * api -> [Req ftype]

-- | Generate the data necessary to generate javascript code for all the
--   endpoints of an API, as <a>:&lt;|&gt;</a>-separated values of type
--   <a>AjaxReq</a>.
javascript :: HasForeign NoTypes NoContent api => Proxy api -> Foreign NoContent api
data NoTypes :: *

-- | Utility class used by <a>listFromAPI</a> which computes the data
--   needed to generate a function for each endpoint and hands it all back
--   in a list.
class GenerateList ftype reqs
generateList :: GenerateList ftype reqs => reqs -> [Req ftype]
newtype FunctionName :: *
FunctionName :: [Text] -> FunctionName
[unFunctionName] :: FunctionName -> [Text]
