Merge pull request #93 from bem-sdk/issue-92

Typings

Author: blond

README.md

@@ -26,6 +26,7 @@ Contents
 * [Install](#install)
 * [Usage](#usage)
 * [API](#api)
+* [TypeScript support](#typescript-support)
 * [Debuggability](#debuggability)
 
 Install
@@ -68,8 +69,8 @@ API
 * [toString()](#tostring)
 * [valueOf()](#valueof)
 * [toJSON()](#tojson)
-* [#isBemEntityName(entityName)](#isbementitynameentityname)
-* [#create(object)](#createobject)
+* [static isBemEntityName(entityName)](#static-isbementitynameentityname)
+* [static create(obj)](#static-createobj)
 
 ### constructor({ block, elem, mod })
 
@@ -256,13 +257,13 @@ name.valueOf();
 
 Returns object for `JSON.stringify()` purposes.
 
-### #isBemEntityName(entityName)
+### static isBemEntityName(entityName)
 
 Determines whether specified entity is an instance of BemEntityName.
 
 Parameter    | Type            | Description
 -------------|-----------------|-----------------------
-`entityName` | `BemEntityName` | The entity to check.
+`entityName` | `*`             | The entity to check.
 
 ```js
 const BemEntityName = require('@bem/entity-name');
@@ -273,7 +274,7 @@ BemEntityName.isBemEntityName(entityName); // true
 BemEntityName.isBemEntityName({ block: 'button' }); // false
 ```
 
-### #create(object)
+### static create(object)
 
 Creates BemEntityName instance by any object representation or a string.
 
@@ -311,6 +312,13 @@ BemEntityName.create({ block: 'my-button', mod: 'focused' });
 // ➜ BemEntityName { block: 'my-button', mod: { name: 'focused', val: true } }
 ```
 
+TypeScript support
+------------------
+
+The package includes [typings](./index.d.ts) for TypeScript. You have to set up transpilation yourself. When you set `module` to `commonjs` in your `tsconfig.json` file, TypeScript will automatically find the type definitions for `@bem/entity-name`.
+
+The interfaces are provided in global namespace `BemSDK.EntityName`. It is necessary to use interfaces in JsDoc.
+
 Debuggability
 -------------
 

globals.d.ts

@@ -0,0 +1,109 @@
+declare namespace BemSDK {
+    export namespace EntityName {
+        /**
+         * Types of BEM entities.
+         */
+        export type TYPE = 'block' | 'blockMod' | 'elem' | 'elemMod';
+
+        /**
+         * Abstract object to represent entity name
+         */
+        interface AbstractEntityRepresentation {
+            /**
+             * The block name of entity.
+             */
+            block: string;
+            /**
+             * The element name of entity.
+             */
+            elem?: string;
+            mod?: any;
+        }
+
+        /**
+         * Object to represent modifier of entity name.
+         */
+        export interface ModifierRepresentation {
+            /**
+             * The modifier name of entity.
+             */
+            name: string;
+            /**
+             * The modifier value of entity.
+             */
+            val: string | true;
+        }
+
+        /**
+         * Strict object to represent entity name.
+         */
+        export interface StrictRepresentation extends AbstractEntityRepresentation {
+            /**
+             * The modifier of entity.
+             */
+            mod?: ModifierRepresentation;
+        }
+
+        /**
+         * Object to create representation of entity name.
+         */
+        export interface Options extends AbstractEntityRepresentation {
+            /**
+             * The modifier of entity.
+             */
+            mod?: string | {
+                /**
+                 * The modifier name of entity.
+                 */
+                name: string;
+                /**
+                 * The modifier value of entity.
+                 */
+                val?: string | boolean;
+            };
+            /**
+             * The modifier name of entity. Used if `mod.name` wasn't specified.
+             * @deprecated use `mod.name` instead.
+             */
+            modName?: string;
+            /**
+             * The modifier value of entity. Used if neither `mod.val` nor `val` were not specified.
+             * @deprecated use `mod.name` instead.
+             */
+            modVal?: string;
+        }
+
+        /**
+         * Non-strict object to represent entity name.
+         *
+         * Contains old field: `val`, `modName` and `modVal.
+         */
+        export interface NonStrictRepresentation extends AbstractEntityRepresentation {
+            /**
+             * The modifier of entity.
+             */
+            mod?: string | {
+                /**
+                 * The modifier name of entity.
+                 */
+                name: string;
+                /**
+                 * The modifier value of entity.
+                 */
+                val?: string | boolean;
+            };
+            /**
+             * The modifier value of entity. Used if neither `mod.val` were not specified.
+             */
+            val?: string;
+            /**
+             * The modifier name of entity. Used if `mod.name` wasn't specified.
+             */
+            modName?: string;
+            /**
+             * The modifier value of entity. Used if neither `mod.val` nor `val` were not specified.
+             */
+            modVal?: string;
+        }
+    }
+}

index.d.ts

@@ -0,0 +1,25 @@
+import './globals.d';
+
+declare class BemEntityName {
+    constructor(obj: BemSDK.EntityName.Options);
+
+    readonly block: string;
+    readonly elem: string | undefined;
+    readonly mod: BemSDK.EntityName.ModifierRepresentation | undefined;
+    readonly modName: string | undefined;
+    readonly modVal: string | true | undefined;
+    readonly id: string;
+    readonly type: BemSDK.EntityName.TYPE;
+
+    isSimpleMod(): boolean | null;
+    toString(): string;
+    valueOf(): BemSDK.EntityName.StrictRepresentation;
+    inspect(depth: number, options: object): string;
+    toJSON(): BemSDK.EntityName.StrictRepresentation;
+    isEqual(entityName: BemEntityName): boolean;
+
+    static isBemEntityName(entityName: any): boolean;
+    static create(obj: BemSDK.EntityName.NonStrictRepresentation | string): BemEntityName;
+}
+
+export = BemEntityName;

index.js

@@ -9,7 +9,7 @@ const stringifyEntity = require('@bem/naming').stringify;
  * Enum for types of BEM entities.
  *
  * @readonly
- * @enum {String}
+ * @enum {string}
  */
 const TYPES = {
     BLOCK:     'block',
@@ -33,17 +33,9 @@ class EntityTypeError extends ExtendableError {
     }
 }
 
-module.exports = class BemEntityName {
+class BemEntityName {
     /**
-     * @param {object} obj — representation of entity name.
-     * @param {string} obj.block  — the block name of entity.
-     * @param {string} [obj.elem] — the element name of entity.
-     * @param {object} [obj.mod] — the modifier of entity.
-     * @param {string} obj.mod.name — the modifier name of entity.
-     * @param {string} [obj.mod.val] — the modifier value of entity.
-     * @param {string} [obj.modName] — the modifier name of entity. Used if `mod.name` wasn't specified.
-     * @param {string} [obj.modVal] — the modifier value of entity.
-     *   Used if neither `mod.val` nor `val` were not specified.
+     * @param {BemSDK.EntityName.Options} obj — representation of entity name.
      */
     constructor(obj) {
         if (!obj.block) {
@@ -94,7 +86,7 @@ module.exports = class BemEntityName {
      *
      * name.elem; // text
      *
-     * @returns {string|undefined} - name of entity element.
+     * @returns {?string} - name of entity element.
      */
     get elem() { return this._data.elem; }
 
@@ -112,7 +104,7 @@ module.exports = class BemEntityName {
      * modName.mod;   // { name: 'disabled', val: true }
      * blockName.mod; // undefined
      *
-     * @returns {{mod: string, val: (string|true)}|undefined} - entity modifier.
+     * @returns {?BemSDK.EntityName.ModifierRepresentation} - entity modifier.
      */
     get mod() { return this._data.mod; }
 
@@ -121,7 +113,7 @@ module.exports = class BemEntityName {
      *
      * If entity is not modifier then returns `undefined`.
      *
-     * @returns {string|undefined} - entity modifier name.
+     * @returns {?string} - entity modifier name.
      * @deprecated - use `mod.name` instead.
      */
     get modName() { return this.mod && this.mod.name; }
@@ -131,7 +123,7 @@ module.exports = class BemEntityName {
      *
      * If entity is not modifier then returns `undefined`.
      *
-     * @returns {string|undefined} - entity modifier name.
+     * @returns {?(string|true)} - entity modifier name.
      * @deprecated - use `mod.val` instead.
      */
     get modVal() { return this.mod && this.mod.val; }
@@ -211,7 +203,7 @@ module.exports = class BemEntityName {
      *
      * name.isSimpleMod(); // null
      *
-     * @returns {boolean|null}
+     * @returns {(boolean|null)}
      */
     isSimpleMod() {
         return this.mod ? this.mod.val === true : null;
@@ -250,7 +242,7 @@ module.exports = class BemEntityName {
      *
      * // ➜ { block: 'button', mod: { name: 'focused', value: true } }
      *
-     * @returns {{block: string, elem: (string|undefined), mod: ({name: string, val: (string|true)}|undefined)}}
+     * @returns {BemSDK.EntityName.StrictRepresentation}
      */
     valueOf() { return this._data; }
 
@@ -284,8 +276,7 @@ module.exports = class BemEntityName {
     /**
      * Return raw data for `JSON.stringify()`.
      *
-     * @returns {{block: string, elem: (string|undefined),
-     *   mod: ({name: string, val: (string|true|undefined)}|undefined)}}
+     * @returns {BemSDK.EntityName.StrictRepresentation}
      */
     toJSON() {
         return this._data;
@@ -294,9 +285,6 @@ module.exports = class BemEntityName {
     /**
      * Determines whether specified entity is the deepEqual entity.
      *
-     * @param {BemEntityName} entityName - the entity to compare.
-     *
-     * @returns {boolean} - A Boolean indicating whether or not specified entity is the deepEqual entity.
      * @example
      * const BemEntityName = require('@bem/entity-name');
      *
@@ -305,6 +293,9 @@ module.exports = class BemEntityName {
      *
      * inputName.isEqual(buttonName); // false
      * buttonName.isEqual(buttonName); // true
+     *
+     * @param {BemEntityName} entityName - the entity to compare.
+     * @returns {boolean} - A Boolean indicating whether or not specified entity is the deepEqual entity.
      */
     isEqual(entityName) {
         return entityName && (this.id === entityName.id);
@@ -313,16 +304,16 @@ module.exports = class BemEntityName {
     /**
      * Determines whether specified entity is instance of BemEntityName.
      *
-     * @param {BemEntityName} entityName - the entity to check.
-     *
-     * @returns {boolean} A Boolean indicating whether or not specified entity is instance of BemEntityName.
      * @example
      * const BemEntityName = require('@bem/entity-name');
      *
      * const entityName = new BemEntityName({ block: 'input' });
      *
      * BemEntityName.isBemEntityName(entityName); // true
      * BemEntityName.isBemEntityName({}); // false
+     *
+     * @param {*} entityName - the entity to check.
+     * @returns {boolean} A Boolean indicating whether or not specified entity is instance of BemEntityName.
      */
     static isBemEntityName(entityName) {
         return entityName && entityName.__isBemEntityName__;
@@ -331,24 +322,15 @@ module.exports = class BemEntityName {
     /**
      * Creates BemEntityName instance by any object representation.
      *
-     * @param {object|string} obj — representation of entity name.
-     * @param {string} obj.block  — the block name of entity.
-     * @param {string} [obj.elem] — the element name of entity.
-     * @param {object|string} [obj.mod]  — the modifier of entity.
-     * @param {string} [obj.val] - the modifier value of entity. Used if `obj.mod` is a string.
-     * @param {string} obj.mod.name — the modifier name of entity.
-     * @param {string} [obj.mod.val]  — the modifier value of entity.
-     * @param {string} [obj.modName] — the modifier name of entity. Used if `obj.mod.name` wasn't specified.
-     * @param {string} [obj.modVal]  — the modifier value of entity.
-     *   Used if neither `obj.mod.val` nor `obj.val` were not specified.
-     *
-     * @returns {BemEntityName} An object representing entity name.
      * @example
      * const BemEntityName = require('@bem/entity-name');
      *
      * BemEntityName.create({ block: 'my-button', mod: 'theme', val: 'red' });
      * BemEntityName.create({ block: 'my-button', modName: 'theme', modVal: 'red' });
      * // → BemEntityName { block: 'my-button', mod: { name: 'theme', val: 'red' } }
+     *
+     * @param {(BemSDK.EntityName.NonStrictRepresentation|string)} obj — representation of entity name.
+     * @returns {BemEntityName} An object representing entity name.
      */
     static create(obj) {
         if (BemEntityName.isBemEntityName(obj)) {
@@ -378,4 +360,11 @@ module.exports = class BemEntityName {
 
         return new BemEntityName(data);
     }
-};
+}
+
+module.exports = BemEntityName;
+
+// TypeScript imports the `default` property for
+// an ES2015 default import (`import BemEntityName from '@bem/entity-name'`)
+// See: https://github.com/Microsoft/TypeScript/issues/2242#issuecomment-83694181
+module.exports.default = BemEntityName;

jsconfig.json

@@ -0,0 +1,10 @@
+{
+    "compilerOptions": {
+        "target": "ES6",
+        "module": "commonjs"
+    },
+    "files": [
+        "index.js",
+        "index.d.ts"
+    ]
+}