Trait (aka the "Trait constructor") takes a record describing required and provided properties and returns a trait containing these properties.

The record argument is usually an object literal. Both its identity and its prototype chain are irrelevant when constructing a trait.

Data properties bound to function objects in the argument are marked as method properties in the resulting trait. The prototype of these function objects is frozen by Trait.

Data properties bound to the Trait.required singleton are marked as required properties in the resulting trait.

compose takes any number of argument traits and returns a composite trait combining all of the own properties of the argument traits.

If two or more traits have own properties with the same name, the composite trait will contain a conflict property for that name. In an Ecmascript 5 environment, conflicting properties are represented as accessors that throw upon access. In an Ecmascript 3 environment, they are represented as functions that throw when called.

Two properties are not in conflict if either of them is a required property, or if they refer to identical values (as determined by ===).

compose is a commutative and associative operation, and the ordering of its arguments does not affect its return value.

If compose is invoked with less than 2 arguments, then:

• compose(t) returns a trait equivalent to t.
• compose() returns an empty trait.

resolve takes a map describing properties to rename or exclude and a trait and returns a resolved trait in which the indicated properties are renamed or excluded. The map is any object that maps property names either to truthy values that will be coerced to String or to falsy values (such as undefined) which are interpreted as excluding the given property.

resolve can be used to rename or exclude properties that would be in conflict in subsequent compositions. resolve first excludes properties, then renames properties. Required properties are not affected by resolve.

Renaming a property p to p' introduces a new binding for p' in the resolved trait (if p' already exists, it is marked in conflict). The old property name p becomes a required property of the trait. Likewise, excluding a property p turns p into a required property of the trait.

Renaming a property does not affect references to that property in the method body of trait methods. Any such references will continue to refer to the original name.

override takes any number of argument traits and returns a composite trait combining all of the own properties of the argument traits.

If two or more traits have own properties with the same name, the property is overridden, with precedence from left to right. This implies that properties of the leftmost trait are never overridden. Required properties are always overridden by non-required properties. override never creates new conflicts.

override is associative: override(t1,t2,t3) is equivalent to override(t1, override(t2, t3)) or to override(override(t1, t2), t3). override is not commutative: override(t1,t2) is not equivalent to override(t2,t1).

If override is invoked with less than 2 arguments, then:

• override(t) returns a trait equivalent to t.
• override() returns an empty trait.

required is a singleton object that serves as a placeholder for a trait's required properties.

In principle, required should only be used inside the record definition passed to the Trait constructor.

create takes a prototype object and a trait and returns an instantiation of the trait. The instantiated object's prototype is proto.

create throws

• an Error('Missing required property: name'); if the trait contains a required property name.
• an Error('Remaining conflicting property: name'); if the trait contains a conflicting property name.

create is similar to the Ecmascript 5 built-in Object.create except that it generates high-integrity, "final" objects. In addition to creating a new object from a trait, it also ensures that:

• the object and all of its accessor and method properties are frozen.
• the this pseudovariable in all accessors and methods of the object is bound to the instantiated object. Hence, even if methods of the trait instance are extracted and used as funargs, this will retain its correct binding.

Because all methods of an instance created by this function are bound functions, their this pseudovariable is no longer late-bound. Hence, such instances should not be used as the prototype of other objects (because this would not refer to the delegating child object). That is why these instances are called "final" objects.

Use Object.create instead of Trait.create if you want your trait instances to remain malleable or if you want them to act as prototypes of other objects.

eqv takes two traits and returns whether or not they are equivalent.

A trait t1 is equivalent to a trait t2 if both define the same set of property names and for all property names n, the property descriptor t1[n] is equivalent to the property descriptor t2[n]. Two property descriptors are equivalent if they have the same value, accessors and attributes.

The value of two property descriptors is compared using ===.

object takes as its sole argument a record describing a trait and returns an instance of that trait whose prototype is Object.prototype.

Trait.object({...}) is a shorthand notation for:
Trait.create(Object.prototype, Trait({...})).

Think of object as the equivalent of Javascript's object-literal notation for high-integrity objects.

If traits.js is loaded in an Ecmascript 3 engine and Object.create does not exist, traits.js defines it. Otherwise, traits.js assumes the built-in Ecmascript 5 definition.

Object.create takes a prototype object and a trait and returns a new instance, whose prototype is proto and whose properties are described by the trait.

Passing a trait to the Ecmascript 5 built-in function Object.create works because traits are represented as property descriptor maps, which is the format accepted by this function. Unlike Trait.create, Object.create returns malleable, non-frozen objects. However:

• No exception is thrown if the trait still contains required or conflicting properties. Required properties remain as non-enumerable (in ES5) properties bound to undefined. Conflicting properties are bound to accessors (in ES5) that throw upon an attempt to get or set the property value. In ES3, they are bound to a function that throws when called.
• Neither the object nor its accessor and method properties are frozen.
• The this pseudovariable in all accessors and methods of the object is left unbound.

Since Ecmascript 3 does not support accessors or the notion of non-writable, non-enumerable and non-configurable properties, only writable, enumerable and configurable data properties can be created using this emulated version of Ecmascript 5's built-in Object.create function.

If traits.js is loaded in an Ecmascript 3 engine and Object.getOwnProperties does not exist, traits.js defines it. Otherwise, traits.js assumes the built-in Ecmascript 5 definition.

Object.getOwnProperties takes a record (usually an object literal) as an argument and returns a property descriptor map that describes the properties of the record.

This method can be used to turn any object into a property descriptor map. The resulting property descriptor map is a valid trait.

Unlike the Trait constructor, Object.getOwnProperties does not transform data properties bound to functions into method properties, or data properties bound to Trait.required into required properties.