Resolve Deps

[blond]

API

The resolve method to supplement the declaration missing entities.

Important: It takes into account the order dependencies of BEM-entities.

resolve(decl, deps) -> decl

Object[] decl — list of BEM-entities. Each item is object. See, bem-naming. Object[] deps — list of dependencies between BEM-entities.

Example:

var deps = require('bem-deps'),
    decl = [
        { block: 'A' },
        { block: 'B' }
    ],
    myDeps = [
        { 
            entity: { block: 'A' },
            dependOn: [
                {
                    entity: { block: 'B' },
                    order: 'dependenceBeforeDependants'
                },
                {
                    entity: { block: 'C' }
                }
            ]
        }
    ];

var res = deps.resolve(decl, myDeps);

console.log(res); 
/*
{ 
    entities: [{ block: 'B' }, { block: 'A' }, { block: 'C' }],
    dependOn: []
}
*/

Terms

• Common dependencies - dependencies where one entity depends on another entity, without taking in account specific techs
• Resolve common dependencies - resolve dependencies without specifying any tech
• Unordered dependencies - dependencies which ordering is not specified explicitly. (i.e. order param is not set)
• Ordered dependencies - dependencies which ordering specified explicitly (i.e. order param is being set)

  Deps Format

Each item of deps list is Object.

Object entity — BEM-entity that is dependent on other Object[] dependOn — list of BEM-entities of which depends on entity

Example:

{
    entity: { block: 'A' },
    dependOn: [
        { entity: { block: 'B' } },
        { entity: { block: 'C' } }
    ]
}

This means that the block A depends on blocks B and C.

Techs

Constraints can be not only between the BEM-entities but also between technologies.

resolve(decl, deps, { tech: 'css' })

Example:

Tech -> Block

{
    entity: { block: 'A' },
    tech: 'css',
    dependOn: [
        { entity: { block: 'B' } }
    ]
}

This means that the css tech of block A depends on all techs of block B.

Example:

Tech -> Tech

{
    entity: { block: 'A' },
    tech: 'js',
    dependOn: [
        { 
            entity: { block: 'B' },
            tech: 'js'
        }
    ]
}

This means that the js tech of block A depends on js tech of block B.

Deps By Techs

For cases when the technology is dependent on other technology in result will be add dependOn field. Each item of dependOn is object with tech and entities filed.

Example:

var myDeps = {
    entity: { block: 'A' },
    tech: 'js',
    dependOn: [
        { 
            entity: [{ block: 'B' }],
            tech: 'bemhtml'
        }
    ]
};

var res = resolve(decl, deps, { tech: 'js' });

console.log(res);

/*
{
    entities: [{ block: 'A' }],
    dependOn: [
        {
            tech: bemhtml,
            entities: [{ block: 'B' }]
        }
    ]
}
*/

Order

Depending provides information about the order:

• dependenceBeforeDependants — BEM-entity may require that the other BEM-entity will be before it.
• false — BEM-entity may expect that the other BEM-entity will be before or after it.

Example:

{
    entity: { block: 'A' },
    tech: 'js',
    dependOn: [
        { 
            entity: { block: 'B' },
            order: 'dependenceBeforeDependants'
        }
    ]
}

This means that the block A depends on of block B and require that B will be before A.

Priority

Rule 1: Try to keep the order of declaration.

Example:

Declaration: A, B, C Dependency graph: B <- E (with order: dependenceBeforeDependants) Expected result: A, E, B, C

Rule 2: Try to keep the natural order for BEM-entities with same block scope (block and its mods, elems and their mods):

• block before others BEM-entities
• elem after block
• block mod after block
• elem mod after elem
• key-val mod after boolean mod

[arikon]

/*
{
    entities: [{ block: 'A' }],
    dependOn: [
        {
            tech: bemhtml,
            entities: [{ block: 'B' }]
        }
    ]
}
*/

I don't like that in the resulting deps info about order of tech-dependencies is lost, and these deps are grouped by techs.

Proposing another resulting format (it could be optional):

/*
{
    entities: [{ block: 'A' }, { block: 'B', tech: 'bemhtml' }]
}
*/

[blond]

I don't like that in the resulting deps info about order of tech-dependencies is lost, and these deps are grouped by techs.

No, this information is not lost. It is important to understand why we need result.

If we need to build JavaScript then dependencies with tech: js will get in entities and order will not be lost.

var myDeps = {
    entity: { block: 'A' },
    tech: 'js',
    dependOn: [
        { 
            entity: [{ block: 'B' }],
            order: 'dependenceBeforeDependants',
            tech: 'js'
        }
    ]
};

var res = resolve(decl, deps, { tech: 'js' });

console.log(res);

/*
{
    entities: [{ block: 'B' }, { block: 'A' }],
    dependOn: []
}
*/

If we need to build JavaScript with BEMHTML then dependencies with tech: 'bemhtml' will get in dependOn.

var myDeps = [
    {
        entity: { block: 'A' },
        tech: 'js',
        dependOn: [
            { 
                entity: [{ block: 'B' }],
                tech: 'bemhtml'
            },
            { 
                entity: [{ block: 'C' }],
                tech: 'bemhtml'
            }
        ]
    },
    {
        entity: { block: 'C' },
        tech: 'bemhtml',
        dependOn: [
            { 
                entity: [{ block: 'D' }],
                tech: 'bemhtml'
            }
        ]
    },
];

var res = resolve(decl, deps, { tech: 'js' });

console.log(res);

/*
{
    entities: [{ block: 'A' }],
    dependOn: [
        {
            tech: bemhtml,
            entities: [{ block: 'B' }, { block: 'C' }]
        }
    ]
}
*/

res.entities // we can concat JS files

var bemhtmlForJsDecl = res.dependOn[0].entities;
var bemhtmlForJsRes = resolve(decl, deps, { tech: 'bemhtml' });

console.log(bemhtmlForJsRes);

/*
{
    entities: [{ block: 'B' }, { block: 'C' }, { block: 'D' }],
    dependOn: []
}
*/

bemhtmlForJsRes.entities // we can compile BEMHTML files

[arikon]

What if I need to mix files of different techs in a single flow?

[blond]

@arikon You're talking about different technologies or different extensions?

Can you give real-life examples?

[arikon]

@blond Different techs and exts

Can you give real-life examples?

No =(

[blond]

Different techs and exts

You can resolve different exts at the time of parsing.

For different techs I think that everything should remain as it is. Real-life example — js+bemhtml.

[blond]

Fixed in #59