@rushstack/typings-generator

Typings Generator

Installation

npm install @rushstack/typings-generator --save-dev

Overview

This is a utility for generating typings for non-TS files. It can operate in either a single-run mode or a watch mode. It is designed to generate .d.ts files with a specified generation function for all files matching specified file extensions, with an option to ignore individual files.

Usage

import { TypingsGenerator } from '@rushstack/typings-generator';

const typingsGenerator: TypingsGenerator = new TypingsGenerator({
  srcFolder: '/repo/package/src',
  generatedTsFolder: '/repo/package/temp/generated-typings',
  fileExtensions: ['file-extension'],
  parseAndGenerateTypings: (fileContents: string, filePath: string) => {
    const parsedFile = parseFile(fileContents);
    const typings: string = generateTypings(parsedFile);
    return typings;
  }
});

// To run once before a compilation:
await typingsGenerator.generateTypings();

// To start a watcher:
await typingsGenerator.runWatcher();

Options

srcFolder = '...'

This property is used as the source root folder for discovery of files for which typings should be generated.

generatedTsFolder = '...'

This property specifies the folder in which .d.ts files should be dropped. It is recommended that this be a folder parallel to the source folder, specified in addition to the source folder in the rootDirs tsconfig.json option. The folder specified by this option is emptied when the utility is invoked.

fileExtensions = [...]

This property enumerates the file extensions that should be handled.

parseAndGenerateTypings = (fileContents: string, filePath: string) => string | Promise<string>

This property is used to specify the function that should be called on every file for which typings are being generated. In watch mode, this is called on every file creation and file update. It should return TypeScript declarations for the file it is called with.

terminal

Optionally provide a Terminal object for logging. If one isn't provided, logs will go to the console.

filesToIgnore

Optionally, provide an array of paths to files that should be ignored. These paths can either be absolute paths, or paths relative to the srcFolder

StringValuesTypingsGenerator

There is an extension of this utility specifically for file types where typings should be a simple set of exported string values. This is useful for file types like CSS and RESX. This class takes the same options as the standard TypingsGenerator, with one additional option (exportAsDefault) and a different return value for parseAndGenerateTypings.

parseAndGenerateTypings = (fileContents: string, filePath: string) => { typings: ({ exportName: string, comment?: string })[] } | Promise<{ typings: ({ exportName: string, comment?: string })[] }>

This function should behave the same as the parseAndGenerateTypings function for the standard TypingsGenerator, except that it should return an object with a typings property, set to an array of objects with an exportName property and an optional comment property. See the example below.

Example return value:

{
  typings: [
    {
      exportName: 'myExport'
    },
    {
      exportName: 'myOtherExport',
      comment: 'This is the other export'
    }
  ]
}

Example generated declaration file:

// This file was generated by a tool. Modifying it will produce unexpected behavior

export declare const myExport: string;

/**
 * This is the other export
 */
export declare const myOtherExport: string;

exportAsDefault = true | false

If this option is set to true, the typings will be exported wrapped in a default property. This allows the file to be imported by using the import myFile from './myFile.my-extension'; syntax instead of the import { myExport } from './myFile.my-extension'; or the import * as myFile from './myFile.my-extension'; syntax. This style of export is not recommended as it can prevent tree-shaking optimization.