easejs/README.traits

# -*-org-*-
# TITLE: GNU ease.js Traits

The trait implementation is not yet complete; this is the list of known
issues/TODOs.  If you discover any problems, please send an e-mail to
bug-easejs@gnu.org.

Aside from the issues below, traits are stable and ready to be used in
production.  See the test cases and performance tests for more
information and a plethora of examples until the documentation is
complete.


* TODO Trait Extending
  Traits are able to "extend" classes, thereby declaring interface
  compatability; this is a useful alternative to interfaces when a trait is
  designed to augment a specific type.  This convenience should be extended
  to traits: a trait should be able to "extend" another trait in the same
  manner that it may extend a class.

* TODO Documentation
  Due to the trait implementation taking longer than expected to
  complete, and the importance of the first GNU release, trait
  documentation is not yet complete.  Instead, traits have been
  released as a development preview, with the test cases and
  performance tests serving as interim documentation.

  Comprehensive documentation, including implementation details and
  rationale, will be available shortly.

* TODO Static members
  Static members are currently unsupported.  There is no particular
  difficulty in implementing them---the author didn't want it to hold
  up an initial release (the first GNU release) even further.

* TODO Getters/setters
  Getters and setters, although they act like properties, should be
  treated as though they are methods.  Further, they do not suffer
  from the same complications as properties, because they are only
  available in an ES5 environment (as an ECMAScript language feature).

* TODO Mixin Caching
  The pattern =Type.use(...)(...)=---that is, mix a trait into a class
  and immediate instantiate the result---is a common idiom that can
  often be better for self-documentation than storing the resulting
  class in another variable before instantiation.  Currently, it's also
  a terrible thing to do in any sort of loop, as it re-mixes each and
  every time.

  We should introduce a caching system to avoid that cost and make it
  fairly cheap to use such an idiom.  Further, this would permit the
  Scala-like ability to use Type.use in Class.isA checks.

* TODO Public/Protected Property Support
  Private properties are currently supported on traits because they do
  not affect the API of the type they are mixed into.  However, due to
  limitations of pre-ES5 environments, implementing public and
  protected member epoxying becomes ugly in the event of a fallback,
  amounting essentially to re-assignment before/after trait method
  proxying.  It is possible, though.

  This is not a necessary, or recommended, feature---one should aim to
  encapsulate all data, not expose it---but it does have its
  legitimate uses.  As such, this is not a high-priority item.

* TODO Trait-specific error messages
  All error messages resulting from traits should refer to the trait
  by name and any problem members by name, and should offer
  context-specific suggestions for resolution.  Currently, the errors
  may be more general and may reflect the internal construction of
  traits, which will be rather confusing to users.

* TODO Performance enhancements
  The current trait implementation works well, but is relatively slow
  (compared to how performant it could be).  While this is sufficient
  for most users' uses, there is plenty of room for
  improvement.  Until that time, be mindful of the performance test
  cases in the =test/perf= directory.

  If we are to do so, though, we must make sure that the entire class
  API is supported.