phosphor-properties
A module for attached property descriptors.
Phosphor properties encapsulate several behaviors:
-
Creation - A property value can default to a static scalar value or be lazily created by invoking a value factory function.
-
Coercion - A property can coerce a user-provided value into a value which is guaranteed to be correct based on current state.
-
Notification - User code can be notified when a property value changes.
-
Attachment - A property can be defined for any object, not just for instances of the class which defines the property. This allows for extra state and behavior to be "attached" to arbitrary objects by external consumers of those objects.
These behavioral patterns are extremely useful for managing complexity in large applications. However, they are tedious and repetitive to implement manually. Phosphor properties reduce developer burden by bundling these behaviors into an efficient and type-safe form.
Package Install
Prerequisites
npm install --save phosphor-properties
Source Build
Prerequisites
git clone https://github.com/phosphorjs/phosphor-properties.gitcd phosphor-propertiesnpm install
Rebuild
npm run cleannpm run build
Run Tests
Follow the source build instructions first.
npm test
Build Docs
Follow the source build instructions first.
npm run docs
Navigate to docs/index.html
.
Supported Runtimes
The runtime versions which are currently known to work are listed below. Earlier versions may also work, but come with no guarantees.
- Node 0.12.7+
- IE 11+
- Firefox 32+
- Chrome 38+
Bundle for the Browser
Follow the package install instructions first.
npm install --save-dev browserifybrowserify myapp.js -o mybundle.js
Usage Examples
Note: This module is fully compatible with Node/Babel/ES6/ES5. Simply omit the type declarations when using a language other than TypeScript.
Class authors should strive to maintain consistency in how their classes expose properties to consumers. The PhosphorJS project has adopted a set of conventions which cover property naming, behavior, and exposure. It is recommended for third party libraries to adopt these same conventions in order to ensure API consistency and maximal compatibility with libraries and meta tools which rely on these conventions.
When defining a property for use by instances of the same class:
-
Define the property as a static member of the class.
-
Ensure the class type is used as the property owner type.
-
Append the suffix
'Property'
to the static member name. -
Give the property a
name
which is the same as the static member name, minus the'Property'
suffix. -
Define a public getter/setter which delegates access to the static property. The getter/setter should contain no logic outside of delegation to the static property.
-
The name of the getter/setter should be the same as the
name
given to the property. -
Consumers should normally use the getter/setter to access the property, but meta tools and code generators are free to use the property API directly. This is why the getter/setter must be a pure delegate as described above.
When defining a property for use by instances of a different class:
-
Define the property as a static member of the class.
-
Ensure the instance type is used as the property owner type.
-
Append the suffix
'Property'
to the static member name. -
Give the property a
name
which is the same as the static member name, minus the'Property'
suffix. -
Define static methods to get and set the value of the property for a particular instance of the owner type. These two methods should contain no logic outside of delegation to the static property.
-
Name the static methods by prepending
'get'
and'set'
to the capitalized propertyname
. -
Consumers should normally use the static methods to access the property, but meta tools and code generators are free to use the property API directly. This is why the methods must be pure delegates as described above.
A property declared for instances of a different class is referred to as an attached property. The behavior and semantics of the property are defined by one class, but the property value belongs to a foreign instance. This pattern is useful when creating container objects which must associate container data with child objects in a way which doesn't require polluting the child class with extraneous data members.
Basic Value:
; ; obj.value; // 42obj.value = 17; //obj.value; // 17
Create Callback:
; ;; obj1.one; // [1, 2, 3]obj1.two; // [1, 2, 3] obj2.one; // [1, 2, 3]obj2.two; // [1, 2, 3] obj1.one === obj2.one; // trueobj1.two === obj2.two; // false
Changed Callback:
; ; obj.value; // 42obj.value = 17; // logs: value changed: 42, 17obj.value; // 17
Coerce Callback:
; ; obj.checkable; // trueobj.checked; // false obj.checked = true; //obj.checked; // true obj.checkable = false; //obj.checked; // false
Notify Signal:
; ; ; obj.stateChanged.connectlogger; obj.value = 17; // logs: name: 'value', old: 42, new: 17obj.name = 'Jane'; // logs: name: 'name', old: 'John', new: 'Jane'
Compare Callback:
; ; obj.one; // 42obj.two; // 19obj.three; // 100 obj.one = 0; // logs: one changedobj.one; // 0obj.one = 1; // logs: one changedobj.one; // 1obj.one = 1; // no logobj.one; // 1 obj.two = 0; // no logobj.two; // 0obj.two = 1; // no logobj.two; // 1obj.two = 1; // no logobj.two; // 1 obj.three = 0; // logs: three changedobj.three; // 0obj.three = 1; // logs: three changedobj.three; // 1obj.three = 1; // logs: three changedobj.three; // 1
Attached Property:
; ;MyContainer.setStretchwidget, 3; ;container.addWidgetwidget;