Improvements to local scripts and generated code docs (#148)

* Improvements to development scripts

* Add JSDoc document generation

.github/workflows/npm-publish.yml

@@ -10,21 +10,21 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-      with:
-        persist-credentials: false
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: 22
-        registry-url: 'https://registry.npmjs.org'
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: 'https://registry.npmjs.org'
 
-    - run: npm ci
-    - run: npm run build
-    - run: npm run build:types
+      - run: npm ci
+      - run: npm run build
+      - run: npm run build:types
 
-    - name: Publish to NPM
-      run: npm publish
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -15,37 +15,37 @@ jobs:
         node: [18, 20, 22]
 
     steps:
-    - uses: actions/checkout@v4
-      with:
-        persist-credentials: false
-
-    - name: Setup Node.js ${{ matrix.node }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node }}
-        cache: 'npm'
-
-    - run: npm ci
-    - run: npm run lint
-    - run: npm run build
-    - run: npm run coverage
-
-    - name: Coveralls Parallel
-      uses: coverallsapp/github-action@v2
-      with:
-        github-token: ${{ secrets.GITHUB_TOKEN }}
-        flag-name: ${{ matrix.node }}
-        parallel: true
-
-    - run: npm publish --dry-run
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'npm'
+
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run build
+      - run: npm run coverage
+
+      - name: Coveralls Parallel
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          flag-name: ${{ matrix.node }}
+          parallel: true
+
+      - run: npm publish --dry-run
 
   finish:
     needs: build
     runs-on: ubuntu-latest
     steps:
-    - name: Coveralls Finished
-      uses: coverallsapp/github-action@v2
-      with:
-        github-token: ${{ secrets.GITHUB_TOKEN }}
-        parallel-finished: true
-        carryforward: "18,20,22"
+      - name: Coveralls Finished
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel-finished: true
+          carryforward: '18,20,22'

.gitignore

@@ -63,7 +63,10 @@ typings/
 .env
 
 # next.js build output
-.next
+.next/
 
 # VSCode project config
-.vscode
+.vscode/
+
+# JSDoc
+docs/

bench.js

@@ -1,5 +1,5 @@
 import Benchmark from 'benchmark';
-import * as fs from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import chalk from 'chalk';
 
 const suite = new Benchmark.Suite();
@@ -24,23 +24,23 @@ for (let index = 1; index < arguments_.length; index++) {
 // If language is defined
 if (i18n) {
   // Check if language file exists
-  if (fs.existsSync('./lib/i18n/' + i18n + '.js')) {
+  if (existsSync('./lib/i18n/' + i18n + '.js')) {
     // Queue specific language benchmark
-    await benchLanguage(i18n);
+    await benchFile('i18n/' + i18n);
   } else {
     // Log error to console
     console.error(chalk.red('\ni18n language file does not exist: ' + i18n + '.js\n'));
   }
 } else {
   // Load all files in language directory
-  const files = fs.readdirSync('./lib/i18n');
+  const files = readdirSync('./lib/i18n');
 
   // Loop through files
   for (const file of files) {
     // Make sure file is JavaScript
     if (file.includes('.js')) {
       // Queue language file benchmark
-      await benchLanguage(file.replace('.js', ''));
+      await benchFile('i18n/' + file.replace('.js', ''));
     }
   }
 }
@@ -55,12 +55,13 @@ suite
 
 /**
  * Queue language test file for benchmarking.
- * @param {string} i18n Language identifier.
+ * @param {string} file Library file.
+ * @param {object} options Options for language file.
  */
-async function benchLanguage(i18n) {
-  const { default: language } = await import('./lib/i18n/' + i18n + '.js');
+async function benchFile(file, options) {
+  const { default: n2words } = await import('./lib/' + file + '.js');
 
-  suite.add(i18n, () => {
-    language(value);
+  suite.add(file, async () => {
+    n2words(value, options);
   });
 }

conf.json

@@ -0,0 +1,16 @@
+{
+  "plugins": [
+    "plugins/markdown"
+  ],
+  "source": {
+    "include": [
+      "./README.md",
+      "./lib"
+    ],
+    "includePattern": ".+\\.js(doc|x)?$"
+  },
+  "opts": {
+    "destination": "./docs/",
+    "recurse": true
+  }
+}

examples/node.js

@@ -15,9 +15,7 @@ if (fs.existsSync('./lib/i18n/' + lang + '.js')) {
 
   const { default: n2words } = await import('../lib/i18n/' + lang + '.js');
 
-  const result = n2words(value, {
-    lang: lang
-  });
+  const result = n2words(value);
 
   console.log('\n' + chalk.bold(result) + '\n');
 } else {

lib/classes/abstract-language.js

@@ -1,8 +1,8 @@
 /**
- * Creates new language class that processes decimals separately.
+ * Creates new common language class that processes decimals separately.
  * Requires implementing `toCardinal`.
  */
-export default class AbstractLanguage {
+class AbstractLanguage {
   #negativeWord;
   #separatorWord;
   #zero;
@@ -156,3 +156,5 @@ export default class AbstractLanguage {
     return words.join(this.spaceSeparator);
   }
 }
+
+export default AbstractLanguage;

lib/classes/base-language.js

@@ -4,9 +4,8 @@ import AbstractLanguage from './abstract-language.js';
  * Creates new common language class that uses a highest matching word value algorithm.
  * Number matching word {@link cards} must be provided for this to work.
  * See {@link AbstractLanguage} for further requirements.
- * @classdesc Common class for (mostly european) languages.
  */
-export default class BaseLanguage extends AbstractLanguage {
+class BaseLanguage extends AbstractLanguage {
   #cards;
 
   /**
@@ -24,15 +23,7 @@ export default class BaseLanguage extends AbstractLanguage {
   }
 
   /**
-   * Get array of number matching "cards" from highest-to-lowest.
-   * @returns {Array} Array of number matching "cards" from highest-to-lowest.
-   */
-  get cards() {
-    return this.#cards;
-  }
-
-  /**
-   * Set array of number matching "cards" from highest-to-lowest.
+   * Array of number matching "cards" from highest-to-lowest.
    * First element in card array is the number to match while the second is the word to use.
    * @example
    * [
@@ -41,7 +32,12 @@ export default class BaseLanguage extends AbstractLanguage {
    *   ...
    *   [1, 'one'],
    * ]
+   * @type {Array}
    */
+  get cards() {
+    return this.#cards;
+  }
+
   set cards(value) {
     this.#cards = value;
   }
@@ -172,3 +168,5 @@ export default class BaseLanguage extends AbstractLanguage {
     return this.postClean(preWords);
   }
 }
+
+export default BaseLanguage;

lib/n2words.js

@@ -1,3 +1,7 @@
+/**
+ * @module n2words
+ */
+
 import n2wordsAR from './i18n/ar.js';
 import n2wordsAZ from './i18n/az.js';
 import n2wordsCZ from './i18n/cz.js';
@@ -66,7 +70,7 @@ const dict = {
  * TODO [2024-06] Migrate to object destructing for parameters
  */
 // eslint-disable-next-line unicorn/no-object-as-default-parameter
-export default function floatToCardinal(value, options = { lang: 'en' }) {
+function floatToCardinal(value, options = { lang: 'en' }) {
   const function_ = dict[options.lang];
   if (function_ != undefined) return function_(value, options);
 
@@ -77,3 +81,5 @@ export default function floatToCardinal(value, options = { lang: 'en' }) {
 
   throw new Error('Unsupported language: ' + value + '.');
 }
+
+export default floatToCardinal;