Have tsd-jsdoc generate default exports

src/Emitter.ts

@@ -1,6 +1,6 @@
 import * as ts from 'typescript';
 import { Dictionary } from './Dictionary';
-import { warn } from './logger';
+import { warn, debug, docletDebugInfo } from './logger';
 import { assertNever } from './assert_never';
 import {
     createClass,
@@ -11,6 +11,7 @@ import {
     createClassMember,
     createInterfaceMember,
     createNamespaceMember,
+    createExportDefault,
     createModule,
     createNamespace,
     createTypedef,
@@ -39,6 +40,14 @@ function isEnum(doclet: TDoclet)
     return (doclet.kind === 'member' || doclet.kind === 'constant') && doclet.isEnum;
 }
 
+function isExportDefault(doclet: TDoclet)
+{
+    return (
+        (doclet.kind === 'member') && doclet.longname.startsWith('module:')
+        && doclet.meta && (doclet.meta.code.name === "module.exports")
+    );
+}
+
 function shouldMoveOutOfClass(doclet: TDoclet)
 {
     return isClassLike(doclet)
@@ -61,6 +70,8 @@ export class Emitter
 
     parse(docs?: TAnyDoclet[])
     {
+        debug(`Emitter.parse()`);
+
         this.results = [];
         this._treeRoots = [];
         this._treeNodes = {};
@@ -75,6 +86,8 @@ export class Emitter
 
     emit()
     {
+        debug(`Emitter.emit()`);
+
         const resultFile = ts.createSourceFile(
             'types.d.ts',
             '',
@@ -100,22 +113,32 @@ export class Emitter
 
     private _createTreeNodes(docs: TAnyDoclet[])
     {
+        debug(`Emitter._createTreeNodes()`);
+
         for (let i = 0; i < docs.length; ++i)
         {
             const doclet = docs[i];
 
             if (doclet.kind === 'package' || this._ignoreDoclet(doclet))
+            {
+                debug(`Emitter._createTreeNodes(): skipping ${docletDebugInfo(doclet)} (package or ignored)`, doclet);
                 continue;
+            }
 
             if (!this._treeNodes[doclet.longname])
             {
+                debug(`Emitter._createTreeNodes(): adding ${docletDebugInfo(doclet)} to this._treeNodes`);
                 this._treeNodes[doclet.longname] = { doclet, children: [] };
+            } else {
+                debug(`Emitter._createTreeNodes(): skipping ${docletDebugInfo(doclet)} (default)`, doclet);
             }
         }
     }
 
     private _buildTree(docs: TAnyDoclet[])
     {
+        debug(`Emitter._buildTree()`);
+
         for (let i = 0; i < docs.length; ++i)
         {
             const doclet = docs[i];
@@ -158,7 +181,18 @@ export class Emitter
                 }
             }
 
-            if (doclet.memberof)
+            if (isExportDefault(doclet))
+            {
+                const parentModule = this._treeNodes[doclet.longname];
+                if (parentModule) {
+                    debug(`Emitter._buildTree(): adding 'export default' ${docletDebugInfo(doclet)} to module ${docletDebugInfo(parentModule.doclet)}`);
+                    parentModule.children.push({ doclet: doclet, children: [] });
+                } else {
+                    warn(`Failed to find parent module of 'export default' doclet ${doclet.longname}`, doclet);
+                    continue;
+                }
+            }
+            else if (doclet.memberof)
             {
                 const parent = this._treeNodes[doclet.memberof];
 
@@ -211,6 +245,8 @@ export class Emitter
 
     private _parseTree()
     {
+        debug(`Emitter._parseTree()`);
+
         for (let i = 0; i < this._treeRoots.length; ++i)
         {
             const node = this._parseTreeNode(this._treeRoots[i]);
@@ -222,6 +258,8 @@ export class Emitter
 
     private _parseTreeNode(node: IDocletTreeNode, parent?: IDocletTreeNode): ts.Node | null
     {
+        debug(`Emitter._parseTreeNode(${docletDebugInfo(node.doclet)}, parent=${parent ? docletDebugInfo(parent.doclet) : parent})`);
+
         const children: ts.Node[] = [];
 
         if (children)
@@ -242,14 +280,18 @@ export class Emitter
 
             case 'constant':
             case 'member':
-                if (node.doclet.isEnum)
-                    return createEnum(node.doclet);
-                else if (parent && parent.doclet.kind === 'class')
-                    return createClassMember(node.doclet);
-                else if (parent && parent.doclet.kind === 'interface')
-                    return createInterfaceMember(node.doclet);
-                else
-                    return createNamespaceMember(node.doclet);
+                if (isExportDefault(node.doclet)) {
+                    return createExportDefault(node.doclet);
+                } else {
+                    if (node.doclet.isEnum)
+                        return createEnum(node.doclet);
+                    else if (parent && parent.doclet.kind === 'class')
+                        return createClassMember(node.doclet);
+                    else if (parent && parent.doclet.kind === 'interface')
+                        return createInterfaceMember(node.doclet);
+                    else
+                        return createNamespaceMember(node.doclet);
+                }
 
             case 'callback':
             case 'function':
@@ -296,6 +338,7 @@ export class Emitter
         if (doclet.kind === 'package'
             || doclet.ignore
             || (!this.options.private && doclet.access === 'private')) {
+            debug(`Emitter._ignoreDoclet(doclet=${docletDebugInfo(doclet)}) => true (package, ignored or private disabled)`);
             return true
         }
 
@@ -304,21 +347,31 @@ export class Emitter
         }
 
         const accessLevels = ["private", "package", "protected", "public"];
-        return accessLevels.indexOf(doclet.access.toString()) < accessLevels.indexOf(this.options.access || "package")
+        const ignored = accessLevels.indexOf(doclet.access.toString()) < accessLevels.indexOf(this.options.access || "package");
+        if (ignored) {
+            debug(`Emitter._ignoreDoclet(doclet=${docletDebugInfo(doclet)}) => true (low access level)`);
+        }
+        return ignored;
     }
 
     private _getInterfaceKey(longname?: string): string
     {
+        debug(`Emitter._getInterfaceKey('${longname}')`);
+
         return longname ? longname + '$$interface$helper' : '';
     }
 
     private _getNamespaceKey(longname?: string): string
     {
+        debug(`Emitter._getNamespaceKey('${longname}')`);
+
         return longname ? longname + '$$namespace$helper' : '';
     }
 
     private _getOrCreateClassNamespace(obj: IDocletTreeNode): IDocletTreeNode
     {
+        debug(`Emitter._getOrCreateClassNamespace(${docletDebugInfo(obj.doclet)})`);
+
         if (obj.doclet.kind === 'namespace')
             return obj;
 

src/create_helpers.ts

@@ -1,5 +1,7 @@
+import * as fs from 'fs';
+import * as path from 'path';
 import * as ts from 'typescript';
-import { warn } from './logger';
+import { warn, debug } from './logger';
 import {
     createFunctionParams,
     createFunctionReturnType,
@@ -57,7 +59,8 @@ function validateModuleChildren(children?: ts.Node[])
                 && !ts.isEnumDeclaration(child)
                 && !ts.isModuleDeclaration(child)
                 && !ts.isTypeAliasDeclaration(child)
-                && !ts.isVariableStatement(child))
+                && !ts.isVariableStatement(child)
+                && !ts.isExportAssignment(child))
             {
                 warn('Encountered child that is not a supported declaration, this is likely due to invalid JSDoc.', child);
                 children.splice(i, 1);
@@ -355,6 +358,54 @@ export function createNamespaceMember(doclet: IMemberDoclet): ts.VariableStateme
     ));
 }
 
+export function createExportDefault(doclet: IMemberDoclet): ts.ExportAssignment | null
+{
+    if (doclet.meta)
+    {
+        let exportDefaultValue = doclet.meta.code.value;
+        if (! exportDefaultValue)
+        {
+            // When the 'export default' value is not given in the 'meta.code.value' attribute,
+            // let's read it directly from the source file.
+            const sourcePath : string = path.join(doclet.meta.path, doclet.meta.filename);
+            debug(`create_helpers.ts:createExportDefault(): Reading '${sourcePath}'`);
+            const fd = fs.openSync(sourcePath, "r");
+            if (fd < 0)
+            {
+                warn(`Could not read from '${sourcePath}'`);
+                return null;
+            }
+            const begin = doclet.meta.range[0];
+            const end = doclet.meta.range[1];
+            const length = end - begin;
+            const buffer = Buffer.alloc(length);
+            if (fs.readSync(fd, buffer, 0, length, begin) !== length)
+            {
+                warn(`Could not read from '${sourcePath}'`);
+                return null;
+            }
+            exportDefaultValue = buffer.toString().trim();
+            debug(`create_helpers.ts:createExportDefault(): exportDefaultValue = '${exportDefaultValue}'`);
+            if (exportDefaultValue.endsWith(";"))
+            {
+                exportDefaultValue = exportDefaultValue.slice(0, -1).trimRight();
+            }
+            if (exportDefaultValue.match(/^export +default +/))
+            {
+                exportDefaultValue = exportDefaultValue.replace(/^export +default +/, "");
+            }
+        }
+        debug(`create_helpers.ts:createExportDefault(): exportDefaultValue = '${exportDefaultValue}'`);
+        if (exportDefaultValue)
+        {
+            const expression : ts.Expression = ts.createIdentifier(exportDefaultValue);
+            return handleComment(doclet, ts.createExportDefault(expression));
+        }
+    }
+    warn(`Cannot create an 'export default' instruction. Information missing.`, doclet);
+    return null;
+}
+
 export function createModule(doclet: INamespaceDoclet, nested: boolean, children?: ts.Node[]): ts.ModuleDeclaration
 {
     validateModuleChildren(children);

src/logger.ts

@@ -19,3 +19,32 @@ export function warn(msg: string, data?: any)
         console.warn(data);
     }
 }
+
+let isDebug = false;
+
+export function setDebug(value: boolean)
+{
+    isDebug = value;
+}
+
+export function debug(msg: string, data?: any)
+{
+    if (typeof(console) === 'undefined')
+        return;
+
+    if (isDebug) {
+        console.log(`${header}   ${msg}`);
+        if (arguments.length > 1)
+        {
+            console.log(data);
+        }
+    }
+}
+
+export function docletDebugInfo(doclet: TAnyDoclet) : string {
+    if ((doclet.kind !== 'package') && doclet.meta && doclet.meta.range) {
+        return `{longname='${doclet.longname}', kind='${doclet.kind}, range=[${doclet.meta.range[0]}-${doclet.meta.range[1]}]'}`;
+    } else {
+        return `{longname='${doclet.longname}', kind='${doclet.kind}'}`;
+    }
+}

src/publish.ts

@@ -2,7 +2,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import * as helper from 'jsdoc/util/templateHelper';
 import { Emitter } from './Emitter';
-import { setVerbose } from './logger';
+import { setVerbose, setDebug } from './logger';
 
 /**
  * @param {TAFFY} data - The TaffyDB containing the data that jsdoc parsed.
@@ -17,6 +17,7 @@ export function publish(data: TDocletDb, opts: ITemplateConfig)
     const docs = data().get();
 
     setVerbose(!!opts.verbose);
+    setDebug(!!opts.verbose);
 
     // create an emitter to parse the docs
     const emitter = new Emitter(opts);

src/typings/jsdoc.d.ts

@@ -67,6 +67,10 @@ declare interface IDocletTag {
     value: string;
 }
 
+/**
+ * @warning All attributes listed below are not necessarily generated by jsdoc ('scope' at least), and should be declared optional.
+ * To be checked.
+ */
 declare interface IDocletBase {
     meta?: IDocletMeta;
     name: string;
@@ -121,6 +125,10 @@ declare interface IFunctionDoclet extends IDocletBase {
     virtual?: string[];
 }
 
+/**
+ * @warning All attributes listed below are not necessarily generated by jsdoc ('iEnum' and 'type' at least), and should be declared optional.
+ * To be checked.
+ */
 declare interface IMemberDoclet extends IDocletBase {
     kind: 'member' | 'constant';
     readonly: boolean;

test/expected/module.d.ts

@@ -27,4 +27,8 @@ declare module "array-to-object-keys" {
     function arrayToObjectKeys(array: string[], valueGenerator?: valueGenerator | any): {
         [key: string]: any;
     };
+    /**
+     * Export arrayToObjectKeys as default.
+     */
+    export default arrayToObjectKeys;
 }

test/expected/module2.d.ts

@@ -0,0 +1,34 @@
+/** @module array-to-object-keys
+ */
+declare module "array-to-object-keys" {
+    /**
+     * @typedef valueGenerator
+     * @type {function}
+     * @param {string} value The original array entry
+     * @param {number} index The index of the array entry (starts at 0)
+     * @returns {*}
+     */
+    type valueGenerator = (value: string, index: number) => any;
+    /**
+     * Converts an array to an object with static keys and customizable values
+     * @example
+     * arrayToObjectKeys(["a", "b"])
+     * // {a: null, b: null}
+     * @example
+     * arrayToObjectKeys(["a", "b"], "value")
+     * // {a: "value", b: "value"}
+     * @example
+     * arrayToObjectKeys(["a", "b"], (key, index) => `value for ${key} #${index + 1}`)
+     * // {a: "value for a #1", b: "value for b #2"}
+     * @param {string[]} array Keys for the generated object
+     * @param {valueGenerator|*} [valueGenerator=null] Optional function that sets the object values based on key and index
+     * @returns {Object<string, *>} A generated object based on the array input
+     */
+    function arrayToObjectKeys(array: string[], valueGenerator?: valueGenerator | any): {
+        [key: string]: any;
+    };
+    /**
+     * Export arrayToObjectKeys as default.
+     */
+    export default arrayToObjectKeys;
+}

test/fixtures/module.js

@@ -26,4 +26,7 @@
 const arrayToObjectKeys = (array, valueGenerator = null) => {
 }
 
+/**
+ * Export arrayToObjectKeys as default.
+ */
 export default arrayToObjectKeys