HORIZON HASKELLDocslts/ghc-9.14.x45dd5372026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 45dd537 · 2026-10-11

Moduleaeson-typescript-0.6.4.0Haskell2010

Data.Aeson.TypeScript.TH

This library provides a way to generate TypeScript .d.ts files that match your existing Aeson ToJSON instances. If you already use Aeson's Template Haskell support to derive your instances, then deriving TypeScript is as simple as

$(deriveTypeScript myAesonOptions ''MyType)

For example,

data D a = Nullary
         | Unary Int
         | Product String Char a
         | Record { testOne   :: Double
                  , testTwo   :: Bool
                  , testThree :: D a
                  } deriving Eq

Next we derive the necessary instances.

$(deriveTypeScript (defaultOptions {fieldLabelModifier = drop 4, constructorTagModifier = map toLower}) ''D)

Now we can use the newly created instances.

>>> putStrLn $ formatTSDeclarations $ getTypeScriptDeclarations (Proxy :: Proxy (D T))

type D<T> = INullary<T> | IUnary<T> | IProduct<T> | IRecord<T>;

interface INullary<T> {
  tag: "nullary";
}

interface IUnary<T> {
  tag: "unary";
  contents: number;
}

interface IProduct<T> {
  tag: "product";
  contents: [string, string, T];
}

interface IRecord<T> {
  tag: "record";
  One: number;
  Two: boolean;
  Three: D<T>;
}

It's important to make sure your JSON and TypeScript are being derived with the same options. For this reason, we include the convenience HasJSONOptions typeclass, which lets you write the options only once, like this:

instance HasJSONOptions MyType where getJSONOptions _ = (defaultOptions {fieldLabelModifier = drop 4})

$(deriveJSON (getJSONOptions (Proxy :: Proxy MyType)) ''MyType)
$(deriveTypeScript (getJSONOptions (Proxy :: Proxy MyType)) ''MyType)

Or, if you want to be even more concise and don't mind defining the instances in the same file,

myOptions = defaultOptions {fieldLabelModifier = drop 4}

$(deriveJSONAndTypeScript myOptions ''MyType)

Remembering that the Template Haskell Q monad is an ordinary monad, you can derive instances for several types at once like this:

$(mconcat <$> traverse (deriveJSONAndTypeScript myOptions) [''MyType1, ''MyType2, ''MyType3])

Once you've defined all necessary instances, you can write a main function to dump them out into a .d.ts file. For example:

main = putStrLn $ formatTSDeclarations (
  (getTypeScriptDeclarations (Proxy :: Proxy MyType1)) <>
  (getTypeScriptDeclarations (Proxy :: Proxy MyType2)) <>
  ...
)
  • 17 types
  • 2 classes
  • 13 values

The main typeclass

3 declarations
classclass Typeable a => TypeScript (a :: k) where
#

The typeclass that defines how a type is turned into TypeScript.

The getTypeScriptDeclarations method describes the top-level declarations that are needed for a type, while getTypeScriptType describes how references to the type should be translated. The getTypeScriptOptional method exists purely so that Maybe types can be encoded with a question mark.

Instances for common types are built-in and are usually very simple; for example,

instance TypeScript Bool where
  getTypeScriptType _ = "boolean"

Most of the time you should not need to write instances by hand; in fact, the TSDeclaration constructors are deliberately opaque. However, you may occasionally need to specify the type of something. For example, since UTCTime is encoded to a JSON string and is not built-in to this library:

import Data.Time.Clock (UTCTime)

instance TypeScript UTCTime where
  getTypeScriptType _ = "string"

If you need to write a definition for a higher-order type, it may depend on a type parameter. For example, a Set is encoded to a JSON list of the underlying type:

instance (TypeScript a) => TypeScript (Set a) where
  getTypeScriptType _ = getTypeScriptType (Proxy :: Proxy a) <> "[]";

Methods

Instances48TypeScript, …
datadata TSType
#

An existential wrapper for any TypeScript instance.

Constructors

Instances3Eq, Ord, Show
  • Eq TSTypeDefined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
  • Ord TSTypeDefined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
  • Show TSTypeDefined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types

Formatting declarations

8 declarations
datadata ExportMode
#

Constructors

  • ExportEach

    Prefix every declaration with the "export" keyword (suitable for putting in a TypeScripe module)

  • ExportNone

    No exporting (suitable for putting in a .d.ts file)

Advanced options

4 declarations

Convenience tools

14 declarations
valuederiveJSONAndTypeScript
  1. :: Options

    Encoding options.

  2. -> Name

    Name of the type for which to generate ToJSON, FromJSON, and TypeScript instance declarations.

  3. -> Q [Dec]
#

Convenience function to generate ToJSON, FromJSON, and TypeScript instances simultaneously, so the instances are guaranteed to be in sync.

This function is given mainly as an illustration. If you want some other permutation of instances, such as ToJSON and TypeScript only, just take a look at the source and write your own version.

datadata T
#
T
Instances1TypeScript
  • TypeScript TDefined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T1
#
T1
Instances1TypeScript
  • TypeScript T1Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T2
#
T2
Instances1TypeScript
  • TypeScript T2Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T3
#
T3
Instances1TypeScript
  • TypeScript T3Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T4
#
T4
Instances1TypeScript
  • TypeScript T4Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T5
#
T5
Instances1TypeScript
  • TypeScript T5Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T6
#
T6
Instances1TypeScript
  • TypeScript T6Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T7
#
T7
Instances1TypeScript
  • TypeScript T7Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T8
#
T8
Instances1TypeScript
  • TypeScript T8Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T9
#
T9
Instances1TypeScript
  • TypeScript T9Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types
datadata T10
#
T10
Instances1TypeScript
  • TypeScript T10Defined in aeson-typescript-0.6.4.0 · Data.Aeson.TypeScript.Types