BREAKING: simplify construct and add create method

Author: qfox

index.js

@@ -1,8 +1,10 @@
 'use strict';
 
+const assert = require('assert');
 const util = require('util');
 
 const stringifyEntity = require('bem-naming').stringify;
+const parseEntity = require('bem-naming').parse;
 
 /**
  * Enum for types of BEM entities.
@@ -23,30 +25,17 @@ module.exports = class BemEntityName {
      * @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.name — the modifier name of entity.
      * @param {string} [obj.mod.val]  — the modifier value of entity.
      */
     constructor(obj) {
-        if (!obj.block) {
-             throw new Error('This is not valid BEM entity: the field `block` is undefined.');
-        }
+        assert(obj.block, 'This is not valid BEM entity: the field `block` is undefined.');
+        assert(!obj.mod || obj.mod.name, 'This is not valid BEM entity: the field `mod.name` is undefined.');
 
         const data = this._data = { block: obj.block };
 
         obj.elem && (data.elem = obj.elem);
-
-        const modObj = obj.mod;
-        const modName = (typeof modObj === 'string' ? modObj : modObj && modObj.name) || obj.modName;
-        const hasModVal = modObj && modObj.hasOwnProperty('val') || obj.hasOwnProperty('modVal');
-
-        if (modName) {
-            data.mod = {
-                name: modName,
-                val: hasModVal ? modObj && modObj.val || obj.modVal : true
-            };
-        } else if (modObj || hasModVal) {
-            throw new Error('This is not valid BEM entity: the field `mod.name` is undefined.');
-        }
+        obj.mod && (data.mod = { name: obj.mod.name, val: obj.mod.val || true });
 
         this.__isBemEntityName__ = true;
     }
@@ -285,4 +274,50 @@ module.exports = class BemEntityName {
     static isBemEntityName(entityName) {
         return entityName && entityName.__isBemEntityName__;
     }
+
+    /**
+     * Creates BemEntityName instance by the any object representation.
+     *
+     * @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|string} [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.
+     * @param {string} [obj.modVal]  — the modifier value of entity.
+     *
+     * @returns {BemEntityName} An object representing entity name.
+     * @example
+     * const BemEntityName = require('@bem/entity-name');
+     *
+     * BemEntityName.create('my-button_theme_red');
+     * 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' } }
+     */
+    static create(obj) {
+        if (BemEntityName.isBemEntityName(obj)) {
+            return obj;
+        }
+
+        const data = { block: obj.block };
+        const mod = obj.mod;
+
+        obj.elem && (data.elem = obj.elem);
+
+        if (mod || obj.modName) {
+            const isString = typeof mod === 'string';
+            const modName = (isString ? mod : mod && mod.name) || obj.modName;
+            const modObj = !isString && mod || obj;
+            const hasModVal = modObj.hasOwnProperty('val') || obj.hasOwnProperty('modVal');
+
+            data.mod = {
+                name: modName,
+                val: hasModVal ? modObj.val || obj.modVal : true
+            };
+        }
+
+        return new BemEntityName(data);
+    }
 };

test/valid.test.js renamed to test/construct.test.js

@@ -2,6 +2,30 @@ const test = require('ava');
 
 const BemEntityName = require('../index');
 
+test('should create object for block', t => {
+    const data = { block: 'b' };
+
+    t.deepEqual((new BemEntityName(data)).valueOf(), data);
+});
+
+test('should create object for block and elem', t => {
+    const data = { block: 'b', elem: 'e' };
+
+    t.deepEqual((new BemEntityName(data)).valueOf(), data);
+});
+
+test('should create object for block and mod', t => {
+    const data = { block: 'b', mod: { name: 'm', val: 'v' } };
+
+    t.deepEqual((new BemEntityName(data)).valueOf(), data);
+});
+
+test('should create object and normalize boolean modifier', t => {
+    const entity = new BemEntityName({ block: 'block', mod: { name: 'mod' } });
+
+    t.deepEqual(entity.valueOf(), { block: 'block', mod: { name: 'mod', val: true } });
+});
+
 test('should throw error for if entity object is not valid', t => {
     t.throws(
         () => new BemEntityName({ elem: 'elem' }),
@@ -22,10 +46,3 @@ test('should throw error for if mod name is undefined', t => {
         'This is not valid BEM entity: the field `mod.name` is undefined.'
     );
 });
-
-test('should throw error for if modName is undefined', t => {
-    t.throws(
-        () => new BemEntityName({ block: 'block', modVal: 'val' }),
-        'This is not valid BEM entity: the field `mod.name` is undefined.'
-    );
-});

test/create.test.js

@@ -0,0 +1,82 @@
+const test = require('ava');
+
+const BemEntityName = require('../index');
+
+test('should return object as is if it`s a BemEntityName', t => {
+    const entity = new BemEntityName({ block: 'b' });
+
+    t.is(BemEntityName.create(entity), entity);
+});
+
+test('should create BemEntityName for block from obj', t => {
+    const entity = BemEntityName.create({ block: 'b' });
+
+    t.pass(entity instanceof BemEntityName, 'Should be an instance of BemEntityName');
+    t.deepEqual(entity.valueOf(), { block: 'b' }, 'Should contain a name for same entity');
+});
+
+test('should create entity for elem from obj', t => {
+    const entity = BemEntityName.create({ block: 'b', elem: 'e' });
+
+    t.deepEqual(entity.valueOf(), { block: 'b', elem: 'e' });
+});
+
+test('should create entity from obj with deps mods without value', t => {
+    const entity = BemEntityName.create({ block: 'b', mod: 'm' });
+
+    t.deepEqual(entity.valueOf(), { block: 'b', mod: { name: 'm', val: true } });
+});
+
+test('should create entity from obj with deps mods', t => {
+    const entity = BemEntityName.create({ block: 'b', mod: 'm', val: 'v' });
+
+    t.deepEqual(entity.valueOf(), { block: 'b', mod: { name: 'm', val: 'v' } });
+});
+
+test('should normalize boolean modifier', t => {
+    const entity = BemEntityName.create({ block: 'block', mod: { name: 'mod' } });
+
+    t.true(entity.mod.val);
+});
+
+test('should normalize short entry for boolean modifier', t => {
+    const entity = BemEntityName.create({ block: 'block', mod: 'mod' });
+
+    t.true(entity.mod.val);
+});
+
+test('should support `modName` and `modVal` fields', t => {
+    const entity = BemEntityName.create({ block: 'block', modName: 'mod', modVal: 'val' });
+
+    t.deepEqual(entity.mod, { name: 'mod', val: 'val' });
+});
+
+test('should support `modName` field only', t => {
+    const entity = BemEntityName.create({ block: 'block', modName: 'mod' });
+
+    t.deepEqual(entity.mod, { name: 'mod', val: true });
+});
+
+test('should use `mod.name` field instead of `modName`', t => {
+    const entity = BemEntityName.create({ block: 'block', mod: { name: 'mod1' }, modName: 'mod2' });
+
+    t.is(entity.mod.name, 'mod1');
+});
+
+test('should use `mod.val` field instead of `modVal`', t => {
+    const entity = BemEntityName.create({ block: 'block', mod: { name: 'm', val: 'v1' }, modVal: 'v2' });
+
+    t.is(entity.mod.val, 'v1');
+});
+
+test('should use `mod.name` and `mod.val` instead of `val`', t => {
+    const entity = BemEntityName.create({ block: 'block', mod: { name: 'm', val: 'v1' }, val: 'v3'});
+
+    t.is(entity.mod.val, 'v1');
+});
+
+test('should use `mod.name` and `mod.val` instead of `modVal` and `val`', t => {
+    const entity = BemEntityName.create({ block: 'block', mod: { name: 'm', val: 'v1' }, modVal: 'v2', val: 'v3'});
+
+    t.is(entity.mod.val, 'v1');
+});