#28 Adding documentation to 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,19 +2,18 @@
 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",
-  },
+  }
 };

metadata/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ty-ras/metadata-openapi",
-  "version": "0.13.1",
+  "version": "1.0.0",
   "author": {
     "name": "Stanislav Muhametsin",
     "email": "346799+stazz@users.noreply.github.com",
@@ -31,38 +31,44 @@
     }
   },
   "dependencies": {
-    "@ty-ras/metadata": "0.13.0",
-    "@ty-ras/metadata-jsonschema": "0.13.1"
+    "@ty-ras/metadata": "^1.0.1",
+    "@ty-ras/metadata-jsonschema": "^1.0.0"
   },
   "peerDependencies": {
     "openapi-types": "^12.0.2"
   },
   "devDependencies": {
-    "@babel/core": "7.19.3",
-    "@babel/eslint-parser": "7.19.1",
-    "@types/node": "18.7.18",
-    "@typescript-eslint/eslint-plugin": "5.38.0",
-    "@typescript-eslint/parser": "5.38.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",
+    "@types/node": "18.16.3",
+    "@typescript-eslint/eslint-plugin": "5.59.2",
+    "@typescript-eslint/parser": "5.59.2",
+    "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",
     "openapi-types": "12.0.2",
-    "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",

metadata/src/__test__/jsonschema.spec.ts

@@ -1,3 +1,7 @@
+/**
+ * @file This file contains unit tests for functionality in file `../jsonschema.ts`.
+ */
+
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 import test from "ava";
 import * as spec from "../jsonschema";

metadata/src/__test__/provider.spec.ts

@@ -1,10 +1,14 @@
+/**
+ * @file This file contains unit tests for functionality in file `../provider.ts`.
+ */
+
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 import test from "ava";
 import * as spec from "../provider";
 import type { OpenAPIV3 as openapi } from "openapi-types";
 import type * as md from "@ty-ras/metadata";
-import type * as openapiMd from "../openapi";
+import type * as openapiMd from "../openapi.types";
 
 test("Validate createOpenAPIProvider works for simplest usecase", (t) => {
   t.plan(2);
@@ -53,8 +57,10 @@ test("Validate createOpenAPIProvider works for one complex endpoint", (t) => {
           "/path/",
           {
             name: "parameter",
-            decoder: "url-parameter",
-            regExp: /.*/,
+            spec: {
+              decoder: "url-parameter",
+              regExp: /.*/,
+            },
           },
         ],
         {
@@ -103,12 +109,12 @@ test("Validate createOpenAPIProvider works for one complex endpoint", (t) => {
                   description: "query-parameter-description",
                 },
               },
-              body: {
+              requestBody: {
                 string: {
                   example: "request-body-example",
                 },
               },
-              output: {
+              responseBody: {
                 description: "response-body-description",
                 mediaTypes: {
                   string: {
@@ -294,7 +300,7 @@ const makeConst = (val: string): openapi.SchemaObject => ({
 // In unit tests, our decoders and encoders are just strings
 // In reality they will be data validators from io-ts/runtypes/zod libraries.
 const createProvider = () =>
-  spec.createOpenAPIProvider<
+  spec.createOpenAPIProviderGeneric<
     string,
     string,
     { string: string },
@@ -356,7 +362,7 @@ const getSimpleEndpoint = (
     inputSpec: undefined,
     metadataArguments: {
       urlParameters: {},
-      output: {
+      responseBody: {
         description: "outputDescription",
         mediaTypes: {
           string: {
@@ -367,7 +373,7 @@ const getSimpleEndpoint = (
       responseHeaders: {},
       requestHeaders: {},
       queryParameters: {},
-      body: {},
+      requestBody: {},
       operation: {},
     },
   },

metadata/src/__test__/utils.spec.ts

@@ -1,3 +1,7 @@
+/**
+ * @file This file contains unit tests for functionality in file `../utils.ts`.
+ */
+
 import test from "ava";
 import * as spec from "../utils";
 import type { OpenAPIV3 as openapi } from "openapi-types";

metadata/src/index.ts

@@ -1,24 +1,8 @@
-// Really waiting for that "export type *": https://github.com/microsoft/TypeScript/issues/37238
-// If we just do "export * from", our index.[m]js file ends up with "export" statement as well, thus causing runtime errors.
-// Another option is rename .d.ts files into .ts files and end up with a bunch of empty .[m]js files and index.[m]js exporting those - not very optimal either.export * from "./headers";
-export type {
-  FinalMetadata,
-  OpenAPIEndpointMD,
-  OpenAPIEndpointStateInfo,
-  OpenAPIArguments,
-  OpenAPIArgumentsInput,
-  OpenAPIArgumentsOutput,
-  OpenAPIArgumentsQuery,
-  OpenAPIArgumentsRequestHeaders,
-  OpenAPIArgumentsResponseHeaders,
-  OpenAPIArgumentsStatic,
-  OpenAPIArgumentsURLData,
-  OpenAPIMetadataProvider,
-  OpenAPIParameterInput,
-  OpenAPIParameterMedia,
-  OpenAPIPathItemArg,
-  PathsObjectInfo,
-} from "./openapi";
+/**
+ * @file This is entrypoint file for this package, exporting all non-internal files.
+ */
+
+export type * from "./openapi.types";
 export * from "./provider";
 export * from "./jsonschema";
 export * from "./utils";

metadata/src/jsonschema.ts

@@ -1,8 +1,17 @@
+/**
+ * @file This file contains function to convert fully-fledged JSON schema 7 values into the ones supported by OpenAPI.
+ */
+
 import type * as jsonSchema from "json-schema";
 import type * as jsonSchemaPlugin from "@ty-ras/metadata-jsonschema";
 import type { OpenAPIV3 as openapi } from "openapi-types";
 
-// OpenAPI doesn't support full shape of JSON7 schemas so we must convert unsupported ones first.
+/**
+ * This function will convert the JSON schema 7 value into the one supported by OpenAPI.
+ * Most notably, the `boolean` values as schema objects are not supported by OpenAPI.
+ * @param schema The {@link jsonSchema.JSONSchema7Definition} to convert.
+ * @returns The JSON schema suitable for OpenAPI as {@link openapi.SchemaObject}.
+ */
 export const convertToOpenAPISchemaObject = (
   schema: jsonSchema.JSONSchema7Definition,
 ): openapi.SchemaObject =>
@@ -71,7 +80,9 @@ const handleSchemaRecord = <
     : Object.entries(record).reduce((newRecord, [key, val]) => {
         newRecord[key] =
           val !== undefined && !Array.isArray(val)
-            ? (convertBooleanSchemasToObjects(val) as typeof newRecord[string])
+            ? (convertBooleanSchemasToObjects(
+                val,
+              ) as (typeof newRecord)[string])
             : val;
         return newRecord;
       }, {} as typeof record);