bio-dts 0.3.0 → 0.4.1

package/README.md

@@ -15,6 +15,17 @@ This module provides `pre` and `post` processing helpers to a type definition pi
 npx bio-dts --outDir dist/types -r lib
 ```
 
+
+## Features
+
+* Generates clean type definitions from ES5 code bases
+* Supports ES5 prototypical classes + inheritance
+* Supports optional parameters before required ones
+* Converts JSDoc to [TSDoc](https://github.com/microsoft/tsdoc)
+
+Checkout the [test fixtures](./test/fixtures) for full coverage.
+
+
 ## API
 
 ```javascript
@@ -38,4 +49,4 @@ const transformedCode = postTransform(tsCode);
 generateTypes(files, {
   outDir: 'dist'
 });
-```
+```

package/bin/cmd.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import ts from 'typescript';
+import Module from 'node:module';
 
 import glob from 'tiny-glob';
 
@@ -10,6 +10,9 @@ import fs from 'node:fs';
 import generateTypes from '../lib/generate-types.js';
 
 async function run() {
+
+  const ts = getTypescript();
+
   const args = process.argv.slice(2);
 
   const {
@@ -44,18 +47,12 @@ async function run() {
 
   for (const fileName of fileNames) {
 
-    try {
-      if (fs.statSync(fileName).isDirectory) {
-
-        const globbedFiles = await glob(globPattern, { cwd: fileName, filesOnly: true });
-
-        files.push(...globbedFiles.map(f => path.join(fileName, f)));
-      } else {
-        files.push(fileName);
-      }
-    } catch (err) {
+    if (isDir(fileName)) {
+      const globbedFiles = await glob(globPattern, { cwd: fileName, filesOnly: true });
 
-      // ignore
+      files.push(...globbedFiles.map(f => path.join(fileName, f)));
+    } else {
+      files.push(fileName);
     }
   }
 
@@ -72,6 +69,34 @@ async function run() {
   console.log('Done.');
 }
 
+function isDir(fileName) {
+
+  try {
+    return fs.statSync(fileName).isDirectory();
+  } catch (err) {
+
+    // ignore
+    return false;
+  }
+}
+
+function getTypescript() {
+
+  const cwd = process.cwd();
+
+  const createRequire = Module.createRequire || Module.createRequireFromPath;
+
+  const requireLocal = createRequire(
+    path.join(cwd, '__placeholder__.js')
+  );
+
+  try {
+    return requireLocal('typescript');
+  } catch (err) {
+    throw new Error(`failed to load <typescript> from <${ cwd }>`);
+  }
+}
+
 run().catch(err => {
   console.error(err);
 

package/lib/post-transform.js

@@ -45,73 +45,232 @@ export default function transform(src) {
     return false;
   }
 
-  traverse(body, function(path) {
+  function keepCommentParams(commentPath, params) {
 
-    const {
-      value
-    } = path;
+    const replacements = [];
 
-    // filter private members
-    if (!isPublic(value)) {
-      return replace(path);
+    const comment = commentPath.value;
+
+    const doc = comment.value.replace(/\n\s+/g, '\n ');
+    const tags = parseJSDoc(doc);
+
+    for (const tag of tags) {
+
+      // remove param not mentioned anymore
+      if (tag.name === 'param' && params.every(p => p.name !== tag.param.name)) {
+        replacements.push([ { start: tag.start - 4, end: tag.end } ]);
+
+        continue;
+      }
     }
 
-    // TODO(nikku): transform illegal typescript methods into override calls
+    const newDoc = replacements.slice().reverse().reduce((newDoc, r) => {
 
-    // TODO(nikku): remove annotations
-    //
-    // * @typedef
-    // * @class
-    // * @constructor
-    // * @template
-    // * @method
+      const [ { start, end }, replacement = '' ] = r;
 
-    const comments = path.get('comments') || { value: [] };
+      return replaceJSDoc(newDoc, { start, end }, replacement);
+    }, doc);
 
-    for (const key of keys(comments.value || []).reverse()) {
+    const builder = {
+      'CommentBlock': b.commentBlock,
+      'CommentLine': b.commentLine
+    }[comment.type];
 
-      const comment = comments.get(key);
+    return cleanComment(builder.from({
+      ...comment,
+      value: newDoc
+    }));
+  }
 
-      const replacements = [];
+  function fixOptionalArgsMethods(nodePath) {
 
-      const doc = comment.value.value.replace(/\n\s+/g, '\n ');
-      const tags = parseJSDoc(doc);
+    const {
+      value: node
+    } = nodePath;
 
-      for (const tag of tags) {
-        if (/class|constructor|template|method|typedef/.test(tag.name)) {
-          replacements.push([ { start: tag.start - 4, end: tag.end } ]);
+    if (node.type !== 'TSDeclareMethod' && node.type !== 'TSDeclareFunction') {
+      return;
+    }
 
-          continue;
-        }
+    const hostPath = nodePath.parentPath.value.type === 'ExportNamedDeclaration'
+      ? nodePath.parentPath
+      : nodePath;
 
-        if (tag.type) {
-          replacements.push([ { start: tag.type.start - 1, end: tag.type.end }, '' ]);
-        }
+    const {
+      variations
+    } = node.params.slice().reverse().reduce((res, param) => {
+
+      let {
+        required,
+        variations
+      } = res;
+
+      // required before optional
+      if (param.optional && required) {
+        variations = [
+          ...variations.map(v => v.slice()),
+          ...variations.map(v => v.slice())
+        ];
+
+        variations.forEach((variation, idx) => {
+
+          if (idx < variations.length / 2) {
+            variation.push(b.identifier.from({
+              ...param,
+              optional: false
+            }));
+          }
+        });
+      } else {
 
-        if (tag.param) {
-          replacements.push([ tag.param, tag.param.name ]);
+        if (!param.optional) {
+          required = true;
         }
+
+        variations.forEach((variation) => {
+          const builder = {
+            'RestElement': b.restElement,
+            'Identifier': b.identifier
+          }[param.type];
+
+          variation.push(builder.from(param));
+        });
       }
 
-      const newDoc = replacements.slice().reverse().reduce((newDoc, r) => {
+      return {
+        required,
+        variations
+      };
+    }, {
+      variations: [
+        []
+      ],
+      required: false
+    });
+
+    if (variations.length === 1) {
+      return;
+    }
 
-        const [ { start, end }, replacement = '' ] = r;
+    const commentPaths = hostPath.get('comments');
 
-        return replaceJSDoc(newDoc, { start, end }, replacement);
-      }, doc);
+    // last comment is significant
+    const commentPath = commentPaths?.value && commentPaths.get(commentPaths.value.length - 1) || { value: null };
 
-      // remove entirely, if empty
-      if (!newDoc.replace(/[/*\s]/g, '')) {
-        replace(comment);
+    const replacements = variations.slice().reverse().map(variation => {
+
+      const builder = {
+        'TSDeclareFunction': b.tsDeclareFunction,
+        'TSDeclareMethod': b.tsDeclareMethod
+      }[node.type];
+
+      const variationComments = commentPath.value ? [ keepCommentParams(commentPath, variation) ] : [ ];
+
+      const newNode = builder.from({
+        ...node,
+        params: variation.slice().reverse(),
+        comments: hostPath === nodePath ? variationComments : []
+      });
+
+      return (
+        hostPath === nodePath
+          ? newNode
+          : b.exportNamedDeclaration.from({
+            ...hostPath.value,
+            declaration: newNode,
+            comments: variationComments
+          })
+      );
+    });
+
+    replace(hostPath, ...replacements);
+
+    return replacements;
+  }
+
+
+  function cleanComment(comment) {
+
+    const replacements = [];
+
+    const doc = comment.value.replace(/\n\s+/g, '\n ');
+    const tags = parseJSDoc(doc);
+
+    for (const tag of tags) {
+
+      // remove full line including the non-TS tag
+      if (/class|constructor|template|method|typedef|property/.test(tag.name)) {
+        replacements.push([ { start: tag.start - 4, end: tag.end } ]);
+
+        continue;
+      }
+
+      if (tag.type) {
+        replacements.push([ { start: tag.type.start - 1, end: tag.type.end }, '' ]);
+      }
+
+      if (tag.param) {
+
+        // [foo=10] => foo
+        replacements.push([ tag.param, tag.param.name ]);
+      }
+    }
+
+    const newDoc = replacements.slice().reverse().reduce((newDoc, r) => {
+
+      const [ { start, end }, replacement = '' ] = r;
+
+      return replaceJSDoc(newDoc, { start, end }, replacement);
+    }, doc);
+
+    // remove entirely, if empty
+    if (!newDoc.replace(/[/*\s]/g, '')) {
+      return null;
+    } else {
+      return b.commentBlock.from({
+        type: 'CommentBlock',
+        leading: true,
+        value: newDoc
+      });
+    }
+  }
+
+  /**
+   * @param {import('./util.js').Path} nodePath
+   */
+  function cleanComments(nodePath) {
+
+    // clean JSDoc comments: remove annotation, fixup type parameters
+    const comments = nodePath.get('comments') || { value: [] };
+
+    for (const key of keys(comments.value || []).reverse()) {
+      const comment = comments.get(key);
+
+      const newComment = cleanComment(comment.value);
+      if (newComment) {
+        replace(comment, newComment);
       } else {
-        replace(comment, b.commentBlock.from({
-          type: 'CommentBlock',
-          leading: true,
-          value: newDoc
-        }));
+        replace(comment);
       }
     }
+  }
+
+  traverse(body, function(path) {
+
+    const {
+      value
+    } = path;
+
+    // filter private members
+    if (!isPublic(value)) {
+      return replace(path);
+    }
+
+    if (fixOptionalArgsMethods(path)) {
+      return false;
+    }
 
+    cleanComments(path);
   });
 
   for (const [ path, args ] of replacements) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bio-dts",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Generate sane and clean types from JavaScript sources",
   "type": "module",
   "main": "index.js",
@@ -16,14 +16,14 @@
   "dependencies": {
     "@babel/parser": "^7.21.2",
     "recast": "^0.22.0",
-    "tiny-glob": "^0.2.9",
-    "typescript": "^4.9.5"
+    "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
     "chai": "^4.3.7",
     "eslint": "^8.36.0",
     "eslint-plugin-bpmn-io": "^1.0.0",
-    "mocha": "^10.2.0"
+    "mocha": "^10.2.0",
+    "typescript": "^5.0.2"
   },
   "files": [
     "bin",