@polymer/gen-typescript-declarations - npm Package Compare versions

Comparing version 0.3.0 to 0.3.1

CHANGELOG.md

@@ -9,2 +9,7 @@ # Changelog
 
+## [0.3.1] - 2017-12-15
+- Convert Closure `Object` to TypeScript `object`.
+- Use glob patterns instead of RegExps to exclude files.
+- Bump Analyzer version to include https://github.com/Polymer/polymer-analyzer/pull/791 which makes Polymer properties possibly `null|undefined`.
+
 ## [0.3.0] - 2017-12-12
@@ -11,0 +16,0 @@ - `void` is not nullable.

lib/closure-types.js

@@ -137,3 +137,11 @@ "use strict";
     else if (isName(node)) {
-        t = new ts.NameType(node.name);
+        if (node.name === 'Object') {
+            // Closure's `Object` type excludes primitives, so it is closest to
+            // TypeScript's `object`. (Technically this should be `object|Symbol`,
+            // but we will concede that technicality.)
+            t = new ts.NameType('object');
+        }
+        else {
+            t = new ts.NameType(node.name);
+        }
     }
@@ -140,0 +148,0 @@ else {

lib/gen-ts.d.ts

@@ -6,4 +6,4 @@ /**
     /**
-     * Skip source files whose paths match this pattern. If undefined, defaults
-     * to excluding directories ending in "test" or "demo".
+     * Skip source files whose paths match any of these glob patterns. If
+     * undefined, defaults to excluding directories ending in "test" or "demo".
      */
@@ -10,0 +10,0 @@ exclude?: string[];

lib/gen-ts.js

@@ -21,2 +21,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const minimatch = require("minimatch");
 const path = require("path");
@@ -50,5 +51,4 @@ const analyzer = require("polymer-analyzer");
 function analyzerToAst(analysis, config, rootDir) {
-    const exclude = config.exclude !== undefined ?
-        config.exclude.map((p) => new RegExp(p)) :
-        [/test\//, /demo\//];
+    const exclude = (config.exclude || ['test/**', 'demo/**'])
+        .map((p) => new minimatch.Minimatch(p));
     const addReferences = config.addReferences || {};
@@ -64,3 +64,3 @@ const removeReferencesResolved = new Set((config.removeReferences || []).map((r) => path.resolve(rootDir, r)));
     for (const jsDoc of analysis.getFeatures({ kind: 'js-document' })) {
-        if (exclude.some((r) => jsDoc.url.match(r) !== null)) {
+        if (exclude.some((r) => r.match(jsDoc.url))) {
             continue;
@@ -67,0 +67,0 @@ }

package.json

 {
   "name": "@polymer/gen-typescript-declarations",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Generate TypeScript type declarations for Polymer components.",
@@ -22,3 +22,4 @@ "main": "lib/gen-ts.js",
     "fs-extra": "^4.0.2",
-    "polymer-analyzer": "^3.0.0-pre.3"
+    "minimatch": "^3.0.4",
+    "polymer-analyzer": "^3.0.0-pre.5"
   },
@@ -25,0 +26,0 @@ "devDependencies": {

README.md

 # gen-typescript-declarations
 
 [![Build Status](https://travis-ci.org/Polymer/gen-typescript-declarations.svg?branch=master)](https://travis-ci.org/Polymer/gen-typescript-declarations)
+[![NPM version](https://img.shields.io/npm/v/@polymer/gen-typescript-declarations.svg)](https://www.npmjs.com/package/@polymer/gen-typescript-declarations)
 
-Generate TypeScript declarations from Polymer Analyzer output
+A library which generates TypeScript declarations for Polymer and custom
+elements.
+
+## How do I use the typings?
+
+### Polymer
+
+Typings for the Polymer 2.0 library will be included in future releases on
+Bower in the `types/` directory ([pending
+PR](https://github.com/Polymer/polymer/pull/4928)).
+
+Install Polymer normally from Bower, and add a [triple-slash
+directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html)
+anywhere in your TypeScript project for the typings you require. Each HTML
+import from Polymer has a corresponding typings file. For example, if you
+depend on `polymer-element.html`:
+
+```ts
+/// <reference path="./bower_components/polymer/types/polymer-element.d.ts" />`
+
+class MyElement extends Polymer.Element {
+  ...
+}
+```
+
+You may also be interested in the [Polymer
+decorators](https://github.com/Polymer/polymer-decorators).
+
+## How do I generate new typings?
+
+You can run this package from the command line with `gen-tsd`, or as a library
+with the `generateDeclarations` function.
+
+It is recommended to integrate typings generation as part of your build/release
+process:
+
+```sh
+$ npm install --save-dev @polymer/gen-typescript-declarations
+```
+
+Add a `gen-tsd` script to your `package.json`:
+
+```js
+{
+  ...
+  "scripts": {
+    "gen-tsd": "gen-tsd"
+  }
+}
+```
+
+If you're using Bower, ensure you run `npm run gen-tsd` to generate the latest
+typings and commit them to your repository before tagging each release.
+
+If you're using NPM, you can instead add this script to the NPM `prepack`
+script to generate and include typings in your NPM package every time you
+publish.
+
+## Config options
+
+By default the `gen-tsd` command will read a file called `gen-tsd.json` in
+your root directory. It has the following options:
+
+* **`exclude`**`: string[]`
+
+  Skip source files whose paths match any of these glob patterns. If
+  `undefined`, defaults to excluding directories ending in "test" or "demo".
+
+* **`removeReferences`**`: string[]`
+
+  Remove any triple-slash references to these files, specified as paths
+  relative to the analysis root directory.
+
+* **`addReferences`**`: {[filepath: string]: string[]}`
+
+  Additional files to insert as triple-slash reference statements. Given the
+  map `a: b[]`, a will get an additional reference statement for each file
+  path in b. All paths are relative to the analysis root directory.
+
+## Using as a module
+
+You can also use this package as a module:
+
+```js
+import {generateDeclarations} from 'gen-typescript-declarations';
+
+const config = {
+  "exclude": [
+    "test/",
+  ],
+  "removeReferences": [
+    "../shadycss/apply-shim.d.ts",
+  ],
+  "addReferences": {
+    "lib/utils/boot.d.ts": [
+      "extra-types.d.ts"
+    ]
+  }
+}
+
+// A map of d.ts file paths to file contents.
+const declarations = await generateDeclarations('/my/root/dir', config);
+```
+
+## FAQ
+
+### Why are some typings missing?
+This library is based on [Polymer
+Analyzer](https://github.com/Polymer/polymer-analyzer) which has limitations in
+its static analysis. For certain patterns, Analyzer relies on additional JSDoc
+annotations.
+
+### Can I augment the generated typings with hand-written ones?
+Yes, see the `addReferences` config option above.

src/closure-types.ts

@@ -140,3 +140,10 @@ /**
   } else if (isName(node)) {  // string, Object, MyClass, etc.
-    t = new ts.NameType(node.name);
+    if (node.name === 'Object') {
+      // Closure's `Object` type excludes primitives, so it is closest to
+      // TypeScript's `object`. (Technically this should be `object|Symbol`,
+      // but we will concede that technicality.)
+      t = new ts.NameType('object');
+    } else {
+      t = new ts.NameType(node.name);
+    }
   } else {
@@ -143,0 +150,0 @@ console.error('Unknown syntax.');

src/gen-ts.ts

@@ -12,2 +12,3 @@ /**
 
+import * as minimatch from 'minimatch';
 import * as path from 'path';
@@ -25,4 +26,4 @@ import * as analyzer from 'polymer-analyzer';
   /**
-   * Skip source files whose paths match this pattern. If undefined, defaults
-   * to excluding directories ending in "test" or "demo".
+   * Skip source files whose paths match any of these glob patterns. If
+   * undefined, defaults to excluding directories ending in "test" or "demo".
    */
@@ -70,5 +71,4 @@ exclude?: string[];
     ts.Document[] {
-  const exclude = config.exclude !== undefined ?
-      config.exclude.map((p) => new RegExp(p)) :
-      [/test\//, /demo\//];
+  const exclude = (config.exclude || ['test/**', 'demo/**'])
+                      .map((p) => new minimatch.Minimatch(p));
   const addReferences = config.addReferences || {};
@@ -86,3 +86,3 @@ const removeReferencesResolved = new Set(
   for (const jsDoc of analysis.getFeatures({kind: 'js-document'})) {
-    if (exclude.some((r) => jsDoc.url.match(r) !== null)) {
+    if (exclude.some((r) => r.match(jsDoc.url))) {
       continue;
@@ -89,0 +89,0 @@ }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

155048

increased by2.99%

Number of package files

23

increased by4.55%

Lines of code

3179

increased by0.47%

Number of lines in readme file

120

increased by1900%

Worsened metrics

Dependency count

9

increased by12.5%

Dependency changes

• + Addedminimatch@^3.0.4

• Updatedpolymer-analyzer@^3.0.0-pre.5