Merge pull request #28 from ty-ras/issue/7-add-jsdoc

#7 Adding documentation for the library.

.c8rc.json

@@ -4,8 +4,9 @@
     "src/**/*.ts"
   ],
   "exclude": [
-    "src/__test__/**/*.*",
+    "src/**/__test__/**/*.*",
     "**/*.d.ts",
+    "**/*.types.ts",
     "src/index.ts"
   ],
   "reporter": [

.eslintrc.library.cjs

@@ -6,20 +6,21 @@ module.exports = {
     "plugin:@typescript-eslint/recommended",
     "plugin:@typescript-eslint/eslint-recommended",
     "plugin:@typescript-eslint/recommended-requiring-type-checking",
-    // See https://github.com/prettier/eslint-config-prettier/blob/main/CHANGELOG.md#version-800-2021-02-21
+    "plugin:type-only-import/recommended",
+    "plugin:jsdoc/recommended-typescript-error",
     "plugin:prettier/recommended",
     "plugin:sonarjs/recommended"
   ],
-  plugins: ["prettier"],
+  plugins: [
+    "type-only-import",
+    "jsdoc",
+    "prettier"
+  ],
   parser: "@typescript-eslint/parser",
-  env: {
-    node: true,
-    es2020: true
-  },
   parserOptions: {
     project: "./tsconfig.json",
     sourceType: "module",
-    ecmaVersion: 2020,
+    ecmaVersion: "latest",
     tsconfigRootDir: __dirname,
   },
   rules: {
@@ -32,13 +33,29 @@ module.exports = {
     "no-useless-return": "error",
     "no-console": "error",
     "sonarjs/no-nested-template-literals": "off", // Nested template literals are OK really
-  },
-  settings: {
-    "import/resolver": {
-      node: {
-        paths: ["src"],
-        extensions: [".ts"] // Add .tsx, .js, .jsx if needed
+    "jsdoc/require-file-overview": "error",
+    "jsdoc/require-jsdoc": [
+      "error",
+      {
+        "publicOnly": true,
+        "require": {
+          "ArrowFunctionExpression": true,
+          "ClassDeclaration": true,
+          "ClassExpression": true,
+          "FunctionDeclaration": true,
+          "FunctionExpression": true,
+          "MethodDefinition": true
+        },
+        "exemptEmptyConstructors": true,
+        "exemptEmptyFunctions": false,
+        "enableFixer": false,
+        "contexts": [
+          "TSInterfaceDeclaration",
+          "TSTypeAliasDeclaration",
+          "TSMethodSignature",
+          "TSPropertySignature"
+        ]
       }
-    }
+    ]
   }
 };

.eslintrc.out-ts.cjs

@@ -0,0 +1,17 @@
+// ESLint config for formatting the resulting .d.ts files (<project name>/dist-ts/**/*.d.ts) that end up in NPM package for typing information.
+const { extends: extendsArray, plugins, rules } = require("./.eslintrc.cjs");
+module.exports = {
+  root: true,
+  extends: extendsArray.filter((ext) => ext.startsWith("plugin:jsdoc/") || ext.startsWith("plugin:prettier/")),
+  plugins: plugins.filter((plugin) => plugin === "jsdoc" || plugin === "prettier"),
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    project: "./tsconfig.out.json",
+    sourceType: "module",
+    ecmaVersion: "latest",
+    tsconfigRootDir: __dirname,
+  },
+  rules: Object.fromEntries(Object.entries(rules).filter(([ruleKey]) => ruleKey.startsWith("jsdoc/") || ruleKey.startsWith("prettier/"))),
+  // So we won't get errors on comments disable e.g. @typescript-eslint/xyz rules.
+  noInlineConfig: true,
+};

.eslintrc.output.cjs → .eslintrc.out.cjs

@@ -2,18 +2,17 @@
 module.exports = {
   root: true,
   extends: [
-    // See https://github.com/prettier/eslint-config-prettier/blob/main/CHANGELOG.md#version-800-2021-02-21
+    "plugin:path-import-extension/recommended",
     "plugin:prettier/recommended",
   ],
-  plugins: ["prettier"],
+  plugins: [
+    "path-import-extension",
+    "prettier"
+  ],
   parser: "@babel/eslint-parser",
   parserOptions: {
     requireConfigFile: false
   },
-  env: {
-    node: true,
-    es2020: true
-  },
   rules: {
     "prettier/prettier": "error",
   }

scripts/generate-stub-package-json.cjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const { version } = JSON.parse(fs.readFileSync("package.json"));
+fs.writeFileSync(
+  "dist-cjs/package.json",
+  // Just version is enough
+  JSON.stringify({ version })
+);

scripts/install.sh

@@ -5,8 +5,8 @@
 yarn install "$@"
 
 cp .eslintrc.library.cjs "${TYRAS_LIB_DIR}/.eslintrc.cjs"
-cp .eslintrc.output.cjs "${TYRAS_LIB_DIR}"
-cp .eslintrc.output.ts.cjs "${TYRAS_LIB_DIR}"
+cp .eslintrc.out.cjs "${TYRAS_LIB_DIR}"
+cp .eslintrc.out-ts.cjs "${TYRAS_LIB_DIR}"
 cp tsconfig.library.json "${TYRAS_LIB_DIR}/tsconfig.json"
 cp tsconfig.build.json "${TYRAS_LIB_DIR}"
 cp tsconfig.out.json "${TYRAS_LIB_DIR}"

scripts/remove-empty-js-files.cjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const glob = require("glob");
+
+glob
+  // Find all CommonJS files
+  .sync("dist-cjs/**/*.js")
+  // Read their contents while remembering the file path
+  .map((file) => ({ file, contents: fs.readFileSync(file, "utf8") }))
+  // Check whether the contents match what is emitted by a file without anything runtime-living to export
+  .filter(({ contents }) => contents === '"use strict";\nObject.defineProperty(exports, "__esModule", { value: true });\n')
+  // Delete the files
+  .map(({ file }) => fs.unlinkSync(file))
+  ;
+
+glob
+  // Find all ESM files
+  .sync("dist-esm/**/*.js")
+  // Read their contents while remembering the file path
+  .map((file) => ({ file, contents: fs.readFileSync(file, "utf8") }))
+  // Check whether the contents match what is emitted by a file without anything runtime-living to export
+  .filter(({ contents }) => contents === 'export {};\n')
+  // Delete the files
+  .map(({ file }) => fs.unlinkSync(file))
+  ;

server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ty-ras/server-node",
-  "version": "0.13.1",
+  "version": "1.0.0",
   "author": {
     "name": "Stanislav Muhametsin",
     "email": "346799+stazz@users.noreply.github.com",
@@ -31,37 +31,43 @@
     }
   },
   "dependencies": {
-    "@ty-ras/server": "0.13.0",
-    "@ty-ras/endpoint-prefix": "0.13.1"
+    "@ty-ras/server": "^1.0.0",
+    "@ty-ras/endpoint-prefix": "^1.0.0"
   },
   "devDependencies": {
-    "@babel/core": "7.19.3",
-    "@babel/eslint-parser": "7.19.1",
-    "@types/node": "18.7.18",
-    "@types/node-forge": "1.3.0",
-    "@typescript-eslint/eslint-plugin": "5.38.0",
-    "@typescript-eslint/parser": "5.38.0",
-    "@ty-ras/server-test-support": "0.13.0",
-    "ava": "5.0.1",
     "@ava/get-port": "2.0.0",
-    "c8": "7.12.0",
-    "eslint": "8.23.1",
-    "eslint-config-prettier": "8.5.0",
+    "@babel/core": "7.21.5",
+    "@babel/eslint-parser": "7.21.3",
+    "@ty-ras/server-test-support": "1.0.0",
+    "@typescript-eslint/eslint-plugin": "5.59.2",
+    "@typescript-eslint/parser": "5.59.2",
+    "@types/node": "18.15.3",
+    "@types/node-forge": "1.3.0",
+    "ava": "5.2.0",
+    "c8": "7.13.0",
+    "eslint": "8.39.0",
+    "eslint-plugin-jsdoc": "43.1.1",
+    "eslint-plugin-path-import-extension": "0.9.0",
+    "eslint-plugin-type-only-import": "0.9.0",
+    "eslint-config-prettier": "8.8.0",
     "eslint-plugin-prettier": "4.2.1",
-    "eslint-plugin-sonarjs": "0.15.0",
+    "eslint-plugin-sonarjs": "0.19.0",
     "node-forge": "1.3.1",
-    "prettier": "2.7.1",
+    "prettier": "2.8.8",
     "ts-node": "10.9.1",
-    "typescript": "4.8.3"
+    "typescript": "5.0.4"
   },
   "scripts": {
     "build:run": "yarn run lint && yarn run tsc",
-    "build:ci": "yarn run clear-build-artifacts && yarn run compile-d-ts-files && yarn run tsc --outDir ./dist-esm && yarn run tsc --module CommonJS --outDir ./dist-cjs && yarn run format-output-files",
+    "build:ci": "yarn run clear-build-artifacts && yarn run compile-d-ts-files && yarn run tsc --outDir ./dist-esm && yarn run tsc --module CommonJS --outDir ./dist-cjs && yarn run remove-empty-js-files && yarn run generate-stub-package-json-for-cjs && yarn run format-output-files",
     "clear-build-artifacts": "rm -rf dist dist-ts dist-cjs dist-esm build",
-    "compile-d-ts-files": "yarn run tsc --removeComments false --emitDeclarationOnly --declaration --declarationDir ./dist-ts && yarn run copy-d-ts-files && yarn run tsc:plain --project tsconfig.out.json",
-    "copy-d-ts-files": "find ./src -mindepth 1 -maxdepth 1 -name '*.d.ts' -exec cp {} ./dist-ts +",
-    "format-output-files": "find dist-ts -name '*.ts' -type f -exec sh -c \"echo '/* eslint-disable */\n/* eslint-enable prettier/prettier */'\"' | cat - $1 > $1.tmp && mv $1.tmp $1' -- {} \\; && eslint --no-eslintrc --config '.eslintrc.output.ts.cjs' --fix './dist-ts/**/*.ts' && eslint --no-eslintrc --config '.eslintrc.output.cjs' --fix 'dist-cjs/*js' 'dist-esm/*js'",
+    "compile-d-ts-files": "yarn run tsc --removeComments false --emitDeclarationOnly --declaration --declarationDir ./dist-ts && yarn run tsc:plain --project tsconfig.out.json",
+    "format-output-files": "yarn run format-output-files-ts && yarn run format-output-files-js",
+    "format-output-files-ts": "eslint --no-eslintrc --config '.eslintrc.out-ts.cjs' --fix --fix-type layout './dist-ts/**/*.ts'",
+    "format-output-files-js": "eslint --no-eslintrc --config '.eslintrc.out.cjs' --fix 'dist-cjs/**/*js' 'dist-esm/**/*js'",
+    "generate-stub-package-json-for-cjs": "../scripts/generate-stub-package-json.cjs",
     "lint": "eslint ./src --ext .ts,.tsx",
+    "remove-empty-js-files": "../scripts/remove-empty-js-files.cjs",
     "tsc": "tsc --project tsconfig.build.json",
     "tsc:plain": "tsc",
     "test:coverage": "c8 --temp-directory /tmp ava",

server/src/__test__/cors.spec.ts

@@ -1,3 +1,7 @@
+/**
+ * @file This file contains unit tests for functionality in file `../cors.ts`.
+ */
+
 import test from "ava";
 import * as spec from "../cors";
 

server/src/__test__/secure.ts

@@ -1,7 +1,15 @@
-// This is pretty much copied from https://www.techengineer.one/how-to-generate-x-509v3-self-signed-certificate-in-pem-format-with-node-js/
-import * as crypto from "crypto";
+/**
+ * @file This file contains code related to testing HTTPS server.
+ * The code is copied, with some modifications, from https://www.techengineer.one/how-to-generate-x-509v3-self-signed-certificate-in-pem-format-with-node-js/ .
+ */
+
+import * as crypto from "node:crypto";
 import forge from "node-forge";
 
+/**
+ * Generates a new self-signed key and certificate to use in testing HTTPS server.
+ * @returns Self-signed key and certificate.
+ */
 export const generateKeyAndCert = () => {
   const pki = forge.pki;
   // generate a keypair and create an X.509v3 certificate

server/src/__test__/server.spec.ts

@@ -1,10 +1,14 @@
+/**
+ * @file This file contains unit tests for functionality in file `../server.ts`.
+ */
+
 import test from "ava";
 
 import * as spec from "../server";
 import * as secure from "./secure";
 
 import * as testSupport from "@ty-ras/server-test-support";
-import type * as ctx from "../context";
+import type * as ctx from "../context.types";
 
 const createServer: testSupport.CreateServer = (
   endpoints,