License | BSD3 |
---|---|
Maintainer | Alp Mestanogullari <alpmestan@gmail.com> |
Stability | experimental |
Portability | non-portable |
Safe Haskell | None |
Language | Haskell2010 |
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:
type API = "users" :> Get '[JSON] [Users] :<|> "messages" :> Get '[JSON] [Message]
All you need to do to generate the Javascript code is to write a Proxy
for this API type:
api :: Proxy API api = Proxy
And pick one of the generators:
vanillaJS
andvanillaJSWith
generate functions that use XMLHttpRequest to query your endpoints. The former just calls the latter with default code-generation options.jquery
andjqueryWith
follow the same pattern except that they generate functions that use jQuery's AJAX functions.angular
andangularWith
do the same but use Angular.js's $http service. In addition, we provideangularService
andangularServiceWith
which produce functions under an Angular service that your controlers can depend on to query the API.
Let's keep it simple and produce vanilla Javascript code with the default options.
jsCode :: Text jsCode =jsForAPI
apivanillaJS
That's it! If you want to write that code to a file:
writeJSCode :: IO () writeJSCode =writeJSForAPI
apivanillaJS
"./my_api.js"
If you want to customize the rendering options, take a look
at CommonGeneratorOptions
which are generic options common to all the
generators. the xxxWith variants all take CommonGeneratorOptions
whereas
the xxx versions use defCommonGeneratorOptions
. Once you have some custom
myOptions :: 'CommonGeneratorOptions'
All you need to do to use it is to use vanillaJSWith
and pass it myOptions
.
jsCodeWithMyOptions :: Text jsCodeWithMyOptions =jsForAPI
api (vanillaJSWith
myOptions)
Follow the same pattern for any other generator.
Note: The Angular generators take an additional type of options,
namely AngularOptions
, to let you tweak aspects of the code generation
that are specific to Angular.js.
- jsForAPI :: (HasForeign api, GenerateList (Foreign api)) => Proxy api -> JavaScriptGenerator -> Text
- writeJSForAPI :: (HasForeign api, GenerateList (Foreign api)) => Proxy api -> JavaScriptGenerator -> FilePath -> IO ()
- type JavaScriptGenerator = [Req] -> Text
- data CommonGeneratorOptions = CommonGeneratorOptions {
- functionNameBuilder :: FunctionName -> Text
- requestBody :: Text
- successCallback :: Text
- errorCallback :: Text
- moduleName :: Text
- urlPrefix :: Text
- defCommonGeneratorOptions :: CommonGeneratorOptions
- concatCase :: FunctionName -> Text
- snakeCase :: FunctionName -> Text
- camelCase :: FunctionName -> Text
- vanillaJS :: JavaScriptGenerator
- vanillaJSWith :: CommonGeneratorOptions -> JavaScriptGenerator
- jquery :: JavaScriptGenerator
- jqueryWith :: CommonGeneratorOptions -> JavaScriptGenerator
- angular :: AngularOptions -> JavaScriptGenerator
- angularWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator
- angularService :: AngularOptions -> JavaScriptGenerator
- angularServiceWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator
- data AngularOptions = AngularOptions {
- serviceName :: Text
- prologue :: Text -> Text -> Text
- epilogue :: Text
- defAngularOptions :: AngularOptions
- axios :: AxiosOptions -> JavaScriptGenerator
- axiosWith :: AxiosOptions -> CommonGeneratorOptions -> JavaScriptGenerator
- data AxiosOptions = AxiosOptions {
- withCredentials :: !Bool
- xsrfCookieName :: !(Maybe Text)
- xsrfHeaderName :: !(Maybe Text)
- defAxiosOptions :: AxiosOptions
- listFromAPI :: (HasForeign api, GenerateList (Foreign api)) => Proxy api -> [AjaxReq]
- javascript :: HasForeign layout => Proxy layout -> Foreign layout
- class GenerateList reqs where
- generateList :: reqs -> [AjaxReq]
Generating javascript code from an API type
:: (HasForeign api, GenerateList (Foreign api)) | |
=> Proxy api | proxy for your API type |
-> JavaScriptGenerator | js code generator to use (angular, vanilla js, jquery, others) |
-> Text | a text that you can embed in your pages or write to a file |
:: (HasForeign api, GenerateList (Foreign api)) | |
=> Proxy api | proxy for your API type |
-> JavaScriptGenerator | js code generator to use (angular, vanilla js, jquery, others) |
-> FilePath | path to the file you want to write the resulting javascript code into |
-> IO () |
type JavaScriptGenerator = [Req] -> Text
Options common to all generators
This structure is used by specific implementations to let you customize the output
CommonGeneratorOptions | |
|
defCommonGeneratorOptions :: CommonGeneratorOptions
Default options.
> defCommonGeneratorOptions = CommonGeneratorOptions > { functionNameBuilder = camelCase > , requestBody = "body" > , successCallback = "onSuccess" > , errorCallback = "onError" > , moduleName = "" > , urlPrefix = "" > }
Function renamers
concatCase :: FunctionName -> Text
Function name builder that simply concat each part together
snakeCase :: FunctionName -> Text
Function name builder using the snake_case convention. each part is separated by a single underscore character.
camelCase :: FunctionName -> Text
Function name builder using the CamelCase convention. each part begins with an upper case character.
Vanilla Javascript code generation
vanillaJS :: JavaScriptGenerator
Generate vanilla javascript functions to make AJAX requests
to your API, using XMLHttpRequest. Uses defCommonGeneratorOptions
for the CommonGeneratorOptions
.
vanillaJSWith :: CommonGeneratorOptions -> JavaScriptGenerator
Generate vanilla javascript functions to make AJAX requests to your API, using XMLHttpRequest. Lets you specify your own options.
JQuery code generation
Generate javascript functions that use the jQuery library
to make the AJAX calls. Uses defCommonGeneratorOptions
for the generator options.
jqueryWith :: CommonGeneratorOptions -> JavaScriptGenerator
Generate javascript functions that use the jQuery library
to make the AJAX calls. Lets you specify your own CommonGeneratorOptions
.
Angular.js code generation
angular :: AngularOptions -> JavaScriptGenerator
Generate regular javacript functions that use
the $http service, using default values for CommonGeneratorOptions
.
angularWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator
Generate regular javascript functions that use the $http service.
angularService :: AngularOptions -> 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 AngularOptions
.
angularServiceWith :: AngularOptions -> CommonGeneratorOptions -> JavaScriptGenerator
Instead of simply generating top level functions, generates a service instance on which your controllers can depend to access your API
data AngularOptions
Options specific to the angular code generator
AngularOptions | |
|
defAngularOptions :: AngularOptions
Default options for the Angular codegen. Used by wrapInService
.
Axios code generation
axios :: AxiosOptions -> JavaScriptGenerator
Generate regular javacript functions that use
the axios library, using default values for CommonGeneratorOptions
.
axiosWith :: AxiosOptions -> CommonGeneratorOptions -> JavaScriptGenerator
Generate regular javascript functions that use the axios library.
data AxiosOptions
Axios configuration
type
Let you customize the generation using Axios capabilities
AxiosOptions | |
|
defAxiosOptions :: AxiosOptions
Default instance of the AxiosOptions Defines the settings as they are in the Axios documentation by default
Misc.
listFromAPI :: (HasForeign api, GenerateList (Foreign api)) => Proxy api -> [AjaxReq]
Generate the necessary data for JS codegen as a list, each AjaxReq
describing one endpoint from your API type.
javascript :: HasForeign layout => Proxy layout -> Foreign layout
class GenerateList reqs where
Utility class used by jsForAPI
which computes
the data needed to generate a function for each endpoint
and hands it all back in a list.
generateList :: reqs -> [AjaxReq]
GenerateList AjaxReq | |
(GenerateList start, GenerateList rest) => GenerateList ((:<|>) start rest) |