servant-typescript: TypeScript client generation for Servant

[ bsd3, library, program, web ] [ Propose Tags ]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.0.1, 0.1.0.2
Change log ChangeLog.md
Dependencies aeson, aeson-typescript, base (>=4.7 && <5), containers, directory, filepath, lens, mtl, servant, servant-foreign, servant-typescript, string-interpolate, text [details]
License BSD-3-Clause
Copyright 2022 Tom McLaughlin
Author Tom McLaughlin
Maintainer tom@codedown.io
Category Web
Home page https://github.com/codedownio/servant-typescript#readme
Bug tracker https://github.com/codedownio/servant-typescript/issues
Source repo head: git clone https://github.com/codedownio/servant-typescript
Uploaded by thomasjm at 2022-03-20T03:44:15Z
Distributions NixOS:0.1.0.2
Executables servant-typescript-exe
Downloads 188 total (11 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2022-03-20 [all 1 reports]

Readme for servant-typescript-0.1.0.2

[back to package description]

Welcome to servant-typescript Hackage servant-typescript

This library generates TypeScript client libraries for Servant.

First, make sure you have TypeScript instances defined for all of the types used in the API.

data User = User {
  name :: String
  , age :: Int
  , email :: String
  } deriving (Eq, Show)
deriveJSONAndTypeScript A.defaultOptions ''User

If you need to generate lots of boilerplate instances, the functions in aeson-typescript's Recursive module can be your friend. I've used recursivelyDeriveMissingTypeScriptInstancesFor to derive instances for the Kubernetes API.

Next, you'll need some Servant API:

type UserAPI = "users" :> Get '[JSON] [User]
          :<|> "albert" :> Get '[JSON] User
          :<|> "isaac" :> Get '[JSON] User

Generating the library is as simple as this:

main = writeTypeScriptLibrary (Proxy :: Proxy UserAPI) "/my/destination/folder/"

Caveats

  • This library doesn't yet support generating generic TypeScript functions to match generic TypeScript instances. You can hack around this by writing your own getFunctions and hardcoding them manually for the necessary types.

Supporting additional combinators

If you use unusual Servant combinators in your API, you may need to define additional HasForeign instances to explain how to convert them to TypeScript. For example, when I work with the servant-websockets package, I add instances like the following.

The same applies to custom AuthProtect combinators from Servant.API.Experimental.Auth, etc.

instance HasForeign LangTS Text WebSocket where
    type Foreign Text WebSocket = Text
    foreignFor _ _ _ _ = "void"

instance HasForeign LangTSDecls [TSDeclaration] WebSocket where
    type Foreign [TSDeclaration] WebSocket = [TSDeclaration]
    foreignFor _ _ _ _ = []