@thefoxjob/js-facade

Js Facade

Static interface to concrete classes via an IoC Service Container.

Before you continue reading, you should know that this package is heavily inspired by Taylor Otwell's Facades in Laravel. Please go read the documentation, to gain a better understanding of what facades are and how they are intended to work.

Contents

• How to install
• Quick start
  • Set the IoC instance
  • Create a facade
  • Using your facade
• Contribution
• Acknowledgement
• Versioning
• License

How to install

npm install @aedart/js-facade

Quick start

Set the IoC instance

The Facade requires an IoC Service Container instance, so that it can resolve the facade's accessor (a string identifier) and obtain a concrete class instance.

There is no check of kind of IoC implementation you should use. But, your IoC is required to have a make method;

Required Make method

/**
 * Resolve the registered abstract from the container
 * 
 * @param {string} abstract
 * @param {Array.<*>} [parameters]
 * 
 * @return {Object}
 * 
 * @throw {Error}
 */
function make(abstract, parameters = []){
    // ... not shown ... //
};

Whenever the make method is invoked, the facade assumes that the IoC is able to return a concrete instance or fail.

As long as your desired IoC has such a method, you can use this facade. Alternatively, you can use my @aedart/js-ioc package.

Setting IoC instance on Facade

import Facade from '@aedart/js-facade';
import IoC from '@aedart/js-ioc';

// Somewhere in you bootstrap / setup logic, set the IoC on the Facade
Facade.ioc = IoC;

Create a facade

Given that you have a concrete class, and that you somehow have registered (bound) an instance to it in your IoC;

A simple Box class

'use strict';

class Box {
    set width(value){
        // ... not shown .../
    }
    
    get width(){
        // ... not shown .../
    }

    set height(value){
        // ... not shown .../
    }
    
    get height(){
        // ... not shown .../
    }
}

export default Box;

A facade for the Box class

'use strict';

import Facade from '@aedart/js-facade';

class BoxFacade extends Facade {
    constructor(){
        // Accessor - MUST match the identifier you used to
        // register your Box with, in your IoC.
        super('my-box-identifier');
    }
}

// You MUST export a initialised instance of this facade.
export default new BoxFacade();

Behind the scene, a Proxy is used by the facade to trap method calls. Those traps ensure to invoke the correct methods on the concrete class, via the IoC Service Container.

Using your facade

Whenever you need to use your concrete class, via a facade, you simply just import it and invoke the methods or properties that you require from it.

Using BoxFacade

'use strict';

// Import you facade from where you stored it...
import BoxFacade from './src/Facades/BoxFacade';

// ... somewhere in your application or inside a component ... //

BoxFacade.width = 25;
BoxFacade.height = 50;

console.log(BoxFacade.width, BoxFacade.height); // Output 25, 50 

Contribution

Have you found a defect ( bug or design flaw ), or do you wish improvements? In the following sections, you might find some useful information on how you can help this project. In any case, I thank you for taking the time to help me improve this project's deliverables and overall quality.

Bug Report

If you are convinced that you have found a bug, then at the very least you should create a new issue. In that given issue, you should as a minimum describe the following;

• Where is the defect located
• A good, short and precise description of the defect (Why is it a defect)
• How to replicate the defect
• (A possible solution for how to resolve the defect)

When time permits it, I will review your issue and take action upon it.

Fork, code and send pull-request

A good and well written bug report can help me a lot. Nevertheless, if you can or wish to resolve the defect by yourself, here is how you can do so;

• Fork this project
• Create a new local development branch for the given defect-fix
• Write your code / changes
• Create executable test-cases (prove that your changes are solid!)
• Commit and push your changes to your fork-repository
• Send a pull-request with your changes
• Drink a Beer - you earned it :)

As soon as I receive the pull-request (and have time for it), I will review your changes and merge them into this project. If not, I will inform you why I choose not to.

Acknowledgement

• Taylor Otwell, for his Facade implementation

Versioning

This package follows Semantic Versioning 2.0.0

License

BSD-3-Clause, Read the LICENSE file included in this package