ProjectLines

Feature

A class property getter for the configuration properties of the class, which can be overridden by configurations passed at construction time.

Unlike a normal static property, this property is only ever used for the class that defines it (as in, hasOwnProperty). It is retrieved for all classes in a class hierarchy, to gather their configs individually and then combine them with those of derived classes.

For example, a Label might declare a text config like so:

 class Label extends Base {
     static configurable = {
         text : null
     };
 }

The text config is automatically inherited by classes derived from Label. By implementing get configurable(), derived classes can change the default value of inherited configs, or define new configs, or both.

When a config property is declared in this way, the class author can also implement either of two special methods that will be called when the config property is assigned a new value:

• changeText()
• updateText()

In the example above, the Label class could implement a changeText() method, an updateText() method, or both. The generated property setter ensures these methods will be called when the text property is assigned.

The generated setter (for text in this example) performs the following steps:

• If the class defines a changeText() method, call it passing the new value and the current value: changeText(newText, oldText).
  Then:
  • If changeText() exits without returning a value (i.e., undefined), exit and do nothing further. The assumption is that the changer method has done all that is required.
  • Otherwise, the return value of changeText() replaces the incoming value passed to the setter.
• If the new value (or the value returned by changeText()) is !== to the current value:
  • Update the stored config value in this._text.
  • If the class defines an updateText() method, call it passing the new value and the previous value. updateText(newText, oldText)

Resolving a value from an owner

By specifying a value starting with 'up.' for a config, the config system will resolve that value by examining the ownership hierarchy. It will walk up the hierarchy looking for a property matching the name (or dot separated path) after 'up.'. If one is found, the value will be read and used as the initial value.

class Parent extends Base {
    static get configurable() {
        return [
          'importantValue'
        ]
    }
}

class Child extends Base {
    static get configurable() {
        return [
          'value'
        ]
    }
}

const parent = new Parent({
    importantValue : 123
});

const child = new Child({
    owner : parent,
    // Will be resolved from the owner
    value : 'up.importantValue'
});

console.log(child.value); // logs 123

Please note that this is for now a one way one time binding, the value will only be read initially and not kept up to date on later changes.

Value Merging

When a config property value is an object, the value declared by the base class is merged with values declared by derived classes and the value passed to the constructor.

 class Example extends Base {
     static configurable = {
         config : {
             foo : 1,
             bar : 2
         }
     };
 }

 class Example2 extends Example {
     static configurable = {
         config : {
             bar : 42,
             zip : 'abc'
         }
     };
 }

 let ex = new Example2({
     config : {
         zip : 'xyz'
     }
 });

The result of the merge would set config to:

 ex.foo = {
     foo : 1,    // from Example
     bar : 42,   // from Example2
     zip : 'xyz' // from constructor
 }

Config Options

Some config properties require additional options such as declarative information about the config that may be useful to automate some operation. Consider a Button. It could declare that its text config affects the rendered HTML by applying a render property to the config definition. Its base class could then examine the config definition to find this property.

To support this, config options ca be declared like so:

 class Button extends Widget {
     static configurable = {
         text : {
             value   : null,
             $config : {
                 render : true
             }
         }
     };
 }

The $config property can alternatively be just the names of the options that should be enabled (set to true).

For example, the following is equivalent to the above:

 class Button extends Widget {
     static configurable = {
         text : {
             value   : null,
             $config : 'render'
         }
     };

Default Value

It is common to set a config to a null value to take advantage of internal optimizations for null values. In most cases the fact that this produces undefined as the actual initial value of the config is acceptable. When this is not acceptable, a config can be declared like so:

 class Widget {
     static configurable = {
         disabled : {
             $config : null,
             value   : null,
             default : false
         }
     };

The default property above determines the value of the config while still gaining the benefits of minimal processing due to the null value of the value property.

A class property getter to add additional, special class properties.

For example, a class adds a declarable class property like so:

 class Something extends Base {
     static get declarable() {
         return ['extra'];
     }

     static setupExtra(cls, meta) {
         // use cls.extra
     }
 }

A derived class can then specify this property like so:

 class Derived extends Something {
     static get extra() {
         // return extra information
     }
 }

When the Derived class is initialized, the setupExtra() method is called and Derived is passed as the argument. It is also the this pointer, but the parameter is minifiable. The second argument passed is the $meta object for the class.

Classes are initialized at the first occurrence of the following:

• An instance is created
• The class $meta property is accessed

A legacy class property getter for the default configuration of the class, which can be overridden by configurations passed at construction time. We recommend using configurable instead.

Unlike a normal static property, this property is only ever used for the class that defines it (as in, hasOwnProperty). It is retrieved for all classes in a class hierarchy, to gather their configs individually and then combine them with those of derived classes.

For example, a Store might declare its url config like so:

 class Store extends Base {
     static get defaultConfig() {
         return {
             url : null
         };
     }
 }

The url config is automatically inherited by classes derived from Store. By implementing get defaultConfig(), derived classes can change the default value of inherited configs, or define new configs, or both. When defining new configs, however, configurable is preferred.

Config properties introduced to a class by this declaration do not participate in value merging and do not get a generated setter. Config properties introduced by a base class using configurable can be set to a different value using defaultConfig and in doing so, the values will be merged as appropriate for configurable.

This class property returns an object that specifies methods to wrap with configurable timer behaviors.

It is used like so:

 class Foo extends Base.mixin(Delayable) {
     static get delayable() {
         return {
             expensiveMethod : 500
         };
     }

     expensiveMethod() {
         this.things();
         this.moreThings();
         this.evenMoreThings();
     }
 }

With the above in place, consider:

 let instance = new Foo();

 instance.expensiveMethod();

Instead of the above code immediately calling the expensiveMethod(), it will start a timer that will invoke the method 500ms later. Because expensiveMethod() is an instance method, each instance of Foo will have its own timer.

NOTE: Only instance methods are currently supported (i.e., only non-static methods).

Options

The value of each key configures how the method will be scheduled. If the value is a number, it is promoted to a config object of type='buffer' as in the following:

 class Foo extends Base.mixin(Delayable) {
     static get delayable() {
         return {
             expensiveMethod : {
                 type  : 'buffer',
                 delay : 500
             }
         };
     }
 }

The type property of the config object must be one of three values. Other options can be provided depending on the type:

• buffer
  Other options:
  • delay (Number) : The number of milliseconds to wait before calling the underlying method. A value of 0 is equivalent to setting immediate: true.
  • immediate (Boolean) : Set to true to call immediately (effectively disabling the buffer).
• raf (short for "request animation frame")
  
• idle (short for "request idle callback") Not available on Safari
  Other options:
  • cancelOutstanding (Boolean) : Set to true to cancel any pending animation frame requests and schedule a new one on each call.
  • immediate (Boolean) : Set to true to call immediately.
• throttle
  Other options:
  • delay (Number) : The number of milliseconds to wait after each execution before another execution takes place. A value of 0 is equivalent to setting immediate: true.
  • immediate (Boolean) : Set to true to call immediately (effectively disabling the throttle).

While immediate: true can be specified at the class level, it is more typical to set it on the instance's method as described below.

Delayable Method API

Delayable methods have a consistent API to manage their scheduling. This API is added to the methods themselves.

For example:

 let instance = new Foo();

 instance.expensiveMethod();         // schedule a call in 500ms
 instance.expensiveMethod.isPending; // true
 instance.expensiveMethod.cancel();
 instance.expensiveMethod.flush();
 instance.expensiveMethod.now();

 instance.expensiveMethod.delay = 10;
 instance.expensiveMethod();         // schedule a call in 10ms

isPending (Boolean, readonly)

This boolean property will be true if a call has been scheduled, and false otherwise.

cancel()

Cancels a pending call if one has been scheduled. Otherwise this method does nothing.

flush()

Cancels the timer and causes the pending call to execute immediately. If there is no pending call, this method does nothing.

now()

Cancels the timer (if one is pending) and executes the method immediately. If there is no pending call, this method will still call the underlying method.

An object owned by this class that does not share properties with its super class. This object may contain other properties which are added as needed and are not documented here.

• class : Function

  The class constructor that owns the meta object

• super : Object

  The $meta object for the super class. This is null for Base

• config : Object

  The object holding the default configuration values for this class

• configs : Object

  An object keyed by config name that holds the defined configs for the class The value of each property is a Config instance

• forkConfigs : Boolean

  This will be true if the default configuration values for this class (in the config property of the meta object) must be forked to avoid object sharing, or if the object can be passed to Object.create() for efficiency

• hierarchy : Function[]

  The array of classes in the ancestry of this class. This will start with Base at index 0 and ends with this class

• properties : Function[]

  The array of classes that define a "static get properties()" getter