Merge branch 'master' into vkarpov15/gh-11945

.github/workflows/benchmark.yml

@@ -2,20 +2,18 @@ name: Benchmark
 on:
   pull_request:
     paths:
-      - '.github/workflows/benchmark.yml'
-      - 'package.json'
-      - 'types/**'
-      - 'benchmarks/typescript/**'
-      - 'benchmarks/typescript.js'
+      - ".github/workflows/benchmark.yml"
+      - "package.json"
+      - "types/**"
+      - "benchmarks/typescript/**"
   push:
     branches:
       - master
     paths:
-      - '.github/workflows/benchmark.yml'
-      - 'package.json'
-      - 'types/**'
-      - 'benchmarks/typescript/**'
-      - 'benchmarks/typescript.js'
+      - ".github/workflows/benchmark.yml"
+      - "package.json"
+      - "types/**"
+      - "benchmarks/typescript/**"
 permissions:
   contents: read
 
@@ -27,12 +25,12 @@ jobs:
       - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
 
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 16
 
       - run: npm install
 
-      - run: node ./benchmarks/typescript
+      - run: npx ts-benchmark -p ./benchmarks/typescript/simple -f 17/100000 18 29 32 -b master -g --colors
         env:
-          DB_URL: ${{ secrets.DB_URL }}
+          DB_URL: ${{ secrets.DB_URL }}

.github/workflows/documentation.yml

@@ -31,7 +31,7 @@ jobs:
       - uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846 # v3
 
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.0
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 16
 

.github/workflows/test.yml

@@ -27,7 +27,7 @@ jobs:
       - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
 
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 14
 
@@ -37,8 +37,6 @@ jobs:
         run: npm run lint-js
 
   test:
-    needs:
-      - lint
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -60,7 +58,7 @@ jobs:
       - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
 
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: ${{ matrix.node }}
 
@@ -86,7 +84,7 @@ jobs:
     steps:
       - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 16
       - run: npm install
@@ -101,7 +99,7 @@ jobs:
     steps:
       - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 16
       - run: npm install

.github/workflows/tidelift-alignment.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 16
       - name: Alignment

.github/workflows/tsd.yml

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
 
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 14
 
@@ -43,7 +43,7 @@ jobs:
       - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.0.2
 
       - name: Setup node
-        uses: actions/setup-node@eeb10cff27034e7acf239c5d29f62154018672fd # v3.1.1
+        uses: actions/setup-node@2fddd8803e2f5c9604345a0b591c3020ee971a93 # v3.4.1
         with:
           node-version: 12
 

.gitignore

@@ -48,4 +48,9 @@ docs/*.html
 docs/tutorials/*.html
 docs/typescript/*.html
 docs/api/*.html
-index.html
+index.html
+
+# yarn package-lock
+yarn.lock
+
+examples/ecommerce-netlify-functions/.netlify/state.json

CHANGELOG.md

@@ -1,3 +1,11 @@
+6.4.4 / 2022-07-08
+==================
+ * fix(types): allow using an object to configure timestamps #12061 [lantw44](https://github.com/lantw44)
+ * fix(types): support findOneAndReplace with rawResult #12062 [lantw44](https://github.com/lantw44)
+ * docs: upgrade API documentation parser #12078 #12072 #12071 #12024 [hasezoey](https://github.com/hasezoey)
+ * docs(document): add more info on $isNew #11990
+ * docs: add SchemaType doValidate() to docs #12068
+
 6.4.3 / 2022-07-05
 ==================
  * fix(document): handle validating deeply nested subdocuments underneath nested paths with required: false #12021

benchmarks/typescript.js

@@ -21,6 +21,8 @@ async function run() {
 
   const tsProjectsDirectories = await fs.readdir('benchmarks/typescript');
 
+  let failed = [];
+
   for (const tsProjectDirectory of tsProjectsDirectories) {
     let instantiations = 0;
     let memoryUsed = 0;
@@ -62,11 +64,19 @@ async function run() {
       totalTime,
       testName: tsProjectDirectory
     });
+
+    if (instantiations >= 100000) {
+      failed.push(tsProjectDirectory);
+    }
   }
 
   await persist({ results });
 
   await mongoose.disconnect();
+
+  if (failed.length > 0) {
+    throw new Error(`Benchmarks ${failed.join(', ')} had over 100k instantiations`);
+  }
 }
 
 async function persist({ results }) {

docs/search.js

@@ -40,6 +40,7 @@ for (const filename of files) {
         });
         const err = content.validateSync();
         if (err != null) {
+          console.log(content);
           throw err;
         }
         contents.push(content);

docs/source/api.js

@@ -50,13 +50,35 @@ const out = module.exports.docs;
 
 const combinedFiles = [];
 for (const file of files) {
-  const comments = dox.parseComments(fs.readFileSync(`./${file}`, 'utf8'), { raw: true });
-  comments.file = file;
-  combinedFiles.push(comments);
+  try {
+    const comments = dox.parseComments(fs.readFileSync(`./${file}`, 'utf8'), { raw: true });
+    comments.file = file;
+    combinedFiles.push(comments);
+  } catch (err) {
+    // show log of which file has thrown a error for easier debugging
+    console.error("Error while trying to parseComments for ", file);
+    throw err;
+  }
 }
 
 parse();
 
+/**
+ * @typedef {Object} PropContext
+ * @property {boolean} [isStatic] Defines wheter the current property is a static property (not mutually exlusive with "isInstance")
+ * @property {boolean} [isInstance] Defines wheter the current property is a instance property (not mutually exlusive with "isStatic")
+ * @property {boolean} [isFunction] Defines wheter the current property is meant to be a function
+ * @property {string} [constructor] Defines the Constructor (or rather path) the current property is on
+ * @property {boolean} [constructorWasUndefined] Defined wheter the "constructor" property was defined by "dox", but was set to "undefined"
+ * @property {string} [type] Defines the type the property is meant to be
+ * @property {string} [name] Defines the current Properties name
+ * @property {Object} [return] The full object for a "@return" jsdoc tag
+ * @property {string} [string] Defines the full string the property will be listed as
+ * @property {string} [anchorId] Defines the Anchor ID to be used for linking
+ * @property {string} [description] Defines the Description the property will be listed with
+ * @property {string} [deprecated] Defines wheter the current Property is signaled as deprecated
+ */
+
 function parse() {
   for (const props of combinedFiles) {
     let name = props.file.
@@ -88,43 +110,70 @@ function parse() {
       if (prop.ignore || prop.isPrivate) {
         continue;
       }
-
+
+      /** @type {PropContext} */
       const ctx = prop.ctx || {};
+
+      // somehow in "dox", it is named "receiver" sometimes, not "constructor"
+      // this is used as a fall-back if the handling below does not overwrite it
+      if ("receiver" in ctx) {
+        ctx.constructor = ctx.receiver;
+        delete ctx.receiver;
+      }
+
+      // in some cases "dox" has "ctx.constructor" defined but set to "undefined", which will later be used for setting "ctx.string"
+      if ("constructor" in ctx && ctx.constructor === undefined) {
+        ctx.constructorWasUndefined = true;
+      }
+
+      // helper function to keep translating array types to string consistent
+      function convertTypesToString(types) {
+        return Array.isArray(types) ? types.join('|') : types
+      }
+
       for (const tag of prop.tags) {
         switch (tag.type) {
           case 'receiver':
-            ctx.constructor = tag.string;
+            console.warn(`Found "@receiver" tag in ${ctx.constructor} ${ctx.name}`);
             break;
           case 'property':
             ctx.type = 'property';
-            let str = tag.string;
-            const match = str.match(/^{\w+}/);
-            if (match != null) {
-              ctx.type = match[0].substring(1, match[0].length - 1);
-              str = str.replace(/^{\w+}\s*/, '');
+
+            // using "name" over "string" because "string" also contains the type and maybe other stuff
+            ctx.name = tag.name;
+            // only assign "type" if there are types
+            if (tag.types.length > 0) {
+              ctx.type = convertTypesToString(tag.types);
             }
-            ctx.name = str;
-            ctx.string = `${ctx.constructor}.prototype.${ctx.name}`;
+
             break;
           case 'type':
-            ctx.type = Array.isArray(tag.types) ? tag.types.join('|') : tag.types;
+            ctx.type = convertTypesToString(tag.types);
             break;
           case 'static':
             ctx.type = 'property';
-            ctx.static = true;
-            ctx.name = tag.string;
-            ctx.string = `${data.name}.${ctx.name}`;
+            ctx.isStatic = true;
+            // dont take "string" as "name" from here, because jsdoc definitions of "static" do not have parameters, also its defined elsewhere anyway
+            // ctx.name = tag.string;
             break;
           case 'function':
             ctx.type = 'function';
-            ctx.static = true;
+            ctx.isStatic = true;
             ctx.name = tag.string;
-            ctx.string = `${data.name}.${ctx.name}()`;
+            // extra parameter to make function definitions independant of where "@function" is defined
+            // like "@static" could have overwritten "ctx.string" again if defined after "@function"
+            ctx.isFunction = true;
             break;
           case 'return':
-            tag.return = tag.description ?
-              md.parse(tag.description).replace(/^<p>/, '').replace(/<\/p>$/, '') :
+            tag.description = tag.description ?
+              md.parse(tag.description).replace(/^<p>/, '').replace(/<\/p>\n?$/, '') :
               '';
+
+            // dox does not add "void" / "undefined" to types, so in the documentation it would result in a empty "«»"
+            if (tag.string.includes('void') || tag.string.includes('undefined')) {
+              tag.types.push("void");
+            }
+
             ctx.return = tag;
             break;
           case 'inherits':
@@ -133,8 +182,12 @@ function parse() {
           case 'event':
           case 'param':
             ctx[tag.type] = (ctx[tag.type] || []);
+            // the following is required, because in newer "dox" version "null" is not included in "types" anymore, but a seperate property
+            if (tag.nullable) {
+              tag.types.push('null');
+            }
             if (tag.types) {
-              tag.types = tag.types.join('|');
+              tag.types = convertTypesToString(tag.types);
             }
             ctx[tag.type].push(tag);
             if (tag.name != null && tag.name.startsWith('[') && tag.name.endsWith(']') && tag.name.includes('.')) {
@@ -147,26 +200,44 @@ function parse() {
           case 'method':
             ctx.type = 'method';
             ctx.name = tag.string;
-            ctx.string = `${ctx.constructor}.prototype.${ctx.name}()`;
+            ctx.isFunction = true;
             break;
           case 'memberOf':
             ctx.constructor = tag.parent;
-            ctx.string = `${ctx.constructor}.prototype.${ctx.name}`;
-            if (ctx.type === 'method') {
-              ctx.string += '()';
-            }
             break;
           case 'constructor':
-            ctx.string = tag.string + '()';
+            ctx.string = tag.string;
             ctx.name = tag.string;
+            ctx.isFunction = true;
+            break;
+          case 'instance':
+            ctx.isInstance = true;
+            break;
+          case 'deprecated':
+            ctx.deprecated = true;
+            break;
         }
       }
 
-      if (/\.prototype[^.]/.test(ctx.string)) {
+      if (ctx.isInstance && ctx.isStatic) {
+        console.warn(`Property "${ctx.name}" in "${ctx.constructor}" has both instance and static JSDOC markings (most likely both @instance and @static)! (File: "${props.file}")`);
+      }
+
+      // the following if-else-if statement is in this order, because there are more "instance" methods thans static
+      // the following condition will be true if "isInstance = true" or if "isInstance = false && isStatic = false" AND "ctx.string" are empty or not defined
+      // if "isStatic" and "isInstance" are falsy and "ctx.string" is not falsy, then rely on the "ctx.string" set by "dox"
+      if (ctx.isInstance || (!ctx.isStatic && !ctx.isInstance && (!ctx.string || ctx.constructorWasUndefined))) {
         ctx.string = `${ctx.constructor}.prototype.${ctx.name}`;
+      } else if (ctx.isStatic) {
+        ctx.string = `${ctx.constructor}.${ctx.name}`;
       }
 
-      // Backwards compat
+      // add "()" to the end of the string if function
+      if ((ctx.isFunction || ctx.type === "method") && !ctx.string.endsWith("()")) {
+        ctx.string = ctx.string + "()";
+      }
+
+      // Backwards compat anchors
       if (typeof ctx.constructor === 'string') {
         ctx.anchorId = `${ctx.constructor.toLowerCase()}_${ctx.constructor}-${ctx.name}`;
       } else if (typeof ctx.receiver === 'string') {
@@ -178,9 +249,6 @@ function parse() {
       ctx.description = prop.description.full.
         replace(/<br \/>/ig, ' ').
         replace(/&gt;/ig, '>');
-      if (ctx.description.includes('function capitalize')) {
-        console.log('\n\n-------\n\n', ctx);
-      }
       ctx.description = md.parse(ctx.description);
 
       data.props.push(ctx);