declarator

  

  
⚙️⚡
Declarator
  

  

declarator simplify the use of native javascript projects with a typescript codebase.

Before:

// tsconfig.json
{
  // ...
  "include": ["src", "./types.d.ts"]
}

// types.d.ts
export declare module 'untyped-dependency';

// code.ts
import dependency from 'untyped-dependency'; // any

dependency.methodThatDoesNotExists(); // Fine!
dependency.sum(1, '2'); // Also fine!

After:

$ declarator
#> Generated types for 1 package(s) out of 1.

// code.ts
import dependency from 'untyped-dependency'; // { sum: (a: number, b: number) => number }

// Error: Property 'methodThatDoesNotExists' does not exist on
// type '{ sum: (a: number, b: number) => number }'.
dependency.methodThatDoesNotExists();

// Error: Expected 2 arguments, but got 1.
dependency.sum(1);

Declarator, make your development process faster and more reliable while working with unknown, undocumented and/or untyped javascript code. This automatically generate declaration files, basically using tsc --emitDeclarationOnly for all dependencies that you specify in the config file.

You'll never have to write a bunch of export declare module 'name'; in a types.d.ts. But keep in mind that you'll find some anyies in the progress.

Table of Contents

• Table of Contents
• Installing
• Running
• Configuration
  • Config examples:
• License
• Contact

Installing

# Npx
npx declarator

# Npm
npm install --save-dev declarator
# (Globally)
npm install -g declarator

# Yarn
yarn add -D declarator

Running

For the types to be generated, you need to run declarator command on your machine, with node_modules already present and installed. After running, the types will already be available to be used.

This project has a very simple CLI:

Run declarator --help for an up-to-date version.

Usage: declarator [flags]

Options:
  -V, --version   output the version number
  -d, --debug     output extra debugging (default: false)
  --init          create a blank config file (default: false)
  -h, --help      display help for command

Commands:
  help [command]  display help for command

TIP: You can use it in a npm postinstall script to, after every package install, run declarator and the types will be updated

 // package.json
{
  "scripts": {
    "postinstall": "declarator"
  }
}

Configuration

You create customized behaviors by creating a declarator file. It needs to be in your project root and follow one of these names:

• declarator.js
• declarator.json
• .declarator.js
• .declarator.json
• .declaratorrc
• .declaratorrc.js
• .declaratorrc.json
• package.json (In a declarator section)

Config examples:

The configuration format is specified by the Configuration type.

JsonSchema and JSDoc for auto completion are also available!

declarator.js, .declarator.js, or .declaratorrc.js

//@ts-check

/**
 *  You can export default a function or a object
 *
 * @type {import('declarator').FileConfig}
 */
const config = () => {
  return {
    packages: [
      // Package that will receive all the defaults
      'random-name',
      [
        'random2',
        {
          // Merge defaults here
          merge: true,
          // Specific config for the random2 package.
          include: ['./custom-path-for-this-library']
        }
      ]
    ],
    defaults: {
      // Default config for all packages.
      compilerOptions: {
        // Use LF for compilation
        newLine: 1
      }
    }
  };
};
module.exports = config;

declarator.json, .declarator.json, .declaratorrc or .declaratorrc.json

{
  // WARN: Comments are not allowed in json files!

  // Schema to ide autocompletion (Check if this path is correct)
  "$schema": "./node_modules/declarator/schema.json",
  "packages": [
    // Package that will receive all the defaults
    "random-name",
    [
      "random2",
      {
        // Merge defaults here
        "merge": true,
        // Specific config for the random2 package.
        "include": ["./custom-path-for-this-library"]
      }
    ]
  ],
  "defaults": {
    // Default config for all packages.
    "compilerOptions": {
      // Use LF for compilation
      "newLine": 1
    }
  }
}

package.json

{
  // WARN: Comments are not allowed in json files!

  // ...

  "declarator": {
    // Schema to ide autocompletion (Check if this path is correct)
    "$schema": "./node_modules/declarator/schema.json",
    "packages": [
      // Package that will receive all the defaults
      "random-name",
      [
        "random2",
        {
          // Merge defaults here
          "merge": true,
          // Specific config for the random2 package.
          "include": ["./custom-path-for-this-library"]
        }
      ]
    ],
    "defaults": {
      // Default config for all packages.
      "compilerOptions": {
        // Use LF for compilation
        "newLine": 1
      }
    }
  }
}

License

Licensed under the MIT. See LICENSE for more informations.

Contact

See my contact information on my github profile or open a new issue.