4457244662

Build Type

push

github

Committed by GitHub

Commit Message

Merge pull request #40 from homer0/next

Run Details

103 of 103 branches covered (100.0%)

Branch coverage included in aggregate %.

1011 of 1011 relevant lines covered (100.0%)

2.42 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

100.0

/src/features/tsUtilityTypes.js

// @ts-check
const path = require('path');

/**
 * This class adds extra type definitions for TypeScript utility types. If the project includes
 * a `typedef` file, the definitions will be added at the end of the file; otherwise, they'll be
 * added to the first file being parsed.
 */
class TSUtilitiesTypes {
  /**
   * @param {EventEmitter} events       To hook to the necessary events to add the
   *                                    definitions.
   * @param {EventNames}   EVENT_NAMES  To get the name of the events the class needs to
   *                                    listen for.
   */
  constructor(events, EVENT_NAMES) {
    /**
     * If a `typedef` file is found, this property will have its path.
     *
     * @type {?string}
     * @access protected
     * @ignore
     */
    this._typedefFile = null;
    /**
     * A control flag used when parsing the files in order to know if the defintions were
     * already added or not.
     *
     * @type {boolean}
     * @access protected
     * @ignore
     */
    this._added = false;
    /**
     * The base URL of where the types are documented.
     *
     * @type {string}
     * @access protected
     * @ignore
     */
    this._typesUrl = 'https://www.typescriptlang.org/docs/handbook/utility-types.html';
    /**
     * The dictionary of the utility types. The keys are the names of the types and the
     * values their anchor section on the documentation page.
     *
     * @type {Object.<string, string>}
     * @access protected
     * @ignore
     */
    this._types = {
      Partial: 'partialt',
      Readonly: 'readonlyt',
      Record: 'recordkt',
      Pick: 'picktk',
      Omit: 'omittk',
      Exclude: 'excludetu',
      Extract: 'extracttu',
      NonNullable: 'nonnullablet',
      Parameters: 'parameterst',
      ConstructorParameters: 'constructorparameterst',
      ReturnType: 'returntypet',
      InstanceType: 'instancetypet',
      Required: 'requiredt',
      ThisParameterType: 'thisparametertype',
      OmitThisParameter: 'omitthisparameter',
      ThisType: 'thistypet',
    };
    // Setup the listeners.
    events.on(EVENT_NAMES.parseBegin, this._findTypedefFile.bind(this));
    events.on(EVENT_NAMES.commentsReady, this._addTypes.bind(this));
  }
  /**
   * This is called by the plugin in order to add the types.
   *
   * @param {string} source    The code of the file being parsed.
   * @param {string} filename  The path of the file being parsed. This is used in case a
   *                           `typedef`
   *                           file exists on the project, to validate if the comments
   *                           should be added on that file.
   * @returns {string}
   * @access protected
   * @ignore
   */
  _addTypes(source, filename) {
    let result;
    if (this._added || (this._typedefFile && filename !== this._typedefFile)) {
      result = source;
    } else {
      const comments = this._getComments();
      result = `${source}\n\n${comments}`;
      this._added = true;
    }

    return result;
  }
  /**
   * This is called by the plugin before the parsing beings, so the class can identify if
   * the project includes a `typedef` file.
   *
   * @param {JSDocParseBeginEventPayload} event  The event information, with the list of
   *                                             files that going to be parsed.
   */
  _findTypedefFile(event) {
    const typedef = event.sourcefiles.find((file) =>
      path.basename(file).match(/^typedef\.[jt]sx?$/),
    );

    this._typedefFile = typedef || null;
    this._added = false;
  }
  /**
   * Generates the `typedef` blocks for the TypeScript utility types.
   *
   * @returns {string}
   * @access protected
   * @ignore
   */
  _getComments() {
    return Object.entries(this._types)
      .map(([name, anchor]) => [
        '/**',
        ` * @external ${name}`,
        ` * @see ${this._typesUrl}#${anchor}`,
        ' */\n',
      ])
      .reduce((acc, lines) => [...acc, ...lines], [])
      .join('\n');
  }
}

module.exports.TSUtilitiesTypes = TSUtilitiesTypes;

1	// @ts-check	1✔
2	const path = require('path');	1✔
3		1✔
4	/**	1✔
5	* This class adds extra type definitions for TypeScript utility types. If the project includes	1✔
6	* a `typedef` file, the definitions will be added at the end of the file; otherwise, they'll be	1✔
7	* added to the first file being parsed.	1✔
8	*/	1✔
9	class TSUtilitiesTypes {	1✔
10	/**	1✔
11	* @param {EventEmitter} events To hook to the necessary events to add the	1✔
12	* definitions.	1✔
13	* @param {EventNames} EVENT_NAMES To get the name of the events the class needs to	1✔
14	* listen for.	1✔
15	*/	1✔
16	constructor(events, EVENT_NAMES) {	1✔
17	/**	3✔
18	* If a `typedef` file is found, this property will have its path.	3✔
19	*	3✔
20	* @type {?string}	3✔
21	* @access protected	3✔
22	* @ignore	3✔
23	*/	3✔
24	this._typedefFile = null;	3✔
25	/**	3✔
26	* A control flag used when parsing the files in order to know if the defintions were	3✔
27	* already added or not.	3✔
28	*	3✔
29	* @type {boolean}	3✔
30	* @access protected	3✔
31	* @ignore	3✔
32	*/	3✔
33	this._added = false;	3✔
34	/**	3✔
35	* The base URL of where the types are documented.	3✔
36	*	3✔
37	* @type {string}	3✔
38	* @access protected	3✔
39	* @ignore	3✔
40	*/	3✔
41	this._typesUrl = 'https://www.typescriptlang.org/docs/handbook/utility-types.html';	3✔
42	/**	3✔
43	* The dictionary of the utility types. The keys are the names of the types and the	3✔
44	* values their anchor section on the documentation page.	3✔
45	*	3✔
46	* @type {Object.<string, string>}	3✔
47	* @access protected	3✔
48	* @ignore	3✔
49	*/	3✔
50	this._types = {	3✔
51	Partial: 'partialt',	3✔
52	Readonly: 'readonlyt',	3✔
53	Record: 'recordkt',	3✔
54	Pick: 'picktk',	3✔
55	Omit: 'omittk',	3✔
56	Exclude: 'excludetu',	3✔
57	Extract: 'extracttu',	3✔
58	NonNullable: 'nonnullablet',	3✔
59	Parameters: 'parameterst',	3✔
60	ConstructorParameters: 'constructorparameterst',	3✔
61	ReturnType: 'returntypet',	3✔
62	InstanceType: 'instancetypet',	3✔
63	Required: 'requiredt',	3✔
64	ThisParameterType: 'thisparametertype',	3✔
65	OmitThisParameter: 'omitthisparameter',	3✔
66	ThisType: 'thistypet',	3✔
67	};	3✔
68	// Setup the listeners.	3✔
69	events.on(EVENT_NAMES.parseBegin, this._findTypedefFile.bind(this));	3✔
70	events.on(EVENT_NAMES.commentsReady, this._addTypes.bind(this));	3✔
71	}	3✔
72	/**	1✔
73	* This is called by the plugin in order to add the types.	1✔
74	*	1✔
75	* @param {string} source The code of the file being parsed.	1✔
76	* @param {string} filename The path of the file being parsed. This is used in case a	1✔
77	* `typedef`	1✔
78	* file exists on the project, to validate if the comments	1✔
79	* should be added on that file.	1✔
80	* @returns {string}	1✔
81	* @access protected	1✔
82	* @ignore	1✔
83	*/	1✔
84	_addTypes(source, filename) {	1✔
85	let result;	4✔
86	if (this._added \|\| (this._typedefFile && filename !== this._typedefFile)) {	4✔
87	result = source;	2✔
88	} else {	2✔
89	const comments = this._getComments();	2✔
90	result = `${source}\n\n${comments}`;	2✔
91	this._added = true;	2✔
92	}	2✔
93		4✔
94	return result;	4✔
95	}	4✔
96	/**	1✔
97	* This is called by the plugin before the parsing beings, so the class can identify if	1✔
98	* the project includes a `typedef` file.	1✔
99	*	1✔
100	* @param {JSDocParseBeginEventPayload} event The event information, with the list of	1✔
101	* files that going to be parsed.	1✔
102	*/	1✔
103	_findTypedefFile(event) {	1✔
104	const typedef = event.sourcefiles.find((file) =>	2✔
105	path.basename(file).match(/^typedef\.[jt]sx?$/),	2✔
106	);	2✔
107		2✔
108	this._typedefFile = typedef \|\| null;	2✔
109	this._added = false;	2✔
110	}	2✔
111	/**	1✔
112	* Generates the `typedef` blocks for the TypeScript utility types.	1✔
113	*	1✔
114	* @returns {string}	1✔
115	* @access protected	1✔
116	* @ignore	1✔
117	*/	1✔
118	_getComments() {	1✔
119	return Object.entries(this._types)	2✔
120	.map(([name, anchor]) => [	2✔
121	'/**',	32✔
122	` * @external ${name}`,	32✔
123	` * @see ${this._typesUrl}#${anchor}`,	32✔
124	' */\n',	32✔
125	])	2✔
126	.reduce((acc, lines) => [...acc, ...lines], [])	2✔
127	.join('\n');	2✔
128	}	2✔
129	}	1✔
130		1✔
131	module.exports.TSUtilitiesTypes = TSUtilitiesTypes;	1✔

homer0 / jsdoc-ts-utils / 4457244662

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous