Merge pull request #72 from bem-sdk/qfox.feat-create

Create method

Author: blond

README.md

@@ -75,7 +75,7 @@ new BemEntityName({
 });
 ```
 
-To describe the simple modifier field `mod.val` must be specified as `true`.
+To describe the simple modifier, field `mod.val` must be specified as `true`.
 
 **Example:**
 
@@ -103,10 +103,11 @@ API
 * [id](#id)
 * [type](#type)
 * [isEqual(entityName)](#isequalentityname)
-* [isBemEntityName(entityName)](#isbementitynameentityname)
 * [toString()](#tostring)
 * [valueOf()](#valueof)
 * [toJSON()](#tojson)
+* [#isBemEntityName(entityName)](#isbementitynameentityname)
+* [#create(object)](#createobject)
 
 ### constructor({ block, elem, mod })
 
@@ -207,23 +208,6 @@ inputName.isEqual(buttonName);  // false
 buttonName.isEqual(buttonName); // true
 ```
 
-### isBemEntityName(entityName)
-
-Determines whether specified entity is instance of BemEntityName.
-
-Parameter    | Type            | Description
--------------|-----------------|-----------------------
-`entityName` | `BemEntityName` | The entity to check.
-
-```js
-const BemEntityName = require('@bem/entity-name');
-
-const entityName = new BemEntityName({ block: 'input' });
-
-BemEntityName.isBemEntityName(entityName); // true
-BemEntityName.isBemEntityName({}); // false
-```
-
 ### toString()
 
 Returns string representing the entity name.
@@ -255,6 +239,57 @@ name.valueOf();
 
 Returns object for `JSON.stringify()` purposes.
 
+### #isBemEntityName(entityName)
+
+Determines whether specified entity is an instance of BemEntityName.
+
+Parameter    | Type            | Description
+-------------|-----------------|-----------------------
+`entityName` | `BemEntityName` | The entity to check.
+
+```js
+const BemEntityName = require('@bem/entity-name');
+
+const entityName = new BemEntityName({ block: 'input' });
+
+BemEntityName.isBemEntityName(entityName); // true
+BemEntityName.isBemEntityName({ block: 'button' }); // false
+```
+
+### #create(object)
+
+Creates BemEntityName instance by any object representation.
+
+Helper for sugar-free simplicity.
+
+Parameter    | Type               | Description
+-------------|--------------------|--------------------------
+`object`     | `object`           | Representation of entity name.
+
+Passed Object could have the common field names for entities:
+
+Object field | Type     | Description
+-------------|----------|------------------------------
+`block`      | `string` | The block name of entity.
+`elem`       | `string` | The element name of entity.
+`mod`        | `string`, `object` | The modifier of entity.<br><br> If specified value is `string` then it will be equivalent to `{ name: string, val: true }`.
+`val`        | `string` | The modifier value of entity. Used if `mod` is a string.
+`mod.name`   | `string` | The modifier name of entity.
+`mod.val`    | `*`      | The modifier value of entity.
+`modName`    | `string` | The modifier name of entity. Used if `mod.name` wasn't specified.
+`modVal`     | `*`      | The modifier value of entity. Used if neither `mod.val` nor `val` were not specified.
+
+```js
+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' } }
+
+BemEntityName.create({ block: 'my-button', mod: 'focused' });
+// ➜ BemEntityName { block: 'my-button', mod: { name: 'focused', val: true } }
+```
+
 Debuggability
 -------------
 

index.js

@@ -285,4 +285,52 @@ module.exports = class BemEntityName {
     static isBemEntityName(entityName) {
         return entityName && entityName.__isBemEntityName__;
     }
+
+    /**
+     * Creates BemEntityName instance by 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.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('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');
+});

test/to-string.test.js

@@ -26,15 +26,15 @@ test('should use `naming.stringify()` for elem', t => {
 });
 
 test('should use `naming.stringify()` for block modifier', t => {
-    const entity = new BemEntityName({ block: 'block', modName: 'mod', modVal: 'val' });
+    const entity = new BemEntityName({ block: 'block', mod: { name: 'mod', val: 'val' } });
 
     entity.toString();
 
     t.truthy(spy.calledWith({ block: 'block', modName: 'mod', modVal: 'val' }));
 });
 
 test('should use naming.stringify() for element modifier', t => {
-    const entity = new BemEntityName({ block: 'block', elem: 'elem', modName: 'mod', modVal: 'val' });
+    const entity = new BemEntityName({ block: 'block', elem: 'elem', mod: { name: 'mod', val: 'val' } });
 
     entity.toString();
 

test/type.test.js

@@ -9,7 +9,7 @@ test('should determine block', t => {
 });
 
 test('should determine modifier of block', t => {
-    const entityName = new BemEntityName({ block: 'block', mod: 'mod' });
+    const entityName = new BemEntityName({ block: 'block', mod: { name: 'mod' } });
 
     t.is(entityName.type, 'blockMod');
 });
@@ -21,7 +21,7 @@ test('should determine elem', t => {
 });
 
 test('should determine modifier of element', t => {
-    const entityName = new BemEntityName({ block: 'block', elem: 'elem', mod: 'mod' });
+    const entityName = new BemEntityName({ block: 'block', elem: 'elem', mod: { name: 'mod' } });
 
     t.is(entityName.type, 'elemMod');
 });