infer types via JSDoc through IoC container (#377)

package.json

@@ -1,13 +1,14 @@
 {
   "name": "fauna-shell",
   "description": "faunadb shell",
-  "version": "2.0.2",
+  "version": "3.0.0-beta",
   "author": "Fauna",
   "bin": {
     "fauna": "./yargs-entrypoint.mjs"
   },
   "bugs": "https://github.com/fauna/fauna-shell/issues",
   "dependencies": {
+    "@babel/core": "^7.25.7",
     "@inquirer/prompts": "^3.1.1",
     "@oclif/core": "^4.0.12",
     "@oclif/plugin-help": "^5.2.14",
@@ -45,6 +46,7 @@
     "@types/node": "^20.6.0",
     "@types/sinon": "^17.0.3",
     "@types/supports-color": "^8.1.3",
+    "@types/yargs": "^17.0.33",
     "@typescript-eslint/parser": "6.7.3",
     "c8": "^8.0.1",
     "chai": "^5.1.1",
@@ -54,7 +56,6 @@
     "eslint-plugin-prettier": "^3.4.0",
     "globals": "^15.10.0",
     "husky": "^7.0.4",
-    "jest": "^29.7.0",
     "mocha": "^10.7.3",
     "mocha-junit-reporter": "^2.2.1",
     "mock-require": "^3.0.3",

src/cli.mjs

@@ -1,3 +1,5 @@
+// @ts-check
+
 import yargs from "yargs";
 import chalk from "chalk";
 
@@ -6,9 +8,18 @@ import loginCommand from "./yargs-commands/login.mjs";
 import schemaCommand from "./yargs-commands/schema/schema.mjs";
 import { logArgv } from "./lib/middleware.mjs";
 
+/** @typedef {import('awilix').AwilixContainer<import('./config/setup-container.mjs').modifiedInjectables>} cliContainer */
+
+/** @type {cliContainer} */
 export let container;
+/** @type {yargs.Argv} */
 export let builtYargs;
 
+/**
+ * @function run
+ * @param {string} argvInput - The command string provided by the user or test. Parsed by yargs into an argv object.
+ * @param {cliContainer} _container - A built and ready for use awilix container with registered injectables.
+ */
 export async function run(argvInput, _container) {
   container = _container;
   const logger = container.resolve("logger");
@@ -34,6 +45,11 @@ export async function parseYargs(builtYargs) {
   return builtYargs.parseAsync();
 }
 
+/**
+ * @function buildYargs
+ * @param {string} argvInput
+ * @returns {yargs.Argv<any>}
+ */
 function buildYargs(argvInput) {
   return (
     yargs(argvInput)
@@ -78,7 +94,7 @@ function buildYargs(argvInput) {
           choices: ["fetch", "error", "argv"],
         },
       })
-      .wrap(yargs.terminalWidth)
+      .wrap(yargs.terminalWidth())
       .help("help", "show help")
       .fail(false)
       .exitProcess(false)

src/config/setup-container.mjs

@@ -1,6 +1,6 @@
 import { exit } from "node:process";
 
-import * as awilix from "awilix/lib/awilix.module.mjs";
+import awilix from "awilix";
 
 import { performQuery } from "../yargs-commands/eval.mjs";
 import logger from "../lib/logger.mjs";
@@ -40,6 +40,12 @@ export function setupCommonContainer() {
   return container;
 }
 
+/**
+ * @template T
+ * @typedef {{ [P in keyof T[P]]: ReturnType<T[P]['resolve']> }} Resolvers<T>
+ */
+
+/** @typedef {Resolvers<injectables>} modifiedInjectables */
 export const injectables = {
   // node libraries
   exit: awilix.asValue(exit),
@@ -74,6 +80,7 @@ export const injectables = {
 };
 
 export function setupRealContainer() {
+  /** @type {awilix.AwilixContainer<injectables>} */
   const container = setupCommonContainer();
 
   container.register(injectables);

src/lib/fetch-wrapper.mjs

@@ -1,7 +1,8 @@
 import { container } from "../cli.mjs";
 
 // this wrapper exists for only one reason: logging
-// in the future, it could also be extended for error-handling
+// in the future, it could also be extended for error-handling,
+// analytics, or metrics collection.
 export default async function fetchWrapper(url, options) {
   const logger = container.resolve("logger");
   const method = options?.method || "GET";

src/lib/logger.mjs

@@ -2,12 +2,31 @@ import chalk from "chalk";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
+/**
+ * @typedef argv
+ * @type {object}
+ * @property {Array.<string>} verboseComponent - An array of components to always log information about, regardless of the current verbosity level.
+ * @property {number} verbosity - The highest (least critical) log line to emit, ranging from 4 (debug) to 1 (fatal). Logs above the verbosity level are not emitted.
+ */
+
+/**
+ * Runs the function in the context of a database connection.
+ *
+ * @function
+ * @param {Object} args
+ * @param {string} args.text - The text to log.
+ * @param {number} args.verbosity - The verbosity level for the log line, ranging from 4 (debug) to 1 (fatal). Used to determine the color of the logged text as well as whether or not to emit the log line (and if so, to which stream).
+ * @param {function} args.stream - A function that handles a log line. Typically `console.log` or `console.error`, but could be any function that takes string input.
+ * @param {string} [args.component] - A string that identifies what "component" of the application this is. Included in the log line as a prefix and also used for formatting with verboseComponents
+ * @param {function} [args.formatter] - A function that takes a string and decorates it. Usually used to provide color for the log line.
+ * @param {argv} [args.argv] - The parsed yargs argv. Used to determine the current verbosity and if any components are included in verboseComponents.
+ */
 export function log({
   text,
   verbosity,
   stream,
   component = "unknown",
-  formatter,
+  formatter = (text) => text,
   argv,
 }) {
   // stringified errors come with this prefix; since we're going to add a component
@@ -18,16 +37,18 @@ export function log({
   if (!argv) {
     // we give yargs _just_ enough information that we can use it to parse
     // out the verbosity flags needed by the logger
-    argv = yargs(hideBin(process.argv)).options({
-      verboseComponent: {
-        type: "array",
-        default: [],
-      },
-      verbosity: {
-        type: "number",
-        default: 0,
-      },
-    }).argv;
+    argv = yargs(hideBin(process.argv))
+      .options({
+        verboseComponent: {
+          type: "array",
+          default: [],
+        },
+        verbosity: {
+          type: "number",
+          default: 0,
+        },
+      })
+      .version(false).argv;
   }
 
   if (
@@ -41,6 +62,14 @@ export function log({
   return false;
 }
 
+/**
+ * Log text at a debug log level (verbosity 5).
+ *
+ * @function
+ * @param {string} text - The text to log.
+ * @param {string} [component] - A string that identifies what "component" of the application this is. Included in the log line as a prefix and also used for formatting with verboseComponents
+ * @param {argv} [argv] - The parsed yargs argv. Used to determine the current verbosity and if any components are included in verboseComponents.
+ */
 function debug(text, component, argv) {
   log({
     text,
@@ -52,6 +81,14 @@ function debug(text, component, argv) {
   });
 }
 
+/**
+ * Log text at a info log level (verbosity 4).
+ *
+ * @function
+ * @param {string} text - The text to log.
+ * @param {string} [component] - A string that identifies what "component" of the application this is. Included in the log line as a prefix and also used for formatting with verboseComponents
+ * @param {argv} [argv] - The parsed yargs argv. Used to determine the current verbosity and if any components are included in verboseComponents.
+ */
 function info(text, component, argv) {
   log({
     text,
@@ -63,6 +100,14 @@ function info(text, component, argv) {
   });
 }
 
+/**
+ * Log text at a warn log level (verbosity 3).
+ *
+ * @function
+ * @param {string} text - The text to log.
+ * @param {string} [component] - A string that identifies what "component" of the application this is. Included in the log line as a prefix and also used for formatting with verboseComponents
+ * @param {argv} [argv] - The parsed yargs argv. Used to determine the current verbosity and if any components are included in verboseComponents.
+ */
 function warn(text, component, argv) {
   log({
     text,
@@ -74,6 +119,14 @@ function warn(text, component, argv) {
   });
 }
 
+/**
+ * Log text at a error log level (verbosity 2).
+ *
+ * @function
+ * @param {string} text - The text to log.
+ * @param {string} [component] - A string that identifies what "component" of the application this is. Included in the log line as a prefix and also used for formatting with verboseComponents
+ * @param {argv} [argv] - The parsed yargs argv. Used to determine the current verbosity and if any components are included in verboseComponents.
+ */
 function error(text, component, argv) {
   log({
     text,
@@ -85,6 +138,14 @@ function error(text, component, argv) {
   });
 }
 
+/**
+ * Log text at a fatal log level (verbosity 1).
+ *
+ * @function
+ * @param {string} text - The text to log.
+ * @param {string} [component] - A string that identifies what "component" of the application this is. Included in the log line as a prefix and also used for formatting with verboseComponents
+ * @param {argv} [argv] - The parsed yargs argv. Used to determine the current verbosity and if any components are included in verboseComponents.
+ */
 function fatal(text, component, argv) {
   log({
     text,

src/yargs-commands/schema/schema.mjs

@@ -30,4 +30,5 @@ export default {
   command: "schema",
   describe: "Manipulate Fauna schema state",
   builder: buildSchema,
+  handler: () => {},
 };