#1284: add proper typing for explainTypes

Accenture · Apr 24, 2024 · cca38a1 · cca38a1
1 parent 5384295
commit cca38a1
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 2 deletions.
diff --git a/lib/index.js b/lib/index.js
@@ -33,6 +33,7 @@ import cache from './util/cache.js';
  * @typedef {import('../types/mcdev.d.js').SoapRequestParams} SoapRequestParams
  * @typedef {import('../types/mcdev.d.js').TemplateMap} TemplateMap
  * @typedef {import('../types/mcdev.d.js').TypeKeyCombo} TypeKeyCombo
+ * @typedef {import('../types/mcdev.d.js').ExplainType} ExplainType
  */
 
 /**
@@ -154,7 +155,7 @@ class Mcdev {
         await Cli.selectTypes(properties);
     }
     /**
-     * @returns {object[]} list of supported types with their apiNames
+     * @returns {ExplainType[]} list of supported types with their apiNames
      */
     static explainTypes() {
         return Cli.explainTypes();

diff --git a/lib/util/cli.js b/lib/util/cli.js
@@ -29,6 +29,7 @@ import TransactionalMessage from './../metadataTypes/TransactionalMessage.js';
  * @typedef {import('../../types/mcdev.d.js').SoapRequestParams} SoapRequestParams
  * @typedef {import('../../types/mcdev.d.js').TemplateMap} TemplateMap
  * @typedef {import('../../types/mcdev.d.js').TypeKeyCombo} TypeKeyCombo
+ * @typedef {import('../../types/mcdev.d.js').ExplainType} ExplainType
  */
 
 /**
@@ -603,9 +604,10 @@ const Cli = {
     /**
      * shows metadata type descriptions
      *
-     * @returns {object[]} list of supported types with their apiNames
+     * @returns {ExplainType[]} list of supported types with their apiNames
      */
     explainTypes() {
+        /** @type {ExplainType[]} */
         const json = [];
         const apiNameArr = Object.keys(MetadataDefinitions);
 

diff --git a/types/mcdev.d.js b/types/mcdev.d.js
@@ -444,5 +444,20 @@ complex
  * @property {Function} errorStack (ex, msg) print error with trace message
  * @typedef {import('winston').Logger & McdevLogger} Logger
  */
+/**
+ * @typedef {object} ExplainType
+ * @property {string} name readable name of type
+ * @property {string} apiName api parameter name for type
+ * @property {string} description more info on what this type is about
+ * @property {boolean | string[]} retrieveByDefault is it retrieved by default OR list of subtypes that are retrieved by default
+ * @property {object} supports supported features
+ * @property {boolean} supports.retrieve can you download this type
+ * @property {boolean} supports.create can you create new records of this type
+ * @property {boolean} supports.update can you update records of this type
+ * @property {boolean} supports.delete can you delete records of this type
+ * @property {boolean} supports.changeKey can you change the key of existing records of this type
+ * @property {boolean} supports.buildTemplate can you apply templating on downloaded records of this type
+ * @property {boolean} supports.retrieveAsTemplate can you retrieve & template in one step
+ */
 
 export default {};