tsd-extract open source npm package

Installation

Choose the installation type:

Quick Take

Examples

Idea

Take a .d.ts TypeScript definitions file as string, extract any definition from it.

No parsing, no dependencies, it’s only ~4.5KB minified.

This program is also suitable for using in MDX where all dependencies are bundled. You would not bundle the whole TypeScript in your blog post strings, would you?

Theoretically, you can use TypeScript and its parser directly, traverse the AST and do the same what this program does, just slower and more cumbersome.

API — `extract()`

The main function extract() is imported like this:

It’s a function which takes two input arguments:

Input argument	Type	Obligatory	Description
	`input` Type: String Obligatory: yes
`input`	String	yes	Type definitions source as string.

	`def` Type: String Obligatory: yes
`def`	String	yes	Name of a definition to extract. Can be system keyword (`export`) or a any variable’s name.

	`opts` Type: Plain object Obligatory: no
`opts`	Plain object	no	Optional Options Object.

The Optional Options Object has the following shape:

Key	Type	Default	Description
	`extractAll` Type: boolean Default: `false`
`extractAll`	boolean	`false`	If enabled, the program will also extract an array of all unique definitions found. This is for GUI app.

	`semi` Type: boolean Default: `true`
`semi`	boolean	`true`	If set to `false`, any semicolons will be omitted from extracted string values and not reported in string index locations. As if they didn’t exist in the source.

	`mustInclude` Type: string Default: `""` (empty string)
`mustInclude`	string	`""` (empty string)	Force algorithm to look for an extra `def` to be present in the finding. Used when there are multiple findings and program otherwise returns the wrong-one.

	`stripAs` Type: boolean Default: `false`
`stripAs`	boolean	`false`	If enabled, instead of `export { x as y } from "z";` it will produce `export { y } from "z";`

	`contentSort` Type: function Default: `undefined`
`contentSort`	function	`undefined`	Optionally, to sort `export` contents, pass a custom compare function to `Array.prototype.sort()` used under the hood, see examples

Here are all defaults in one place for copying:

This function will return a plain object of a shape:

You’ll see three terms used:

“identifiers”
“content”
“value”

Identifiers

That’s any “word” which is located up to equal sign, or bracket of any kind:

// three indentifiers here:
declare function a<b>(c: d): e;
// ^^^^ ^^^^^^^^ ^
//  1      2     3

// two identifiers here:
interface Opts {
  // ^^^^ ^^^^
  //  1     2
  whitelist: string[];
  backend: HeadsAndTailsObj[];
}

// one identifier here:
export { x } from "y";
// ^^^
//  1

The definition def you pass will be matched against these extracted identifiers.

Content

That’s everything after identifiers but excluding any generics and variables in brackets:

// three indentifiers here:
declare function a<b>(c: d): e;
//                   ^^^^^^^^^^
//                   all this^
//
// ^ semicolon will be excluded (if present) opts.semi === false

Value

That’s the whole found statement, from the very first character to the very last-one (except the semicolon if opts.semi === false).

API — `join()`

This function extracts and merges the contents of multiple interfaces:

import { strict as assert } from "assert";
import { join } from "tsd-extract";
let source1 = `type x = {
    a: string;
  } & {
    b: number;
  }`;
let source2 = ` = Statement & {
      c: boolean;
    } & {
      d: null | string;
    }`;
let source3 = ` = zz & {
      e: number;
    } & {
      f: (g) => void;
    }`;
let source4 = null;
let source5 = "";
assert.equal(
  join(source1, source2, source3, source4, source5),
  `{
  a: string;
  b: number;
  c: boolean;
  d: null | string;
  e: number;
  f: (g) => void;
}`
);

The main function join() is imported like this:

It’s a function which takes any amount of string input arguments:

The function will return a string — all contents between curlies extracted, and each lines’s indentation set to two spaces.

API — `defaults`

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — `version`

You can import version:

Changelog

Open Changelog

tsd-extract0.8.3