add tscheck annotations, add JSDoc types to makeFaunaRequest (#379)

src/lib/command-helpers.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 function buildHeaders() {
   const headers = {
     "X-Fauna-Source": "Fauna Shell",
@@ -14,10 +16,11 @@ export async function getSimpleClient(argv) {
     const faunadb = (await import("faunadb")).default;
     const { Client, query: q } = faunadb;
     const { hostname, port, protocol } = new URL(argv.url);
+    const scheme =  protocol?.replace(/:$/, ""),
     client = new Client({
       domain: hostname,
-      port,
-      scheme: protocol?.replace(/:$/, ""),
+      port: Number(port),
+      scheme: /** @type {('http'|'https')} */ (scheme),
       secret: argv.secret,
       timeout: argv.timeout,
 

src/lib/db.mjs

@@ -1,12 +1,25 @@
+//@ts-check
+
 import { container } from "../cli.mjs";
 
+/**
+  * @function makeFaunaRequest
+  * @param {object} args
+  * @param {string} args.secret - The secret to include in the AUTHORIZATION header of the request.
+  * @param {string} args.baseUrl - The base URL from the scheme up through the top level domain and optional port; defaults to "https://db.fauna.com:443".
+  * @param {string} args.path - The path part of the URL. Added to the baseUrl and params to build the full URL.
+  * @param {Record<string, string>} [args.params] - The parameters (and their values) to set in the query string.
+  * @param {('GET'|'HEAD'|'OPTIONS'|'PATCH'|'PUT'|'POST'|'DELETE'|'PATCH')} args.method - The HTTP method to use when making the request.
+  * @param {object} [args.body] - The body to include in the request.
+  * @param {boolean} [args.shouldThrow] - Whether or not to throw if the network request succeeds but is not a 2XX. If this is set to false, makeFaunaRequest will return the error instead of throwing.
+  */
 export async function makeFaunaRequest({
   secret,
   baseUrl,
   path,
-  params,
+  params = undefined,
   method,
-  body,
+  body = undefined,
   shouldThrow = true,
 }) {
   const fetch = container.resolve("fetch");

src/lib/fauna-account-client.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { container } from "../cli.mjs";
 
 export class FaunaAccountClient {
@@ -44,7 +46,7 @@ export class FaunaAccountClient {
       const { /*state,*/ access_token } = await response.json();
       return access_token;
     } catch (err) {
-      throw new Error("Failure to authorize with Fauna: ", err.message);
+      throw new Error("Failure to authorize with Fauna: " + err.message);
     }
   }
 
@@ -71,8 +73,7 @@ export class FaunaAccountClient {
       return session;
     } catch (err) {
       throw new Error(
-        "Failure to create session with Fauna: ",
-        JSON.stringify(err)
+        "Failure to create session with Fauna: " + JSON.stringify(err)
       );
     }
   }

src/lib/fauna-client.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 // export type QueryResponse<T> = QuerySuccess<T> | QueryFailure;
 import https from "node:https";
 

src/lib/fetch-wrapper.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { container } from "../cli.mjs";
 
 // this wrapper exists for only one reason: logging
@@ -12,7 +14,7 @@ export default async function fetchWrapper(url, options) {
   return fetch(url, options).then(async (response) => {
     const isJSON = response.headers
       .get("content-type")
-      .includes("application/json");
+      ?.includes("application/json");
     let logMessage = `Received ${response.status} of type ${response.type} from ${method} ${url}`;
 
     let body;

src/lib/file-util.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import fs from "node:fs";
 import { normalize } from "node:path";
 

src/lib/middleware.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { container } from "../cli.mjs";
 
 export function logArgv(argv) {

src/yargs-commands/eval.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 const EVAL_OUTPUT_FORMATS = ["json", "json-tagged", "shell"];
 
 import util from "util";
@@ -16,7 +18,7 @@ const { readFile, runQueries, writeFile } = misc;
  * Write json encoded output
  *
  * @param {String} file Target filename
- * @param {Any}    data Data to encode
+ * @param {any}    data Data to encode
  */
 async function writeFormattedJson(file, data) {
   let str = JSON.stringify(data);
@@ -31,7 +33,7 @@ async function writeFormattedJson(file, data) {
  * Write fauna shell encoded output
  *
  * @param {String} file Target filename
- * @param {Any}    data Data to encode
+ * @param {any}    str Data to encode
  */
 async function writeFormattedShell(file, str) {
   if (file === null) {
@@ -63,7 +65,7 @@ async function writeFormattedOutput(file, data, format) {
  * @param {string} fqlQuery - The FQL v4 query to be executed.
  * @param {string} outputFile - Target filename
  * @param {Object} flags - Options for the query execution.
- * @param {(4 | 10)} flags.version - FQL version number
+ * @param {("4" | "10")} flags.version - FQL version number
  * @param {("json" | "json-tagged" | "shell")} flags.format - Result format
  * @param {boolean} [flags.typecheck] - (Optional) Flag to enable typechecking
  */
@@ -185,7 +187,7 @@ async function doEval(argv) {
 
   if (argv.dbname) throw new Error("Not currently supported!");
 
-  const client = container.resolve("getSimpleClient")(argv);
+  const client = await (container.resolve("getSimpleClient")(argv));
 
   const readQuery = argv.stdin || argv.file !== undefined;
   let queryFromFile;

src/yargs-commands/login.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { container } from "../cli.mjs";
 
 async function doLogin() {

src/yargs-commands/schema/abandon.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { confirm } from "@inquirer/prompts";
 
 import { commonQueryOptions } from "../../lib/command-helpers.mjs";

src/yargs-commands/schema/commit.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { confirm } from "@inquirer/prompts";
 
 import { commonQueryOptions } from "../../lib/command-helpers.mjs";

src/yargs-commands/schema/diff.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import chalk from "chalk";
 
 import { container } from "../../cli.mjs";

src/yargs-commands/schema/pull.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { container } from "../../cli.mjs";
 import { commonQueryOptions } from "../../lib/command-helpers.mjs";
 

src/yargs-commands/schema/push.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { container } from "../../cli.mjs";
 import { confirm } from "@inquirer/prompts";
 import { commonQueryOptions } from "../../lib/command-helpers.mjs";
@@ -24,7 +26,7 @@ async function doPush(argv) {
   } else {
     // Confirm diff, then push it. `force` is set on `validate` so we don't
     // need to pass the last known schema version through.
-    const params = new URLSearchParams({ force: true });
+    const params = new URLSearchParams({ force: "true" });
     if (argv.color) params.set("color", "ansi");
 
     const response = await makeFaunaRequest({

src/yargs-commands/schema/schema.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import abandonCommand from "./abandon.mjs";
 import commitCommand from "./commit.mjs";
 import diffCommand from "./diff.mjs";

src/yargs-commands/schema/status.mjs

@@ -1,3 +1,5 @@
+//@ts-check
+
 import { container } from "../../cli.mjs";
 import { commonQueryOptions } from "../../lib/command-helpers.mjs";