v3 last review

.github/workflows/release.yml

@@ -24,6 +24,9 @@ jobs:
 
       - run: npm ci
 
+      - name: Run tests
+        run: npm test
+
       - name: Publish to NPM
         run: npm publish --provenance
 

.gitignore

@@ -31,6 +31,8 @@ node_modules
 
 # Optional REPL history
 .node_repl_history
-test/
 
-.DS_Store
+.DS_Store
+*.zip
+*.tar
+*.tar.gz

README.md

@@ -34,6 +34,7 @@ $ gfcli install "Open Sans" -v regular,700
 	- [homebrew](#homebrew-using-tap)
 - [CLI](#cli)
 	- [Search a font](#search-a-font)
+	- [Caching](#caching)
 	- [Download a font](#download-a-font)
 	- [Install a font](#install-a-font)
 	- [Copy font CSS URL](#copy-font-css-url)
@@ -74,6 +75,12 @@ $ brew install gfcli
 
 From your terminal emulator, you can use the command `gfcli`
 
+### Caching
+
+- The Google Fonts metadata list is cached for 24h at `~/.gfcli/cache.json`.
+- Use `--refresh-cache` on any command to force a fresh download.
+- If the cache is valid, commands skip the download step for faster startup.
+
 ### Search a font
 
 ```
@@ -85,7 +92,7 @@ For instance, search for _Source Sans_ or _Sans Source_ will produce the same re
 ### Download a font
 
 ```
-$ gfcli download [family_name] [-d|--dest destination_folder] [-v|--variants comma_separeted_variants] [--ttf|--woff2]
+$ gfcli download [family_name|"family1,family2"] [-d|--dest destination_folder] [-v|--variants comma_separated_variants] [--ttf|--woff2] [--refresh-cache]
 ```
 
 If **family_name** will match more than one family, nothing will be downloaded: a list of alternatives will help you better specify the font family name.
@@ -95,16 +102,20 @@ Download command accepts these options:
 - `-v` or `--variants` let you specify which variants of the font will be downloaded. You have to write each variant separated by the other with a comma. For example `$ gfcli download Source Sans Pro -v 300,400`. If omitted, all variants will be downloaded.
 - `--ttf` downloads the font in TTF format (default)
 - `--woff2` downloads the font in WOFF2 format (optimized for web use)
+- Multiple families: pass a comma-separated list in quotes, e.g. `$ gfcli download "Inter,Roboto" --woff2 -d ./fonts`
+- `--refresh-cache` forces a fresh font list download and ignores the local cache
 
 ### Install a font
 ```
-$ gfcli install [family_name] [-v|--variants comma_separeted_variants]
+$ gfcli install [family_name|"family1,family2"] [-v|--variants comma_separated_variants] [--refresh-cache]
 ```
 
 If **family_name** will match more than one family, nothing will be installed: a list of alternatives will help you better specify the font family name.
 
 Install command accepts only one option:
 - `-v` or `--variants` let you specify which variants of the font will be installed. You have to write each variant separated by the other with a comma. For example `$ gfcli install Source Sans Pro -v 300,400`. If omitted, all variants will be downloaded.
+- Multiple families: pass a comma-separated list in quotes, e.g. `$ gfcli install "Inter,Roboto" -v 400,700`
+- `--refresh-cache` forces a fresh font list download and ignores the local cache
 
 ### Copy font CSS url
 ```
@@ -154,6 +165,21 @@ Inter variant 200 downloaded in /home/user/someFolder/Inter-200.woff2
 ...
 ```
 
+**Download Inter and Roboto in one command (WOFF2)**
+```
+$ gfcli download "Inter,Roboto" --woff2 -d ./fonts
+```
+
+**Install Inter and Roboto with selected variants**
+```
+$ gfcli install "Inter,Roboto" -v regular,700
+```
+
+**Force refresh of the cached font list**
+```
+$ gfcli search inter --refresh-cache
+```
+
 **Install Lato 100**
 ```
 $ gfcli install lato -v 100

cli.js

@@ -1,37 +1,79 @@
 #!/usr/bin/env node
+// @ts-check
 
 "use strict";
 
-const program = require("commander");
+/**
+ * @typedef {import('./lib/types').GoogleFontListInstance} GoogleFontListInstance
+ * @typedef {import('./lib/types').GoogleFontInstance} GoogleFontInstance
+ * @typedef {import('./lib/types').FontResult} FontResult
+ */
+
+const { Command } = require("commander");
 const pc = require("picocolors");
 const ncp = require("copy-paste-win32fix");
 const GoogleFontList = require("./lib/google-font-list");
 const pjson = require("./package.json");
 
+/** @type {any} */
 const fontList = new GoogleFontList();
+const program = new Command();
+
+program.option("--refresh-cache", "Refresh the cached Google font list");
 
 /**
- * Helper to wrap fontList initialization in a Promise
+ * Split comma-separated font family arguments into an array
+ * @param {string[]} familyArgs - Array of family arguments
+ * @returns {string[]} Array of trimmed family names
  */
-const ensureFontsLoaded = () =>
-  new Promise((resolve) => {
-    if (fontList.loaded) return resolve();
-    console.log(pc.bold(pc.blue("\nDownloading Google Font List...\n")));
-    fontList.on("success", resolve);
-    fontList.on("error", (err) => {
-      console.error(pc.bold(pc.red("Error loading font list!")));
-      console.error(pc.red(err.toString()));
-      process.exit(1);
+const splitFamilies = (familyArgs) =>
+  familyArgs
+    .join(" ")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+/**
+ * Promisified wrapper for getFontByName
+ * @param {string} term - Font family name to search
+ * @returns {Promise<any>} Filtered font list
+ */
+const getFontByNameAsync = (term) =>
+  new Promise((resolve, reject) => {
+    fontList.getFontByName(term, (/** @type {Error | null} */ err, /** @type {any} */ filtered) => {
+      if (err) return reject(err);
+      resolve(filtered);
     });
   });
 
+/**
+ * Helper to wrap fontList initialization in a Promise
+ * @param {boolean} [refreshCache=false] - Whether to force refresh the cache
+ * @returns {Promise<void>}
+ */
+const ensureFontsLoaded = async (refreshCache = false) => {
+  if (refreshCache) {
+    fontList.loaded = false;
+    console.log(pc.bold(pc.blue("\nRefreshing Google Font List cache...\n")));
+  }
+  if (fontList.loaded) return;
+  try {
+    await fontList.load(refreshCache);
+  } catch (err) {
+    console.error(pc.bold(pc.red("Error loading font list!")));
+    console.error(pc.red(err.toString()));
+    process.exit(1);
+  }
+};
+
 program.version(pjson.version);
 
 program
   .command("search [family...]")
   .description("Search for a font family")
   .action(async (family) => {
-    await ensureFontsLoaded();
+    const refresh = program.opts().refreshCache;
+    await ensureFontsLoaded(refresh);
     const term = family ? family.join(" ") : "";
     fontList.searchFontByName(term, printFontList);
   });
@@ -44,53 +86,137 @@ program
   .option("--ttf", "Download TTF format (default)")
   .option("--woff2", "Download WOFF2 format")
   .action(async (family, options) => {
-    await ensureFontsLoaded();
-    const term = family.join(" ");
+    const refresh = program.opts().refreshCache;
     const variants = options.variants ? options.variants.split(",") : false;
     const format = options.woff2 ? "woff2" : "ttf";
+    const families = splitFamilies(family);
 
-    fontList.getFontByName(term, (err, filteredList) => {
-      if (err || filteredList.data.length !== 1) {
-        handleMatchError("Download", term, err);
-        return;
+    try {
+      await ensureFontsLoaded(refresh);
+      /** @type {FontResult[]} */
+      let allResults = [];
+      let successCount = 0;
+      let failCount = 0;
+
+      for (const term of families) {
+        try {
+          const filteredList = await getFontByNameAsync(term);
+          if (filteredList.data.length !== 1) {
+            handleMatchError("Download", term, null);
+            failCount++;
+            continue;
+          }
+          const font = filteredList.getFirst();
+          if (!font) {
+            handleMatchError("Download", term, null);
+            failCount++;
+            continue;
+          }
+          const result = await font.saveAtAsync(variants, options.dest, format);
+          allResults = allResults.concat(result);
+          successCount++;
+        } catch (err) {
+          handleMatchError("Download", term, /** @type {Error} */ (err));
+          failCount++;
+        }
       }
-      filteredList.getFirst().saveAt(variants, options.dest, format, printResult);
-    });
+
+      if (allResults.length > 0) {
+        printResult(null, allResults);
+      }
+
+      // If all operations failed, exit with error
+      if (failCount > 0 && successCount === 0) {
+        console.error(pc.red(pc.bold(`\nAll ${failCount} font download(s) failed.`)));
+        process.exit(1);
+      }
+
+      // Report partial failures
+      if (failCount > 0 && successCount > 0) {
+        console.log(pc.yellow(`\n${successCount} font(s) downloaded successfully, ${failCount} failed.`));
+      }
+    } catch (err) {
+      console.error(pc.red(/** @type {Error} */ (err).toString()));
+      process.exit(1);
+    }
   });
 
 program
   .command("install <family...>")
   .description("Install a font family to the system")
   .option("-v, --variants <variants>", "Variants separated by comma")
   .action(async (family, options) => {
-    await ensureFontsLoaded();
-    const term = family.join(" ");
+    const refresh = program.opts().refreshCache;
     const variants = options.variants ? options.variants.split(",") : false;
+    const families = splitFamilies(family);
 
-    fontList.getFontByName(term, (err, filteredList) => {
-      if (err || filteredList.data.length !== 1) {
-        handleMatchError("Installation", term, err);
-        return;
+    try {
+      await ensureFontsLoaded(refresh);
+      /** @type {FontResult[]} */
+      let allResults = [];
+      let successCount = 0;
+      let failCount = 0;
+
+      for (const term of families) {
+        try {
+          const filteredList = await getFontByNameAsync(term);
+          if (filteredList.data.length !== 1) {
+            handleMatchError("Installation", term, null);
+            failCount++;
+            continue;
+          }
+          const font = filteredList.getFirst();
+          if (!font) {
+            handleMatchError("Installation", term, null);
+            failCount++;
+            continue;
+          }
+          const result = await font.installAsync(variants);
+          allResults = allResults.concat(result);
+          successCount++;
+        } catch (err) {
+          handleMatchError("Installation", term, /** @type {Error} */ (err));
+          failCount++;
+        }
       }
-      filteredList.getFirst().install(variants, printResult);
-    });
+
+      if (allResults.length > 0) {
+        printResult(null, allResults);
+      }
+
+      // If all operations failed, exit with error
+      if (failCount > 0 && successCount === 0) {
+        console.error(pc.red(pc.bold(`\nAll ${failCount} font installation(s) failed.`)));
+        process.exit(1);
+      }
+
+      // Report partial failures
+      if (failCount > 0 && successCount > 0) {
+        console.log(pc.yellow(`\n${successCount} font(s) installed successfully, ${failCount} failed.`));
+      }
+    } catch (err) {
+      console.error(pc.red(/** @type {Error} */ (err).toString()));
+      process.exit(1);
+    }
   });
 
 program
   .command("copy <family...>")
   .description("Copy Google Fonts stylesheet link to clipboard")
   .option("-v, --variants <variants>", "Variants separated by comma")
   .action(async (family, options) => {
-    await ensureFontsLoaded();
+    const refresh = program.opts().refreshCache;
+    await ensureFontsLoaded(refresh);
     const term = family.join(" ");
     const variants = options.variants ? options.variants.split(",") : false;
 
-    fontList.getFontByName(term, (err, filteredList) => {
+    fontList.getFontByName(term, (/** @type {Error | null} */ err, /** @type {any} */ filteredList) => {
       if (err || filteredList.data.length !== 1) {
         handleMatchError("Copy", term, err);
         return;
       }
       const font = filteredList.getFirst();
+      if (!font) return;
       const url = variants
         ? `${font.getCssUrl()}:${variants.join(",")}`
         : font.getCssUrl();
@@ -112,6 +238,13 @@ if (program.args.length === 0) {
  * Output Helpers
  */
 
+/**
+ * Handle and display match errors for font operations
+ * @param {string} action - Action being performed (e.g., "Download", "Install")
+ * @param {string} term - Font family name that failed
+ * @param {Error | null} err - Error object or null
+ * @returns {void}
+ */
 function handleMatchError(action, term, err) {
   if (err) {
     console.error(pc.red(err.toString()));
@@ -123,6 +256,13 @@ function handleMatchError(action, term, err) {
   }
 }
 
+/**
+ * Print a list of fonts to the console
+ * @param {Error | null} err - Error object or null
+ * @param {GoogleFontListInstance} list - Font list to display
+ * @param {string} [message="Search results for:"] - Header message
+ * @returns {void}
+ */
 function printFontList(err, list, message = "Search results for:") {
   if (err) return console.error(pc.red(err.toString()));
   if (list.data.length === 0) {
@@ -139,6 +279,12 @@ function printFontList(err, list, message = "Search results for:") {
   });
 }
 
+/**
+ * Print font operation results to the console
+ * @param {Error | null} err - Error object or null
+ * @param {FontResult[]} result - Array of font results to display
+ * @returns {void}
+ */
 function printResult(err, result) {
   if (err) return console.error(pc.red(err.toString()));
   console.log("");

jest.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/test/**/*.test.js'],
+  collectCoverageFrom: [
+    'lib/**/*.js',
+    '!lib/windows/**/*.js'
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  verbose: true,
+  testTimeout: 10000,
+  maxWorkers: 1
+};