Merge pull request #31 from veghdev/docs

docs: create docs site

Author: veghdev

.github/workflows/doc.yml

@@ -0,0 +1,43 @@
+name: Publish documentation
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Configure git
+        run: |
+          git config --global user.mail [email protected]
+          git config --global user.name docs
+
+      - name: Switch to gh-pages branch
+        run: |
+          git branch -f gh-pages
+          git switch gh-pages
+
+      - name: Initialize development environment
+        run: npm install
+
+      - name: Build documentation
+        run: npm run docs
+
+      - name: Push to gh-pages branch
+        run: |
+          git add docs
+          if ! git diff-index --quiet HEAD; then
+            git commit -am 'docs: update'
+            git push -f origin gh-pages
+          fi
+        if: ( github.event_name == 'release' && github.event.action == 'published' ) || github.event_name == 'workflow_dispatch'

package.json

@@ -11,6 +11,7 @@
     "check-prettier": "prettier -c ./*js ./src/*js",
     "check-eslint": "eslint ./*js ./src/*js",
     "check": "npm-run-all check-prettier check-eslint",
+    "docs": "npx jsdoc -d docs --readme README.md ./src/*js",
     "rollup": "rollup -c",
     "pack": "mkdir -p build && npm pack --pack-destination build && tar -ztvf build/*.tgz"
   },
@@ -47,6 +48,7 @@
     "rollup": "^2.70.2",
     "@rollup/plugin-commonjs": "^22.0.0",
     "rollup-plugin-auto-external": "^2.0.0",
-    "rollup-plugin-terser": "^7.0.2"
+    "rollup-plugin-terser": "^7.0.2",
+    "jsdoc": "^3.6.10"
   }
 }

src/writenpmstat.js

@@ -7,19 +7,37 @@ const createCsvWriter = require("csv-writer").createArrayCsvWriter;
 
 const StatDate = require("./statdate.js");
 
+/**
+ * Enum for statistics grouping (year, month, day, null)
+ * @readonly
+ * @enum {string|null}
+ */
 const StatPeriod = new Enum(
     ["year", "month", "day", null],
     { ignoreCase: true },
     { freeze: true }
 );
 
+/**
+ * Class to collect, filter and save npm statistics to csv files
+ * @property {string|null} [outDir] - path of the directory where
+ *     the gathered data will be saved into csv files
+ * @property {StatPeriod} [datePeriod=year] - grouping of the statistics
+ * @property {boolean} [mergeStoredData=true] - flag used to merge actual npm statistics with previously stored
+ */
 class WriteNpmStat {
     #packageName;
     outDir;
 
     #datePeriod;
     #mergeStoredData;
 
+    /**
+     * Initialize WriteNpmStat class
+     * @param {string} packageName - name of the target npm package
+     * @param {string|null} [outDir] - path of the directory where
+     *     the gathered data will be saved into csv files
+     */
     constructor(packageName, outDir) {
         if (!packageName) {
             throw new Error("packageName is a required argument");
@@ -52,8 +70,32 @@ class WriteNpmStat {
         this.#mergeStoredData = Boolean(mergeStoredData);
     }
 
-    getNpmStat(startDay, endDay) {
-        const statDate = new StatDate(startDay, endDay);
+    /**
+     * Returns npm statistics for a package
+     * @param {string|null} [startDate] - start date of the statistics
+     *    should be in one of the following formats:
+     *
+     *    <br>&nbsp;&nbsp; - "%Y", for example "2022", which means to be collected from "2022-01-01"
+     *
+     *    <br>&nbsp;&nbsp; - "%Y-%m", for example "2022-01", which means to be collected from "2022-01-01"
+     *
+     *    <br>&nbsp;&nbsp; - "%Y-%m-%d", for example "2022-01-01", which means to be collected from "2022-01-01"
+     *
+     *    <br>&nbsp;&nbsp; - undefined, which means to be collected from the last half year
+     * @param {string|null} [endDate] - end date of the statistics
+     *     should be in one of the following formats:
+     *
+     *     <br>&nbsp;&nbsp; - "%Y", for example "2022", which means to be collected until "2022-12-31"
+     *
+     *     <br>&nbsp;&nbsp; - "%Y-%m", for example "2022-12", which means to be collected until "2022-12-31"
+     *
+     *     <br>&nbsp;&nbsp; - "%Y-%m-%d", for example "2022-12-31", which means to be collected until "2022-12-31"
+     *
+     *     <br>&nbsp;&nbsp; - undefined, which means to be collected until the actual day
+     * @returns {Promise} Promise object represents the npm statistics for a package
+     */
+    getNpmStat(startDate, endDate) {
+        const statDate = new StatDate(startDate, endDate);
         const days = WriteNpmStat.getDays(statDate.start, statDate.end);
         return new Promise((resolve) => {
             const stats = [];
@@ -66,10 +108,10 @@ class WriteNpmStat {
         });
     }
 
-    static getDays(startDay, endDay) {
+    static getDays(startDate, endDate) {
         const arr = [];
-        const dt = new Date(startDay);
-        for (dt; dt <= new Date(endDay); dt.setDate(dt.getDate() + 1)) {
+        const dt = new Date(startDate);
+        for (dt; dt <= new Date(endDate); dt.setDate(dt.getDate() + 1)) {
             arr.push(StatDate.formatDate(new Date(dt)));
         }
         return arr;
@@ -91,26 +133,51 @@ class WriteNpmStat {
         });
     }
 
-    writeNpmStat(startDay, endDay, postfix = "npmstat") {
+    /**
+     * Writes npm statistics for a package
+     * @param {string|null} [startDate] - start date of the statistics
+     *     should be in one of the following formats:
+     *
+     *     <br>&nbsp;&nbsp; - "%Y", for example "2022", which means to be collected from "2022-01-01"
+     *
+     *     <br>&nbsp;&nbsp; - "%Y-%m", for example "2022-01", which means to be collected from "2022-01-01"
+     *
+     *     <br>&nbsp;&nbsp; - "%Y-%m-%d", for example "2022-01-01", which means to be collected from "2022-01-01"
+     *
+     *     <br>&nbsp;&nbsp; - undefined, which means to be collected from the last half year
+     * @param {string|null} [endDate] - end date of the statistics
+     *     should be in one of the following formats:
+     *
+     *     <br>&nbsp;&nbsp; - "%Y", for example "2022", which means to be collected until "2022-12-31"
+     *
+     *     <br>&nbsp;&nbsp; - "%Y-%m", for example "2022-12", which means to be collected until "2022-12-31"
+     *
+     *     <br>&nbsp;&nbsp; - "%Y-%m-%d", for example "2022-12-31", which means to be collected until "2022-12-31"
+     *
+     *     <br>&nbsp;&nbsp; - undefined, which means to be collected until the actual day
+     * @param {string|null} [endDate=npmstat] - csv file's postfix
+     * @returns {Promise} Promise object represents the npm statistics for a package
+     */
+    writeNpmStat(startDate, endDate, postfix = "npmstat") {
         return new Promise((resolve) => {
-            const stats = this.getNpmStat(startDay, endDay);
+            const stats = this.getNpmStat(startDate, endDate);
             stats.then((stats) => {
                 const grouped = this.#groupStats(
                     stats,
-                    startDay,
-                    endDay,
+                    startDate,
+                    endDate,
                     postfix
                 );
                 this.#mergeStats(grouped).then((merged) => {
                     this.#writeStats(merged);
+                    return resolve(merged);
                 });
-                return resolve();
             });
         });
     }
 
-    #groupStats(stats, startDay, endDay, postfix) {
-        const statDate = new StatDate(startDay, endDay);
+    #groupStats(stats, startDate, endDate, postfix) {
+        const statDate = new StatDate(startDate, endDate);
         const days = WriteNpmStat.getDays(statDate.start, statDate.end);
         const grouped = {};
         if (this.datePeriod) {