ISpecifiable

Construction

Given a specification, a specifiable class must provide a way to construct instances from it.

A specification object (or any of its "owned" contents) can be used destructively, partially or totally, to construct a specifiable object.

This supports the memory-effective, one-time cast-construction pattern, where the prototype of existing objects is changed, by using Object.setPrototypeOf.

This also means that, without further knowledge, a specification can only be used to create a single copy of an object.

"Newable" constructors

By convention, in classes that have a constructor function that should be used with the new operator — has a "newable" constructor — the specification object is the first, optional or required, constructor argument.

The following example illustrates this type of constructor function.

function Foo(spec) {
   this.bar = (spec && spec.bar) || "bar";
   this.qux = (spec && spec.qux) || "qux";
}

Foo.prototype.toSpec = function() {
    return {
        bar: this.bar,
        qux: this.qux
    };
};

// Create a Foo instance
var foo1 = new Foo({bar: "a", qux: "b"});

// Obtain a specification of foo1 var foo1Spec = foo1.toSpec(); // And use it to create a copy of it var foo2 = new Foo(foo1Spec); // Obtain another specification of foo1 foo1Spec = foo1.toSpec(); // And use it to create another copy of it var foo3 = new Foo(foo1Spec); 

"Initialization" constructors

In classes whose constructor is an initialization function that should not, however, be called using new (not "newable"), a plain object's prototype should be set using Object.setPrototypeOf and the constructor called on the "morphed" object, afterwards. In these cases, it is also conventional for the constructor function to provide a static to method that performs the class "conversion".

The following example illustrates this type of constructor function.

function Foo() {
   if(!this.bar) this.bar = "bar";
   if(!this.qux) this.qux = "qux";
}

Foo.prototype.toSpec = function() {
    return {
        bar: this.bar,
        qux: this.qux
    };
};

Foo.to = function(spec) {
    if(spec instanceof Foo) return spec;

    Object.setPrototypeOf(spec, Foo);
    Foo.call(spec);
    return spec;
};

// Convert to a Foo instance
var foo1 = Foo.to({bar: "a", qux: "b"});

Source: doc-js/pentaho/lang/ISpecifiable.jsdoc, line 17

Methods

Methods Details