171
edits
ServerJS/API/ProposalK: Difference between revisions
Jump to navigation
Jump to search
Added some story behind the ProposalK for ServerJS API.
m (Added a link to the list proposal for ServerJS) |
(Added some story behind the ProposalK for ServerJS API.) |
||
| Line 1: | Line 1: | ||
* | |||
* | == Synopsis == | ||
* | |||
In JavaScript there are both "rhinocerous", native patterns for collection | |||
types embodied by the usage and generic methods of <tt>Array</tt> and | |||
<tt>Object</tt>. However these objects and their patterns have several disadvantages | |||
which give rise to the need for "best practices" in user-defined collections. | |||
* <tt>.length</tt> assignment is not observable in pure-JS interoperably | |||
* <tt>[index]</tt> assignment is only special for <tt>Array</tt> and inheriting <tt>Array does not imbue types with their specialness. | |||
* <tt>[name]</tt> assignment can have name collisions between names in an object's prototype chain and those that it ought to contain. Assigning arbitrary strings in this domain can potentially mask builtins. | |||
* The <tt>in</tt> operator cannot be safely used on <tt>Object</tt> instances to check for containment or iteration. You have to use the <tt>Object.prototype.hasOwnProperty.call</tt> method instead. | |||
* Proxies for native objects cannot observe indexing or length assignment. | |||
* <tt>Array</tt>'s constructor is not strictly variadic. That is, creating an Array with a single value that is a number must be done with Array literals. <tt>Array</tt> and <tt>Object</tt> do not support copy construction. | |||
* <tt>Object</tt> can only be used for mappings from a domain of strings. | |||
However, there are distinct advantages of playing nicely with these types, like | |||
being able to use the <tt>Array.prototype</tt> generic methods. For this reason, | |||
there need to be two layers of collection types: those that play well with | |||
natives ("rhinocerous types", if you will), and those that can be manipulated | |||
in pure JavaScript using a new set of conventional names. With these | |||
user-defined types, it's necessary to use methods for all interaction with | |||
the underlying collection. | |||
We can create a system of base types that support | |||
mutual copy construction and mutual interface implementation. | |||
That is, all collections should be constructable | |||
by passing an iterable as their argument, and in turn all collections should | |||
be iterable. Python does this well, but we can do one step better by making | |||
the default iteration on dictionary mappings to render an iterable of | |||
(key, value) pairs instead of simply the keys. We can also define orthogonal | |||
interfaces intrinsic to each of the three main collection types and cross | |||
implement those interfaces in each other type to the extent it make sense. | |||
That is, a List is a duck-type for a Dict where the keys are offsets. | |||
A Dict is a Set of pairs. A Set is an unordered List. | |||
Methods intrinsic to: | |||
* Set (unordered values): insert, remove, retrieve, discard | |||
* Dict (unordered pairs): get, set, del, has, put, cut | |||
* List (ordered values, (index value pairs)): push, pop, shift, unshift | |||
But List implements all of these Dict interface, and Dict can inherit Set. | |||
This is a proposal for modules to be included in the standard library. | |||
Since there's some coupling between iteration and stream IO, I've begun | |||
layout out those modules as well. My recommendation is to implement | |||
the IO, file, and socket modules in the standard library. That would leave | |||
each platform to implement a "posix" module with all the routines that | |||
these other libraries would need. | |||
This is very rough draft status. I imagine there's a lot of room for | |||
discussion on nomenclature and intended scope for the ServerJS | |||
standard library. | |||
== API == | |||
* Iterations Module API [[ServerJS/API/iter/ProposalK]] | * Iterations Module API [[ServerJS/API/iter/ProposalK]] | ||
* Sets Module API [[ServerJS/API/set/ProposalK]] | * Sets Module API [[ServerJS/API/set/ProposalK]] | ||
* Dictionaries Module API [[ServerJS/API/dict/ProposalK]] | * Dictionaries Module API [[ServerJS/API/dict/ProposalK]] | ||
* Lists Module API [[ServerJS/API/list/ProposalK]] | * Lists Module API [[ServerJS/API/list/ProposalK]] | ||
* Posix Module API [[ServerJS/API/posix/ProposalK]] | |||
* File Module API [[ServerJS/API/file/ProposalK]] | |||
* IO Module API [[ServerJS/API/io/ProposalK]] | |||