GNU
/
easejs
1
0
Fork 0
Code Releases Activity

README TODOs using Org mode 

Even if you don't use Emacs, the outline style should be intuitive.

This commit is partially for organization, partially to let people
know that this project is still on my mind and will be getting more
attention soon.
textend
Mike Gerwitz 2014-12-19 22:20:32 -05:00
parent ee85b058df
commit 313a51d750
No known key found for this signature in database
GPG Key ID: F22BB8158EE30EAB
2 changed files with 91 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
README.todo
View File

@ -1,26 +1,25 @@
TODO
====
Todo tasks can be found in the bug tracker at http://easejs.org/bugs. Below is
a list of the glaring issues that may be found at first glance.
# -*-org-*-
# TITLE: GNU ease.js TODOs
TODO tasks can be found in the bug tracker at
http://easejs.org/bugs. Below is a list of the glaring issues that may
be found at first glance.
COUPLING
--------
During the beginning of the project, all modules were represented as object
literals, which is similar to the concept of a Singleton. This satisfied the
needs of the early project, but it soon evolved far past its original design and
resulted in a tightly coupled system that was difficult to maintain, add to and
test. Refactoring into prototypes is ongoing.
* TODO Coupling
During the beginning of the project, all modules were represented as
object literals, which is similar to the concept of a
Singleton. This satisfied the needs of the early project, but it
soon evolved far past its original design and resulted in a tightly
coupled system that was difficult to maintain, add to and
test. Refactoring into prototypes is ongoing.
* TODO Performance tests
Performance tests need to be written for every aspect of the
system. They will ultimately be graphed to show the relative
performance across versions of the software.
PERFORMANCE TESTS
-----------------
Performance tests need to be written for every aspect of the system. They will
ultimately be graphed to show the relative performance across versions of the
software.
CLOSURE COMPILER WARNINGS
-------------------------
Certain warnings are suppressed. Figure out the best way to resolve them without
suppressing them, unless suppression is truely the best option.
* TODO Closure compiler warnings
Certain warnings are suppressed. Figure out the best way to resolve
them without suppressing them, unless suppression is truely the best
option.

148
README.traits
View File

@ -1,98 +1,88 @@
GNU ease.js 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.
production. See the test cases and performance tests for more
information and a plethora of examples until the documentation is
complete.
TODO: Trait Extending
---------------------
Currently, the only way for a trait to override methods of a class it is
being mixed into is to implement a common interface. Traits should
alternatively be able to "extend" classes, which will have effects similar
to Scala in that the trait can only be mixed into that class. Further,
traits should be able to extend and mix in other traits (though such should
be done conservatively).
* TODO Trait Extending
Currently, the only way for a trait to override methods of a class
it is being mixed into is to implement a common interface. Traits
should alternatively be able to "extend" classes, which will have
effects similar to Scala in that the trait can only be mixed into
that class. Further, traits should be able to extend and mix in
other traits (though such should be done conservatively).
* 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.
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.
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: 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 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: 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 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: 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.
* 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.
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 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.
* TODO Intermediate object as class
The immediate syntax---=Foo.use(T)()=---is a short-hand equivalent
of =Foo.use(T).extend({})()=. As such, for consistency, =Class.isA=
should consider the intermediate object returned by a call to =use=
to be a class.
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.
TODO: Intermediate object as class
----------------------------------
The immediate syntax---Foo.use(T)()---is a short-hand equivalent of
Foo.use(T).extend({})(). As such, for consistency, Class.isA should consider
the intermediate object returned by a call to `use' to be a class.
If we are to do so, though, we must make sure that the entire class API is
supported.
If we are to do so, though, we must make sure that the entire class
API is supported.