Merge pull request #33 from tsedio/fix-generate-id-per-symbol

fix: add id to generate file name

packages/ts-doc/components/code-highlight/code-highlight.js

@@ -1,5 +1,5 @@
 const {stripsComments} = require("../../src/utils/strips");
-const {highlight} = require("../../src/highlight");
+const {highlight} = require("./highlight");
 
 module.exports = {
   name: "codeHighlight",

packages/ts-doc/src/highlight/index.js → packages/ts-doc/components/code-highlight/highlight.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const {context} = require("../context");
+const {context} = require("../../src/context");
 const KEYWORDS =
   /(\benum\b|\bstatic\b|\bclass\b|\binterface\b|\bprivate\b|\bpublic\b|\bconst\b|\blet\b|\bprotected\b|\bimplements\b|\bconstructor\b|\breadonly\b|\babstract\b|\bimport\b|\bexport\b|\bas\b|\bfrom\b|\bextends\b)/g;
 const TYPES = /(\bany\b|\bstring\b|\bboolean\b|\bnumber\b|\bDate\b|\bvoid\b)/g;

packages/ts-doc/src/highlight/index.spec.js → packages/ts-doc/components/code-highlight/highlight.spec.js

@@ -1,5 +1,5 @@
 const {expect} = require("chai");
-const {highlight} = require("./index");
+const {highlight} = require("./highlight");
 
 describe("Highlight", () => {
   it("should highlight content", () => {

packages/ts-doc/components/symbol-params/symbol-params.js

@@ -1,4 +1,4 @@
-const {bindSymbols} = require("../../src/highlight");
+const {bindSymbols} = require("../code-highlight/highlight");
 module.exports = {
   name: "symbolParams",
   trim: false,

packages/ts-doc/package.json

@@ -34,10 +34,11 @@
     "fs-extra": "8.1.0",
     "glob": "7.1.6",
     "globby": "8.0.2",
+    "lodash": "^4.17.21",
     "listr": "^0.14.3",
     "normalize-path": "3.0.0",
     "read-pkg-up": "7.0.0"
   },
   "devDependencies": {},
   "peerDependencies": {}
-}
+}

packages/ts-doc/src/models/DocSymbol.js

@@ -2,6 +2,7 @@ const path = require("path");
 const normalizePath = require("normalize-path");
 const {context} = require("../context");
 const {descriptionParser} = require("../parsers/description-parser.js");
+const {dashCase} = require("../utils/dashCase");
 
 const _filterParams = (labels) => {
   return labels
@@ -45,6 +46,10 @@ class DocSymbol {
     this.labels = [];
   }
 
+  get id() {
+    return dashCase([this.symbolType, this.symbolName].filter(Boolean).join("-"));
+  }
+
   get path() {
     return this.docFile.path;
   }
@@ -112,11 +117,7 @@ class DocSymbol {
    * @returns {*}
    */
   get url() {
-    const url = [
-      context.baseUrl,
-      normalizePath(path.dirname(this.docFile.relativePackagePath)), //.replace(/\.ts$/, '')
-      `${this.symbolName}.html`
-    ].join("/");
+    const url = [context.baseUrl, normalizePath(path.dirname(this.docFile.relativePackagePath)), `${this.id}.html`].join("/");
 
     return context.outputResolver(url);
   }
@@ -126,7 +127,7 @@ class DocSymbol {
    * @returns {*}
    */
   get outputPath() {
-    const file = normalizePath(path.join(context.outputDir, path.dirname(this.docFile.relativePackagePath), `${this.symbolName}.md`));
+    const file = normalizePath(path.join(context.outputDir, path.dirname(this.docFile.relativePackagePath), `${this.id}.md`));
 
     return context.outputResolver(file);
   }

packages/ts-doc/src/models/DocSymbol.spec.js

@@ -26,6 +26,7 @@ describe("DocSymbol", () => {
 
     this.docSymbol = new DocSymbol();
     this.docSymbol.symbolName = "SymbolName";
+    this.docSymbol.symbolType = "Const";
     await this.docSymbol.setDocFile({
       file: path.join(process.cwd(), "/packages/common/di/lib/file.d.ts"),
       path: path.join(process.cwd(), "/packages/common/di/lib/file.ts"),
@@ -88,10 +89,10 @@ describe("DocSymbol", () => {
   });
 
   it("should return the url", () => {
-    expect(this.docSymbol.url).to.eq("/api/common/di/SymbolName.html");
+    expect(this.docSymbol.url).to.eq("/api/common/di/const-symbol-name.html");
   });
 
   it("should return the outputPath", () => {
-    expect(this.docSymbol.outputPath).to.eq(path.join(process.cwd(), "/docs/api/common/di/SymbolName.md"));
+    expect(this.docSymbol.outputPath).to.eq(path.join(process.cwd(), "/docs/api/common/di/const-symbol-name.md"));
   });
 });

packages/ts-doc/src/parsers/DocParser.js

@@ -37,32 +37,31 @@ class DocParser {
   static async parse(docFile) {
     const {symbols} = new DocParser(docFile.contents).parse();
 
-    for (const [, symbol] of symbols) {
-      try {
-        await symbol.setDocFile(docFile);
+    const promises = await Promise.all(
+      [...symbols.values()].map(async (symbol) => {
+        try {
+          await symbol.setDocFile(docFile);
+
+          return symbol;
+        } catch (er) {
+          logger.error("Fail to process symbol", {symbol, error: er});
+        }
+      })
+    );
+
+    const parsedSymbols = await Promise.all(promises);
+
+    for (const symbol of parsedSymbols) {
+      if (symbol) {
         const newSymbol = context.symbols.push(symbol);
+
         docFile.symbols.set(newSymbol.symbolName, newSymbol);
-      } catch (er) {
-        logger.error("Fail to process symbol", {symbol, error: er});
       }
     }
 
     return docFile.symbols;
   }
 
-  // /**
-  //  *
-  //  * @param str
-  //  * @returns {string}
-  //  */
-  // overview (str = '') {
-  //   return stripsTags(stripsComments(str))
-  //     .split('\n')
-  //     .filter(o => !!o.trim())
-  //     .join('\n')
-  //     .trim()
-  // }
-
   /**
    *
    */

packages/ts-doc/src/scan/scan.js

@@ -58,17 +58,24 @@ module.exports = {
     let symbolsSize = 0;
     const files = await globby(patterns);
 
-    for (const file of files) {
-      try {
-        const symbols = await DocParser.parse(new DocFile(file));
+    // paginate files by 5
+    for (let i = 0; i < files.length; i += 5) {
+      const filesChunk = files.slice(i, i + 5);
 
-        symbols.forEach((symbol) => {
-          context.logger(`Scanned symbol '${chalk.cyan(symbol.symbolName)}'`);
-          symbolsSize++;
-        });
-      } catch (er) {
-        context.logger.error(chalk.red(er), er.stack);
-      }
+      await Promise.all(
+        filesChunk.map(async (file) => {
+          try {
+            const symbols = await DocParser.parse(new DocFile(file));
+
+            symbols.forEach((symbol) => {
+              context.logger(`Scanned symbol '${chalk.cyan(symbol.symbolName)}'`);
+              symbolsSize++;
+            });
+          } catch (er) {
+            context.logger.error(chalk.red(er), er.stack);
+          }
+        })
+      );
     }
 
     context.logger(`${chalk.green(symbolsSize)} scanned symbols`);

packages/ts-doc/src/tasks/build-api.js

@@ -15,13 +15,17 @@ module.exports = {
       .then(() => context.readPkg())
       .then(() => scanComponents(context.templatesDir))
       .then(() => scanFiles(context.scanPatterns))
-      .then(() => {
+      .then(async () => {
         let symbols = 0;
-        context.symbols.forEach((symbol) => {
-          const content = context.components.page(symbol);
-          symbols++;
-          return writeSymbol(symbol, content);
-        });
+
+        await Promise.all(
+          context.symbols.toArray().map((symbol) => {
+            const content = context.components.page(symbol);
+            symbols++;
+            return writeSymbol(symbol, content);
+          })
+        );
+
         logger(chalk.green(symbols) + " symbols write");
       })
       .then(() => writeJson())

packages/ts-doc/src/utils/dashCase.js

@@ -0,0 +1,5 @@
+const snakeCase = require("lodash/snakeCase");
+
+module.exports.dashCase = function dashCase(str) {
+  return snakeCase(str).replace(/_/g, "-");
+};

packages/ts-doc/src/utils/dashCase.spec.js

@@ -0,0 +1,13 @@
+const {expect} = require("chai");
+const {dashCase} = require("./dashCase");
+
+describe("dashCase", () => {
+  it("should convert camelCase to dash-case", () => {
+    expect(dashCase("camelCase")).to.equal("camel-case");
+    expect(dashCase("camelCase-test")).to.equal("camel-case-test");
+    expect(dashCase("")).to.equal("");
+    expect(dashCase("XMLHttpRequest")).to.equal("xml-http-request");
+    expect(dashCase("__foo_bar__")).to.equal("foo-bar");
+    expect(dashCase("  spaced  words  ")).to.equal("spaced-words");
+  });
+});

packages/ts-doc/src/write/write.js

@@ -5,24 +5,39 @@ const logger = require("fancy-log");
 const chalk = require("chalk");
 const {context, symbolTypes, symbolStatus} = require("../context");
 
+let cache = new Set();
+
 module.exports = {
   /**
    *
    * @param symbol
    * @param content
    */
-  writeSymbol(symbol, content) {
+  async writeSymbol(symbol, content) {
     if (symbol.symbolName.trim() === "") {
-      console.error("Symbol empty =>", symbol);
       return;
     }
 
+    // prevent duplicate write
+    if (cache.has(symbol.outputPath)) {
+      return;
+    }
+
+    cache.add(symbol.outputPath);
+
     try {
-      fsExtra.mkdirsSync(path.dirname(symbol.outputPath), {});
-    } catch (er) {}
-    fsExtra.writeFileSync(symbol.outputPath, content.trim(), {
-      flag: "w+"
+      await fsExtra.mkdirs(path.dirname(symbol.outputPath), {});
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        logger.warn(`Failed to create directory for ${symbol.outputPath}: ${error.message}`);
+        throw error;
+      }
+    }
+
+    await fsExtra.writeFile(symbol.outputPath, content.trim(), {
+      flag: "w"
     });
+
     logger(`Write '${chalk.cyan(symbol.outputPath.replace(context.rootDir, ""))}'`);
   },
 
@@ -35,7 +50,7 @@ module.exports = {
     const {version, scope} = context;
 
     const modules = context.symbols.toArray().reduce((acc, symbol) => {
-      const {symbolName, module, exported, symbolType, symbolLabel, symbolCode, labels} = symbol;
+      const {symbolName, module, exported, symbolType, symbolLabel, symbolCode, labels, id} = symbol;
 
       const key = module.moduleName;
       acc[key] = acc[key] || {symbols: [], name: key};
@@ -47,6 +62,7 @@ module.exports = {
       }
 
       acc[key].symbols.push({
+        id,
         path: symbol.url.replace(".html", ""),
         symbolName,
         module: module.moduleName,

packages/ts-doc/test/snapshots/ControllerProvider.md

@@ -15,7 +15,7 @@ meta:
 
 
 <div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang "><span class="token keyword">class</span> ControllerProvider&lt;T<span class="token punctuation"> = </span><span class="token keyword">any</span>&gt; <span class="token keyword">extends</span> Provider&lt;T&gt; <span class="token punctuation">{</span>
-    <span class="token keyword">readonly</span> entity<span class="token punctuation">:</span> <a href="/api/schema/domain/JsonEntityStore.html"><span class="token">JsonEntityStore</span></a><span class="token punctuation">;</span>
+    <span class="token keyword">readonly</span> entity<span class="token punctuation">:</span> <a href="/api/schema/domain/class-json-entity-store.html"><span class="token">JsonEntityStore</span></a><span class="token punctuation">;</span>
 
 
 
@@ -25,9 +25,9 @@ meta:
 
     get <span class="token function">endpoints</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span> EndpointMetadata<span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span>
 
-    get <span class="token function">children</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span> <a href="/api/common/platform/domain/IChildrenController.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span>
+    get <span class="token function">children</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span> <a href="/api/common/platform/domain/interface-i-children-controller.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span>
 
-    set <span class="token function">children</span><span class="token punctuation">(</span>children<span class="token punctuation">:</span> <a href="/api/common/platform/domain/IChildrenController.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
+    set <span class="token function">children</span><span class="token punctuation">(</span>children<span class="token punctuation">:</span> <a href="/api/common/platform/domain/interface-i-children-controller.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
 
     get <span class="token function">routerOptions</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span> <span class="token keyword">any</span><span class="token punctuation">;</span>
 
@@ -82,7 +82,7 @@ Controllers that depend to this controller.
 ::: v-pre
 
 <div class="method-overview">
-<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang "><span class="token keyword">readonly</span> entity<span class="token punctuation">:</span> <a href="/api/schema/domain/JsonEntityStore.html"><span class="token">JsonEntityStore</span></a><span class="token punctuation">;</span></code></pre></div>
+<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang "><span class="token keyword">readonly</span> entity<span class="token punctuation">:</span> <a href="/api/schema/domain/class-json-entity-store.html"><span class="token">JsonEntityStore</span></a><span class="token punctuation">;</span></code></pre></div>
 
 </div>
 
@@ -150,7 +150,7 @@ Controllers that depend to this controller.
 ::: v-pre
 
 <div class="method-overview">
-<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang ">get <span class="token function">children</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span> <a href="/api/common/platform/domain/IChildrenController.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span></code></pre></div>
+<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang ">get <span class="token function">children</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span> <a href="/api/common/platform/domain/interface-i-children-controller.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">;</span></code></pre></div>
 
 </div>
 
@@ -167,7 +167,7 @@ Controllers that depend to this controller.
 ::: v-pre
 
 <div class="method-overview">
-<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang ">set <span class="token function">children</span><span class="token punctuation">(</span>children<span class="token punctuation">:</span> <a href="/api/common/platform/domain/IChildrenController.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre></div>
+<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang ">set <span class="token function">children</span><span class="token punctuation">(</span>children<span class="token punctuation">:</span> <a href="/api/common/platform/domain/interface-i-children-controller.html"><span class="token">IChildrenController</span></a><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre></div>
 
 </div>
 

packages/ts-doc/test/snapshots/Ignore.md

@@ -14,15 +14,15 @@ meta:
 ## Overview
 
 
-<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang ">function <span class="token function">Ignore</span><span class="token punctuation">(</span>cb?<span class="token punctuation">:</span> <span class="token keyword">boolean</span> | <a href="/api/schema/interfaces/IgnoreCallback.html"><span class="token">IgnoreCallback</span></a><span class="token punctuation">)</span><span class="token punctuation">:</span> <span class="token punctuation">(</span>...args<span class="token punctuation">:</span> <span class="token keyword">any</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span> =&gt; <span class="token keyword">any</span><span class="token punctuation">;</span></code></pre></div>
+<div class="language-typescript"><pre class="language-typescript" v-pre=""><code class="typescript-lang ">function <span class="token function">Ignore</span><span class="token punctuation">(</span>cb?<span class="token punctuation">:</span> <span class="token keyword">boolean</span> | <a href="/api/schema/interfaces/interface-ignore-callback.html"><span class="token">IgnoreCallback</span></a><span class="token punctuation">)</span><span class="token punctuation">:</span> <span class="token punctuation">(</span>...args<span class="token punctuation">:</span> <span class="token keyword">any</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">)</span> =&gt; <span class="token keyword">any</span><span class="token punctuation">;</span></code></pre></div>
 
 
 
 
 <!-- Params -->
 Param | Type | Description
 ---|---|---
- cb | `boolean` "&#124;" <a href="/api/schema/interfaces/IgnoreCallback.html"><span class="token">IgnoreCallback</span></a> | Optional. Callback to know if the property must be ignored 
+ cb | `boolean` "&#124;" <a href="/api/schema/interfaces/interface-ignore-callback.html"><span class="token">IgnoreCallback</span></a> | Optional. Callback to know if the property must be ignored