PKG -- [fcl] Generate types from JSDoc (#1555)

* PKG -- [fcl] Generate types from JSDoc * PKG -- [fcl] Update types path * PKG -- [fcl] remove lint * PKG -- [root] build types at root * PKG -- [fcl] Generate types from JSDoc * PKG -- [fcl] Update types path * PKG -- [fcl] remove lint * PKG -- [root] build types at root * PKG -- [fcl] Add subpackage types * PKG -- [fcl] Add dev dep * PKG -- [fcl] Add dev dep * PKG -- [fcl] remove * PKG -- [fcl] Fix tests running * PKG -- [fcl] Cleanup types * PKG -- [fcl] Cleanup types * PKG -- [fcl] Cleanup types * FCL -- [fcl] Add JSDoc for Wallet Utils send msg * PKG -- [fcl] Add JSDoc for on message * PKG -- [fcl] Add CompositeSignature class * PKG -- [fcl] Add description tags * PKG -- [fcl] Clean up chain id * PKG -- [fcl] Add ix template jsdoc * Update packages/fcl/src/interaction-template-utils/generate-template-interface-id.js Co-authored-by: Jeff Doyle <jeffrey.doyle@dapperlabs.com> * Update packages/fcl/src/interaction-template-utils/get-template-message.js Co-authored-by: Jeff Doyle <jeffrey.doyle@dapperlabs.com> * Update packages/fcl/src/interaction-template-utils/verify-dependency-pin-same-at-block.js Co-authored-by: Jeff Doyle <jeffrey.doyle@dapperlabs.com> * Update packages/fcl/src/interaction-template-utils/verify-dependency-pin-same-at-block.js Co-authored-by: Jeff Doyle <jeffrey.doyle@dapperlabs.com> * Update packages/fcl/src/interaction-template-utils/get-interaction-template-audits.js Co-authored-by: Jeff Doyle <jeffrey.doyle@dapperlabs.com> * PKG -- [fcl] Add config to types * PKG -- [fcl] Add sdk * PKG -- [sdk] Fix type * PKG -- [fcl] remove repetitive globs --------- Co-authored-by: Chase Fleming <1666730+chasefleming@users.noreply.github.com> Co-authored-by: Jeff Doyle <jeffrey.doyle@dapperlabs.com>
onflow · Mar 6, 2023 · fd22870 · fd22870
1 parent 74c75d5
commit fd22870
Show file tree

Hide file tree

Showing 27 changed files with 258 additions and 40 deletions.
diff --git a/Makefile b/Makefile
@@ -22,6 +22,8 @@ clean:
 	$(EXEC) sh -c 'rm -rf $$0/node_modules'
 	$(info delete packages/*/dist)
 	$(EXEC) sh -c 'rm -rf $$0/dist'
+	$(info delete packages/*/types)
+	$(EXEC) sh -c 'rm -rf $$0/types'
 
 .PHONY: install
 install:

diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/fcl/.gitignore b/packages/fcl/.gitignore
@@ -0,0 +1 @@
+types/
diff --git a/packages/fcl/package.json b/packages/fcl/package.json
@@ -24,20 +24,24 @@
   },
   "devDependencies": {
     "@onflow/fcl-bundle": "^1.2.0",
+    "@types/node": "^18.13.0",
     "jest": "^27.0.6",
-    "jest-esm-transformer": "1.0.0"
+    "jest-esm-transformer": "1.0.0",
+    "typescript": "^4.9.5"
   },
   "source": "src/fcl.js",
   "main": "dist/fcl.js",
   "module": "dist/fcl.module.js",
   "unpkg": "dist/fcl.umd.min.js",
+  "types": "types/fcl.d.ts",
   "scripts": {
     "pain": "npm publish --tag pain",
     "alpha": "npm publish --tag alpha",
     "prepublishOnly": "npm test && npm run build",
     "test": "jest",
     "test:watch": "jest --watch",
     "build": "fcl-bundle",
+    "build:types": "tsc",
     "start": "fcl-bundle --watch"
   },
   "dependencies": {

diff --git a/packages/fcl/src/app-utils/verify-signatures.js b/packages/fcl/src/app-utils/verify-signatures.js
@@ -92,6 +92,7 @@ const getVerifySignaturesScript = async (sig, opts) => {
 }
 
 /**
+ * @description
  * Verify a valid account proof signature or signatures for an account on Flow.
  *
  * @param {string} appIdentifier - A message string in hexadecimal format
@@ -117,7 +118,6 @@ const getVerifySignaturesScript = async (sig, opts) => {
  *    {fclCryptoContract}
  *  )
  */
-
 export async function verifyAccountProof(
   appIdentifier,
   {address, nonce, signatures},
@@ -146,6 +146,7 @@ export async function verifyAccountProof(
 }
 
 /**
+ * @description
  * Verify a valid signature/s for an account on Flow.
  *
  * @param {string} msg - A message string in hexadecimal format

diff --git a/packages/fcl/src/exec/mutate.js b/packages/fcl/src/exec/mutate.js
@@ -10,22 +10,11 @@ import {preMutate} from "./utils/pre.js"
  *
  *  @param {Object} opts - Mutation Options and configuration
  *  @param {string} opts.cadence - Cadence Transaction used to mutate Flow
- *  @param {ArgsFn} [opts.args] - Arguments passed to cadence transaction
+ *  @param {import("../fcl").ArgsFn} [opts.args] - Arguments passed to cadence transaction
  *  @param {Object} [opts.template] - Interaction Template for a transaction
  *  @param {number} [opts.limit] - Compute Limit for transaction
  *  @returns {string} Transaction Id
  *
- *  Where:
- *    @callback ArgsFn
- *    @param {ArgFn}  arg - Argument function to define a single argument
- *    @param {Object} t   - Cadence Types object used to define the type
- *    @returns {args[]}
- *
- *    @callback ArgFn
- *    @param {Any}  value - the value of the argument
- *    @param {Type} type  - the cadence type of the value
- *    @returns {arg}
- *
  * @example
  *    fcl.mutate({
  *      cadence: `

diff --git a/packages/fcl/src/exec/query.js b/packages/fcl/src/exec/query.js
@@ -7,23 +7,12 @@ import {preQuery} from "./utils/pre.js"
  * @description
  * Allows you to submit scripts to query the blockchain.
  *
- *  @param {Object} opts         - Query Options and configuration
+ *  @param {Object} opts - Query Options and configuration
  *  @param {string} opts.cadence - Cadence Script used to query Flow
- *  @param {ArgsFn} [opts.args]    - Arguments passed to cadence script
+ *  @param {import("../fcl").ArgsFn} [opts.args] - Arguments passed to cadence script
  *  @param {Object} [opts.template] - Interaction Template for a script
  *  @param {number} [opts.limit]   - Compute Limit for Query
- *  @returns {Promise<Response>}
- *
- *  Where:
- *    @callback ArgsFn
- *    @param {ArgFn}  arg - Argument function to define a single argument
- *    @param {Object} t   - Cadence Types object used to define the type
- *    @returns {args[]}
- *
- *    @callback ArgFn
- *    @param {Any}  value - the value of the argument
- *    @param {Type} type  - the cadence type of the value
- *    @returns {arg}
+ *  @returns {Promise}
  *
  *  @example
  *    const cadence = `

diff --git a/packages/fcl/src/fcl.js b/packages/fcl/src/fcl.js
@@ -78,3 +78,17 @@ export {ref} from "@onflow/sdk"
 export {params, param} from "@onflow/sdk"
 export {validator} from "@onflow/sdk"
 export {invariant} from "@onflow/sdk"
+
+/**
+ * @callback ArgsFn
+ * @param {ArgFn} arg - Argument function to define a single argument
+ * @param {Object} t - Cadence Types object used to define the type
+ * @returns {any[]}
+ */
+
+/**
+ * @callback ArgFn
+ * @param {any} value - the value of the argument
+ * @param {Type} type - the cadence type of the value
+ * @returns {any}
+ */
diff --git a/packages/fcl/src/interaction-template-utils/derive-cadence-by-network.js b/packages/fcl/src/interaction-template-utils/derive-cadence-by-network.js
@@ -1,6 +1,14 @@
 import {invariant} from "@onflow/sdk"
 import {normalizeInteractionTemplate} from "../normalizers/interaction-template/interaction-template"
 
+/**
+ * @description Fills import addresses in Cadence for network
+ * 
+ * @param {Object} params
+ * @param {string} params.network - Network to derive Cadence for
+ * @param {Object} params.template - Interaction Template to derive Cadence from
+ * @returns {string} - Cadence
+ */
 export function deriveCadenceByNetwork({network, template}) {
   invariant(
     network != undefined,

diff --git a/packages/fcl/src/interaction-template-utils/generate-dependency-pin.js b/packages/fcl/src/interaction-template-utils/generate-dependency-pin.js
@@ -11,6 +11,14 @@ import {genHash} from "./utils/hash.js"
 import {findImports} from "./utils/find-imports.js"
 import {generateImport} from "./utils/generate-import.js"
 
+/**
+ * @description Produces a dependency pin for a contract at a given block height
+ * @param {Object} params
+ * @param {string} params.address - The address of the account containing the contract
+ * @param {string} params.contractName - The name of the contract
+ * @param {number} params.blockHeight - The block height to produce the dependency pin for
+ * @returns {Promise<string>} - The dependency pin
+ */
 export async function generateDependencyPin(
   {address, contractName, blockHeight},
   opts = {}
@@ -72,6 +80,9 @@ export async function generateDependencyPin(
   return genHash(contractHashesJoined)
 }
 
+/**
+ * @description Produces a dependency pin for a contract at latest sealed block
+ */
 export async function generateDependencyPinAtLatestSealedBlock(
   {address, contractName},
   opts = {}

diff --git a/packages/fcl/src/interaction-template-utils/generate-template-id.js b/packages/fcl/src/interaction-template-utils/generate-template-id.js
@@ -3,6 +3,13 @@ import {encode as rlpEncode} from "@onflow/rlp"
 import {genHash} from "./utils/hash.js"
 import {normalizeInteractionTemplate} from "../normalizers/interaction-template/interaction-template.js"
 
+/**
+ * @description Generates Interaction Template ID for a given Interaction Template
+ *  
+ * @param {Object} params
+ * @param {Object} params.template - Interaction Template
+ * @returns {Promise<string>} - Interaction Template ID
+ */
 export async function generateTemplateId({template}) {
   invariant(
     template != undefined,

diff --git a/packages/fcl/src/interaction-template-utils/generate-template-interface-id.js b/packages/fcl/src/interaction-template-utils/generate-template-interface-id.js
@@ -3,6 +3,13 @@ import {encode as rlpEncode} from "@onflow/rlp"
 import {genHash} from "./utils/hash.js"
 import {normalizeInteractionTemplateInterface} from "../normalizers/interaction-template/interaction-template-interface.js"
 
+/**
+ * @description Generates Interaction Template Interface ID for a given Interaction Template Interface
+ * 
+ * @param {Object} params
+ * @param {Object} params.templateInterface - Interaction Template Interface
+ * @returns {Promise<string>} - Interaction Template Interface ID
+ */
 export async function generateTemplateInterfaceId({templateInterface}) {
   invariant(
     templateInterface != undefined,

diff --git a/packages/fcl/src/interaction-template-utils/get-interaction-template-audits.js b/packages/fcl/src/interaction-template-utils/get-interaction-template-audits.js
@@ -5,6 +5,16 @@ import {generateTemplateId} from "./generate-template-id.js"
 import {normalizeInteractionTemplate} from "../normalizers/interaction-template/interaction-template.js"
 import {getChainId} from "../utils"
 
+/**
+ * @description Returns whether a set of auditors have audited a given Interaction Template
+ * 
+ * @param {Object} params
+ * @param {Object} params.template - Interaction Template
+ * @param {Array<string>} params.auditors - Array of auditors
+ * @param {Object} opts
+ * @param {string} opts.flowInteractionAuditContract - Flow Interaction Template Audit contract address
+ * @returns {Promise<Object>} - Object of auditor addresses and audit status
+ */
 export async function getInteractionTemplateAudits(
   {template, auditors},
   opts = {}

diff --git a/packages/fcl/src/interaction-template-utils/get-template-argument-message.js b/packages/fcl/src/interaction-template-utils/get-template-argument-message.js
@@ -1,5 +1,15 @@
 import {invariant} from "@onflow/sdk"
 
+/**
+ * @description Gets Interaction Template argument message by message key, argument label, and localization
+ * 
+ * @param {Object} opts
+ * @param {string} opts.localization [localization="en-US"] - Localization to get message for
+ * @param {string} opts.argumentLabel - Argument label to get message for
+ * @param {string} opts.messageKey - Message key to get message for
+ * @param {Object} opts.template - Interaction Template to get message from
+ * @returns {string} - Message
+ */
 export function getTemplateArgumentMessage({
   localization = "en-US",
   argumentLabel,

diff --git a/packages/fcl/src/interaction-template-utils/get-template-message.js b/packages/fcl/src/interaction-template-utils/get-template-message.js
@@ -1,5 +1,14 @@
 import {invariant} from "@onflow/sdk"
 
+/**
+ * @description Get Interaction Template argument message
+ * 
+ * @param {Object} params
+ * @param {string} params.localization [localization="en-US"] - Localization code
+ * @param {string} params.messageKey - Message key
+ * @param {Object} params.template - Interaction Template
+ * @returns {string} - Message
+ */
 export function getTemplateMessage({
   localization = "en-US",
   messageKey,

diff --git a/packages/fcl/src/interaction-template-utils/verify-dependency-pin-same-at-block.js b/packages/fcl/src/interaction-template-utils/verify-dependency-pin-same-at-block.js
@@ -3,6 +3,16 @@ import {invariant, block} from "@onflow/sdk"
 import {log, LEVELS} from "@onflow/util-logger"
 import {normalizeInteractionTemplate} from "../normalizers/interaction-template/interaction-template.js"
 
+/**
+ * @description Checks if an Interaction Template's pins match those generated at a block height
+ * 
+ * @param {Object} params
+ * @param {Object} params.template - Interaction Template to check pins for
+ * @param {number} params.blockHeight - Block height to check pins at
+ * @param {string} params.network - Network to check pins on
+ * @param {Object} opts
+ * @returns {Promise<boolean>} - Whether or not the pins match
+ */
 export async function verifyDependencyPinsSame(
   {template, blockHeight, network},
   opts = {}
@@ -92,6 +102,15 @@ export async function verifyDependencyPinsSame(
   }
 }
 
+/**
+ * @description Checks if an Interaction Template's pins match those generated at the latest block height
+ * 
+ * @param {Object} params
+ * @param {Object} params.template - Interaction Template to check pins for
+ * @param {string} params.network - Network to check pins on
+ * @param {Object} opts
+ * @returns {Promise<boolean>} - Whether or not the pins match
+ */
 export async function verifyDependencyPinsSameAtLatestSealedBlock(
   {template, network},
   opts = {}