Have ideas to improve npm?Join in the discussion! »

detsTypeScript icon, indicating that this package has built-in type declarations

0.9.3 • Public • Published

dets

Build Status npm GitHub tag GitHub issues

(pronounced: deee - ts)

A TypeScript declaration file bundler.

dets is a small utility to generate single-file TypeScript declaration files. It can operate in multiple modes.

It is best used if you want to selectively export an API or if you want to build an isolated d.ts file that does not depend on any other declaration packages.

Installation

You can run dets directly via npx. Otherwise, if you want to use it globally you can install it via:

npm i dets -g

We recommend a local installation though:

npm i dets --save-dev

Usage

There are two primary ways of using dets: Either via the command line or programmatically.

Special Treatments

Ignoring Properties

By default, members that have a @ignore comment will be ignored. Therefore, an interface like

interface Foo {
  bar: boolean;
  /**
   * @ignore
   */
  foo: string;
}

will be changed by dets to look like:

interface Foo {
  bar: boolean;
}

This can be disabled via the CLI or programmatic options (--no-ignore). Additionally, a special comment like @dets_preserve could be added, too.

interface Foo {
  bar: boolean;
  /**
   * @ignore
   * @dets_preserve
   */
  foo: string;
}

Here, the property is kept, but the dets_preserve dets comment will be removed:

interface Foo {
  bar: boolean;
  /**
   * @ignore
   */
  foo: string;
}

Removing Properties

When doing interface merging certain properties may be desired to be hidden. To do this a special tag comment @dets_removeprop is used:

// original interface
interface Foo {
  foo: string;
  bar: boolean;
}

// somewhere later
/**
 * @dets_removeprop foo
 */
interface Foo {
  qxz: number;
}

This results in the merged interface, just without the excluded property:

interface Foo {
  bar: boolean;
  qxz: number;
}

Removing Inheritance Clauses

When doing interface merging certain extend clauses may be desired to be hidden. To do this a special tag comment @dets_removeclause is used:

// original interface
interface Foo extends FooBase1, FooBase2 {
  foo: string;
}

// somewhere later
/**
 * @dets_removeclause FooBase1
 */
interface Foo {}

This results in the merged interface, just without the excluded clauses:

interface Foo extends FooBase2 {
  foo: string;
}

From the CLI

An example call for dets from the command line is:

dets --name foo --files src/**/*.ts --types src/index.ts --out dist/index.d.ts

Here we use a glob pattern for the input files and an explicit path for the output.

The available command line arguments are:

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
  --name     Sets the name of the module                                [string]
  --files    Sets the files referenced by TypeScript       [array] [default: []]
  --types    Sets the type entry modules to export via their file path
                                                           [array] [default: []]
  --apis     Sets the interfaces to include using "InterfaceName:FilePath"
             syntax                                        [array] [default: []]
  --imports  Sets the imports to avoid bundling in via their package names
                                                           [array] [default: []]
  --out      Sets the path to the output file
                                         [string] [default: "./dist/index.d.ts"]

If name is omitted then the name from the closest package.json is taken.

From Node Applications

An example code for using dets in a Node.js application is:

import { generateDeclaration } from "dets";
import { writeFileSync } from "fs";

const content = generateDeclaration({
  name: "foo",
  root: process.cwd(),
  files: ["src/**/*.ts"],
  types: ["src/index.ts"]
});

writeFileSync("dist/index.d.ts", content, "utf8");

This is effectively the same call as the example in the CLI section.

There are multiple other possibilities, which may be relevant.

The basis for most operations is a DeclVisitorContext, which can be created via the setupVisitorContext function.

import { setupVisitorContext } from "dets";

const context = setupVisitorContext('foo', ["src/**/*.ts"]);

Using the DeclVisitorContext you can fill from an exported object, which is automatically enriched with all available information form the given input files:

import { fillVisitorContextFromApi } from "dets";

fillVisitorContextFromApi(context, 'src/types/api.ts', 'MyExportedApi');

Alternatively, just get all exports from a given module.

Using the DeclVisitorContext you can fill from an exported object, which is automatically enriched with all available information form the given input files:

import { fillVisitorContextFromTypes } from "dets";

fillVisitorContextFromTypes(context, 'src/types/index.ts');

Development

Right now dets is fully in development. So things may change in the (near) future.

Any ideas, issues, or enhancements are much appreciated!

We follow common sense here, so I hope that we do not need a long code of conduct or anything overall complex for everyone to feel welcome here.

License

MIT License (MIT). For more information see LICENSE file.

Install

npm i dets

DownloadsWeekly Downloads

1,504

Version

0.9.3

License

MIT

Unpacked Size

202 kB

Total Files

42

Last publish

Collaborators

  • avatar