@esmbly/transformer-jsdoc
TypeScript icon, indicating that this package has built-in type declarations

0.0.6 • Public • Published

@esmbly/transformer-jsdoc

Transform JavaScript files with JSDoc comments to TypeScript.

Installation

# Using Yarn:
yarn add @esmbly/transformer-jsdoc

# Or, using NPM:
npm install @esmbly/transformer-jsdoc --save

Getting Started

Check out Using the JSDoc transformer for a step-by-step guide on how to get started with @esmbly/transformer-jsdoc and the command-line interface.

Try

Try it out in the Esmbly version of WebAssembly Studio!

Usage

The @esmbly/transformer-jsdoc transforms JavaScript files with JSDoc comments to TypeScript. In order to use it, make sure you have @esmbly/cli installed .

The following Esmbly configuration will transform all JavaScript files located in the src directory and output TypeScript files to the dist directory.

// esmbly.config.js

const JSDoc = require('@esmbly/transformer-jsdoc');

module.exports = {
  input: ['./src/**/*.js'],
  transformers: [
    JSDoc.createTransformer(),
  ],
  output: [
    {
      format: '.ts',
      outDir: 'dist',
      rootDir: 'src',
    },
  ],
};

Configuration

The createTransformer() method accepts an optional configuration object (see the JSDocTransformerOptions interface). The following options are possible.

Option Description Type Default
stripComments (optional) Whether to remove remove the JSDoc comments after the transformation boolean false
customRules (optional) An object containing any custom rules which should be applied (existing rules can be overridden). Check out the custom-rule example for further details. CustomRules

Examples

Supported tags

@param

Synonyms: @arg, @argument

The param tag provides the name, type and an optional description about a function parameter. To correctly be able to transform a documented function to TypeScript you are required to specify the name and type of the parameter you are documenting. The param tags also needs to be in the same order as the function parameters. Any parameter that is missing a name or type will be assumed to be any.

// input.js

/**
 * Add two numbers
 * @param {number} a
 * @param {number} b
 */
export function add(a, b) {
  return a + b;
}
// output.ts

export function add(a: number, b: number) {
  return a + b;
}

There is also support for union and rest parameters

// input.js

/**
 * @param {...number} numbers
 */
export function add(...numbers) {
  return numbers.reduce((total, n) => total + n, 0);
}

/**
 * @param {(number | string)} id
 */
export function toStringId(id) {
  return `ID${id}`;
}
// output.ts

export function add(...numbers: number[]) {
  return numbers.reduce((total, n) => total + n, 0);
}

export function toStringId(id: number | string) {
  return `ID${id}`;
}

@returns

Synonyms: @return

The returns tag specifies the return type of a function.

// input.js

/**
 * Add two numbers
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
export function add(a, b) {
  return a + b;
}
// output.ts

export function add(a: number, b: number): number {
  return a + b;
}

@type

The type tag is used to document the type of a variable.

// input.js

/**
 * @type {number}
 */
const a = add(2, 3);
// output.ts

const a: number = add(2, 3);

@constant

Synonyms: @const

The constant tag is used to document the type of a constant variable. Any documented variable that is declared using the var or let keyword will automatically be transform to a const when transforming to TypeScript.

// input.js

/**
 * @constant {string}
 */
var RED = 'FF0000';
// output.ts

const RED: string = 'FF0000';

@typeArgument

The typeArgument tag is a custom tag (not included in the JSDoc specification) that can be used to specify the the type arguments of a function call.

// input.js

/**
 * @type {number[]}
 * @typeArgument {number}
 */
const arr = toArray(1, 2, 3);
// output.ts

const arr: number[] = toArray<number>(1, 2, 3);

@declare

The declare tag is a custom tag (not included in the JSDoc specification) that can be used to specify that a variable or a function should be declared. Initializers are only allowed for constant values and can only be a string or numeric literal. If a function is tagged with @declare, the function implementation (the function body) will be removed.

// input.js

/**
 * @type {string}
 * @declare
 */
const color = 'red';

/**
 * @type {string}
 * @declare
 */
var someValue;

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 * @declare
 */
function add(a, b) {}
// output.ts

declare const color = 'red';

declare someValue: string;

declare function add(a: number, b: number): number;

Roadmap

JSDoc TypeScript
Abstract @abstract abstract class A { }
Access @access private private someMethod() { }
Callback @callback
Class methods
Enum @enum
Interface @interface
Implements @implements class A implements B { }
Namespace @namespace MyNamespace namespace MyNamespace { }
Nullable type {?number} number | null
Non-nullable type {!number} NonNullable<number> (strictNullChecks)
Optional parameters @param {number} [foo] foo?: number
Private @private private someProperty
Protected @protected protected someProperty
Public @public public someProperty
Read only @readonly readonly someProperty
Static @static static someMethod() { }
Typedef @typedef
Decorator @decorator {inline} @inline

Contributing

All types of contributions are very much welcome. Check out our Contributing Guide for instructions on how to get started.

Package Sidebar

Install

npm i @esmbly/transformer-jsdoc

Weekly Downloads

1

Version

0.0.6

License

MIT

Unpacked Size

810 kB

Total Files

50

Last publish

Collaborators

  • ollelauribostrom