Generate TypeScript definitions from ApiInfo

Author: palas

cardano-wasm/app/Main.hs

@@ -1,4 +1,8 @@
-module Main (main) where
+module Main where
+
+import Cardano.Wasm.Internal.Api.Info (apiInfo)
+import Cardano.Wasm.Internal.Api.InfoToTypeScript (apiInfoToTypeScriptFile)
+import Cardano.Wasm.Internal.Api.TypeScriptDefs (printTypeScriptFile)
 
 main :: IO ()
-main = pure ()
+main = printTypeScriptFile (apiInfoToTypeScriptFile apiInfo)

cardano-wasm/cardano-wasm.cabal

@@ -40,7 +40,9 @@ executable cardano-wasm
       "-optl-Wl,--strip-all,--export=getApiInfo,--export=newConwayTx,--export=addTxInput,--export=addSimpleTxOut,--export=setFee,--export=estimateMinFee,--export=signWithPaymentKey,--export=alsoSignWithPaymentKey,--export=txToCbor"
   other-modules:
     Cardano.Wasm.Internal.Api.Info
+    Cardano.Wasm.Internal.Api.InfoToTypeScript
     Cardano.Wasm.Internal.Api.Tx
+    Cardano.Wasm.Internal.Api.TypeScriptDefs
     Cardano.Wasm.Internal.ExceptionHandling
     Cardano.Wasm.Internal.JavaScript.Bridge
 

cardano-wasm/example/cardano-api.d.ts

@@ -1,12 +1,12 @@
 // cardano-api.d.ts
 
-export default initialize;
+export default initialise;
 
 /**
- * Initializes the Cardano API.
+ * Initialises the Cardano API.
  * @returns A promise that resolves to the main `CardanoAPI` object.
  */
-declare function initialize(): Promise<CardanoAPI>;
+declare function initialise(): Promise<CardanoAPI>;
 
 /**
  * Represents an unsigned transaction.
@@ -28,27 +28,27 @@ declare interface UnsignedTx {
     /**
      * Adds a simple transaction output to the transaction.
      * @param destAddr The destination address.
-     * @param lovelaceAmount The amount in lovelace to output.
+     * @param lovelaceAmount The amount in lovelaces to output.
      * @returns The `UnsignedTx` object with the added output.
      */
     addSimpleTxOut(destAddr: string, lovelaceAmount: bigint): UnsignedTx;
 
     /**
      * Sets the fee for the transaction.
-     * @param lovelaceAmount The fee amount in lovelace.
+     * @param lovelaceAmount The fee amount in lovelaces.
      * @returns The `UnsignedTx` object with the set fee.
      */
     setFee(lovelaceAmount: bigint): UnsignedTx;
 
     /**
      * Estimates the minimum fee for the transaction.
      * @param protocolParams The protocol parameters.
-     * @param numExtraKeyWitnesses The number of extra key witnesses (in addition to the ones already added).
-     * @param numExtraByronKeyWitnesses The number of extra Byron key witnesses.
+     * @param numKeyWitnesses The number of key witnesses.
+     * @param numByronKeyWitnesses The number of Byron key witnesses.
      * @param totalRefScriptSize The total size of reference scripts in bytes.
-     * @returns A promise that resolves to the estimated minimum fee in lovelace.
+     * @returns A promise that resolves to the estimated minimum fee in lovelaces.
      */
-    estimateMinFee(protocolParams: any, numExtraKeyWitnesses: number, numExtraByronKeyWitnesses: number, totalRefScriptSize: number): Promise<bigint>;
+    estimateMinFee(protocolParams: any, numKeyWitnesses: number, numByronKeyWitnesses: number, totalRefScriptSize: number): Promise<BigInt>;
 
     /**
      * Signs the transaction with a payment key.
@@ -96,3 +96,4 @@ declare interface CardanoAPI {
      */
     newConwayTx(): Promise<UnsignedTx>;
 }
+

cardano-wasm/example/cardano-api.js

@@ -4,7 +4,7 @@ import { WASI } from "https://unpkg.com/@bjorn3/[email protected]/dist/ind
 import ghc_wasm_jsffi from "./cardano-wasm.js";
 const __exports = {};
 const wasi = new WASI([], [], []);
-async function initialize() {
+async function initialise() {
   let { instance } = await WebAssembly.instantiateStreaming(fetch("./cardano-wasm.wasm"), {
     ghc_wasm_jsffi: ghc_wasm_jsffi(__exports),
     wasi_snapshot_preview1: wasi.wasiImport,
@@ -14,7 +14,7 @@ async function initialize() {
 
   // Wrap a function with variable arguments to make the parameters inspectable
   function fixateArgs(params, func) {
-    const paramString = params.join(',');
+    const paramString = params.map(p => p.name).join(',');
     // Dynamically create a function that captures 'func' from the closure.
     // 'this' and 'arguments' are passed through from the wrapper to 'func'.
     // Using eval allows the returned function to have named parameters for inspectability.
@@ -28,7 +28,7 @@ async function initialize() {
 
   // Same as fixateArgs but for async functions
   async function fixateArgsAsync(params, func) {
-    const paramString = params.join(',');
+    const paramString = params.map(p => p.name).join(',');
     // Dynamically create an async function.
     const wrapper = eval(`
       (async function(${paramString}) {
@@ -82,7 +82,7 @@ async function initialize() {
   });
 
   // Populate the main API object with static methods
-  apiInfo.staticMethods.forEach(method => {
+  apiInfo.mainObject.methods.forEach(method => {
     cardanoAPI[method.name] = async function (...args) {
       const resultPromise = instance.exports[method.name](...args);
 
@@ -95,4 +95,4 @@ async function initialize() {
   });
   return cardanoAPI;
 }
-export default initialize;
+export default initialise;

cardano-wasm/src/Cardano/Wasm/Internal/Api/Info.hs

@@ -1,6 +1,14 @@
 {-# LANGUAGE InstanceSigs #-}
 
-module Cardano.Wasm.Internal.Api.Info (apiInfo) where
+module Cardano.Wasm.Internal.Api.Info
+  ( apiInfo
+  , ApiInfo (..)
+  , VirtualObjectInfo (..)
+  , MethodInfo (..)
+  , ParamInfo (..)
+  , MethodReturnTypeInfo (..)
+  )
+where
 
 import Data.Aeson qualified as Aeson
 import Data.Text qualified as Text
@@ -18,56 +26,84 @@ data MethodReturnTypeInfo
   deriving (Show, Eq)
 
 instance Aeson.ToJSON MethodReturnTypeInfo where
+  toJSON :: MethodReturnTypeInfo -> Aeson.Value
   toJSON Fluent = Aeson.object ["type" Aeson..= Text.pack "fluent"]
   toJSON (NewObject objTypeName) = Aeson.object ["type" Aeson..= Text.pack "newObject", "objectType" Aeson..= objTypeName]
   toJSON (OtherType typeName) = Aeson.object ["type" Aeson..= Text.pack "other", "typeName" Aeson..= typeName]
 
+-- | Information about a single parameter of a method.
+data ParamInfo = ParamInfo
+  { paramName :: String
+  , paramType :: String
+  , paramDoc :: String
+  }
+  deriving (Show, Eq)
+
+instance Aeson.ToJSON ParamInfo where
+  toJSON :: ParamInfo -> Aeson.Value
+  toJSON (ParamInfo name pType doc) =
+    Aeson.object
+      [ "name" Aeson..= name
+      , "type" Aeson..= pType
+      , "doc" Aeson..= doc
+      ]
+
 -- | Information about a single method of a virtual object.
 data MethodInfo = MethodInfo
   { methodName :: String
-  , methodParams :: [String]
+  , methodDoc :: String
+  , methodParams :: [ParamInfo]
   -- ^ Names of parameters, excluding 'this'.
   , methodReturnType :: MethodReturnTypeInfo
+  , methodReturnDoc :: String
   }
   deriving (Show, Eq)
 
 instance Aeson.ToJSON MethodInfo where
   toJSON :: MethodInfo -> Aeson.Value
-  toJSON (MethodInfo name params retType) =
+  toJSON (MethodInfo name doc params retType retDoc) =
     Aeson.object
       [ "name" Aeson..= name
+      , "doc" Aeson..= doc
       , "params" Aeson..= params
       , "return" Aeson..= retType
+      , "returnDoc" Aeson..= retDoc
       ]
 
 -- | Information about a virtual object and its methods.
 data VirtualObjectInfo = VirtualObjectInfo
   { virtualObjectName :: String
+  , virtualObjectDoc :: String
   , virtualObjectMethods :: [MethodInfo]
   }
   deriving (Show, Eq)
 
 instance Aeson.ToJSON VirtualObjectInfo where
   toJSON :: VirtualObjectInfo -> Aeson.Value
-  toJSON (VirtualObjectInfo name methods) =
+  toJSON (VirtualObjectInfo name doc methods) =
     Aeson.object
       [ "objectName" Aeson..= name
+      , "doc" Aeson..= doc
       , "methods" Aeson..= methods
       ]
 
 -- | Aggregate type for all API information.
 data ApiInfo = ApiInfo
-  { staticMethods :: [MethodInfo]
+  { mainObject :: VirtualObjectInfo
   , virtualObjects :: [VirtualObjectInfo]
+  , initialiseFunctionDoc :: String
+  , initialiseFunctionReturnDoc :: String
   }
   deriving (Show, Eq)
 
 instance Aeson.ToJSON ApiInfo where
   toJSON :: ApiInfo -> Aeson.Value
-  toJSON (ApiInfo staticObjs virtualObjs) =
+  toJSON (ApiInfo mainObj virtualObjs initDoc initRetDoc) =
     Aeson.object
-      [ "staticMethods" Aeson..= staticObjs
+      [ "mainObject" Aeson..= mainObj
       , "virtualObjects" Aeson..= virtualObjs
+      , "initialiseFunctionDoc" Aeson..= initDoc
+      , "initialiseFunctionReturnDoc" Aeson..= initRetDoc
       ]
 
 -- | Provides metadata about the "virtual objects" and their methods.
@@ -77,64 +113,101 @@ apiInfo =
   let unsignedTxObjectName = "UnsignedTx"
       signedTxObjectName = "SignedTx"
 
-      staticApiMethods =
-        [ MethodInfo
-            { methodName = "newConwayTx"
-            , methodParams = []
-            , methodReturnType = NewObject unsignedTxObjectName
-            }
-        ]
-
       unsignedTxObj =
         VirtualObjectInfo
           { virtualObjectName = unsignedTxObjectName
+          , virtualObjectDoc = "Represents an unsigned transaction."
           , virtualObjectMethods =
               [ MethodInfo
                   { methodName = "addTxInput"
-                  , methodParams = ["txId", "txIx"]
+                  , methodDoc = "Adds a simple transaction input to the transaction."
+                  , methodParams =
+                      [ ParamInfo "txId" "string" "The transaction ID of the input UTxO."
+                      , ParamInfo "txIx" "number" "The index of the input within the UTxO."
+                      ]
                   , methodReturnType = Fluent
+                  , methodReturnDoc = "The `UnsignedTx` object with the added input."
                   }
               , MethodInfo
                   { methodName = "addSimpleTxOut"
-                  , methodParams = ["destAddr", "lovelaceAmount"]
+                  , methodDoc = "Adds a simple transaction output to the transaction."
+                  , methodParams =
+                      [ ParamInfo "destAddr" "string" "The destination address."
+                      , ParamInfo "lovelaceAmount" "bigint" "The amount in lovelaces to output."
+                      ]
                   , methodReturnType = Fluent
+                  , methodReturnDoc = "The `UnsignedTx` object with the added output."
                   }
               , MethodInfo
                   { methodName = "setFee"
-                  , methodParams = ["lovelaceAmount"]
+                  , methodDoc = "Sets the fee for the transaction."
+                  , methodParams = [ParamInfo "lovelaceAmount" "bigint" "The fee amount in lovelaces."]
                   , methodReturnType = Fluent
-                  }
-              , MethodInfo
-                  { methodName = "signWithPaymentKey"
-                  , methodParams = ["signingKey"]
-                  , methodReturnType = NewObject signedTxObjectName
+                  , methodReturnDoc = "The `UnsignedTx` object with the set fee."
                   }
               , MethodInfo
                   { methodName = "estimateMinFee"
+                  , methodDoc = "Estimates the minimum fee for the transaction."
                   , methodParams =
-                      ["protocolParams", "numKeyWitnesses", "numByronKeyWitnesses", "totalRefScriptSize"]
+                      [ ParamInfo "protocolParams" "any" "The protocol parameters."
+                      , ParamInfo
+                          "numKeyWitnesses"
+                          "number"
+                          "The number of key witnesses."
+                      , ParamInfo "numByronKeyWitnesses" "number" "The number of Byron key witnesses."
+                      , ParamInfo "totalRefScriptSize" "number" "The total size of reference scripts in bytes."
+                      ]
                   , methodReturnType = OtherType "BigInt"
+                  , methodReturnDoc = "A promise that resolves to the estimated minimum fee in lovelaces."
+                  }
+              , MethodInfo
+                  { methodName = "signWithPaymentKey"
+                  , methodDoc = "Signs the transaction with a payment key."
+                  , methodParams = [ParamInfo "signingKey" "string" "The signing key to witness the transaction."]
+                  , methodReturnType = NewObject signedTxObjectName
+                  , methodReturnDoc = "A promise that resolves to a `SignedTx` object."
                   }
               ]
           }
 
       signedTxObj =
         VirtualObjectInfo
           { virtualObjectName = signedTxObjectName
+          , virtualObjectDoc = "Represents a signed transaction."
           , virtualObjectMethods =
               [ MethodInfo
                   { methodName = "alsoSignWithPaymentKey"
-                  , methodParams = ["signingKey"]
+                  , methodDoc = "Adds an extra signature to the transaction with a payment key."
+                  , methodParams = [ParamInfo "signingKey" "string" "The signing key to witness the transaction."]
                   , methodReturnType = Fluent
+                  , methodReturnDoc = "The `SignedTx` object with the additional signature."
                   }
               , MethodInfo
                   { methodName = "txToCbor"
+                  , methodDoc = "Converts the signed transaction to its CBOR representation."
                   , methodParams = []
                   , methodReturnType = OtherType "string"
+                  , methodReturnDoc =
+                      "A promise that resolves to the CBOR representation of the transaction as a hex string."
                   }
               ]
           }
    in ApiInfo
-        { staticMethods = staticApiMethods
+        { mainObject =
+            VirtualObjectInfo
+              { virtualObjectName = "CardanoAPI"
+              , virtualObjectDoc = "The main Cardano API object with static methods."
+              , virtualObjectMethods =
+                  [ MethodInfo
+                      { methodName = "newConwayTx"
+                      , methodDoc = "Creates a new Conway-era transaction."
+                      , methodParams = []
+                      , methodReturnType = NewObject unsignedTxObjectName
+                      , methodReturnDoc = "A promise that resolves to a new `UnsignedTx` object."
+                      }
+                  ]
+              }
         , virtualObjects = [unsignedTxObj, signedTxObj]
+        , initialiseFunctionDoc = "Initialises the Cardano API."
+        , initialiseFunctionReturnDoc = "A promise that resolves to the main `CardanoAPI` object."
         }