-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Generate TypeScript definition files from your ADTs
--
-- Please see the README on Github at
-- https://github.com/codedownio/aeson-typescript#readme
@package aeson-typescript
@version 0.4.2.0
-- | Internal details. For now, this module just exports the full
-- TSDeclaration constructors. These are subject to breaking changes but
-- are exported here in case you want to live dangerously.
module Data.Aeson.TypeScript.Internal
data TSDeclaration
TSInterfaceDeclaration :: String -> [String] -> [TSField] -> TSDeclaration
[interfaceName] :: TSDeclaration -> String
[interfaceGenericVariables] :: TSDeclaration -> [String]
[interfaceMembers] :: TSDeclaration -> [TSField]
TSTypeAlternatives :: String -> [String] -> [String] -> TSDeclaration
[typeName] :: TSDeclaration -> String
[typeGenericVariables] :: TSDeclaration -> [String]
[alternativeTypes] :: TSDeclaration -> [String]
TSRawDeclaration :: String -> TSDeclaration
[text] :: TSDeclaration -> String
data TSField
TSField :: Bool -> String -> String -> TSField
[fieldOptional] :: TSField -> Bool
[fieldName] :: TSField -> String
[fieldType] :: TSField -> String
-- | 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)) <>
-- ...
-- )
--
module Data.Aeson.TypeScript.TH
-- | Generates a TypeScript instance declaration for the given data
-- type.
deriveTypeScript :: Options -> Name -> Q [Dec]
-- | Generates a TypeScript instance declaration for the given data
-- type.
deriveTypeScript' :: Options -> Name -> ExtraTypeScriptOptions -> Q [Dec]
-- | Generates a TypeScript declaration for a closed type family as
-- a lookup type.
deriveTypeScriptLookupType :: Name -> String -> Q [Dec]
-- | 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) <> "[]";
--
class (Typeable a) => TypeScript a
-- | Get the declaration(s) needed for this type.
getTypeScriptDeclarations :: TypeScript a => Proxy a -> [TSDeclaration]
-- | Get the type as a string.
getTypeScriptType :: TypeScript a => Proxy a -> String
getTypeScriptKeyType :: TypeScript a => Proxy a -> String
-- | Get a flag representing whether this type is optional.
getTypeScriptOptional :: TypeScript a => Proxy a -> Bool
-- | Get the types that this type depends on. This is useful for generating
-- transitive closures of necessary types.
getParentTypes :: TypeScript a => Proxy a -> [TSType]
-- | Special flag to indicate whether this type corresponds to a template
-- variable.
isGenericVariable :: TypeScript a => Proxy a -> Bool
-- | An existential wrapper for any TypeScript instance.
data TSType
TSType :: Proxy a -> TSType
[unTSType] :: TSType -> Proxy a
data TSDeclaration
TSRawDeclaration :: String -> TSDeclaration
-- | Same as formatTSDeclarations', but uses default formatting
-- options.
formatTSDeclarations :: [TSDeclaration] -> String
-- | Format a list of TypeScript declarations into a string, suitable for
-- putting directly into a .d.ts file.
formatTSDeclarations' :: FormattingOptions -> [TSDeclaration] -> String
-- | Format a single TypeScript declaration. This version accepts a
-- FormattingOptions object in case you want more control over the
-- output.
formatTSDeclaration :: FormattingOptions -> TSDeclaration -> String
data FormattingOptions
FormattingOptions :: Int -> (String -> String) -> (String -> String) -> ExportMode -> SumTypeFormat -> FormattingOptions
-- | How many spaces to indent TypeScript blocks
[numIndentSpaces] :: FormattingOptions -> Int
-- | Function applied to generated interface names
[interfaceNameModifier] :: FormattingOptions -> String -> String
-- | Function applied to generated type names
[typeNameModifier] :: FormattingOptions -> String -> String
-- | Whether to include the export keyword in declarations
[exportMode] :: FormattingOptions -> ExportMode
-- | How to format the declaration of the alternatives when multiple
-- constructors exist
[typeAlternativesFormat] :: FormattingOptions -> SumTypeFormat
defaultFormattingOptions :: FormattingOptions
-- | TODO: docstrings here
data SumTypeFormat
TypeAlias :: SumTypeFormat
Enum :: SumTypeFormat
EnumWithType :: SumTypeFormat
data ExportMode
-- | Prefix every declaration with the "export" keyword (suitable for
-- putting in a TypeScripe module)
ExportEach :: ExportMode
-- | No exporting (suitable for putting in a .d.ts file)
ExportNone :: ExportMode
defaultExtraTypeScriptOptions :: ExtraTypeScriptOptions
keyType :: ExtraTypeScriptOptions -> Maybe String
typeFamiliesToMapToTypeScript :: ExtraTypeScriptOptions -> [Name]
-- | Type variable gathering
data ExtraTypeScriptOptions
-- | Convenience typeclass class you can use to "attach" a set of Aeson
-- encoding options to a type.
class HasJSONOptions a
getJSONOptions :: HasJSONOptions a => Proxy a -> Options
-- | 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.
deriveJSONAndTypeScript :: Options -> Name -> Q [Dec]
deriveJSONAndTypeScript' :: Options -> Name -> ExtraTypeScriptOptions -> Q [Dec]
data T
T :: T
data T1
T1 :: T1
data T2
T2 :: T2
data T3
T3 :: T3
module Data.Aeson.TypeScript.Recursive
getTransitiveClosure :: Set TSType -> Set TSType
getTypeScriptDeclarationsRecursively :: TypeScript a => Proxy a -> [TSDeclaration]
recursivelyDeriveMissingTypeScriptInstancesFor :: Monoid w => Name -> (Name -> Q w) -> Q w
recursivelyDeriveMissingInstancesFor :: Monoid w => (Name -> Q Bool) -> Name -> (Name -> Q w) -> Q w
deriveInstanceIfNecessary :: Monoid w => Name -> (Name -> Q w) -> WriterT w Q ()
doesTypeScriptInstanceExist :: Name -> Q Bool
getAllParentTypes :: Name -> (Name -> Q Bool) -> Q [Name]