CommonJS Spec Wiki http://wiki.commonjs.org/wiki/CommonJS MediaWiki 1.15.3 first-letter Media Special Talk User User talk CommonJS CommonJS talk File File talk MediaWiki MediaWiki talk Template Template talk Help Help talk Category Category talk Property Property talk Type Type talk Form Form talk Concept Concept talk Filter Filter talk Website Website talk 3 999 2009-09-10T03:15:35Z Dantman 1 Robot: Automated text replacement (-CommonJS/API +OldAPI) {{Old}} Here are sections for proposed standard modules. * [[OldAPI/console]] * [[OldAPI/system]] * [[OldAPI/binary]] * [[OldAPI/file]] * [[OldAPI/io]] * [[OldAPI/ioString]] 4 1000 2009-09-10T03:15:45Z Dantman 1 Robot: Automated text replacement (-CommonJS/API +OldAPI) == Synopsis == In JavaScript there are both "javascriptish/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</tt> 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 CommonJS standard library. == API == * Iterations Module API [[OldAPI/iter/ProposalK]] * Sets Module API [[OldAPI/set/ProposalK]] * Dictionaries Module API [[OldAPI/dict/ProposalK]] * Lists Module API [[OldAPI/list/ProposalK]] * Binary Module API [[OldAPI/binary/ProposalK]] * Posix Module API [[OldAPI/posix/ProposalK]] * File Module API [[OldAPI/file/ProposalK]] * IO Module API [[OldAPI/io/ProposalK]] 5 1247 2009-09-12T04:40:59Z Dantman 1 Robot: Automated text replacement (-\[\[(.+?)\|\1\]\] +[[\1]]) Please see the [[Binary]] proposal for details about the contents of the "binary" module. 6 973 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/binary/ProposalK]] to [[OldAPI/binary/ProposalK]] /*** Binary Returns a representation of an array of bytes. Accepts a Binary, or an Array of Numbers. Throws an error if any Number is greater than or equal to 256, less than 0, or of sub-integer precision. */ /**** length */ /**** get */ /**** set */ /**** slice */ /**** concat */ /**** indexOf */ /**** replace */ /**** toSource */ /**** toString */ /**** toSource */ 7 975 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/console]] to [[OldAPI/console]] Many client-side libraries already support a JavaScript console object. Since this functionality is useful on the server, and to ease migration of client-side JavaScript to the server, server-side JavaScript platforms need to provide a "console" object suitable for use with minimal modification to existing scripts. Rather than provide a "console" free variable like web browsers, interoperable JavaScript modules may explicitly import the "console" module and bind it to a module local "console" variable. = Specification = The "console" top-level module must be available in all platforms. The module must provide the following exports: ; log(message) : logs a message ; info(message) : logs an informational message ; warn(message) : logs a warning message ; error(message) : logs an error message Messages may be any reference. Names must be strings. = Prior Art = * [http://getfirebug.com/logging.html Firebug] * [http://developer.apple.com/internet/safari/faq.html#anchor14 Safari 1.3 Console] * [http://operawiki.info/OperaJSConsole Opera JavaScript Console] * Internet Explorer 8 JavaScript Console = Relevant Discussions = = Show of Hands = = Implementations = 8 977 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/dict/ProposalK]] to [[OldAPI/dict/ProposalK]] /*** Dict an unordered collection of key to value mappings. Unlike `Object`, a `Dict` object's key domain includes any object, with better performance when the `hash` of each key does not collide. That is, the `Number` ``1`` and the `String` ``"1"`` are distinct objects. `Dict` inherits from `Iterable` and `Set`, overriding the `eq` and `hash` of the underlying `Set` to use versions that hash and compare equivalence based on the pair component of key value pairs. Different than Python ``dict``: - ``update``: `add` - ``has_key``: `hasKey` - ``iteritems``: `itemsIter` - ``iterkeys``: `keysIter` - ``itervalues``: `valuesIter` - ``fromkeys(S, v)``: ``Dict(each(S.keys(), function (k) {return [k, v]}))`` - ``setdefault``: use `set` and `get` - ``__del__`` -> `remove` - ``__contains__`` -> `has` Same as Python: - `get` - `clear` - `copy` - `items` - `keys` - `values` - `pop` */ /**** keysIter returns an `Iter` of keys from the key and value pairs (items) in the dictionary. Uses `itemsIter`. - `stateless` */ /**** keys returns a `Set` of keys from the key and value pairs (items) in the dictionary. Uses `keysIter` and `itemsIter`. - `stateless` */ /**** valuesIter returns an `Iter` of values from the key and value pairs (items) in the dictinoary. Uses `itemsIter`. - `stateless` */ /**** values returns a `List` of values from the key and value pairs (items) in the dictionary. Uses `valuesIter` and `itemsIter`. - `stateless` */ /**** itemsIter returns an iteration, `Iter`, of the key and value pairs (items) in the dictionary. Items are represented as native JavaScript `Array` objects. Uses `iter`, which is defined for the `Set` base-type. - `stateless` */ /**** items returns a `List` of the key and value pairs (items) in the dictionary. Items are represnted as native JavaScript `Array` objects. Uses `itemsIter`. - `stateless` */ /**** get returns the value of an item in the dictionary that has a given key. If there is item for the key, attempts to return a default value, checking whether you've specified a default value to return as a second argument, or deferring to `getDefault`. If no acceptable default exists, throws a `KeyError`. accepts: - a key (any object) - an optional default value, which can be `undefined` or `null` if you wish to avoid throwing a `KeyError`. - `stateless` */ /**** set stores a key and corresponding value (an item) in the dictionary. If an item already exists in the dictionary that has the same key, it is overwritten. - stateful - chainable */ /**** put an alias for `set` */ /**** has returns whether a dictionary contains a given key. */ /**** cut returns the value for a given key and removes the corresponding key, value pair from the dictionary. - `stateful` */ /**** del deletes the key and value pair (item) in the dictionary that has a given key. - `stateful` - `chainable` */ /**** getDefault an overridable function that returns a value or throws a KeyError if you attempt to `get` an item for a key that the dictionary does not contain. - `stateless`, but overrides may be stateful. */ /**** hasValue returns whether the dictionary contains an item with the given value. - `stateless` */ /**** hasKey an alias of `has` - `stateless` */ /**** update Sets the given iterable of key value pairs on this dictionary, overriding any existing keys. - `stateful` - `chainable` */ /**** updated Returns a new copy of this dictionary that has been updated with the pairs in a given iterable. - `stateless` - `chainable` */ /**** complete Sets the given iterable of key value pairs on this dictionary, except for those with existing keys. - `stateful` - `chainable` */ /**** completed Returns a new copy of this dictionary that has been completed with the pairs in a given iterable. - `stateless` - `chainable` */ /**** find - `stateless` */ /**** findReverse since dictionary keys are not ordered, `findReverse` is an alias of `find`. - `stateless` */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq - `stateless` */ /**** repr - `stateless` */ /**** string - `stateless` */ /**** hash - `stateless` */ /**** invoke an alias of `get` that permits a dictionary to be used as a unary relation on its domain of keys to its range of values. */ /*** toDict */ /*** toObject Creates a new native JavaScript `Object` from any instance. Defers to any user defined `toObject` method of the given object. Failing that, defers to `dict` to convert the given object to a `Dict` and then creates an `Object` from that dictionary's key value pairs. */ /*** hasKey - `polymorphic` */ /*** hasValue - `polymorphic` */ /*** update - `polymoprhic` - `stateful` - `chainable` */ /*** updated - `polymorphic` - `stateless` - `chainable` */ /*** complete - `polymoprhic` - `stateful` - `chainable` */ /*** completed - `polymorphic` - `stateless` - `chainable` */ /*** clear removes all key value pairs from list and dict-like objects including native Arrays, Objects, and types that override the `clear` function like `Dict` and `List`. - `polymorphic` - `stateful` - `chainable` */ /*** keys - `polymorphic` - `stateless` */ /*** keysIter - `polymorphic` - `stateless` */ /*** values - `polymorphic` - `stateless` */ /*** valuesIter - `polymorphic` - `stateless` */ /*** items - `polymorphic` - `stateless` */ /*** itemsIter - `polymorphic` - `stateless` */ 9 1239 2009-09-12T04:35:20Z Dantman 1 Robot: Automated text replacement (-Filesystem API +Filesystem) Moved to [[Filesystem]] and the original proposal at [[Filesystem/A]]. 10 981 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/file/Names]] to [[OldAPI/file/Names]] #REDIRECT [[Filesystem/Names]]. 11 983 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/file/ProposalK]] to [[OldAPI/file/ProposalK]] /** */ /*** File - :isa:`io#Io` */ /*** Stat - :isa:`Object` a representation of a file's metadata including permissions, ownership, time stamps, and other traits. */ /*** Dir */ /**** iter */ /*** glob returns a `List` of file names for a given "glob" expression that may contain patterns: === ====================================================== ? matches any single character * matches any pattern of characters ** matches any pattern of characters in the file names of a depth first traversal starting with the file names and directories that start with the file name characters before ``**`` and ending with the file name characters after ``**`` === ====================================================== */ /*** globIter returns an iteration of file names for a given "glob" expression that may contain patterns according to those documented in `glob` */ /*** separator The path separator for the platform's file systems. */ /*** resolve returns the real, absolute, fully-qualified path arrived at from a ``base`` path following an relative ``rel`` path. When no ``base`` is provided, resolves the ``rel`` path relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative path between two fully-qualifed paths. */ /*** baseName */ /*** dirName */ 12 985 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/io/ProposalK]] to [[OldAPI/io/ProposalK]] This module and the file module in this proposal are a hybrid of mostly the Ruby API melded with Pythonic/Rhinocerous iteration, and liberated of the notion that certain things should be static methods as opposed to simply hosted by the module. /** */ /*** Io - :is:`iter#Iterable` */ /**** input - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier - returns a `String` decoded from reading */ /**** print - accepts a `String` to encode and write - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier */ /**** read - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were actually read. */ /**** write - returns a `Number` of however many bytes were actually written. */ /**** readNonblock - accepts a maximum `Number` of bytes to read. - returns a `Binary` of however many bytes were read without blocking. */ /**** writeNonblock - accepts a `Binary` of bytes to write. - returns a `Number` of however many bytes were actually written without blocking. */ /**** isEof returns whether the read/write head is at or beyond the end of the stream. */ /**** iter an alias for `linesIter` */ /**** linesIter - accepts an optional `String` line terminator - accepts an optional `String` encoding module identifier returns an iteration on lines (`String`) of the stream. */ /**** charsIter - accepts an optional `String` encoding module identifier returns an iteration of characters (`String`) of the stream. */ /**** bytesIter returns an iteration on bytes (`Binary`) of the stream. */ /**** fcntl */ /**** getFileNo returns an integer `Number` for the process stream number that the IO object is attached to. */ /**** toNumber an alias for `getFileNo` */ /**** getLineNo returns the current "line" number from the file. updated on read. */ /**** isTty returns whether the stream is attached to a terminal device, a teletype, ``tty``. */ /**** getPos get the current byte offset of the read/write head in the stream. */ /**** setPos set the current byte offset of the read/write head in the stream. */ /**** rewind Equivalent to ``setPos(0)`` */ /**** seek Seeks to a given integer `Number` offset in the stream relative to a given position: Accepts: - ``offset``, an integer `Number` - ``whence``, an enumerated integer `Number` supplied by one of the following constants. Whence: ======== ================================== SEEK_CUR Seeks to current position plus ``offset`` SEEK_END Seeks to the end of the stream plus ``offset``, usually negative. SEEK_SET Seeks to the beginning of the stream plus ``offset`` ======== ================================== Example:: var file = require('file'); var io = require('io'); var f = file.File("testfile", "utf-8"); f.seek(-13, io.SEEK_END); var line = f.input() */ /**** stat */ /**** select */ /**** fsync */ /**** ioctl */ 13 987 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/iter/ProposalK]] to [[OldAPI/iter/ProposalK]] /*** Iterable a mixin that adds convenience functions to types that implement `iter`. */ /**** iter a default ``iter`` that returns itself. */ /**** added */ /**** nextCatch */ /**** len a default, destructive implementation of `len` that consumes the remaining elements of the iteration and returns how many were encountered. */ /**** toObject */ /**** toArray */ /**** toList */ /**** toDict */ /**** toUnique returns a `Set` of the unique elements of the iterable. */ /**** toString returns the concatenation of the elements of the iterable coerced into `String` objects. */ /**** toNumber a polymorphic alias of `len`. */ /**** toBoolean returns whether `toNumber` is greater than 0. */ /**** sliced */ /**** forEach */ /**** forEachApply */ /**** each */ /**** eachIter */ /**** eachApply */ /**** eachApplyIter */ /**** where */ /**** whereIter */ /**** whereApply */ /**** whereApplyIter */ /**** zip */ /**** zipIter */ /**** transpose */ /**** transposeIter */ /**** enumerate */ /**** enumerateIter */ /**** reduce */ /**** reduced */ /**** flatten */ /**** flattened */ /**** group */ /**** sorted */ /**** reversed */ /**** min */ /**** mix */ /**** sum */ /**** product */ /**** all */ /**** any */ /**** join */ /*** Iter - :is:`Iterable` Accepts: - an optional ``next`` `Function`. Without a ``next`` function, returns an empty iteration. - an optional ``hasNext`` `Function``. */ /**** next */ /**** hasNext */ /*** iter Returns an iteration of a given object. Attempts to call the polymorphic `iter` of a typed object. Otherwise, coerces to the first applicable of `String`, `Array`, or `Object` types. */ /*** objectIter */ /*** arrayIter */ /*** stringIter */ /** Top Level Functions =================== Functions that operate on iterables, or objects coercible to iterables using the polymorphic `iter` function. */ /*** forEach */ /*** forEachApply */ /*** each */ /*** each */ /*** eachIter */ /*** eachApply */ /*** eachApplyIter */ /*** where */ /*** whereIter */ /*** whereApply */ /*** whereApplyIter */ /*** map */ /*** mapIter */ /*** forTimes */ /*** timesIter */ /*** times */ /*** transpose */ /*** transposeIter */ /*** zip */ /*** zipIter /*** enumerate */ /*** enumerateIter */ /*** reduce */ /*** cycle */ /*** chain */ /*** repeat */ /*** flatten */ /*** compact */ /*** compactIter */ /*** without */ /*** withoutIter */ /*** group */ /*** all */ /*** any */ /*** min */ /*** max */ 14 989 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/list/ProposalK]] to [[OldAPI/list/ProposalK]] /*** List is `Iterable` Different than Python: - append: `push` - extend: `add` - count: `len` - index: `find` - insert: `put` - remove: `del` Same as Python: - `pop` - `sort` - `reverse` */ /**** toIter - `stateless` */ /**** len - `stateless` */ /**** push - `stateful` - `chainable` */ /**** pop - `stateful` */ /**** unshift - `stateful` - `chainable` */ /**** shift - `stateful` */ /**** reverse - `stateful` - `chainable` */ /**** reversed - `stateless` */ /**** reversedIter - `stateless` */ /**** sort - `stateful` - `chainable` */ /**** sorted - `stateless` - `chainable` */ /**** slice - `stateful` - `chainable` */ /**** sliced - `stateless` - `chainable` */ /**** splice - `stateful` */ /**** spliced - `stateless` - `chainable` */ /**** clear - `stateful` - `chainable` */ /**** first - `stateless` */ /**** last - `stateless` */ /**** begins returns whether the first elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``startswith``. This divergence from Python nomenclature is a matter of idealism. Ideally the semantic group of `start`, `stop`, `pause`, `resume`, and `run` are all temporal verbs, whereas the semantic group `begins`, `ends`, `first`, `last`, and such all apply to the state of spatial segments or lists. - `stateless` */ /**** ends returns whether the last elements of a given list-like-object are equal, by way of `eq`, the respective elements in this list. In Python, this function is called ``endsWith``. See ``startsWith`` for the rationale. - `stateless` */ /**** reduce reduce is an in place operation. see reduced for a stateless variant - `stateful` - `chainable` */ /**** keysIter - `stateless` */ /**** keys - `stateless` */ /**** valuesIter - `stateless` */ /**** values an alias of `copy` so that lists can be used as dictionary like objects. - `stateless` */ /**** itemsIter enumerates the values of the list. - `stateless` */ /**** items returns a list of the enumerated values from this list, using `itemsIter`. - `stateless` */ /**** get gets a value by its offset. - `stateless` */ /**** set sets a value at a particular offset. - `stateful` - `chainable` */ /**** put displaces the item at a given index, sending successive elements down the line. - `stateful` - `chainable` */ /**** cut gets the value at a given offset and delete the value from the list. - `stateful` */ /**** del removes a value from the list, shifting all successive values into its void. - `stateful` - `chainable` */ /**** has returns whether the list contains a given value. - `stateless` */ /**** hasKey returns whether the list contains a value at a given index. - `stateless` */ /**** hasValue retunrs whether the list contains a given value. Uses `has`. - `stateless` */ /**** find returns the first index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** findReverse returns the last index of a given value in the list, or throws a `ValueError` if none can be found. - `stateless` */ /**** insert an alias of `push` */ /**** retrieve */ /**** remove */ /**** discard */ /**** add - `stateful` - `chainable` */ /**** added - `stateless` - `chainable` */ /**** eq returns whether this list has the same cardinality, order, and respective values as another object. - `stateless` */ /**** lt returns whether the the most significant, distinct value between the respective values of this list and another list-like object is less than the other. - `stateless` */ /**** join returns a `String` of the joined string values of the values in this list, on a given delimiter or simply concatenated. - `stateless` */ /**** repr - `stateless` */ /**** toArray - `stateless` */ /**** hash - `stateless` */ /*** toList constructs a `List` from any given iterable. Defers to a `toList` or `toIter` method of the given object if it exists. - `poymorphic` on `toList` or `toIter` */ /*** toArray constructs a native JavaScript `Array` from any iterable. - `polymorphic` on `toArray` or `toIter` */ /*** len returns the length of a `List`, `Array`, `Object`, or any other object that provides a `len` member function. - `polymorphic` */ /*** reversed returns a `List` of the values from an iterable in reversed order. - `stateless` */ /*** sorted returns a `List` of the values in a given `Iteration` in sorted order. Accepts an optional override of `compare`, a binary relation that returns a `Number` that has the same comparison relationship with ``0`` as the relationship between the given values. For example, ``-1`` if the first is less than the second, or ``0`` if they are equal. - `stateless` */ /*** slice - `polymorphic` - `not-curry` - `stateless` */ /*** splice */ 15 991 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/posix/ProposalK]] to [[OldAPI/posix/ProposalK]] The idea behind this module is that it would be implemented as a native module on each respective platform and hosted by the default loader. Other IO modules would use these functions as a basis. /** */ /*** open Accepts: - ``fileName`` - ``mode`` Returns a file descriptor of unspecified type. Modes ===== Mode Meaning ==== ====================================================================== "r" read-only, starting at the beginning of the file "r+" read-write, starting at the beginning of the file "w" write-only, truncates an existing file to empty or creates a new file "w+" read-write, truncates an existing file to empty or creates a new file "a" write-only, starts at end of file if file exists or creates a new file "a+" read-write, starts at end of file if file exists or creates a new file "b" binary file mode, may appear before any of the modes above */ /*** close */ /*** creat */ /*** flush */ /*** tell */ /*** stat */ /*** lstat */ /*** unlink */ /*** chown */ /*** chmod */ /*** dup */ /*** dup2 */ /*** fctnl */ /*** ioctl */ /*** select */ /*** getcwd */ 16 993 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/set/ProposalK]] to [[OldAPI/set/ProposalK]] /*** Set An unordered collection of unique values. Accepts: - optional ``values`` (may be ``undefined``, or any iterable object, by way of the polymorphic `toIter`) - optional custom ``hash`` relation. - optional custom ``eq`` binary equivalence relation. Inherits member functions from `Iterable`. `Set` operations operate in constant time best case, and linear for degenerate cases. If you insert an object in a set and modify that object in such a way that its ``hash`` result changes, it will be irrecoverable. Most other libraries enforce that only immutable objects should be inserted in sets for this reason, so be careful. */ /*** insert inserts a value in the `Set`. Position is not relevant. Replaces an existing value if the value has the same `hash` key and is `eq` to an existing value. The `hash` function and `eq` function can be overridden in the `Set` constructor. - `stateful` - `chainable` */ /*** retrieve retrieves a value from the `Set` that has the same `hash` key and is `eq` to a given value. `eq` and `hash` can be overridden in the `Set` constructor. - `stateless` */ /**** remove removes a value from the `Set` if it has the same `hash` and is `eq` to the value. throws a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** discard discards a value from the `Set` if it has the same `hash` and is `eq` to the value. Unlike `remove`, does not throw a `ValueError` if no matching value can be found. - `stateful` - `chainable` */ /**** clear removes all values in this set. - `stateful` - `chainable` */ /**** has returns whether a set contains a given value. uses `eq` and `hash` to attempt to find the value in the set. These functions can be overridden in the `Set` constructor. */ /**** find searches all of the values in set for one that is `eq` to a given value. returns that value. throws a `ValueError` if no value can be found. - accepts a value to find - accepts an optional override to the `eq` function - `stateless` */ /**** toIter */ /**** eq */ /**** union augments itself with any values that exist in another iterable. - `stateful` - `chainable` */ /**** intersect - `stateful` - `chainable` */ /**** difference - `stateful` - `chainable` */ /**** unioned returns all elements that are in itself and another iterable. - `stateless` - `chainable` */ /**** intersected returns all values that are in this set and another. - `stateless` - `chainable` */ /**** differenced returns the set of all values that are in this set but not another. - `stateless` - `chainable` */ /**** symmetricDifferenced returns the set of all values that are exactly one set between itself and another. - `stateless` - `chainable` */ /**** isSuperSet returns whether this set contains all of the values in a given container. - `stateless` */ /**** isSubSet returns whether a given container contains all of this set's values. - `stateless` */ /**** added alias of `unioned` - `stateless` - `chainable` */ /**** add alias of `union` - `stateful` - `chainable` */ /**** muled alias of `intersected` - `stateless` - `chainable` */ /**** mul alias of `intersect` - `stateful` - `chainable` */ /**** subed alias of `differenced` - `stateless` - `chainable` */ /**** sub alias of `difference` - `stateful` - `chainable` */ /**** and alias of `intersect` - `stateful` - `chainable` */ /**** anded alias of `intersected` - `stateless` - `chainable` */ /**** or alias of `union` - `stateful` - `chainable` */ /**** ored alias of `unioned` - `stateless` - `chainable` */ /**** xor alias of `symmetricDifferenced` - `stateful` - `chainable` */ /**** xored alias of `symmetricDifferenced` - `stateless` - `chainable` */ /** Functions ========= Functions that operate on sets, or arrays coercible to sets using the polymorphic `toSet` function. */ /*** toSet */ /*** insert */ /*** retrieve */ /*** remove */ /*** discard */ /*** clear */ /*** has */ /*** union */ /*** intersect */ /*** difference */ /*** symetricDifference */ /*** isSuperSet */ /*** isSubSet */ 17 1248 2009-09-12T04:41:08Z Dantman 1 Robot: Automated text replacement (-\[\[(.+?)\|\1\]\] +[[\1]]) See the [[System]] proposal. It is as yet undecided whether the "system" object will be a free variable available to all modules, or a module that can be required. 18 997 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/url/ProposalK]] to [[OldAPI/url/ProposalK]] /*** resolve returns the real, absolute, fully-qualified URL arrived at from a ``base`` URL following an relative ``rel`` URL. When no ``base`` is provided, resolves the ``rel`` URL relative to the current working directory. - accepts ``rel`` - accepts an optional ``base`` */ /*** relative returns the relative URL between two fully-qualifed paths. */ 19 2772 2010-05-13T19:12:31Z Markm 54 /* Relevant Discussions */ '''STATUS: PROPOSALS, DISCUSSION''' JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working byte or binary array or string class. == Proposals == # [[Binary/A]] Proposal A from Ondras # [[Binary/B]] Proposal B from Kris Kowal (implemented by a few platforms) # [[Binary/C]] Proposal C from Daniel Friesen # [[Binary/D]] Proposal D from Kris Kowal (based on [[Binary/B]], -array-comprehsiveness, +bits, +radix-encoding) # [[Binary/E]] Proposal E (based on [[Binary/D]] with byte string <nowiki>[[Get]]</nowiki> returning Number instead of ByteString, +Binary base type, -bits, -radix-encoding, -patching) # [[Binary/Lite]] Proposal "Lite" from Ondras (single Binary type -charsets) # [[Binary/F]] Proposal F (based on [[Binary/E]] but viciously trimmed, -ByteString, s/ByteArray/Buffer/ -flexible length) == Prior Art == * [http://help.adobe.com/en_US/AIR/1.1/jslr/flash/utils/ByteArray.html Adobe AIR's ByteArray] * [https://developer.mozilla.org/En/NsIBinaryInputStream Mozilla's nsIBinaryInputStream] * [https://developer.mozilla.org/En/NsIBinaryOutputStream Mozilla's nsIBinaryOutputStream] * [http://www.ejscript.org/products/ejs/doc/api/ejscript/intrinsic-ByteArray.html EJScript ByteArray] * [http://code.google.com/apis/gears/api_blob.html Google Gears Blob] * [http://code.google.com/p/jslibs/wiki/jslang#jslang::Blob_class JSlibs Blob] * [http://flusspferd.org/docs/js/Blob Flusspferd Blob] [http://github.com/ruediger/flusspferd/blob/1ead764aca33aca6926b6ac85871d1482c465616/src/core/blob.jsdoc repository link] (since it has been removed, the docs might go away at some point) * [http://www.w3.org/TR/FileAPI/ W3C File API] (blob, FileBlob, readAsBinaryString, readAsDataUrl) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/da076076c965d069/2cd8ac336387ceb3?lnk=gst Comments on Binary object] * [http://groups.google.com/group/commonjs/browse_thread/thread/e866544eb3aff182/16ed57b3c78b86e1?lnk=gst Binary API Brouhaha] * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] regarding proposal B * [http://groups.google.com/group/commonjs/browse_thread/thread/0680b464e775726c Binary/C - range for memcopy] * [http://groups.google.com/group/commonjs/browse_thread/thread/8a0d9db68e81baae ByteString / ByteArray duality] * [http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 Alternate binary proposal] regarding [[Binary/C]] * [http://wiki.ecmascript.org/doku.php?id=strawman:typed_arrays Typed Arrays strawman on the EcmaScript wiki] which cites Khronos's proposed [https://cvs.khronos.org/svn/repos/registry/trunk/public/webgl/doc/spec/TypedArray-spec.html TypedArray spec] as its primary source. [[Encodings]] are a related topic. 20 871 2009-09-10T02:48:08Z Dantman 1 moved [[CommonJS/Binary/A]] to [[Binary/A]] == Binary Data == JavaScript does not have a binary data type. However, in server-side scenarios, binary data needs to be often processed. That is why we need some working <tt>Binary()</tt> class. === Binary() object proposition === This is an interface of my proposed Binary object. I also created a sample implementation, see http://tmp.zarovi.cz/binary.js. <source> /** * Creates a new variable holding binary data. * @param {number} initialData Variable amount if initial arguments. Every number represents a byte. * @returns {Binary} */ function Binary(initialData) {}; /** * Returns the number of bytes stored in this structure. * This is intentionally named "getLength" instead of "length" to indicate a method (and not a property). * @returns {number} */ Binary.prototype.getLength = function() {}; /** * Converts the binary variable to string by UTF-8 encoding its contents. * @returns {string} */ Binary.prototype.toString = function() {}; /** * Returns a byte value from a given index. * @param {number} index * @returns {number} */ Binary.prototype.getByte = function(index) {}; /** * Sets a byte value at given index. * @param {number} index */ Binary.prototype.setByte = function(index, value) {}; /** * These are essentialy copied from the Array class. */ Binary.prototype.pop = function() {}; Binary.prototype.push = function() {}; Binary.prototype.shift = function() {}; Binary.prototype.unshift = function() {}; /** * Encodes the data in Base64 * @returns {string} */ Binary.prototype.base64encode = function() {}; /** * Calculates MD5 hash * @returns {string} */ Binary.prototype.md5 = function() {}; /** * Calculates SHA1 hash * @returns {string} */ Binary.prototype.sha1 = function() {}; /** * Decodes the Base64 encoded string * @returns {Binary} */ String.prototype.base64decode = function() {}; /** * Converts an UTF-8 encoded string into its binary (one byte per item) variant * @returns {Binary} */ String.prototype.toBinary = function() {}; [[User:Ondras|Ondras]] 08:24, 5 February 2009 (UTC) 21 2790 2010-05-24T00:03:54Z KrisKowal 6 added NarwhalJSC and NarwhalNode to list of compliant implementations {{Spec |status=proposed, discussed, some implementations |implementations=Flusspferd, GPSEE, NarwhalRhino=0.2, NarwhalJSC=0.2, NarwhalNode=0.5, RingoJS, v8cgi }} Draft 2. All platforms must support two types for interacting with binary data: ByteArray and ByteString. The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds. The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1. These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString. (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/commonjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.) = Philosophy = This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/commonjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[../|prior art]]. This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array. Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the CommonJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points. This behavior may be specified further in the future. In accordance with Daniel Friesen's [[Binary/C]], a high priority in this proposal was String/ByteString and Array/ByteArray interoperability. For a defined subset of the String and Array APIs, Strings are interoperable with ByteStrings and Arrays with ByteArrays. To this end, it is necessary to support valueAt as an alternative to charAt on Strings with which ByteStrings would iteroperate. Supporting charAt on ByteString would be counter-intuitive. Similarly, codeAt must be implemented on both String and ByteString as an alternative to charCodeAt. The following methods are interoperable between ByteString and String: * codeAt returning Number (added to String) * valueAt returning ByteString or String respectively (added to String) * get returning ByteString or String respectively (added to String) * indexOf * lastIndexOf * split * slice * substr * substring The following methods are interoperable between ByteArray and Array: * get returning Number (added to Array) * indexOf * lastIndexOf * concat * pop * push * shift * unshift * reverse * slice * sort * splice * split * forEach * every * some * map * reduce * reduceRight The following methods are interoperable between ByteString and ByteArray: * codeAt returning Number * valueAt returning ByteString * get returning ByteString or Number respectively * toByteString * toByteArray * toString * toArray * decodeToString * indexOf * lastIndexOf * slice returning ByteString or ByteArray respectively * split returning an Array of ByteStrings or ByteArrays respectively * concat returning ByteString or ByteArray respectively = Specification = The "binary" top-level module must export "Binary", "ByteArray" and "ByteString". (In multi-sandbox scenarios, the implementation should strive to consistently export the same "Binary", "ByteArray", and "ByteString") == Binary == A Binary function must exist. The Binary function must throw a ValueError if it is ever called or constructed. The Binary type exists only to affirm that ByteString and ByteArray instances of Binary. == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array that does not implicitly terminate at the first 0-valued byte. Indexing returns a byte substring of length 1. ByteString instances are instances of ByteString, Binary, and Object. The typeof a ByteString is "object". Object.prototype.call.toString(byteString) returns "[object ByteString]". === Constructor === ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. : If any element is outside the range 0...255, a RangeError is thrown. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Constructor methods === ; join(array, delimiter) : Like Array.prototype.join, but for Binarys. Returns a ByteString. The following are equivalent expressions. ByteString.join([1,2,3], 0) ByteString([1, 0, 2, 0, 3]) === Instance properties === ; length : The length in bytes. Immutable. === Instance operators === ; [] ByteString : the immutable [] operator returning ByteStrings === Instance methods (in prototype) === ; toByteArray() : Returns a byte for byte copy in a ByteArray. ; toByteArray(sourceCharset, targetCharset) : Returns a transcoded copy in a ByteArray. ; toByteString() : Returns itself, since there's no need to copy an immutable ByteString. ; toByteString(sourceCharset, targetCharset) : Returns a transcoded copy. ; toArray() : Returns an array containing the bytes as numbers. ; toArray(charset) : Returns an array containing the decoded Unicode code points. ; toString() : Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included. ; toSource() : returns "ByteString([])" for a null byte string or "ByteString([0, 1, 2])" for a byte string of length 3 with bytes 0, 1, and 2. ; decodeToString(charset) : Returns the decoded ByteArray as a string. ; indexOf(byte) ; indexOf(byte, start) ; indexOf(byte, start, stop) : Returns the index of the first occurance of byte (a Number or a ByteString or ByteArray of any length) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; lastIndexOf(byte) ; lastIndexOf(byte, start) ; lastIndexOf(byte, start, stop) : Returns the index of the last occurance of byte (a Number or a ByteString or ByteArray of any length) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. ; codeAt(offset) Number : Return the byte at offset as a Number. ; byteAt(offset) ByteString ; valueAt(offset) ByteString ; get(offset) ByteString : Return the byte at offset as a ByteString. get(offset) is analogous to indexing with brackets. ; copy(target, start, stop, targetStart) : copies the Number values from this ByteString between start and stop to a target ByteArray or Array at the targetStart offset. start, stop, and targetStart must be Numbers, undefined, or omitted. If omitted, start is presumed to be 0. If omitted, stop is presumed to be the length of this ByteString. If omitted, targetStart is presumed to be 0. ; split(delimiter, [options]) : Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size. : Options is an optional object parameter with the following optional properties: * ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters. * ''includeDelimiter'' - Whether the delimiter should be included in the result. : Returns an array of ByteStrings. ; slice() ; slice(start) ; slice(start, stop) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; concat(...ByteString/ByteArray/Array...) : returns a ByteString composed of itself concatenated with the given ByteString, ByteArray, and Array values. ; substr(start) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substr String.prototype.substr] ; substr(start, length) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substr String.prototype.substr] ; substring(first) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substring String.prototype.substring] ; substring(first, last) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substring String.prototype.substring] ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset. == ByteArray == A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array. Instances of ByteArray are instances of ByteArray, Binary, and Object. The typeof a ByteArray is "object". Object.prototype.toString.call(byteArray) returns "[object ByteArray]". === Constructor === ; ByteArray() : New, empty ByteArray. ; ByteArray(length) : New ByteArray filled with length zero bytes. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. : Throws an exception if any element is outside the range 0...255 (''TODO''). ; ByteArray(string, charset) : Create a ByteArray from a Javascript string, the result being encoded with charset. Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor. All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set. Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array. Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined". Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF. Negative numbers will be bit extended to a byte in two's complement form and likewise masked. === Instance properties === ; mutable length property : extending a byte array fills the new entries with 0. === Instance Operators === ; [] Number : The mutable [] operator for numbers === Instance methods (in prototype) === ; toArray() : n array of the byte values ; toArray(charset) : an array of the code points, decoded ; toString() : A string debug representation like "[ByteArray 10]", where 10 is the length of the byte string. This method must not throw an error. ; toSource() : returns "ByteArray([])" for a null byte array or "ByteArray([0, 1, 2])" for a byte array of length 3 with bytes 0, 1, and 2. ; decodeToString(charset String) : returns a String from its decoded bytes in a given charset. ; toByteArray() : returns a copy ; toByteArray(sourceCharset, targetCharset) : transcoded ; toByteString() : byte for byte copy ; toByteString(sourceCharset, targetCharset) : transcoded ; byteAt(offset) ByteString ; valueAt(offset) ByteString : Return the byte at offset as a ByteString. ; get(offset) Number ; codeAt(offset) Number : Return the byte at offset as a Number. get(offset) is anlaogous to indexing with brackets. ; copy(target, start, stop, targetStart) : copies the Number values from this ByteArray between start and stop to a target ByteArray or Array at the targetStart offset. start, stop, and targetStart must be Numbers, undefined, or omitted. If omitted, start is presumed to be 0. If omitted, stop is presumed to be the length of this ByteArray. If omitted, targetStart is presumed to be 0. ; fill(value, start, stop) : fills each of the contained bytes with the given value (either a unary ByteString, ByteArray, or a Number) from the "start" offset to the "stop" offset. "start" and "stop" must be numbers, undefined, or omitted. If omitted, "start" is presumed to be 0. If omitted, "stop" is presumed to beh the length of this ByteArray. ; concat(other:ByteArray|ByteString|Array) ByteArray ; pop() byte:Number : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/pop Array.prototype.pop] ; push(...variadic Numbers...) -> count(Number) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/push Array.prototype.push] ; extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...) : equivalent to this.push.apply(this, arguments) ; shift() byte:Number : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/shift Array.prototype.shift] ; unshift(...variadic Numbers...) count:Number : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/unshift Array.prototype.unshift] ; extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...) : equivalent to this.unshift.apply(this, arguments) ; reverse() in place reversal : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/reverse Array.prototype.reverse] ; slice() : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; sort() : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/sort Array.prototype.sort] ; splice() : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/splice Array.prototype.splice] ; indexOf() : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/indexOf Array.prototype.indexOf] ; lastIndexOf() : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/lastIndexOf Array.prototype.lastIndexOf] ; split() : Returns an array of ByteArrays instead of ByteStrings. ; filter(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/filter Array.prototype.filter] ; forEach(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/forEach Array.prototype.forEach] ; every(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/every Array.prototype.every] ; some(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/some Array.prototype.some] ; map(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/map Array.prototype.map] ; reduce(callback[, initialValue]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/reduce Array.prototype.reduce] ; reduceRight(callback[, initialValue]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/reduceRight Array.prototype.reduceRight] ; displace(start, stop, values/ByteStrings/ByteArrays/Arrays...) -> length : start/stop are specified like for slice. Can be used like splice but does not return the removed elements. == String == The String prototype will be extended with the following members: ; toByteArray(charset) : Converts a string to a ByteArray encoded in charset. ; toByteString(charset) : Converts a string to a ByteString encoded in charset. ; charCodes() : Returns an array of Unicode code points (as numbers). ; charAt(offset) Number : an alias for charCodeAt that interoperates with ByteString's charAT. ; get(offset) String : an alias for the index operator and interoperable with ByteString, ByteArray, and Array. == Array == The Array prototype will be extended with the following members: ; toByteArray(charset) : Converts an array of Unicode code points to a ByteArray encoded in charset. ; toByteString(charset) : Converts an array of Unicode code points to a ByteString encoded in charset. ; get(offset) : an alias for the index operator and interoperable with ByteString, ByteArray, and String. == General Requirements == None of the specified prototypes or augmentations to existing prototypes are enumerable. Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii" and "utf-8". Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. Charsets are case insensitive. = Tests = * [http://github.com/tlrobinson/narwhal/tree/master/tests/serverjs CommonJS tests] compatible with [http://github.com/tlrobinson/narwhal/tree/master/lib/test this test framework]. (targetting draft 1) = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/commonjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] 23 877 2009-09-10T02:48:08Z Dantman 1 moved [[CommonJS/Binary/C/Essay]] to [[Binary/C/Essay]] This page contains the essay like portions of [[../|Binary/C]] which were essay like and were moved out of the spec. == ByteArray? == From the discussions in the CommonJS mailing list I do not recall anyone saying "[I] want to mutate a [sequence] with the Array api". I only recall the statements "[I] want a way to mutate a [sequence]" and "mutable, like an Array". The decision to use the name "ByteArray" had nothing to do with wanting an Array type sequence. It had to do with wanting to mutate a sequence, and Arrays being the other type of list. Looking into prior art the Array api does not fit. There is a more relevant term used in computing, the buffer. 24 1326 2009-09-18T09:09:32Z Dantman 1 This page lists the various show of hands for points within the [[Binary/C]] proposal. Blob and Buffer in what module: :A) Blob and Buffer in require('binary'); :* Kris Kowal :* Ash Berlin :B) Blob in require('binary'); and Buffer in require('io'); :* Mario Valente :C) Blob and Buffer as globals :* Kris Kowal :D) Blob as global and Buffer in require('io/buffer'); :* Daniel Friesen (MonkeyScript will provide global Blob whether it is standard or a non-standard addition) ---- Method parameter preference for new methods like .clear .fill .remove (methods based on existing js methods will keep the same parameters. :A) offset, length (used in .splice .substr) :* Daniel Friesen :B) begin, end (used in .slice .substring, Java) :* Kris Kowal :C) named arguments :* Ash Berlin :C.1) <code>x.remove({ from: 4, to: 5 });</code> :* Daniel Friesen (alt to A) :C.2) <code>x.remove({ begin: 4, end: 5 });</code> :C.3) <code>x.remove({ start: 4, end: 5 });</code> ---- blob[idx]: :A) Leave blob[idx] out of the standard (easier to implement in js-only rhino) :B) Require implementations to implement blob[idx] (Array (and string?) methods will work on blobs) ---- Property used on String, Blob, Buffer, Streams, and so on to refer to the mode it is running in (binary or text) by returning the String or the Blob constructor. (If you can think of a better name, just add a new item) :A) Content :* Kris Kowal :B) Value :C) contentConstructor :* Daniel Friesen :D) contentPrototype :E) content :F) value :G) Unit :H) Element [[Category:Show of hands]] 25 881 2009-09-10T02:48:09Z Dantman 1 moved [[CommonJS/Binary/C/Unpacking]] to [[Binary/C/Unpacking]] These methods are related to unpacking, they were be removed from the proposal in favor of specifying that at a higher layer but are here for reference until we write a proposal for unpacking of binary data. ;blob.integerAt(offset, size=1, signed=false, networkEndian=false); :Extracts an integer out of a blob. Arguments may control the byte size extracted whether the number is signed or unsigned, and whether or not the byte is in networkEndian or not. The default is to return a single unsigned byte in the form of an integer in the range 0..255. ;blob.floatAt(offset, size); :Extracts a float out of a blob. This method requires a size argument of either 4 (floats) or 8 (doubles) to extract a number and should generate a TypeError if passed invalid params. ;blob.stringAt(offset, size, fromCharset=UTF-16); :Extracts a string out from a blob. This method is similar to if you had done <code>blob.slice(offset, size).toString(fromCharset||"UTF-16");</code>. 26 2070 2010-02-02T15:08:07Z Wesgarland 13 GPSEE URL update For C/C++ based JavaScript interpreters, being able to interface easily with C libraries is a big win because of all of the available functionality. Each JavaScript interpreter has its own bridge to C, but if there is some common API (possibly exposed at the JavaScript level as in ctypes), then this will make it much easier to share work between interpreters. == Prior Art == * The JSAPI is the C API for the [https://developer.mozilla.org/en/SpiderMonkey SpiderMonkey] JavaScript engine https://developer.mozilla.org/En/SpiderMonkey/JSAPI_ * NSPR API Reference https://developer.mozilla.org/en/NSPR_API_Reference * Ejscript http://www.ejscript.org/products/ejs/doc/api/native.html is a complete native API to create objects, classes and composite native types. It also supports loadable modules with backing native libraries. * jsffi http://code.google.com/p/jslibs/wiki/jsffi is a module that allow you to call any symbol in a native module (dll/so). * jsext "Including C functions" http://jsext.sourceforge.net/Including%20C%20functions.html * js-ctypes https://wiki.mozilla.org/JSctypes is a foreign-function library for Mozilla’s privileged JavaScript. It provides C-compatible data types and allows JS code to call functions in shared libraries (dll, so, dylib) and implement callback functions. * SpiderApe plugins http://spiderape.sourceforge.net/plugins/ * NSPR API Reference https://developer.mozilla.org/en/NSPR_API_Reference * K7 http://github.com/sebastien/k7 Uses a system of C preprocessor macros to product cross-interpreter native modules. * Flusspferd's C++ api http://docs.flusspferd.org/ provides a nicer (and slightly abstracted) C++ API to Spidermonkey * [http://code.google.com/p/gpsee/ GPSEE] has an FFI-like layer which exposes generic native types/calls which are portable without JS-land changes between various UNIX and Linux platforms. Currently implemented for SpiderMonkey. == Papers == * [http://scholar.google.com/scholar?cluster=9334403348999738260&hl=en&as_sdt=2000 C APIs in extension and extensible languages] The authors of Lua make a convincing argument for the advantages of the Lua 5 C API, which evolved considerably and incompatibly from Lua 1. They compare it with Python's API, Java's JNI API, and others. The main idea is that using a stack to communicate between Lua and C solves 2 "impedance mismatches" between Lua and C: * Converting between the C type system and the Lua type system * Manual memory management in C and automatic memory management in Lua (garbage collection). For example, the Python API is very concerned about the details of garbage collection, which Lua avoids. v8's API is also influenced strongly by its particular implementation of garbage collection. Using the stack for communication also allows for a much smaller API, and they compare the sizes of the various APIs. 27 845 2009-09-10T02:15:01Z Dantman 1 moved [[CommonJS/Coding Standards]] to [[Coding Standards]] Code will be formatted according to this style guide: http://javascript.crockford.com/code.html Need to add details about namespaces and thread safety. Also, documentation and testing practices for things that help to describe and verify the API. 28 2876 2010-08-19T23:31:39Z Panzi 130 = Command line processing = Many server-side tools use a command line as their interface, and there should be a high-level way to deal with the arguments. == Prior Art == * Flusspferd's [http://flusspferd.org/docs/js/flusspferd%20core/getopt.html getopt] module * v8cgi's [http://code.google.com/p/v8cgi/wiki/API_GetOpt GetOpt] module * Microsoft [http://msdn.microsoft.com/en-us/library/ss1ysb2a(VS.85).aspx WshArguments] object in the Windows Script Host environment. ** [http://code.google.com/p/curlie/source/browse/trunk/curlIE.wsf?spec=svn9&r=7#39 CommandLine object], by Olivier Mengué, a generic API to Unix-style parsed arguments with a concrete JavaScript implementation on top of WshArguments ([http://code.google.com/p/curlie/source/browse/trunk/curlIE.wsf?spec=svn9&r=7#163 CScriptCommandLine]). * Python's [http://docs.python.org/library/optparse.html optparse] module provides a reasonably powerful, flexible and full-featured option parser. * [http://bitbucket.org/panzi/javascript-utils/src/tip/optparse.js optparse.js]: inspired by Python's optparse module but with some distinct differences. * Narwhal's "args" module [http://github.com/tlrobinson/narwhal/blob/master/lib/narwhal.js example usage], [http://github.com/tlrobinson/narwhal/blob/master/lib/args.js the module] 29 1940 2010-01-04T05:59:55Z Andychu 62 Add NodeJS One should probably try to follow the [http://www.whatwg.org/specs/web-workers/current-work/ WebWorkers API] as far as it makes sense on the server. However, WebWorkers cannot share state, they can only communicate via messages, so if traditional threads are desired they are not acceptable. And traditional threads are generally considered deprecated in modern language design. The WebWorkers design was intentional. * [http://www.synchro.net/ Synchronet's] load() method supports creating background tasks/threads and implements a bidirectional Queue object which may be used to communicate with the concurrently executing child script: http://synchro.net/docs/jsobjs.html#Queue A possible alternative is a stronger eventing dispatch mechansim. Actionscript did lots of good work in this area. [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/ejs.events-classes.html Here] is a set of event, listener and timer classes from Ejscript. These can be retro fitted to interpreters for which threads and threading are problematic or impossible. * JSAPI threading https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference#Threading * NSPR threads https://developer.mozilla.org/en/NSPR_API_Reference#Threads * NSPR in general https://developer.mozilla.org/en/NSPR_API_Reference * JavaScript Strands adds coroutine and cooperative threading support to the JavaScript language http://www.xucia.com/strands-doc/index.html * Erlang-style concurrency with JavaScript 1.7 http://www.beatniksoftware.com/erjs/index.html * Threading in Javascript 1.7 http://www.neilmix.com/2007/02/07/threading-in-javascript-17/ * [http://nodejs.org/ NodeJS] makes a strong argument about doing concurrent I/O with an event loop. The implementation uses threadpools to work around synchronous APIs, but these are all hidden from the user. The user APIs are all asynchronous using callbacks and promises. 30 2857 2010-07-15T10:49:35Z Zumbrunn 5 Undo revision 2856 by [[Special:Contributions/Adam holmes|Adam holmes]] ([[User talk:Adam holmes|Talk]]) Welcome to [http://commonjs.org CommonJS], a group with a goal of building up the JavaScript ecosystem for web servers, desktop and command line apps and in the browser. This wiki is a starting point for collecting up ideas, links and any draft API suggestions for the [http://groups.google.com/group/commonjs CommonJS group]. Discussions occur on that mailing list and [http://log.serverjs.org/mochabot/join on IRC (#commonjs on freenode)]. == Meta == * [[Introduction]] * [[FAQ]] * [[Process]] * [[Target Platforms]] * [[Coding Standards]] == Current Efforts == This is a list of issues currently being discussed / standardized. They come from the "Low level" department, as we need to have a solid basics prior to building a tower. # [[Global|Uniform Baseline / Globals]] (discussion) # [[Modules]] ([[Modules/1.1.1|1.1.1]]) ## <code>binary</code>: [[Binary]] Data Objects (byte arrays and/or strings) (proposals, discussion, early implementations) ## <code>encodings</code>: [[Encodings]] and character sets (proposals, discussion, early implementations) ## <code>io</code>: [[IO|I/O Streams]] (proposals, discussion) ## <code>fs</code>, <code>fs-base</code>: [[Filesystem]] (proposals, discussion, early implementations) ## <code>system</code>: [[System]] Interface (stdin, stdout, stderr, &c) ([[System/1.0|1.0]], amendments proposed) ## <code>assert</code>, <code>test</code>: [[Unit Testing]] ([[Unit_Testing/1.0|1.0]], amendment proposals pending) ## <code>sockets</code>: [[Sockets|Socket I/O]] TCP/IP sockets (early proposals) ## <code>event-queue</code>: [[Reactor]] Reactor/Event Queue (early proposals) ## <code>worker</code>: [[Worker]] Worker (concurrent shared nothing process/thread) (proposal) ## <code>console</code>: [[console]] (proposal) # [[Packages]] ([[Packages/1.0|1.0]]) # [[JSGI|Web Server Gateway Interface (JSGI)]] (proposals, discussion, early implementations) # [[Promises]] (proposal) * [[Status|Pending Business / Calls for Action / Status Report]] == Future Efforts == === Low-level APIs === This is the collection of APIs that we'd like to see behaving consistently across JavaScript interpreters. * [[Runtime Services|Language and Runtime Services]] * [[Logging]] * [[RDBMS|Relational database interface]] * ResultSets (collections of data maybe from RDBMS, maybe from other sources) * [[Concurrency]] * [[String IO|String / ByteString I/O]] * [[C API|C unified API]] to our Target Platforms * [[Subprocess]]es (popen) === High-level APIs === This is the collection of APIs that implement common functionality on top of the low-level API. * [[HTTP Client|HTTP client]] APIs * [[Email]] * [[XMPP|Jabber (XMPP)]] * [[i18n|Internationalization]] * [[Promise Manager]] * [[Command Line|Command line processing]] == Implementations == {{ImplementationsTable |standards={{#ask: [[Category:Spec]] [[Is standard::yes]] | link=none }} |non-standards={{#ask: [[Category:Spec]] [[Is standard::no]] [[Has implementations::yes]] | link=none }} }} In development: * mob is implementing SecurableModules in Ejscript http://www.ejscript.org * pmuellr posted a sample loader for SecurableModules: http://wiki.github.com/pmuellr/modjewel * atul varma has a SecurableModule implementation for Python/Spidermonkey: http://hg.toolness.com/pydertron/raw-file/tip/docs.html * [[User: Alexandre.Morgaut|Alexandre]] implements several commonJS standards in Wakanda (SquirrelFish) http://www.wakandasoft.com * [[User: Fbraem|Franky Braem]] tries to implement several commonJS standards in GLUEscript: http://gluescript.sf.net. * Titanium is in the process of adding support for CommonJS. http://www.appcelerator.com == Tests == * [http://github.com/280north/narwhal/tree/master/tests/commonjs/ CommonJS tests] compatible with [http://github.com/280north/narwhal/tree/master/lib/test/ this test framework]. == Further Reading == * [[Existing APIs]] * [[Infrastructure]] * [[High Level Tools]] * [[Random Links]] == Wiki == * [[Dumps]] 31 2144 2010-03-10T10:39:54Z Oberhamsi 81 = Date and Time = EcmaScript already supports a wide range of functions handling Date, see https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Date but those kind of setters/getters are not very convinient when working with DateTimes. an easy way to e.g. add/substract timeranges, calculate time-diffs, etc. would be beneficial. problems to solve * outputting / parsing datetime * date calculations / manipulating * json date extension (see crockford's json module)? including TZ conversion? naive datetime's - not knowing about TZ - are easier to handle, though it seems JS has native aware datetime objects. utc & localtime. == Prior Art == * RingoJS, minimal date extensions http://github.com/ringo/ringojs/blob/master/modules/core/date.js e.g., Date.diff Date.getTimespan Date.equals * datejs, clientside library. nifty & big. http://code.google.com/p/datejs/ <source> // Get today’s date Date.today(); // Add 5 days to today Date.today().add(5).days(); // Get Friday of this week Date.friday(); // Get March of this year Date.march(); // Is today Friday? Date.today().is().friday(); // true|false </source> * [http://api.dojotoolkit.org/jsdoc/1.3/dojo.date dojo.date] and [http://api.dojotoolkit.org/jsdoc/1.3/dojo.date.locale dojo.date.locale] (dojo.date.stamp is obsoleted by ES5) ** dojo.date provides convenience methods ** dojo.date.locale provides format and parse functions which are data driven off the [http://unicode.org/cldr Unicode CLDR project], fully localized client-side, downloading localizations only as needed. Support for hundreds of languages/variants. <source> >>> dojo.date.locale.format(myDate, {selector: “date”, formatLength: “long”}) // en-us “June 28, 2008″ >>> dojo.date.locale.format(myDate, {selector: “date”, formatLength: “long”}) // zh-cn “2008年6月28日” </source> ** [http://api.dojotoolkit.org/jsdoc/1.3/dojox.date dojox.date] has experimental support for non-Gregorian calendars as well as Unix- and PHP-style formatting. * Matthew Eernisse implemented a [http://js.fleegix.org/plugins/date/date Date-like class] in JS to deal with the Olson table client-side, as well as code to parse and preprocess the Olson table. * ... 32 1085 2009-09-10T20:02:34Z Dantman 1 moved [[CommonJS/Doctools]] to [[Doctools]] = Documentation Tools = A major output of CommonJS will be an API specification and possibly some user docs to help people get started with a CommonJS-compatible platform. == Prior Art == * http://code.google.com/p/jsdoc-toolkit/ (requires Java) * Ejscript has a javadoc style doc generator called ejsmod. This [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/index.html doc], was generated with ejsmod. * http://scriptdoc.org/ (no public tooling) * http://www.naturaldocs.org/ (requires Perl) * [http://code.google.com/p/code-illuminated/ Code Illumionated] uses an approach with nice typography to document code. * [http://sphinx.pocoo.org/ Sphinx] is a Python-based tool for building documentation packages based on ReStructured Text files. It can generate HTML and PDF. [http://www.blueskyonmars.com/projects/paver/ Paver] has support for Sphinx to be able to maintain example code separate from the documentation files. 33 1836 2009-12-08T14:59:11Z Alexandre.Morgaut 33 PHP Mail Object APIs = Email APIs = Sending email is an extremely common server side activity and must be supported. This means providing easy mechanisms for generating a MIME message and sending email via an SMTP server (or possibly via a local command). == Prior Art == * Microsoft [http://msdn.microsoft.com/en-us/library/aa488400(EXCHG.65).aspx CDO.Message] object. Used in classic ASP, WSH, HTAs. * Netscape Server [http://research.nihonsoft.org/javascript/ServerReferenceJS12/sendmail.htm JavaScript 1.2 Sendmail API] * PHP [http://pear.php.net/manual/en/package.mail.mail-mime.php PEAR Mail_Mime] : [http://pear.php.net/manual/en/package.mail.mail-mime.example.php Sample] * PHP [http://framework.zend.com/manual/en/zend.mail.html Zend Mail] 34 2021 2010-01-24T01:27:39Z KrisKowal 6 fixed recursive move error #REDIRECT [[Encodings/A]] 35 2018 2010-01-24T01:24:55Z KrisKowal 6 moved [[Encodings/OldClass]] to [[Encodings/A/OldClass]]:&#32;putting in the proposal name space (non-versioned, lettered) === Class: Converter === There also should be a class enc.Converter for more advanced conversion. Please note that the interface is ''one way''. Despite the fact that it has two methods, it's ''one way''. It only supports ''encoding'', '''no''' decoding! Multiple people have got that wrong when glancing over it, so it's emphasised here. ; [Constructor] Converter(from, to) : Where from and to are the encoding names. ; [Method] write(byteStringOrArray) : Convert input from a ByteString or ByteArray. The results are stored in an internal buffer, and also those parts of byteStringOrArray that could not be converted (for multi-byte encodings, in a separate buffer). : Returns nothing. ; [Method] read([byteArray,] [maximumSize]) : Read maximumSize bytes or as many bytes as available out of the internal buffer. If byteArray is specified, the data is ''appended'' to that ByteArray. : Returns a ByteString if byteArray is not specified, or byteArray itself otherwise. ; [Method] close() : Close the stream. Throws an exception if there was a conversion error (specifically, a partial multibyte character). : Returns nothing and takes no parameters. Example usage: Converter = require('encodings').Converter converter = new Converter('iso-8859-1', 'utf-32') converter.write(input) // input is a ByteString output = converter.read() // output is a ByteString converter.close() 36 2113 2010-02-19T00:32:12Z Lucideer 76 It's a closed source project, but could still act as inspiration I suppose Links to existing server-side JS APIs which may act as an inspiration for some coordinated progress. * [http://code.google.com/p/piston/ Piston] * [http://code.google.com/p/chironjs/ chironjs] * [http://code.google.com/p/v8cgi/w/list v8cgi] * [http://code.google.com/p/jslibs/wiki/JSLibs JSLibs] * [http://www.ejscript.org/products/ejs/doc/ref/ejs/index.html EJScript] * [http://www.ejscript.org/products/ejs/doc/api/ejscript/index.html EJScript API] * [http://docs.persvr.org/documentation/server-side-js Persevere] * [http://jsext.sourceforge.net/Object%20reference.html JSExt] * [http://www.jsdb.org/reference.html jsdb] * [http://www.jnext.org/index.html jnext] * [http://www.modjs.org/ modjs] * [http://helma.zumbrunn.com/reference/ helma] * <s>http://www.wxjavascript.net/modules.html wxJavaScript</s> (Replaced by [http://gluescript.sf.net GLUEscript]) * [http://appjet.com/docs/librefbrowser appjet] * [http://www.10gen.com/apidocs/ 10gen] * [http://www.aptana.com/reference/jaxer/api/Jaxer.index-frame.html Jaxer API] * [http://freebaseapps.com/ Freebase Apps] * [http://github.com/mvalente/starbucks/tree/master STARBUCKS SSJS Web Dev Framework] (uses JSLibs, moving to Jaxer?) * [http://monkeyscript.org/ MonkeyScript] (uses JSLibs) * [http://spiderape.sourceforge.net/ SpiderApe] * [http://synchro.net/docs/jsobjs.html Synchronet] * [http://www.adobe.com/devnet/acrobat/javascript.html JavaScript for Acrobat] * <del>http://www.adobe.com/livedocs/flashm..._cs_asd_1.html</del> (dead) * [http://tinyclouds.org/node/ Node] * [http://tinyclouds.org/node/api.html Node API] * [http://www.page.ca/~wes/opensource/gpsee/ GPSEE Module Documenation] * [http://gluescript.sf.net GLUEscript] * [http://dev.opera.com/libraries/unite/docs/ Unite API] 37 1968 2010-01-12T03:22:28Z Pbannister 65 /* Why not Perl/PHP/Python/Ruby? */ === Why use JavaScript on the server? === As the scripting language of the web browser, JavaScript is and will be familiar to many developers. The group of developers acquainted and fluent with JavaScript likely will only increase over time. There is much developer productivity to be gained by re-using that fluency. In addition, using the same language on both the client and server sides may allow for some degree of code sharing. === Why not Perl/PHP/Python/Ruby? === While entirely worthy (to varying degrees) languages not in the browser will always be familiar to a subset of web application developers, where JavaScript fluency is more universal. When a higher order language is useful, JavaScript is roughly comparable to the other higher order alternatives. (Naturally, opinions will differ as to which is "best".) When developer fluency is factored in, JavaScript becomes a pragmatic choice. Note that JavaScript inherits notions from some of the more interesting object-oriented languages, including [http://en.wikipedia.org/wiki/Self_(programming_language) Self], [http://en.wikipedia.org/wiki/Scheme_(programming_language) Scheme], and Prototype - all with a C/C++/Java-like syntax. === If sharing code is the objective, then why not compile language X to JavaScript to send to the browser? === Debugging compiled code is not an enjoyable experience. Often, the abstraction layer between language X and JavaScript also has some holes then you end up needing to plug with hand-crafted JS (and not just stock JS, but JS that is designed to interface with that library). By using JavaScript all the way across, there are no such leaks. Also, there can be some impedance mismatch between the prototype-based object model in JavaScript and the class-based object models of other languages. === Is there a bonus reason to use JavaScript on the server? === Why yes, I'm glad you asked. JavaScript is powering increasingly complex applications in the browser. This has caused browser vendors to work hard on their JavaScript performance. Server side JavaScript has the potential to significantly outperform other common dynamic languages because of this work. 38 1092 2009-09-10T20:14:54Z Dantman 1 Redirected page to [[Filesystem/A]] #REDIRECT [[Filesystem/A]] 39 2557 2010-04-06T12:26:59Z Alexandre.Morgaut 33 /* Prior Art */ '''STATUS: PROPOSALS, DISCUSSION''' == Requirements/Proposals == * [[Filesystem/A]] Proposal ** [[Filesystem/A/0]] Proposal – a low level minimal proposal on which FS/A can be implemented using pure JS * [[/Hierarchy|File API Class hierarchy proposal]] * [[IO/B/Filesystem/Raw]] and [[IO/B/Filesystem]] of the [[IO/B]] proposal == Questionnaires and show of hands == * [[/Names|File API name preferences questionnaire]] * Summary/Comparison of current File APIs used by JS engines: [http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw CommonJS File Object Survey] * [[/Show of hands/]] * [[/Join/]] == Prior Art == * Microsoft [http://msdn.microsoft.com/en-us/library/z9ty6h50.aspx Scripting.FileSystemObject]. Used in classic ASP, WSH, HTAs. * [http://www.mozilla.org/js/js-file-object.html JavaScript File object proposal] (~1998) * [https://developer.mozilla.org/En/SpiderMonkey:File_object Spidermonkey File object] * [http://synchro.net/ Synchronet] provides a [http://synchro.net/docs/jsobjs.html#File File Class] that was originally inspired by SpiderMonkey's jsfile.c, but has been widely used and enhanced over the years. * Ejscript's [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/ejs.io-File.html File class] is still evolving, but is fairly comprehensive. It supports stackable streams such as BinaryStream, StringStream. It can also do I/O to and from a ByteArray class. * [http://jsext.sourceforge.net/JSEXT1.File.html JSExt.File] * [http://code.google.com/p/jslibs/wiki/jsio jslibs jsio module] * [http://www.wxjavascript.net/io/index.html wxJavascript IO module] * v8cgi has a [http://code.google.com/p/v8cgi/wiki/API#File_functions File] and [http://code.google.com/p/v8cgi/wiki/API#Directory_functions Directory] interfaces * helma has two File apis. One [http://helma.zumbrunn.com/reference/File.html deprecated] and one [http://helma.zumbrunn.com/reference/helma.File.html current] * adobe's extendscript has a File constructor.Documentation is difficult to find online. * generic [http://koberg.com/ripple/docs/api/ collection/document resource] (java) api (work in process) * Opera Software's [http://dev.opera.com/articles/view/file-i-o-api-for-widgets/ File I/O API for widgets], which will probably be standardized by the [http://www.w3.org/2006/webapi/ W3C Web API Working Group]. * [http://www.w3.org/TR/file-upload/ W3C File Upload] (Last version: October 2006) * [http://www.w3.org/TR/dap-api-reqs/#file-system W3C - Device APIs Requirements - File System] (Last version: October 2009) * [http://www.w3.org/TR/FileAPI/ W3C File API] (Last version: November 2009) === Inspiration === * (Python) PEP on new File IO http://www.python.org/dev/peps/pep-3116/ * Java File API http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html * Java Output API http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html * Java Input API http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html * E Secure File API http://www.erights.org/javadoc/java/io/File.html * Joe-E Secure File System API http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html * Python Path API http://docs.python.org/library/os.path.html * Ruby File API http://www.ruby-doc.org/core/classes/File.html * Ruby IO API http://www.ruby-doc.org/core/classes/IO.html * Perl Path::Class http://search.cpan.org/perldoc?Path::Class * PHP Filesystem http://php.net/manual/book.filesystem.php == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/a1b175c20ad61ed7 writ or write?] * [http://groups.google.com/group/commonjs/browse_thread/thread/5ed547baaba11f6c Filesystem API - Hobgoblin of little minds in little bike sheds with little bicycles] * [http://groups.google.com/group/commonjs/browse_thread/thread/eb721e00452c4d02 Filesystem API: stat] * [http://groups.google.com/group/commonjs/browse_thread/thread/abef650ba0c4f76d Filesystem API - Path(path, <nowiki>[fs]</nowiki>)] * [http://groups.google.com/group/commonjs/browse_thread/thread/f71e34667e1d5bde Filesystem API, Pure-JS glob implementation] * [http://groups.google.com/group/commonjs/browse_thread/thread/c4af0c8d278fd34b Return value of return? Partial writing?] 40 2788 2010-05-24T00:00:58Z KrisKowal 6 added NarwhalNode to list of implementations {{Spec |status=proposal, discussion |implementations=NarwhalRhino=draft 4 in 0.1, NarwhalNode=0.5, RingoJS=minus globbing }} Proposal A, Draft 6 = Overview = The "fs" module provides a file system API for the manipulation of paths, directories, files, links, and the construction of file streams. The [[IO|IO stream API]] is beyond the scope of this specification. ''Note: Other objects, apart from the "fs" module exports, may claim to conform to this specification.'' This specification builds on the normal primitives exported by "fs-base" specified in [[Filesystem/A/0]]. All methods implemented by "fs-base" must be exported by and override methods of this module. == Security == Objects implementing the File System API, including the "file" module object, are capability bearing objects that carry and mediate authority to read and write to the underlying storage. As such, the "fs" module can return other objects that implement and attenuate the File System API for sandboxing. Furthermore, streams returned by the file system object are implicitly attenuated to only give the receiver authority to manipulate the given file, without knowledge of the path on which it resides or access to references that would permit it to manipulate other parts of the file system. == Regarding Paths == Many methods accept paths as arguments. In every case, the path may be any object that is coercible to a <code>String</code> with the <code>String</code> constructor, that defers to <code>toString</code> for most objects. This includes <code>Path</code> objects. = Specification = == Files == ; open(path, mode|options) : returns an [[IO]] stream that supports an appropriate interface for the given options and mode, which include reading, writing, updating, byte, character, unbuffered, buffered, and line buffered streams. :* path: any value coercible to a String, including a Path, that can be interpreted as a fully-qualified path, or a path relative to the current working directory. :* mode String: any subtring of "rwa+bxc" meaning "read", "write", "append", "update", "binary", and "exclusive" flags respectively, in any order. :* options :** mode String: conforming to the above mentioned mode string pattern :** charset String: an IANA, case insensitive, charset name. <code>open</code> must throw a ('''TODO''') error if the charset is not supported. The <code>ascii</code> and <code>utf-8</code> charsets must be supported. :** read Boolean: open for reading, do not create, set position to beginning of the file, throw an error if the file does not exist. :** write Boolean: open for writing, create or truncate, set position to the beginning of the file. :** append Boolean: open for appending, create if it doesn't exist, do not truncate, set position to end of the file. :** update Boolean: open for updating, create if it doesn't exist, do not truncate, set position to the beginning of the file. :** binary Boolean return a raw stream instead of a buffered, charset encoded, text stream. :** exclusive Boolean: open for write only if it does not already exist, otherwise throw an error. : The "open" function mediates the construction of various kinds of streams. As "open" is the only method with the authority to manipulate files, it constructs these types on behalf of a potentially unpriviledged caller. Stream constructors are not directly callable in a secure sandbox, so where and how these stream types are implemented is beyond the necessary scope of this specification. The "open" function always creates a byte stream, and by default wraps that in a textual IO wrapper. "open" returns a stream resulting from the following algorithm: :# create a "raw" byte stream. If "x" mode (with either "w" or "a" mode), only open if the file does not already exist. Create the file and open the stream atomically. :#* if "r" mode, make "raw" a ByteReader :#* if "w" mode, make "raw" a ByteWriter :#* if "u" mode, make "raw" a ByteUpdater :# if "+", seek to end. :# if not "b" mode, return "raw". :# return a wrapper encoded/decoded string stream, wrapped around a buffered stream, wrapped around "raw". :#* if "r" mode, wrap "raw" in a TextReader :#* if "w" mode, wrap "raw" in a TextWriter :#* if "u" mode, wrap "raw" in a TextUpdater ; read(path, (mode|options)_opt) : opens, reads, and closes a file, returning its content. Equivalent to <code>open(source, mode).read()</code>. ; write(path, content String|Binary, (mode|options)_opt) : opens, writes, flushes, and closes a file with the given content. If the content is a ByteArray or ByteString, the binary mode is implied. Equivalent to <code>open(source, mode + "w" + (content instanceof Binary ? "b" : "")).write(content).flush()</code>, for mode Strings. ; copy(source, target) : reads one file and writes another in byte mode. Equivalent to <code>open(source, "b").copy(target, "b")</code> ; rename(path, name String) : Changes the name of a file at a given path. This differs from move in that the target is relative to the source instead of the current working directory. This method in particular should be implemented by the native "fs-base" module overriding any pure JavaScript implementation, if possible. ; move : [[Filesystem/A/0]] ; remove : [[Filesystem/A/0]] ; touch : [[Filesystem/A/0]] == Directories == ; makeDirectory : [[Filesystem/A/0]] ; removeDirectory : [[Filesystem/A/0]] ; makeTree(path) : Creates the directory specified by "path" including any missing parent directories. ; removeTree(path) : Removes whatever exists at the given path, regardless of whether it is a file, direcotory, or otherwise. If the path refers to a directory, but not a symbolic link to a directory, calls <code>removeTree</code> on each member of the directory. ; copyTree(source, target) : copies files from a source path to a target path, copying the files of the source tree to the corresponding locations relative to the target, copying but not traversing into symbolic links to directories. === Listing === ; list(path) Array * String : [[Filesystem/A/0]] ; listTree(path) Array * String : returns an Array that starts with the given path, and all of the paths relative to the given path, discovered by a depth first traversal of every directory in any visited directory, reporting but not traversing symbolic links to directories, in lexically sorted order within directories. The first path is always "", the path relative to itself. ; listDirectoryTree(path) Array * String : returns an Array that starts with the given directory, and all the directories relative to the given path, discovered by a depth first traversal of every directory in any visited directory, not traversing symbolic links to directories, in lexically sorted order within directories. === Globbing === ; glob(pattern) : returns an Array of all paths that match the given glob pattern from the current working directory. : glob patterns may include asterisks for 0 or more of any character except directory separator matches, question marks for exactly one of any character except directory separator matches, non-delimited square bracket notation for unions and escapes, comma delimited curly brace notation for nestable unions of substrings, and double asterisk for 0 or more of any character including directory separator matches (by way of a depth first traversal of intervening directories, visiting but not following symbolic links). ; match(path, pattern) : returns whether a path matches a given glob pattern. ; escape(path) : returns a path or path component as a glob pattern that would only match the given path component. === Path Objects === For each of the previous "list" and "glob" methods, there is a corresponding "-Paths" method that returns Path object instances instead of Strings. ; listPaths(path) Array * Path ; listTreePaths(paths) Array * Path ; listDirectoryTreePaths(paths) Array * Path ; globPaths(path) Array * Path === Iterator Objects === ; iterate(path) Iterator * String : returns an iterator that lazily browses a directory, backward and forward, for the base names of entries in that directory. ; iteratePaths(path) Iterator * Path : returns an iterator that lazily browses a directory, backward and forward, for the full Paths of entries in that directory, joined on the given path. Iterator objects have the following members: ; next() String or Path : returns the next path in the iteration or throws a StopIteration if there is none. ; prev() String or Path : returns the previous path in the iteration or throws a StopIteration if there is none. ; iterator() : returns itself ; close() : closes the iteration. After calling close, all calls to next and prev must throw StopIteration. Directory iterators also support the following Array methods: * forEach * map * every * some * reduce * reduceRight == Links == Symbolic and hard links must not be emulated with Windows Shortcuts. ; link(source, target) : [[Filesystem/A/0]] ; hardLink(source, target) : [[Filesystem/A/0]] ; readLink(path) String : [[Filesystem/A/0]] == Tests == ; exists(path) : [[Filesystem/A/0]] ; isFile(path) : [[Filesystem/A/0]] ; isDirectory(path) : [[Filesystem/A/0]] ; isLink(path) : [[Filesystem/A/0]] ; isReadable(path) Boolean : [[Filesystem/A/0]] ; isWritable(path) Boolean : [[Filesystem/A/0]] ; same(source, target) Boolean : [[Filesystem/A/0]] == Attributes == ; size(path) : [[Filesystem/A/0]] ; lastModified(path) Date : [[Filesystem/A/0]] == Extended Attributes (optional) == Extended attribute methods may be defined on systems that may support the feature on some volumes. ; getAttribute(path, key String, default ByteString) ByteString : [[Filesystem/A/0]] ; setAttribute(path, key String, value ByteString) : [[Filesystem/A/0]] ; removeAttribute(path, key String) : [[Filesystem/A/0]] ; discardAttribute(path, key String) : Removes the extended attribute for a given key, if there is a corresponding attribute. ; getAttributes(path) Object : Returns an Object that maps all of the extended attribute keys to their corresponding values. ; listAttributeNames(path) Array * String : [[Filesystem/A/0]] == Security == ; owner(path) String : [[Filesystem/A/0]] ; changeOwner(path, name String) : [[Filesystem/A/0]] ; permissions(path) Permissions : [[Filesystem/A/0]] ; changePermissions(path, permissions Permissions) : [[Filesystem/A/0]] == Paths == ; workingDirectory() String : [[Filesystem/A/0]] ; changeWorkingDirectory(path) : [[Filesystem/A/0]] ; workingDirectoryPath() Path : returns the current working directory as an absolute Path object === Paths as Text === ; join(...) String : takes a variadic list of path Strings, joins them on the file system's path separator, and normalizes the result. [[Filesystem/Join|details]] ; split(path) Array * String : returns an array of path components. If the path is absolute, the first component will be an indicator of the root of the file system; for file systems with drives (such as Windows), this is the drive identifier with a colon, like "c:"; on Unix, this is an empty string "". The intent is that calling "join.apply" with the result of "split" as arguments will reconstruct the path. ; normal(path) String : removes '.' path components and simplifies '..' paths, if possible, for a given path. ; absolute(path) String : returns the absolute path, starting with the root of this file system object, for the given path, resolved from the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result. "absolute" can be implemented in terms of "workingDirectory", "join", and "normal". ; canonical(path) String : [[Filesystem/A/0]] ; readLink(path) String : returns the text of a symbolic link at a given path. Throws a '''TODO''' error if there is no accessible symbolic link at the given path. ; directory(path) String : returns the path of a file's containing directory, albeit the parent directory if the file is a directory. A terminal directory separator is ignored. ; base(path, extension_opt String) String : returns the part of the path that is after the last directory separator. If an extension is provided and is equal to the file's extension, the extension is removed from the result. ; extension(path) String : returns the extension of a file. The extension of a file is the last dot (excluding any number of initial dots) followed by one or more non-dot characters. Returns an empty string if no valid extension exists. [http://github.com/kriskowal/narwhal-test/blob/master/src/test/file/extension.js unit test]. ; resolve(...) : a function like "join" except that it treats each argument as as either an absolute or relative path and, as is the convention with URL's, treats everything up to the final directory separator as a location, and everything afterward as an entry in that directory, even if the entry refers to a directory in the underlying storage. Resolve starts at the location "" and walks to the locations referenced by each path, and returns the path of the last file. Thus, resolve(file, "") idempotently refers to the location containing a file or directory entry, and resolve(file, neighbor) always gives the path of a file in the same directory. "resolve" is useful for finding paths in the "neighborhood" of a given file, while gracefully accepting both absolute and relative paths at each stage. [http://github.com/kriskowal/narwhal-test/blob/master/src/test/file/resolve.js unit test]. ; relative(source, target_opt) : returns the relative path from one path to another using only ".." to traverse up to the two paths' common ancestor. If the target is omitted, returns the path to the source from the current working directory. === Path Type === Path instances inherit from the String prototype. ; [new] Path(path...) Path : returns a Path object. Path is a chainable shorthand for working with paths. Path objects have no more or less authority to manipulate the file system that produces them. If multiple arguments are passed to the Path constructor, they are joined to construct the corresponding path. If an argument is an Array, as ascertained by <code>Array.isArray</code>, it must conform to normal output of <code>split</code>, meaning that if the first value is a drive or root, the components are joined absolutely, and otherwise they are joined relatively. ; path(path...) Path : a shorthand for creating a new Path that does not use the "new" keyword, and also can be more easily applied variadically with the apply and call methods. The path constructor accepts as its first argument either a String, Path, or Array. If the path is an Array (as tested by Array.isArray, not merely typeof path == "array"), it must conform to the specification for values returned by "fs.split". Every path object has the members '''absolute''', '''base''', '''canonical''', '''directory''', '''normal''', and '''relative'''. All of these return new Path objects constructed by converting the path to a string, passing it through the likewise named method of the file system API, and converting it back to a Path. Thus, all of these methods are chainable. In addition, '''join''' and '''resolve''' are variadic, so additional paths can be passed as arguments in either String, Path, or Array form. Every path object has the members '''listDirectoryTreePaths''', '''listPaths''', and '''listTreePaths'''. All of these return objects that provide Path objects constructed by converting the path to a string, passing it through the likewise named method of the file system API, and converting it back to a Path. Every path object has the members '''copy''', '''copy''', '''copyTree''', '''discardAttribute''', '''exists''', '''extension''', '''getAttribute''', '''getAttributes''', '''isDirectory''', '''isFile''', '''isLink''', '''isReadable''', '''isWritable''', '''iterate''', '''iterateDirectoryTree''', '''iterateTree''', '''lastModified''', '''link''', '''linkExists''', '''list''', '''listDirectoryTree''', '''listTree''', '''makeDirectory''', '''makeTree''', '''move''', '''open''', '''read''', '''remove''', '''removeAttribute''', '''removeDirectory''', '''removeTree''', '''removeTree''', '''rename''', '''setAttribute''', '''size''', '''split''', '''symbolicLink''', '''touch''', and '''write'''. All of these functions convert themselves to strings and pass the results through the likewise named method of the file system API. In addition, paths implement: ; toString() : converts the path to its String representation ; to(target) : returns the path from this path to the target. Equivalent to <code>Path(relative(this, target))</code>. ; from(source) : returns the path from the source to this path. Equivalent to <code>Path(relative(source, this))</code>. ; glob(pattern) : returns an Array of path Strings that match the given pattern at this path. ; globPaths(pattern) : returns an Array of Path objects that match a given pattern at this path. = Notes = * Path separator constants are deliberately omitted from this specification to encourage the use of the provided cross-platform methods. * Full Posix stat functionality, including stat, has been left for an exercise for a separate specification. == For Future Versions == * locks * comprehensive stat access and modification * ACLs * temporary files and directories * more open options: permissions, owner, groupOwner * copy with metadata * other [[API/file/Names|proposed names]]. = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/a1b175c20ad61ed7 writ or write?] * [http://groups.google.com/group/commonjs/browse_thread/thread/5ed547baaba11f6c Filesystem API - Hobgoblin of little minds in little bike sheds with little bicycles] * [http://groups.google.com/group/commonjs/browse_thread/thread/eb721e00452c4d02 Filesystem API: stat] * [http://groups.google.com/group/commonjs/browse_thread/thread/abef650ba0c4f76d Filesystem API - Path(path, <nowiki>[fs]</nowiki>)] * [http://groups.google.com/group/commonjs/browse_thread/thread/f71e34667e1d5bde Filesystem API, Pure-JS glob implementation] * [http://groups.google.com/group/commonjs/browse_thread/thread/c4af0c8d278fd34b Return value of return? Partial writing?] * [http://groups.google.com/group/commonjs/browse_thread/thread/c35d10239fade9ab Simplifying core filesystem methods] 41 915 2009-09-10T02:59:11Z Dantman 1 moved [[Filesystem API/Hierarchy]] to [[Filesystem/Hierarchy]] = Filesystem Class Hierarchy = This proposal aims to create a set of classes (in an OOP sense) which would add some structuring (and taxonomy) to the Filesystem API. I believe that this can (and should) be done prior to standardizing every available method, including their names, arguments, return values and exceptions thrown. == Basics == Top-level class is a '''Path'''. This object (<tt>var path = new Path("/etc")</tt>) represents a generic path in a filesystem hierarchy. We are not aware of the underlying representation's properties, type (file/dir/link/pipe/socket/whatever), existence etc. Path acts as an ancestor, offering methods which are commot to all fielsystem objects. For instance, we might have <tt>path.exists(), path.isFile(), path.stat(), path.join("/passwd"), path.delete()</tt> and so on. Then, we have a '''File'''. This class extends Path by adding methods which are specific to files; most notable methods for creation, reading and writing. Similarly, we have a '''Directory''' - File's sibling - which adds (to the Path parent) methods useful for Directory traversal and creation. One can freely extend this, for instance by creating a Symlink class - its parent would be File. Symlink might offer additional funcionality - methods <tt>symlink.follow(), symlink.edit()</tt> etc. Note that neither of these objects guarantees the existence of its underlying filesystem representation. == Examples == # var data = new File("/etc/passwd").open("r").read(); # var data = new Directory("/etc").listFiles(); # var path = new Path("/home").join("ondras"); <br/> assert(path.exists()); # var path = new Path("/a/b/c"); <br/> if (path.isDirectory()) { doSomething(); } == Troubles == There are still several points in this proposal which make me uncomfortable. Perhaps a different point of view or a discussion can make things clear in this area. * It is unclear how should one convert between various Filesystem-related classes. Two solutions come to my mind: *# var dir = new Path("/etc").toDirectory(); *# var dir = new Directory(new Path("/etc/")); Both are problematic. The first one states that a Path should offer toXXX() methods, which is incorrect - as a top class, Path should not depend on existence of any of its descendants. The second way, on the other hand, is less readable. * It is unclear how moving, copying and removing should be implemented. In my original proposal, these are methods of Path object. However, as the real file/directory manipulation might be (in some way) specific to the object in question, it seems logical to have these implemented in each movable/copyable/removable class. 42 1132 2009-09-10T20:31:41Z Dantman 1 == Definition == == Unit Tests == == Show of Hands == '''A''': implicitly uses "normal" to normalize the result, so all empty, ".", and ".." path components are resolved if possible. This is our "normal" definition, which is distinct from "canonical" and "absolute" in that it does not consult the underlying storage or the current working directory. ''for'': <code>join("foo", "..", "bar") == "bar"</code> and <code>join("..", "foo") == "../foo"</code> * Kris Kowal ''against'': <code>join("foo", "..", "bar") == "foo/../bar"</code> * Ash Berlin * Daniel Friesen * Mário Valente * Wes Garland * Zachary Carter '''B''': recognizes and follows absolute paths. ''for'': <code>join("foo", "/bar") == "/bar"</code> (Unix) <code>join("Foo", "c:\\Bar") == "c:\\Bar"</code> (Microsoft) * Kris Kowal * Wes Garland ''against'': <code>join("foo", "/bar") == "foo/bar"</code> * Mário Valente * Zachary Carter * ''Daniel Friesen (fuzzy)'' [[Category:Show of hands]] 43 926 2009-09-10T03:01:54Z Dantman 1 = API and Proposed Names = The following sections are organized with a bullet point per function. Each point includes a specification for the behavior of a given method, intended to be suitable for documentation. Under each definition is a list of potential names for that function, and in bullets beneath that, everyone is encouraged to write their name under their preference. Please feel to leave comments as well. In the next section, "General Preferences", there are several broad sweeping points about whether to use certain conventions in a consistent fashion. All of the name options are intended to conform to the prevalent opinion among those elections. For example, "make" and "create" and "dir" and "directory" are both general preference elections, so if you would prefer "makeDir" over "createDirectory", please vote independently for "make" and "dir" in the general preferences. == File System Object == The "file" module would conform to the File System API, as well as objects returned by "chroot". There is no definitive implementation of a FileSystem class, so "chroot" is the only way to construct new objects that conform to the FileSystem API. In permissive platforms, the "file" module may have direct access to ambient authority through a foreign function interface, or may itself be a dynamically loaded module. In secured platform, the "file" module must copy the properties of "system.fs" onto its exports. In a secure sandbox, the following statements would be equivalent. require('file').open(foo) system.fs.open(foo) Since "fs" must be frozen to be secure, there is no need for the "file" module to assemble aparatus for late binding to "fs" methods. * whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists. If the file is a broken symbolic link, returns false. ** exists(path): *** Kris Kowal *** Wes Garland *** (Python: os.path.exists, Ruby: exist?, exists?, Java: exists, JSExt: access, Spidermonkey: Helma: v8cgi: JSExt: EJScript: Synchronet: exists, jslibs: exist, PHP: file_exists) * whether a symbolic link or file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file, albeit a broken symbolic link, that exists. ** exists(path, true): *** Wes Garland *** Mario Valente ** linkExists(path): *** Kris Kowal ** exists(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.path.lexists) * moves a file from a source to a target path. Both paths are joined on the current working directory. ** move(source, target): ** (Ruby: move, Python: shutil.move, Java: File.renameTo, PHP: rename) * renames a file: receives two paths. The first is a path, joined on the current working directory, that refers to the file to rename. The second argument is a path relative to the former file's fully qualified path. ** rename(path, name): ** should not be included in the spec: *** Kris Kowal ** (Ruby: rename) * copies a file from a source to a target path. Both paths are joined on the current working directory. ** copy(source, target): ** (Ruby: copy, systemCopy, Python:PHP: copy, Unix: cp) * copies a file and its recursive contents to a target path. Both paths are joined on the current working directory. If "synbolicLinks" is truthy, symbolic links in the source tree are represented as symbolic links in the new tree; if falsy, the contents of the linked files are copied to the new tree. If ignore is given, it must be a relation that will receive as its arguments the directory being visited by copytree(), and a list of its contents. Since this is called recursively (or walking an equivalent iteration), the ignore relation will be called once for each directory that is copied. The relation must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ** copyTree(source, target, symbolicLinks = false, ignore = undefined) ** copy(source, target, "recursive") ** copy(source, target, true) ** (Python: copytree) * makes a directory at a given path in the base directory implied by the given path. Throws an exception if the base directory does not exist, or if the given path already exists. ** makeDirectory(path): *** Kris Kowal ** createDirectory(path): *** Mario Valente ** mkdir(path) *** Kevin Dangoor ** (Unix:PHP: mkdir) * creates recursive directories. Makes all intermediate-level directories needed to contain the leaf directory. Throws an exception if the leaf directory already exists or cannot be created. The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. ** makePath(path): *** Kris Kowal ** makeDirectory(path, true): *** Wes Garland ** makeDirectory(path, "recursive"): ** makeDirectory(path, "path"): *** Kris Kowal (as a compromise) ** makeTree(path) ** (Unix: mkdir -p, Ruby: makedirs, mkpath, Python: os.makedirs) ** mkdirs(path) *** Kevin Dangoor ** (PHP: mkdir(path, mode, true)) * removes a file. ** remove(path): *** Kris Kowal *** Tom Robinson *** Kevin Dangoor *** Wes Garland (as a compromise) ** unlink(path): *** Wes Garland ** (Ruby: unlink, delete, Python: unlink, remove, Java: delete, Posix:PHP: unlink, Unix: rm, Spidermonkey: Helma: EJScript: Synchronet: remove, jslibs: Delete) * removes a file or directory and its recursive contents. ** remove(path): ** remove(path, true): ** remove(path, "recursive") ** removeRecursive(path) ** removeTree(path, ignoreErrors = false, onError = undefined) ** (Unix: rm -r, Python: rmtree) * creates a hard link of the source path as the target path. Both paths are joined on the current working directory. ** link(source, target): *** uncontested ** (Python:Ruby:PHP: link, Unix: ln) * creates a symbolic link on a given "target" file name. The source path becomes the text of the symbolic link, which the underlying system will join on the containing directory when it's followed, while the target path is joined on the current working directory. ** symbolicLink(source, target): *** Kris Kowal ** link(source, target, true): *** Wes Garland ** link(source, target, "symbolic"): *** Kris Kowal (as a compromise) ** (Ruby:Python:PHP: symlink, Unix: ln -s) * creates an empty file at a given path in its implied base directory. The path is resolved relative to the current working directory. Accepts an optional ``Permissions`` object (or a duck-type thereof, or the, typically octal, numeric representation of permissions in Unix) that notes which permissions the file will be created with, assuming that those permissions are in the "umask". ** create(path, [permissions]): *** Mario Valente ** unnecessary: *** Kris Kowal, *** Wes Garland ** (Java: createNewFile, Posix: creat, Unix:PHP: touch) * truncates a the file at a given path. Accepts an optional length that default to zero. The path is resolved on the current working directory. ** truncate(path, [length = 0]): ** omit entirely: *** Kris Kowal ** (Ruby: truncate, Python:PHP: ftruncate applies to open files only) * updates the stat/metadata of the file at a given path. Accepts a stat object. Implicitly updates the time that the file's metadata/stat was updated to the current time, regardless of the metadata modification time provided by the stat object. *** Wes Garland ** update(path, stat): ** chstat(path, stat): ** setStat(path, stat): ** restat(path, stat): ** (a low-level alternative to Python's copy2 and copyStat) * updates the modification time of the file at a given path. Accepts an alternate modification time to set the file. Also implicitly updates the time that the file's metadata/stat object was updated to the current time, regardless of the chosen modification time. ** touch(path, [date]): *** Kris Kowal ** (Unix:PHP: touch) * locks the file at a given path with either an exclusive or shared advisory lock. The path is resolved on the current working directory. Blocks until the lock is acquired, or if a timeout is defined, when that timeout occurs. ** lock(path, "shared|exclusive", [timeout=undefined]): *** Wes Garland *** Kris Kowal ** lock(path, "rw|") ** (Posix:Python: lock) * attempts to acquire an advisory lock a file at a given path but does not block. The path is resolved relative to the current working directory. Does not block if the file is not lockable. Returns whether the lock was obtained. *** Wes Garland ** tryLock(path, "shared|exclusive"): ** lock(path, "rw") ** (Python: lock, PHP: flock($handle)) * releases a lock for a given path. ** unlock(path): *** Kris Kowal ** lock(path, "unlock") ** lock(path, "u") ** (Python: lock, PHP: flock($handle, LOCK_UN)) * retrieves an object that represents the metadata of a distinct file, for a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path): *** Mario Valente ** (Python: os.stat, Ruby: File.stat, Posix:PHP: stat) * retrieves an object that represents the metadata of a distinct file or symbolic link to a file at a given path. The path is resolved relative to the current working directory. The returned object has the properties described in the Stat API. ** stat(path, true): *** Wes Garland ** linkStat(path): *** Kris Kowal ** stat(path, "link"): *** Kris Kowal (as a compromise) ** (Python: os.lstat, Ruby: File.lstat, PHP: lstat) * returns the size of the corresponding file. ** size(path) ** (Python: size, Ruby: size?: Java: length, Posix: st_size, PHP: filesize) * returns the total size of a tree of files. ** size(path) // as a special case for a directory ** size(path, "recursive") ** recursiveSize(path) * returns an IO object for accessing or manipulating the data in a file at a given path. The path is resolved relative to the current working directory. The given permissions object may be a Unix numeric representation of permissions, a Stat object, or any object that provides the members of Stat regarding permissions. ** open(path, "+arwxc", permissions, encoding): *** Mario Valente *** Kris Kowal ** Mode: *** +, update *** a, append *** r, read *** w, write *** x, exclusive (lock) *** c, canon (nonblocking) ** (Java: FileStream classes, Python: open, file, Ruby: File.new, universal precedent among SSJS frameworks) ** open([path,] [mode,] {[path: path,] mode: "+arxwc", permissions: permissions, encoding: encoding})<br>(keyword-style parameters, first parameter is path or keyword object containing path) *** Aristid Breitkreuz *** Kris Kowal * return a Dir object for a given directory path. The path is resolved relative to the current working directory. The Dir object is an bidirectional iterator of a snapshot of the contents of the directory, and may be either a lazy Array or genuine array, depending on whether the underlying implementation can retrieve indicies on demand. ** list(path) ** (Python: os.listdir, Ruby: Dir, PHP: dir) * returns an object that, like a Dir, supports the iterator protocol (next, prev) and the Array protocol (length, [index]) for all files that match a given glob pattern. ** The glob pattern may include any of the following productions: *** ? - exactly one character in a path component *** * - any number of characters in a path component *** ** - any number of characters in a path *** {a,b,c} - the letters a, b, or c, or any other union of paths. ** glob(pattern) ** (Ruby: Dir[]) * returns whether a given path matches a glob pattern. ** match(pattern, path) ** (Ruby: fnmatch) * returns a new object that implements the file system API that uses the directory at the given path as its root. Resolves the path relative to the current working directory. ** chroot(path) == Paths == More properites of a FileSystem object. * a string directing a path up to the parent of the current directory, usually '..'. ** PARENT ** (a function that gets an opaque reference to the actual parent node on the file system, as referenced by the directory's parent hard link, has been deliberately omitted to avoid leaking the capability to access that object from within a chroot file system) ** (Python: pardir) * a string directing a path back to itself, usually '.'. ** SELF ** (Python: curdir) * a string that contains the path separator, usually '/', '\', or ':'. ** SEPARATOR ** (Python: sep, Spidermonkey: separator, Ruby: SEPARATOR, Separator) * a string that contains the alternate path separator, if it exists. Otherwise, undefined. ** ALTERNATE_SEPARATOR ** (Python: altsep, Ruby: ALT_SEPARATOR) * a string that contains the extension separator, usually '.'. ** EXTENSION_SEPRATOR ** (Python: extsep) * whether the file system supports unicode file names ** SUPPORTS_UNICODE_FILE_NAMES * accepts a variadic list of paths as arguments and follows each successive path from the current working directory, left to right, and returns the normalized path of the ultimate file or directory. Paths that end with a directory separator refer to the contents of a directory as a place to continue resolving, whereas paths that do not end with a directory separator indicate that the next path should be followed from the directory containing that file. ** join([path, [path, [path, [...]]]]) * returns the path components for a given path ** split(path) * takes a string and returns an escaped path component of that string, such that directory separators and other special characters do not partition it into multiple path components ** escape(string) ** (not precedented) * returns the path of the directory containing a given path. ** dirName(path): *** Kris Kowal ** dirname(path) *** Wes Garland ** (Python: Unix: dirname) * returns the last path component without its extension. The extension begins after the first extension separator. ** baseName(path): *** Kris Kowal ** basename(path): *** Wes Garland ** (Python: Unix: basename) * returns the extension of the given path. The extension begins after the first extension separator. ** extension(path): *** George Mosochovitis *** Kris Kowal *** Wes Garland ** (Ruby: extname) * removes '.' path components and simplifies '..' paths, if possible for a given path. If the file system is case sensitive, transforms all letters to lower-case to make them unambiguous. ** normal(path) ** (Python: normpath) * returns the absolute path, starting with the root of this file system object, for the given path, resolved relative to the current working directory. If the file system supports home directory aliases, absolute resolves those from the root of the file system. The resulting path is in normal form. On most systems, this is equivalent to epxanding any user directory alias, joining the path to the current working directory, and normalizing the result. ** absolute(path) ** (Python: abspath) * returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function may not communicate information about the true parent directories of files in chroot environments. This function is equivalent to expanding an user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result. ** canonical(path) ** (Python: realpath) * returns whether a given path has no self and parent path components. ** isNormal(path) * returns whether the given path is normal and starts with the root of the file system. ** isAbsolute(path) ** (Python: isabs) * returns whether the given path is the same as the corresponding cannonical path. ** isCanonical(path) * returns whether the given paths both refer to the same intrinsic file. Both paths are resolved relative to the working directory. ** same(path, path) == Stat Object == * the Date that the file was last accessed. ** atime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastAccessed: *** Kris Kowal ** (Python: getatime, Ruby: atime) * the Date that the file was last modified. ** mtime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastModified: *** Kris Kowal *** Mario Valente *** Daniel Friessen ** (Python: getmtime, Ruby: mtime, Java: Spidermonkey: Helma: lastModified, jslibs: modifyTime, EJScript: modified, Synchronet: date) * the Date that the file's stat/metadata was last modified. ** ctime: *** Tom Robinson *** Kevin Dangoor *** Ondrej Zara ** lastChanged: *** Wes Garland *** Kris Kowal ** (Ruby: ctime, Python: getctime) * the Date that the file was created, if the underlying file system makes that datum available (most Unix systems do not store creation time, but Windows and some Unix varieties do). Returns undefined if the underlying file system does not provide a time. ** created: ** creationTime: ** firstModified: ** omit entirely: *** Kris Kowal ** (Spidermonkey: jslibs: creationTime, EJScript: create) * a String name for the type of the file. One of: "file", "directory", "characterSpecial", "blockSpecial", "fifo", "link", "socket", or "unknown" ** type: ** kind: ** omit entirely: *** Kris Kowal * whether the corresponding object is a file (not a directory). ** isFile: *** Kris Kowal * whether the corresponding object is a directory ** isDirectory ** (Spidermonkey: isDir, Helma: isDir, JSExt: isdir) * whether the corresponding object is a symbolic link ** isLink * whether the corresponding object is a mount point ** isMountPoint: ** omit entirely: *** Wes Garland *** Ondrej Zara * whether the corresponding object is a socket ** isSocket * whether the corresponding object is a pipe ** isPipe ** isFifo * whether the correpsonding object is a block device ** isBlockDevice * the size of the corresponding object in bytes ** size *** Ondrej Zara ** (jslibs: size, Helma: getLength, Spidermonkey: wxJS: EJScript: Synchronet: length) * the name or id of the owner of the file (following symlinks) ** owner * the name or id of the group owner of the file (following symlinks) ** groupOwner * the name or id of the owner of the file or symbolic link ** linkOwner * the name or id of the group owner of the file or symbolic link ** linkGroupOwner * whether the owner of the process at the time of this stat object's construction is the same as the owner of this file. ** owned * whether the corresponding object can be opened for reading by the current process owner ** isReadable * whether the corresponding object can be opened for writing by the current process owner ** isWritable * whether the corresponding object is an executable for the current process owner ** isExecutable * whether the corresponding executable file will be forced to run as the owner of the file if any user executes it. ** executesAsOwner ** setuid * whether the corresponding executable file wil be forced to run with its group owner if any user executes it. ** executesAsGroupOwner ** setgid * whether the corresponding directory will permit anyone to create files in it, but only let the owner of a file delete it. ** sticky * an object that represents the permissions granted to the owner of the file. ** This object would contain: *** isReadable *** isWritable *** isExecutable ** ownerPermissions * an object that represents the permissions granted to the group that owns the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** groupPermissions * an object that represents the permissions granted to anyone who has no claim to the file. ** The object would contain: *** isReadable *** isWritable *** isExecutable ** worldPermissions * returns an object that represents the permissions granted to the user corresponding to a particular name or identifier. ** The returned object would contain: *** isReadable *** isWritable *** isExecutable ** getPermissions(user) * the inode/vnode number of the underlying object (optional) ** inode * the device number of the underlying object (optional) ** device == File Object == File objects can only be constructed by methods of FileSystem objects. Different IO types might be returned for calls to open with different modes, generally following the protocol outlined in Python's PEP 3116. == IO Objects == * reads as many bytes as are available from an IO stream and returns the number of actually read bytes. ** read() * reads as many bytes as are available but less than a given number from an IO stream and returns the number of actually read bytes. ** read(n) * reads a line of characters from a line buffered IO object. Returns a blank line on EOF. ** readLine() ** (Python: JSExt: readline, Spidermonkey: Helma: Synchronet: readln) * returns an Array-like view of the lines in an IO stream, or simply an Array of Strings. ** readLines() ** (Python: readlines, JSExt: readlines, EJScript: getLines) * returns the next line in the stream. Throws a StopIteration exception on EOF. ** next() * returns an iteration on the lines of the IO stream, which is simply itself since it implements "next". ** iter() * calls a relation with each line of input from the IO stream. ** forEach(relation) * reads bytes into a buffer, up to as many as the length of the buffer, pending availablility. Returns the number of bytes actually read. ** readInto(buffer) * writes bytes to a stream. Returns the number of bytes that were actually written. ** write(buffer) * moves the position of the cursor in a random access IO stream. ** Accepts a code that determines whether to move the position relative to the beginning, end, or current position: *** 0 or "begin": beginning of file (default) *** 1 or "relative": current position *** 2 or "end": end of file ** seek(pos, whence) ** (universal precedent) * returns the current position of the random access cursor for an IO stream. The position may be a "cookie" object or a Number, depending on the IO type. ** tell() ** (wxJS: JSExt: Python: Ruby: tell) * truncates the size of a file to the current cursor position or a given position, which must be either a "cookie" object or a Number, depending on the IO type. ** truncate(pos) ** (Ruby: truncate, Python: ftruncate) * returns whether the cursor is at the end of the IO stream. ** eof() *** Kris Kowal ** atEOF(): *** Wes Garland (non-commital) ** (Helma: wxJS: JSExt: Synchronet: eof) * flushes buffers for an IO stream ** flush() ** (universal precedent) * blocks until an advisory lock is acquired. Throws an error if a lock cannot be acquired on the system. ** lock("exclusive|shared") * tries to grab an advisory lock without blocking, and returns whether it succeeded. ** tryLock("exclusive|shared") ** (related to isOpen in many existing SSJS frameworks, but without a race condition hazard) * releases an advisory lock. ** unlock() * closes a stream ** close() * whether the IO stream is readable ** isReadable * whether the IO stream is writable ** isWritable * whether the IO stream supports random access ** isSeekable * whether the IO stream is attached to a virtual or real teletype. ** isTTY: *** Wes Garland ** isTty: *** Kris Kowal * the descriptor of the underlying file, an opaque reference to the file descriptor, or undefined if file descriptors are not supported. ** fileNo * the underlying unbuffered IO stream, if it exists. Otherwise undefined. ** raw * creates a duplicate of the IO stream, with its own buffereing and cursor. ** copy() *** Kris Kowal ** dup() = Notes for Further Discussion = * input, output, stdin, stdout, STDIN, STDOUT * ...placed on environment or in a module? * separation of knowledge of paths between file system and files * currentDirectory, getCurrentDirectory * temporary files and directories * opening a temp file with an implied immediate exclusive lock * dup and dup2 and other file-descriptor specific constructs for permissive environments. * canRead, canWrite, poll, select * taxonomy of IO classes * default encoding for String, line-buffered IO = General Preferences = # make vs. create #* make: #** Mario Valente, #** Wes Garland (but only for directories) #** Kris Kowal (but only for directories) #* create: #** George Moschovitis, #** Wes Garland (but only for files) #** Kris Kowal (but only for files) #** Ondrej Zara # dir vs. directory #* directory: #** Tom Robinson, #** Kevin Dangoor, #** George Mosochovitis, #** Wes Garland #** Ondrej Zara #* dir: #** Mario Valente # cur vs. current #* current: #** Tom Robinson, #** Kevin Dangoor, #** Wes Garland, #** Kris Kowal, #** Mario Valente #** Ondrej Zara #** George Moschovitis #* cur: # canonize, realize, normalize, qualify, cannon, real, normal, qualified, absolute, cannonicalize #* remove . and ..: #** normalize: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis #** qualify: #*** Wes Garland #** expand: #*** Ondrej Zara #* remove . and .., start at /: #** absolute: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal, #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente #** qualified: #*** Wes Garland #** normalize: #*** Ondrej Zara #* remove . and .., start at /, follow symlinks: #** canonical: #*** Tom Robinson, #*** Kevin Dangoor, #*** Kris Kowal #** absolute: #*** George Mosochovitis, #*** Wes Garland, #*** Mario Valente, #** real: #*** Tom Robinson, #*** Kevin Dangoor #** qualified: #*** Wes Garland # constantCase, CONSTANT_CASE, kConstantCase #* CONSTANT_CASE: #** Tom Robinson, #** Kevin Dangoor #** Ondrej Zara #** George Moschovitis #* constantCase: #** Kris Kowal, #** Wes Garland, #** Mario Valente, # "static" methods #* require(module).staticMethod: #** Kris Kowal #** Wes Garland #** Mario Valente #** Ondrej Zara #* require(module).Klass.staticMethod: #** Tom Robinson #** George Mosochovitis # properties, accessors, mutators #* foo.setX(x); foo.getX() #** For: #** Against: #* foo.setX(x); foo.X() #** For: #** Against: #* no convention #** For: #** Against: #* foo.x = x; foo.x #** For: #*** Davey Waterson #*** Wes Garland #*** Daniel Friesen #*** Sam Phillips #** Against: #*** Tom Robinson #*** Kris Kowal = References = ; http://www.python.org/dev/peps/pep-3116/: PEP on new File IO ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html: Java File API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileOutputStream.html: Java Output API ; http://java.sun.com/j2se/1.4.2/docs/api/java/io/FileInputStream.html: Java Input API ; http://www.erights.org/javadoc/java/io/File.html: E Secure File API ; http://www.cs.berkeley.edu/~daw/joe-e/api/org/joe_e/file/Filesystem.html: Joe-E Secure File System API ; http://docs.python.org/library/os.path.html: Python Path API ; http://www.ruby-doc.org/core/classes/File.html: Ruby File API ; http://www.ruby-doc.org/core/classes/IO.html: Ruby IO API ; http://spreadsheets.google.com/pub?key=p9uiX8MUHeTiP0kPT591RUw: A matrix of existing CommonJS File API nomenclature and support [[Category:Show of hands]] 44 2343 2010-03-13T21:48:28Z Dantman 1 Reverted edits by [[Special:Contributions/Rezelyn|Rezelyn]] ([[User talk:Rezelyn|Talk]]) to last revision by [[User:Dantman|Dantman]] ;.write operations on a stream: :A.1) May do partial writes and return the data that has not yet been read. :A.2) May do partial writes and return the length of data that has been written. :* Wes Garland :B) Block until all the data has been written to the underlying layer (partial writes may be handled with a different method or options; unspecified atm). :* Daniel Friesen :* Kris Kowal :* Tom Robinson :* Kevin Dangoor :* Joshaven Potter === Notes === * Kris Kowal thinks that B).write should return `this` to allow chaining. [[Category:Show of hands]] 45 1089 2009-09-10T20:14:11Z Dantman 1 moved [[CommonJS/Future Efforts]] to [[Future Efforts]] 46 2566 2010-04-06T19:36:24Z Alexandre.Morgaut 33 /* Requirements/Proposals */ = HTTP Client API = Server side programs often need to grab information via HTTP. There should be an API that makes this as easy as possible. There are certainly other protocols that deserve support, but each protocol has its own purpose and interface and will be documented separately if it will become part of the stdlib. == Requirements/Proposals == * [[HTTP Client/A|HTTPClient Proposal A]] * [[HTTP Client/B|HTTPClient Proposal B]] based on XMLHttpRequest == Prior Art == * [http://www.w3.org/TR/XMLHttpRequest/ XMLHttpRequest] is already the standard JS API for HTTP. * [http://www.w3.org/TR/XMLHttpRequest2/ XMLHttpRequest level 2] is the Draft for the next version of this standard JS API. * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/ejs.io-Http.html Here] is an extended HTTP API from Ejscript. * v8cgi has a [http://code.google.com/p/v8cgi/wiki/API_HTTP HTTP] class * Helma has a ([http://helma.zumbrunn.com/reference/helma.Http.html HttpClient]) * Wakanda has [http://www.w3.org/TR/XMLHttpRequest/ XMLHttpRequest] with parts of [http://www.w3.org/TR/XMLHttpRequest2/ XMLHttpRequest Level 2] * Ajax.org O3 SSJS API has XMLHttpRequest * XMLHttpRequest is being implemented for gpsee and flusspferd 47 1065 2009-09-10T19:59:52Z Dantman 1 moved [[CommonJS/HTTP Client/A]] to [[HTTP Client/A]] Proposal A, Draft 1 '''Status: Proposal''' The "http-client" module exposes an HTTPClient constructor that creates an HTTP Client object. == Constructor: HTTPClient(settings) == If called as a simple function, then return a new HTTPClient(settings). Set all protected members to the default values. If a settings object is included, call this.set(settings). == Object Methods == All methods return "this" except where otherwise specified. === set([settings object | key, value]) === Set the body, headers, method, or url, or any combination thereof in the settings object. Attribute validity is enforced (see valid settings on members, below.) === setHeader(key, val) === Set a header on the header object in a case-insensitive manner. That is, if the user sets "content-type", and then later sets "Content-Type", then the first setting is lost. === setHeaders(headers:Object) === Set a bunch of headers expressed as name-value pairs. === write(data:toByteString-able) === Append data to the outgoing request. (That is, to the iterable body object.) Implementers MAY require the body object to expose a push() method, and call this push() method to append data to the request. === connect() === Open the connection to the URL using the method supplied. If the method or url is missing, throw an error. After connecting, write() will have no effect. Calling connect() SHOULD NOT block the application, but MUST initiate the HTTP request. === read() === Read the request and return a JSGI-style object consisting of <code>{status:Integer, headers:Objecct, body:Iterable<ByteString>}</code>. Calling read() SHOULD NOT block the application until the request is completed, but it MUST open the input stream such that the data can be read. === finish() === Alias for .connect().read() == Static Methods == === decode(response[, encoding]) === Return a response object where the body has been wrapped in a decoder middleware. For example: <pre>resp.body = {forEach : function (block) { raw.forEach(function (i) { block(i.decodeToString(encoding)); }); }};</pre> Make a best-guess attempt to determine the appropriate encoding based on the response headers if no encoding is specified. The ultimate fallback encoding SHOULD be UTF-8. === unDecode(response) === Replace the decoded body with the original body. This is useful when the decoded content is clearly invalid and the consumer wants to backtrack. == Members == All members below are required and SHOULD be protected. === body === An iterable (that is <code>forEach</code>-able) object where forEach iterates over items with a <code>toByteString</code> method. Implementers MAY require that the body member expose a <code>push</code> method in order for the write function to operate properly. Default value: [] === headers === A hash of request headers. Care SHOULD be taken to ensure that keys are added in a case-insensitive manner. Default value: {"X-Requested-With" : "CommonJS HTTP Client"} === method === The request method as a string. Default value: "GET" === url === URL as a string Default value: none == Example Implementation == * Isaac's Narwhal fork: [http://github.com/isaacs/narwhal/blob/master/lib/http-client.js code], [http://github.com/isaacs/narwhal-playground/blob/master/http-client.js usage], [http://github.com/isaacs/narwhal-playground/blob/master/http-client-blocking-test.js concurrent demonstration] 48 1077 2009-09-10T20:00:42Z Dantman 1 moved [[CommonJS/High Level Tools]] to [[High Level Tools]] The point of everything above is to make it easier for higher level tools to be reliably built out of more reusable parts and for the higher level tools to work on more platforms with less redundant work. (This is a fine place to link up higher level web application frameworks). 49 2543 2010-03-31T10:07:10Z Hannesw 10 '''STATUS: PROPOSALS, DISCUSSION''' The purpose of this proposal is to create a unified interface for stream-like objects in JavaScript. This specification was originally part of the [[Filesystem|FileSystem API]] and has been extracted to provide a common API for other I/O related modules. == Proposals == * [[IO/A|I/O Proposal A]] - [[User:Hannesw|Hannes Wallnöfer]] * [[IO/B|I/O Proposal B]] - [[User:Dantman|Daniel Friesen]] * [[IO/C/Stream|IO Stream Proposal C]] - Michael O'Brien == Inspirations and Prior Art == The [[Filesystem|FileSystem API]] page contains an extensive list of existing I/O related APIs. == Discussion == * [http://groups.google.com/group/commonjs/browse_thread/thread/d7661cde0b631bf I/O proposal first draft Options] * [http://groups.google.com/group/commonjs/browse_thread/thread/6cce4e4730c35651 The case for a dedicated I/O spec] 50 1573 2009-10-04T12:08:06Z KrisKowal 6 /* Notes */ ''Second draft. See [[IO/A#Notes|Update Notes]] below for changes from first draft'' This document describes an interface for reading and writing stream of raw bytes, and classes built on top of it to provide string based reading and writing. This specification refers to the ByteString and ByteArray classes defined in the [[Binary/B]] proposal, but it should be easy to adapt it to any definition of binary buffers or arrays. = Specification = Platforms implementing this specification must provide a top level '''io''' module. The io module must export the classes and interfaces described below. == Raw I/O == === Stream === The Stream class implements a I/O stream for reading and writing raw bytes. ===== Constructor ===== Whether the Stream class provides a public constructor, and what the arguments of the constructor are, is not part of this specification. The process of creating actual Stream objects is implementation specific. Various built-in modules such as the [[Filesystem|file module]] will know how to build native Stream objects in a platform specific way. Application classes should be able to extend the Stream class through JavaScript prototype chaining. However, duck typing should also work for Stream objects, meaning that any object implementing the Stream interface ''should'' work for code expecting an io.Stream object. ===== Instance Properties ===== '''''Note''': the length and position properties are used to implement random access streams traditionally implemented using the tell()/seek()/truncate() protocol. The rationale for departing from that nomenclature is that this puts stream more in line with other core objects such as String and Array. Also, random access streams are not often used in day-to-day programming, so these properties may most commonly be used for in-memory stream implementations, where they should fit in nicely.'' ;length Number :The length of the stream, in bytes. This property is only defined for seekable streams, and is only writable for streams that are both seekable and writable. Decreasing the length property of a stream causes the stream to be truncated. Increasing the length of a stream causes the stream to be extended. The content of the extended section of the stream are not defined. Accessing this property may throw an error if the underlying operation did not succeed. ;position Number :The position within the stream at which the next read or write operation occurs, in bytes. This property is only defined for seekable streams. Setting it to a new value moves the stream's positon to the given byte offset. Accessing this property may throw an error if the underlying operation did not succeed. ===== Instance Methods ===== ;read([n Number]) ByteString :Read up to n bytes from the stream, or until the end of the stream has been reached. In n is null, reads up to the block size of the underlying device, or up to 1024 bytes if the block size is not discernible. If n is not specified, this method always reads the full stream until its end is reached. An empty ByteString is returned when the end of the stream has been reached. Throws an error if the operation could not be completed. ;readInto(buffer ByteArray, [begin Number], [end Number]) Number :Read bytes from the stream into the ByteArray buffer. This method does not increase the length of the ByteArray buffer. Returns the number of bytes read, or -1 if the end of the stream has been reached. '''''Note''': Could we safely return 0 on EOF?'' ;skip(n Number) Number :Try to skip over n bytes in the stream. Throws an error if the operation could not be completed. ;write(b Binary, [begin Number], [end Number]) :Write bytes from b to the stream. If begin and end are specified, only the range starting at begin and ending before end are written. Throws an error if the contents of b couldn't be written to the stream. ;copy(target Stream) :reads from this stream with <code>read(null)</code>, writing the results to the target stream and flushing, until the source has been exhausted. Throws a '''TODO''' error if the target closes before the source has been exhausted. ;readable() Boolean :Returns true if the stream supports reading, false otherwise. ;writable() Boolean :Returns true if the stream supports writing, false otherwise. ;seekable() Boolean :Returns true if the stream supports the length and position properties, false otherwise. '''''Note''': we're not impelementing seek(), so should we find another term for this, too? 'positionable' comes to mind, but feels slightly awkward.'' ;closed() Boolean :Returns true if the stream is closed, false otherwise. ;flush() :Flushes the bytes written to the stream to the underlying medium. Throws an error if the operation did not succeed. ;close() :Closes the stream, freeing the resources it is holding. Throws an error if the operation did not succeed. == Text I/O == === TextStream === The TextStream class wraps a raw stream and exposes a similar interface as the Stream class, but its write() method takes a string as first arguments and its read() method returns a string. Additionally, it defines the properties and methods listed below. ===== Constructor ===== ;[new] TextStream(raw Stream, [options Object]) TextStream :Build a TextStream around a raw byte stream. The options argument may contain the following properties: * charset: a string containing the name of the encoding to use * newline: a string containing the newline character sequence to use * delimiter: a string containing the delimiter to use in print() ===== Instance Properties ===== ;raw :A readonly property containing the raw byte stream wrapped by this text stream. ;buffer :A readonly property containing the buffer used internally by this text stream, if it is buffered. This property may be undefined. ===== Instance Methods ===== ; readLine() String : Reads a line from the reader. If the end of the stream is reached before any data is gathered, returns an empty string. Otherwise, returns the line including the newline. Throws an error if the operation did not succeed. ; readLines() Array*String : Returns an Array of Strings accumulated by calling readLine until an empty string turns up. Does not include the final empty string, and does include newline at the end of every line. Throws an error if the operation did not succeed. ; next() String throws StopIteration : Returns the next line of input without the newline. Throws StopIteration if the end of stream is reached. Throws an error if the operation did not succeed. ; iterator() Iterator : Returns the reader itself. ; writeLine(line String) : Writes line followed by a newline. Throws an error if the operation did not succeed. ; print(...) : writes a delimiter delimited array of values as Strings terminated with a newline, then flushes. Throws an error if the operation did not succeed. ;copy(target Stream) :reads from this stream with <code>readLine()</code>, writing the results to the target stream and flushing, until the source has been exhausted. Throws a '''TODO''' error if the target closes before the source has been exhausted. = Notes = * This proposal does not describe non-blocking I/O, nor does it describe buffered I/O. These may be introduced in a later revision of the spec, possibly in conjunction with a Socket API. Platforms are free to implement non-blocking and buffered I/O in their own specific way. * Text streams need read() for read-all ~KrisKowal * Daniel Friesen recommended read(Infinity) instead of read(null), sounds good to me. ~KrisKowal == Changes from First Draft == ; Removed Memory based I/O section. : I realized how easy it is to build a stream interface to the existing binary specification, so in the interest of a simple spec I think it's best to leave that part to implementors for now. ; Removed IOError section but added notes about which methods can throw errors. : Introducing a new error class in a module may be tricky as error classes should be global and immutable to allow instanceof checks. Instead, defining what methods can throw errors under what circumstances seems more important at this stage. ; Removed readAll() method : Folded the functionality into read() being called without argument. ; write() no longer returns the number of bytes written : If the method terminates without throwing an exception it means that all bytes passed to it were written to the stream. 52 1208 2009-09-12T02:30:32Z Dantman 1 Robot: Automated text replacement (-CommonJS/ +) * [[Packaging|Code packaging, installation and deployment]] * [[Doctools|Documentation tools]] 53 839 2009-09-10T02:14:52Z Dantman 1 moved [[CommonJS/Introduction]] to [[Introduction]] Server side JavaScript has been around for a long time, and potentially offers some unique and interesting advantages over other languages because the same language is spoken by both client and server. http://philip.greenspun.com/wtr/livewire.html http://docs.sun.com/source/816-6411-10/contents.htm Unfortunately, though, server side JavaScript is very fragmented. A script that accesses files can't be used without modification on both rhino and v8. Spidermonkey and JavaScriptCore can't both load in additional modules in the same way. A JavaScript web framework is very much tied to its interpreter and is often forced to create a bunch of APIs that Python, Ruby and Java programmers take for granted. The goal for this project is to create a standard library that will ultimately allow web developers to choose among any number of web frameworks and tools and run that code on the platform that makes the most sense for their application. This group/project was initially introduced in a blog posting: [http://www.blueskyonmars.com/2009/01/29/what-server-side-javascript-needs/ "What Server Side JavaScript Needs"] * [http://steve-yegge.blogspot.com/2008/10/universal-design-pattern.html#JavaScript Javascript @ "The Universal Design Pattern"] * [http://developer.mozilla.org/En/Server-Side_JavaScript/Walkthrough Back to the Server: Server-Side JavaScript On The Rise] * [http://steve-yegge.blogspot.com/2007/02/next-big-language.html The Next Big Language] * [http://bannister.us/weblog/2006/12/19/revisiting-server-side-javascript/ Revisiting serverside Javascript] * [http://softwareas.com/server-side-javascript-hope-and-opportunity Server-side Javascript: Hope and opportunity] * [http://mv.asterisco.pt/cat.cgi?A%20Future%20Web%20Development%20Framework%20-%20Application%20Logic A Future Web Development Framework App Logic] 54 1993 2010-01-15T11:00:01Z Alexandre.Morgaut 33 Wakanda use console.log A standard logging API has proven to be useful in many languages. This is especially true for server side environments where things are often running unattended (unlike client side work, where you are personally actively using the code that is doing the logging). == Prior Art == The standard logging API in the browser is one option: console.log(...); console.debug(...); ... Current server-side APIs: * [http://docs.persvr.org/documentation/server-side-js Persevere also uses this standard console API] for JavaScript logging. I believe Jaxer may provide this API as well. * [http://www.wakandasoftware.com Wakanda] use this standard console API * Synchronet has a global log() method which allows logging of messages to consoles, files, etc. using the 8 standard Unix syslog severity levels: http://synchro.net/docs/jsobjs.html#global * Blackbird offers a dead-simple way to log messages in JavaScript http://www.gscottolson.com/blackbirdjs/ * XBug the Javascript debugger http://www.xbug.co.uk/ * NitobiBug a browser-based JavaScript object logger and inspection tool http://www.nitobibug.com/ * [http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html Java Logging] is based on the pattern established by log4j to provide flexible logging. 55 2873 2010-08-02T16:59:43Z Sallamar 128 Removed a spam link '''STATUS: [[/1.1|1.1]] RATIFIED''' == Modules == To date, client side JavaScript has generally been able to get away with something as simple as the <script> tag and no standard way to do namespaces. On the server, it's a bit different because you're more likely to use more libraries and you can potentially load up a lot of code. Having a basic system for loading code and encouraging the use of namespaces to avoid unintentional interference will underlie everything else. === Specifications === * [[/1.0|1.0]] * [[/1.1|1.1]] ([[/1.0|1.0]] + [[/Meta|Module Meta-object Amendment]]). * [[/1.1.1|1.1.1]] relaxes details for "main" and enumerability requirements. ** version 1.1.1 will need spec tweaks and more work: there has been discussion/argument over the behaviour and formation of module.id, one side going for invariance based on path relative to search paths, the other going for absolute file path, since the top level id is dependent on the require.paths at the time of module load. There is also discussion about what we should and shouldn't allow as an argument to require, particularly about camelCase (which not many platforms mandate) and about file extensions. === Proposals === Several proposals were made. There was convergence toward the [[Modules/SecurableModules|Securable Modules]] proposal, with several implementations passing the unit tests. # [[Modules/GlobalFileLoading|Global File Loading]] # [[Modules/GlobalObjectLoading|Global Object Loading]] # [[Modules/PythonicModules|Pythonic Modules]] # [[Modules/SecurableModules|Securable Modules]] There are also proposals for amendments and supplements to these proposals: # [[Modules/Meta]] ratified and incorporated into [[Modules/1.1]]. # [[Modules/Loaders]] for module loader specification proposals # [[Modules/Transport]] for module transport format proposals (for a module format suitable for browser script injection) # [[Modules/SetExports]] function for exporting something other than a plain object. # [[Modules/Async/A]] proposes async loading. # [[Modules/Metadata]] proposes JSON metadata. We need proposals for: # A module-relative "resource" object, like <code>module.resource(path).open(…)</code>. # To fix the module identifier domain. The current specification restricts module identifiers to camelCase delimited by slashes, but this is hazardous in case-insensitve stores, and not restricted in practice. # A page for discussing a system for injecting free variables from the exports of a foreign module # <code>module.setExports(exports) exports Object</code> === Prior Art === * Spidermonkey (and Jaxer) and Rhino offer a [https://developer.mozilla.org/En/SpiderMonkey/Introduction_to_the_JavaScript_shell load] function, but does not have any specific pattern for namespacing. * Dojo has a complete incremental loading facility in the form of [http://dojotoolkit.org/book/dojo-book-0-9/part-3-programmatic-dijit-and-dojo/functions-used-everywhere/dojo-require dojo.require] and a standard mechanism for declaring modules. dojo.require ensures that the module is loaded only once. It also manages dependecies between modules. * The Jack project [http://github.com/tlrobinson/jack/blob/54a28398425287bddd9466955d5e8ea616eb8d47/core.js implements a simple "require" system]. * [http://docs.persvr.org/documentation/server-side-js Persevere uses "require"] (similar to Jack) for module loading. * RingoJS implements a [http://ringojs.org/wiki/Modules%20and%20Scopes/ module system with per-module scopes] and import, include and require functions. * jslibs bootstrapping jshost provides only basic code and loading module support, direct from file and either into the global namespace or a chosen namespace http://code.google.com/p/jslibs/wiki/jshost * Advanced JavaScript Importing & Loading Extension is the browser-independent extension that provides Javascript with namespace and dynamic script loading support ( http://ajile.iskitz.com/ ) * modulesjs an XHR JS module loader provides module loading, singleton modules ( http://modulesjs.com/ ) * [http://synchro.net/ Synchronet] provides a global load() method which allows a specified scope/sandbox object, passing arguments, and background/concurrent execution: http://synchro.net/docs/jsobjs.html#global * [http://www.ejscript.org/ Ejscript] has a loadable module mechanism based on language extensions "module" and "use module" definitions. Modules can have scope, dependencies, incremental loading and optional backing native code. * [http://torino.sourceforge.net Torino] implements a C-style "#include" preprocessor which is intended to provide a low-level loading mechanism on top of which more sophisticated module management schemes can be implemented in JavaScript. * [http://wiki.eclipse.org/E4 Eclipse E4] is doing work using Rhino to support writing modular [http://wiki.eclipse.org/E4/JavaScript JavaScript bundles] that can interoperate cleanly with the OSGi modularity layer used by Java plugins in the platform. === Related Discussions === * [http://groups.google.com/group/commonjs/browse_thread/thread/d761996c25769e6c a module system (difficult to agree)] * [http://groups.google.com/group/commonjs/browse_frm/thread/b99a5b6eb9ed8a23 Concerns about the proposed module system(s)] * [http://groups.google.com/group/commonjs/browse_frm/thread/2dcfbff6b6ba5928 do we need a Module object instead of require() function?] * [http://groups.google.com/group/commonjs/browse_frm/thread/1abef605cf13c337 Are we agreed on require, in general?] * [http://groups.google.com/group/commonjs/browse_thread/thread/f2447ac0d593ad47 SecurableModules question] * [http://groups.google.com/group/commonjs/browse_thread/thread/5dc7db5ceeb1422a Do you think require() should be implemented in JS?] * [http://groups.google.com/group/commonjs/browse_thread/thread/d2dc85a2725992be Securable Modules show of hands] * [http://groups.google.com/group/commonjs/browse_thread/thread/c7016998d1087b5e Secureable Modules: "exports" vs "this"] * [http://groups.google.com/group/commonjs/browse_thread/thread/e2258194f110eda2 SecurableModules: Namespacing, version numbers] * [http://groups.google.com/group/commonjs/browse_thread/thread/d3dc1c0acd89dae5 Global Free Variable] * [http://groups.google.com/group/commonjs/browse_thread/thread/54f089cc4a4bd69e Modules 1.2 Agenda] 56 2668 2010-04-16T12:13:11Z Jhuni 106 Standard identation is four spaces, not two, that way you can line up var statements. <source> // ================================================================== // browser code in development // locked into on of these options // // 1) using a special XHR synchronous script loader and // a) seeing poor error messages with strange line numbering // not corresponding with source code line numbering or // b) using a JavaScript interpreter written in JavaScript // to execute the code retrieved by the XHR. Line numbers // would then correspond to source code line numbers. // (Seems like an extreme solution.) // // 2) edit-compile-load-test cycle using the code below. Also // strange numbering in error messages that does not match // source files. Tools could make compile automatic but that // means tools are required and that is not the case in // the current browser scripting world. // ================================================================== // compiled for production in browser // // library.js // var require = (function() { // memoized export objects var exportsObjects = {} // don't want outsider redefining "require" and don't want // to use arguments.callee so name the function here. var require = function(name) { if (exportsObject.hasOwnProperty(name)) { return exportsObject[name]; } var exports = {}; // memoize before executing module for cyclic dependencies exportsObject[name] = exports; modules[name](require, exports); return exports; }; return require; })(); var run = function(name) { require(name); // doesn't return exports }; var modules = {}; // // compiledModules.js // modules["math"] = function(require, exports) { exports.add = function() { var sum = 0, i = 0, args = arguments, l = args.length; while (i < l) { sum += args[i++]; } return sum; }; }; modules["increment"] = function(require, exports) { var add = require('math').add; exports.increment = function(val) { add(val, 1); }; }; modules["program"] = function(require, exports) { var inc = require('increment').increment; var a = 1; inc(a); // 2 }; // // html in document head // <script src="library.js" type="text/javascript"></script> <script src="compiledModules.js" type="text/javascript"></script> <script type="text/javascript"> // You might not use use the window.onload property // but rather addEventListener/attachEvent. window.onload = function() { run("program"); }; </script> 57 1210 2009-09-12T02:30:52Z Dantman 1 Robot: Automated text replacement (-CommonJS/ +) Moved to [[Modules/Loaders]]. 58 1819 2009-12-02T22:52:38Z KrisKowal 6 Noted that this proposal is no longer being pursued. '''STATUS: PROPOSAL, NO LONGER BEING PURSUED, SEE [[Modules]]''' The following is a simple system based on loading files by filename. This is quite Ruby-like. <source> // // Evaluate the content of the fully specified file // in the global scope. // load('/usr/local/lib/js/File.js') // // If no file extension is included '.js' is assumed // load('/usr/local/lib/js/File') // // Searching through the library path. // Suppose the path is // /home/peter/js:/usr/local/lib/js:/usr/lib/js // load('File') // // Use 'load' above only if this file has never been // loaded before. // load.once('File') // // Load a file relative to the current file's path. // '__DIR__' is a macro expanded to the file's absolute path // before the code is evaluated. It may be that __DIR__ is // expanded to be something like // // /home/peter/src/foo-project // // This allows for one file to load many others distributed // in the same package. // // web-framework.js // web-framework/ // routing.js // templates.js // orm.js // // This does not cross over to the browser as the browser does // not have macros. // load(__DIR__+'subdir/foo'); </source> Remark: the __DIR__ macro is not necessary: the JS intepreter can as well do a chdir() to the directory of a script being loaded, effectively setting a new base path for consecutive relative includes. Remark: I think chdir() is not a good option here because if one module does chdir to include other modules which also do chdir(), then chdir() is required before every individual "load". Otherwise the current directory is basically unknown to any particular script. -- Peter Michaux Remark: What about using the same schematics as CSS files? All references to external resources are always relative to the current file location. -- Jonas == sample code == <source> // ================================================================== // source code ------------------------------------------------------ // // base.js // var LIB = {}; // // math.js // require('base'); LIB.add = function() { var sum = arguments[0]; for (var i=1; i<arguments.length; i++) { sum += arguments[i]; } return sum; }; // // increment.js // require('base'); require('math'); LIB.increment = function(val) { return LIB.add(val, 1); }; // // program.js // require('increment'); var a = 1; LIB.inc(a); // 2 // ================================================================== // browser code in development // // *Can* manually include all dependencies like the following. // Other more complex techniques for manual dependency resolution // can be used. // <script type="text/javascript">require=function(){}</script> <script src="/js/src/base.js" type="text/javascript"></script> <script src="/js/src/math.js" type="text/javascript"></script> <script src="/js/src/increment.js" type="text/javascript"></script> <script src="/js/src/program.js" type="text/javascript"></script> // =================================================================== // browser code in production // // Can just concatenate the source files and perhaps minify them. // Other more complex techniques can be used. // <script type="text/javascript">require=function(){}</script> <script src="/js/lib.js" type="text/javascript"></script> <script src="/js/program.js" type="text/javascript"></script> </source> 59 1820 2009-12-02T22:57:03Z KrisKowal 6 Updated status. '''STATUS: PROPOSAL, NO LONGER BEING PURSUED, SEE [[Modules]]''' A system similar to the simple file loading as file content is still evaluated in the global scope; however, this system depends on a naming convention between file and object names. This makes it a bit more Java-like and is more heavily dependent on the library path. It removes the need to think about a file system and makes it possible to use the same system in the browser. <source> // // Searching through the library path. // Suppose the path is // /home/peter/js:/usr/local/lib/js:/usr/lib/js // Then if can evaluate the content of the file // /usr/local/lib/js/io/File.js in the global scope // with load('io.File') // // Use 'load' above only if this file has never been // loaded before. // load.once('io.File') </source> 60 1751 2009-11-22T03:20:45Z KrisKowal 6 moved [[Modules/Loaders]] to [[Modules/Loaders/A]]:&#32;out of the way! '''There has been no discussion of this proposal.''' Sandboxes have a very simple design and do not benefit greatly from customization for particular sandbox varieties, apart from using more advanced data structures to map interesting module identifiers to their corresponding objects. However, loaders perform a great deal of heavy lifting that can be customized for various kinds of secure and insecure sandboxes, with various kinds of storage and retrieval for module texts. This proposal includes the names that a module author may be able to use for particular load implementations and the corresponding behavior and interface they can expect when using those member functions. Any members of a specified object (including modules, or enumerated argument options) that are not reserved by the specification must be named with "x" as their first term and a vendor-specific label as their second term, like "require.xChironCurryId" or "system.xCajaDomita". == The Require Function/Object == * id: the "require" object MAY have an "id" member that must be the normalized identifier of the current module * loader: the "require" object MAY have a "loader" member that is an interface to the object used by "require" to acquire module factory functions. Tampering with this variable must not alter the behavior of "require". * main: the "require" object MAY have an "main" member that is the module ID of the module that was the entry point for this sandbox. Thus the common Python idiom <tt>if __name__ == '__main__':</tt> would be <tt>if (require.id == require.main)</tt>, except that this strategy avoids the problem of double loading the main module if it's referred to elsewhere by its real name. * isLoaded: returns whether a module exports object has been loaded for a given canonical module identifier. * isInstance: returns whether an object is an instance of one of a module's named exports. This is a convenient shortcut to avoid loading a module when, if the module has not been loaded as yet, the instance clearly cannot have been instantiated by one of its native exports. * clear: forgets all loaded modules == A Loader Object == * load: the "loader" object, if present, MUST have a "load" method that returns a module factory function. ** a module factory function MUST accept "require", "exports", and "system" as its arguments. * fetch: a module loader, if present, must provide a "fetch" method that returns the text of a module for a given normalized, fully-qualified, absolute module identifier. * evaluate: a module loader, if present, must provide an "evaluate" method that accepts a module text and returns a module factory function ** a module text MUST be a string that conforms to a JavaScript "program" construction. * resolve: a module loader, if present, MUST provide a "resolve" method that accepts a module identifier (that may be a relative module identifier) and optionally a base module identifier (that must be an absolute module identifier) and returns the corresponding absolute identifier of the former. * canonical: a module loader, if present, MUST provide a "normalize" method that accepts an absolute module identifier and returns that identifier in its canonical form. "canonical" MAY be an identity relation. "canonical" may return an opaque reference object to prevent information about the underlying file system from leaking into a sandbox. * reload: forces a module factory to be refetched, reevaluated, and memoized. Can be used by load polymorphically in response to notification that the underlying stored module text has been modified. * clear: forgets all loaded module factories * getPaths MAY be present in permissive sandboxes, but MUST not be present in a secure sandbox. Returns the list of prioritized top-level module paths. * setPaths MAY be present in permissive sandboxes, but MUST not be present in a secure sandbox. Sets the prioritized list of top-level paths that the loader uses to find modules. * getExtensions MAY be present in permissive sandbox, but MUST not be present in secure sandboxes. Gets the list of prioritized file extensions that modules may have, including the dot prefix. * setExtensions MAY be present in permissive sandbox, but MUST not be present in secure sandboxes. Sets the list of prioritized file extensions that modules may have, including the dot prefix. 61 1707 2009-10-16T05:08:44Z KrisKowal 6 /* Contract */ '''STATUS: RATIFIED AND INTEGRATED IN [[Modules/1.1]]''' == Contract == This proposal adds the following on top of what is already specified by [[Modules/SecurableModules]]. === Module Context === # In a module, there must be a free variable "module", that is an Object. ## The "module" object must have a read-only, don't delete "id" property that is the top-level "id" of the module. The "id" property must be such that <tt>require(module.id)</tt> will return the exports object from which the <tt>module.id</tt> originated. (That is to say module.id can be passed to another module, and requiring that must return the original module). ## The "module" object may have a "uri" String that is the fully-qualified URI to the resource from which the module was created. The "uri" property must not exist in a sandbox. # ''In a module, there is a free variable "require", that is a function.'' ## … ## … ## … ## … ## The "require" function may have a "main" property that is read-only, don't delete and represents the top-level "module" object of the program. If this property is provided, its must be referentially identical to the "module" object of the main program. ## The "require" function may have a "paths" attribute, that is a prioritized Array of path Strings, from high to low, of paths to top-level module directories. ### The "paths" property must not exist in "sandbox" (a secured module system). ### The "paths" attribute must be referentially identical in all modules. ### Replacing the "paths" object with an alternate object may have no affect. ### If the "paths" attribute exists, in-place modification of the contents of "paths" must be reflected by corresponding module search behavior. ### If the "paths" attribute exists, it may not be an exhaustive list of search paths, as the loader may internally look in other locations before or after the mentioned paths. ### If the "paths" attribute exists, it is the loader's prorogative to resolve, normalize, or canonicalize the paths provided. == Discussion == * [http://groups.google.com/group/commonjs/browse_thread/thread/6ad5c2c3b005cb3b/5a0f17e43d347673 RFC require.paths behaviour] * [http://groups.google.com/group/commonjs/browse_thread/thread/c3682135d72b1f8 Module meta data Proposal.] (resurrection of this discussion) 62 2148 2010-03-10T11:18:05Z Oberhamsi 81 '''STATUS: PROPOSAL, NO LONGER BEING PURSUED, SEE [[Modules]]''' = Pythonic Modules = This proposal describes a module system similar to the one implemented in [http://github.com/ringo/ringojs/tree/master RingoJS]. I call it Pythonic Modules because it is heavily inspired by the way modules are [http://pytut.infogami.com/node8.html implemented in Python]. It provides protection against name collisions by isolating module scopes, while being reasonably easy to implement in a server or standalone JavaScript runtime. I have written about this in [http://dev.helma.org/wiki/Modules+and+Scopes+in+Helma+NG/ other places], but I try to rephrase its essential properties here in a more general way. I will for the purpose of this proposal refer to a generic JavaScript runtime that implements the pythonic module system. Note that while our JavaScript runtime uses the file system to store and access its modules, this is no requirement of this proposal. == Scripts are modules == For our JavaScript runtime, every script represents a module. This is true for all scripts, regardless of whether they are part of a core library or a user-written application. There is nothing special a script must contain in order to make it a module. == Module names == Modules are managed by the JavaScript runtime by looking for files within one or more directories which we call module directories. A module name translates to a file name by adding the .js extension to it. Thus, when our JavaScript runtime tries to load a module named A, it will look for a file called A.js in its module directories. Modules that live in subdirectories of a module directory are accessed using a dotted module name where each element in the module name corresponds ot an element in the file path. For example, a module named A.B.C will cause our JavaScript runtime to search its module directories for a file called A/B/C.js. == Every module has its own scope == This is maybe the most radical step away from JavaScript as we know it, since the shared global scope is one of JavaScript's more prominent features. But it is also one of the most critisized one, and one that will seriously hamper development of real large scale applications. As it turns out, giving each script its own top level scope is both easy and backwards compatible. When our JavaScript runtime starts up, it creates the familiar global JavaScript object containing the Object, Array, Date, Math, etc. objects. However, whenever the JavaScript runtime loads a module, it doesn't use the global object but instead creates a new, empty JavaScript object to evaluate the module on. This object, which we call the module scope, has two important features: 1. It represents a top-level scope, i.e. its parent scope is set to null. 2. It has the shared global object in its prototype chain. This makes sure module code will never pollute the shared global object (or any other module scope, for that matter), because it is the top-most object in its scope chain, but can still see the standard global objects through the module scope's prototype chain. With this setup, modules code will never unintentionally pollute any other scope. Users of our JavaScript runtime can just write global functions and variables, even accidentally omitting the var keyword, without any risk of disturbing with other modules or global code. == Importing modules == Since modules are shielded from each other, there must be a well-defined way for one module to load and make use of another module. Our JavaScript runtime provides one global require() function to allow one module to load and use another: <source> require('modulename') </source> This causes our JavaScript runtime to load the module with the given name, evaluate it on a module scope, and return the module scope to the caller. == Visibility of loaded modules == One great feature of the separated module scopes is protection against name collisions as described above. Another, maybe equally important feature is the fact that imported modules and module properties are only visible to the very modules that imported them. == Module loading and caching == Our JavaScript runtime keeps a map of loaded modules. Before a module is loaded, the runtime first checks whether the module has already been loaded before. If so, the existing module scope is reused. Our runtime also makes sure module scopes are registered in the loaded module map before evaluating them in order to be able to deal with cyclic imports. == Programming Notes == All top-level variables inside the module are exported. Variables can be hidden by using the module pattern and ensuring the use of "var" so they are not exported. <source> (function() { var modulePrivate = 10; moduleExported=11; })(); var otherModuleExported=12; </source> == Open issues == A discussion on irc happened about the separator in the require argument. Should it be require('A.B') or require('A/B')? There are other options but these seemed to be the popular options. As discussed on irc, the argument to require probably shouldn't have a file extension (e.g. ".js" or ".so") because that ties to an implementation. The JavaScript code should not need to know how a library is implemented. Should the module lookup path be mutable during program execution? Perhaps an array require.path could be mutated for this purpose. This may be tricky to implement and seems non-essential. Can this be postponed to a later edition of the spec so as not to slow things down? Should the module automatically-tried extensions be mutable during program execution. Something like require.extensions=["dll","js"] ? Should there be a require.loaded array-valued property with all the loaded module names or scopes? This seems non-essential. Can this be postponed to a later edition of the spec so as not to slow things down? What is the value of "this" when evaluated in the module scope? 63 2672 2010-04-16T12:41:15Z Jhuni 106 == Browser Sharable as Written == It would be handy to be able to share modules "as written" with the browser by loading the source code with html script tags. I think the following source code allows this feature. The first and last lines of the modules would be idiomatic boilerplate for modules to be shared on both the client and server. There are several ways to write the first and last lines. Some of them are shorter than below but give up some of the protection of the global namespace. The technique below only relies on the browser having the "require.install" property and the server not having it. <source> // ================================================================== // source code // // math.js // (function(){ var mod = function(require,exports) { exports.add = function() { var sum = 0, i = 0, args = arguments, l = args.length; while (i < l) { sum += args[i++]; } return sum; }; }; require.install ? require.install('math', mod) : mod(require, exports); })(); // // increment.js // (function(){ var mod = function(require,exports) { var add = require('math').add; exports.increment = function(val) { return add(val, 1); }; }; require.install ? require.install('increment', mod) : mod(require, exports); })(); // // program.js // var inc = require('increment').increment; var a = 1; inc(a); // 2 </source> Below is a comparison of a module written two different ways. First, the "normal" way for the browser that people are accustom to seeing these days. There are other ways to do it but this is certainly one way in an attempt to make an oranges-to-oranges comparison. <source> // define the library in a file called asdf.js // first and last lines are boilerplate var LIB = LIB || {}; LIB.asdf = (function() { var exports={}; var c = 1; exports.a = function() { return c; }; exports.b = 2; return exports; })(); // use the library in the browser LIB.asdf.a(); // use the library on the server require('asdf').LIB.asdf.a(); // Use the library on the server or in browser. // A module dependent on asdf would need to // be written like this or something similar. (require ? require('asdf') : window).LIB.asdf.a(); </source> Now write the library so it can be used the same way in the browser and on the server where the server has securable module loading. Note the boilerplate is only a little longer and both versions of boilerplate include the name of the module once. The main three lines of the library are the same. <source> // define the library in a file called asdf.js // assume "exports" is not defined // assume "modules" and "require" are defined // first and last lines are boilerplate (function(){ var mod = function(require, exports) { var c = 1; exports.a = function() { return c; }; exports.b = 2; }; require.install ? require.install('asdf', mod) : mod(require, exports); })(); // use the library in the browser or on the server require('asdf').a(); </source> 64 2797 2010-05-27T09:05:09Z Alexandre.Morgaut 33 {{Spec |status=superseded |by=1.1 |standard=yes |published=Website:Index/specs/modules/1.0 |implementations=Flusspferd, GPSEE, Narwhal=0.1, Persevere, RingoJS, SproutCore, node.js, v8cgi, CouchDB,Smart, Yabble, Wakanda }} This specification addresses how modules should be written in order to be interoperable among a class of module systems that can be both client and server side, secure or insecure, implemented today or supported by future systems with syntax extensions. These modules are offered privacy of their top scope, facility for importing singleton objects from other modules, and exporting their own API. By implication, this specification defines the minimum features that a module system must provide in order to support interoperable modules. == Contract == === Module Context === # In a module, there is a free variable "require", that is a function. ## The "require" function accepts a module identifier. ## "require" returns the exported API of the foreign module. ## If there is a dependency cycle, the foreign module may not have finished executing at the time it is required by one of its transitive dependencies; in this case, the object returned by "require" must contain at least the exports that the foreign module has prepared before the call to require that led to the current module's execution. ## If the requested module cannot be returned, "require" must throw an error. # In a module, there is a free variable called "exports", that is an object that the module may add its API to as it executes. # modules must use the "exports" object as the only means of exporting. === Module Identifiers === # A module identifier is a String of "terms" delimited by forward slashes. # A term must be a camelCase identifier, ".", or "..". # Module identifiers may not have file-name extensions like ".js". # Module identifiers may be "relative" or "top-level". A module identifier is "relative" if the first term is "." or "..". # Top-level identifiers are resolved off the conceptual module name space root. # Relative identifiers are resolved relative to the identifier of the module in which "require" is written and called. === Unspecified === This specification leaves the following important points of interoperability unspecified: # Whether modules are stored with a database, file system, or factory functions, or are interchangeable with link libraries. # Whether a PATH is supported by the module loader for resolving module identifiers. == Unit Tests == * [http://code.google.com/p/interoperablejs/ Unit Tests at Google Code] by Kris Kowal * [http://github.com/ashb/interoperablejs/tree/master Unit Tests Git Mirror] by Ash Berlin == Sample Code == ;math.js: <source> exports.add = function() { var sum = 0, i = 0, args = arguments, l = args.length; while (i < l) { sum += args[i++]; } return sum; }; </source> ;increment.js: <source> var add = require('math').add; exports.increment = function(val) { return add(val, 1); }; </source> ;program.js: <source> var inc = require('increment').increment; var a = 1; inc(a); // 2 </source> <noinclude> == Notes == * [[Modules/Secure|Secure Modules]] * [[Modules/CompiledModules|Notes on compiling modules for browsers]] * [[Modules/ScriptModules|On writing modules that also work as <script>s]] == Amendment Proposals == # [[Modules/Loaders|Module Loaders]] # [[Modules/Meta|Module Metaobject]] == Implementations == Passing all compliance tests: * Flusspferd (Spidermonkey / C++) http://flusspferd.org/ * Ondrej Zara's v8cgi for V8 http://code.google.com/p/v8cgi/ * Tom Robinson's narwhal for Rhino http://github.com/tlrobinson/narwhal/ * Wes Garland's GPSEE for Spidermonkey http://code.google.com/p/gpsee/ * Kris Kowal's chiron for browsers http://github.com/kriskowal/chiron/ * Hannes Wallnoefer's RingoJS for Rhino at http://github.com/ringo/ringojs * Ben Collver's Trogl for v8 at http://bencollver.googlepages.com/trogl-1.zip * Atul Varma's Pydertron for Python/Spidermonkey at http://hg.toolness.com/pydertron/raw-file/tip/docs.html * Daniel Friesen's [http://lite.monkeyscript.org MonkeyScript Lite] for Rhino * Irakli Gozalishvili's narwhal for XULRunner http://github.com/gozala/narwhal-xulrunner/ * James Brantly's Yabble for browsers http://github.com/jbrantly/yabble * 4D's Wakanda (JavaScriptCore/SquirrelFish) http://www.wakandasoft.com Fully implemented: * Kris Zyp's Persevere for Rhino at http://www.persvr.org/ In development: * nathan smith is implementing this for JScript and ASP at http://github.com/smith/interoperablejscript/tree/master * mob is implementing this in Ejscript http://www.ejscript.org * pmuellr posted a sample loader http://wiki.github.com/pmuellr/modjewel </noinclude> == Related Documents == * Proposal to ECMA TC39: [http://docs.google.com/Doc?id=dfgxb7gk_34gpk37z9v&hl=en Module System for ES-Harmony] * Presentation to ECMA TC39: [http://docs.google.com/Presentation?docid=dcd8d5dk_0cs639jg8&hl=en Modules] 65 1122 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/Secure]] to [[Modules/Secure]] To be usable in secured module loaders, a module must conform to additional constraints: # A module must not write to any free variables or their transitive members. # A module must not refer to any free variables apart from primordials ("Object", "Array", etc. as defined by ECMAScript), "require", "environment", and "exports". # A module must not tamper with (assign to, assign to members of, delete, or otherwise mutate) the transitive primordials. 66 1083 2009-09-10T20:02:32Z Dantman 1 moved [[CommonJS/Packaging]] to [[Packaging]] = Packaging, installation and deployment = One of the most important parts of this project is to provide a repository for code releases and an easy way to install that code for development and production uses. Possibly the most successful example of this is Perl's CPAN. Python has its Cheeseshop (also called the Python Package Index) and Ruby has gems. It is important to work alongside the Linux distro packaging mechanism, but for Windows, Mac users and people who want to run something that is not yet in their distro, having a language specific installation process is critical. 67 931 2009-09-10T03:04:31Z Dantman 1 Redirected page to [[Status]] #REDIRECT [[Status]] 68 1217 2009-09-12T02:42:14Z Dantman 1 Robot: Automated text replacement (-CommonJS/ +) '''STATUS: RATIFIED''' The goal of this project is to have something that people can run and build web frameworks and applications on. The process needs to support that goal, plus the goal of having a specification that allows people to make other JS interpreters/platforms compatible. There are two parts to the process: # Creating the specs and code # Handling disagreements Number 1 is how things get done. Number 2 is how we ensure that number 1 is able to continue in face of inevitable disagreements. * [[ProposalProcess|CommonJS Proposal Process]] (to be continued...) == Prior Art == * [http://www.python.org/dev/peps/pep-0001/ Python Enhancement Proposal] (PEP). This process is not completely applicable, because Python has a dictator that keeps things from spiraling out of control. * [http://srfi.schemers.org/ Scheme Requests For Implementation] * [http://en.wikipedia.org/wiki/Request_for_Comments#RFC_production_and_evolution Request for Comments] (RFC) * [http://www.apache.org/foundation/voting.html Apache Voting] == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/280c8b0375783604 Organisation and Making Decisions] * [http://groups.google.com/group/commonjs/browse_thread/thread/5271db92e9e22dbd A modest proposal for a simple proposal process] * [http://groups.google.com/group/commonjs/browse_thread/thread/130b5ecd678befeb Spec medium] * [http://groups.google.com/group/commonjs/browse_thread/thread/f415d73c2cefa45e A proposal for modesty] 69 1845 2009-12-11T02:02:52Z Kriszyp 39 /* Proposed API */ = Promise Manager = Promise manager provides a convenience API for handling promises. == Prior Art == * [https://vsci.hpl.hp.com/-/7fuxka/#s=yuwsw2qt3bde7b ref_send]. A promise manager. == Proposed API == A top-level 'promise' module should export the functions defined here: http://waterken.sourceforge.net/web_send/ In addition, a promise module should export: ; wait() : This will block the execution of the current function while waiting for the Promise to be fulfilled, *if* the implementation and this Promise support this operation. If supported, the function will return the result of the resolved Promise when it is fulfilled. If the Promise is resolved with an error, than this function will throw the provided error object. If the concurrency model of the implementation or the Promise object does not support blocking, the "wait" property should be a null or undefined. This API is not intended to imply that implementations that provide a "wait" function are superior. == Related Discussions == http://groups.google.com/group/commonjs/browse_thread/thread/e93f73ef97e88439/9cdb490abb8edfa6 http://groups.google.com/group/commonjs/browse_thread/thread/86fd52c9be191c4b 70 2554 2010-04-05T23:20:51Z KrisKowal 6 /* Proposals */ '''STATUS: PROPOSAL, DISCUSSION''' = Promises = Promises provide a well-defined interface for interacting with an object that represents the result of an action that is performed asynchronously, and may or may not be finished at any given point in time. By utilizing a standard interface, different components can return promises for asynchronous actions and consumers can utilize the promises in a predictable manner. Promises can also provide the fundamental entity to be leveraged for more syntactically convenient language-level extensions that assist with asynchronicity. == Prior Art == * [http://docs.dojocampus.org/dojo/Deferred Dojo's Deferred] A form of promises that was inherited from MochiKit and Twisted. * [http://waterken.sourceforge.net/web_send/#Q ref_send]. A promise manager. * [http://wiki.erights.org/wiki/Object_Ref]. E reference API == Proposals == * [[Promises/A]] by Kris Zyp * [[Promises/B]] by Kris Kowal == Requirements == * 1. if a function receives a promise as its input, that function must itself return a promise for its output. Provide a simple mechanism that guarantees, in the face of programmer error, non-determinism, and malice: * 1.1. that defends the function's internal consistency from attack by the provider of the input promise. * 1.2. that defends the function's internal consistency from attack by the consumer of the output promise. * 1.3 that defends each recipient of the output promise from each other recipient. * 1.4 that prevents the input promise from being leaked to the output consumer. The return value of this expression must never be the input or provide the consumer from gaining direct access to the input. function API(input) { return when(input, function (input) { }); }; For example, a password checking API must be able to retain a reference to a remote table of password hashes and must never give the consumer direct access to any of those hashes. function PasswordChecker(accounts) { return function (user, password) { var passwordHash = Q.get(accounts, user); return when(passwordHash, function (passwordHash) { if (hash(password) === passwordHash) return true; }; }; } // returns a password checking capability // but does not return access to the passwordHash return PasswordChecker(accounts); * 1.4. when the input is resolved, and if it is discovered that there is additional unresolved input, permit the function to forward a new promise. * 1.5. that permits the function to either forward the failure of its input, or recover from that failure by forwarding a resolved value, or recover by forwarding a new promise to eventually resolve or fail later. * 2. avoid interleaving hazards. * 2.1. prevent promise consumers from giving promise providers direct use of their callbacks as in these counter-examples: var internalCounter = 0; // /!\ HAZARD: untrusted promise given direct access to a // function that has the capability to alter internal // state, either during the same turn or in any future turn promise("when", function () { internalCounter++; }); // /!\ HAZARD: untrusted promise given direct access to a // function that has the capability to alter internal // state, either during the same turn or in any future turn promise.when(function () { internalCounter++; }); // /!\ HAZARD: untrusted promise given direct access to a // function that has the capability to alter internal // state, either during the same turn or in any future turn promise.then(function () { internalCounter++; }); ASSERT.equal(internalCounter, 0); * 2.2. prevent promise providers from calling a consumer's internal callbacks in the same turn as they are registered. // /!\ HAZARD: untrusted promise given direct access to a // function that has the capability to alter internal // state, either during the same turn or in any future turn var internalCounter = 0; when(promise, function () { internalCounter++; }); ASSERT.equal(internalCounter, 0); * 2.3. prevent promise providers from calling a consumer's internal callback or errback more than once, ever. var internalCounter = 0; when(promise, function (value) { internalCounter++; }, function (error) { internalCounter++; }); setTimeout(function () { ASSERT.ok(internalCounter == 0 || internalCounter == 1); }, forever); * 3. Separate the concerns of "resolving" from "observing resolution". * 3.1 permit an API to safely produce a "deferred", retain the "resolver" portion for itself, and distribute the "promise" component to any number of mutually suspicious consumers. * 3.2 "Competitive Races": permit an API to safely produce a "deferred", retain the "promise" portion for itself, and distribute the "resolver" component to any number of mutually suspicious consumers. * 4. provide a mechanism that permits a promise consumer to throw an exception in any turn where a suspicious promise attempts to resolve multiple times. * 5. Provide support for arbitrary message passing to promises, including support for intercepting arbitrary messages for which no handler has been explicitly provided. == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/e93f73ef97e88439/9cdb490abb8edfa6 Promise API Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/d567d30e2bbea598 CommonJS Promises and the Q API] * [http://groups.google.com/group/commonjs/browse_thread/thread/c5a26c43640ede26 A Different Approach to Future/Promise] 71 1125 2009-09-10T20:25:03Z Dantman 1 moved [[CommonJS/ProposalProcess]] to [[ProposalProcess]] '''STATE: DISCUSSION''' We adopt a [http://www.perlfoundation.org/perl5/index.cgi?jfdi JFDI] policy regarding adding proposals to CommonJS. As long as the page makes the level of acceptance clear with a line at the top, it's not a problem. == State 1: "Proposed" == "Hay guys, I have an idea for a topic!" Don't say it, just do it. Add a page to the wiki describing your proposal. Bonus points if you can point at working code. It's not always prudent to implement something complicated before discussing with the group, since it might be misguided and difficult, but at the very least, rough sketch/prototype/proof of concept often helps crystallize the discussion. Congratulations. You own the idea now. You're responsible for maintaining the wiki page, counting votes, starting the discussion, etc. If it's not worth it to you to do the work, then it's probably not important enough to be in the spec. This ensures that all ideas need to get over a bit of a hump to get accepted. == State 2: "Discussion" == "Let's talk about my idea!" Send a message to [http://groups.google.com/group/commonjs CommonJS] with a link to the wiki page. We'll talk about it, build all kinds of bike sheds. This should last at least a few days, or however long necessary to flesh out any dissenting opinions. People start weighing in with their votes. If you have an opinion, share it now. If you don't care one way or the other, then stay out of it. === Silence is not consent. === ''Some'' discussion must occur for the idea to progress to "official accepted" status. If someone suggests something, and no one responds, then the idea remains open indefinitely. If you suggest something, and no one else speaks up in favor of it, that doesn't mean it's a bad idea. However, this is probably something that you should just put in your own application, and it most likely does not belong in the CommonJS specification. This bit of inertia prevents us from building specifications no one wants. The flip side of this: if someone suggests something, and you think it's a good idea, ''Speak up!'' === Unanimity is Suspect === There may be cases when everyone involved in the discussion is in favor of the proposal. This probably means that someone's voice isn't being heard. In the case of a completely one-sided discussion, make some effort to figure out who might be against it, and try to ping them directly, or at least wait until they weigh in on it before considering the issue closed. It could be that they didn't feel strongly in the first place, or that they've been swayed by the arguments from the other side. But there was probably a reason for their initial resistance, and it should be heard. == State 3: "Decided" == "We're talking in circles and here are the major ideas:..." Someone count the votes, and we make a decision. Update the wiki page to the latest decision. Note that a simple vote count doesn't necessarily imply a decision. If 15 people decide that it's a good idea to do something, and the 2 people who maintain that code rebut with valid reasons why it's impossible or impractical, then the 2 should outweigh the 15, and perhaps propose some kind of alternative to meet their needs. == State 4: "Implemented" == At least a handful of the relevant projects have implemented the spec. Add links to implementations to the wiki page. At this point, it's considered final, and can only be changed by restarting this process. A proposal ''only'' reaches this state by virtue of being implemented in more than one library. At this point, it is considered a standard, and implementers can rest assured that it will not change without good reason. 72 1051 2009-09-10T19:56:26Z Dantman 1 moved [[CommonJS/RDBMS]] to [[RDBMS]] = Relational Database Interface = Though there are many kinds of persistence engines available, relational databases are the most commonly deployed. Relational databases have a consistent data model and a reasonably consistent set of operations. This has allowed for the creation of a standard interface in many different languages. If it's possible to interface with other types of databases using the same kind of interface, that is a win. However, the primary goal with this API is to provide access to relational databases. == Prior Art == * JSDB is JavaScript for databases http://www.jsdb.org/ * SQueaL is an XML-based SQL Schema designed for defining databases http://alt.cellosoft.com/squeal.html * Ejscript has a low level database access API and a high level "Rails like" ORM http://www.ejscript.org/products/ejs/doc/api/ejscript/ejs.db-classes.html The Record class is based on the Rails ActiveRecord class. * Jester, REST in Javascript, http://www.thoughtbot.com/projects/jester * JSONSQL http://www.trentrichardson.com/jsonsql/ * jslibs jssqlite module http://code.google.com/p/jslibs/wiki/jssqlite * TaffyDB, a JS database for your browser http://taffydb.com/index.cfm * JSMemCached JS memcached client http://code.google.com/p/jsmemcached-client/ * v8cgi has a [http://code.google.com/p/v8cgi/wiki/API#MySQL_functions MySQL] class * [http://en.wikipedia.org/wiki/Java_Database_Connectivity JDBC] * [http://www.python.org/dev/peps/pep-0249/ Python DBAPI] * HTML5 defines a local database API http://dev.w3.org/html5/webstorage/#databases (supported by Safari) * Google Gears database API http://code.google.com/intl/fr/apis/gears/api_database.html == Other notes == I second that proposal. I particuarly like the model CodeIgniter uses for the dbms interface: A common interface or abstract class that is then subclassed for each database implementation. This would allow some RDBMS implementations to be done by this project, but should allow for me (a third party) to use my own driver. What are we gonna call our interface for connecting to a database? Options: RDBMS, DB, Connection, Database? 'DB' is short and rather to the point. DB : Class { DB : function (driver, host, username, password, database) // or the following constructor DB : function (driver, connectionString) // mcoquet: I rather like better passing in an object with the arguments instead of a string like so: DB : function (driver, connectionConfigObj) // ie: method ("mysql", {host:"bla.com",port:"3306",user:"username",pass:"mypass"}) query : function (sql) // returns a JS object execute : function (sql) version : function () close : function() } I haven't defined any sort of ResultSet object because I'm left to understand that a ResultSet class merely (or often) provides a pretty interface for looping through the results and getting some other minor meta data. Most of this functionality can be achieved by providing a simple structured Javascript object. For example: myResultSet: { meta: ['id', 'name', 'age'], data: [ { id: 1, name: 'Yunero', age: 22 }, { id: 2, name: 'Abbadon', age: 45 }, { id: 3, name: 'Luna', age: 31 } ] } Is there much else a recordset needs? The DB interface is slim to say the least; Often drivers and classes have all sorts of helper methods; In the case of an RDBMS we could add all sorts of methods for update, select, delete, creating/manipulating database schema,.. but often is the case that the more that gets added - the more politics and ideals are gonna slow it down. Should there be more to this design? Perhaps the DB interface above should be more function overloaded? The prepared statement style of querying (passing a string with "?" placeholders, and additional arguments filling in the placeholders) is a good way of preventing SQL injection. Should it support that syntax? == ORMs == Object relational mappers would use the interface defined here, but are still an area of active exploration and not one to standardize at this time. * ActiveRecord.js, ORM in Javascript http://www.activerecordjs.org/ * Ejscript Record ORM http://www.ejscript.org/products/ejs/doc/api/ejscript/ejs.db-classes.html 73 1079 2009-09-10T20:00:54Z Dantman 1 moved [[CommonJS/Random Links]] to [[Random Links]] http://www.blueskyonmars.com/2009/01/29/what-server-side-javascript-needs/ http://www.blueskyonmars.com/2009/01/30/server-javascript-wiki-and-irc/ http://ajaxian.com/archives/what-server-side-javascript-needs-join-in http://www.blueskyonmars.com/2009/02/05/serverjs-one-week-into-building-a-better-javascript/ http://pmuellr.blogspot.com/2009/02/its-alive-javascript-modules.html http://peter.michaux.ca/articles/a-bright-future-for-standardized-server-side-javascript 74 2112 2010-02-18T21:30:50Z Ruediger 75 = Language and Runtime Services = This API provides information about the JavaScript interpreter and its environment. == Prior Art == * [http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/index.html Ejscript] has an "ejs.sys" module that provides a set of classes for system level activities such as Debug control, GC management, Memory resource utilization and command execution * The JSAPI is the C API for the SpiderMonkey JavaScript engine https://developer.mozilla.org/En/SpiderMonkey/JSAPI_Reference * [http://flusspferd.org/docs/js/flusspferd%20core/flusspferd.html Flusspferd's flusspferd module] * Python's [http://docs.python.org/library/sys.html sys module] has some of this kind of information for Python. 75 1747 2009-11-16T11:47:19Z Paraboul 36 /* Prior Art */ == Requirements/Proposals == * [[Sockets/A]] Proposal * [[IO/B/Socket]] of the [[IO/B]] proposal == Questionnaires and show of hands == * Summary/Comparison of current Socket APIs used by JS engines: [http://spreadsheets.google.com/pub?key=tYP9b4a7U5ezmh1ivHURJXg CommonJS Socket Object Survey] * [[/Show of hands/]] == Prior Art == * NSPR Socket Manipulation Functions https://developer.mozilla.org/en/NSPR_API_Reference/I%2f%2fO_Functions#Socket_Manipulation_Functions * W3 WebSocket interface http://dev.w3.org/html5/spec/Overview.html#network * v8cgi has a [http://code.google.com/p/v8cgi/wiki/API#Socket_functions Socket] class * jslibs jsio module This module is based on Netscape Portable Runtime (NSPR) that provides a platform-neutral API for system level and libc like functions. http://code.google.com/p/jslibs/wiki/jsio * Synchronet provides a Socket class that supports TCP and UDP sockets and provides a fairly complete wrapper for the Berkeley Sockets API: http://synchro.net/docs/jsobjs.html#Socket * Ejscript provides a Socket class too for TCP and UPP. See: http://www.ejscript.org/products/ejs/doc/api/gen/ejscript/ejs.io-Socket.html * [http://jaxer.org/ Jaxer] provides a [http://github.com/aptana/Jaxer/blob/master/server/framework/IO/Socket.js Socket implementation]. * [http://www.ape-project.org/ APE] provides a high level socket API : http://www.ape-project.org/wiki/index.php/How_to_build_a_serverside_JS_module#Sockets === Inspiration === * some free time, a couple of Cokes and wanting CommonJS implementations of File and Socket ASAP == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/f415d73c2cefa45e/81461f32e8d22303 A proposal for modesty] * [http://groups.google.com/group/commonjs/browse_thread/thread/6cce4e4730c35651/29d855b960ab640c The case for a dedicated I/O spec] 76 1989 2010-01-15T04:54:41Z KrisKowal 6 /* Resolutions */ fixed chronological order This page summarizes the group's status. == Require Discussion == * [[Binary|Binary Proposal Ratification]] * [[Filesystem/A#Todo|Filesystem Proposal Todo List]] * [[Encodings|Encodings API Proposal Ratification]] * [[System|System Module Additional Proposed Names]] * [[Modules/Loaders|Standard Module Loader API]] (not ready for discussion, pending rewrite - KrisKowal) * C Runtime Linkage API Proposals * C Module API Proposals * Unit Testing Extensions, Gearing Toward QUnit DSL Compatibility == Discussion == * [[Filesystem/A/0|Filesystem Proposal A/0]] (low-level file system proposal) == Show of Hands == == Resolutions == * [[Packages/1.0]] (ratified) * [[Unit_Testing/1.0]] (ratified) * [[System/1.0]] (ratified) * [[Modules/1.1]] Meta Object Amendment (ratified) * [[Modules/1.0]] (ratified) == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/602310411fa74f4d August, 2009] 77 2801 2010-05-27T09:12:04Z Alexandre.Morgaut 33 {{Spec |status=implementations |standard=yes |implementations=Flusspferd, GPSEE, NarwhalRhino=0.2, NarwhalNode=0.5, NarwhalJSC=0.2, RingoJS, SproutCore, v8cgi, Wakanda }} = System Interface = All platforms must support a module, "system", that MUST contain the following attributes. * stdin: the standard input stream, an object with the same API as a file opened with the mode "r" with no encoding. * stdout: the standard output stream, an object with the same API as a file opened with the mode "w" with no encoding. * stderr: the standard error stream, an object with the same API as a file opened with the mode "w" with no encoding. * env: an Object containing posix-style or CGI environment variables. * args: an Array containing the command line arguments for the invoking arguments, not including the interpreter/engine but including the path to the program as it was executed. See also the [[Command Line|Command Line page]]. Any names not mentioned here or amended into this specification later should begin with "x" and a vendor-specific label as a prefix, like system.xCajaDomita. This will permit the future standardization of additional names as needed. Please request additional standard names below. = Compliant Implementations = * [http://github.com/tlrobinson/narwhal/ Narwhal] * [http://flusspferd.org/ Flusspferd] (in 0.7) * [http://github.com/ringo/ringojs/ RingoJS] (in 0.4) * [http://code.google.com/p/v8cgi/ v8cgi] = Proposals for Future Versions = The following names have been proposed but not ratified for inclusion in the System proposal. The "system" module MAY export the following functions, that if preset MUST behave as specified. * print: a function that forwards its thisp and arguments to "system.stdout.print" with lazy binding (meaning that, if system.stdout is replaced, print MUST forward to the new stdout). * log: a function that accepts a "message" and an optional "label" String. ** The label MAY be one of "log", "debug", "warn", "error", "pass", "fail". ** Any other, unspecified label MUST be in lower-case and begin with "x" and a vendor-specific label like "x-v8cgi-database". ** Still not sure that this belongs system. (There are lots of flavours of logging: log("x", "debug") vs log.debug("x"). Also prefixed logging (by namespace) doesn't work with this form) [[User:Ashb|Ashb]] * platform: a string with its vendor-specific platform name. ** Is this meant to be the OS name or the commonjs project name ("flusspferd","gpsee","narwhal" etc)? [[User:Ashb|Ashb]] * global: the "system" MAY contain a reference to the global object. * command: an array containing argv[0] and any subsequent arguments that would be relevant for "Usage:" lines. argv[0] would be removed from system.args. [http://groups.google.com/group/commonjs/browse_thread/thread/6d1063937b0b0a3c] Supporters: KrisKowal, ChristophDorn, AshBerlin, DonnyViszneki * Split "env", "args", and "command" into one module, so stdio can be alternately imported as synchronous or asynchronous in another module. == Removed proposals == * fs: a file default file system root object conforming to the File System API * print (proposal A): The "system" MAY have a "print" function that accepts a "message" and an optional "label" String. ** The label MAY be one of "log", "warn", "error", "pass", "fail". ** Any other, unspecified label MUST be in lower-case and begin with "x" and a vendor-specific label like "x-v8cgi-database". ** '''Counter-argument''' This is infact not printing, but logging. 1) there is lots of logging frameworks, 2) it probably doesn't belong on sys, certainl not called ''print'' *** '''Counter-argument''' However, ''print'' has meant to write a line to stdout in many languages. That it would frequently be used for logging in non-stdio contexts is not necessarily relevant. = Show of Hands = [[System/ArchivedShowOfHands]] == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/4f6c16e2f4c14c25/7c10fe164ead35c0?lnk=gst Module System feedback] * [http://groups.google.com/group/commonjs/browse_thread/thread/749c3777f62cf34 System API Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/6d1063937b0b0a3c System command routing] 78 1124 2009-09-10T20:24:46Z Dantman 1 Redirected page to [[System]] #REDIRECT [[System]] 79 1700 2009-10-16T04:56:52Z KrisKowal 6 moved [[System/ArchivedShowOfHands]] to [[System/1.0/ArchivedShowOfHands]] = Archived "Show of Hands" = == Archived 2009-06-18 == module or free variable: * Z as a free variable ** Kris Kowal ** Ihab Awad * Y as a module ** Hannes Wallnoefer ** Peter Michaux ** Chris Zumbrunn ** Robert Thurnher ** Aristid Breitkreuz ** Ash Berlin == Archived 2009-05-28 == arguments: * A arguments ** Ondrej Zara ** Wes Garland ** Daniel Friesen ** Ash Berlin * B args ** Tom Robinson, ** Kevin Dangoor, ** Hannes Wallnoefer, ** Michael O'Brien, ** Chris Zumbrunn, ** Robert Thurnher ** George Moschovitis * C argv ** Tom Robinson ** Kris Kowal environment: * 1 env ** Ondrej Zara ** Tom Robinson ** Kris Kowal ** Kevin Dangoor ** Hannes Wallnoefer ** Michael O'Brien ** Chris Zumbrunn ** Robert Thurnher ** George Moschovitis ** Ash Berlin * 2 environ * 3 environment ** Wes Garland system: * I sys ** Tom Robinson, ** Kris Kowal ** Aristid Breitkreuz * II System ** Ondrej Zara * III system ** Ondrej Zara, ** Kevin Dangoor, ** Hannes Wallnoefer, ** Chris Zumbrunn, ** Robert Thurnher ** George Moschovitis ** Ash Berlin [[Category:Show of hands]] 80 843 2009-09-10T02:14:58Z Dantman 1 moved [[CommonJS/Target Platforms]] to [[Target Platforms]] There are four main open source JavaScript interpreters today: Rhino, Spidermonkey, v8 and JavaScriptCore. Our goal is that libraries and applications that use the APIs defined here (and nothing else platform specific) will run unmodified on all four of these interpreters. http://developer.mozilla.org/en/SpiderMonkey http://code.google.com/p/v8/ http://trac.webkit.org/wiki/SquirrelFish http://www.mozilla.org/rhino/ Some other JS engines: http://www.ejscript.org/ http://esxx.org/ http://en.wikipedia.org/wiki/List_of_JavaScript_engines == Code Volunteers == === Rhino === * Chris Zumbrunn ( http://zumbrunn.com/ , chris@zumbrunn.com ) - in the context of Helma 1.x, Apache Sling and Helma NG * Peter Michaux (http://peter.michaux.ca/, petermichaux@gmail.com) * Kris Zyp (http://www.sitepen.com, kris@sitepen.com implementing in Persevere: http://www.persvr.org/) * Robert Thurnher (http://soup.robert42.com, r.thurnher@gmail.com) === Spidermonkey === * Mário Valente ( http://mv.asterisco.pt/ , mfvalente@gmail.com ) * Wes Garland ( http://www.page.ca/, wes@page.ca ) * Davey Waterson (geekfreak AT gmail) === V8 === * Lorenzo Pastrana (http://www.happyendfilms.com/#/profile:3, pastrana at ultraflat dot net) === JavaScriptCore === === Ejscript === * Michael O'Brien (http://www.ejscript.org/, mob@embedthis.com) 81 2778 2010-05-22T16:58:01Z KrisKowal 6 /* Specifications and Proposals */ NodeJS calls for notOk '''STATUS: 1.0 RATIFIED, AMENDMENT PROPOSALS PENDING''' = Unit testing = Automated tests are an important part of software development today. Providing a standard test library will help encourage more people to write more tests. Additionally, the API specification will likely be written in the form of tests, so this component will be needed by the CommonJS project itself. Testing involves both an API for easily defining tests and running assertions, plus a tool (or tools) for locating and running the tests. == Specifications and Proposals == * [[/1.0|1.0]] '''ratified''' Known spec bugs in version 1.0: * Not self-consistent: <code><pre>assert.equal(4,new Number(4));</pre><pre>assert.deepEqual(4, new Number(4));</pre></code> * Not self-consistent: <code><pre>assert.equal(/a/, /a/g);</pre><pre>assert.deepEqual(/a/, /a/g);</pre></code> * 7.4 talks about checking prototype properties, not the internal [&#91;Prototype]] itself (<tt>__proto__</tt> or <tt>Object.getPrototypeOf</tt>) * Does not handle string equivalence, specifically that strings in deep equivalence calls must be identical, not equal after coercion. * <code>assert.throws</code> has to be written <code>assert['throws']</code> in some implementations to get around protected keywords or JSLint * There's a call for "assert.equal" to either be strict or "fixed" for some value of correctness for equality comparison. [http://groups.google.com/group/commonjs/browse_thread/thread/f2069b1ef5bf4c67] * The NodeJS mailing list calls for "assert.ifError", "assert.noError", or "assert.notOk" [http://groups.google.com/group/nodejs/browse_thread/thread/674dbb3b1dccdf7a] == Prior Art == * [http://jsunit.berlios.de/ JsUnit] - browser, native, Ant, and Maven based test runners * [http://code.google.com/p/rhinounit/ rhinounit] - Ant based test runner * JavaScript Assertion Unit - * [http://docs.jquery.com/QUnit QUnit] jQuery's unit testing framework, browser based * [http://download.dojotoolkit.org/current-stable/dojo-release-1.2.3/util/doh/ DOH] JavaScript unit testing framework (used by Dojo, but without Dojo dependencies), supports browsers and stand-alone JavaScript environments. * JSSpec is a Javascript BDD(Behavior Driven Development) framework. http://code.google.com/p/jsspec/ * JSpec is a minimalistic JavaScript behavior driven development framework http://github.com/visionmedia/jspec/tree/master * Better Javascript testing through ScrewUnit http://pivotallabs.com/users/nick/bl...ough-screwunit * Mochitest is an [https://developer.mozilla.org/En/Mozilla_automated_testing automated testing framework] built on top of the MochiKit JavaScript libraries https://developer.mozilla.org/en/Mochitest * Yahoo! UI Library: YUI Test http://developer.yahoo.com/yui/yuitest/ * JSMock is a fully featured Mock Object library for JavaScript that provides the necessary tools to do effective interactive based testing. http://jsmock.sourceforge.net/ * JSLitmus is a lightweight tool for creating ad-hoc JavaScript benchmark tests. http://www.broofa.com/Tools/JSLitmus/ * Jack is a toolkit for mocking JavaScript objects and functions. http://boss.bekk.no/display/BOSS/Jack * MockMe for JavaScript http://johanneslink.net/projects/mockme.html * qMock is a standalone, lightweight mocking framework that facilitates integration testing for JavaScript programs. http://code.google.com/p/qmock/ * TDD JS with JsMock http://www.pathf.com/blogs/2006/11/tdd_and_javascr/ * Test Driven Javascript http://www.testdrivenjavascript.com/Practice/5.aspx * jsUnity is a lightweight JavaScript testing framework that is context-agnostic http://jsunity.com/ * JsUnitTest is based off unittest.js from prototypejs, except this library has no dependencies http://jsunittest.com * Inspec BDD style test framework http://github.com/aq1018/inspec 82 2833 2010-06-22T21:25:55Z Hannesw 10 Add RingoJS to implementations {{Spec |status=approved by discussion participants |specification=yes |participants=Tom Robinson, Ash Berlin, George Moschovitis, Chris Zumbrunn, Hannes Wallnöfer, Kris Kowal, Kevin Dangoor, Ates Goral, and Davey Waterson |discussion=http://groups.google.com/group/commonjs/browse_thread/thread/2952de9982fc2b55 |implementations=Flusspferd, Narwhal=0.2, SproutCore, node.js, v8cgi, Wakanda, RingoJS }} = Specification = 1.0 == Assert == 1. The <tt>assert</tt> module provides functions that throw <tt>AssertionError</tt>'s when particular conditions are not met. The <tt>assert</tt> module must conform to the following interface. <source>var assert = require("assert");</source> 2. The AssertionError is defined in <tt>assert</tt>. <source> new assert.AssertionError({message: message, actual: actual, expected: expected}) assert.AssertionError instanceof Error </source> At present only the three keys mentioned above are used and understood by the spec. Implementations or sub modules can pass other keys to the AssertionError's constructor - they will be ignored. 3. All of the following functions must throw an <tt>AssertionError</tt> when a corresponding condition is not met, with a message that may be undefined if not provided. All assertion methods provide both the actual and expected values to the assertion error for display purposes. 4. Pure assertion tests whether a value is truthy, as determined by <code>!!guard</code>. <source>assert.ok(guard, message_opt);</source> This statement is equivalent to <code>assert.equal(guard, true, message_opt);</code>. To test strictly for the value <code>true</code>, use <code>assert.strictEqual(guard, true, message_opt);</code>. 5. The equality assertion tests shallow, coercive equality with <code>==</code>. <source>assert.equal(actual, expected, message_opt);</source> 6. The non-equality assertion tests for whether two objects are not equal with <code>!=</code> <source>assert.notEqual(actual, expected, message_opt);</source> 7. The equivalence assertion tests a deep equality relation. * 7.1. All identical values are equivalent, as determined by <tt>===</tt>. * 7.2. If the expected value is a Date object, the actual value is equivalent if it is also a Date object that refers to the same time. * 7.3. Other pairs that do not both pass <tt>typeof value == "object"</tt>, equivalence is determined by <tt>==</tt>. * 7.4. For all other <tt>Object</tt> pairs, including <tt>Array</tt> objects, equivalence is determined by having the same number of owned properties (as verified with <tt>Object.prototype.hasOwnProperty.call</tt>), the same set of keys (although not necessarily the same order), equivalent values for every corresponding key, and an identical "prototype" property. Note: this accounts for both named and indexed properties on Arrays. <source>assert.deepEqual(actual, expected, message_opt);</source> 8. The non-equivalence assertion tests for any deep inequality. <source>assert.notDeepEqual(actual, expected, message_opt);</source> 9. The strict equality assertion tests strict equality, as determined by <tt>===</tt>. <source>assert.strictEqual(actual, expected, message_opt);</source> 10. The strict non-equality assertion tests for strict inequality, as determined by <tt>!==</tt>. <source>assert.notStrictEqual(actual, expected, message_opt);</source> 11. Expected to throw an error: <source>assert.throws(block, Error_opt, message_opt);</source> == Test == 12. The "test" module provides a "run" method that runs unit tests and catalogs their results. The "run" method must return the total number of failures, suitable for use as a process exit status code. The idiom for a self-running test module program would be: <source> if (module === require.main) require("test").run(exports); </source> 13. <tt>run</tt> must accept any <tt>Object</tt>, usually a unit test module's exports. "run" will scan the object for all functions and object properties that have names that begin with but are not equal to "test", and other properties for specific flags. Sub-objects with names that start with but are not equal to "test" will be run as sub-tests. A future version of this specification may add a mechanism for changing the mode of test functions from fail-fast (where failed assertions throw) to fail-slow (where failed assertions just log/print) via a <tt>logger</tt> argument or similar, but in the interim, this is implementation specific. <source> // ./sub-test exports.testPatience = function () { require('os').sleep(1000); }; </source> <source> // ./test exports.testSubTest = require("./sub-test"); </source> 14. Test names may be any String that begins with "test", not necessarily respecting a case convention. <source> [ [{"a": 10}, {"a": 10}], [[1, 2, 3], [1, 2, 3]] ].forEach(function (pair) { exports['test ' + pair[0].toSource()] = function () { assert.equal.apply(assert, pair); }; }); exports["test behaviour X"] = function() { behaviour.X() } </source> = Notes = == Custom Assert Modules == The assertions defined above will not be to everyone's taste style wise (or infact behaviour wise.) Authors are free to define their own assertion methods in new modules as desired. To make it possible to combine assertions from different modules in one test suite, all assert methods must throw a <tt>AssertionError</tt> (or something that is an <tt>instanceof AssertionError</tt>). Below is an example of how a custom assert module could be defined: <source> // file: my-check.js exports.check = function(actual) { return { is: function(expect, message) { if (actual != expect) throw new AssertionError({actual: actual, expected: expected, message: message}); }, } } </source> <source> // This would be used as follows: var check = require("my-check").check; exports.testSomething = function() { var sq = Math.pow(3, 2); check(sq).is(9, "3 squared is 9"); } </source> If future versions of this spec add a logger mechanism (with the intent of making it so that a failed assertion doesn't abort the above case) then the implementation above for <tt>check.is</tt> will need to be updated. == Implementations == # Narwhal, implemented by Zachary Carter. http://github.com/280north/narwhal/blob/master/lib/assert.js and http://github.com/280north/narwhal/blob/master/lib/test.js # Flusspferd, based largely on the Narwhal version. # SproutCore CoreTest - for the browser http://github.com/sproutit/core_test # v8cgi (from r766) # Wakanda == Unit Tests == # http://github.com/commonjs/commonjs/tree/master/tests/unit-testing/1.0/ == Show of Hands == [[Unit_Testing/A/Voting]] == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/2952de9982fc2b55 Unit Testing 1.0 Candidate] * [http://groups.google.com/group/commonjs/browse_thread/thread/77abf61133d26c22 Recount on Unit Testing API (was: Vote: use QUnit API or Unit Testing/A)] * [http://groups.google.com/group/commonjs/browse_thread/thread/236024c7269bc9ec Vote: use QUnit API or Unit Testing/A] * [http://groups.google.com/group/commonjs/browse_thread/thread/bf1e7ce55320f0b8 Revisiting "include" (was: QUnit and CommonJS)] * [http://groups.google.com/group/commonjs/browse_thread/thread/269253f5b713c5c5 QUnit and CommonJS] * [http://groups.google.com/group/commonjs/browse_thread/thread/daee7099261d8d9a Unit Testing A Show of Hands III] * [http://groups.google.com/group/commonjs/browse_thread/thread/77ca421f63017b3f Unit Testing Show of Hands II] * [http://groups.google.com/group/commonjs/browse_thread/thread/a0db8fb0a815a6fe Unit Testing, Testing for Missing "var"s.] * [http://groups.google.com/group/commonjs/browse_thread/thread/07c69484abc8a560 Unit Testing Show of Hands] 83 1964 2010-01-12T01:35:07Z Pbannister 65 '''STATUS: RATIFIED, FURTHER DISCUSSION''' = Web server to application interface = A well-defined interface for connecting web applications to web servers is a very powerful thing. This approach has enabled applications written with any Java framework, for example, to be deployed behind and Java server ("servlet container"). Additionally, the standard interface allows the creation of "middleware", or software that sits in between the server and the application. There are many useful applications for middleware (automatic application of site wide styling, caching and sessions, security). == Prior Art == * [http://ken.coar.org/cgi/ Common Gateway Interface (CGI)]. The base from most everything later derives. See [http://www.ietf.org/rfc/rfc3875 RFC 3875]. Still used widely, not performant. * [http://www.fastcgi.com/ FastCGI]. A performant minimal and very stable variant of CGI. Allows use of existing CGI code with minimal change. Note [http://www.iis.net/expand/FastCGI FastCGI in IIS] support is very important to some folk. * [http://en.wikipedia.org/wiki/Java_Servlet Java Servlets]. One of the first language-specific interfaces. * [http://www.python.org/dev/peps/pep-0333/ Web Server Gateway Interface] (Python). Very successful interface, but experience has shown that it's not 100% ideal. * [http://rack.rubyforge.org/ Ruby Rack]. An up and coming standard in Ruby that looks a lot like WSGI 2.0. * The Jack project provides a WSGI/Rack-like standard interface to webservers in JavaScript: http://jackjs.org * Comparison of current WebServer APIs used by JS engines: **[http://tr.im/http_ssjs_api HTTP incoming request JS APIs] == Proposed API == * 0.2: Proposal for JSGI specification: http://jackjs.org/jsgi-spec.html [ratified] * 0.3: <strike>[[/Level0/A|Level 0, Draft 1]]</strike> * 0.3: [[/Level0/A/Draft2|Level 0, Draft 2]] == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/43372363c819859b "Obviously stupid JS WSGI gateway"] * [http://groups.google.com/group/commonjs/browse_thread/thread/c548608ef3053303 JSGI Level 0 Proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/a1b8d29fb2436bc7 outstanding jsgi spec issues] * [http://groups.google.com/group/commonjs/browse_thread/thread/9c5d5712ef0d2e8d JSGI | Problem with response headers and middleware] * [http://groups.google.com/group/commonjs/browse_thread/thread/4c964dfeac6240e4 ATTN Jack users: JSGI spec change, response array changed to object] * [http://groups.google.com/group/commonjs/browse_thread/thread/b8365ffff2f4d634 JSGI Response change proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/7662580bb89fa991 another small jsgi request...] 84 2851 2010-07-14T03:47:56Z Astro 125 /* Prior Art */ xmppjs & node-xmpp = Jabber (XMPP) = The Jabber protocol is a popular, open protocol for real-time messaging and presence notification. == Prior Art == * Xmpp4Js is an XMPP client library written in pure Javascript http://xmpp4js.sourceforge.net/ * JSJaC - JavaScript Jabber/XMPP Client Library http://blog.jwchat.org/jsjac/ * Strophe - Javscript XMPP client library with excellent protocol support http://code.stanziq.com/strophe/ * xmppjs — Strophe for components on node.js: http://github.com/mwild1/xmppjs * node-xmpp — Asynchronous XMPP client/component library for node.js: http://github.com/astro/node-xmpp/ 85 1298 2009-09-17T10:39:41Z Bryanwb 12 {{DISPLAYTITLE:i18n}} i18n is an important need for web applications. JavaScript already has unicode string support, but the ability to localize information is important as well. Standardizing this might be difficult, but would likely be worthwhile because every high level web framework could use the same formats for string catalogs and the same API for currency display, etc. [[i18n Proposal A]] == Prior Art == * [http://www-01.ibm.com/software/globalization/icu/index.jsp ICU] * [http://babel.edgewall.org/ Babel] * Dojo has a variation of require called requireLocalization which loads a JSON bundle based on locale and offers a string substitution utility. Dojo also [http://bugs.dojotoolkit.org/browser/util/trunk/buildscripts/cldr transforms] a subset of the XML from [http://unicode.org/cldr Unicode CLDR], the same repository which drives [http://www-01.ibm.com/software/globalization/icu/index.jsp ICU], into something [http://bugs.dojotoolkit.org/browser/dojo/trunk/cldr JSON-like]. Dojo then implements its own Javascript based utilities on top of that for culturally-sensitive parsing and formatting. 88 813 2009-09-09T22:50:36Z Dantman 1 Redirected page to [[CommonJS]] #REDIRECT [[CommonJS]] 89 616 2009-09-09T22:29:28Z Dantman 1 moved [[ServerJS]] to [[CommonJS]]:&#32;Subpages needed to be enabled #REDIRECT [[CommonJS]] 90 1006 2009-09-10T03:16:57Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI]] 91 1005 2009-09-10T03:16:47Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/ProposalK]] 92 1011 2009-09-10T03:17:48Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/binary]] 93 1004 2009-09-10T03:16:37Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/binary/ProposalK]] 94 1012 2009-09-10T03:17:57Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/console]] 95 1003 2009-09-10T03:16:27Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/dict/ProposalK]] 96 1002 2009-09-10T03:16:17Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/file]] 97 933 2009-09-10T03:06:15Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Names]] 98 1013 2009-09-10T03:18:07Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/file/ProposalK]] 99 1008 2009-09-10T03:17:17Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/io/ProposalK]] 100 1009 2009-09-10T03:17:27Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/iter/ProposalK]] 101 1007 2009-09-10T03:17:07Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/list/ProposalK]] 102 1014 2009-09-10T03:18:18Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/posix/ProposalK]] 103 1016 2009-09-10T03:18:37Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/set/ProposalK]] 104 1015 2009-09-10T03:18:28Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/system]] 105 1010 2009-09-10T03:17:37Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[OldAPI/url/ProposalK]] 106 943 2009-09-10T03:08:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Binary]] 107 949 2009-09-10T03:09:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Binary/A]] 108 1161 2009-09-10T20:44:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Binary/B]] 109 1162 2009-09-10T20:44:12Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Binary/C]] 110 954 2009-09-10T03:09:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Binary/C/Essay]] 111 960 2009-09-10T03:10:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Binary/C/Show of hands]] 112 950 2009-09-10T03:09:12Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Binary/C/Unpacking]] 113 1158 2009-09-10T20:43:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[C API]] 114 937 2009-09-10T03:07:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Coding Standards]] 115 1154 2009-09-10T20:42:43Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Command Line]] 116 1165 2009-09-10T20:44:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Concurrency]] 117 1172 2009-09-10T20:45:53Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[CommonJS]] 118 1169 2009-09-10T20:45:22Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[DateTime]] 119 1152 2009-09-10T20:42:23Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Doctools]] 120 1174 2009-09-10T20:46:13Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Email]] 121 959 2009-09-10T03:10:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Encodings]] 122 940 2009-09-10T03:07:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Encodings/OldClass]] 123 1167 2009-09-10T20:45:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Existing APIs]] 124 939 2009-09-10T03:07:22Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[FAQ]] 125 1143 2009-09-10T20:40:51Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/A]] 126 962 2009-09-10T03:11:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem]] 127 956 2009-09-10T03:10:12Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/A]] 128 934 2009-09-10T03:06:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Hierarchy]] 129 961 2009-09-10T03:10:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Join]] 130 948 2009-09-10T03:08:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Names]] 131 951 2009-09-10T03:09:22Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Show of hands]] 132 1159 2009-09-10T20:43:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Future Efforts]] 133 1160 2009-09-10T20:43:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[HTTP Client]] 134 1171 2009-09-10T20:45:43Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[HTTP Client/A]] 135 1147 2009-09-10T20:41:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[High Level Tools]] 136 935 2009-09-10T03:06:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[IO]] 137 947 2009-09-10T03:08:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[IO/A]] 139 1137 2009-09-10T20:39:49Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Infrastructure]] 140 952 2009-09-10T03:09:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Introduction]] 141 1177 2009-09-10T20:46:43Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Logging]] 142 942 2009-09-10T03:07:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules]] 143 1149 2009-09-10T20:41:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/CompiledModules]] 144 1155 2009-09-10T20:42:53Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/Environment]] 145 1148 2009-09-10T20:41:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/GlobalFileLoading]] 146 1145 2009-09-10T20:41:11Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/GlobalObjectLoading]] 147 1142 2009-09-10T20:40:41Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/Loaders]] 148 1139 2009-09-10T20:40:11Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/Meta]] 149 1178 2009-09-10T20:46:53Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/PythonicModules]] 150 1138 2009-09-10T20:40:01Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/ScriptModules]] 151 1144 2009-09-10T20:41:01Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/SecurableModules]] 152 1166 2009-09-10T20:44:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Modules/Secure]] 153 1156 2009-09-10T20:43:03Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Packaging]] 154 945 2009-09-10T03:08:22Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Status]] 155 944 2009-09-10T03:08:12Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Process]] 156 1151 2009-09-10T20:42:13Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Promise Manager]] 157 1170 2009-09-10T20:45:33Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Promises]] 158 1141 2009-09-10T20:40:31Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[ProposalProcess]] 159 1175 2009-09-10T20:46:23Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[RDBMS]] 160 1153 2009-09-10T20:42:33Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Random Links]] 161 1173 2009-09-10T20:46:03Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Runtime Services]] 162 1163 2009-09-10T20:44:22Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Sockets]] 163 953 2009-09-10T03:09:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Status]] 164 957 2009-09-10T03:10:22Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[System]] 165 1164 2009-09-10T20:44:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[System]] 166 1176 2009-09-10T20:46:33Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[System/ArchivedShowOfHands]] 167 936 2009-09-10T03:06:52Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Target Platforms]] 168 1150 2009-09-10T20:42:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Unit Testing]] 169 1140 2009-09-10T20:40:21Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Unit Testing/A]] 170 1250 2009-09-12T04:54:50Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[JSGI]] 171 1157 2009-09-10T20:43:16Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[XMPP]] 172 1168 2009-09-10T20:45:12Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[I18n]] 173 814 2009-09-09T22:50:56Z Dantman 1 Created page with 'CommonJS' CommonJS 174 816 2009-09-09T22:51:46Z Dantman 1 moved [[CommonJS/FAQ]] to [[FAQ]] #REDIRECT [[FAQ]] 175 2477 2010-03-19T09:12:01Z Dantman 1 * SEARCH * navigation ** mainpage|mainpage ** implementations|implementations ** FAQ|FAQ ** http://groups.google.com/group/commonjs|Mailing List ** irc://irc.freenode.net/commonjs|IRC ** http://log.serverjs.org/mochabot/join|IRC Via Mochabot ** http://log.server-side-javascript.org/mochabot/|IRC Logs ** recentchanges-url|recentchanges ** randompage-url|randompage * TOOLBOX * LANGUAGES 176 2442 2010-03-19T06:57:24Z Dantman 1 div.mw-geshi { padding: 1em; margin:1em 0; border: 1px dashed #2fab6f; } .allpagesredirect a { background: url('http://wiki.commonjs.org/images/Allpagesredirect.gif') center left no-repeat; padding-left: 13px; font-style: italic; font-size: 90%; color: grey; } .hands { background: #f3f3f3 url('http://wiki.commonjs.org/images/Hands.png') top left; padding: 1em; margin: 1em 0; border: 1px dashed #2eabbc; } .hint { background-color: #eee; padding: .3em; margin: .2em 0; border: 1px dotted #ccc; } #firstHeading .website_link { float: right; font-size: .5em; text-shadow: grey 2px 2px 1px; } table.wikitable { margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; } table.wikitable th, .wikitable td { border: 1px #aaa solid; padding: 0.2em; } table.wikitable th { background: #f2f2f2; text-align: center; } table.wikitable caption { font-weight: bold; } 177 840 2009-09-10T02:14:52Z Dantman 1 moved [[CommonJS/Introduction]] to [[Introduction]] #REDIRECT [[Introduction]] 178 842 2009-09-10T02:14:55Z Dantman 1 moved [[CommonJS/Process]] to [[Process]] #REDIRECT [[Process]] 179 844 2009-09-10T02:14:58Z Dantman 1 moved [[CommonJS/Target Platforms]] to [[Target Platforms]] #REDIRECT [[Target Platforms]] 180 846 2009-09-10T02:15:01Z Dantman 1 moved [[CommonJS/Coding Standards]] to [[Coding Standards]] #REDIRECT [[Coding Standards]] 181 1660 2009-10-08T10:58:25Z Dantman 1 This proposal defines the '''''Stream''''' class portion of [[IO/B]]. Please also see [[Binary/C]] and [[IO/B/Stream/Level0]]. == Preamble == This proposal defines a Stream class which is completely generic. New types of streams can be made JavaScript side either by using the raw IO interface defined by IO/B/Raw, or by subclassing stream and borrowing methods directly defined on another stream. (The former permits streams built on other data sources which only require a simple raw api, and the latter permits Stream subclasses which simply munge data or arguments for certain methods or add new ones) The Stream class is intended to be extremely abstract makes no assumption to the capabilities of the underlying source of the data; Almost every operation works the same whether the stream is binary or text. Capabilities are duck-typed onto the Stream instead of defining separate types of streams. Access to a binary layer below a text layer is not assumed as streams may be implemented for any data source, and some of those data sources (Like a Stream that works on a StringBuffer) will already be text and thus will not support dual-layer text wrapped streaming. == Terminology == ;contentConstructor: ''See [[Binary/C]].'' ;sequence: ''See [[Binary/C]].'' ;''#'' units: A length measured in the relevant unit (Byte or Characters) for the given sequence type of the stream. == Class api == ;new Stream(Object def); :''(Only required by the base Stream class)'' :Creates a new generic stream instance using <code>def</code> as a object defining what the stream can do and how to do it using the [[../Raw|Raw io api]]. ;s.contentConstructor -> Function; :contentConstructor MUST return either <code>Blob</code> or <code>String</code> to indicate the underlying type of the stream content. ;s.canRead -> boolean; ;s.canWrite -> boolean; :''(canRead MAY not be present if the stream is not readable)'' :''(canWrite MAY not be present if the stream is not writeable)'' :Boolean getters indicating the readable state of the stream. :* canRead/canWrite should be false if read/write is not able to read/write data right away. :* canRead/canWrite should be true if read/write will return with data right away. :* canRead MUST NOT be false if EOF has been reached and read will return an EOF indication right away. :* canRead/canWrite MUST assume things are not blocked and return true if the underlying io api does not provide a mechanism to get this information. ;s.seenEOF -> boolean; :Boolean property indicating if EOF has been reached. :* .seenEOF must NOT be true before .read has returned an EOF indicator. ;s.position -> uint; :The current position within the stream. :* If <code>position</code> is so large that the number cannot be accurately represented (<code>p == p+1</code> is true) then <code>position</code> MUST return <code>Infinity</code>. :* <code>position</code> is measured in the same units as the type of sequence specified by .contentConstructor; :* <code>position</code> MUST work even when Stream is constructed without a position: key. :** This may be implemented by incrementing an internal position counter with lengths as .reads, .writes, .skips, etc... are performed, and modifying it along with a .seek where .tell should also include information that can reconstruct .the .position inside of an opaque cookie. ;s.read() -> ''Sequence''; ;s.read(uint max) -> ''Sequence''; :''(MUST not be present if the stream is not readable)'' :Reads data from the stream. :* .read MUST ONLY return sequences of the same type as .contentConstructor; :* If ''max'' is 0, negative or not a integer a TypeError SHOULD be thrown. :** 0 MAY be given a different error message as rather than being an invalid number the issue is you cannot read nothing. :* ''max'' is measured in the same units as the type of sequence specified by .contentConstructor; :* If ''max'' is omitted then .read buffers the entire stream then returns it's contents. :* If ''max'' is specified then .read will do a partial read. :** The resulting data MAY be of length ''max'' OR less than ''max'' but MUST have a length greater than 0. :* If EOF has been reached then .read should return an empty sequence of length 0. :* If max is <code>null</code> it should be set to 1 (?narwhal) ;s.skip(uint max) -> uint; :<del>''(MUST not be present if the stream is not readable)''</del> :Skips over data as if reading from the stream. :* If ''max'' is 0, negative or not a integer a TypeError SHOULD be thrown. :** 0 MAY be given a different error message as rather than being an invalid number the issue is you cannot skip nothing. :* ''max'' is measured in the same units as the type of sequence specified by .contentConstructor; :* .skip does partial skips behaving similarly to .read; :* .skip returns the number of units skipped in the skip. This number must be greater than 0. :* If EOF has been reached then .skip should return 0. :* .skip MUST be implemented on a readable stream even if not available in the underlying layer (it should use .read and discard the data if it needs to). ;s.write(''Sequence''|Buffer|''OpaqueRange'' data) -> ???; :''(MUST not be present if the stream is not writable)'' :Writes data to the stream. :* .write must fully write the data, it may not do partial writes. :* .write SHOULD attempt try to memcopy data. ;s.writePartial(''Sequence''|Buffer|''OpaqueRange'' data, [offset=0]) -> uint; :Writes data to the stream without blocking to wait for all the chunks to go through. :* .write MUST write at least 1 unit of data or block till it is permitted to write. :* .write returns the length of the data it wrote into the stream. The return value may be combined together and used as the offset to further calls. ;s.tell() -> ''OpaqueCookie''|uint; :Returns the location within the stream in a format that can be used later by .seek :* If this returns a Number it MUST be an integer indicating the location within the stream measured in the same units as the type of sequence specified by .contentConstructor; :** Therefore, if this returns a number it should be the same as <code>position</code>. :* An OpaqueCookie MUST contain enough information for .seek to later return to this location within the data and set .position back to the current state. :* An OpaqueCookie returned by this function is only valid for this stream. :* An OpaqueCookie returned by this function is invalid if a write has been made to a position in the stream before the location specified by this OpaqueCookie. ;s.seek(''OpaqueCookie''|uint to); :''(MUST not be present if the stream is not seekable)'' :Seeks to another location within the file. :* This method MUST accept any valid value outputted by .tell on the same stream. :* If an OpaqueCookie is used as input and a write was made to a location before the location specified by that OpaqueCookie in between the time .tell was called and .seek is called behaviour is not defined and will likely break. ;s.rewind(); :''(MUST not be present if the stream is not seekable)'' :Seeks to the very beginning of the stream. ;s.flush(); :Flushes data which may be buffered in this or an underlying stream :* If the underlying stream does not have a way to flush then this will be a no-op function. ;s.close(); :Closes the stream preventing any further reads or writes. :* This must remove any .read, .write, or .seek present on the stream object. == Requirements == Stream's constructor MUST be implemented such that <code>Stream.call(this, def);</code> within a function that has a .prototype that inherits from Stream.prototype will modify the object specified by <code>this</code> instead of constructing a new object. This requirement is defined so that subclasses of Stream may be made using the simple stub: <source> function StreamSubclass(o) { Stream.call(this, o); } StreamSubclass.prototype = new Stream(); </source> == Notes and comment bait == * Should we specify that the OpaqueCookie returned by .tell should respond to > and < calls (this can fairly easily be made to work using .valueOf) 182 1659 2009-10-08T10:58:17Z Dantman 1 This proposal defines the raw io interface portion of [[IO/B]]. Please also see [[Binary/C]] and [[IO/B/Stream/Level1]]. == Preamble == IO/B's streams are inspired by the InputStream/OutputStreams and Reader/Writers inside of Java's io system in which most classes only require you overload a method or two to provide the functionality for the rest of the methods in the class. IO/B/Stream defines the API for generic stream classes. This spec defines a raw io JS API which may reside on Object, be it a literal or a subclass. JavaScript side is may be simpler to just use an object Literal, but there is nothing stoping JavaScript or the underlying host language (C/C++/Java depending on the interpreter) from instead defining a new class type to handle raw IO for a specific type of data source. Every method in this api is optional, except for the contentConstructor which is required. Some operations are broken up into complementary methods. The Stream API MUST work arround missing methods by using the complementary method as a fallback. (For example, if readInto is implemented but not readChunk then to read just a chunk the Stream API must use readInto on a buffer then extract the chunk from there). If all methods from a set are missing then that signifies that the stream does not support a feature (ie: if readChunk and readInto are both missing, then read is not supported) The stream api makes no assumptions or requirements about the underlying data source of the stream. It may or may not be read buffered, and may or may not be write buffered, but SHOULD implement .flush to flush data if it is buffered. It may or may not use resources that can be closed but should use .close to clean up after itself. == The API == ;s.contentConstructor -> Function; :contentConstructor MUST return either <code>Blob</code> or <code>String</code> to indicate the underlying type of the stream content. ;s.read(Buffer buf, uint offset, uint max) -> uint; :Read data from the stream into a buffer. :* .read may only return 0 when EOF has been reached. :* <code>offset</code> denotes an offset within <code>buf</code> to start inserting at. :* <code>max</code> is measured in the same units as the type of sequence specified by .contentConstructor; :* .skip returns the number of units skipped in the skip. This number must be greater than 0. :* This SHOULD attempt to memcopy from data right into the buffer. ;s.skip(uint max); :Skip over a length of data in the stream as if it were read. :* APIs using this MUST not call .skip with anything other than a <code>max</code> integer greater than (NOT equal to) 0. :* .skip may only return 0 when EOF has been reached. :* <code>max</code> is measured in the same units as the type of sequence specified by .contentConstructor; :* .skip does partial skips behaving similarly to .read; :* .skip returns the number of units skipped in the skip. This number must be greater than 0. ;s.write(''Sequence''|Buffer|''OpaqueRange'' data) -> uint; :Write data from a sequence or buffer into a stream. Returns the amount of data from the data that was written. :* This SHOULD attempt to memcopy from data from the data source. ;s.flush(); :Flushes any write buffered data in this layer or any underlying data layer forcing it to be written. ;s.tell() -> ''OpaqueCookie''|uint; :Return the current location within the stream. :* If this returns a number it MUST be an integer indicating the location within the stream measured in the same units as the type of sequence specified by .contentConstructor; :* An OpaqueCookie MUST contain enough information for .seek to later return to this absolute location. :** This means that for a text layer backed by a binary position your OpaqueCookie MUST contain at least both the binary index AND the text index. :* An OpaqueCookie returned by this function is only valid for this stream. :* An OpaqueCookie returned by this function is invalid if a write has been made to a position in the stream before the location specified by this OpaqueCookie. ;s.seek(''OpaqueCookie''|uint to) -> uint; :Seeks to another location within the file. :* This method MUST accept any valid number or opaque cookie outputted by .tell on the same stream. :* If an OpaqueCookie is used as input and a write was made to a location before the location specified by that OpaqueCookie in between the time .tell was called and .seek is called behaviour is not defined and will likely break. :* .seek MUST return the new location in the stream measured int the same units as the type of sequence specified by .contentConstructor; :* If .seek and .tell make use of ''OpaqueCookie''s rather than numbers .seek MUST as a special case accept the number 0 in order to rewind to the beginning of the stream. ;s.close(); :Closes the stream. If this stream object uses any resources .close MUST be implemented to close or destroy those resources. :Implementations SHOULD try to call .close if the raw stream class is about to be destroyed. == Rationales == * Data sources may not always be binary (such as a stream that uses a string, string buffer, or other string api) so this api is written to work abstractly over either binary or textual data. * Data may not be stored in the same sequence type as it outputs (such as a text stream reading from a file which is binary), which do not have a 1 to 1 correspondence for this reason we use an ''OpaqueCookie'' sometimes so we can have an absolute location in both units at the same time. ** We do NOT specify this as ''OpaqueCookie'' on text mode because it's possible to have textual backings that are fine with working with character based indexes. == ToDo == * Identifying when read/write/etc... will block. * Do locks fit at this level? * truncate 183 851 2009-09-10T02:35:44Z Dantman 1 moved [[CommonJS/IO]] to [[IO]] #REDIRECT [[IO]] 184 853 2009-09-10T02:35:44Z Dantman 1 moved [[CommonJS/IO/A]] to [[IO/A]] #REDIRECT [[IO/A]] 185 855 2009-09-10T02:35:44Z Dantman 1 moved [[CommonJS/IO/B/Raw]] to [[IO/B/Raw]] #REDIRECT [[IO/B/Raw]] 186 857 2009-09-10T02:35:44Z Dantman 1 moved [[CommonJS/IO/B/Stream]] to [[IO/B/Stream]] #REDIRECT [[IO/B/Stream]] 187 1372 2009-09-20T02:13:13Z Dantman 1 ''Unfinished, in drafting'' IO/B defines an alternate proposal to [[IO/A]]. Focuses in IO/B are: * Abstract handling of binary and textual data * Flexibility and ease in defining new Stream types without needing to implement the entire complex api. * Streaming as a generic system which can apply to any sort of data source (file, socket, buffers, etc...) IO/B is broken up into separate sections: * [[/Buffer/]] - <code>require('io/buffer');</code> Buffer, StringBuffer, and BlobBuffer split out from [[Binary/C]] * [[/Filesystem/Level0/]] - Level 0 <code>require('io/filesystem/raw');</code> - Low level native access to the filesystem used to implement higher layers of filesystem access. * [[/Filesystem/Level1/]] - Level 1 <code>require('io/filesystem');</code> - ... * [[/Stream/Level0/]] - Level 0, api only (there is nothing to implement at this level) - Raw method base api used to give Stream access to data sources at the most basic level * [[/Stream/Level1/]] - Level 1 <code>require('io/stream');</code> - Implementable in pure JS * [[/Socket/]] - Level 1 <code>require('io/socket');</code> - ... 189 864 2009-09-10T02:47:05Z Dantman 1 moved [[CommonJS/Encodings]] to [[Encodings]] #REDIRECT [[Encodings]] 190 866 2009-09-10T02:47:06Z Dantman 1 moved [[CommonJS/Encodings/OldClass]] to [[Encodings/OldClass]] #REDIRECT [[Encodings/OldClass]] 192 870 2009-09-10T02:48:08Z Dantman 1 moved [[CommonJS/Binary]] to [[Binary]] over redirect #REDIRECT [[Binary]] 193 872 2009-09-10T02:48:08Z Dantman 1 moved [[CommonJS/Binary/A]] to [[Binary/A]] #REDIRECT [[Binary/A]] 195 1278 2009-09-15T01:53:12Z Dantman 1 :''See also: the [[/Show of hands/]] as well as the [[/Unpacking/]] and [[/Essay/]] portions which were removed.'' This proposal was written by Daniel Friesen as an alternative to the [[Binary/B]] proposal, it is accompanied by [[IO/B/Buffer]]. This proposal extends the Blob type that a number of existing Server-side JavaScript implementations use, and a Buffer type reflecting the StringBuffer/StringBuilder within Java. Instead of Binary/B's ByteArray, Binary/C defers to [[IO/B/Buffer]] to provide buffers. One goal of this proposal is interoperability between Strings and Blobs. That is, like Binary/B, this proposal aims to permit a class of generic algorithms that can operate on both Blob and String through a generic intersection between their API's. However, this proposal avoids things that seem counter-intuitive, like putting .charAt on a Blob, a byte collection. Instead, this proposal augments String with a .valueAt so that method can be used generically on both Blob and String and defers to IO/B/Buffer to provide a Buffer system which works on either type. This proposal and IO/B/Buffer is based off of API's drafted for MonkeyScript ([http://draft.monkeyscript.org/api/_std/Blob.html Blob] [http://draft.monkeyscript.org/api/_std/Buffer.html Buffer]). == Terms and reading notes == To avoid confusion and ambiguity these are the basic definitions of terms used within this document. ;List :A type which groups a series of items in a specific order. ;Sequence :A type of list which manages a list of fixed-unit pieces of data. :These units of data are normally either bytes or characters. "Sequence" is basically a term which refers generically to both Strings, Blobs/ByteStrings, and mutable counterparts like Buffer and whatnot. ;Array :A type of list which manages a list of items. These items are not related to one another in any way other than their inclusion in the list and do not need to be of the same type. :A key importance is an Array is a loose collection of items, these items do not have any sort of fixed unit to them. ;memcopy :Where used memcopy is used it refers to the technique of copying memory as directly as possible from one source to another. At the very least this refers to copying from A to B without creating an intermediate Blob. Where "as if by" is used in the spec the result is meant, the algorithm should not be affected by changes to the class' prototype. == Differences between a Sequence and an Array == While this may not be the case in lower level languages, JavaScript's API does make a clear distinction between strings and arrays. ;Units :A Sequence is built up of a list of single unit items. Whilst an Array is built up of unitless items, the array does nothing but point to objects, it contains nothing itself. The sequence "abc" is made up of 3 units { a, b, c } whilst [1,"asdf",3,{}] is made up of 4 items { 1, "asdf", 3, {} } with no relation to each other and no fixed units as we see two separate numbers in there, a 4 unit sequence inside of it, and an object which could have an indefinite hierarchy. ;Spillover :Depending on whether the type is a Sequence or an Array type functions such as .indexOf may "spill" or "overflow" over multiple items. Sequences spill, while Arrays do not spill. There is a subtle difference in the api between the two. :* sequence.indexOf(sequence, [offset]); :* array.indexOf(item, [offset]); :When using .indexOf on a sequence you give it another sequence. indexOf does not look for just a single item, but a sequence of items within that sequence. Contrasted to this, when using .indexOf on an array it ONLY looks for a single item and the search is unaffected by adjacent items. :This is apparent from how <code>"foobarbaz".index("bar");</code> returns the index of "bar" despite the fact that 'b', 'a', and 'r' are 3 units within this 9 unit long sequence (in this 1 unit being 1 character). While contrasted to this <code>[1,2,3,4,5].indexOf([2,3,4]);</code> does NOT return the location of the 2, 3, and 4 inside this array. The reason for this being that indexOf on an array is a single item operation, it does not spill lookup over into the following items. ;Pushing and Popping :Another point which does not get emphasised because strings are immutable in JavaScript and thus don't need methods to mutate them as Arrays do, is the semantics of .push, .pop, etc... :.pop() and .shift() remove ONE item from an array and return it. :As well given one argument .push() and .unshift() add ONE item to an array. :The key point here is [1,2,3].push([4,5,6]); does NOT turn the array into [1,2,3,4,5,6] it just adds the [4,5,6] as a sub array as so [123,[456]]. :You can give multiple arguments to these methods, but then you are no longer working with your lists in the same way. : :There is another name which does fit this kind of operation, "Append" (Side note, Wrench.js does add .append to Array). Using [1,2,3].append([4,5,6]); DOES push 4, 5, and 6 onto the array creating the array [1,2,3,4,5,6]. == The API == The two tiers of the api for this spec define two new classes. Blob (Fluspferd, Google, jslibs have all used this name, it's a fairly long-standing name and normally works similarly) and Buffer, and two subclasses of Buffer, StringBuffer and BlobBuffer. {{hands|=It is up to an implementation whether they wish to make Blob and Buffer native global objects, or seclude them inside of a binary module. Whether they are made global or not if the implementation implements require() then <code>require('binary');</code> must return an object containing Blob and Buffer as keys, even if the binary module is simply a module containing <code>exports.Blob = Blob; exports.Buffer = Buffer;</code>.}} === Blob === Blob is the binary counterpart to String, it has a slightly different API but has many similarities. A Blob is an immutable representation of a sequence of 8bit bytes. Most of the blob methods work on blobish data, rather than flat blobs. This means that the argument is treated as if it were passed through Blob(), thus .indexOf(255); is the same as if you had done .indexOf(Blob(255)), so you do not need to explicitly convert everything into a blob. Note that unlike String, Blob is not defined as a primitive datatype by ECMA, this means that typeof will never return 'blob' and all blobs will be objects unlike strings which are normally primitives. Blob works with and without the new constructor and acts the same. It is recommended to use the `Blob()` form ;[new] Blob(); :Construct an empty blob ;[new] Blob(number); :Construct a single unit blob, converting the number a byte. If the item is outside that range, not a number, or not an integer (has a decimal point) a TypeError should be thrown. ;[new] Blob(arrayOfNumbers); :Construct an blob the same length as the array, converting numbers 0..255 into bytes. If any item is outside that range, not a number, or not an integer (has a decimal point) a TypeError should be thrown. ;[new] Blob(blob); :Passes the blob through. ;[new] Blob(string, toCharset); :Construct a new blob with the binary contents of a string. The string will be encoded from the native UTF-16 charset into the charset specified by the <code>toCharset</code> argument and represented in the new blob in 8bit bytes. ;Blob.fromByteCode(code); ;Blob.fromCode(code); :Returns a new blob using a numeric byte code within the range 0..255. ;blob.contentConstructor; :Returns Blob to indicate this has binary content. ;blob.length; :Returns the length of the blob. This is immutable. ;blob.byteCodeAt(index); ;blob.codeAt(index); (@level1) :Extracts a single byte from the blob and returns it as a unsigned integer (Number) such that the number will be in the range 0..255. ;blob.concat(otherBlob, ...); :Combines the content of multiple blobs together and returns a new blob. ;blob.slice(begin, end); :Extracts a section of the blob and returns a new blob containing it as the contents. (This should behave the same as string.slice and array.slice) ;blob.indexOf(blob, offset=0); ;blob.lastIndexOf(blob, offset=0); :Returns the index within the calling blob object of the first or last (depending on which method is used) occurrence of the specified value, or -1 if not found. ;blob.byteAt(index); ;blob.valueAt(index); :Extracts a single byte from the blob and returns a new blob object containing only it. ;blob.split(); ;blob.split(separator); ;blob.split(separator, limit); :Splits the blob based on a sequence of bytes ({0 0 0 255 0 0} split by 255 would become [{0 0 0}, {0 0}]) and returns an array of blobs. This is the same as string.split except it does not support regular expressions. Like string.split this supports sequences of more than one unit (ie: You may split {0 0 255 0 0 255 3 0} by the blob {255 0} and get [{0 0}, {0 255 3 0}]) ;blob.toBlob([fromCharset, toCharset]); :If passed with no argument returns the same blob. :If passed with two charset arguments transcodes the data from one charset to the other and returns the data as a new blob. :Note that if a single argument is passed to this method it should throw a TypeError to prevent gotchas where someone runs .toBlob(charset) on a blob instead of a string where it is relevant. ;blob.toString(); :Returns a debug representation like "[Blob length=2]", where 2 is the length of the blob. Alternative debug representations are valid too, as long as (A) this method will never fail, (B) the length is included, (C) It is not only the representation of an implicitly converted string. ;blob.toString(fromCharset); :Converts the binary data in the blob from the charset specified by <code>fromCharset</code> to the native UTF-16 charset and returns a new string with that content. ;blob.toArray(); :Returns an array containing the bytes as numbers as if by <code>[ blob.byteCodeAt(i) for ( i in blob ) ]</code>. ;blob.toArray(fromCharset); :Returns an array containing the decoded Unicode code points as if by <code>var str = blob.toString(fromCharset); [ str.charCodeAt(i) for ( i in str ) ]</code>. ;blob.toSource(); :This method is optional, it should be included if the interpreter being used supports .toSource() on it's various objects and types. :Returns a representation of the blob in the format "(Blob([]))" or "(new Blob([]))". If the blob has content in it the string should contain integers 0..255 representing the blob such that if evaluated (calling the correct Blob function) would return a blob with the same content. === String ''extensions'' === ;string.contentConstructor; :Returns String to indicate this has text content. ;string.toBlob(toCharset); :Converts a UTF-16 string into the specified charset and returns a blob containing that binary data. ;string.valueAt(index); :An alias for string.charAt(index); :The point of this prototype is so that (string or blob).valueAt(index); may be used independently of whether the sequence is a string or a blob. This will allow strings to maintain .charAt and blobs to maintain .byteAt without returning unintuitive results while still allowing a method of working abstractly without relying on things like (str or blob)[index] which may not be implemented in some engines. ;string.codeAt(index); :An alias for string.charCodeAt(index); :The point of this prototype is so that (string or blob).codeAt(index); may be used independently of whether the sequence is a string or a blob. This will allow strings to maintain .charCodeAt and blobs to maintain .byteCodeAt without returning unintuitive results. ;String.fromCode(code); :And alias for String.fromCharCode(code); :The point of this prototype is so that (String or Blob).fromCode(code); may be used on .contentConstructor independently of whether the sequence is a string or a blob. This will allow calls to .codeAt to be returned to blob or string format abstractly. == Abstract API == One of the primary focuses was interoperability between Strings and Blobs so that abstract algorithms could be written which work on either strings or blobs. The entire Buffer api in IO/B/Buffer designed for this purpose, and the following methods on String and Blob are usable in abstract programming: * seq.length; * seq.contentConstructor (can be used as seq.contentConstructor() to return an empty seq of the same type) * seq.valueAt(idx); // Sequence at index * seq.codeAt(idx); // Number at index * seq.valueOf(); // Returns the same seq (on a buffer returns the equiv Blob or String) * seq.indexOf(seq, [off]); and seq.lastIndexOf(seq, [off]); // finding the location of a subsequence * seq.concat(...seq); // combining sequences together * seq.slice(begin, end); // extracting a portion of a sequence * seq.split(sep, [limit]); // split up a sequence using another sequence as a separator * ''Sequence''.fromCode(code); // return a single byte or single character based on a numeric code (Turning seq.codeAt(idx) back into a sequence) == Textual casting == This spec does not define any implementation requirements on it's own on the Blob(string, charset); and blob.toString(charset); methods. However it expects that they will behave the same as the [[encodings]] spec defines in regards to transcoding, character sets, and errors. == Notes == * A high priority in this proposal was String/Blob interoperability. While implicit string conversion was avoided it was important to make sure there was a api which could abstractly work with a sequence of data ignorant of whether the data was a string or a blob. ** .valueAt was added to string so that there was a common method for both blobs and strings without implementing a counterintuitive .charAt on blob. Note that as a result you can actually check .charAt vs .byteAt and string will only have .charAt, while blob will only have .byteAt. * Some experimentation with .valueOf needs to be done. .valueOf has type hinting (the first argument is a string hint of what type may be converted to, operators like > and < make use of it as well as a few other cases). It would be nice to see if it's possible to use the native < and > operators to compare blobs on their binary order. * For now things like .eq/equals, .lt, gt, etc... have been omited. Do note that Rhino actually implements .equals on String already. Also if we do add these things to blobs we should probably implement the same on strings. == Relevant discussion == * http://groups.google.com/group/commonjs/browse_thread/thread/3b0a3a20a67987d8 196 878 2009-09-10T02:48:08Z Dantman 1 moved [[CommonJS/Binary/C/Essay]] to [[Binary/C/Essay]] #REDIRECT [[Binary/C/Essay]] 197 880 2009-09-10T02:48:09Z Dantman 1 moved [[CommonJS/Binary/C/Show of hands]] to [[Binary/C/Show of hands]] #REDIRECT [[Binary/C/Show of hands]] 198 882 2009-09-10T02:48:09Z Dantman 1 moved [[CommonJS/Binary/C/Unpacking]] to [[Binary/C/Unpacking]] #REDIRECT [[Binary/C/Unpacking]] 201 891 2009-09-10T02:55:12Z Dantman 1 moved [[CommonJS/System]] to [[System]] #REDIRECT [[System]] 202 893 2009-09-10T02:55:15Z Dantman 1 moved [[CommonJS/Status]] to [[Status]] #REDIRECT [[Status]] 205 938 2009-09-10T03:07:12Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem]] 206 941 2009-09-10T03:07:42Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/A]] 207 964 2009-09-10T03:11:22Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Hierarchy]] 208 946 2009-09-10T03:08:32Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Join]] 209 955 2009-09-10T03:10:02Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Names]] 210 963 2009-09-10T03:11:12Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Show of hands]] 211 912 2009-09-10T02:59:11Z Dantman 1 moved [[Filesystem API]] to [[Filesystem]] #REDIRECT [[Filesystem]] 212 914 2009-09-10T02:59:11Z Dantman 1 moved [[Filesystem API/A]] to [[Filesystem/A]] #REDIRECT [[Filesystem/A]] 213 916 2009-09-10T02:59:11Z Dantman 1 moved [[Filesystem API/Hierarchy]] to [[Filesystem/Hierarchy]] #REDIRECT [[Filesystem/Hierarchy]] 214 918 2009-09-10T02:59:11Z Dantman 1 moved [[Filesystem API/Join]] to [[Filesystem/Join]] #REDIRECT [[Filesystem/Join]] 215 920 2009-09-10T02:59:11Z Dantman 1 moved [[Filesystem API/Names]] to [[Filesystem/Names]] #REDIRECT [[Filesystem/Names]] 216 922 2009-09-10T02:59:11Z Dantman 1 moved [[Filesystem API/Show of hands]] to [[Filesystem/Show of hands]] #REDIRECT [[Filesystem/Show of hands]] 217 928 2009-09-10T03:02:23Z Dantman 1 All show of hands pages on the wiki. [[Category:CommonJS]] 218 966 2009-09-10T03:13:33Z Dantman 1 Created page with '<div style="padding: 5px; margin: 2px 10px 7px; background-color: #ccc; text-align: center;"> This page and pages under it have become old and lost favor to other pages. </div>' <div style="padding: 5px; margin: 2px 10px 7px; background-color: #ccc; text-align: center;"> This page and pages under it have become old and lost favor to other pages. </div> 219 968 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API]] to [[OldAPI]] #REDIRECT [[OldAPI]] 220 970 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/ProposalK]] to [[OldAPI/ProposalK]] #REDIRECT [[OldAPI/ProposalK]] 221 972 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/binary]] to [[OldAPI/binary]] #REDIRECT [[OldAPI/binary]] 222 974 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/binary/ProposalK]] to [[OldAPI/binary/ProposalK]] #REDIRECT [[OldAPI/binary/ProposalK]] 223 976 2009-09-10T03:13:56Z Dantman 1 moved [[CommonJS/API/console]] to [[OldAPI/console]] #REDIRECT [[OldAPI/console]] 224 978 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/dict/ProposalK]] to [[OldAPI/dict/ProposalK]] #REDIRECT [[OldAPI/dict/ProposalK]] 225 980 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/file]] to [[OldAPI/file]] #REDIRECT [[OldAPI/file]] 226 1001 2009-09-10T03:16:06Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[Filesystem/Names]] 227 984 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/file/ProposalK]] to [[OldAPI/file/ProposalK]] #REDIRECT [[OldAPI/file/ProposalK]] 228 986 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/io/ProposalK]] to [[OldAPI/io/ProposalK]] #REDIRECT [[OldAPI/io/ProposalK]] 229 988 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/iter/ProposalK]] to [[OldAPI/iter/ProposalK]] #REDIRECT [[OldAPI/iter/ProposalK]] 230 990 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/list/ProposalK]] to [[OldAPI/list/ProposalK]] #REDIRECT [[OldAPI/list/ProposalK]] 231 992 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/posix/ProposalK]] to [[OldAPI/posix/ProposalK]] #REDIRECT [[OldAPI/posix/ProposalK]] 232 994 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/set/ProposalK]] to [[OldAPI/set/ProposalK]] #REDIRECT [[OldAPI/set/ProposalK]] 233 996 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/system]] to [[OldAPI/system]] #REDIRECT [[OldAPI/system]] 234 998 2009-09-10T03:13:57Z Dantman 1 moved [[CommonJS/API/url/ProposalK]] to [[OldAPI/url/ProposalK]] #REDIRECT [[OldAPI/url/ProposalK]] 235 1019 2009-09-10T03:47:10Z Dantman 1 Dumps of the wiki can be found at http://wiki.commonjs.org/dumps/. * [http://wiki.commonjs.org/pages.xml pages.xml]: A dump of only current revisions of pages in the main namespace with redirects omitted. Use this for archives and browseable dumps of the wiki. * [http://wiki.commonjs.org/current.xml current.xml]: A dump of the most recent revisions of all pages. Use this for bots. * [http://wiki.commonjs.org/full.xml fullxml]: A dump of all revisions of all pages. Use this for full wiki backups. 236 1025 2009-09-10T16:37:54Z Dantman 1 <div class=hands title="This block is waiting on a show of hands">{{{1|{{{ }}}}}}</div> 237 1028 2009-09-10T17:01:29Z Dantman 1 moved [[CommonJS/Binary/C]] to [[Binary/C]]:&#32;History merge #REDIRECT [[Binary/C]] 238 1036 2009-09-10T17:56:37Z Dantman 1 <source> // -*- coding: UTF-8 -*- /** * CommonJS Binary/C (Level 1) supplementary library */ Blob.fromCode = Blob.fromByteCode = function(code) { if(typeof code === "number") throw new TypeError("Byte codes must be numbers"); return new Blob(code); }; Blob.prototype.contentConstructor = Blob; Blob.prototype.codeAt = Blob.prototype.byteCodeAt; Blob.prototype.byteAt = Blob.prototype.valueAt = function(index) { return Blob(this.byteCodeAt(index)); }; Blob.prototype.split = function split(separator, limit) { if ( typeof limit !== "number" ) limit = Infinity; // @todo }; Blob.prototype.toBlob = function toBlob(fromCharset, toCharset) { if ( arguments.length === 0 ) return this; if ( arguments.length === 1 ) throw new TypeError("blob.toBlob passed with one argument. blob.toBlob was likely confused with string.toBlob"); return require('encodings').convert(fromCharset, toCharset, this); }; Blob.prototype.toString = function toString(fromCharset) { if ( arguments.length === 0 ) return "[Blob length=" + this.length + "]"; return require('encodings').convertToString(fromCharset, this); }; Blob.prototype.toArray = function toArray(fromCharset) { if ( fromCharset ) var str = this.toString(fromCharset); var arr = new Array(this.length); for(var i = 0, l = str.length; i<l; ++i) arr[i] = str.charCodeAt(i); return arr; } else { var arr = new Array(this.length); for(var i = 0, l = this.length; i<l; ++i) arr[i] = this.byteCodeAt(i); return arr; } }; Blob.prototype.toSource = function toSource() { return "(new Blob(["+this.toArray().join(', ')+"]))"; }; StringBuffer.prototype.contentConstructor = String; BlobBuffer.prototype.contentConstructor = Blob; Buffer.prototype.valueAt = function(index) { return this.contentConstructor.fromCode(this.codeAt(index)); }; Buffer.prototype.append = function append(data) { this.insert(data, Infinity); }; Buffer.prototype.insert = function insert(data, index) { this.splice(index, 0, data); }; Buffer.prototype.clear = function clear(start, length) { this.fill(start, length, this.contentConstructor.fromCode(0)); }; Buffer.prototype.fill = function fill(start, length, seq) { // @todo }; Buffer.prototype.replace = function remove(data, offset) { // @todo }; Buffer.prototype.remove = function remove(offset, length) { return this.splice(offset, length); }; Buffer.prototype.split = function split(separator, limit) { // @todo }; String.fromCode = String.fromCharCode; String.prototype.contentConstructor = String; String.prototype.toBlob = function toBlob(toCharset) { return require('encodings').convertFromString(toCharset, this.valueOf()); }; String.prototype.valueAt = String.prototype.charAt; String.prototype.codeAt = String.prototype.charCodeAt; </source> 239 1042 2009-09-10T19:55:20Z Dantman 1 moved [[CommonJS/C API]] to [[C API]] #REDIRECT [[C API]] 240 1044 2009-09-10T19:56:13Z Dantman 1 moved [[CommonJS/Runtime Services]] to [[Runtime Services]] #REDIRECT [[Runtime Services]] 241 1046 2009-09-10T19:56:17Z Dantman 1 moved [[CommonJS/Sockets]] to [[Sockets]] #REDIRECT [[Sockets]] 242 1048 2009-09-10T19:56:20Z Dantman 1 moved [[CommonJS/Command Line]] to [[Command Line]] #REDIRECT [[Command Line]] 243 1050 2009-09-10T19:56:23Z Dantman 1 moved [[CommonJS/Logging]] to [[Logging]] #REDIRECT [[Logging]] 244 1052 2009-09-10T19:56:26Z Dantman 1 moved [[CommonJS/RDBMS]] to [[RDBMS]] #REDIRECT [[RDBMS]] 245 1249 2009-09-12T04:54:38Z Dantman 1 Robot: Fixing double redirect #REDIRECT [[JSGI]] 246 1056 2009-09-10T19:56:33Z Dantman 1 moved [[CommonJS/Concurrency]] to [[Concurrency]] #REDIRECT [[Concurrency]] 247 1058 2009-09-10T19:56:35Z Dantman 1 moved [[CommonJS/Promises]] to [[Promises]] #REDIRECT [[Promises]] 248 1060 2009-09-10T19:56:43Z Dantman 1 moved [[CommonJS/Unit Testing]] to [[Unit Testing]] #REDIRECT [[Unit Testing]] 249 1062 2009-09-10T19:56:43Z Dantman 1 moved [[CommonJS/Unit Testing/A]] to [[Unit Testing/A]] #REDIRECT [[Unit Testing/A]] 250 1064 2009-09-10T19:59:52Z Dantman 1 moved [[CommonJS/HTTP Client]] to [[HTTP Client]] #REDIRECT [[HTTP Client]] 251 1066 2009-09-10T19:59:52Z Dantman 1 moved [[CommonJS/HTTP Client/A]] to [[HTTP Client/A]] #REDIRECT [[HTTP Client/A]] 252 1068 2009-09-10T19:59:54Z Dantman 1 moved [[CommonJS/Email]] to [[Email]] #REDIRECT [[Email]] 253 1070 2009-09-10T19:59:57Z Dantman 1 moved [[CommonJS/XMPP]] to [[XMPP]] #REDIRECT [[XMPP]] 254 1072 2009-09-10T19:59:59Z Dantman 1 moved [[CommonJS/i18n]] to [[I18n]] #REDIRECT [[I18n]] 255 1074 2009-09-10T20:00:03Z Dantman 1 moved [[CommonJS/Promise Manager]] to [[Promise Manager]] #REDIRECT [[Promise Manager]] 256 1076 2009-09-10T20:00:38Z Dantman 1 moved [[CommonJS/Infrastructure]] to [[Infrastructure]] #REDIRECT [[Infrastructure]] 257 1078 2009-09-10T20:00:42Z Dantman 1 moved [[CommonJS/High Level Tools]] to [[High Level Tools]] #REDIRECT [[High Level Tools]] 258 1080 2009-09-10T20:00:54Z Dantman 1 moved [[CommonJS/Random Links]] to [[Random Links]] #REDIRECT [[Random Links]] 259 1082 2009-09-10T20:00:55Z Dantman 1 moved [[CommonJS/Existing APIs]] to [[Existing APIs]] #REDIRECT [[Existing APIs]] 260 1084 2009-09-10T20:02:32Z Dantman 1 moved [[CommonJS/Packaging]] to [[Packaging]] #REDIRECT [[Packaging]] 261 1086 2009-09-10T20:02:34Z Dantman 1 moved [[CommonJS/Doctools]] to [[Doctools]] #REDIRECT [[Doctools]] 262 1088 2009-09-10T20:04:57Z Dantman 1 Redirected page to [[Binary/B]] #REDIRECT [[Binary/B]] 263 1090 2009-09-10T20:14:11Z Dantman 1 moved [[CommonJS/Future Efforts]] to [[Future Efforts]] #REDIRECT [[Future Efforts]] 264 1094 2009-09-10T20:15:13Z Dantman 1 moved [[CommonJS/DateTime]] to [[DateTime]] #REDIRECT [[DateTime]] 265 1098 2009-09-10T20:18:22Z Dantman 1 moved [[CommonJS/Current Efforts]] to [[CommonJS]]:&#32;Merge histories #REDIRECT [[CommonJS]] 267 1103 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules]] to [[Modules]] over redirect #REDIRECT [[Modules]] 268 1105 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/CompiledModules]] to [[Modules/CompiledModules]] #REDIRECT [[Modules/CompiledModules]] 269 1107 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/Environment]] to [[Modules/Environment]] #REDIRECT [[Modules/Environment]] 270 1109 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/GlobalFileLoading]] to [[Modules/GlobalFileLoading]] #REDIRECT [[Modules/GlobalFileLoading]] 271 1111 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/GlobalObjectLoading]] to [[Modules/GlobalObjectLoading]] #REDIRECT [[Modules/GlobalObjectLoading]] 272 1113 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/Loaders]] to [[Modules/Loaders]] #REDIRECT [[Modules/Loaders]] 273 1115 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/Meta]] to [[Modules/Meta]] #REDIRECT [[Modules/Meta]] 274 1117 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/PythonicModules]] to [[Modules/PythonicModules]] #REDIRECT [[Modules/PythonicModules]] 275 1119 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/ScriptModules]] to [[Modules/ScriptModules]] #REDIRECT [[Modules/ScriptModules]] 276 1121 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/SecurableModules]] to [[Modules/SecurableModules]] #REDIRECT [[Modules/SecurableModules]] 277 1123 2009-09-10T20:22:32Z Dantman 1 moved [[CommonJS/Modules/Secure]] to [[Modules/Secure]] #REDIRECT [[Modules/Secure]] 278 1126 2009-09-10T20:25:03Z Dantman 1 moved [[CommonJS/ProposalProcess]] to [[ProposalProcess]] #REDIRECT [[ProposalProcess]] 279 1128 2009-09-10T20:25:20Z Dantman 1 moved [[CommonJS/System/ArchivedShowOfHands]] to [[System/ArchivedShowOfHands]] #REDIRECT [[System/ArchivedShowOfHands]] 280 1130 2009-09-10T20:25:30Z Dantman 1 moved [[CommonJS/IO/B]] to [[IO/B]] #REDIRECT [[IO/B]] 281 1180 2009-09-10T21:37:59Z Dantman 1 Protected "[[File:Wiki.png]]": This will control the logo ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 282 1251 2009-09-12T05:02:15Z KrisKowal 6 fleshed out a description of the problem and discussed solutions. '''STATUS: DISCUSSION''' JavaScript runs on many engines with many variations of the standard global primordial objects, like <code>Object</code>, <code>Array</code>, and <code>Date</code>. Interoperable modules must be able to run on a wide variety of engines. To facilitate code sharing for components of a standard library and interoperable packaged libraries, each of these platforms need to make certain guarantees, a contract between library and engine. == Proposals == There have been no formal proposals. The discussed directions are informally: # ECMAScript 5. In so far as few engines support ES5 even partially, all present engine would fall short of compliance, with the intent of asymptotically approaching compliance by implementing ES5 or stubs that close the gap. # All those parts of ECMAScript 5 that are possible to emulate on most engines. For this proposal to be viable, someone will need to formalize the list of ES5 methods that would need to be emulated or stubbed in order to maintain compliance, and in what ways they may fail to function, like enumerability on object properties. Also, certain facilities of the languages would have to be forbidden to interoperable modules, like for name loops on Arrays. == Relevant Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/3cd154d53e312a65 Baseline ECMA version] * [http://groups.google.com/group/commonjs/browse_thread/thread/28acc7ed8855f537 Date.format proposal] 284 1903 2009-12-18T11:01:47Z Fgm 53 /* The default package */ typo '''STATUS: DISCUSSION''' This is a stub. Please fill me in. Regarding layout, metadata, management, catalogs, sources, loader extensions. == Design goals == * The [[Modules/SecurableModules]] specification must be supported. * The pattern of installing modules on a <tt>PATH</tt>-like structure, where there exists a knowledgeable administrator maintaining that <tt>PATH</tt>, must be supported. * Modules may be installed by existing tools, including those provided by operating system vendors, like <code>apt-get</code>. * Running code must be able to cause modules hitherto unknown to the system to be installed from the network and loaded on the fly. * Any namespace of modules must avoid name collisions even in the cases of (a) completely independent authors who have no pre-arranged cooperation; or (b) malicious authors who wish to mount a "substitution attack" by providing faulty modules under a previously used name. * Running code must be able to load, into the same CommonJS sandbox, more than one "version" of the "same" module, for reasonable definitions of "version" and "same". In other words, if CommonJS bakes in a module versioning scheme, it must not require that only one version be running in the same JavaScript VM, or even in the same sandbox. * It is preferable for CommonJS to not have a baked-in versioning scheme. * It must be possible to support CommonJS clients who have limited bandwidth or storage space. * The common case of module inclusion must be implementable synchronously; it must not require callbacks or promises. == Definition of a package == A ''package'' is a container holding a directory structure of JavaScript ''module''s, where each ''module'' is a contiguous piece of program text satisfying the ECMAScript <tt>Program</tt> production. In the following diagram, we show an example of a package and introduce our graphical notation. [[File:Packages-0.png]] The diagram shows one module, <tt>hashSet</tt>, <tt>require</tt>-ing another, <tt>hashMap</tt>, from the same package. To <tt>require</tt> a module from the same package, a module specifies its relative path within the package directory structure, as described under <b>Module Identifiers</b> in [[Modules/SecurableModules]]. == Package files == A ''package file'' is the interoperable exchange format for packages. Each package file is an archive (ZIP or TGZ) of a directory structure. For example, the following shows a typical, small package file: [[File:Packages-file.png]] Note the <tt>manifest.json</tt> file at the top (the contents of which we will discuss later), and the <tt>lib</tt> directory which contains a singly rooted hierarchy of CommonJS modules, each of which is a JavaScript file with an extension <tt>*.js</tt>. == The default package == A CommonJS installation is endowed by the system administrator or other out-of-band container with a repository of modules organized in a ''logical'' single-rooted hierarchy, similarly to a <tt>PYTHONPATH</tt>. These modules are part of the so-called ''default'' package. The default package is a local, logical construct and is not represented via an interoperable package file. A CommonJS installation may choose to run various tasks (e.g., command line shells) as though they were each a module in the default package. The modules in the default package are populated by initial installation of a CommonJS system; by operating system tools (such as <tt>apt-get</tt>); and by direct administrator involvement (such as editing environment variables and adding directories in the right places). The implementation of the default package, and the ways in which it is maintained, is outside the scope of CommonJS. However, CommonJS may specify some particular modules, with standardized paths, as minimal CommonJS requirements that must exist in the default package. In the following example, the default package is implemented as an ordered list of root directories containing JavaScript files. Imagine that <tt>/usr/local/commonjs/lib/</tt> was installed using <tt>apt-get</tt>, and <tt>/usr/local/commonjs/site-lib/</tt> contains local edits made by the Unix user. Note how standard PATH-like behavior, where the local <tt>strHash.js</tt> overrides the system-provided one, can be implemented easily. [[File:Packages-1.png]] == Package descriptors == A ''package descriptor'' is a set of instructions to the CommonJS runtime identifying a specific package file required by a client. It answers the questions: * Where can the CommonJS runtime find the package file; and * How can the runtime verify that it has fetched the correct one? The following describes a package available as a zipfile in two different locations, and asks that its checksum be verified: { locate: [ 'http://allmysoftware.com/archive/bar/bar_2.4.8.zip', 'http://barsoft.com/distros/bar_2.4.8.zip' ], verify: [ { checksum: '24f7c8cbf635f4c03bad2dde7bf07531', algorithm: 'md5' } ] } and the following provides a public key fingerprint, thus asking the CommonJS runtime to verify that the retrieved content has been signed by the corresponding private key: { locate: [ 'http://foosoft.com/public/latest/foo.zip' ], verify: [ { signature: 'c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87' algorithm: 'rsa-sha1' } ] } == Issuing <tt>require</tt> from the default package == In the following example, a module in the default package <tt>require.async()</tt>s a module specifying a module descriptor as the first argument. The local CommonJS runtime may or may not already have a copy of <tt>fontUtils.zip</tt>, but the application writer does not have to worry about that. The call is nonblocking, via <tt>require.async()</tt>, so the CommonJS runtime can issue a remote request for <tt>fontUtils.zip</tt> and satisfy the request whenever the data is downloaded and the signature verified. Also, the runtime may report any failures as part of the result of <tt>require.async()</tt>, and <tt>windowSystem.js</tt> can arrange to react to these failures. [[File:Packages-2.png]] In general, any <tt>require</tt>s from a module in the default package to a module in another package must specify the target package descriptor in this manner, and be asynchronous (thus using <tt>require.async</tt>). == Issuing <tt>require</tt> targeting the default package == A module in any package can <tt>require</tt> a module from the default package using the 2-argument form of <tt>require</tt> where the first argument is the string <tt>'default'</tt>. Access to the default package may or may not be permitted by the local CommonJS implementation but, if it is, this <tt>require</tt> will succeed: [[File:Packages-3.png]] It's important to note that no "search path" exists between packages. Therefore, if the module in <tt>fontUtils.zip</tt> failed to specify the package <tt>'default'</tt>, it would get nothing: [[File:Packages-3.5.png]] == General <tt>require</tt> between packages == In the most common case where a module to <tt>require</tt>s a module from another package: * The client package includes, in its <tt>manifest.json</tt>, a descriptor for the target package, and assigns that descriptor to a local alias; and * The client module mentions that alias in the 2-argument form of the <tt>require</tt> function. In the following example, package <tt>fontUtils.zip</tt> assigns an alias <tt>'bez'</tt> to some foreign package, and a module then uses it in <tt>require</tt>. [[File:Packages-5.png]] Note that a synchronous <tt>require</tt> is possible here, since the CommonJS runtime has a place to stand to introspect on <tt>fontUtils.zip</tt>, prefetch its dependencies, and only run the <tt>courier.js</tt> module of <tt>fontUtils.zip</tt> when it has fetched the dependency <tt>curve.js</tt>. == Additional notes == [[File:Packages-misc.png]] == Discussion == * [http://groups.google.com/group/commonjs/browse_thread/thread/9f73afe65dc33df7 modules packaging] 285 1224 2009-09-12T04:09:34Z Dantman 1 moved [[WSGI]] to [[JSGI]] #REDIRECT [[JSGI]] 286 1265 2009-09-13T08:18:43Z Dantman 1 moved [[IO/B/Raw]] to [[IO/B/Stream/Raw]] #REDIRECT [[IO/B/Stream/Raw]] 287 1665 2009-10-08T11:43:43Z Dantman 1 leaf -> node This proposal defines a <code>io/file/raw</code> module which acts as a level 0 module for filesystem access. This module is not meant for use in normal programming but instead acts as the lowest level layer between pure-JavaScript CommonJS code and native filesystem code. It is intended only for the purpose of providing a raw access layer that higher level modules may use to create file apis with. Some comments about this proposal are on the [[Talk:IO/B/Filesystem/Level0]] == Terminology == ;Node :A Node refers to an object which exists or does not exist on the filesystem, this is basically a path which irrelevant parts of (like the difference between / and \ on Windows) may be cleaned up but may not necessarily be a path string. ;''Opaque*'' :"''Opaque*''" is a piece of terminology (started in Filesystem/A) used to refer to a value of some sort which is implementation dependent. An Opaque value is one that only has a very small and specific set of defined behaviors, other than those there is no definition of how or what the implementation should use to create them. Something opaque can range in anything from an object literal, wrapped native data, a resource as a number, and so on... Inside a spec an Opaque value is NEVER introduced with something that requires dot notation (an Opaque is never expected to have the ability to look at a property on it), the only action used with an Opaque is to pass it as an argument to a function within the same implementation which will use it. == The module == The <code>io/file/raw</code> module accessed by <code>require('io/file/raw');</code> exports these functions: ;.pathToNode(string path) -> ''OpaqueNode'' :Returns an ''OpaqueNode'' that refers to a non-mutable path on the filesystem which may be used in methods within this module. :{{hint|Even if your native layer accepts path strings, rather than just passing the path string through this is a good place to clean up that path string into a format that your implementation expects. Like how NSPR expects / even on Windows, while others expect \ on Windows. You can clean up both / and \ to the separator your underlying layer is expecting of you, then return the cleaned up string.}} ;.nodeToPath(''OpaqueNode'' node) -> string :Returns the string path for a ''OpaqueNode'' (this may have been cleaned up in terms of separator conversion). ;.nodeToName(''OpaqueNode'' node) -> string :Returns the file name for an ''OpaqueNode''. ;.stat(''OpaqueNode'' node) -> ''OpaqueStat'' :Returns an ''OpaqueStat'' for the ''OpaqueNode'' specified by <code>node</code>. :Methods that use the ''OpaqueStat'' object are not guaranteed to not change between the time you call .stat and the time you call the method that uses the '''OpaqueStat'''. ;.canonical(''OpaqueNode'' node) -> ''OpaqueNode'' :Returns a ''OpaqueNode'' refering to the canonical ;.exists(''OpaqueStat'' stat) -> boolean :Tests for existence of the node on the filesystem. ;.size(''OpaqueStat'' stat) -> uint|false :Returns the size of the file specified by <code>stat</code>, or returns false. ;.isFile(''OpaqueStat'' stat) -> boolean|false ;.isDirectory(''OpaqueStat'' stat) -> boolean|false :Checks the <code>stat</code> to see if the node it refers to is a file or is a directory. :isFile and isDirectory may both return false if the node's path does not exist on the filesystem, or is a existing path on the filesystem that refers to something that is neither file nor directory. ;.lastModified(''OpaqueStat'' stat) -> Date|false :Returns the last modified time (mtime) of the file refered to by <code>stat</code> as a date or returns false. ;.setLastModified(''OpaqueNode'' node, Date time) -> boolean :Sets the last modified time (mtime) of the file refered to by <code>node</code>. ;.isReadable(''OpaqueStat'' stat) -> boolean ;.isWriteable(''OpaqueStat'' stat) -> boolean :Returns booleans indicating if the <code>stat</code> refers to a file that is readable or writable. ;.createDirectory(''OpaqueNode'' node, [boolean recursive=false]) -> boolean :Create a directory at the node specified by <code>node</code>. If <code>resursive</code> is specified this should attempt to create any parent directories instead of failing because they are missing. :Returns a boolean to indicate if it created the directory or failed. ;.listPaths(''OpaqueNode'' node) -> Array*string ;.listPathsByPath(''OpaqueNode'' node, Function pathCallback) -> Array*string ;.listNodes(''OpaqueNode'' node) -> Array*''OpaqueNode'' ;.listNodesByPath(''OpaqueNode'' node, Function pathCallback) -> Array*''OpaqueNode'' ;.listNodesByNode(''OpaqueNode'' node, Function nodeCallback) -> Array*''OpaqueNode'' ;.listNodesByStat(''OpaqueNode'' node, Function statCallback) -> Array*''OpaqueNode'' :List out the files within a directory. :* These methods will throw if used on a file or nonexistent directory. :* pathCallback(''OpaqueNode'' dir, string name); :* nodeCallback(''OpaqueNode'' dir, ''OpaqueNode'' node); :* statCallback(''OpaqueNode'' dir, ''OpaqueStat'' stat); ;.open(''OpaqueNode'' node, ''Object'' flags); :Opens a file in a mode specified by <code>flags</code> and returns a [[#Stream|stream]] in binary or text mode. :* .open will throw if used on a directory. :** <code>encoding</code>: A character encoding to use when opening this in text mode. If this is falsey (undefined, false, or absent) the file shall be opened in binary mode instead of text mode :** <code>read</code>: True if opening for read :** <code>write</code>: True if opening for write :** <code>append</code>: True if all writes should be made to the end of the file :** <code>truncate</code>: True if the system should truncate the file after opening :** <code>create</code>: True if the system should create the file instead of failing if it doesn't exist (only applies when opening for writing) :** <code>sync</code>: True if writes should synchronously wait for the os to write the data to disk ;.remove(''OpaqueNode'' node) -> boolean :Deletes the file or empty directory specified by <code>node</code>. Returns true or false to indicate if deletion worked or failed. ;.move(''OpaqueNode'' from, ''OpaqueNode'' to) -> boolean :Rename/moves the node specified by <code>from</code> to the location specified by <code>to</code>. == Stream == Streams returned by .open are defined by [[IO/B/Stream/Level0]] with the following additional requirements: * In binary mode .tell MUST return the location in bytes, not an OpaqueCookie. * Programs using streams opened by .open in text mode MUST expect .tell to return an OpaqueCookie rather than a position in characters. ** Actual implementations may use whichever works best for their implementation == Rationales == * Java and perhaps some other native abstractions use instances of a class or some other resource to non-mutably refer to a node on the filesystem, while others only use paths. For this reason we use an ''OpaqueNode'' which may take on an implementation dependent form. Java implementations could return a java.io.File object directly, implementations using a native layer that uses some sort of resource identifier could encapsulate that and return that as an ''OpaqueNode'', and implementations which use paths could simply return the path string. * Similarly posix systems usually provide a stat object, while systems like Java have separate lastModified, and such calls. For that reason we use an ''OpaqueStat'' which could be some sort of stat object, or even just return the ''OpaqueNode'' that was passed to it. * <code>ctime</code> is inconsistent. Windows records creation time, but not change time of metadata. Unix records change time of metadata, but not creation time of the file. Then there are filesystems like ZFS which have separate fields that record both. Additionally Java does not provide a means to access ctime without significant work using JNI or something like JNA to access this data at C/C++ level. The majority of applications also have little need for ctime info and at most only need mtime (lastModified). For these reasons combined any sort of ctime (lastChanged/creationTime) is not specified by this platform independent filesystem access spec. That should be specified separately in something such as a posix module meant for posix specific filesystem access. * While low level systems provide a directory open and read, Java only provides directory list* methods with Filename or File object filters. For this reason as a compromise we specify 4 separate directory listing methods, 3 of which can filter in different ways. * All native level systems so far do not provide a copy mechanism. For this reason copy is omitted at this level and expected to be implemented at a higher level. (If there are any systems that provide a high performance copy this could be changed). * .open at this level only specifies the raw things needed as a simple object. Any mode string parsing or more flexible object should be done in a higher level. * Some implementations may optimize binary->text using native layering rather than js based layering so text/binary modes are included in .open at this level and a .raw binary layer is not exposed in a text layer. == ToDo == * setCurrentWorkingDirectory. Should this use a path or a OpaqueNode? * Permission modification * Equivalence * comparison? * Hidden * Roots and filesystem space * isExecutable * Temp files / delete on exit 288 1533 2009-09-30T09:04:14Z Dantman 1 /* Notes */ This proposal defines a <code>io/buffer</code> module that defines 3 classes Buffer, StringBuffer, and BlobBuffer. This proposal depends on [[Binary/C]] and uses a lot of terminology from there, please reference Binary/C for more information. Binary/B originally defined a ByteArray, none of the prior art actually implemented a ByteArray as Binary/B proposes. Most implementations implemented a Blob type similar to Binary/B's ByteString, and any that implemented something called ByteArray actually implemented something more like a stream API based buffer rather than anything remotely resembling an Array. This proposal and Binary/C is based off of API's drafted for MonkeyScript ([http://draft.monkeyscript.org/api/_std/Blob.html Blob] [http://draft.monkeyscript.org/api/_std/Buffer.html Buffer]). == Prior art == Java's [http://java.sun.com/javase/6/docs/api/java/lang/StringBuffer.html java.lang.StringBuffer] is a very good reference for prior art. It is made for Strings rather than bytes, but nonetheless it's a api designed solely for the purpose of mutation of a string, not one designed for one purpose and hacked to suit another. Java's StringBuffer works using by append[ing](), insert[ing](), strings to grow the buffer. .delete() removes portions of the buffer, .indexOf() and .lastIndexOf() can search, .replace() and .reverse() are available, .length() shows the length of the data itself, .capacity() shows the current amount of memory allocated, and .substring can grab a substring from the StringBuffer. == The API == === Buffer''s'' === Buffers are accompanied by three classes; Buffer, StringBuffer, and BlobBuffer. Buffer itself is the generic class, making calls to it will normally create either a StringBuffer or a BlobBuffer. Both StringBuffer and BlobBuffer should inherit from Buffer and return true in a <code>buf instanceof Buffer</code>. Buffers may implement smart resizing in the background (ie: padding arrays or whatnot to sizes to avoid reallocating on each insert) but information on this is not available to the JavaScript API. Buffers will only take their own data type as arguments. If you try to insert a String into a BlobBuffer or a Blob into a StringBuffer a TypeError will be thrown. ;new Buffer(); :No-op... This simply creates an instance of Buffer. On it's own the Buffer class does nothing so this simply exists so that prototypes may be made that inherit from Buffer. ;new StringBuffer(); :Creates a new empty text buffer. ;new BlobBuffer(); :Creates a new empty binary buffer. ;new StringBuffer(len); :Creates a new text buffer of <code>len</code> size. ;new BlobBuffer(len); :Creates a new binary buffer of <code>len</code> size. ;new Buffer('''String'''); :Creates a new empty StringBuffer. ;new Buffer('''Blob'''); :Creates a new empty BlobBuffer. ;new Buffer('''String''', len); :Creates a new StringBuffer of <code>len</code> size. ;new Buffer('''Blob''', len); :Creates a new BlobBuffer of <code>len</code> size. ;new Buffer(string); :Creates a new StringBuffer with the same size and contents as the string. ;new Buffer(blob); :Creates a new BlobBuffer with the same size and contents as the blob. ;buf.length; ;buf.length = len; :Get or set the length of the buffer (For binary buffers this is number of bytes, for text buffers this is number of characters). :When length is set the buffer is dynamically resized. If shrunk it is truncated to size discarding items from the end. If grown the buffer is padded with 0 bytes for binary, and '\0' (null characters) for text. ;buf.contentConstructor; :Returns Blob from a BlobBuffer to indicate it has binary content, and String from StringBuffer to indicate it has text content. Implementations should make an effort to make this readonly. ;blob.codeAt(index); :Extracts a single byte from the blob and returns it as a unsigned integer (Number) such that the number will be in the range 0..255. ;buf.splice(offset, length, data, ...); :Remove a section of the buffer and insert chunks of data starting from the place it was removed from. If data is another Buffer memcopy should be used. ;buf.slice(); ;buf.slice(start); ;buf.slice(start, end); :Extract a subsection of the buffer and return it as a new sequence. (Behaves the same as the string and blob counterparts) ;<del>buf.copy(data, offset, length, [dataOffset]);</del> :Uses memcopy to copy a section of data directly into buf. data may either be another buffer of the same type, or a sequence (String/Blob) of same type as indicated by contentConstructor. ;buf.indexOf(sequence, offset=0); ;buf.lastIndexOf(sequence, offset=0); :Returns the index within the calling buffer object of the first or last (depending on which method is used) occurrence of the specified value, or -1 if not found. ;buf.valueOf(); :Return the non-mutable sequence for the buffer. :* In a BlobBuffer this returns a Blob which matches the contents of the buffer. :* In a StringBuffer this returns a String which matches the contents of the buffer. ;buf.valueAt(index); :Returns a string or blob representing the unit at a specified index. ;buf.append(data); :Append a chunk of data to the end of the buffer growing it by <code>data.length</code>. If data is another Buffer memcopy should be used. ;buf.insert(data, index); :Insert a chunk of data into a buffer growing it by <code>data.length</code> and shifting the data to the right of the specified index towards the end of the buffer. If data is another Buffer memcopy should be used. ;buf.clear(start, length); :Zero out a section of the buffer. Binary buffers have bytes replaced with 0 bytes and text buffers have characters replaced with '\0' (null characters). ;buf.fill(start, length, seq); :Zero out a section of the buffer. Binary buffers have bytes replaced with 0 bytes and text buffers have characters replaced with '\0' (null characters). ;buf.replace(data, index); :Insert data into the buffer starting from an index overwriting any existing bytes after that index up to the end of the data. Expands the buffer if necessary (<code>index + data.length > buf.length</code>). ;buf.remove(offset, length); :Remove a section of the buffer starting at <code>offset</code> and continuing for <code>length</code> units, shrinking it by <code>length</code>. ;buf.split(); ;buf.split(separator); ;buf.split(separator, limit); :Splits the buffer based on a sequence and returns an array of strings or blobs. (When used on text buffers this may or may not chose to support regular expressions) === ''Ranges'' === IO/B/Buffer supports an additional pattern for memcopy of data from one mutable or non-mutable sequence to another mutable sequence. This part of IO/B/Buffer extends Binary/B, native String, IO/B/Stream/Raw. Under this extension all Buffer and stream methods accepting a sequence type of data to be placed into the buffer/stream MUST accept an ''OpaqueRange'' and SHOULD memcopy that data. As well String, Blob, and Buffer MUST contain the additional method: ;.range(???, ???) -> ''OpaqueRange'' :Returns an ''OpaqueRange'' which can be used to memcopy the specified range of data from the sequence. ==== ''OpaqueRange'' ==== An ''OpaqueRange'' MUST contain enough information to reconstruct a specific range of data from the sequence .range was called on. Normally this may consist of the original sequence, and two numbers that can be used to determine what portion of the sequence to memcopy. Or could perhaps consist of the chunk of data itself in memory. An ''OpaqueRange'' is NOT required to remain safe after first use, and NOT required to provide valid data if not passed directly to a method for use. In short this means that the ONLY supported use of .range is a use such as <code>bufB.append(bufA.range(???, ???));</code> where you pass the range directly to a method like .append that uses it. The result of attempting to reuse a pre-used range or storing an ''OpaqueRange'' for any period of time is not defined, not supported, and may typically result in anything from errors, corrupt or unexpected data, to a segfault of the application. == Abstract API == Like [[Binary/C]], IO/B/Buffer is able to work abstractly on both strings and blobs. Every method on the Buffer classes is built abstractly. There are a number of useful code stubs: Create a new buffer with the same type as another form of data (be it a string, blob, another buffer, stream, or anything following the same contentConstructor rule). <source>var buf = new Buffer(data.contentConstructor);</source> Cast some data to the same type as the sequence type of a buffer (to string or to blob, or throw an error if bad data; good when writing Buffer prototypes): <source>buf.contentConstructor(data);</source> Create a new empty sequence of the same type as the sequence type of a buffer (empty string or blob, like what you'd return to signal EOF). <source>buf.contentConstructor();</source> Get a character or byte in sequence form of the same type as a buffer corresponding to a byte or character code. In this case, the most useful purpose is returning the 0 byte or null character for an operation like clearing data. <source>buf.contentConstructor.fromCode(0);</source> These are key to string/blob abstract programming and must be supported by implementations. == Notes == * Buffer was made independent of whether the data is binary or text. To avoid implicit string conversion TypeErrors are thrown when giving data of the incorrect type to a buffer. But you are still able to write code using buffer that works on either strings or blobs and doesn't care which mode it is in. ** Note how Buffer accepts <code>String</code> or <code>Blob</code> to determine it's data type. You could actually write code like <code>var buf = new Buffer(sequence.constructor);</code> and create a buffer based on the type of a sequence without checking what it is. 289 1285 2009-09-16T03:48:24Z Ihab 11 290 1371 2009-09-20T02:12:17Z Dantman 1 == Stream == Streams returned by .open are defined by [[IO/B/Stream/Level1]] with the following additional requirements: * In binary mode .tell MUST return the location in bytes, not an OpaqueCookie. * Programs using streams opened by .open in text mode MUST expect .tell to return an OpaqueCookie rather than a position in characters. ** Actual implementations may use whichever works best for their implementation ** This requirement is made so that == Notes == * autoflush "wf" support for .open so that every .write will .flush right after 291 1342 2009-09-19T04:02:47Z Bryanwb 12 /* Test Cases */ This proposal focuses on i18n for strings javascript code and strings in HTML files. It may be better described as a module rather than a standard. == Rationale == Basic internationalization is part of the standard library/platform. Good examples are [http://docs.python.org/3.1/library/gettext.html Python] and the [http://www.gnu.org/software/gettext/manual/gettext.html GNU platform]. Internationalization is frequently an afterthought for software developers so having a well-defined and simple API can ensure that applications can be internationalized without major refactoring. == Philosophy == The i18n mechanism should work in a client/server application and completely offline without any server-side emulation. This is distinctly different than how i18n works in web frameworks such as [http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html ruby-on-rails] and django. Most web frameworks use server-side html templates that replace translatable strings before sending the page to the client. This scheme does not work for offline applications. It also relies on html markup that is either invalid or unrenderable prior to pre-processing. It also makes the application very dependent a on a specific server-side handler and particular web server configuration. This document proposes an i18n mechanism without server-side dependencies and using valid html5 markup. It also proposes a mechanism that is as simple as possible and can be applied incrementally to an existing application. == Applicability == This specification is applicable to: * Marking strings in javascript code for translation * Marking strings in html for translation It is not applicable at this time to: * Common Locale Data Repository (CLDR) as exemplified in [http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap07.html POSIX locale] * internationalizing CSS attributes such as fonts and images == Basic Mechanisms == === Method for Marking Strings in javascript Code === 1. The Standard GNU Gettext method _("A translatable string"); Example: document.write(_("Translate me!")); 2. The same method within E4X Example: var navigationBar = <nav><button>{_("Go Back")}</button><button>{_("Reset")}</button></nav> ; === Method for Marking strings for Translation in HTML === Use the [http://www.whatwg.org/specs/web-apps/current-work/#custom-data-attribute data-*] collection of author-defined attributes in html5 Example 1. <nowiki><p data-_="true">To say hello in Spanish, say <span data-_="false">Hola</span></p></nowiki> Example 2. <nowiki><button data-_="true" data-_context="research">Compile Articles</button><!-- Somewhere else in same application --><button data-_="true" data-_context="computers">Compile Code</button></nowiki> '''Marking''' strings means that they will fetched from the translation .po files at run time and that collection script '''xgettext''' can be used to gather string for translation. === Storing and Retrieving Translations === The translations will be stored [http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files .po] files. PO (Portable Files) are well supported by online translation tools such as [http://translate.sourceforge.net/wiki/pootle/index Pootle]. xgettext is the standard tool for grabbing translatable strings from an application. CommonJS requires a js implementation of this tool. == Implementation == Here are the methods, attributes, global variable, and helper scripts I would like to see. It is primarily using Gettext.js === Methods === Pretty much entirely copied from [http://jsgettext.berlios.de/doc/html/Gettext.html#methods jsgettext] * new Gettext (args)textdomain( domain ) * gettext( MSGID ) * dgettext( TEXTDOMAIN, MSGID ) * dcgettext( TEXTDOMAIN, MSGID, CATEGORY ) * ngettext( MSGID, MSGID_PLURAL, COUNT ) * dngettext( TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT ) * dcngettext( TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT, CATEGORY ) * pgettext( MSGCTXT, MSGID ) * dpgettext( TEXTDOMAIN, MSGCTXT, MSGID ) * dcpgettext( TEXTDOMAIN, MSGCTXT, MSGID, CATEGORY ) * npgettext( MSGCTXT, MSGID, MSGID_PLURAL, COUNT ) * dnpgettext( TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT ) * dcnpgettext( TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT, CATEGORY ) * strargs (string, argument_array) strargs in particular will have to be modified to handle native numerals like १ २ ३ ४ ५ (1, 2, 3, 4, 5 in Nepali). Notably Arabic and Hindi use the standard numeric system (1-10) but different characters to represent the numbers === HTML5 Attributes === For specifying a String should be translated * data-translate="true|false" text for element should be translated * data-_="true|false" short form of the above * data-_C="true|false" grab all text from this element and all its children * data-_I="true|false" grab text AND all inline markup, then translators can decide whether <nowiki> <i> or <strong> </nowiki> are semantically meaningful in their language. This grabs all innerHTML and leaves it to the translators to decide * data-_comments="help explain meaning of text to be translated" <nowiki>example: <button data-_="true" data-_comments="File is used as verb">File</button></nowiki> * data-_ctxt -- Context -- to differentiate between different usage of the same word w/in the same document, particularly when those meanings do not have a synonym in a different language <nowiki>example: <button data-_="true" data-_context="research">Compile</button> <button data-_="true" data-_context="computers">Compile</button></nowiki> === Helper Functions === xgettext - w/ essentially the same options and function as [http://linux.die.net/man/1/xgettext gnu gettext], but w/ at least one new switch --report to indicate what percent of the application has been translated into other locales === Environment Variables === ALL_LINGUAS = "de en fr" this variable indicates what locales the application has translations for. === Relevant Files and directories === po/ for po files that contain translations POTFILES.in files that xgettext should grab strings from POTFILES.ignore files that xgettext should ignore application_name.pot locale_name.po translation of the application for a given locale == Test Cases == Sample text (Everything should be translated) Hello world Sample text with placeholder for dynamic data (The generated POT file should have the tags as well) Score : 0 Sample text with context (Everything should be translated, additionally the generated POT file should have two instances of "Compile Articles", with different msgctxt) Compile Articles Compile Articles Date and time (this should appear in local format, eg: শুক্র সেপ্টেম্বর 18 15:10:58 IST 2009) Numbered list (The numerals should be in native digits) # Hello world1 # Hello world2 # Hello world3 Right to left text - Direction and justification (left|right) should be preserved خطأ في مُغيّرات الألوان المحددة. == Further Reading == * [http://cldr.unicode.org/ Common Locale Data Repository] * [http://www.gnu.org/software/gettext/manual/gettext.html GNU Gettext Manual] * [http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap07.html How POSIX handles locale] 292 1334 2009-09-18T22:47:09Z Dantman 1 Dump of irc chat had about this subject. <poem> 22:47 <ashb> http://wiki.commonjs.org/wiki/Modules/Meta 22:47 <ashb> a few discussion points added 22:48 <kriskowal> going on about isMain again, eh? 22:49 <kriskowal> it *is* more concise for the common use case 22:49 <kriskowal> but i believe i already mentioned that require(require.main) is handy too 22:49 <ashb> for? 22:49 <kriskowal> e.g., self executing jack config files. i've done it. 22:49 <ashb> mmm lots of reasons i guess 22:49 <ashb> yeah 22:50 <ashb> exports.foo = ...; require('jackup'); and it just works 22:50 <kriskowal> actually, if (require.main == module.id) require("jackup").main([module.path]) 22:51 <kriskowal> words to that effect anyway 22:51 <ashb> so i guess if module.id and require.id are both speced to be 'absolute/always load same module' thats okay 22:51 <kriskowal> is that not explicated in the spec? 22:51 * kriskowal checks 22:51 <ashb> implied, but not stated 22:51 <kriskowal> top-level 22:51 <ashb> 'The "module" object must have an "id" that is the top-level "id" of the module.' 22:52 <ashb> is all it says about module.id 22:53 <ashb> kriskowal: what does main() do with the path? 22:53 <kriskowal> top-level isn't the same thing as absolute, but has the effect you're talking about. absolute id's are beyond spec, but it makes sense to make them absolute if they're outside the module id domain 22:53 <kriskowal> main takes system.args, or faux args 22:53 <ashb> kriskowal: yeah, i think the exact mechanism doesn't need to be specified, just hte intent that you get the right module 22:54 <ashb> k so for the jackup example isMain would work too 22:54 <kriskowal> right, so the question is whether you want two channels to the same data. 22:54 <ashb> yeah 22:54 <kriskowal> unless it's your expectation for isMain to be lazily evaluated on require.main == module.id 22:55 <ashb> but so far the only real example usage people have given me for require.main is what you've just shown 22:55 <kriskowal> or as a function call that closes on those values. 22:55 <ashb> if anyone can give me one real example i'll drop my quest for isMain :) 22:55 <ashb> kriskowal: i envisaged it as a ro prop rather than a fn 22:56 <kriskowal> suppose that you're in another module, and you want to see the main module's exports 22:56 <ashb> should probably make .main and .id perm, read-only properties 22:56 <kriskowal> in a system where the convention is for the main module to be a config file 22:56 <ashb> kriskowal: yeah that makes sense 22:57 <kriskowal> let's not take the "if nobody's doing it for real yet no one will ever want to" angle. the purpose of a language or library is to permit programs to be written unforseen by the creators of the language or library. 22:57 <ashb> i do wonder slightly if |require.main| is the wrong name/place for it tho 22:57 <ashb> kriskowal: this is true. but we also don't want to go the other way of specing everything just because it might be useful to someone 22:57 <kriskowal> the reasoning is that it's a place that works with many variations on the loader. 22:58 <ashb> but consider isMain dropped 22:58 <kriskowal> the idea is that sometimes "require" is a global object, and "module" is always a per-module object. 22:58 <kriskowal> although, in some loaders "require" is per-module too 22:59 <ashb> yeah i've switched it to per module in flusspferd 22:59 <ashb> cos the way we had it before broke JITing 22:59 <kriskowal> ihab pointed out that we could have conflated require and module using the same mechanisms in gpsee and helma that were used to discover the calling module for these other properties, but i don't intend to rock the boat. it's a little more readable anyway. 22:59 <ashb> kriskowal: so module.id should certainly be RO, and i guess require.main should be too? 23:00 <kriskowal> i certainly wouldn't expect things to work if it were assigned too 23:00 <ashb> what mechanism is that? 23:00 <kriskowal> i'm not intimate with the details, but i presume it was through dynamic scope traversal only possible from c 23:01 <ashb> okay. finaly comment on the proposal is i want to remove all mentions of 'sanbox' 23:01 <ashb> specifially i dont see why the spec mandates that those properties must not be present in a sandbox 23:02 <kriskowal> in a secure sandbox 23:02 <kriskowal> .paths discloses information about the structure of your file system and probably even your user name, increasing the attack surface of the system 23:03 <ashb> yes but there are many types of secure sandbox 23:03 <kriskowal> we should probably revisit the issue with security experts when we actually have a real sandbox to talk about. 23:03 <kriskowal> like, one :P 23:03 <ashb> thats kinda my thinking 23:04 <ashb> since 'a secure sandbox' might just mean loading no new code to one person 23:04 <ashb> where as it might mean 'no FS access at all and no info leak' to another 23:04 <kriskowal> that's where dependency injection comes in 23:05 <kriskowal> i haven't been able to do hermetic eval in narwhal yet, due to strangeness of rhino. can't wait to have a real Object.freeze et al 23:05 <ashb> yeah, in the first module.path is allowed 23:05 <ashb> but: 'The "path" property must not exist in a sandbox.' 23:06 <ashb> tbh i basically see (ultra-)secure sandboxes as a documented subset of commonJS 23:06 <kriskowal> it's a little more strict than that 23:07 <ashb> oh? 23:07 <kriskowal> if we're talking about modules and standard libraries, in the interest of real interoperability, those modules must work in a secure sandbox 23:08 <kriskowal> so, while engine specific components can be written in the context of commonjs related stuff, those modules are not commonjs compliant, and really can't be shared in the absolute sense 23:08 <kriskowal> i think the general idea is that application developers can do whatever they need, but we're promising that the standard library will work in a wide variety of contexts. 23:09 <ashb> yeah. i just dont like the fact we are mandating that something must not be possible in X, when we haven't really defined X 23:09 <kriskowal> it's better to be safe than future incompatible 23:10 <Wes_> Mmmm much better 23:10 * Wes_ was seeing stars 23:10 <kriskowal> that happens a lot in LA 23:10 <ashb> kriskowal: hmmm i guess you're right 23:11 <kriskowal> so, i think that Modules/Meta is ratified. i guess the status line never got updated. 23:11 <kriskowal> would you say that's okay? 23:11 <ashb> tho in this specific example (module.path) i can't see how forbidding an optional property could be incompatible 23:12 <ashb> kriskowal: whith one slight amendment as to the intent/behaviour of module.id/require.main 23:12 <kriskowal> perhaps explication of intent would be the right word. i think the normative text is as strict as we can make it without defining "absolute" 23:12 <ashb> just some verbage such as 'require.main can be passed to require() and loading the main program module' 23:12 <kriskowal> perhaps you can add something to the introduction or add a footnote 23:13 <kriskowal> ah, that would work 23:13 <ashb> and similar for module.id 23:13 <ashb> and i guess that the forms must be normalize so that .main == .id is true for the main script 23:13 <kriskowal> require(require.main) must return the exports of the main module 23:13 <kriskowal> require(module.id) must be equivalent to exports 23:14 <ashb> even when called from outside the current module 23:14 <kriskowal> even when passed through another module 23:14 <kriskowal> aye 23:14 <ashb> with those changes, yes i'm happy with it 23:14 * Wes_ is caught up 23:14 <kriskowal> i'd say go for it. 23:14 <Wes_> Not super happy with require.main -- but there isn't a better solution that doesn't involve polluting namespace: lesser of two evils wins 23:15 <kriszyp> so kriskowal, I sent you my work that I did on adding async/comet support to jack/narwhal. Is there anyone else I should send it to for review? 23:15 <Wes_> I'm also not happy with sandboxy "must not" -- but agree with KK pragmatism on subject 23:15 <ashb> Wes_: the other thing i thought was something on system module 23:15 <kriskowal> kriszyp: got email 23:15 <Wes_> ashb: possibly, but it doesn't seem like loading a module to get that seems reasomable either 23:15 <kriskowal> as far as i know tlrobinson isn't ready to evaluate promises. 23:15 <kriskowal> of course, neither am i :P 23:16 <ashb> Wes_: yeah it doesn't 22:47 <ashb> http://wiki.commonjs.org/wiki/Modules/Meta 22:47 <ashb> a few discussion points added 22:48 <kriskowal> going on about isMain again, eh? 22:49 <kriskowal> it *is* more concise for the common use case 22:49 <kriskowal> but i believe i already mentioned that require(require.main) is handy too 22:49 <ashb> for? 22:49 <kriskowal> e.g., self executing jack config files. i've done it. 22:49 <ashb> mmm lots of reasons i guess 22:49 <ashb> yeah 22:50 <ashb> exports.foo = ...; require('jackup'); and it just works 22:50 <kriskowal> actually, if (require.main == module.id) require("jackup").main([module.path]) 22:51 <kriskowal> words to that effect anyway 22:51 <ashb> so i guess if module.id and require.id are both speced to be 'absolute/always load same module' thats okay 22:51 <kriskowal> is that not explicated in the spec? 22:51 * kriskowal checks 22:51 <ashb> implied, but not stated 22:51 <kriskowal> top-level 22:51 <ashb> 'The "module" object must have an "id" that is the top-level "id" of the module.' 22:52 <ashb> is all it says about module.id 22:53 <ashb> kriskowal: what does main() do with the path? 22:53 <kriskowal> top-level isn't the same thing as absolute, but has the effect you're talking about. absolute id's are beyond spec, but it makes sense to make them absolute if they're outside the module id domain 22:53 <kriskowal> main takes system.args, or faux args 22:53 <ashb> kriskowal: yeah, i think the exact mechanism doesn't need to be specified, just hte intent that you get the right module 22:54 <ashb> k so for the jackup example isMain would work too 22:54 <kriskowal> right, so the question is whether you want two channels to the same data. 22:54 <ashb> yeah 22:54 <kriskowal> unless it's your expectation for isMain to be lazily evaluated on require.main == module.id 22:55 <ashb> but so far the only real example usage people have given me for require.main is what you've just shown 22:55 <kriskowal> or as a function call that closes on those values. 22:55 <ashb> if anyone can give me one real example i'll drop my quest for isMain :) 22:55 <ashb> kriskowal: i envisaged it as a ro prop rather than a fn 22:56 <kriskowal> suppose that you're in another module, and you want to see the main module's exports 22:56 <ashb> should probably make .main and .id perm, read-only properties 22:56 <kriskowal> in a system where the convention is for the main module to be a config file 22:56 <ashb> kriskowal: yeah that makes sense 22:57 <kriskowal> let's not take the "if nobody's doing it for real yet no one will ever want to" angle. the purpose of a language or library is to permit programs to be written unforseen by the creators of the language or library. 22:57 <ashb> i do wonder slightly if |require.main| is the wrong name/place for it tho 22:57 <ashb> kriskowal: this is true. but we also don't want to go the other way of specing everything just because it might be useful to someone 22:57 <kriskowal> the reasoning is that it's a place that works with many variations on the loader. 22:58 <ashb> but consider isMain dropped 22:58 <kriskowal> the idea is that sometimes "require" is a global object, and "module" is always a per-module object. 22:58 <kriskowal> although, in some loaders "require" is per-module too 22:59 <ashb> yeah i've switched it to per module in flusspferd 22:59 <ashb> cos the way we had it before broke JITing 22:59 <kriskowal> ihab pointed out that we could have conflated require and module using the same mechanisms in gpsee and helma that were used to discover the calling module for these other properties, but i don't intend to rock the boat. it's a little more readable anyway. 22:59 <ashb> kriskowal: so module.id should certainly be RO, and i guess require.main should be too? 23:00 <kriskowal> i certainly wouldn't expect things to work if it were assigned too 23:00 <ashb> what mechanism is that? 23:00 <kriskowal> i'm not intimate with the details, but i presume it was through dynamic scope traversal only possible from c 23:01 <ashb> okay. finaly comment on the proposal is i want to remove all mentions of 'sanbox' 23:01 <ashb> specifially i dont see why the spec mandates that those properties must not be present in a sandbox 23:02 <kriskowal> in a secure sandbox 23:02 <kriskowal> .paths discloses information about the structure of your file system and probably even your user name, increasing the attack surface of the system 23:03 <ashb> yes but there are many types of secure sandbox 23:03 <kriskowal> we should probably revisit the issue with security experts when we actually have a real sandbox to talk about. 23:03 <kriskowal> like, one :P 23:03 <ashb> thats kinda my thinking 23:04 <ashb> since 'a secure sandbox' might just mean loading no new code to one person 23:04 <ashb> where as it might mean 'no FS access at all and no info leak' to another 23:04 <kriskowal> that's where dependency injection comes in 23:05 <kriskowal> i haven't been able to do hermetic eval in narwhal yet, due to strangeness of rhino. can't wait to have a real Object.freeze et al 23:05 <ashb> yeah, in the first module.path is allowed 23:05 <ashb> but: 'The "path" property must not exist in a sandbox.' 23:06 <ashb> tbh i basically see (ultra-)secure sandboxes as a documented subset of commonJS 23:06 <kriskowal> it's a little more strict than that 23:07 <ashb> oh? 23:07 <kriskowal> if we're talking about modules and standard libraries, in the interest of real interoperability, those modules must work in a secure sandbox 23:08 <kriskowal> so, while engine specific components can be written in the context of commonjs related stuff, those modules are not commonjs compliant, and really can't be shared in the absolute sense 23:08 <kriskowal> i think the general idea is that application developers can do whatever they need, but we're promising that the standard library will work in a wide variety of contexts. 23:09 <ashb> yeah. i just dont like the fact we are mandating that something must not be possible in X, when we haven't really defined X 23:09 <kriskowal> it's better to be safe than future incompatible 23:10 <Wes_> Mmmm much better 23:10 * Wes_ was seeing stars 23:10 <kriskowal> that happens a lot in LA 23:10 <ashb> kriskowal: hmmm i guess you're right 23:11 <kriskowal> so, i think that Modules/Meta is ratified. i guess the status line never got updated. 23:11 <kriskowal> would you say that's okay? 23:11 <ashb> tho in this specific example (module.path) i can't see how forbidding an optional property could be incompatible 23:12 <ashb> kriskowal: whith one slight amendment as to the intent/behaviour of module.id/require.main 23:12 <kriskowal> perhaps explication of intent would be the right word. i think the normative text is as strict as we can make it without defining "absolute" 23:12 <ashb> just some verbage such as 'require.main can be passed to require() and loading the main program module' 23:12 <kriskowal> perhaps you can add something to the introduction or add a footnote 23:13 <kriskowal> ah, that would work 23:13 <ashb> and similar for module.id 23:13 <ashb> and i guess that the forms must be normalize so that .main == .id is true for the main script 23:13 <kriskowal> require(require.main) must return the exports of the main module 23:13 <kriskowal> require(module.id) must be equivalent to exports 23:14 <ashb> even when called from outside the current module 23:14 <kriskowal> even when passed through another module 23:14 <kriskowal> aye 23:14 <ashb> with those changes, yes i'm happy with it 23:14 * Wes_ is caught up 23:14 <kriskowal> i'd say go for it. 23:14 <Wes_> Not super happy with require.main -- but there isn't a better solution that doesn't involve polluting namespace: lesser of two evils wins 23:15 <kriszyp> so kriskowal, I sent you my work that I did on adding async/comet support to jack/narwhal. Is there anyone else I should send it to for review? 23:15 <Wes_> I'm also not happy with sandboxy "must not" -- but agree with KK pragmatism on subject 23:15 <ashb> Wes_: the other thing i thought was something on system module 23:15 <kriskowal> kriszyp: got email 23:15 <Wes_> ashb: possibly, but it doesn't seem like loading a module to get that seems reasomable either 23:15 <kriskowal> as far as i know tlrobinson isn't ready to evaluate promises. 23:15 <kriskowal> of course, neither am i :P 23:16 <ashb> Wes_: yeah it doesn't </poem> 293 1353 2009-09-19T23:59:53Z Mvalente 14 Headline Work [[User:Mvalente/SocketsA|SocketsA]] 294 1647 2009-10-06T23:13:35Z Mvalente 14 /* Sockets */ '''Proposal A, Draft 1 (in development)''' The "socket" module supports the Socket API, providing an interface for socket manipulation. For the purpose of this documentation, "soc" is a variable name for any object that implements the Socket API, including the exports of the "socket" module === Interface === ;var s = new Socket(family, type) :The Socket class is used to create a non-blocking TCP socket. *family = AF_INET (default), AF_INET6 or AF_UNIX. *type = SOCK_STREAM for TCP (default) or SOCK_DGRAM for UDP). Others (RAW, RDM, SEQPACKET)? ==== Sockets ==== The "socket" module must export the following: ;connect( host, port [, timeout] ) :Initiate a connection on a socket. Connect to a remote port on the specified host with a connection timeout. Throws an exception in case of failure. * host: IP address or hostname * port: port number or service name * timeout: timeout value (default X microseconds) ;accept() :Accept a connection on a socket. Returns a new (connected) Socket. ;bind( [host] [,port]) :When a new socket is created, it has no address bound to it. Bind assigns the specified address (also known as name) to the socket. Throws an exception in case of failure. * host: address (interface) to which the socket will be bound. If address is ommited, any address is will match. * port: port number or service name to which socket is to be bound. If port is undefined, the socket wont bind to any port. ;listen() : Listen for incoming connections on a socket (use before an accept). Throws an exception in case of failure. ;shutdown([what]) :Shut down part of a full-duplex connection on a socket. If [what] is SHUT_RD, further receives will be disallowed. If [what] is SHUT_WR further sends will be disallowed. If what is SHUT_RDWR, further sends and receives will be disallowed. * what: SHUT_RD, SHUT_WR or SHUT_RDWR ;close() : Close the socket immediately ;receive/read( [maxlen]) :Receive a block of bytes from the socket. Returns block of bytes read * maxlen: number of bytes to read. Default: X bytes ;send/write(data) : Send a block of bytes to the socket * data: block of bytes to send ;receiveFrom( [maxlen]) : Receive all data from socket. Returns object with ip_address and port of sender along with data properties * maxlen: number of bytes to read. Default: X bytes ;sendTo( host, port, data) : Send a block of data to a specific host and port * host: IP address or hostname * port: port number or service name * data: block of bytes to send ;sendFile(file) : Sends a complete File object across a socket. * file: a File object ;setOption( option, value) : Set socket option value to socket option name ;getOption() : Get socket option value, option should be socket option name ==== Tests ==== ;isConnected : Returns TRUE if the socket is in a connected state - READ ONLY ;isWritable : Returns TRUE if socket can accept written data - READ ONLY ;isReadable : Returns TRUE if data is waiting to be read from socket - READ ONLY ==== Metadata ==== ;localAddress : Get local socket IP address. Returns the IP address for this socket. ;localPort : Get local socket port number. Returns the port number for this socket. ;remoteAddress : Get remote socket IP address. Returns the IP address for this socket. ;remotePort : Get remote socket port number. Returns the port number for this socket. ;type : Socket type, SOCK_STREAM (TCP) or SOCK_DGRAM (UDP) 296 1415 2009-09-21T16:33:30Z Dantman 1 Redirected page to [[Sockets/A]] #REDIRECT [[Sockets/A]] 297 1363 2009-09-20T02:09:10Z Dantman 1 moved [[IO/B/Stream]] to [[IO/B/Stream/Level1]] #REDIRECT [[IO/B/Stream/Level1]] 298 1365 2009-09-20T02:10:42Z Dantman 1 moved [[IO/B/Filesystem/Raw]] to [[IO/B/Filesystem/Level0]] #REDIRECT [[IO/B/Filesystem/Level0]] 299 1367 2009-09-20T02:10:48Z Dantman 1 moved [[IO/B/Filesystem]] to [[IO/B/Filesystem/Level1]] #REDIRECT [[IO/B/Filesystem/Level1]] 300 1369 2009-09-20T02:10:52Z Dantman 1 moved [[IO/B/Stream/Raw]] to [[IO/B/Stream/Level0]] #REDIRECT [[IO/B/Stream/Level0]] 302 1413 2009-09-21T16:31:02Z Dantman 1 moved [[User:Mvalente/SocketsA]] to [[Sockets/A]]:&#32;History merge #REDIRECT [[Sockets/A]] 303 2551 2010-04-02T16:30:54Z Deanlandolt 15 needs a note to point people to recent version NOTE: the more recent version of this specification is [http://wiki.commonjs.org/wiki/JSGI/Level0/A/Draft2 Draft 2] JSGI Level 0 Proposal A, Draft 1 (in development) == Philosophy == * A straightforward but more user friendly mapping to existing gateway interface conventions * Suitable for extension via some forthcoming "Level 1" JSGI * Addressing all known shortcomings that would be difficult to correct with a "Level 1" layer (header name mangling, header case consistency, raw/decoded values) * Tweak to be JSGI more inline with javascript idioms (proper environment variable namespacing and dot access, mixedCase keys) == Principles == * Do not duplicate data in the request or response * Optimize for the application developer, not the server or middleware developer == Specification == === Applications === A JSGI application is a javascript function. It takes exactly one argument, the '''environment''', and returns a JavaScript Object containing three attributes: the '''status''', the '''headers''', and the '''body'''. === Request === The request environment must be a JavaScript Object instance that includes CGI-like headers. The application is free to modify the environment. The environment is required to include these variables (adopted from PEP333 and Rack), except when they would be empty (exceptions noted below): * '''.requestMethod''': The HTTP request method, such as "GET" or "POST". This MUST NOT be an empty string, and so is always required. * '''.scriptName''': The initial portion of the request URL's "path" that corresponds to the application object, so that the application knows its virtual "location". This MAY be an empty string, if the application corresponds to the "root" of the server. ''Restriction: if non-empty, MUST start with "/" and MUST be decoded.'' * '''.pathInfo''': The remainder of the request URL's "path", designating the virtual "location" of the request's target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash. ''Restriction: if non-empty, MUST start with "/" and MUST be decoded.'' * '''.queryString''': The portion of the request URL that follows the "?", if any. ''Restriction: MAY be empty but key MUST exist.'' * '''.serverName''', '''serverPort''': When combined with scriptName and pathInfo, these variables can be used to complete the URL. Note, however, that '''.headers.host''', if present, should be used in preference to serverName for reconstructing the request URL. ''Restriction: serverName and serverPort can never be empty strings, and so MUST be present.'' * '''.scheme''': URL scheme (per [http://www.ietf.org/rfc/rfc1738.txt RFC 1738]). "http", "https", etc. * '''.body''': The request body, which MAY be empty. ''Requirement: MUST be an input stream.'' Variables corresponding to the client-supplied HTTP request headers are stored in the '''.headers''' object. The presence or absence of these variables should correspond with the presence or absence of the appropriate HTTP header in the request. All keys in the '''.headers''' object MUST be the lower-case equivalent of the request's HTTP header keys. In addition to this, the request environment MUST include these JSGI-specific variables: * '''.jsgi''': ** '''.jsgi.version''': The Array [0,3], representing this version of JSGI. ** '''.jsgi.errors''': See below, the error stream. ** '''.jsgi.multithread''': true if the application object may be simultaneously invoked by another thread in the same process, false otherwise. ** '''.jsgi.multiprocess''': true if an equivalent application object may be simultaneously invoked by another process, false otherwise. ** '''.jsgi.runonce''': true if the server expects (but does not guarantee!) that the application will only be invoked this one time during the life of its containing process. Normally, this will only be true for a sever based on CGI (or something similar). JSGI server implementations are encouraged to include as much information in the request environment as possible. CGI-like keys ('''TODO''': define?) should be all lower case, except letters following the underscores, which should be upper case, with the underscore removed, and stored at the top level of the environment ('''TODO''': this wording sucks, somebody FIXME). These keys MUST have string values. <strike>Servers or applications can also store their own data in the request environment. In order to prevent collisions with unspecified CGI keys, custom keys MUST be stored in the '''.env''' top level object.</strike> === Input Stream === Must be an input stream. ('''TODO''' can we reference something in particular?) === Output Stream === Must be an output stream. === Response === ;.status :The status MUST be an integer greater than or equal to 100. ('''TODO''' changed from "if parsed as an integer" -- was this right?) ;.headers :The header MUST be a JavaScript object containing key/value pairs of Strings. All keys SHOULD be lower-case to prevent confusion. The header must not contain a Status key, contain keys with : or newlines in their name, contain keys names that end in - or _, but only contain keys that consist of letters, digits, _ or - and start with a letter. The values of the header must be Strings, consisting of lines (for multiple header values) separated by “\n”. The lines must not contain characters below 037. :* '''content-type''': There must be a Content-Type, except when the Status is 1xx, 204 or 304, in which case there must be none given. :* '''content-length''': There must not be a Content-Length header when the Status is 1xx, 204 or 304. Compliant Level 0 servers MUST accept header keys that are lower-case over keys that contain capital letters but are otherwise identical. Servers SHOULD ignore keys that contain capital letters. Servers MAY case-correct keys when serving the response in any manner. ('''TODO''': DL assumed this was decided but it's still up in the air -- if you have an opinion one way or another please show your hand here or on the mailing list) ;.body :The Body must respond to forEach and must only yield objects which have a toByteString method (including Strings and Binary objects) ('''TODO''': is this a dependency on the binary spec?). If the Body responds to close, it will be called after iteration. The Body commonly is an array of Strings or ByteStrings. == Summary of changes from [http://jackjs.org/jsgi-spec.html JSGI 0.2] == ''NOTE: this area is not aligned with proposals in the Open Issues section and is most certainly out of date.'' === Environment === ==== Top level keys ==== * UPPER_SNAKE_CASE to mixedCase * No alterations to key names themselves (env.REQUEST_METHOD to env.requestMethod, not env.method) * Server or application-specific environment keys no longer required to contain a "." to differentiate from CGI keys. Since CGI keys MUST be strings; added top-level keys in the environment MUST be objects. * CONTENT_LENGTH and CONTENT_TYPE moved into headers object and case-normalized (TODO: should content-length still be parsed down to an int?) === JSGI variables === * moved env["jsgi.URL_SCHEME"] to env["scheme"] (rationale: it's not a CGI key so no need to maintain consistency in naming) * moved env["jsgi.input"] to env["body"] (rationale: consistent with response object) * env["jsgi.*"] to env["jsgi"]["*"]; changed snake_case to mixedCase (technically, all lowercase) * lower_snake_case to mixedCase === Headers variables === * env["HTTP_*"] to env["headers"]["*"] * Header keys MUST NOT be mangled in any way, and must be set in lower-case form === Server or application variables: === * Instead of differentiating these by requiring a ".", we require added top-level keys to contain an object == Notes == The "jsgi" property only contains metadata related to JSGI itself, not HTTP, top level contains HTTP info. "input" is moved top level "body", and "url_scheme" is "scheme", like servlet's request. == Open questions == ;The "CGI" problem :JSGI server implementations built atop CGI SHOULD provide a truthy <code>.jsgi.cgi</code> parameter (in case we discover multiple levels of cgi FAIL) *DL: What should our NOTE FOR CGI IMPLEMENTERS say? They have to s/_/-/g header keys, for one. ;Response key casing :(a) lower-case :(b) UPPER-CASE :(c) Mixed-case :(d) specify a case-insensitive object :(e) unspecified *DL: (a) +1; (c), (d), (e) -1 ;Content-Length -- where should it appear? :(a) <code>.headers["content-length"]</code> as String :(b) <code>.contentLength</code> as integer, added by server if response is buffered :(c) Both *DL: (a) +1; (c) -1: including both would violate our principle of non-duplication ;Header modification :Should it be noted whether servers or applications are encouraged, discouraged or prevented from adding or modifying headers (e.g. .headers["content-length"])? Is there any rationale for preventing this (e.g. the headers SHOULD reflect the initial state of the request)? *DL: -1, I think it should stay unspecified ;More spec-like :Should we call out normative references where they have been codified for required environment variable? This would allow us to ''explicitly'' override them in specific cases (PATH_INFO, SCRIPT_NAME). *DL: +1: I'll add them -- they'll be easy to remove if this is a bad idea ;Response Reason :Specifying a ''.reason'' or ''.statusText'' on the response object would duplicate information. If this is necessary servers could provide a mechanism to make this happen -- does this merit a note? *DL: probably not: "The client is not required to examine or display the Reason-Phrase." -- [http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1 RFC 2616] ;Replacing the "request" object :Overwriting the "request" object with a new environment -- should this be explicitly disallowed? If L0 middleware does this it could break L1 middleware. But in order for L1 to exist on an L0 server it would need to wrap the request. The function of L1 doesn't belong in this discussion, but we should probably at least discuss the implications here. *DL: +1 on explicitly disallowing this ;Response object defaults :Should applications and middleware be REQUIRED to return a full response object -- status, headers and body? If not, middleware developers will always have to feature-test the response -- is this a problem? *DL: a related question is async testing promises ;Async :How much should we say about async usage patterns? Kris Zyp has gone into great detail on the list, discussions we could link to -- but what kind of normative language should the spec contain about async? ;Top-level env conflicts :When additional CGI keys are added to the environment, they should exist at the top level and be camelCased -- this opens the door to conflicts with user-added keys. How do we fix this? *DL: I've got a suggestion on the ML == Acknowledgements == This specification is adapted from the [http://rack.rubyforge.org/doc/files/SPEC.html Rack specification] written by Christian Neukirchen. Some parts of this specification are adopted from [http://www.python.org/dev/peps/pep-0333/ PEP333: Python Web Server Gateway Interface v1.0]. 304 1437 2009-09-23T21:32:54Z Ihab 11 uploaded a new version of "[[File:Packages-0.png]]" 305 1443 2009-09-23T21:54:33Z Ihab 11 306 1451 2009-09-23T23:03:06Z Ihab 11 307 1453 2009-09-23T23:10:17Z Ihab 11 308 1460 2009-09-23T23:27:01Z Ihab 11 309 1462 2009-09-23T23:30:26Z Ihab 11 310 1466 2009-09-23T23:49:59Z Ihab 11 uploaded a new version of "[[File:Packages-5.png]]" 311 1504 2009-09-28T04:12:58Z Ihab 11 uploaded a new version of "[[File:Packages-misc.png]]" 313 1502 2009-09-27T09:18:34Z Mikewse 9 removing 314 1530 2009-09-28T23:32:45Z Deanlandolt 15 /* Response */ Just reserving this page for some notes on L1 nice to haves: == Request == An object that can accommodate: * Header case-insensitive hash implementation * Cosmetic cleanups == Response == An object that can accommodate: * Automagical promise fulfillment * Header case-preservation hints * Reason message hints 315 1555 2009-10-04T05:25:18Z Dantman 1 # you still use OpaqueLeaf. as i mentioned before, Leaf bad term # all the listXXX functions are odd. #* a) can't list on a file either # open doesn't make sense on a dir # 2+3 imply to me that its worht separating into Dir only, File only, and common (Path or Entity) # isFile isn't always !isDir (fifo,socket, etc) # should probably have an lstat to go with your stat # createDir should die if it fails, not return false. # ditto for anything else that returns false on failure. (setLastModified) # lastModified returning a date or false is odd od odd. Date or undefined/null, or perhaps even die [[User:Ashb|Ashb]] 20:14, 3 October 2009 (UTC) :# couldn't come up with a new name yet :# listXXX are due to open/read/close dir not being portable (Java replaces them with a variety of list functions which can be filtered in different ways). :#* a) Course, it errors :# Course, it errors :# The other apis didn't exactly do it... and it's not really a common thing to do. I don't see a reason. Especially since this is level0. :# I know, I debated an isOther, thought !isFile !isDirectory would do, Java doesn't provide this either. I could make a note though. :# stat is lstat; stat and lstat work on file descriptors and paths, an Opaque in that api would be a path, file descriptors don't exist on opaques, file descriptors are used by streams, another stat would require a stat in the stream api. :# Java doesn't throw errors, what about other engines? Throwing an error when a directory you want to exist already exists sounds strange. :# I was avoiding custom errors at this level, this is a low level interface, IMHO not the place for custom errors that are hard to implement in JS engines. :# To match up with other methods :[[User:Dantman|Daniel Friesen]]05:25, 4 October 2009 (UTC) 316 2787 2010-05-23T23:58:21Z KrisKowal 6 corrected narwhal rhino version {{Spec |status=implementations, unresolved issues with permissions |implementations=Flusspferd, GPSEE, NarwhalNode=0.5, NarwhalRhino=8a45686, RingoJS }} The "fs-base" module exports a minimal, engine-specific interface for manipulating a file system and constructing raw byte streams. The [[IO|IO stream API]] is beyond the scope of this specification. It is the intent of this specification to provide exactly and only the components of a file system API that cannot be implemented in pure JavaScript. ''Pending the ratification of [[Filesystem/A]]: Implementations may opt to provide more methods, matching the interfaces specified in [[Filesystem/A]], if they can be implemented with better performance natively than in pure JavaScript based on the methods specified here.'' = Specification = == Types == Arguments used throughout this document will have the following types, unless explicitly specified otherwise: * '''path''' is either a String, an Object with a toString() method, or an Object with a valueOf() method that returns an Object with a toString() method. In the case where path is an Object, the object must return the same string for the same path on the same system, provided the path in canonicalizable. * '''mode''' is an Object describing the open mode for a file. Each property is subject to a true or falsey test. Meaningful properties include read, write, append, truncate, create, and exclusive. ''Note: any value is equivalent to false if the property is omitted.'' * '''permissions''' is an instance of Permissions, or a duck-type thereof. The "fs-base" module exports the following constructors: * '''Permissions''', a class that describes file system permissions. Instances of Permissions are initially deep copies of all transitively owned properties of Permissions.default and have a eponymous property for the optional "constructor" argument of the constructor. ** Mandatory properties on all platforms are Boolean values owner.read and owner.write. ** Mandatory properties on UNIX platforms platforms are Boolean values owner.{read, write, execute}, group.{read, write, execute} and other.{read, write, execute}. ** Permissions.default must initially reflect the current default file creation permissions in the host environment; i.e. in a UNIX environment, Permissions.default would reflect the inverse of umask. Where this is not possible, compliant implementations must initialize Permissions.default to {{owner: {read: true, write: true}} == Files == ; openRaw(path, mode, permissions) : returns a raw byte stream object with the given mode and permissions from the [[IO]] system. The details of this object are unspecified, except * it has a "close" method that closes any operating-system level resources allocated by "openRaw", and * the garbage collector must finalize the stream by performing an equivalent operation to the "close" method to prevent resource leaks. "openRaw" throws an exception when "path" cannot be opened, or "path" refers to a directory. * "openRaw" interprets the '''mode''' object's properties as follows ** '''read''': open for reading ** '''write''': open for writing ** '''append''': open for writing: the file position is set to the end of the file before every write. An exception is thrown when append is not used in conjunction with write. ** '''create''': create the file if it does not exist ** '''exclusive''': used only in conjunction with create, specifies that the if the file already exists that the open should fail. "openRaw" must implement "exclusive" with atomic file system primitives. "openRaw" must throw an exception when "path" is a symbolic link, and when "exclusive" is used without "create". ** '''truncate''': used only in conjunction with "write" or "append", specifies that if the path exists, it must be truncated (not replaced) by "openRaw". "openRaw" must throw an exception when "truncate" is used without "write". * When creating a file, the '''permissions''' object passed to "openRaw" is used as the argument to the Permissions constructor. The resultant Permissions instance is used to open this file. ; move(source, target) : Moves a file at one path to another. Failure to move the file, or specifying a directory for target when source is a file must throw an exception. * When the files are in the same file system, a compliant implementation must use the operating system's underlying atomic move or rename function to perform this operation. * When the files are not in the same file system, a compliant implementation may choose to copy-then-remove the original file. This behaviour is encouraged when there is technical means to accomplish this by system-wide atomic means. In the case where target is copied, a conforming implementation must ** Overwrite the target file if it exists ** Not create or alter an existing target file unless the entire operation succeeds ** Transfer permissions from source to target (failure to do so must throw) ** Make an effort to transfer ownership from source to target ** Preserve modification time from source to target (failure to do so must throw) ** Not remove the source file unless the entire operation succeeds (move does not throw) ; remove(path String) : Removes the file at the given path. Throws an exception if the path corresponds to anything that is not a file or a symbolic link. If "path" refers to a symbolic link, removes the symbolic link. ; touch(path, mtime_opt Date) : Sets the modification time of a file or directory at a given path to a specified time, or the current time. Creates an empty file at the given path if no file (special or otherwise) or directory exists, using the default permissions (as though openRaw were called with no permissions argument). If the underlying file system does not support milliseconds, the time is truncated (not rounded) to the nearest supported unit. On file systems that support last-accessed time, this must be set to match the modification time. Where possible, the underlying implementation should insure that file creation and time stamp modification are transactionally related to the same file, rather than the same directory entry. == Directories == ; makeDirectory(path, permissions_opt) : Create a single directory specified by ''path''. If the directory cannot be created for any reason an exception must be thrown. This includes if the parent directories of "path" are not present. The '''permissions''' object passed to this method is used as the argument to the Permissions constructor. The resultant Permissions instance is applied to the given path during directory creation. * Conforming implementations must create the directory with the exact permissions given, rather than applying the permissions after directory creation. In cases where this is not possible, the directory must be created with more restrictive permissions than specified, and a subsequent system call will be used to relax them. ; removeDirectory(path) : Removes a directory if it is empty. If path is not empty, not a directory, or cannot be removed for another reason an exception must be thrown. If path is a link and refers canonically to a directory, the link must be removed. ; move(source, target) : Moves a directory from one path to another on the same file system. Does not copy the directory under any circumstances. A conforming implementation must move the directory using the operating system's file-system-atomic move or rename call. If it cannot be moved for any reason an exception must be thrown. An exception must be thrown if "target" specifies an existing directory. : *Note*: this is the same method used to move files. The behaviour differs depending on whether source is a file or directory. == Paths == ; canonical(path) String : returns the canonical path to a given abstract path. Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path. This function is equivalent to joining the given path to the current working directory (if the path is relative), joining all symbolic links along the path, and normalizing the result to remove relative path (. or ..) references. * When the underlying implementation is built on a Unicode-aware file system, Unicode normalization must also be performed on the path using the same normal form as the underlying file system. * It is not required that paths whose directories do not exist have a canonical representation. Such paths will be canonicalized as "undefined". ''Note: this point has caused some argument, and the exact behaviour in this case needs to be determined.'' ; workingDirectory() String : returns the current working directory as an absolute String (not as an object with a toString method) ; changeWorkingDirectory(path) : changes the current working directory to the given path, resolved on the current working directory. Throws an exception if the operation failed. * ''Note: It is not required that this method call the operating system's underlying change-directory system call; virtualizing the appearance of a working directory at the level of this API to the JavaScript environment is sufficient for a compliant implementation. Module writers implementing modules in a language other than JavaScript (i.e. Java or C++) should take care when interoperating with this module.'' == Security == ; owner(path) String ; owner(path) Number ''optional'' : returns the name of the owner of a file with typeof string. Where the owner name is not defined, a numeric userId with typeof number may be returned instead. ; group(path) String ; group(path) Number ''optional'' : returns the name of the group owner of a file with typeof string. Where the group name is not defined, a numeric groupId with typeof number may be returned instead. This interface is optional but recommended when Permissions support a group member; the numeric interface shall not be implemented unless the String interface is implemented. ; changeOwner(path, name String) ; changeOwner(path, userId Number) ''optional'' : sets the owner of a given file or directory. If path is a symbolic link, the target file or directory is affected instead. Throws an exception if the operation fails for any reason (including that current user does not have permission to change the owner). This method must accept any return values from the "owner" method. ; changeGroup(path, name String) ; changeGroup(path, userId Number) ''optional'' : sets the group ownership of a given file or directory. If path is a symbolic link, the target file or directory is affected instead. Throws an exception if the operation fails for any reason (including that current user does not have permission to change the group). This method must accept any return values from the "group" method. This interface is optional but recommended when Permissions support a group member; the numeric interface shall not be implemented unless the String interface is implemented. ; permissions(path) Permissions : returns a Permissions object describing the current permissions for a given path. If path is a symbolic link, the returned permissions describe the target file or directory and not the link file itself. ; changePermissions(path, permissions Permissions) : sets the permissions for a given path. The '''permissions''' object passed to this method is used as the argument to the Permissions constructor. The resultant Permissions instance is applied to the given path if it is a file or directory; if path is a symbolic link it will be applied to the link target instead. == Links == Symbolic and hard links must not be emulated with Windows Shortcuts. On systems where symbolic links are not supported, symbolicLink and readLink must be undefined. On systems where hard links are not supported, hardLink must be undefined. ; symbolicLink(source, target) : creates a symbolic link at the target path that refers to the source path. Must throw an exception if the target already exists. Conforming implementations must not rewrite or canonicalize either the source or target arguments, nor validate that the link target exists, before passing to the underlying filesystem layer. ''Note: The intent is to allow users to create directory hierarchies with symbolic links that can be freely moved around a filesystem and maintain internal referential integrity.'' ; hardLink(source, target) : creates a hard link at the target path that shares storage with the source path. Throws an exception if this is not possible, such as when the source and target are on separate logical volumes or hard links are not supported by the volume. ; readLink(path) String : returns the immediate target of a symbolic link at a given path. Throws an exception if there is no symbolic link at the given path or the link cannot be read. This function differs from canonical in that it may return a path that itself is a symbolic link. == Tests == ; exists(path) : returns true if a file (of any type) or a directory exists at a given path. If the file is a broken symbolic link, returns false. ; isFile(path) : returns true if a path exists and that it, after resolution of symbolic links, corresponds to a regular file. ; isDirectory(path) : returns whether a path exists and that it, after resolution of symbolic links, corresponds to a directory. ; isLink(target) : returns whether a symbolic link exists at "target". Windows Shortcuts must not be equated with symbolic links. This function must not follow/resolve symbolic links. ; isReadable(path) : returns whether a path exists and that it could be opened for reading at the time of the call using "openRaw" for files or "list" for directories. ; isWriteable(path) : If a path exists, returns whether a file may be opened for writing, or entries added or removed from an existing directory. If the path does not exist, returns whether entries for files, directories, or links can be created at its location. ; same(pathA, pathB) Boolean : returns whether two paths refer to the same storage (file or directory), either by virtue of symbolic or hard links, such that modifying one would modify the other. In the case where either some or all paths do not exist, we return false. If we are unable to verify if the storage is the same (such as by having insufficient permissions), an exception is thrown. ; sameFilesystem(pathA, pathB) Boolean : returns whether two paths refer to an entity on the same filesystem. An exception will be thrown if it is not possible to determine this. * In the case where any path does not exist, we yield the same result as though it did exist, and that any necessary intermediate directories also exist as real directories and not symbolic links. == Attributes == ; size(path) Number : returns the size of a file in bytes, or throws an exception if the path does not correspond to an accessible path, or is not a regular file or a link. If path is a link, returns the size of the final link target, rather than the link itself. : Care should be taken that this number returned is suitably large (i.e. that we can get useful figures for files over 1GB (30bits+sign bit). If the size of a file cannot be represented by a JavaScript number, "size" must throw a RangeError. ; lastModified(path) Date : returns the time that a file was last modified as a Date object. == Listing == ; list(path) Array * String : returns the names of all the files in a directory, in lexically sorted order. Throws an exception if the directory cannot be traversed (or path is not a directory). : ''Note: this means that <code>list("x")</code> of a directory containing <code>"a"</code> and <code>"b"</code> would return <code>["a", "b"]</code>, not <code>["x/a", "x/b"]</code>.'' ; iterate(path) Iterator * String : returns an iterator that lazily browses a directory, backward and forward, for the base names of entries in that directory. === Iterator Objects === Iterator objects have the following members: ; next() String or Path : returns the next path in the iteration or throws "StopIteration" if there is none. ; iterator() : returns itself ; close() : closes the iteration. After calling close, all calls to next and prev must throw StopIteration. == Extended Attributes (optional) == Extended attribute methods may be defined on systems that may support the feature on some volumes. See [http://en.wikipedia.org/wiki/Extended_file_attributes]. ; getAttribute(path, key String, default ByteString) ByteString : Gets the value of an extended attribute. If a third argument is provided, including undefined, and there is no corresponding extended attribute for the requested key, the default is returned. Otherwise, if there is no extended attribute for the requested key, getAttribute must throw an exception. Throws a ValueError if the volume does not support extended attributes. ; setAttribute(path, key String, value ByteString) : Sets an extended attribute. Throws a ValueError if the volume does not support extended attributes. ; removeAttribute(path, key String) : Removes the extended attribute for a given key. If there is no corresponding key, throws an exception. Throws a ValueError if the volume does not support extended attributes. ; listAttributeNames(path) Array * String : returns an Array of Strings of the keys of all extended attributes on a given path. Throws a ValueError if the volume does not support extended attributes. == Unicode == * Filesystems which are Unicode-compatible shall have their file names seamlessly translated to and from Strings containing UTF-16BE or UTF-16LE, depending on the native architecture. * Filesystems which are not Unicode-compatible shall have file names represented in JavaScript strings such that all unique filenames generate unique Strings, and all values returned by the index() method are suitable for use as a path. = Notes = * Conformant implementations working on ''path'' must not alter the permissions of ''path'''s parent directory to complete an operation, even if altering the permissions of the parent directory would be necessary for the operation to succeed. The following topics have been deferred for a future specification: * locking * access control lists (ACL's) * temporary files and directories = Implementations = * Trial implementation in Flusspferd (no permissions support yet) * Trial implementation in GPSEE = Related Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/150ff8f33d4810ea Minimal Filesystem API] 317 1664 2009-10-08T11:11:02Z Dantman 1 <div class=hint>'''Hint:''' {{{1|{{{ }}}}}}</div> 318 2115 2010-02-19T01:28:09Z KrisKowal 6 /* Must throw error */ == Show of Hands == === Assertion === * assert.assert(actual, message_opt) ** Tom Robinson ** Ash Berlin ** Kris Kowal * assert.is(true, actual, message_optl) ** George Moschovitis ** Raphael Speyer * assert.isTrue(actual, message_opt) ** Neville Burnell ** Chris Zumbrunn ** Nathan Stott * assert.ok(action, message_opt) ** Dean Landolt === Deep equivalence assertion === * none * assert.eq(expected, actual, message_opt) ** Kris Kowal ** Ash Berlin ** Ates Goral * assert.equal(expected, actual, message_opt) ** Hannes Wallnöfer ** George Moschovitis ** Dean Landolt ** Raphael Speyer * assert.isEqual(expected, actual, message_opt) ** Chris Zumbrunn ** Nathan Stott * assert.equals(expected, actual, message_opt) * assert.equiv(expected, actual, message_opt) * assert.equivalent(expected, actual, message_opt) === Deep non-equivalence assertion === * none * assert.notEqual(expected, actual, message_opt) ** Hannes Wallnöfer ** George Moschovitis ** Chris Zumbrunn ** Dean Landolt * assert.ne(expected, actual, message_opt) ** Kris Kowal ** Ates Goral ** Ash Berlin * assert.neq(expected, actual, message_opt) ** Ates Goral * assert.notEqual(expected, actual, message_opt) * assert.notEquals(expected, actual, message_opt) * assert.notEquiv(expected, actual, message_opt) * assert.notEquivalent(expected, actual, message_opt) * assert.not.eq(expected, actual, message_opt) * assert.not.equal(expected, actual, message_opt) ** Dean Landolt ** Nathan Stott ** Raphael Speyer === Object identity assertion === * assert.same(expected, actual, message_opt) ** Hannes Wallnöfer ** Dean Landolt ** Nathan Stott ** Raphael Speyer * assert.is(expected, actual, message_opt) ** Kris Kowal ** Ash Berlin * assert.isIdentical(expected, actual, message_opt) ** Chris Zumbrunn * assert.identical(expected, actual, message_opt) === Object non-identity === * none * assert.notSame(expected, actual, message_opt) ** Hannes Wallnöfer ** Dean Landolt * assert.isnt(expected, actual, message_opt) ** Ash Berlin ** Ates Goral * assert.ni(expected, actual, message_opt) * assert.notIdentical(expected, actual, message_opt) ** Chris Zumbrunn * assert.not.same ** Dean Landolt ** Nathan Stott ** Raphael Speyer === Must throw error === * none * assert.throws ** Hannes Wallnöfer ** Ash Berlin ** George Moschovitis ** Chris Zumbrunn ** Dean Landolt * assert.error ** Kris Kowal === Arguments === # (A) making (message, guard) and (guard) the accepted argument forms. #* Daniel Friesen # (B) making (guard, message) and (guard) the accepted argument forms. #* Ash Berlin #* Mark Porter #* Kris Kowal #* George Moschovitis #* Hannes Wallnöfer # (X) make the assertion message mandatory. #* # (Y) make the assertion message optional. #* Ash Berlin #* Kris Kowal #* Mark Porter #* George Moschovitis #* Hannes Wallnöfer 319 1690 2009-10-16T04:42:39Z KrisKowal 6 moved [[Unit Testing/A]] to [[Unit Testing/1.0]]:&#32;ratification #REDIRECT [[Unit Testing/1.0]] 320 1692 2009-10-16T04:42:39Z KrisKowal 6 moved [[Unit Testing/A/Voting]] to [[Unit Testing/1.0/Voting]]:&#32;ratification #REDIRECT [[Unit Testing/1.0/Voting]] 321 1695 2009-10-16T04:56:09Z KrisKowal 6 moved [[Modules/SecurableModules]] to [[Modules/1.0]]:&#32;ratification #REDIRECT [[Modules/1.0]] 322 1697 2009-10-16T04:56:52Z KrisKowal 6 moved [[System]] to [[System/1.0]] #REDIRECT [[System/1.0]] 324 1701 2009-10-16T04:56:52Z KrisKowal 6 moved [[System/ArchivedShowOfHands]] to [[System/1.0/ArchivedShowOfHands]] #REDIRECT [[System/1.0/ArchivedShowOfHands]] 325 1703 2009-10-16T04:58:28Z KrisKowal 6 moved [[System/1.0/1.0]] to [[System/1.0]] over redirect #REDIRECT [[System/1.0]] 326 2800 2010-05-27T09:10:24Z Alexandre.Morgaut 33 {{Spec |status=multiple implementations |standard=yes |implementations=Ejscript=2.x, Flusspferd=0.9, GPSEE, Narwhal=0.2, Persevere=?, RingoJS, SproutCore=?, v8cgi, Wakanda }} This specification addresses how modules should be written in order to be interoperable among a class of module systems that can be both client and server side, secure or insecure, implemented today or supported by future systems with syntax extensions. These modules are offered privacy of their top scope, facility for importing singleton objects from other modules, and exporting their own API. By implication, this specification defines the minimum features that a module system must provide in order to support interoperable modules. == Contract == === Module Context === # In a module, there is a free variable "require", that is a Function. ## The "require" function accepts a module identifier. ## "require" returns the exported API of the foreign module. ## If there is a dependency cycle, the foreign module may not have finished executing at the time it is required by one of its transitive dependencies; in this case, the object returned by "require" must contain at least the exports that the foreign module has prepared before the call to require that led to the current module's execution. ## If the requested module cannot be returned, "require" must throw an error. ## The "require" function may have a "main" property that is read-only, don't delete and represents the top-level "module" object of the program. If this property is provided, it must be referentially identical to the "module" object of the main program. ## The "require" function may have a "paths" attribute, that is a prioritized Array of path Strings, from high to low, of paths to top-level module directories. ### The "paths" property must not exist in "sandbox" (a secured module system). ### The "paths" attribute must be referentially identical in all modules. ### Replacing the "paths" object with an alternate object may have no effect. ### If the "paths" attribute exists, in-place modification of the contents of "paths" must be reflected by corresponding module search behavior. ### If the "paths" attribute exists, it may not be an exhaustive list of search paths, as the loader may internally look in other locations before or after the mentioned paths. ### If the "paths" attribute exists, it is the loader's prorogative to resolve, normalize, or canonicalize the paths provided. # In a module, there is a free variable called "exports", that is an object that the module may add its API to as it executes. ## modules must use the "exports" object as the only means of exporting. # In a module, there must be a free variable "module", that is an Object. ## The "module" object must have a read-only, don't delete "id" property that is the top-level "id" of the module. The "id" property must be such that <tt>require(module.id)</tt> will return the exports object from which the <tt>module.id</tt> originated. (That is to say module.id can be passed to another module, and requiring that must return the original module). ## The "module" object may have a "uri" String that is the fully-qualified URI to the resource from which the module was created. The "uri" property must not exist in a sandbox. === Module Identifiers === # A module identifier is a String of "terms" delimited by forward slashes. # A term must be a camelCase identifier, ".", or "..". # Module identifiers may not have file-name extensions like ".js". # Module identifiers may be "relative" or "top-level". A module identifier is "relative" if the first term is "." or "..". # Top-level identifiers are resolved off the conceptual module name space root. # Relative identifiers are resolved relative to the identifier of the module in which "require" is written and called. === Unspecified === This specification leaves the following important points of interoperability unspecified: # Whether modules are stored with a database, file system, or factory functions, or are interchangeable with link libraries. # Whether a PATH is supported by the module loader for resolving module identifiers. == Unit Tests == * [http://github.com/commonjs/commonjs/tree/master/tests/modules Unit tests on CommonJS Github Repository] == Sample Code == ;math.js: <source> exports.add = function() { var sum = 0, i = 0, args = arguments, l = args.length; while (i < l) { sum += args[i++]; } return sum; }; </source> ;increment.js: <source> var add = require('math').add; exports.increment = function(val) { return add(val, 1); }; </source> ;program.js: <source> var inc = require('increment').increment; var a = 1; inc(a); // 2 module.id == "program"; </source> == Notes == * [[Modules/Secure|Secure Modules]] * [[Modules/Natives|How Modules relate to global natives like String]] * [[Modules/Natives|How do you extend native prototypes from a Module?]] * [[Modules/CompiledModules|Notes on compiling modules for browsers]] * [[Modules/ScriptModules|On writing modules that also work as <script>s]] == Related Documents == * Proposal to ECMA TC39: [http://docs.google.com/Doc?id=dfgxb7gk_34gpk37z9v&hl=en Module System for ES-Harmony] * Presentation to ECMA TC39: [http://docs.google.com/Presentation?docid=dcd8d5dk_0cs639jg8&hl=en Modules] == Related Discussion == * [http://groups.google.com/group/commonjs/browse_thread/thread/6ad5c2c3b005cb3b/5a0f17e43d347673 RFC require.paths behaviour] * [http://groups.google.com/group/commonjs/browse_thread/thread/c3682135d72b1f8 Module meta data Proposal.] (resurrection of this discussion) 327 1732 2009-10-28T13:40:09Z Optimus 29 About placeholders: we could use a second parameter in the query method to send values for sanitizing, like: db.query(sql,values) so we could have two constructors, one for plain sql with embedded values, the other with parametrized and sanitizable values. db.query("select * from customers where id=123") or db.query("select * from customers where id=?id",{id:123}) ---- About resultsets: I believe sending column names in every row is a waste of bytes, we are already defining them in the meta section of the set, so no need to repeat them. Unless you want named objects in the result set for better manipulation like customer.name instead of customer[1] but we should give the coder the option to save bytes, specially for large resultsets over the wire. Proposal: a setting to indicate if the resultset will be an object of objects (with meta) or a 2d array, like db.resultType=db.typeObject or db.typeArray 328 1757 2009-11-23T18:06:51Z KrisKowal 6 moved [[AlternateModuleFormatRun]] to [[Modules/Transport/A]]:&#32;organizing '''STATUS: PROPOSED''' == Alternate Module Format: run()== This is a proposal for an alternate module format that is optimized for browser loading. The current difficulties with [Modules/1.1] as it relates to loading code in a browser: In order to work in the browser, CommonJS 1.1 modules normally need to take one of two paths: # Requires a synchronous XHR request to load the module and eval it, so that modules are loaded in the right order. # Requires an intermediate process (like a server process or build step) to wrap the module in a function wrapper so the modules are not executed out of order. Path #1 is a slower loading process that blocks the browser. Using eval() on the modules makes it hard to debug them in all browsers, and eval() is generally discouraged as a coding practice. Path #2 requires an intermediary, extra machinery to develop modules. Depending on your environment choice, it means slower development. It also means a developer cannot just write some static files in an IDE and click refresh to load static files. == Proposed Format == To fix these problems, an alternate format is suggested. This format is implemented by [http://code.google.com/p/runjs/wiki/RunJs RunJS], but it is open for discussion on the particulars. RunJS in some form is a likely candidate for a Dojo 2.0 code loader. Choices made in the module format are optimized for/restricted by the browser environment, but they will work on in a server environment. All modules are registered by calling a run() function. The name of the function is not set in stone, but a function entry point is needed. run() takes a variable amount of arguments, based on the scenario: === Running code that does not define a module === <source> run( ["a", "b", "c"], //the module names function(a, b, c) { //modules are passed in as arguments matching the array of module names. //do things with the a, b and c modules. } ); </source> === Defining a module === Defining a module is the same as running code that depends on a module, but the first argument is the module name, and the function should return an object that defines the module: <source> run( "a", ["b", "c"], function(b, c) { //Return an object or function to define the "a" module. return { color: "blue" }; } ); </source> An explicit module name is needed in order to properly identify the run call in the browser. Mike Wilson on the dojo-contributors list suggested that maybe the script tag's onload handler would be fired right after loading of a script, which would make it possible to not specify the module name. Unfortunately, Internet Explorer does not always fire onload events that match up to the script onload events. [http://www.tagneto.org/runjs/0.0.3/tests/scriptload/ See this test page]. So an explicit module name is needed. This is also beneficial when combining a few modules together into one file, for the purposes of optimized file loading. If a module does not have any dependencies, and it is just a set of properties, then the run() call can be simplified: <source> run( "a", { color: "blue" } ); </source> A module can also define a function as its definition, but run() needs to know that it will return a Function, so Function is passed after the module name. <source> run( "node", Function, ["b", "c"], function(b, c) { return function(id) { if (typeof id == "string") { return document.getElementById(id); } else { //already a DOM node, return it. return id; } } } ); </source> Currently runjs also supports a format for loading i18n bundles. I will not document it here, since it is not strictly necessary for basic module syntax, but you can [http://code.google.com/p/runjs/wiki/RunJs read more about it here], in the "Define an I18N Bundle" section. == Configuration Options == At the top level of code execution, a configuration object can be passed as the first option. This example shows it running in a browser: <source> <script type="text/javascript" src="scripts/run.js"></script> <script type="text/javascript"> run({ baseUrl: "/another/path/", paths: { "some": "some/v1.0" }, waitSeconds: 15, context: "foo" }, ["a.js", "b.js", "some.module", "my.module"], function() { //This function will be called when all the dependencies //listed above are loaded. Note that this function could //be called before the page is loaded. This callback is optional. } ); </script> </source> That example shows all the supported configuration options: '''baseUrl''': the root path to use for all module lookups. So in the above example, "my.module"'s script tag will have a src="/another/path/my/module.js". If no baseUrl is passed in, the path to run.js is used as the baseUrl path. '''paths''': allows configuration of some modules paths. Assumed to be relative to baseUrl. So for "some.module"'s script tag will have a src="/another/path/some/v1.0/module.js" '''waitSeconds''': The number of seconds to wait before giving up on loading a script. The default is 7 seconds. This is needed for the browser context, where loading of individual modules is done through async script tags. '''context''': A name to give to a loading context. This allows run.js to load multiple versions of modules in a page, as long as each top-level run call specifies a unique context string. See Advanced Features below. == Advanced Features == === Multiversion support === As mentioned in Configuration Options, multiple versions of a module can be loaded in a page by using different "context" configuration options. Here is an example that loads two different versions of the alpha and beta modules (this example is taken from one of the test files): <source> <script type="text/javascript" src="../run.js"></script> <script type="text/javascript"> run({ context: "version1", baseUrl: "version1/" }, ["run", "alpha", "beta",], function(run, alpha, beta) { log("alpha version is: " + alpha.version); //prints 1 log("beta version is: " + beta.version); //prints 1 setTimeout(function() { run(["omega"], function(omega) { log("version1 omega loaded with version: " + omega.version); //prints 1 } ); }, 100); } ); run({ context: "version2", baseUrl: "version2/" }, ["run", "alpha", "beta"], function(run, alpha, beta) { log("alpha version is: " + alpha.version); //prints 2 log("beta version is: " + beta.version); //prints 2 setTimeout(function() { run(["omega"], function(omega) { log("version2 omega loaded with version: " + omega.version); //prints 2 } ); }, 100); } ); </script> </source> === Module Modifiers === The [http://code.google.com/p/runjs/wiki/RunJs RunJS documentation] describes a module modifier capability, that works by lazy loading modules that modify other modules. However, that feature is not required for this proposal. == Tests == There are some tests that show a simple use case, a circular reference and multiversion support: [http://www.tagneto.org/runjs/0.0.3/tests/ RunJS 0.0.3 tests] == Contrasts with CommonJS modules == This format differs from current CommonJS files in the following ways: # Requires modules to specify their name, because of browser constraints. It also makes bundling multiple modules in one file easier. # Relative module names that start with "." and ".." are not supported in the module names, given the first point. # All dependencies are declared up top, and passed as arguments to a function that define the module. # "." is used in module names, however, it could be changed to "/" if that worked better for the community. 329 1748 2009-11-17T17:42:42Z Timjs 28 Here are some snippets from my own notes on these subjects, having experimented with current platforms looking for feasible common ground. These are of course my opinions, but because of limited time, I’ve expressed them as matters-of-fact and probably out of order. Thanks for bearing with me if you do. Synchronicity ----------------- async-to-sync is apples-to-oranges. This might one day be expressed and well-maintained as two separate copies of similar functionalities (at twice the cost). Not today, not in retrospect, and not by accident. Security ---------- Minimally-Practical vs. Secure is also apples-to-oranges. Python’s “restricted mode” abandoned its noble efforts likely because of too many loopholes hidden by applying security in retrospect. In all practical ways, CommonJS is in retrospect here. (FWIW, I had a need to explore sharing global state between modules/contexts, and am currently using an inconspicuous security loophole across several recent proto-platforms to accomplish this). Thought Vehicles --------------------- I see lots of bike-shaped stenciling on minivans, monster trucks, and unicycles. ‘JavaScript’ is 40% ‘Java’ in terms of surface stenciling, but… Separation of Concerns ---------------------------- Very little overlap happens by random chance. How are these different needs to be managed now and in the future, both in discussion and in code? Are current specifications catering to just one or two of these? * The CommonJS-as-a-language * The Module Librarians * The End-User Developers * The Platform Builders * The Module Authors Going with the Flow ------------------------- Current proposals, when viewed across the above concerns and across existing codebases, remain suspicious and burdensome. What other approaches might better serve to maintain inter-project rapport while revealing palatable solutions? How about an incremental approach? (1) vanilla ES3 module concept No prescribed module identifiers or resolution mandates or paths, just an embryonic, abstract mechanism for an End-User Developer to express a need, and for a Module Author to similarly identify dependencies. This is doable in useful ways through code comments. (2) vanilla ES3+Core concept With the addition of bare-minimum, majority concurred CommonJS APIs. Both Synchronous and Asynchronous interfaces provided (fine if emulated). Nothing dependent on any module or packaging system. The APIs expressed as superglobals, not module imports, with no choices whatsoever for the End-User Developer to make here (beyond all or nothing ES3+Core). (3) An ES3+Core+Stdlib reference implementation Basically ES3+Core+MoreES3s, with any MoreES3s’ synchronicity support TBD. Again superglobals used to reference the larger API, and just one decision for a user to make. (4) ?? Tangential Needs --------------------- * DISCUSSION FORUM: ES3+xAPI * To vet some good interfaces to already-common libraries like mysql/ memcache/etc. This seems completely overlooked by CommonJS movement. It needs to be addressed quickly to re-unify current divides and to avoid new exponential divides across platforms. * DISCUSSION FORUM: ES3+Synchronicity * To coordinate async vs. sync standards any possible interop; to track relatable efforts w/o confusing them with module or security discussions. ------------------------ Again, just some thoughts from my notes offered with a grain of salt. Best, -Tim Here is my wish list for a specification-backed module environment, somewhat organized by stakeholders. It contemplates several atomic needs that have been obscured by recent pushes towards a one-size-fits-most "require" construct. -------------------------------- 1) Standard Library/Modules (ala Python) [@ CommonJS core ] a) The CommonJS-as-a-language standard libs and APIs b) The CommonJS-candidates "de facto standard" libs and APIs c) Pseudo-standard libs (ie: verticals) d) ...generalized module reuse, packaging, repositories 2) Local Module Management [@ Sysop / Code Librarian] a) Intrinsic modules (knowledge of globals, superglobals, "require") b) Filesystem (organized by paths) c) COM registration (ie: Components.classes["@mozilla.org/preferences-service;1"]) d) URI mappings / registrations 3) Module Binding [@ End-user developer] a) _global_ (affects VM state) b) _static_ (deterministic / easy to lint / perhaps sync) c) _dynamic_ (non-deterministic / difficult to lint / perhaps async) d) _untrusted_ (sandboxed / preprocessed) 4) Module Loaders / Resolvers [@ VM / Platform developers] a) Versioning (dependency tracking, sniffing) b) De-duping (ie: load into VM/context just once) c) Unloading / Reloading modules d) Synthetic modules (adapters, submodules, autoloaders, etc.) e) Serialization (ie: VM-hibernate) 5) Module XYZ [ @ Module developers ] a) (expression of) dynamic dependencies (container agnostic) b) Static linking (for autonomy) c) Submodules (internal reuse, public/private conventions) d) etc. ------------- 330 1743 2009-11-11T03:20:19Z Timjs 28 Created page with 'What wonderfully-different JavaScript module systems to consider now, both in use and those presented in theory. They represent such a large and diverse set of developer require…' What wonderfully-different JavaScript module systems to consider now, both in use and those presented in theory. They represent such a large and diverse set of developer requirements. The more I dive into the existing documentation and code of our predecessors (alongside current efforts), the more I see what at first blush appeared as avoidable fragmentation may be entirely to the contrary. Beyond mere fragmentation, we seem headed towards outright exclusion! “One of five” is not quite as common as I was thinking we’d be shooting for. So, by what measurement are varying developer needs being ranked? Voting with only a handful of constituents present seems difficult to validate. Who are our constituents? People (developers) don’t seem to commonly know about CommonJS yet, but have started arriving more regularly (if the mailing list is any indication). They are often all too happy to share their wealth of knowledge and experience with us. Many of these “late arrivals” are not late in any other sense -- having had their own module implementations in place for some time. As I ponder these differences, I look for ways to distinguish between various approaches and for classification (ie: as potential candidates for bike-shedding, as legitimate apples-to-oranges, etc.). Consider the following separation of concerns: * The CommonJS-as-a-language * The Module Librarians * The End-User Developers * The Platform Builders * The Module Authors The distances between these areas continue to grow. I’m not sure why. I do think that we need more representative abstractions to inform any reasonable set of specifications moving forward. 331 2767 2010-05-10T01:11:52Z Markm 54 fixed link '''STATUS: PROPOSALS''' There are a variety of reasons why it should be possible to create new module systems from within a module system. For one, such a system would make it possible to write test scaffolds for a module, where modules are injected around a module to simulate its interface with the rest of the world. Also, the ability to load a module is a capability (in the [http://en.wikipedia.org/wiki/Object-capability_model object-capability programming sense]), but can be made a very safe capability by restricting the loadable modules to a carefully managed branch of a file system, by statically verifying that the content of the module is compliant with the CommonJS module specification, and by otherwise freezing and attenuating all other security hazards. Doing all of these things guarantees that, if you instantiate a module system, the modules therein would only have the ability to perform computation, and manipulate the capabilities you deliberately inject into that system. Another facet of exposing some of the internal mechanisms for finding, evaluating, and loading modules is that these facilities can be used to create more advanced module systems for domain specific languages. == Proposals == * The [http://docs.google.com/Doc?docid=0AVWyIFBvIVXGZGZneGI3Z2tfMzRncGszN3o5dg&hl=en|original proposal] for modules to ECMA TC39 in January 2009 included a module loader design. The design in practical implementations has drifted and improved since. * [[Modules/Loaders/A]] accompanied the original [[Modules/SecurableModules]] proposal, was ignored, and now has become obsolete. * [[Modules/Loaders/B]] 332 1755 2009-11-22T04:32:38Z KrisKowal 6 '''STATUS: PROPOSAL''' This is a proposal that specifies the interface of a Module Loader. Implementations of the Module Loader interface can be made secure and provided to suspicious sandboxes: sandboxes with reduced capabilities (privileges that are exercisable only by containing a reference to a gate keeper). The module loader interface is intended to be extensible in privileged sandboxes to: # load shared objects and dynamic libraries # load modules from formats other that CommonJS, like ObjectiveJ, or a hand-written module factory format, like a module transport format suitable also for script injection in browsers # load modules that have different values in scope, dependency injection, like Jakefiles and QUnit tests, or a simulated browser scope == Specification == === 1. Modules === # The "require" function provided to modules may have a "loader" property that must be a module loader object. === 2. Module Loaders === # A module loader must have the "resolve(id, baseId)" function. This function must return a top-level module identifier given any other valid CommonJS module identifier. The given identifier may be relative to the base identifer or a top-level identifier itself, in which case the base identifier is ignored. If the module loader supports module identifiers outside the CommonJS module identifier domain, resolve must return some form of canonical module identifier acceptable by require(canonicalId). # A module loader must have a "reload(topId)" property function. This function may force a module factory function to be created from the original medium. The given identifier must be a value returned by "resolve". # A module loader must have a "load(topId)". The given identifier must be a value returned by "resolve". "load" returns a module factory function. ==== 2.1. Module File Loaders ==== # A module loader may have a "find(topId)" function that must return the canonical path of the file that can be loaded. # A module loader may have an "evaluate(text, fileName_opt, lineNo_opt)" function that accepts the text of a JavaScript program and returns a module factory function. The resultant factory function, when called may execute the program in a different, or deeply frozen JavaScript context. # A module loader may implement the augmented reload interface, "reload(topId, path_opt)", that accepts a hint of where to find the path to the file corresponding to the identifier. # A module loader may implement the augmented load interface, "load(topId, path_opt)", that accepts a hint of where to find the path to the file corresponding to the identifier. ==== 2.2. Module Multiplexer Loaders ==== # A module may implement "canLoad(path)" that accepts a path and returns whether the loader can load a module at that path with "reload(id, path)" and "load(id, path)". Acceptable grounds for determining whether the module can load the module include the extension or the content of the file. # A module may have a "loaders" property that must be an Array of module loader objects, [canLoad(path), loader] pairs, [extension, loader] pairs, or any combination thereof. ## Any module loader providing a "loaders" property must respect in-place changes to the loaders property. ## The loaders property may not be writable. ## The loaders property may not be configurable. === 3. Module Factory Functions === # A module factory function accepts an object and returns nothing. # The keys of the object accepted by a module factory function must be valid JavaScript identifiers. # The object accepted by a module factory function may include a "require", "exports", and "module", the values of which correspond to the free variables defined in a CommonJS module. === 4. Packaged Module Loaders === # A package may provide a module loader. # package.json may have a "loader" property that may either be a loader identifier or a prioritized order of loader identifiers from high to low priority. # A package system may construct and provide as "require.loader" a multiplexing loader from the collected loader identifiers in all installed packages, in which case it must construct the multiplexing loader's "loader" property with loader instances corresponding to each loader identifier in each <tt>package.json</tt> in each package in package dependency order as established by a topological sort of all packages ordered from most dependent to least dependent. # A loader instance corresponding to a module loader identifier must be constructed, without use of the "new" keyword, from the "Loader" function of the module file found by resolving resolving the module loader identifier as the path relative to the containing <tt>package.json</tt>. 333 1758 2009-11-23T18:06:51Z KrisKowal 6 moved [[AlternateModuleFormatRun]] to [[Modules/Transport/A]]:&#32;organizing #REDIRECT [[Modules/Transport/A]] 334 2521 2010-03-25T04:23:20Z KrisKowal 6 /* Related Discussions */ There are a variety of ways to transport a module from a server to a browser. However, the highest performance solutions available today involve script injection, which necessitates that the script arrange with the loader to call a particular function when it executes. == Proposals == * [[Modules/Transport/A]] "run" system. * [[Modules/Transport/B]] "register" system. * [[Modules/Transport/C]] "register" system that uses positional args, explicit free variables. * [[Modules/Transport/D]] "register" system that supports dependency injection and module sets. == Prior Art == == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/129c8d4ec3244ec7 Module spec questions] * [http://groups.google.com/group/commonjs/browse_thread/thread/a1e8c041c40751ab/b0f7e0a647382d27?#b0f7e0a647382d27 Module Loaders] * [http://groups.google.com/group/google-caja-discuss/browse_thread/thread/b060927ff5b47ffa/cd55027d5100588d Module loading discussion] * [http://groups.google.com/group/commonjs/browse_thread/thread/3cab4886bb39c28e Updated Transport proposals] 335 1809 2009-12-01T09:37:25Z KrisKowal 6 /* Relevant Discussions */ additional dicussions '''STATUS: PROPOSAL''' This proposal, based on [[Binary/B]], defines types and methods for constructing, manipulating, and transcoding binary data in both mutable and immutable forms. ByteString resembles its immutable text analog, String, and ByteArray resembles its mutable analog, Array. Both types constrain their data to the byte domain and provide a memory-safe interface to underlying continguous, random-access byte collections. An [http://spreadsheets.google.com/ccc?key=0An5phhxDkYDPdEFoTnlsRWgyc0x0WkpidURWT3pSYnc&hl=en overview] of the supported types, methods, signatures, and corresponding return types is on Google Docs. = Specification = The "binary" top-level module must export ByteArray, ByteString, BitArray, BitString, Range, a charset support checking function, and the following alphabets for radix encodings. ; ByteString : immutable, byte quantized ; ByteArray : mutable, explicitly resizable, byte quantized ; BitString : immutable, bit quantized ; BitArray : mutable, explicitly resizable, bit quantized ; supports(charset String) Boolean : returns whether the given charset is supported for all encoding, decoding, or transcoding operations. ; base8 String : The base 8 alphabet, including padding, "<tt>01234567=</tt>". ; base16 String : The base 16 alphabet, "<tt>0123456789abcdef</tt>". ; base32 String : The default alphabet for base 32 encoding as specified by [http://www.crockford.com/wrmg/base32.html Doug Crockford]. See the toString(radix, alphabet) methods of ByteString and ByteArray. ; rfc4648 String : An alternate alphabet for base 32 encoding as specified by [http://tools.ietf.org/html/rfc4648 RFC 4648]. See the toString(radix, alphabet) ; base64 String : The base 64 alphabet, "<tt>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/</tt>". == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array that does not implicitly terminate at the first 0-valued byte. ByteString instances are comparable with the <tt>==</tt> and <tt>===</tt> operators based on equal order and respective values of their content. === Constructor === A ByteString function must exist. When called as a function, it must return a byte string. When constructed with "<tt>new</tt>", it must throw a TypeError. <source> ByteString(); assert.throws(function () { new ByteString(); }, TypeError); </source> ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. For performance, transparently to the layer specified here, the "ByteArray" may relinquish ownership of its underlying byte buffer and switch to a copy-on-write mode. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. Coerces Numbers to bytes by selecting their least significant eight bits. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Prototype Properties === ; toByteArray() ByteArray : Returns a byte for byte copy in a ByteArray. : ''Note: for best performance, implementations should transfer ownership of the underlying buffer and flag the original owner to copy-on-write.'' ; toByteArray(sourceCharset, targetCharset) ByteArray : Returns this transcoded from the source charset to the target charset as a ByteArray. The source and target charset are internally cast to String with the String constructor. ; toByteString() ByteString : Returns this ByteString. ; toByteString(sourceCharset, targetCharset) ByteString : Returns this transcoded from the source charset to the target charset as a ByteString. The source and target charset are internally cast to String with the String constructor. ; toBitArray() BitArray : Returns this as a BitArray by composing each byte, in consistent order, into groups of eight bits from most significant to least significant. <code>ByteArray([3]).toBitArray()</code> and <code>BitArray([0, 0, 0, 0, 0, 0, 1, 1])</code> are equivalent. ; toBitString() BitString : Returns this as a BitString by composing each byte, in consistent order, into groups of eight bits from most significant to least significant. <code>ByteString([3]).toBitString() == BitString([0, 0, 0, 0, 0, 0, 1, 1])</code>. ; toString() String : Returns a debug representation like "<tt>[ByteString 10]</tt>", where 10 is the length this ByteString. ; toString(charset) String : Decodes this ByteString according to the given character set and returns the String from the corresponding unicode points. May throw a ValueError if the byte string is malformed or if any of the code points are out of the implementation's supported range. ; toString(radix, alphabet_opt) String : encodes this as base 2, 8, 16, 32, or 64 with the given alphabet. The default padding character is "=", but can be overridden with an alternate padding character at the index of the radix in the alphabet. Throws a "ValueError" if the alphabet is not the length of the radix or one larger than the radix. The default alphabet corresponds to [http://www.crockford.com/wrmg/base32.html Doug Crockford's] base32 alphabet for human-error resistant binary communication. "rfc4648" is an alternate alphabet. These alphabets are exported by the "binary" module as "base32" and "rfc4648" respectively. ; toArray() Array : Returns an Array containing the bytes as Numbers. ; valueOf(endian_opt) Number : Returns this as a Number of the highest precision storable, treating these bytes as ordered in the given endianness. endian may be omitted, undefined, "LE" or "BE". If omitted or undefined, defaults to "BE". If "LE", these bytes are treated as little-endian, or least to most significant. If "BE", these bytes are treated as big-endian, albeit network-byte-order, most to least significant. ; toSource() String : returns "<tt>require("binary").ByteString([])</tt>" for a null byte string or "<tt>require("binary").ByteString([0, 1, 2])</tt>" for a byte string of length 3 with bytes 0, 1, and 2. ; valueAt(offset_opt) Number : Returns the byte at offset as a Number. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; byteStringAt(offset_opt) ByteString : Returns a unary (length 1) ByteString of the byte at the given offset. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; indexOf(values, start_opt, stop_opt) Number : Returns the index of the first occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; lastIndexOf(values, start_opt, stop_opt) Number : Returns the index of the last occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; range(start_opt, stop_opt) Range : Returns a Range object. The value of stop defaults to the length of this. The value of start defaults to 0. Uses this for the Range's ref property. ; copy(target, targetStart, start, stop) ByteString : Copies the Number values of each byte from this between start and stop to a target ByteArray or Array at the targetStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a ByteArray or Array. Returns this. ; slice(start_opt, stop_opt) ByteString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start_opt, length_opt) ByteString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substr String.prototype.substr] ; substring(start_opt, last_opt) ByteString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substring String.prototype.substring] ; concat(...) ByteString : Returns a ByteString composed of itself concatenated with the given ByteString, ByteArray, and Array values. Throws a TypeError if any of the arguments are not a ByteString, ByteArray, or Array of Numbers. Coerces Numbers to bytes by selecting their least significant eight bits. ; join(array) ByteString : Returns a ByteString of the ByteStrings, ByteArrays, Arrays of Numbers, or a combination thereof, delimited by this. Arrays of Numbers are converted to ByteArrays. Coerces Numbers to bytes by selecting their least significant eight bits. ; split(delimiter_opt, max_opt) Array : Returns an Array of ByteStrings pared from the ByteString between strings of ByteStrings that match the given delimiter for up to the maximum number of delimiters, starting from the left. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteString. The delimiter is internally coerced to a ByteString with the ByteString constructor. ; splitRight(delimiter_opt, max_opt) Array : Returns an Array of ByteStrings pared from the ByteString between strings of ByteStrings that match the given delimiter for up to the maximum number of delimiters, starting from the right. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteString. The delimiter is internally coerced to a ByteString with the ByteString constructor. ; Content : an alias of ByteString, indicating that ByteString is the type of what <nowiki>[[Get]]</nowiki> returns. === Internal Properties === ; <nowiki>[[Get]]</nowiki> ByteString : Returns a unary (length 1) ByteString of the byte at the given offset. ; <nowiki>[[Put]]</nowiki> : throws a TypeError. === Instance Properties === ; length : The length in bytes. Not <nowiki>[[Writable]]</nowiki>, not <nowiki>[[Configurable]]</nowiki>, not <nowiki>[[Enumerable]]</nowiki>. == ByteArray == A ByteArray is a mutable, flexible (explicitly growable and shrinkable) representation of a C unsigned char (byte) array. === Constructor === A ByteArray function must exist. Calling and constructing a ByteArray both return a new ByteArray instance. <source> ByteArray() instanceof ByteArray; new ByteArray() instanceof ByteArray; typeof ByteArray() === "object"; typeof new ByteArray() === "object"; </source> ; ByteArray() : New, empty ByteArray. ; ByteArray(length Number, fill_opt Number) : New ByteArray of the given length, with the given fill number at all offsets. The default filler is 0. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. Coerces Numbers to bytes by selecting their least significant eight bits. ; ByteArray(string, charset) : Create a "ByteArray" from a "String", the result being encoded with charset. === Prototype Properties === ; toByteArray() ByteArray : Returns a byte for byte copy in a ByteArray. : ''Note: for best performance, implementations should transfer ownership of the underlying buffer and flag the original owner to copy-on-write.'' ; toByteArray(sourceCharset, targetCharset) ByteArray : Returns this transcoded from the source charset to the target charset as a ByteArray. The source and target charset are internally cast to String with the String constructor. ; toByteString() ByteString : Returns a byte for byte copy in a ByteString. : ''Note: for best performance, implementations should transfer ownership of the underlying buffer and flag the original owner to copy-on-write.'' ; toByteString(sourceCharset, targetCharset) ByteString : Returns this transcoded from the source charset to the target charset as a ByteString. The source and target charset are internally cast to String with the String constructor. ; toBitArray() BitArray : Returns this as a BitArray by composing each byte, in consistent order, into groups of eight bits from most significant to least significant. <code>ByteArray([3]).toBitArray()</code> and <code>BitArray([0, 0, 0, 0, 0, 0, 1, 1])</code> are equivalent. ; toBitString() BitString : Returns this as a BitString by composing each byte, in consistent order, into groups of eight bits from most significant to least significant. <code>ByteString([3]).toBitString() == BitString([0, 0, 0, 0, 0, 0, 1, 1])</code>. ; toString() String : Returns a debug representation like "<tt>[ByteArray 10]</tt>", where 10 is the length this ByteArray. ; toString(charset) String : Decodes this according to the given character set and returns the String from the corresponding unicode points. May throw a ValueError if the byte string is malformed or if any of the code points are out of the implementation's supported range. ; toString(radix, alphabet_opt) String : encodes this as base 2, 8, 16, 32, or 64 with the given alphabet. The default padding character is "=", but can be overridden with an alternate padding character at the index of the radix in the alphabet. Throws a "ValueError" if the alphabet is not the length of the radix or one larger than the radix. The default alphabet corresponds to [http://www.crockford.com/wrmg/base32.html Doug Crockford's] base32 alphabet for human-error resistant binary communication. "rfc4648" is an alternate alphabet. These alphabets are exported by the "binary" module as "base32" and "rfc4648" respectively. ; toArray() Array : Returns an Array containing the bytes as Numbers. ; valueOf(endian_opt) Number : Returns this as a Number of the highest precision storable, treating these bytes as ordered in the given endianness. endian may be omitted, undefined, "LE" or "BE". If omitted or undefined, defaults to "BE". If "LE", these bytes are treated as little-endian, or least to most significant. If "BE", these bytes are treated as big-endian, albeit network-byte-order, most to least significant. ; toSource() String : returns "<tt>require("binary").ByteArray([])</tt>" for a null byte string or "<tt>require("binary").ByteArray([0, 1, 2])</tt>" for a byte string of length 3 with bytes 0, 1, and 2. ; valueAt(offset_opt) Number : Returns the byte at offset as a Number. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; byteStringAt(offset_opt) ByteString : Returns a unary (length 1) ByteString of the byte at the given offset. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; indexOf(values, start_opt, stop_opt) Number : Returns the index of the first occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; lastIndexOf(values, start_opt, stop_opt) Number : Returns the index of the last occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; range(start_opt, stop_opt) Range : Returns a Range object. The value of stop defaults to the length of this. The value of start defaults to 0. Uses this for the Range's ref property. ; copy(target, targetStart, start, stop) ByteArray : Copies the Number values of each byte from this between start and stop to a target ByteArray or Array at the targetStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a ByteArray or Array. Returns this. ; copyFrom(source, sourceStart, start, stop) ByteArray : Copies the Number values of each byte from a given ByteArray or ByteString into this from start to stop at the given sourceStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a ByteArray or Array. Returns this. ; fill(value, start_opt, stop_opt) ByteArray : Fills each of the contained bytes with the given value (either a unary ByteString, ByteArray, or a Number) from the start offset to the stop offset. start and stop must be numbers, undefined, or omitted. If omitted, start is presumed to be 0. If omitted, stop is presumed to beh the length of this ByteArray. If omitted, "value" is presumed to be 0. Returns this. ; splice(start_opt, stop_opt, ...values) ByteArray : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/splice Array.prototype.splice] ; slice(start_opt, stop_opt) ByteArray : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; split(delimiter_opt, max_opt) Array : Returns an Array of ByteArrays pared from the ByteArrays between strings of ByteArrays that match the given delimiter for up to the maximum number of delimiters, starting from the left. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteArray. The dlimiter is internally coerced to a ByteArray with the ByteArray constructor. ; splitRight(delimiter_opt, max_opt) Array : Returns an Array of ByteArrays pared from the ByteArray between strings of ByteArrays that match the given delimiter for up to the maximum number of delimiters, starting from the right. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteArray. The delimiter is internally coerced to a ByteArray with the ByteArray constructor. ; forEach(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/forEach Array.prototype.forEach] ; every(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/every Array.prototype.every] ; some(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/some Array.prototype.some] ; map(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/map Array.prototype.map] ; Content : an alias of Number, indicating that Number is the type of what <nowiki>[[Get]]</nowiki> returns. === Internal Properties === ; <nowiki>[[Get]]</nowiki> Number : Returns the Number value of a the byte at the given offset. ; <nowiki>[[Put]]</nowiki> Number : Sets the byte value at the given offset. Throws a ValueError if the index is beyond the current bounds of the byte array (byte arrays can be grown or shrunk by explicitly assigning a new length). === Instance Properties === ; length : The length in bytes. Not <nowiki>[[Configurable]]</nowiki>, not <nowiki>[[Enumerable]]</nowiki>. Assigning to the length of a ByteArray causes the array to reallocate its underlying buffer to the given size, copying the original buffer up to the length of the new buffer if it is less, and filling all bytes beyond the length of the original buffer with the value 0. == BitString == A "BitString" is an immutable, fixed-width representation of any number of bits (not necessarily a multiple of 8). BitString instances are comparable with the <tt>==</tt> and <tt>===</tt> operators based on equal order and respective values of their content. === Constructor === A "BitString" function must exist. When called as a function, it must return a bit string. When constructed with "new", it must throw a "TypeError". <source> BitString(); assert.throws(function () { new BitString(); }, TypeError); </source> ; BitString() : Construct an empty bit string. ; BitString(bitString) : Copies bitString. ; BitString(bitArray) : Use the contents of bitArray. ; BitString(array) : construct a bit string where a bit is on if Boolean(value) for each value of the given value is true. ; BitString(bytes) : Returns the given ByteString or ByteArray as a BitString by composing each byte, in consistent order, into groups of eight bits from most significant to least significant. === Prototype Properties === ; toByteArray() ByteArray : Returns a ByteArray composed of these bits in groups of eight from most to least significant. Throws a ValueError if the length of this is not a multiple of 8. ; toByteString() ByteString : Returns a ByteString composed of these bits in groups of eight from most to least significant. Throws a ValueError if the length of this is not a multiple of 8. ; toBitArray() BitArray : Returns this as a BitArray with equivalent respective bit values. ; toBitString() BitString : Returns this BitString. ; toString() String : Returns this represented as a String of 0s and 1s. ; toArray() Array : Returns an Array containing the bits as the Numbers 0 and 1. ; valueOf() Number : Returns this as a Number of the highest precision storable, treating these bits as ordered from most to least significant. The result of valueOf must be equivalent to the Number arrived at by initializing an accumulator with 0 and iteratively multiplying the accumulator by 2 and adding the 0 or 1 Number value of each bit. ; toSource() String : returns "<tt>require("binary").BitString([])</tt>" for a null bit string or "<tt>require("binary").BitString([0, 1, 0])</tt>" for a bit string of length 3 with bits 0, 1, and 0. ; valueAt(offset_opt) Number : Returns the bit at offset as a Number. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; indexOf(values, start_opt, stop_opt) Number : Returns the index of the first occurence of of a bit or consecutive bits as represented by a Number, BitString, or BitArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; lastIndexOf(values, start_opt, stop_opt) Number : Returns the index of the last occurence of of a bit or consecutive bits as represented by a Number, BitString, or BitArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; range(start_opt, stop_opt) Range : Returns a Range object. The value of stop defaults to the length of this. The value of start defaults to 0. Uses this for the Range's ref property. ; copy(target, targetStart, start, stop) BitString : Copies the Number values of each bit from this between start and stop to a target BitArray or Array at the targetStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a BitArray or Array. Returns this. ; slice(start_opt, stop_opt) BitString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start_opt, length_opt) BitString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substr String.prototype.substr] ; substring(start_opt, last_opt) BitString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substring String.prototype.substring] ; concat(...) BitString : Returns a BitString composed of itself concatenated with the given BitString, BitArray, and Array values. Throws a TypeError if any of the arguments are not a ByteString, ByteArray, or Array of Numbers. Coerces nonzero Numbers to 1. ; join(array) BitString : Returns a BitString of the BitStrings, BitArrays, Arrays of Numbers, or a combination thereof, delimited by this. Arrays of Numbers are converted to BitArrays, so this function may throw a RangeError. ; split(delimiter_opt, max_opt) Array : Returns an Array of BitStrings pared from the BitStrings between strings of BitStrings that match the given delimiter for up to the maximum number of delimiters, starting from the left. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty BitString. The delimiter is internally coerced to a ByteString with the ByteString constructor. ; splitRight(delimiter_opt, max_opt) Array : Returns an Array of BitStrings pared from the BitStrings between strings of BitStrings that match the given delimiter for up to the maximum number of delimiters, starting from the right. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty BitString. The delimiter is internally coerced to a ByteString with the ByteString constructor. === Internal Properties === ; <nowiki>[[Get]]</nowiki> BitString : Returns a unary (length 1) BitString of the byte at the given offset. === Instance Properties === ; length : The length in bits. Not <nowiki>[[Writable]]</nowiki>, not <nowiki>[[Configurable]]</nowiki>, not <nowiki>[[Enumerable]]</nowiki>. == BitArray == A BitArray is a mutable, flexible (explicitly growable and shrinkable) representation of an ordered collection of bits, not necessarily with a length that is a multiple of 8. === Constructor === A BitArray function must exist. Calling and constructing a BitArray both return a new BitArray instance. <source> BitArray() instanceof BitArray; new BitArray() instanceof BitArray; typeof BitArray() === "object"; typeof new BitArray() === "object"; </source> ; BitArray() : New, empty BitArray. ; BitArray(length Number, fill_opt Number) : New BitArray of the given length, with the given fill number at all offsets. The default filler is 0. ; BitArray(bitArray) : Copy bitArray. ; BitArray(array) : construct a bit string where a bit is on if Boolean(value) for each value of the given value is true. ; BitArray(bytes, endian) : Returns the given ByteString or ByteArray as a BitArray by composing each byte, in consistent order, into groups of eight bits from most significant to least significant. === Instance Methods === ; toByteArray() ByteArray : Returns a ByteArray composed of these bits in groups of eight from most to least significant. Throws a ValueError if the length of this is not a multiple of 8. ; toByteString() ByteString : Returns a ByteString composed of these bits in groups of eight from most to least significant. Throws a ValueError if the length of this is not a multiple of 8. ; toBitArray() BitArray : Returns a copy of this. ; toBitString() BitString : Returns this as a BitString with equivalent respective bit values. ; toString() String : Returns this represented as a String of 0s and 1s. ; toArray() Array : Returns an Array containing the bits as the Numbers 0 and 1. ; valueOf() Number : Returns this as a Number of the highest precision storable, treating these bits as ordered from most to least significant. The result of valueOf must be equivalent to the Number arrived at by initializing an accumulator with 0 and iteratively multiplying the accumulator by 2 and adding the 0 or 1 Number value of each bit. ; toSource() String : returns "<tt>require("binary").BitArray([])</tt>" for a null bit array or "<tt>require("binary").BitArray([0, 1, 0])</tt>" for a bit array of length 3 with bits 0, 1, and 0. ; valueAt(offset_opt) Number : Returns the bit at offset as a Number. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; indexOf(values, start_opt, stop_opt) Number : Returns the index of the first occurence of of a bit or consecutive bits as represented by a Number, BitString, or BitArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; lastIndexOf(values, start_opt, stop_opt) Number : Returns the index of the last occurence of of a bit or consecutive bits as represented by a Number, BitString, or BitArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; range(start_opt, stop_opt) Range : Returns a Range object. The value of stop defaults to the length of this. The value of start defaults to 0. Uses this for the Range's ref property. ; copy(target, targetStart, start, stop) BitArray : Copies the Number values of each bit from this between start and stop to a target BitArray or Array at the targetStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a BitArray or Array. Returns this. ; copyFrom(source, sourceStart, start, stop) BitArray : Copies the Number values of each bit from a given BitArray or BitString into this from start to stop at the given sourceStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a ByteArray or Array. Returns this. ; fill(value, start_opt, stop_opt) BitArray : Fills each of the contained bits with the given value (either a unary BitString, BitArray, or a Number) from the start offset to the stop offset. start and stop must be numbers, undefined, or omitted. If omitted, start is presumed to be 0. If omitted, stop is presumed to beh the length of this ByteArray. If omitted, "value" is presumed to be 0. Returns this. ; splice(start_opt, stop_opt, ...values) BitArray : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/splice Array.prototype.splice] ; slice(start_opt, stop_opt) BitArray : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; split(delimiter_opt, max_opt) Array : Returns an Array of BitStrings pared from the BitStrings between strings of BitStrings that match the given delimiter for up to the maximum number of delimiters, starting from the left. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty BitString. The delimiter is internally coerced to a ByteString with the ByteString constructor. ; splitRight(delimiter_opt, max_opt) Array : Returns an Array of BitArrays pared from the BitArray between strings of BitArrays that match the given delimiter for up to the maximum number of delimiters, starting from the right. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty BitArray. The delimiter is internally coerced to a BitArray with the BitArray constructor. === Internal Properties === ; <nowiki>[[Get]]</nowiki> Number : returns the Number value of a the bit at the given offset. ; <nowiki>[[Put]]</nowiki> Number : Sets the bit value at the given offset. Throws a ValueError if the index is beyond the current bounds of the bit array (bit arrays can be grown or shrunk by explicitly assigning a new length). === Instance Properties === ; length : The length in bits. Not <nowiki>[[Configurable]]</nowiki>, not <nowiki>[[Enumerable]]</nowiki>. Assigning to the length of a bit array causes the array to reallocate its underlying buffer to the given size, copying the original buffer up to the length of the new buffer if it is less, and filling all bits beyond the length of the original buffer with the value 0. == Range == A range object is a convenience for copying ranges from one ByteArray or ByteString to another ByteArray. === Constructor === ; new Range({ref, start, stop}) : returns a Range object with the respective properties. === Prototype Properties === ; copy(target, start_opt, stop_opt) : generically calls <codee>this.ref.copy(target, this.start, Math.min(this.stop, this.start + target.length - start), start)</code>. The default value of stop is the target length. ; copyFrom(source, start_opt, stop_opt) : generically calls <code>this.ref.copyFrom(source, this.start, Math.min(this.stop, this.start + source.length - start), start)</code>. The default value of stop is the source length. ; fill(value) : generically calls <code>this.ref.fill(value, this.start, this.stop)</code> ; splice(start_opt, stop_opt, ...values) : generically calls <code>this.ref.splice.apply(this.ref, arguments)</code> == String == === Prototype Properties === ; toByteArray(charset) ByteArray : Returns a ByteArray of these unicode code points as the corresponding bytes in the given character set. Must throw an error if the given character set is not supported. ; toByteArray(radix, alphabet_opt, lookup_opt) ByteArray : Returns a ByteArray of these characters encoded in base 2, 8, 16, 32, or 64. If omitted or undefined, the alphabet defaults to the standard alphabet, or the Doug Crockford base 32 alphabet. Optionally accepts a lookup object or function that normalizes ambiguous characters, as in the default behavior of Doug Crockford's base 32 encoding for the characters "o" to 0, and "l" to 1, and all lower-case letters to their upper-case analogs. Must throw a ValueError if any contained character cannot be expressed in the requested radix's alphabet. ; toByteString(charset) ByteString : Returns a ByteString of these unicode code points as the corresponding bytes in the given character set. Must throw an error if the given character set is not supported. ; toByteString(radix, lookup_opt) ByteString : Returns a ByteString of these characters encoded in base 2, 8, 16, 32, or 64. If omitted or undefined, the alphabet defaults to the standard alphabet, or the Doug Crockford base 32 alphabet. Optionally accepts a lookup object or function that normalizes ambiguous characters, as in the default behavior of Doug Crockford's base 32 encoding for the characters "o" to 0, and "l" to 1, and all lower-case letters to their upper-case analogs. Must throw a ValueError if any contained character cannot be expressed in the requested radix's alphabet. ; valueAt(offset_opt) Number : Returns the Unicode code point Number at the given offset. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; charCodes() Array : Returns an array of Unicode code points for each respective contained character. == Array == === Prototype Properties === ; toByteArray(charset) : Returns a ByteArray of these unicode code points as the corresponding bytes in the given character set. Must throw an error if the given character set is not supported. ; toByteString(charset) : Returns a ByteString of these unicode code points as the corresponding bytes in the given character set. Must throw an error if the given character set is not supported. == Number == === Prototype Properties === ; toByteArray(width, endian_opt) ByteArray : Returns this as a ByteArray of the given width, extending the most significant bits of a negative Number arithmetically. The endian parameter may be omitted, undefined, "LE" or "BE". If omitted or undefined, the endian parameter defaults to "BE". If the endianness is "BE", the bytes are ordered from most to least significant, and if the endianness is "LE", they are ordered from least to most significant. If this Number translates to bits that cannot be represented ; toByteString(width, endian_opt) ByteString : Returns this as a ByteString of the given width, extending the most significant bits of a negative Number arithmetically. The endian parameter may be omitted, undefined, "LE" or "BE". If omitted or undefined, the endian parameter defaults to "BE". If the endianness is "BE", the bytes are ordered from most to least significant, and if the endianness is "LE", they are ordered from least to most significant. If this Number translates to bits that cannot be represented ; toBitArray(length) BitArray : Returns this as a BitArray of the given length, extending the most significant bits of a negative Number arithmetically. The bits are ordered from most to least significant. ; toBitString(length) BitString : Returns this as a BitString of the given length, extending the most significant bits of a negative Number arithmetically. The bits are ordered from most to least significant. == General Requirements == All of the properties specified on prototypes are not <nowiki>[[Enumerable]]</nowiki> on instances. Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii", "utf-8", and "utf-16". Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. Charsets are case insensitive. Endianness arguments are case insensitive. = Rationale = The idea of using the particular ByteString and ByteArray types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/commonjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion. == Structures == This proposal is not an object oriented variation on Perl, PHP, Python, or Ruby's pack, unpack, and calcsize with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/commonjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[../|prior art]]. == Encoding Methods == This proposal also does not provide separate member functions for any particular subset of the possible charsets, encodings, compression algorithms, or consistent hash digests that might operate on a byte string or array, for example "toBase64", "toMd5", or "toUtf8" are not specified. Instead, "toString" accepts IANA charset names and radix numbers for charsets and encodings. The intent is that implementations will opt to make this extensible by falling back to an "encodings" module and searching for modules by the same name and calling "encode" or "decode" exports on those modules if they exist. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). == <nowiki>[[Get]]</nowiki> and <nowiki>[[Put]]</nowiki> == This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the CommonJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). == Future Proofing == This proposal suggests that the specified data types should be exported by a "binary" module. The intent is that eventually ECMAScript will specify native types to replace these, and these new types would be hosted as "primordials", free variables available in all top-level scopes. Because these types are specified to be exported by the "binary" module, there is some ambiguity of whether "instanceof" relationships would be maintained when references are passed among global contexts. It would be valuable for these identities to be preserved. For module systems that share a common global scope, this would suggest that the binary types should be patched into some commonly shared object, like the global scope, only if they do not yet exist. That would permit the first, permissive context to construct the types, and all subsequent sandboxes to share them. Secure sandboxes would have to make other accomodations. == Memory Optimization == In contrast to Maciej Stachowiak's [https://mail.mozilla.org/pipermail/es-discuss/2009-November/010132.html proposal], there are no methods for explicitly managing the mutability of the underlying buffer. Since it is possible for implementations to explicitly use ownership and copy-on-write flags, it is desirable to keep the memory management beneath the surface of JavaScript. For example, with freezing semantics as proposed by Maciej, freezing a mutable byte array could produce an immutable byte string that usurps ownership of the original byte array's buffer, so there would be no need for allocation. However, this would render the original byte array unusable, and all persisting references to that array would be broken and we would have to define failure modes for that object. Alternately, the byte array and byte string could share the buffer. The byte string would be guaranteed to not modify the content of the buffer, and if the owner of the original byte array were to perform a modifying operation on the byte array, the implementation could at that time incur the cost of copying the buffer. Similar optimizations could be applied by all ByteString and ByteArray constructors and conversion functions. == Genericity == In accordance with Daniel Friesen's [[Binary/C]], a high priority in this proposal was duck typing. ; a generic way to get a value in the Content type of a ByteArray, ByteString, or String : <nowiki>[[Get]]</nowiki> ; a generic way to get the type of what is returned by <nowiki>[[Get]]</nowiki> for ByteArray, ByteString, and String (Number, ByteString, and String respectively): : Content ; a generic way to get a ByteString for the value at an offset for either ByteArray or ByteString : byteStringAt(offset) ByteString ; a generic way to get a ByteArray for the value at an offset for either ByteArray or ByteString : would have been wasteful to include since byte arrays are meant for assembling large byte buffers through copying data from other binary collections, not for allocation churn. ; a generic way to get a Number for the value at an offset for any ByteArray, ByteString, Array, or String : valueAt(offset) Number ; a generic way to get an object of length one in the same type that contains just the value at a given offset for any ByteArray, ByteString, Array, or String : slice(offset, offset + 1) The following methods and properties are interoperable among ByteArray, ByteString, Array, and String: * <nowiki>[[Get]]</nowiki> * indexOf * lastIndexOf * slice The following methods and properties are interoperable among ByteArray, ByteString, and String: * <nowiki>[[Get]]</nowiki> * Content * valueAt * join * split * splitRight * indexOf * lastIndexOf * slice The following methods and properties are interoperable between ByteArray and ByteString: * <nowiki>[[Get]]</nowiki> * Content * valueAt * byteStringAt * indexOf * lastIndexOf * slice * copy * range The following methods and properties are interoperable between ByteString and String: * <nowiki>[[Get]]</nowiki> * Content * valueAt * indexOf * lastIndexOf * slice * substr * substring The following methods are interoperable between ByteArray and Array: * <nowiki>[[Get]]</nowiki> * indexOf * lastIndexOf * slice * forEach * every * some * map == Idempotence == [[Binary/B]] had a "decodeToString" method and "toString" was required to be distinct, to avoid decoding and encoding hazards. However, in keeping with the existing Number.prototype.toString(radix), for subjective aesthetic reasons having worked with prototypes of both, and because it easier to remember which way encoding and decoding go with "toString", "toByteString", and "toByteArray" than with "encode" and "decode", this proposal eschews "decodeToString". This has the side effect of making the generic "toByteString" and "toString" methods idempotent for converting to and from a charset. For example, if you receive an object that may be a ByteString or a String, but if it is a String it will need to be converted to a ByteString with a given charset, you can simply call "toByteString" with that charset, even repeatedly. Likewise, if you receive a ByteString or a String and you need it to be a String, you can simply call "toString" with the desired charset, allowing a succession of adapters or decorators to make the conversion at any point along the way. == Binary Object == This proposal omits the "Binary" type from [Binary/B] in anticipation that "ByteArray" and "ByteString" may become native types, in which case they would not be objects. Presently, any "String" constructed with the "new" keyword is not a native string, but a "boxed" wrapper object for a String. <source> assert.equals(typeof "", "string"); assert.equals("" instanceof String, false); assert.equals(new String() instanceof String, true); assert.equals(typeof new String(), "object"); assert.equals(new String().slice() instanceof String, false); assert.equals(Object.prototype.toString.call(""), "[object String]"); </source> This anticipates that the following would be true in an ECMA specification: <source> assert.equals(typeof "", "byteString"); assert.equals("" instanceof ByteString, false); assert.equals(new ByteString() instanceof ByteString, true); assert.equals(typeof new ByteString(), "object"); assert.equals(new ByteString().slice() instanceof ByteString, false); assert.equals(Object.prototype.toString.call(""), "[object ByteString]"); </source> This means that this specification does not provide a facility for checking whether a reference is either of the binary types: byte string or byte array, any more than it provides a direct facility for checking whether an object is either a String or a ByteString. However, it should serve in practice to call "toByteString(charset)" or "toString(charset)" to coerce either type to "ByteString" or "String". If the "charset" is not a useful argument, as it would be to convert a byte string to a byte string, this specification mandates that it be ignored. This specification also deliberately avoids specifying whether the "typeof" operator on binary types should return "object" or some other value, and whether "instanceof" between a binary instance and its factory function returns true, as it is anticipated that this will be false in the future, but may be onerous to prevent from being true in the short term. This is to permit CommonJS implementations to take a breadth of approaches to providing the type today. This specification, however, does require constructing binary types with "new" to throw an error, in anticipation that that code pattern will eventually return a boxed type. == Miscelaneous == "ByteString" does not implement "toUpperCase" or "toLowerCase" since they are not meaningful without the context of a charset. Unlike the "Array", the "ByteArray" is not variadic so that its initial length constructor is not ambiguous with its copy constructor. The [[Binary/B]] proposal, at Ash Berlin's recommendation, had split methods on both ByteStrings and ByteArrays that accepted as their optional second argument, an object of options for both the number of delimiters to match, but whether to include the delimiter on the right side of each term, presumably including a terminal delimiter that would obviate an empty collection from being returned as the last value. This has been left as an exercise for a byte reader stream's "readLine(delimiter)" method, so that this proposal's split and splitRight methods may more closely resemble their cousins on existing Strings in JavaScript and other languages. The "join" methods on "ByteArray" and "ByteString" differ from what you would expect in JavaScript based on Array joins, in a way that will be familiar and probably upsetting coming from Python. The delimiter is the left side of the expression. This is because the Array joining method can not be practically extended to determine whether to return a String, ByteString, or ByteArray based on the types of all of the values it contains. It is far more practical to multi-plex the return type based on the type of the left hand side of the expression. This proposal calls for extensions to existing types. This does not mean that this specification encourages the practice of monkey-patching. Ideally, this proposal would be implemented at the very lowest levels of each engine, augmenting the existing primordial types before a line of JavaScript is evaluated. However, this specification does not prevent implementations from performing these augmentations either as a stop-gap or as standard practice (as in V8) in JavaScript as part of the engine's bootstrapping process. This suggests that it is not the responsibility of the "<tt>binary</tt>" module to construct these types, but merely to host them. If multiple modules systems share the same primordial objects, the instantiation of the binary module should not cause these types to be recreated or to not be referentially identical. The "Content" property begins with a capital letter to distinguish it as a factory method like the constructor function to which it always refers, albeit ByteString, ByteArray, or Number. To date, this remains a point of discussion. Daniel Friesen's proposal [[Binary/C]] uses the name "contentConstructor". = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/commonjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] * [http://groups.google.com/group/commonjs/browse_thread/thread/98c51580a47e855e Binary D ready for review] * [http://groups.google.com/group/commonjs/browse_thread/thread/f609c72c9749e2c3 Binary/D Draft 2] = Todo = # chronicle the rationale for bit and byte types supported at this architecture layer # write a section on what kinds of additional requirements could be expected in a future revision of the specification 336 2762 2010-05-05T21:41:45Z Dantman 1 /* body */ Maybe I'll install Cite later... JSGI Level 0/A Draft 2 Proposal (AKA JSGI 0.3) == Philosophy == * Straightforward but convenient mapping to HTTP and existing gateway interface conventions * Suitable for extension with a defined mechanism for Extension Proposals * Cosmetic modifications more inline with JavaScript conventions and idioms === Principles === * Discourage duplicate data in request and response objects * Optimize for the Application developer, not the Server or Middleware developer * Adhere to HTTP semantics wherever possible == Specification == === Application === A JSGI Application is a JavaScript Function which takes exactly one argument, the [[#Request|Request]] as a JavaScript Object, and returns its [[#Response|Response]] as a JavaScript Object containing three required attributes: '''status''', '''headers''' and '''body''' ('''DL: should we mention `then` here?'''). === Middleware === JSGI Middleware are JSGI Applications that can call other JSGI Applications. Middleware can be stacked up into a call chain to provide useful services to Requests and Responses. === Server === A JSGI Server is the glue that connects JSGI Applications to HTTP request and response messages. ('''DL: this definition sucks, but Server should be defined...ideas?''') === Request === The request environment MUST be a JavaScript Object representative of an HTTP request. Applications are free to modify the Request. ==== Required Keys ==== The Request is required to include these keys: * '''.method''': The HTTP request method, such as "GET" or "POST". Request's method cannot be undefined and so MUST be present with a value of an UPPERCASE string. * '''.scriptName''': The initial portion of the request URL's "path" that corresponds to the Application object, so that the Application knows its virtual "location". This MAY be an empty string, if the Application corresponds to the "root" of the Server. ''Restriction: if non-empty `scriptName` MUST start with "/", MUST NOT end with "/" and MUST NOT be decoded.'' * '''.pathInfo''': The remainder of the request URL's "path", designating the virtual "location" of the Request's target within the Application. This may be an empty string, if the request URL targets the Application root and does not have a trailing slash. ''Restriction: if non-empty `pathInfo` MUST start with "/" and MUST NOT be decoded.'' * '''.queryString''': The portion of the request URL that follows the first "?", if any. ''Restriction: MAY be an empty string but `queryString` key MUST NOT be undefined.'' * '''.host''': The portion of the request URL that follows the `scheme`. ''Restriction: MUST be non-empty String, MUST NOT contain a colon or slash.'' ''Note: when combined with `scheme`, `port`, `scriptName`, `pathInfo`, and `queryString` this variable can be used to complete the URL. However Request's `headers.host`, if present, should be used in preference to `host` for reconstructing the request URL.'' '''DL: not according to RFC 2616: If Request-URI is an absoluteURI, the host is part of the Request-URI. Any Host header field value in the request MUST be ignored.''' * '''.port''': Representative of the Request port. If `host` is followed by a colon this is all digits following this colon. If not present in the request URL `port` can be derived from the `scheme`. ''Restriction: MUST NOT be undefined and MUST be an integer. * '''.scheme''': URL scheme (per [http://www.ietf.org/rfc/rfc1738.txt RFC 1738]). "http", "https", etc. * '''.input''': The request body. ''Requirement: MUST be an input stream.'' * '''.headers''': Variables corresponding to the client-supplied HTTP request headers are stored in the `headers` object. The presence or absence of these variables should correspond with the presence or absence of the appropriate HTTP header in the request. All keys in the `headers` object MUST be the lower-case equivalent of the request's HTTP header keys. ''See: [[#Examples|example requests]] for more details.'' * '''.jsgi''': The Request MUST include these JSGI-specific variables in a `jsgi` key: ** '''.jsgi.version''': The Array [0,3], representing this version of JSGI. ** '''.jsgi.errors''': Stream for Application errors ('''anyone have better wording?'''). ''Requirement: MUST be an output stream.'' ('''MOB: shouldn't this also be moved to the top level?''') ** '''.jsgi.multithread''': truthy if the Application object may be simultaneously invoked by another thread in the same process, otherwise falsey. ** '''.jsgi.multiprocess''': truthy if an equivalent Application object may be simultaneously invoked by another process, otherwise falsey. ** '''.jsgi.runOnce''': truthy if Server expects (but does not guarantee) that the Application will only be invoked this one time during the life of its containing process, otherwise falsey. ''Note: normally, this will only be true for a server based on CGI (or something similar).'' ** '''.jsgi.cgi''': CGI version Array in [major, minor] form if Server is implemented atop CGI, otherwise falsey. ** '''.jsgi.ext''': Defined in the [[#Extensions|Extensions]] section. * '''.env''': The top level of the Request object SHOULD only consist of the keys specified above. Servers and Middleware MAY add additional information the `env` key. Servers are encouraged to add any additional relevant data relating to the Request in a key in the `env` object. ''Requirements: MUST be an object.'' ==== Optional Keys ==== The Request MAY contain contain these keys: * '''.authType''': Corresponds to the CGI key AUTH_TYPE * '''.pathTranslated''': Corresponds to the CGI key PATH_TRANSLATED * '''.remoteAddr''': Corresponds to the CGI key REMOTE_ADDR * '''.remoteHost''': Corresponds to the CGI key REMOTE_HOST * '''.remoteIdent''': Corresponds to the CGI key REMOTE_IDENT * '''.remoteUser''': Corresponds to the CGI key REMOTE_USER * '''.serverSoftware''': Corresponds to the CGI key SERVER_SOFTWARE ('''DL: added the above keys (everything spec'd by CGI) to effectively ''reserve'' them in the top level request so that we can safely extend the JSGI spec without worrying about conflicts -- is this alright?''') === Response === Applications MUST return a JavaScript Object representative of an HTTP response: ==== status ==== The status MUST be a three-digit integer ([http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1 RFC 2616 Section 6.1.1]) ==== headers ==== MUST be a JavaScript object containing key/value pairs of Strings or Arrays. Servers SHOULD output multiple headers for `header` values supplied as Arrays. All keys MUST be lower-case. The `headers` object MUST NOT contain a `status` key and MUST NOT contain key names that end in `-` or `_`. It MUST contain keys that consist of letters, digits, `_` or `-` and start with a letter. Header values MUST NOT contain characters below 037. * '''content-type''': There MUST be a `content-type` header key, except when the [#status Status] is 1xx, 204 or 304, in which case `content-type MUST NOT be present. * '''content-length''': There MUST NOT be `content-length` header key when the Status is 1xx, 204 or 304. ==== body ==== MUST be an object which responds to `forEach` and MUST only yield objects which have a toByteString method (including Strings and Binary<ref>Binary, as defined in [[Binary/D]] ('''DL: or whatever binary module is ratified''') objects</ref>). If `body` responds to close, it SHOULD be called after iteration. == Conventions == To facilitate interoperability among JSGI Applications and Servers, Applications SHOULD be added as the `app` key on their module's `exports` object. Upon initialization Servers MUST provide an object representative of every Request's `jsgi` object as a second argument to the `app` function. ('''AB: this needs more detail''') === Extensions === This specification can be extended by JSGI Extension Proposals. Ratification of extensions occurs by the standard [[Process|CommonJS process]]. An Extension Proposal MUST specify a key String and version Array to be placed in `request.jsgi.ext` to be ratified. ---- '''The following sections of this specification are non-normative.''' ---- == Rationale == Multiple header values with the same key should now be provided as an Array value. JSGI 0.2 specified this as a string containing `\n` but working with them as arrays is easier and should a middleware mistakenly concatenate to the header value Array's toString will do the right thing [http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2 according to RFC 2616] and coerce header value into a comma-joined string. Header casing is specified as lower-case to aid interoperability amongst middleware. While case is irrelevant according to RFC 2616 Servers MAY correct the case of Response header keys or expose this functionality to Applications. ('''DL: notes about potential CGI information loss, particularly with regard to decoded paths, headers actually containing an _ and multiple headers, as well as the security implications (X_FORWARDED_FOR/x-forwarded-for''') (AB: If server on top of CGI and undecoded PATH_INFO available, we should note that servers should use it) ('''DL: there should be a note about forEach for sync streaming and a promise's progressCallback for async streaming, which has been the subject of confusion. Any other areas that deserve special explanation?''') == Changes from [http://jackjs.org/jsgi-spec.html JSGI 0.2] == == Specification changes == * Added definitions for Middleware and Server * Added specification for Extensions === Request changes === * Explicitly override CGI-like variables: ; Required : env.REQUEST_METHOD => request.method : env.SERVER_PROTOCOL => request.version, parsed "HTTP/1.1" => [1, 1] : env.SERVER_NAME => request.host : env.SERVER_PORT => request.port, parsed : env.SCRIPT_NAME => request.scriptName, MUST NOT be decoded, MUST NOT end in slash : env.PATH_INFO => request.pathInfo, MUST NOT be decoded : env.QUERY_STRING => request.queryString ; Optional : env.AUTH_TYPE => request.authType : env.PATH_TRANSLATED => request.pathTranslated ''DL: this is duplicate data, should we forbid?'' : env.REMOTE_ADDR => request.remoteAddr ''DL: remoteAddress?'' : env.REMOTE_HOST => request.remoteHost : env.REMOTE_IDENT => request.remoteIdent ''DL: remoteIdentity?'' : env.REMOTE_USER => request.remoteUser : env.SERVER_SOFTWARE => request.serverSoftware ; Forbidden : env.CONTENT_TYPE: exists in request.jsgi.headers["content-type"] if applicable : env.CONTENT_LENGTH: exists in request.jsgi.headers["content-length"] if applicable : env.GATEWAY_INTERFACE: exists in request.jsgi.cgi if applicable * Allow request.headers["content-length"] and request.headers["content-type"] and disallow env.CONTENT_LENGTH and env.CONTENT_TYPE * Add request.env object for all non-specified keys * Move env["jsgi.url_scheme"] to request.scheme * Move env["jsgi.input"] to request.input ==== request.jsgi ==== * Move env["jsgi.*"] to request.jsgi.* * Added request.jsgi.ext required object * Move request.jsgi.run_once to request.jsgi.runOnce ('''DL: Mike Wilson suggested this be camelCase like everything else and noone objected -- speak up if you don't like''') * Server SHOULD add request.jsgi.async key if Server supports returning response as promise * Add request.jsgi.cgi key if Server sits atop CGI ** Note CGI security deficiencies, e.g. X_FORWARDED_FOR/x-forwarded-for * Bump request.jsgi.version to [0,3] ==== request.headers ==== * Move env["HTTP_*"] to request.headers.* (eliminating the "HTTP_" prefix) * Header keys MUST be lowercase but otherwise SHOULD be equivelent to the HTTP request headers ** Compliant Servers MUST ''unmangled'' header keys if CGI (replace(/_/g, "-")) * Servers MAY provide request header values as Array of Strings if HTTP request contains multiple headers with the same key '''(DL: should this be SHOULD? It's impossible with CGI -- any ideas?)''' ==== request.env ==== * All custom keys added to the request by Servers or Middleware MUST be placed in request.env === response === * Specify status, headers and body keys MUST be present in Response OR Response must contain a '''then''' function that, when resolved, returns an object with all three keys * Middleware SHOULD preserve additional keys supplied in response object if not intending to supersede it ==== response.status ==== * No changes ==== response.headers ==== * The header MUST be a JavaScript Object containing values which are Objects that respond to toString * Keys MUST be in lower-case form * If a header value responds to a forEach method Server SHOULD provide multiple HTTP headers with values corresponding to toString ==== response.body ==== * If the Body responds to '''close''' it MUST be called after iteration with the same arguments passed to forEach === Conventions === * Applications: SHOULD be added as the `app` key on their module's `exports` object for interoperability. * Servers: To allow Applications on Servers with unsupported features to fail fast servers must now supply the contents of the `jsgi` key as a second argument to the Application. == Examples == === Request === <pre> { version: [1, 1], // parsed HTTP version ~ "HTTP/1.1" method: "GET", headers: { // HTTP headers, lowercased but otherwise unmangled host: "jackjs.org", "user-agent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.3) Gecko/20090824 Firefox/3.5.3", accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "accept-language": "en-us,en;q=0.5", "accept-encoding": "gzip,deflate", "accept-charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.7", "keep-alive": "300", connection: "keep-alive", "if-modified-since": "Fri, 04 Sep 2009 07:47:22 GMT", "cache-control": "max-age=0" }, input: (new InputStream), // request body stream scheme: "http", host: "jackjs.org", port: 80, env: { // this is the place where Server and Middleware put keys juice: { version: [0, 1] }, jack: { request: null } }, jsgi: { version: [0, 3], errors: (new OutputStream), multithread: false, multiprocess: true, runOnce: false, async: true, cgi: false // [1, 1] if CGI/1.1 } } </pre> ('''DL: I'd like to have at least a simple response and Async Extension promise response example''') == Acknowledgements == This specification is adapted from the [http://rack.rubyforge.org/doc/files/SPEC.html Rack specification] written by Christian Neukirchen. Some parts of this specification are adopted from [http://www.python.org/dev/peps/pep-0333/ PEP333: Python Web Server Gateway Interface v1.0]. Special thanks to the many contributors of the CommonJS group. 337 1812 2009-12-01T20:39:02Z Mdaniel 45 initial revision == Matthew L Daniel == http://MatthewDaniel.com/ 338 1824 2009-12-04T23:41:30Z Deanlandolt 15 added placeholder This is a placeholder for a strawman for a JSGI Request object wrapper (formerly referred to as JSGI Level 1). .jsgi.ext.request = [0,1] 339 1842 2009-12-11T01:53:00Z Kriszyp 39 Replaced content with 'Event Queue Module specification for the Reactor pattern '''STATUS: PROPOSAL''' The event queue module exists for the purpose of maintaining an event queue and running an e…' Event Queue Module specification for the Reactor pattern '''STATUS: PROPOSAL''' The event queue module exists for the purpose of maintaining an event queue and running an event loop based on that queue. == Proposals == # [[Reactor/A]] Proposal A 340 1855 2009-12-11T16:55:39Z Okito 50 /* Functions */ Event Queue Module specification for the Reactor pattern '''STATUS: PROPOSAL''' == Specification == The event queue module exists for the purpose of maintaining an event queue and running an event loop based on that queue. The "reactor" top-level module must export enterEventLoop, enqueue, shutdown, hasPendingEvents, processNextEvent, and optionally getNextEvent. === Functions === ; enterEventLoop(onIdle) : Enters the event loop, sequentially processing each event in the queue and blocking (waiting) for events when the queue is empty. This should continue to loop until shutdown is called and all the events are processed. If a function is provided as the first parameter, it should be called after any event finishes processing and the queue is empty. ; enqueue(task, priority) boolean : Adds a new event to the event-queue. The first parameter, task, should be a function that will be added to the queue and then executed when its is removed from the queue. The second parameter is a number that indicates the requested priority of the task. The handling of the priority parameter is implementation specific and it may be ignored. This returns true if the task was successfully added the queue, otherwise it should return false (generally only the case if the event loop is shutting down). ; shutdown() : This makes a request to exit the event loop. The event loop will continue processing all the events in the queue, but the enqueue operation should not allow any events to be added. One the event loop has processed all the events in the event queue, enterEventLoop should return. ; hasPendingEvents() : Determines whether or not the event-queue has events that are ready to be processed. Returns true if there are pending events at the time the function was called. ; processNextEvent(mayWait) : Processes the next pending event. If there aren't any pending events, this method may wait -- depending on the value of the mayWait parameter -- until an event is enqueued in this queue. This method is re-entrant. If the mayWait parameter is true, this method blocks until an event is available to process if the event queue is empty. If false, this method returns immediately if the queue is empty. This returns true if an event was processed, or false if there were no pending events. ; getNextEvent() : If implemented, this returns the next event function to be processed, removing it from the queue. this method blocks until an event is available if the event queue is empty. ; timer setTimeout(func, delay, context, ...param) : Schedules a one shot timer to execute the passed function after "delay" milliseconds. If "context" is passed, the function will be bound to it when invoked. Any additional parameters should be curried and passed as params to the function as well. This method does not offer a real-time guarantee. The passed function will execute eventually but it may be delayed if the process is busy executing other code in the mean time. Returns an opaque object referencing the scheduled timer. ; void clearTimeout(timer) : Removes a previously scheduled one-shot timer from the event loop. If the passed timer object is not valid or if it has already fired, this function has no effect. ; timer setInterval(func, delay, context, ...param) : Works just like setTimeout() with the same params except the function will execute periodically every "delay" milliseconds until the timer is explicitly cancelled. ; void clearInterval(timer) : Removes a previously scheduled interval timer from the event loop. If the passed timer is not a valid interval timer or if it has already been cancelled, this function has no effect. == Open Issues == * If a timeout timer or an interval timer is scheduled, should the process exit when the main code finishes executing? If so, how do we blend that with the event-drive API of the browser or node.js where you run an implicit event loop? A generic wait() function won't work because you can't actually block in the browser. [Charles Jolley] * The browser does not support explicit control over it's event loop. This means you pretty much cannot implement any of the above methods except for enqueue(), setTimeout(), clearTimeout(), setInterval(), and clearInterval(). Perhaps the loop control methods should be made optional? [Charles Jolley] 341 1848 2009-12-11T02:12:37Z Kriszyp 39 Created page with 'Worker Module Specification '''STATUS: PROPOSAL''' The worker module exists for the purpose of creating workers, concurrent shared nothing processes/threads, that can communica…' Worker Module Specification '''STATUS: PROPOSAL''' The worker module exists for the purpose of creating workers, concurrent shared nothing processes/threads, that can communicate with other workers with message passing. == Proposals == The 'worker' module must export Worker, SharedWorker, and optionally name. Worker and SharedWorker are constructors that follow the W3C/HTML5 WebWorkers specification: http://dev.w3.org/html5/workers/ The primary difference is that script names should follow CommonJS module naming mechanism, and should be resolved using the same mechanism the 'require' function. The 'worker' module may also export a 'name' property that indicates the name of the current worker (if started as a named SharedWorker). 342 1858 2009-12-15T00:25:05Z IsaacSchlueter 52 link to setExports discussion setExports function discussion: http://groups.google.com/group/commonjs/browse_thread/thread/11c6f25c46b3837b 343 2821 2010-06-12T01:26:03Z Jhuni 106 '''STATUS: PROPOSAL, DISCUSSION''' == Specification == This proposal amends [[Modules/1.1]]. * The "module" free variable exposes a "setExports" function. * This function sets the module's export to the first argument, and returns it. * To prevent problems with inconsistencies in the case of circular dependencies, if the module has already been required by another module, calling module.setExports() must throw an Error. == Relevant Discussions == * http://groups.google.com/group/commonjs/browse_thread/thread/11c6f25c46b3837b/c208f92d98c4f72c == Show of Hands == Those in favor of incorporating this proposal in the next minor revision of Modules/1: * Isaac Schlueter * Dean Landolt * Kevin Dangoor * Kris Zyp * Francisco Tolmasky * Jhuni Those against: * Mark S. Miller -- keep it simple. Why is there even a "module" free variable anyway? * Ihab Awad * Wes Garland * Ondrej Zara -- a sane function (require) ought to return one data type * Daniel Friesen * Tom Robinson == Prototypes == * Node (isaacs branch) * Narwhal (kriskowal's refactor and using-packages branches, landing in the 0.3 timeframe if ratified) 344 2769 2010-05-12T03:31:34Z Cadorn 60 /* Roadmap */ '''STATUS: [[/1.0|1.0]] RATIFIED''' == Specifications == * [[Packages/1.0]] concerning the package layout format and package descriptor schema == Roadmap == * System Packages [[/1.0|1.0]] (''ratified'') * System Packages [[/1.1|1.1]] (''draft'') * Package Catalogs * Using Packages ([[/A|background]]) == Open Issues for Next Versions == * Make bugs optional [http://groups.google.com/group/commonjs/browse_thread/thread/c70af7ad188d6082] * License is slightly misleading [http://groups.google.com/group/commonjs/browse_thread/thread/c70af7ad188d6082] * Make repositories optional [http://groups.google.com/group/commonjs/browse_thread/thread/c70af7ad188d6082] * Make depedencies optional [http://groups.google.com/group/commonjs/browse_thread/thread/c70af7ad188d6082] * Make properties that start with & and _ and possibly the "type" attribute reserved for package registries. [http://groups.google.com/group/commonjs/browse_thread/thread/c70af7ad188d6082] * Make "engines" a map of engine names to required versions [http://groups.google.com/group/commonjs/browse_thread/thread/d079d42067a3598c] == Proposals == * [[Packages/B]] concerning the package layout format, package descriptor schema, and eventually a catalog schema 345 2900 2010-09-11T14:34:26Z AzaToth 133 /* Catalog Properties */ added note for chekcsums to be automatically added, also add example sha1,sha256 (undef which sums should be available) {{Spec |status=ratified |standard=yes }} == Packages == This specification describes the CommonJS package format for distributing CommonJS programs and libraries. A CommonJS package is a cohesive wrapping of a collection of modules, code and other assets into a single form. It provides the basis for convenient delivery, installation and management of CommonJS components. This specifies the CommonJS package descriptor file and package file format. It does not specify a package catalogue file or format; this is an exercise for future specifications. The package descriptor file is a statement of known fact at the time the package is published and may not be modified without publishing a new release. == Package Descriptor File == Each package must provide a top-level package descriptor file called "package.json". This file is a JSON format file. Each package must provide all the following fields in its package descriptor file. * name - the name of the package. This must be a unique, lowercase alpha-numeric name without spaces. It may include "." or "_" or "-" characters. It is otherwise opaque. * description - a brief description of the package. By convention, the first sentence (up to the first ". ") should be usable as a package title in listings. * version - a version string conforming to the Semantic Versioning requirements (http://semver.org/). * keywords - an Array of string keywords to assist users searching for the package in catalogs. * maintainers - Array of maintainers of the package. Each maintainer is a hash which must have a "name" property and may optionally provide "email" and "web" properties. For example: "maintainers":[ { "name": "Bill Bloggs", "email": "billblogs@bblogmedia.com", " web": "http://www.bblogmedia.com", }] * contributors - an Array of hashes each containing the details of a contributor. Format is the same as for author. By convention, the first contributor is the original author of the package. * bugs - URL for submitting bugs. Can be mailto or http. * licenses - array of licenses under which the package is provided. Each license is a hash with a "type" property specifying the type of license and a url property linking to the actual text. If the license is one of the [http://www.opensource.org/licenses/alphabetical official open source licenses] the official license name or its abbreviation may be explicated with the "type" property. If an abbreviation is provided (in parentheses), the abbreviation must be used. "licenses": [ { "type": "GPLv2", "url": "http://www.example.com/licenses/gpl.html", } ] * repositories - Array of repositories where the package can be located. Each repository is a hash with properties for the "type" and "url" location of the repository to clone/checkout the package. A "path" property may also be specified to locate the package in the repository if it does not reside at the root. For example: "repositories": [ { "type": "git", "url": "http://github.com/example.git", "path": "packages/mypackage" } ] * dependencies - Hash of prerequisite packages on which this package depends in order to install and run. Each dependency defines the lowest compatible MAJOR[.MINOR[.PATCH]] dependency versions (only one per MAJOR version) with which the package has been tested and is assured to work. The version may be a simple version string (see the version property for acceptable forms), or it may be a hash group of dependencies which define a set of options, any one of which satisfies the dependency. The ordering of the group is significant and earlier entries have higher priority. For example: "dependencies": { "webkit": "1.2", "ssl": { "gnutls": ["1.0", "2.0"], "openssl": "0.9.8", }, } Optional Keywords * "homepage" - URL string for the package web site * "os" - Array of supported operating systems. If absent or set to the empty set, the package makes no platform assumptions. The set of valid os names includes: aix, freebsd, linux, macos, solaris, vxworks, windows. * "cpu" - Array of supported CPU architectures. If absent or set to the empty set, the package makes no platform assumptions. The set of valid cpu names includes: arm, mips, ppc, sparc, x86, x86_64. * "engine" - Array of supported JavaScript engines. If absent or set to the empty set, the package makes no platform assumptions. The set of valid engine names includes: ejs, flusspferd, gpsee, jsc, spidermonkey, narwhal, node, rhino, v8. * "builtin"- Boolean value indicating the package is built in as a standard component of the underlying platform * directories - Object hash of package directories. Typical directories include "lib", "src", "doc", "jars", "test" and "bin". Package manager tools must use these directory definitions to find various package components. * implements - Array of relevant CommonJS specifications this package supports. A specification identifier is the WikiName of the specification prefixed by "CommonJS/". Arbitrary URLs may also be specified to indicate support for externally published specifications. "implements": [ "CommonJS/Modules/1.0", "CommonJS/JSGI/1.0"] * scripts - Object hash of scripts used in managing the package. A package manager tool may use these scripts to install, build, test or uninstall the package. For example: "scripts": { "install": "install.js", "uninstall": "uninstall.js", "build": "build.js", "doc": "make-doc.js", "test": "test.js", } Package managers and loaders should ignore unknown fields in the package descriptor file. The following fields are reserved for future expansion: build, default, email, external, files, imports, maintainer, paths, platform, require, summary, test, using, downloads, uid, type. Extensions to the package descriptor specification should strive to avoid collisions for future standard names by name spacing their properties with innocuous names that do not have meanings relevant to general package management. == Catalog Properties == When a package.json is included in a catalog of packages, the following fields should be present for each package. * checksums - Hash of package checksums. This checksum is used by package manager tools to verify the integrity of a package. For example: checksums: { "md5": "841959b03e98c92d938cdeade9e0784d", "sha1": " f8919b549295a259a6cef5b06e7c86607a3c3ab7", "sha256": "1abb530034bc88162e8427245839ec17c5515e01a5dede6e702932bbebbfe8a7" } This checksum is meant to be automatically added by the catalog service == Package File Format == The package files shall be a simple archive of the package directory including the package.json file in a relative, ZIP archive format (Though this format may change in future revisions of this specification). The archive must have a single top level directory. == Package Directory Layout == A CommonJS package will observe the following: * A package.json file must be in the top level directory * Binary files should be in the "bin" directory, * Javascript code should be under the "lib" directory * Documentation should be under the "doc" directory * Unit tests should be under the "test" directory == Package Files == To install and uninstall a CommonJS package some local installation steps may be required. A package may specify various scripts to run via the "scripts" package.json field. == Other Requirements == * All modules contained in packages must conform to the CommonJS Securable Modules specification. == Example Package Descriptor File == { "name": "mypackage", "version": "0.7.0", "description": "Sample package for CommonJS. This package demonstrates the required elements of a CommonJS package.", "keywords": [ "package", "example" ], "maintainers": [ { "name": "Bill Smith", "email": "bills@example.com", "web": "http://www.example.com" } ], "contributors": [ { "name": "Mary Brown", "email": "maryb@embedthis.com", "web": "http://www.embedthis.com" } ], "bugs": { "mail": "dev@example.com", "web": "http://www.example.com/bugs" }, "licenses": [ { "type": "GPLv2", "url": "http://www.example.org/licenses/gpl.html" } ], "repositories": [ { "type": "git", "url": "http://hg.example.com/mypackage.git" } ], "dependencies": { "webkit": "1.2", "ssl": { "gnutls": ["1.0", "2.0"], "openssl": "0.9.8" } }, "implements": ["cjs-module-0.3", "cjs-jsgi-0.1"], "os": ["linux", "macos", "win"], "cpu": ["x86", "ppc", "x86_64"], "engines": ["v8", "ejs", "node", "rhino"], "scripts": { "install": "install.js", "uninstall": "uninstall.js", "build": "build.js", "test": "test.js" }, "directories": { "lib": "src/lib", "bin": "local/binaries", "jars": "java" } } == Editor Macros/Scripts == Remembering the format and typing the common bits can be boring. So listed below are known editor scripts to make this easier: * [http://gist.github.com/311512 commonjs-package-json.vim] written by Ashb. == Background == * [[Packages-Background]] (discussion) * [http://groups.google.com/group/commonjs/browse_thread/thread/9f73afe65dc33df7 modules packaging] * [http://semver.org/ Semantic Versioning] * [http://github.com/280north/narwhal/blob/master/docs/packages-howto.md How to make packages in Narwhal] 346 1875 2009-12-16T21:10:24Z Mob 56 moved [[PackagesDescriptors/0.1]] to [[Packages/0.1]]:&#32;Simple rename #REDIRECT [[Packages/0.1]] 347 1882 2009-12-16T21:36:32Z KrisKowal 6 moved [[Packages-Background]] to [[Packages/A]]:&#32;organizing #REDIRECT [[Packages/A]] 348 1884 2009-12-16T21:37:17Z KrisKowal 6 moved [[Packages/0.1]] to [[Packages/B]]:&#32;organizing (not a versioned proposal yet) #REDIRECT [[Packages/B]] 349 2498 2010-03-24T11:59:39Z Tobie 102 /* Philosophy */ {{Spec |status=proposal |draft=2 |drafts=1:2344 }} Module transport format is a content format that can be used to send module factories from a server to an asynchronous client-side module loader. A module factory can then be used on the client to instantiate modules. == Specification == Content in module transport format is called a "bundle". # A bundle is a JavaScript program and consists only of any number of calls to a "require.def" function. # "require.def" accepts a top-level module identifier and a "module descriptor" object. # A "module descriptor" consists of: ## A "factory" function. The factory function accepts an object that permits the loader to inject arbitrary dependencies, particularly "require", "exports", and "module" for CommonJS modules. It is the purview of the module text to extract these values. ## A "requires" array of top-level module identifiers corresponding to the shallow dependencies of the given module factory, those that it directly "requires". A module factory must not be called until all of the module desciptors mentioned in the transitive "requires" have been given to a loader by calls to "require.def". == Non-normative Form == The following is an example of the structure of a module transport. All capitals denote meta-syntactic variables; names that would be replaced. Elisions imply continuation, either by repetition or extension as applicable in context. Destructuring notation, as [http://wiki.ecmascript.org/doku.php?id=harmony:destructuring proposed for future ECMAScript] is used here to communicate that the injection argument to the module factory function does not have any particular name, and may not necessarily be bound as anything other than arguments[0], but that it can carry arbitrary values for use by the module; "require", "exports", and "module" are names that must be injected particularly and only necessarily for the case of CommonJS modules. require.def(ID, { "factory": function ({require, exports, module, …}) { MODULE_TEXT }, "requires": […MODULE_IDS], … }); … == Example == Given a CommonJS module "example/point": var Scalar = require("./scalar").Scalar; exports.Point = function (x, y) { return Object.create(exports.Point.prototype, { "x": {"get": function () {retun Scalar(x)}}, "y": {"get": function () {retun Scalar(y)}} }); } This would be the bundle of "example/point": require.def("example/point", { "factory": function () { var exports = arguments[0].exports, require = arguments[0].require, module = arguments[0].module; var Scalar = require("./scalar").Scalar; exports.Point = function (x, y) { return Object.create(exports.Point.prototype, { "x": {"get": function () {retun Scalar(x)}}, "y": {"get": function () {retun Scalar(y)}} }); } }, "requires": ["example/scalar"] }); = Philosophy = Module Transport Format is not intended to be written by hand; it is intended that modules conforming to the CommonJS [[Modules/1.1]] specification can be programmatically wrapped and bundled to Module Transport Format. It would be harmful for modules to be crafted by hand in this format because individual modules and trees of modules would become atonomous and therefore tightly coupled to their module name space. * modules can be dynamically complied to Module Transport Format * all module factories can be registered in a single call, but also * module transport format is concatenatable. * the module descriptor is intentionally an extensible name space. One obvious extension would be a "deepRequires" list that could be used by an asynchronous, client-side module loader that has not been provided fore-knowledge about the transitive dependencies of a module to initiate early and optimially ordered HTTP requests for those dependencies before their shallow dependees are downloaded and registered by "require.def". A good heuristic for optimal order of download for modules is largest to smallest. [{{fullurl:Modules/Transport/B|oldid=2344}} Draft 1] called for "require.def" to accept an object mapping multiple top-level module identifiers to respective module descriptors. In response to Tobie Langel's comment that this would necessitate onerous complication for loaders on Internet Explorer because of the [http://www.dhtmlkitchen.com/learn/js/enumeration/dontenum.jsp#JScriptDontEnumBug "DontEnum" bug], this proposal was revised to accept only one module for each call to "require.def". 350 1932 2009-12-23T07:48:19Z KrisKowal 6 Recommended duck-type nomenclature for collection APIs '''STATUS: RECOMMENDATION. NOT STANDARDS TRACK''' == Lookup Table == ; del(key) this * Deletes an item for a key. * Returns the mutated collection. * For ordered collections, accepts a beginning key and an ending key, deleting all items in that range of keys excluding the ending key. * Implemented in terms of remove. ; set(key, value) this * Adds or overwrites an item for a key. * Returns the mutated collection. * Implemented in terms of insert. ; cut(key, value_opt) Value * Deletes an item for a key. * If no item has the given key and no default value is provided, throws a KeyError. * Returns the corresponding value, or the default value. * Implemented in terms of get and del. ; has(key, eq_opt, hash_opt) Boolean * Returns whether key is among items. ; put(key, value) Value * Adds an item for a key. * returns the mutated collection. * In an ordered collection, reserves the right to change the keys of some other items to make room for the new item by shifting later items right. * Throws a key error if there is already an item with that key and it cannot be moved to a different key. * Implemented in terms of set and has. ; get(key, value_opt) Value * Returns a value for the given key. * If there is no value for the given key and no default value is provided, throws a KeyError. * Implemented in terms of retrieve and has. ; getset(key, value) Value * If there is no value for the given key, sets the value for the key to the given value. * Returns the value for the given key. * Implemented in terms of get and set. ; keys() Set of Key ; values() Array of Value ; items() Array of [Key, Value] pairs == Lookup Set == ; insert(item, eq_opt, hash_opt) this * Adds or overwrites a value. * Returns the mutated collection. * Defaults to an implementation in terms of find and set. ; retrieve(item, eq_opt, hash_opt) Item * Returns the contained value that is naturally equivalent to a given value. * Throws a value error if none exists. * Defaults to an implementation in terms of find and get. ; remove(item, eq_opt, hash_opt) this * Removes a value. * Throws a value error if the value isn't in the collection. * Returns the mutated collection. * Defaults to an implementation in terms of find and del. ; discard(item, eq_opt, hash_opt) this * Removes a value if it exists. * Returns the mutated collection. * Implemented in terms of has and remove. ; find(item, eq_opt, hash_opt) Item * Returns the key for a given value. * Accepts an optional equivalence relation to override the default of eq. 351 1944 2010-01-05T01:37:59Z SubtleGradient 63 This proposal is meant to recognize how some implementations already work and give a name to the two separate existing standards. That way everyone should know what the differences are and the implica == Proposal == This is a proposal for addition to the CommonJS Modules spec to define the two separate options for the, as yet undefined, area of functionality surrounding modules and natives. So far this area has been specifically left undefined as an implementation detail. However, it is the purpose of this proposal to recognize the necessity of explicitly specifying the two major options for how this should be implemented. This proposal is meant to recognize how some implementations already work and give a name to the two separate existing standards. That way everyone should know what the differences are and the implications. == Modules (with global natives) "MGN" == Uses the same natives at the script which loads it. Modifying the prototype of a native from within an MGN module would NOT limit those changes to the scope of the module. e.g. http://gist.github.com/269015 Prior art: script tags in an html page in any browser. Each script runs in the same environment with access to the same natives. == Modules (with sandboxed natives) "MSB" == Uses fresh "sandboxed" natives. Modifying the prototype of a native from within an MSB module would limit those changes to the scope of the module and its exports. Instances of these "sandboxed" natives may be exported using `exports` or available from an exported closure. e.g. http://gist.github.com/268551 Prior art: "How To Subclass The JavaScript Array Object " http://dean.edwards.name/weblog/2006/11/hooray/ == Why do we need to specify this? == Currently many real-world JavaScript libraries and frameworks expect to be able to modify the global environment by extending native prototypes. This is a core feature of JavaScript. Also, making modules secure is a very important feature. Not all implementations of CommonJS support the same things. It's important when talking about an environments support for CommonJS that we be explicit about exactly what level of support they have. Giving these two Module options separate names and separate APIs is important in order to manage user expectation. == API == This proposal is less interested in the specific API implementation of each of these options as it is with specifying that they are separate and important things. One option for the API would be to use a separate function name for requiring: MGN: `require('extend-my-natives')` MSB: `requireSafe('sandbox-my-natives')` An alternative options would be to pass an additional argument to `require` MGN: `require('extend-my-natives')` MSB: `require('sandbox-my-natives', true)` "I personally prefer having separate function names since that's a bit clearer when reading the code. But I'm sure other people care about it more." — Thomas Aylott == Notes == These two specifications are not mutually exclusive. An environment may claim CommonJS compliance if it implements at least one of these Modules specifications. i.e. NodeJS could implement MGN and not MSB and still be a CommonJS compatible environment. == Extending native prototypes is the devil == I know how many people personally feel about extending native prototypes. Many people hang their hearts on their sleeves by using the derogatory term "polluting". I'm sure some would like to freeze the prototypes of all natives. But regardless of how we may personally feel about PrototypeJS, MooTools or whatever other JavaScript we've seen that has possibly abused prototypes in the past. We simply need to recognize that extending native prototypes is a very basic core feature of JavaScript that needs to be more easily and explicitly supported. 352 2103 2010-02-14T05:39:55Z Intrader 74 /* How Modules relate to Global Natives */ == How Modules relate to Global Natives == Currently as of Modules 1.1 the spec for how an environment chooses to implement native classes in Modules is "undefined". That means it's up to each environment implementation to decide how it should work. """To a developer "undefined" means that you cannot count on any specific behavior. If you take advantage of an "undefined" behavior, that means that there's a chance that behavior could break in the future, or break on a different platform. If you don't monkey with the globals, your app will work fine across CommonJS implementations (barring other, unrelated, compatibility issues of course)""" — Kevin Dangoor There's no way of knowing what will happen if you modify a native from inside a Module. So how would you safely go about doing it according to the current spec? === How to do it now === [http://gist.github.com/268543 Example of how to extend prototypes using a CommonJS Module] === Can this change in the future? === [[Modules/ProposalForNativeExtension|Proposal for explicit native use in Modules]] === Discussions === * http://groups.google.com/group/commonjs/browse_thread/thread/2e91a6f12b5c39d9?hl=en * http://groups.google.com/group/commonjs/browse_thread/thread/3a0886456f9fb8cd?hl=en * http://groups.google.com/group/commonjs/browse_thread/thread/87db792cd61d05c2?hl=en 353 1962 2010-01-12T01:24:24Z Pbannister 65 354 1965 2010-01-12T01:50:22Z Pbannister 65 Preston L. Bannister - [mailto:preston@bannister.us preston@bannister.us] / [http://bannister.us/ website] / [http://bannister.us/weblog/ weblog] / 1-949-588-0872 [[File:Preston-2009-03.jpg]] "Running Light without Overbyte" 355 1974 2010-01-12T18:53:40Z Mob 56 moved [[Packages/B]] to [[Packages/1.0]]:&#32;Ratified #REDIRECT [[Packages/1.0]] 356 2817 2010-06-01T14:40:40Z Alexandre.Morgaut 33 Product Manager at [http://www.4d.com 4D] Member of the [http://www.wakandasoft.com Wakanda] Project Team 357 1996 2010-01-17T08:05:59Z KrisKowal 6 Created page with ''''STATUS: PROPOSAL''' This proposal, based on [[Binary/D]], defines types and methods for constructing, manipulating, and transcoding binary data in both mutable and immutable …' '''STATUS: PROPOSAL''' This proposal, based on [[Binary/D]], defines types and methods for constructing, manipulating, and transcoding binary data in both mutable and immutable forms. ByteString resembles its immutable text analog, String, and ByteArray resembles its mutable analog, Array. Both types constrain their data to the byte domain and provide a memory-safe interface to underlying continguous, random-access byte collections. An [http://spreadsheets.google.com/ccc?key=0An5phhxDkYDPdDB1MDZDdGdwbXNxLUFUOFFSX0trVWc&hl=en overview] of the supported types, methods, signatures, and corresponding return types is on Google Docs. = Specification = The "binary" top-level module must export ByteArray, ByteString, and Range. ; Binary : a non-constructable base type for ByteString and ByteArray ; ByteString : immutable, byte quantized ; ByteArray : mutable, explicitly resizable, byte quantized ; Range : a sub-range wrapper object == Binary == A base type for ByteString and ByteArray. Calling and constructing Binary must throw a TypeError. == ByteString == A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array that does not implicitly terminate at the first 0-valued byte. ByteString instances are comparable with the <tt>==</tt> and <tt>===</tt> operators based on equal order and respective values of their content. === Constructor === A ByteString function must exist. Both calling and constructing must return a ByteString Object. <source> ByteString() instanceof ByteString; new ByteString() instanceof ByteString; ByteString() instanceof Binary; new ByteString() instanceof Binary; typeof ByteString() === "object"; typeof new ByteString() === "object"; </source> ; ByteString() : Construct an empty byte string. ; ByteString(byteString) : Copies byteString. ; ByteString(byteArray) : Use the contents of byteArray. For performance, transparently to the layer specified here, the "ByteArray" may relinquish ownership of its underlying byte buffer and switch to a copy-on-write mode. ; ByteString(arrayOfNumbers) : Use the numbers in arrayOfNumbers as the bytes. Coerces Numbers to bytes by selecting their least significant eight bits. ; ByteString(string, charset) : Convert a string. The ByteString will contain string encoded with charset. === Prototype Properties === ; toByteArray() ByteArray : Returns a byte for byte copy in a ByteArray. : ''Note: for best performance, implementations should transfer ownership of the underlying buffer and flag the original owner to copy-on-write.'' ; toByteArray(sourceCharset, targetCharset) ByteArray : Returns this transcoded from the source charset to the target charset as a ByteArray. The source and target charset are internally cast to String with the String constructor. ; toByteString() ByteString : Returns this ByteString. ; toByteString(sourceCharset, targetCharset) ByteString : Returns this transcoded from the source charset to the target charset as a ByteString. The source and target charset are internally cast to String with the String constructor. ; toString() String : Returns a debug representation like "<tt>[ByteString 10]</tt>", where 10 is the length this ByteString. ; toString(charset) String : Decodes this ByteString according to the given character set and returns the String from the corresponding unicode points. May throw a ValueError if the byte string is malformed or if any of the code points are out of the implementation's supported range. ; toArray() Array : Returns an Array containing the bytes as Numbers. ; toSource() String : returns "<tt>require("binary").ByteString([])</tt>" for a null byte string or "<tt>require("binary").ByteString([0, 1, 2])</tt>" for a byte string of length 3 with bytes 0, 1, and 2. ; valueAt(offset_opt) Number : Returns the byte at offset as a Number. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; indexOf(values, start_opt, stop_opt) Number : Returns the index of the first occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; lastIndexOf(values, start_opt, stop_opt) Number : Returns the index of the last occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; range(start_opt, stop_opt) Range : Returns a Range object. The value of stop defaults to the length of this. The value of start defaults to 0. Uses this for the Range's ref property. ; copy(target, targetStart, start, stop) ByteString : Copies the Number values of each byte from this between start and stop to a target ByteArray or Array at the targetStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a ByteArray or Array. Returns this. ; slice(start_opt, stop_opt) ByteString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; substr(start_opt, length_opt) ByteString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substr String.prototype.substr] ; substring(start_opt, last_opt) ByteString : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/substring String.prototype.substring] ; concat(...) ByteString : Returns a ByteString composed of itself concatenated with the given ByteString, ByteArray, and Array values. Throws a TypeError if any of the arguments are not a ByteString, ByteArray, or Array of Numbers. Coerces Numbers to bytes by selecting their least significant eight bits. ; join(array) ByteString : Returns a ByteString of the ByteStrings, ByteArrays, Arrays of Numbers, or a combination thereof, delimited by this. Arrays of Numbers are converted to ByteArrays. Coerces Numbers to bytes by selecting their least significant eight bits. ; split(delimiter_opt, max_opt) Array : Returns an Array of ByteStrings pared from the ByteString between strings of ByteStrings that match the given delimiter for up to the maximum number of delimiters, starting from the left. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteString. The delimiter is internally coerced to a ByteString with the ByteString constructor. ; splitRight(delimiter_opt, max_opt) Array : Returns an Array of ByteStrings pared from the ByteString between strings of ByteStrings that match the given delimiter for up to the maximum number of delimiters, starting from the right. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteString. The delimiter is internally coerced to a ByteString with the ByteString constructor. ; Content : an alias of Number, indicating that Number is the type of what <nowiki>[[Get]]</nowiki> returns. === Internal Properties === ; <nowiki>[[Get]]</nowiki> Number : Returns the byte at offset as a Number. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; <nowiki>[[Put]]</nowiki> : throws a TypeError. === Instance Properties === ; length : The length in bytes. Not <nowiki>[[Writable]]</nowiki>, not <nowiki>[[Configurable]]</nowiki>, not <nowiki>[[Enumerable]]</nowiki>. == ByteArray == A ByteArray is a mutable, flexible (explicitly growable and shrinkable) representation of a C unsigned char (byte) array. === Constructor === A ByteArray function must exist. Calling and constructing a ByteArray both return a new ByteArray instance. <source> ByteArray() instanceof ByteArray; new ByteArray() instanceof ByteArray; ByteArray() instanceof Binary; new ByteArray() instanceof Binary; typeof ByteArray() === "object"; typeof new ByteArray() === "object"; </source> ; ByteArray() : New, empty ByteArray. ; ByteArray(length Number, fill_opt Number) : New ByteArray of the given length, with the given fill number at all offsets. The default filler is 0. ; ByteArray(byteArray) : Copy byteArray. ; ByteArray(byteString) : Copy contents of byteString. ; ByteArray(arrayOfBytes) : Use numbers in arrayOfBytes as contents. Coerces Numbers to bytes by selecting their least significant eight bits. ; ByteArray(string, charset) : Create a "ByteArray" from a "String", the result being encoded with charset. === Prototype Properties === ; toByteArray() ByteArray : Returns a byte for byte copy in a ByteArray. : ''Note: for best performance, implementations should transfer ownership of the underlying buffer and flag the original owner to copy-on-write.'' ; toByteArray(sourceCharset, targetCharset) ByteArray : Returns this transcoded from the source charset to the target charset as a ByteArray. The source and target charset are internally cast to String with the String constructor. ; toByteString() ByteString : Returns a byte for byte copy in a ByteString. : ''Note: for best performance, implementations should transfer ownership of the underlying buffer and flag the original owner to copy-on-write.'' ; toByteString(sourceCharset, targetCharset) ByteString : Returns this transcoded from the source charset to the target charset as a ByteString. The source and target charset are internally cast to String with the String constructor. ; toString() String : Returns a debug representation like "<tt>[ByteArray 10]</tt>", where 10 is the length this ByteArray. ; toString(charset) String : Decodes this according to the given character set and returns the String from the corresponding unicode points. May throw a ValueError if the byte string is malformed or if any of the code points are out of the implementation's supported range. ; toArray() Array : Returns an Array containing the bytes as Numbers. ; toSource() String : returns "<tt>require("binary").ByteArray([])</tt>" for a null byte string or "<tt>require("binary").ByteArray([0, 1, 2])</tt>" for a byte string of length 3 with bytes 0, 1, and 2. ; valueAt(offset_opt) Number : Returns the byte at offset as a Number. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; byteStringAt(offset_opt) ByteString : Returns a unary (length 1) ByteString of the byte at the given offset. The offset is coerced internally with the Number constructor. Thus, if it is omitted or passed as undefined, it defaults to getting the value at offset 0. ; indexOf(values, start_opt, stop_opt) Number : Returns the index of the first occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; lastIndexOf(values, start_opt, stop_opt) Number : Returns the index of the last occurence of of a byte or consecutive bytes as represented by a Number, ByteString, or ByteArray of any length, or returns -1 if no match was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched. start defaults to 0 and stop defaults to the length of this. ; range(start_opt, stop_opt) Range : Returns a Range object. The value of stop defaults to the length of this. The value of start defaults to 0. Uses this for the Range's ref property. ; copy(target, targetStart, start, stop) ByteArray : Copies the Number values of each byte from this between start and stop to a target ByteArray or Array at the targetStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a ByteArray or Array. Returns this. ; copyFrom(source, sourceStart, start, stop) ByteArray : Copies the Number values of each byte from a given ByteArray or ByteString into this from start to stop at the given sourceStart offset. If undefined or omitted, stop is presumed to be the length of this. targetStart, start, and stop are internally coerced to Numbers with the Number constructor. Throws a TypeError if the target is not a ByteArray or Array. Returns this. ; fill(value, start_opt, stop_opt) ByteArray : Fills each of the contained bytes with the given value (either a unary ByteString, ByteArray, or a Number) from the start offset to the stop offset. start and stop must be numbers, undefined, or omitted. If omitted, start is presumed to be 0. If omitted, stop is presumed to beh the length of this ByteArray. If omitted, "value" is presumed to be 0. Returns this. ; splice(start_opt, stop_opt, ...values) ByteArray : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/splice Array.prototype.splice] ; slice(start_opt, stop_opt) ByteArray : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice] ; split(delimiter_opt, max_opt) Array : Returns an Array of ByteArrays pared from the ByteArrays between strings of ByteArrays that match the given delimiter for up to the maximum number of delimiters, starting from the left. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteArray. The dlimiter is internally coerced to a ByteArray with the ByteArray constructor. ; splitRight(delimiter_opt, max_opt) Array : Returns an Array of ByteArrays pared from the ByteArray between strings of ByteArrays that match the given delimiter for up to the maximum number of delimiters, starting from the right. If omitted, the maximum defaults to Infinity. The delimiter defaults to an empty ByteArray. The delimiter is internally coerced to a ByteArray with the ByteArray constructor. ; forEach(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/forEach Array.prototype.forEach] ; every(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/every Array.prototype.every] ; some(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/some Array.prototype.some] ; map(callback[, thisObject]) : See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/map Array.prototype.map] ; Content : an alias of Number, indicating that Number is the type of what <nowiki>[[Get]]</nowiki> returns. === Internal Properties === ; <nowiki>[[Get]]</nowiki> Number : Returns the Number value of a the byte at the given offset. ; <nowiki>[[Put]]</nowiki> Number : Sets the byte value at the given offset. Throws a ValueError if the index is beyond the current bounds of the byte array (byte arrays can be grown or shrunk by explicitly assigning a new length). Implicitly coerces the value to a Number and masks it with 0xFF. === Instance Properties === ; length : The length in bytes. Not <nowiki>[[Configurable]]</nowiki>, not <nowiki>[[Enumerable]]</nowiki>. Assigning to the length of a ByteArray causes the array to reallocate its underlying buffer to the given size, copying the original buffer up to the length of the new buffer if it is less, and filling all bytes beyond the length of the original buffer with the value 0. == Range == A range object is a convenience for copying ranges from one ByteArray or ByteString to another ByteArray. === Constructor === ; new Range({ref, start, stop}) : returns a Range object with the respective properties. === Prototype Properties === ; copy(target, start_opt, stop_opt) : generically calls <codee>this.ref.copy(target, this.start, Math.min(this.stop, this.start + target.length - start), start)</code>. The default value of stop is the target length. ; copyFrom(source, start_opt, stop_opt) : generically calls <code>this.ref.copyFrom(source, this.start, Math.min(this.stop, this.start + source.length - start), start)</code>. The default value of stop is the source length. ; fill(value) : generically calls <code>this.ref.fill(value, this.start, this.stop)</code> ; splice(start_opt, stop_opt, ...values) : generically calls <code>this.ref.splice.apply(this.ref, arguments)</code> == General Requirements == All of the properties specified on prototypes are not <nowiki>[[Enumerable]]</nowiki> on instances. Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation. All implementations MUST support "us-ascii", "utf-8", and "utf-16". Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets. Charsets are case insensitive. Endianness arguments are case insensitive. = Rationale = The idea of using the particular ByteString and ByteArray types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/commonjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion. == Structures == This proposal is not an object oriented variation on Perl, PHP, Python, or Ruby's pack, unpack, and calcsize with notions of inherent endianness, read/write head position, or intrinsic codec or charset information. The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data. Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/commonjs/msg/592442ba98c6c70e the list]). This goes against most mentioned [[../|prior art]]. == Encoding Methods == This proposal also does not provide separate member functions for any particular subset of the possible charsets, encodings, compression algorithms, or consistent hash digests that might operate on a byte string or array, for example "toBase64", "toMd5", or "toUtf8" are not specified. Instead, "toString" accepts IANA charset names and radix numbers for charsets and encodings. The intent is that implementations will opt to make this extensible by falling back to an "encodings" module and searching for modules by the same name and calling "encode" or "decode" exports on those modules if they exist. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list). This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation). == <nowiki>[[Get]]</nowiki> and <nowiki>[[Put]]</nowiki> == This proposal also reflects both group sentiment and a pragmatic point about properties. This isn't a decree that properties like "length" should be consistently used throughout the CommonJS APIs. However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified. (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/commonjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]). == Future Proofing == This proposal suggests that the specified data types should be exported by a "binary" module. The intent is that eventually ECMAScript will specify native types to replace these, and these new types would be hosted as "primordials", free variables available in all top-level scopes. Because these types are specified to be exported by the "binary" module, there is some ambiguity of whether "instanceof" relationships would be maintained when references are passed among global contexts. It would be valuable for these identities to be preserved. For module systems that share a common global scope, this would suggest that the binary types should be patched into some commonly shared object, like the global scope, only if they do not yet exist. That would permit the first, permissive context to construct the types, and all subsequent sandboxes to share them. Secure sandboxes would have to make other accomodations. == Memory Optimization == In contrast to Maciej Stachowiak's [https://mail.mozilla.org/pipermail/es-discuss/2009-November/010132.html proposal], there are no methods for explicitly managing the mutability of the underlying buffer. Since it is possible for implementations to explicitly use ownership and copy-on-write flags, it is desirable to keep the memory management beneath the surface of JavaScript. For example, with freezing semantics as proposed by Maciej, freezing a mutable byte array could produce an immutable byte string that usurps ownership of the original byte array's buffer, so there would be no need for allocation. However, this would render the original byte array unusable, and all persisting references to that array would be broken and we would have to define failure modes for that object. Alternately, the byte array and byte string could share the buffer. The byte string would be guaranteed to not modify the content of the buffer, and if the owner of the original byte array were to perform a modifying operation on the byte array, the implementation could at that time incur the cost of copying the buffer. Similar optimizations could be applied by all ByteString and ByteArray constructors and conversion functions. == Genericity == In accordance with Daniel Friesen's [[Binary/C]], a high priority in this proposal was duck typing. ; a generic way to get a value in the Content type of a ByteArray, ByteString, or String : <nowiki>[[Get]]</nowiki> ; a generic way to get the type of what is returned by <nowiki>[[Get]]</nowiki> for ByteArray, ByteString, and String (Number, ByteString, and String respectively): : Content ; a generic way to get a ByteString for the value at an offset for either ByteArray or ByteString : byteStringAt(offset) ByteString ; a generic way to get a ByteArray for the value at an offset for either ByteArray or ByteString : would have been wasteful to include since byte arrays are meant for assembling large byte buffers through copying data from other binary collections, not for allocation churn. ; a generic way to get a Number for the value at an offset for any ByteArray, ByteString, Array, or String : valueAt(offset) Number ; a generic way to get an object of length one in the same type that contains just the value at a given offset for any ByteArray, ByteString, Array, or String : slice(offset, offset + 1) The following methods and properties are interoperable among ByteArray, ByteString, Array, and String: * <nowiki>[[Get]]</nowiki> * indexOf * lastIndexOf * slice The following methods and properties are interoperable among ByteArray, ByteString, and String: * <nowiki>[[Get]]</nowiki> * Content * valueAt * join * split * splitRight * indexOf * lastIndexOf * slice The following methods and properties are interoperable between ByteArray and ByteString: * <nowiki>[[Get]]</nowiki> * Content * valueAt * byteStringAt * indexOf * lastIndexOf * slice * copy * range The following methods and properties are interoperable between ByteString and String: * <nowiki>[[Get]]</nowiki> * Content * valueAt * indexOf * lastIndexOf * slice * substr * substring The following methods are interoperable between ByteArray and Array: * <nowiki>[[Get]]</nowiki> * indexOf * lastIndexOf * slice * forEach * every * some * map == Idempotence == [[Binary/B]] had a "decodeToString" method and "toString" was required to be distinct, to avoid decoding and encoding hazards. However, in keeping with the existing Number.prototype.toString(radix), for subjective aesthetic reasons having worked with prototypes of both, and because it easier to remember which way encoding and decoding go with "toString", "toByteString", and "toByteArray" than with "encode" and "decode", this proposal eschews "decodeToString". This has the side effect of making the generic "toByteString" and "toString" methods idempotent for converting to and from a charset. For example, if you receive an object that may be a ByteString or a String, but if it is a String it will need to be converted to a ByteString with a given charset, you can simply call "toByteString" with that charset, even repeatedly. Likewise, if you receive a ByteString or a String and you need it to be a String, you can simply call "toString" with the desired charset, allowing a succession of adapters or decorators to make the conversion at any point along the way. == Miscelaneous == "ByteString" does not implement "toUpperCase" or "toLowerCase" since they are not meaningful without the context of a charset. Unlike the "Array", the "ByteArray" is not variadic so that its initial length constructor is not ambiguous with its copy constructor. The [[Binary/B]] proposal, at Ash Berlin's recommendation, had split methods on both ByteStrings and ByteArrays that accepted as their optional second argument, an object of options for both the number of delimiters to match, but whether to include the delimiter on the right side of each term, presumably including a terminal delimiter that would obviate an empty collection from being returned as the last value. This has been left as an exercise for a byte reader stream's "readLine(delimiter)" method, so that this proposal's split and splitRight methods may more closely resemble their cousins on existing Strings in JavaScript and other languages. The "join" methods on "ByteArray" and "ByteString" differ from what you would expect in JavaScript based on Array joins, in a way that will be familiar and probably upsetting coming from Python. The delimiter is the left side of the expression. This is because the Array joining method can not be practically extended to determine whether to return a String, ByteString, or ByteArray based on the types of all of the values it contains. It is far more practical to multi-plex the return type based on the type of the left hand side of the expression. The "Content" property begins with a capital letter to distinguish it as a factory method like the constructor function to which it always refers, albeit ByteString, ByteArray, or Number. To date, this remains a point of discussion. Daniel Friesen's proposal [[Binary/C]] uses the name "contentConstructor". == Errata == This proposal is a strict subset of [[Binary/D]] with a few exceptions: the Content type and return value of <nowiki>[[Get]]</nowiki> for ByteString has been changed to Number; ByteString and ByteArray are object types instead of anticipating future-compatibility with "bytestring" and "bytearray" types; and the Binary type has been reintroduced. Bit types, radix encoding (base8...base64), and consistency shims for existing primordial types have been removed and are possible candidates for extensions to future revisions of this specification. = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/commonjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] * [http://groups.google.com/group/commonjs/browse_thread/thread/98c51580a47e855e Binary D ready for review] * [http://groups.google.com/group/commonjs/browse_thread/thread/f609c72c9749e2c3 Binary/D Draft 2] 358 2897 2010-09-10T01:57:09Z Kriszyp 39 Redirect to asynchronous module definition {{Spec |status=proposal |implementations=Yabble,RequireJS }} == Format == The Transport/C proposal has moved to [http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition]. 359 2241 2010-03-13T04:21:07Z KrisKowal 6 Licensed [[Real Name::Kris Kowal| ]] * http://askawizard.blogspot.com * http://github.com/kriskowal Working on Narwhal, Chiron, and with ECMA I assign the MIT License to all of my contributions under http://wiki.commonjs.org 360 2756 2010-04-29T21:03:59Z Hannesw 10 # [[Encodings/A]] # [[Encodings/B]] # [[Encodings/C]] 361 2545 2010-03-31T14:16:41Z Aristid 46 {{Spec |status=proposal |implementations=Flusspferd }} For Streams, we need encodings support. There also should be a low-level API available for this. = Specification = == Encoding Names == The encoding names should be among those supported by ICONV, which seem to be a superset of http://www.iana.org/assignments/character-sets. The following encodings are required: * US-ASCII * UTF-8 * UTF-16 * ISO-8859-1 Encoding names <b>must</b> be case <b>insensitive</b> == API == OK, so probably this should be a module: <source> var enc = require('encodings') </source> === Simple methods === For convenience, there should be these easy methods for converting between encodings: ; string = enc.convertToString(sourceEncoding, byteStringOrArray) : Converts a ByteString or a ByteArray to a Javascript string. ; byteString = enc.convertFromString(targetEncoding, string) : Converts a Javascript string to a ByteString. ; byteString = enc.convert(sourceEncoding, targetEncoding, byteStringOrArray) : Converts a ByteString or a ByteArray to a ByteString. === Checking for available encodings === ; enc.supports(encodingName) : Checks if encodingName is supported and return true if so, false otherwise. ; enc.listEncodings([encodingCheckerFunction or regex]) : encodingCheckerFunction takes the encoding name as a parameter and returns true-ish if the encoding should be listed. Regexes should also be supported. If the parameter is missing, returns all supported encodings. === Class: Transcoder === There also should be a class enc.Transcoder for general transcoding conversion (between ByteStrings or ByteArrays). ; [Constructor] Transcoder(from, to) : Where from and to are the encoding names. ; [Constant] sourceCharset : String containing the (possibly normalised) source charset name. ; [Constant] destinationCharset : String containing the (possibly normalised) destination charset name. ; [Method] push(byteStringOrArray[, outputByteArray]) : Convert input from a ByteString or ByteArray. Those parts of byteStringOrArray that could not be converted (for multi-byte encodings) are stored in a buffer. If outputByteArray is passed, the results are ''appended'' to outputByteArray. : If outputByteArray was passed, returns outputByteArray, otherwise returns <u>the converted bytes as a ByteString</u>. : <u>The result will also contain bytes accumulated in prior calls to pushAccumulate.</u> ; <u>[Method] pushAccumulate(byteStringOrArray)</u> : <u>Convert input from a ByteString or ByteArray into an internal buffer that will be read out the next time push or close is called.</u> ; [Method] close([outputByteArray]) : Close the stream. Throws an exception if there was a conversion error (specifically, a partial multibyte character). : <u>Writes the remaining output bytes (including those that were accumulated in pushAccumulate) into the here given outputByteArray (appended) or a new ByteString. If outputByteArray is given, it is returned, otherwise the ByteString is returned.</u> : <u>Also adds initial shift state sequences if required by the encoding.</u> '''TODO''': Which exception to throw on error? = Usage examples = Example: <source> Transcoder = require('encodings').Transcoder transcoder = new Transcoder('iso-8859-1', 'utf-32') transcoder.pushAccumulate(input) // input is a ByteString output = transcoder.close() // and output is a ByteString too </source> Another example: <source> transcoder = new Transcoder('utf-32', 'utf-8') output = new ByteArray() while (input = readSomeByteFromSomewhere()) { transcoder.push(input, output) } transcoder.close(output) // output is the complete conversion of all the input chunks concatenated now </source> (See [[Encodings/OldClass]] for another API.) == Stateful encodings == Some encodings can carry state across many characters - state which has to be reset at the end of a conversion. This creates the need to ''always'' call transcoder.close(output) after converting. The simple methods take care of that already. An example of such an encoding would be [http://en.wikipedia.org/wiki/ISO/IEC_2022 ISO-2022-JP], a Japanese encoding. This encoding is compatible with ASCII as long as it is in the initial state. But there is an escape sequence (actually more than one: <tt>ESC ( J</tt>, <tt>ESC $ @</tt> and <tt>ESC $ B</tt>) to get into Kana/Kanji mode, and another escape sequence to get back into ASCII mode: <tt>ESC ( B</tt>. So a reader of ISO-2022-JP content assumes that, initially, the encoding is in ASCII mode, and as soon as it sees an escape sequence, switches into another mode. Therefore, in order to be able to concatenate files, ISO-2022-JP files should end with <tt>ESC ( B</tt> if they are in non-ASCII mode at the end. <source> // Te Su To - thanks to miwagawa katakana_string = "\u30c6\u30b9\u30c8", katakana_shift_jis = binary.ByteString([ 0x83,0x65, 0x83,0x58, 0x83,0x67 ]), // Shift to JIS X 0208-1983 iso2022_FROM_ascii = [ 0x1b,0x24,0x42 ], // Shift to ASCII iso2022_TO_ascii = [ 0x1b,0x28,0x42 ], katakana_iso2022 = binary.ByteString( iso2022_FROM_ascii.concat([ 0x25,0x46, 0x25,0x39, 0x25,0x48, ], iso2022_TO_ascii) ); </source> If you transcode as in the examples above, this should work. Flusspferd has some tests for these things in http://github.com/ruediger/flusspferd/blob/master/test/js/encodings.t.js = Implementation Recommendations = First of all, it is recommended to implement convertToString, convertFromString and convert with Transcoder. Secondly, you should make sure that initial shift state support is properly implemented. When you're using iconv, you need to call iconv(cd, 0, 0, &ob, &ol) in Transcoder.close(). An example of what an initial shift state is: In the Japanese ISO-2022-JP encoding, the default state are ASCII bytes. However, the state can be switched to Japanese with an escape sequence. To make sure that at the end of the text, the state is ASCII again, iconv will emit another escape sequence to switch back again. This is important if you want to concatenate ISO-2022-JP texts, and an implementation of Transcoder that doesn't properly emit these sequences is <b>broken</b>. = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/6365b2a54615a134 Proposal: Encodings API (independent from Streams)] * [http://groups.google.com/group/commonjs/browse_thread/thread/3faf4a067973a71a How to make Encodings] * [http://groups.google.com/group/commonjs/browse_thread/thread/f9fcf27e1dd4a8b1 Who's implementing the Encodings API?] = Other = [http://flusspferd.org Flusspferd]'s implementation is documented [http://flusspferd.org/docs/js/commonjs%20core/encodings.html here] and [http://flusspferd.org/docs/js/commonjs%20core/encodings/transcoder.html here]. 362 2019 2010-01-24T01:24:55Z KrisKowal 6 moved [[Encodings/OldClass]] to [[Encodings/A/OldClass]]:&#32;putting in the proposal name space (non-versioned, lettered) #REDIRECT [[Encodings/A/OldClass]] 363 2042 2010-01-25T18:03:43Z Aristid 46 /* Transcoding */ == Philosophy == There are already numerous proposals for Binary datatype out there (Binary/[A-E]). I personally find all of these too complex and cumbersome; aimed at ducktyping and multi-argument-type methods. The Binary/Lite proposal aims to provide a simplified data type which maintains the core functionality. There is only one object specified in this proposal: the <code>Binary</code> function. It is essentialy a (mutable) array of <code>Numbers</code>. However, when compared with native <code>Array</code>, this object offers these advantages: * automatic conversion to <code>Number</code> and masking by 0xFF, * flat structure, * built-in transcoding methods. == Specification == === Construction === The <code>Binary</code> object has only one constructor form. /** * @param {int} length Initial length of this binary */ var Binary = exports.Binary = function(length = 0) {}; === Correspondence with Array === There is a strong similarity with <code>Array</code>. Binary.prototype = []; This way, we automatically have all those iterative methods, such as <code>forEach</code>, <code>reduce</code> etc. On client side, this is achieved by var Binary = exports.Binary = Array; === Cooperation with other data types === To create <code>Binary</code> from other data types, we use factory methods. var b1 = Binary.fromArray([1, 2, 3]); var b2 = Binary.fromString("hello ondřej", "utf-8"); Converting back to standard types is very similar. Note that there are no monkey-patching efforts. var array = b1.toArray(); var string = b1.decodeToString(charset); The default "toString" is reserved for debugging purposes. Binary.prototype.toString = function() { return "[Binary " + this.length + "]"; } === Basic usage === The <code>length</code> property specifies the size. It is possible to resize the binary object by assigning to <code>length</code>. Newly created values are zero-filled. var b1 = Binary.fromArray([1, 2, 3]); var length = b1.length; /* 3 */ b1.length = 10; The '''[]''' operator is used to retrieve byte values (as <code>Number</code>s) as well as modify the binary object. One can freely modify non-existant index - in this case, the object is first resized accordingly. var b1 = Binary.fromArray([1, 2, 3]); b1[3] = 123; /* b1 == [1, 2, 3, 123] */ === Array methods === These methods return a <code>Number</code> and resize the buffer accordingly: * <code>pop</code> * <code>shift</code> These methods accept a variadic list of <code>Number</code>s and resize the buffer accordingly: * <code>push</code> * <code>unshift</code> These methods return a <code>Binary</code>: * <code>slice</code> * <code>splice</code> === Miscellaneous === /** * Appends contents of other variadic Binary instance(s) to the end of this one. */ Binary.prototype.extendRight = function() {}; /** * Appends contents of other variadic Binary instance(s) to the beginning of this one. */ Binary.prototype.extendLeft = function() {}; /** * Converts contents from one encoding to another */ Binary.prototype.transcode = function(fromCharset, toCharset) {}; /** * Returns a copy of this Binary */ Binary.prototype.clone = function() {}; == Place for improvements == === Naming === Current naming scheme does not anticipate the existency of an immutable binary data type. If we decide that an immutable binary is a must, I suggest picking one of these approaches: * leaving ''Binary'' as is, creating an ''ImmutableBinary'' type. The awkward name corresponds to the fact that in most situations, a mutable Binary is sufficient. * switching back to ByteString and ByteArray variants. I am still unsure what is the overall attitude regarding the number of Binary data types we really want. === Transcoding === As mentioned by [[User:MrN|MisterN]], everything related to transcoding might get separated into a different module. This clearly makes sense, as the set of tasks related to transcoding might get larger in the future. On the other hand, converting Strings to Binary has little sense without specifying a charset to be used. 364 2032 2010-01-25T12:53:56Z Aristid 46 reply It seems that iso-8859-1 (Latin-0) has become much less relevant than [http://en.wikipedia.org/wiki/ISO-8859-15 iso-8859-15] (Latin-9), notably due to use of the euro directly in documents instead of being used as a named entity. It would therefore make sense to either replace iso-8859-1 with it, or add it to the list. --Fgm :To the list of required encodings? I'm not sure how many encodings we should require. --[[User:MrN|MrN]] 12:53, 25 January 2010 (UTC) 365 2339 2010-03-13T20:09:41Z Dantman 1 moved [[User:MrN]] to [[User:Aristid]] In the list, I'm also known as [[Real Name::Aristid Breitkreuz]]. 366 2480 2010-03-19T10:41:55Z Ondras 57 This is [[Real Name::Ondřej Žára]]. 367 2048 2010-01-29T01:52:27Z IsaacSchlueter 52 <h1 id="jsgi_extension_proposal_evented_streaming_jsgi">JSGI Extension Proposal - Evented Streaming JSGI</h1> <h2 id="status_proposed">Status: Proposed</h2> <p>Extension name: <code>stream</code> <br> Extension version: <code>0.1</code> <br> Reference Implementation: http://github.com/isaacs/ejsgi</p> <h2 id="rationale">Rationale</h2> <p>Simplify the input, error, and response body objects to a single non-blocking data stream class.</p> <p>Support reading the input request and writing the response body without ever having to hold the entire body in memory.</p> <h2 id="changes_from_jsgi_03">Changes from JSGI 0.3</h2> <h3 id="specification_changes">Specification Changes</h3> <ul> <li>add <code>url</code> member to the request object, which is the requested URL exactly as it appears on the first line of the HTTP request.</li> <li><code>request.input</code> MUST be a Stream object.</li> <li><code>response.body</code> MUST be a Stream object.</li> <li><code>request.jsgi.error</code> MUST be a Stream object.</li> <li><code>request.jsgi.stream</code> MUST be a reference to the Stream implementation.</li> </ul> <h3 id="stream_objects">Stream Objects</h3> <p>Stream Objects are representations of a stream of data in an asynchronous evented paradigm.</p> <h4 id="methods">Methods</h4> <p>Stream Objects have the following methods:</p> <ul> <li><strong>write</strong> - Send data down the stream. If the stream is closed, then throw an Error. This must not actually perform the write until after the current scope of execution is completed. The order of written data MUST be consistent with the order in which <code>write</code> is called.</li> <li><strong>close</strong> - Close the stream. Once closed, no more data may be written to the Stream.</li> <li><strong>pause</strong> - Temporarily prevent the firing of <code>data</code> events. This is useful when a reader needs to throttle a stream of incoming data.</li> <li><strong>resume</strong> - Resume a paused thread, so that <code>data</code> events will begin firing again.</li> <li><strong>addListener</strong> - Attach an event handler to an event. The first argument is the event name, and the second is the callback.</li> </ul> <h4 id="events">Events</h4> <p>Stream Objects emit the following events</p> <ul> <li><strong>data</strong> - All the data that is passed through <code>write</code> eventually triggers a <code>data</code> event. The argument is the data that was written.</li> <li><strong>eof</strong> - Emitted when all data has been written, and the stream is closed.</li> <li><strong>drain</strong> - Emitted when the internal buffer empties.</li> <li><strong>pause</strong> - Emitted when the stream is paused with the <code>pause</code> method.</li> <li><strong>resume</strong> - Emitted when the stream is resumed with the <code>resume</code> method.</li> </ul> <h4 id="timing">Timing</h4> <p>Stream objects MUST implement some sort of &#8220;event queue&#8221; in order to defer callbacks until after the current execution context has exited. Specifically, the <code>data</code>, <code>eof</code>, and <code>drain</code> events MUST NOT be fired immediately after the corresponding calls to <code>write()</code>, <code>close()</code>, and <code>resume()</code>.</p> <h4 id="read_write">Read/Write</h4> <p>All streams SHOULD be both readable and writeable. This allows for middleware to step into the flow and filter the input or output to/from an app.</p> <h2 id="backward_compatibility">Backward Compatibility</h2> <p>For the purposes of this spec, &#8220;compliant&#8221; applications are applications that return a stream as the response body.</p> <p>However, non-streaming JSGI applications can easily be supported using a middleware adapter. See the <code>array-to-stream.js</code> and <code>string-to-stream.js</code> examples included in the reference implementation.</p> 368 2119 2010-02-19T09:24:04Z Mikewse 9 /* forEach+promise or streaming jsgi is... */ == Options for Asyncing up the response == <ol><li>forEach() that returns a promise which is resolved when it's done</li><li>response.body is a stream (and we'll talk about what that is, exactly)</li><li>Async responses don't belong in the spec. Just use threads.</li><li>Something else entirely</li></ol> Please add your name here, with your vote for 1, 2, 3, or 4. * isaacs 2 * hassox 2 * mikeal 2 * tlrobinson 1 * mikewse 2 == request.input --> request.body == Please add your name here with either "yes" or "no" for this change. * isaacs yes * mikeal yes * deanlandolt yes, please! * hassox yes * tlrobinson yes * mikewse yes == forEach+promise or streaming jsgi is... == <ol> <li>An extension</li> <li>A proposal for the next version of JSGI (0.4)</li> <li>Not something that we should bother with</li> </ol> Please add your name here with either 1, 2, or 3. * deanlandolt: 2 if it is incompatible with the widely-adopted bits of 0.3, 1 if it can be made compatible * mikewse: can "streaming is a layer below forEach/Promise-based JSGI" fit into 1? 369 2159 2010-03-12T13:44:06Z Kriszyp 39 <h1>JSGI Streaming Body Using forEach</h1> <h2 id="status_proposed">Status: Proposed</h2> <p> Reference Implementation: http://github.com/kriszyp/jsgi-node</p> <h2 id="rationale">Rationale</h2> <p>KISS - Make it as simple as possible to return a response.</p> <p>Read request input and write to the response body without buffering data without requiring extra effort on the part of the programmer.</p> <p>Consistency between synchronous and asynchronous streaming of the body with backwards compatibility with JSGI 0.3.</p> <p>Consistency with the API on how asynchronous actions are modeled, keeping in mind that in JSGI, response status and headers are asynchronously provided using promises.</p> <h2 id="changes_from_jsgi_03">Addition JSGI 0.3</h2> <ul> <li>add <code>url</code> member to the request object, which is the requested URL exactly as it appears on the first line of the HTTP request.</li> <li><code>request.body</code> MUST be a forEach-able Stream object.</li> <li><code>response.body</code> MUST be a forEach-able Stream object.</li> <li><code>request.jsgi.error</code> MUST be a forEach-able Stream object.</li> </ul> <h3 id="stream_objects">Stream Objects</h3> <p>forEach-able Stream Objects are representations of a stream of data.</p> <h4 id="methods">Methods</h4> <p>forEach-able Stream Objects have the following method:</p> <ul> <li><strong>forEach(write)</strong> - When the stream can be written to, this will be called. The first parameter, write, MUST be a function. The forEach function can call the write function to write strings to the stream. The stream will be closed when forEach returns with any value that does not have a then() function, or if it returns a then() function (a promise), then() should be called with a callback that can be called when the stream is finished. Each time the write callback is called, it may optionally also return a promise with a then() function if wishes to indicate that it has not yet completed handling processing the data. Once the data consumer is ready to continue receiving data, it call the callbacks to indicate that the forEach should continue. This allows for throttling of data. </li> </ul> <h4 id="methods">Properties</h4> <ul> <li><strong>charset</strong> - This property can be set to the desired charset to use for encoding or decoding strings.</li> </ul> <h4 id="examples">Examples</h4> Simple sync app: <pre> app = function(request){ return { status: 200, headers: {}, body: ["hello", "world"] } }; </pre> Streaming app, this could be sync or async, as along as "data" is a forEach-able source data structure: <pre> app = function(request){ return { status: 200, headers: {}, body: { forEach: function(write){ return data.forEach(function(item){ return serialize(item); }) } } } }; </pre> Reading input: <pre> app = function(request){ var file = new File("fileToSave"); var fileUpload = request.body.forEach(function(data){ file.write(data); }).then(file.close); return fileUpload.then(function(){ return { status: 200, headers: {}, body: ["file successfully uploaded"] }; }; }; </pre> Streaming app, where the source is an event emitter: <pre> app = function(request){ return { status: 200, headers: {}, body: { forEach: function(write){ var promise = new Promise(); someEventSource.addListener("data", function(data){ write(data); }); someEventSource.addListener("finished", function(data){ promise.resolve() }); return promise; } } } }; </pre> Middleware: <pre> MiddleWare = function(nextApp){ return function(request){ var response = nextApp(request); var inBody = response.body; response.body = { forEach: function(write){ return inBody.forEach(function(block){ return modify(block); }) } } return response; } }; </pre> 370 2064 2010-02-02T01:15:08Z Tlrobinson 2 Tom Robinson Projects: * [http://narwhaljs.org http://narwhaljs.org/] * [http://jackjs.org/ http://jackjs.org/] * [http://cappuccino.org/ http://cappuccino.org/] Websites: * [http://tlrobinson.net/ http://tlrobinson.net/] * [http://280north.com/ http://280north.com/] 371 2079 2010-02-03T18:19:44Z Mob 56 Clarify This proposal defines a ''''Stream'''' class suitable for use in async and sync programs. == Preamble == Stream objects represent flows of data that pass data elements between an endpoint known as a source or sink and a consumer or producer. Streams may be half or full duplex and may be stacked where intermediate streams are be used as filters or data mutators. Example endpoints are the File, Socket, and Http classes. The TextStream is an example of a filter stream. Streams may buffer the incoming data or not. Streams will issue events to registered listeners for topics of interest. Streams may be used in both synchronous and asynchronous programs. The Stream interface is an interface for concrete classes. Stream classes will typically augment the Stream class with extra user-facing methods and functionality. == Interface api == ;'''function Stream(stream: Stream = null)''' :Creates a new stream instance. If another stream is provided as an argument to the constructor, the new stream instance will be stacked upon it. Reads and writes from the stream will be relayed to the connected stream and so-on along the stream chain. ;'''function addListener(name: [String | Array], listener: Function): void''' :Add a listener for events on the stream. Events are issued for important state changes on the stream. Events are issued in both sync and async modes if listeners are registered. :''name'' Name can be a string event name or it can be an array of event names. :''listener'' Callback function to be invoked when the event is emitted. ;'''function get async(): Boolean''' :Test if the stream is operating in async mode. In async mode, read, write and close methods will not block. :''Returns'' True if the stream is in async mode, otherwise false. ;'''function set async(enable: Boolean): void''' :Set the streams operating mode. Used to put the stream into async or sync mode. :''enable'' Set to true to put the stream into async mode. Set to false to put the stream into sync mode ;'''function close(): void''' :Close the stream. :''Events'' The ''close'' event is issued when closing the stream. ;'''function read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number''' :Read data from the stream. If data is available, the call will return immediately with data. If no data is available and the stream is in sync mode, the call will block until data is available. If no data is available and the stream is in async mode, the call will not block and will return immediately. A "readable" event will be issued if data becomes available for reading. :''buffer'' Destination byte array for read data. :''offset'' Integer offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer. :''count'' Integer count of the number of bytes to read. Read up to this number of bytes. If -1, read as much as the buffer will hold up. If the stream is of fixed and known length (such as a file) and the buffer is of sufficient size or is growable, read the entire stream. :''Returns'' an integer count of the bytes actually read. Returns null on eof. :''Events'' The ''readable'' event may be listened to be notified when new read data becomes available. ;'''function removeListener(name: [String | Array], listener: Function): void :Remoe a listener from the stream. :''name'' Name can be a string event name or it can be an array of event names. :''listener'' Callback function specified when the listener was previously added. ;'''function write(...data): Number :Write data to the stream. If the stream can accept all the write data, the call returns immediately with the number of elements written. If writing more data than the stream can absorb in sync mode, the call will block until the data is written. If writing more data than the stream can absorb in async mode, the call will not block and will return immediately. A "writable" event will be issued when all the data has been written. :''data'' Variable number of data objects to write. It is stream specific how the written data will be converted or encoded. :''Returns'' an integer count of the bytes actually written. Returns null on a write error. :''Events'' The ''writable'' event is issued when the stream becomes empty and it is ready to be written to. 372 2759 2010-05-02T02:09:53Z KrisKowal 6 related discussions '''STATUS: PROPOSAL''' * [http://wiki.commonjs.org/index.php?title=Events/A&oldid=2082 Draft 1] * [http://wiki.commonjs.org/index.php?title=Events/A&oldid=2088 Draft 2] * Draft 3 == Proposal == === NameEmitter === ; NameEmitter() NameEmitter : creates a name emitter with an empty internal emitter memo. ; observe(name String, observer Function) Emitter : gets or creates an internal emitter with the given name. Calls and returns the result of the "observe" method on the internal emitter, passing the given observer function. ; emit(name String, ...args) Undefined : gets or creates an internal emitter with the given name. Applies and returns the result of the "emit" method on the internal emitter, passing the rest of the arguments. ; emitter(name String) Emitter : gets or creates an internal emitter with the given name. === Emitter === ; Emitter(defaultAction_opt Function, dismiss_opt Function) Emitter : creates a emitter with an optional default action and an empty observer array. ; observe(observer Function) Emitter : creates a new Emitter from the given action and a dismissal function, and pushes that emitter onto an internal array of observers. The dismissal function, when called, removes the child emitter from the parent emitter's array of observers. ; emit(...args) Undefined : uses "this" as an "Event" instance, creating a new one if necessary, and iteratively emits the event as the this object and the given arguments to each of its own observers until the event says it should no longer propagate, and then calls and returns the result of the default action if the event says it should still default. ; dismiss() Undefined : if the emitter was constructed with a dismissal function, calls that function. === Event === ; Event() : creates a new Event that should still propagate and cause the corresponding emitter's default action to occur ; stopPropagation() Undefined : prevents the event from propagating to further observers ; cancelDefault() Undefined : cancels the corresponding emitter's default action ; stop() Undefined : stops propagation and cancels the default action ; propagating() Boolean : returns whether the event should continue propagating to further observers ; defaulting() Boolean : returns whether the default action of the corresponding emitter should be called == Examples == === Dismissing an Observer === var nameEmitter = new NameEmitter(); var emitter = nameEmitter.observe("foo", function () { }); emitter.dismiss(); === Observing Before Another Observer === var parent = nameEmitter.observe("foo", function () {print("parent")}); var child = parent.observe(function () {print("child")}); var beforeChild = child.observe(function () {print("beforeChild");}); nameEmitter.emit("foo"); beforeChild child parent === Observing After an Observer === var parent = new Emitter(function () {print("parent")}); var child = parent.observe(function () {print("child");}); var afterChild = parent.observe(function () {print("afterChild")}); parent.emit(); child afterChild parent === Emit Arguments === var emitter = new Emitter(function (a, b, c) { print(a, b, c); }); emitter.emit(1, 2, 3); 1 2 3 == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/9bd7b457d0bdc85f/bfccd9961dea4335 Events A] * [http://groups.google.com/group/commonjs/browse_thread/thread/70c0d276dc5fa267/6118058542d95d78 Events A Continued] 373 2083 2010-02-04T00:37:49Z KrisKowal 6 even more brain-dead events proposal '''STATUS: PROPOSAL''' == Proposal == === Emitter === An emitter internally contains a memo of names to signal objects, which are created on-demand internally. ; observe(name String, callback Function) Undefined : gets the internal signal or creates and sets the internal signal for the given name and calls the observe method of that signal with the given callback. ; emit(name String, ...args) Undefined : gets the internal signal or creates and sets the internal signal for the given name and applies the emit method of that signal with the given arguments. === Signal === ; Signal() Signal : creates a signal with an empty observer array. ; observe(callback Function) Undefined : pushes the callback on the internal observer array. ; emit(...args) Undefined : applies each internal callback in order with the given arguments. 374 2093 2010-02-05T13:38:32Z Fbraem 68 Franky Braem is the project leader and developer of the GLUEscript project: http://gluescript.sf.net Follow GLUEscript on Twitter: http://twitter.com/gluescript My LinkedIn profile: http://be.linkedin.com/in/frankybraem 375 2096 2010-02-07T13:14:16Z Zimbatm 72 /* NameEmitter */ Signal -> Emitter '''STATUS: PROPOSAL''' Based on [[Events/A]]: * without event objects, so stopping propagation or default actions is not possible * renaming Signal to Emitter and Emitter to NameEmitter * addition of emitter method to NameEmitter == Proposal == === Emitter === ; Emitter(defaultAction_opt Function, dismiss_opt Function) : creates an emitter with an optional default action and an empty observer array. ; observe(observer Function) Emitter : creates a new Emitter from the given action and a dismissal function, and pushes that emitter onto an internal array of observers. The dismissal function, when called, removes the child emitter from the parent emitter's array of observers. ; emit(...args) Undefined : calls each observer's emit method with the given arguments, and then calls and returns the result of the default action with the given arguments. ; dismiss() Undefined : if the emitter was constructed with a dismissal function, calls that function. Otherwise, does nothing. === NameEmitter === ; observe(name String, observer Function) Emitter : gets or creates an internal emitter with the given name. Calls and returns the result of the "observe" method on the internal emitter, passing the given observer function. ; emit(name String, ...args) Undefined : gets or creates an internal emitter with the given name. Applies and returns the result of the "emit" method on the internal emitter, passing the rest of the arguments. ; emitter(name String) Emitter : gets or creates an internal emitter with the given name and returns that emitter object. 376 2097 2010-02-07T17:46:10Z KrisKowal 6 DOM2-like API '''STATUS: PROPOSAL''' This proposal is a strict subset of the DOM2 events API [http://www.w3.org/TR/DOM-Level-2-Events/idl-definitions.html]. == Proposal == ; createEvent(type String) Undefined : constructs and returns a new Event with the given type === EventTarget === ; addEventListener(type String, listener Function) : pushes an event listener onto the internal array of listener functions for the given event type. ; removeEventListener(type String, listener Function) : removes the given listener function from the internal array of listener functions for the given type. ; dispatchEvent(event Event) Boolean throws EventException : sets the event's target to this object and calls each listener function in order with the given event as an argument until the event's stopPropagation method is called. === Event === No constructor; use <code>createEvent</code>. ; initEvent() : initializes the event. Must be called before dispatching. ; type String : the type name of the event, as set by <code>createEvent</code> ; target EventTarget : the target of the event, as set by <code>dispatchEvent</code> ; stopPropagation() Undefined : prevents an event from being propagated to further listeners. ; preventDefault() Undefined : this specification does not provide a mechanism for defining default actions for event types, so this is a no-op unless implementations of dispatchEvent for particular objects opt to define the behavior for particular event types on particular targets. === EventException === ; code Number : implementation defined. == Examples == === Removing a Listener === var listener = function (event) {}; var target = new EventTarget(); target.addEventListener("foo", listener); target.removeEventListener("foo", listener); === Listening Before Another Listener === Not supported. === Listening After another Listener === var target = new EventTarget(); target.addEventListener("foo", function (event) {print("before")}); target.addEventListener("foo", function (event) {print("after")}); var event = createEvent(); event.initEvent(); target.dispatch(event) before after === Emit Arguments === Not supported. 377 2099 2010-02-09T14:44:13Z Darren 73 Is the Reactor module needed? Given the limitations of the browser event loop and the overlap with the worker module, is the Reactor module genuinely required? What benefits does it offer that aren't already covered? 378 2228 2010-03-13T00:45:33Z Dantman 1 Adding real name semantic. [[Real Name::Rüdiger Sonderfeld| ]] Hi, I'm a member of the [http://flusspferd.org Flusspferd Team]. 379 2111 2010-02-18T21:28:23Z Ruediger 75 Created page with 'This API should provide a way to start and communicate with subprocesses. == Prior Art == * [http://github.com/280north/narwhal/blob/master/engines/rhino/lib/os-engine.js#L69 na…' This API should provide a way to start and communicate with subprocesses. == Prior Art == * [http://github.com/280north/narwhal/blob/master/engines/rhino/lib/os-engine.js#L69 narwhal's os-engine] * [http://flusspferd.org/docs/js/bundled%20modules/subprocess.html Flusspferd's subprocess module] === Other Languages === * popen(3) in POSIX.1-2001 * [http://docs.python.org/library/subprocess.html Subprocess module in Python] 380 2123 2010-02-21T02:23:38Z KrisKowal 6 Noted implementations '''STATUS: PROPOSAL''' by Kris Zyp = Proposal = A promise represents the eventual value returned from the single completion of an operation. A promise may be in one of the three states, unfulfilled, fulfilled, and failed. The promise may only move from unfulfilled to fulfilled, or unfulfilled to failed. Once a promise is fulfilled or failed, the promise's value MUST not be changed, just as a values in JavaScript, primitives and object identities, can not change (although objects themselves may always be mutable even if there identity isn't). The immutable characteristic of promises are important for avoiding side-effects from listeners that can create unanticipated changes in behavior and allows promises to be passed to other functions without affecting the caller, in same way that primitives can be passed to functions without any concern that the caller's variable will be modified by the callee. This API does not define how promises are created, but only defines the necessary interface that a promise must provide for promise consumers to interact with it. Implementors are free to define how promises are generated. Some promises may be provide their own functions to fulfill the promise, and other promises may be fulfilled by mechanisms that are not visible to the promise consumer. See the [Promise Manager] API for a proposal for useful convenience functions. Promises itself may include other additional convenience methods as well. For example, one could implement Dojo's Deferred functions on promises such as addCallback and addBoth. A promise is defined as an object that has a function as the value for the property 'then': ; then(fulfilledHandler, errorHandler, progressHandler) : Adds a fulfilledHandler, errorHandler, and progressHandler to be called for completion of a promise. The fulfilledHandler is called when the promise is fulfilled. The errorHandler is called when a promise fails. The progressHandler is called for progress events. All arguments are optional and non-function values are ignored. The progressHandler is not only an optional argument, but progress events are purely optional. Promise implementors are not required to ever call a progressHandler (the progressHandler may be ignored), this parameter exists so that implementors may call it if they have progress events to report. This function should return a new promise that is fulfilled when the given fulfilledHandler or errorHandler callback is finished. This allows promise operations to be chained together. The value returned from the callback handler is the fulfillment value for the returned promise. If the callback throws an error, the returned promise will be moved to failed state. An example of using a CommonJS compliant promise: >asyncComputeTheAnswerToEverything(). then(addTwo). then(printResult, onError); 44 An interactive-promise is an extended promise that supports the following additional functions: ; get(propertyName) : Requests the given property from the target of this promise. Returns a promise to provide the value of the stated property from this promise's target. ; call(functionName, arg1, arg2, ...) : Request to call the given method/function on the target of this promise. Returns a promise to provide the return value of the requested function call. = Open Issues = Should calls to the callback handlers be put on the event queue or executed immediately? - Currently unspecified, and I don't know for sure what is best. = Implementations = * http://github.com/kriszyp/node-promise Promises for NodeJS * http://github.com/280north/narwhal/blob/master/lib/promise.js Promises for Narwhal * http://github.com/280north/narwhal/blob/master/lib/events.js Experimental Promises on Emitters = Related Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/e93f73ef97e88439/9cdb490abb8edfa6 Promise API Proposal] 381 2751 2010-04-28T20:45:36Z KrisKowal 6 Removed old general requirements. {{Spec |status=proposal |draft=3 |drafts=1:2128, 2:2403 }} This proposal, based on [[Binary/E]] and [[Binary/F/Wes]], defines a single, mutable, fixed-length, numeric byte storage type. = Specification = The "common/buffer" module exports a "Buffer" type that meets the following criteria. A Buffer is a mutable, fixed-length, representation of a C unsigned char (byte) array. == Constructor == # A Buffer function must exist. # Calling and constructing a Buffer both return a new Buffer instance. # Buffers are instances of Buffer and Object. # The type of a Buffer is "object". # Any call or construction of Buffer that does not have a Number, Buffer, Array, or String as its first argument throws a TypeError. ; Buffer(length Number, Number(fill_opt)) # New Buffer of the given length, with the given fill number at all offsets. # The default filler is 0. ; Buffer(source Buffer, Number(start_opt), Number(stop_opt), Boolean(copy_opt)) # New Buffer that is either a copy or a view of the allocation as the given buffer, from "start" to "stop". # "start" is 0 if undefined or omitted. # "stop" is the other buffer's length if undefined or omitted. # "start" and "stop" may both be negative numbers, in which case they correspond to offsets counting from the length of the buffer. # "copy" is true if undefined or omitted # When true, "copy" indicates that the buffer must have its own copy of the allocation. # When false, "copy" indicates that the buffer must share its allocation with the given buffer. ; Buffer(source Array, Number(start_opt), Number(stop_opt)) # New Buffer that contains the respective values from the given array, from "start" to "stop". # "start" is 0 if undefined or omitted. # "stop" is the array's "length" if undefined or omitted. # The "length" of the new buffer is exactly the length from "start" to "stop". # "start" and "stop" may both be negative numbers, in which case they correspond to offsets counting from the length of the array. ; Buffer(string String, String(charset)) # Create a buffer from a string, the result being encoded with "charset". == Prototype Properties == ; toString() String # Returns a debug representation like "<tt>[Buffer 10]</tt>", where 10 is the length this Buffer. # This signature of "toString" applies if the "arguments.length" is 0. ; toString(String(charset), Number(start_opt), Number(stop_opt)) String # Decodes this between "start" and "stop" according to the given character set and returns the String from the corresponding unicode points. # "start" is 0 if undefined or omitted. # "stop" is the length of this buffer if undefined or omitted. # "start" and "stop" may be negative numbers, in which case they correspond to an offset counting from this buffer's length. # Must throw a RangeError if the buffer is malformed, undefined, out of range, or incomplete for the given character set. # "charset" must be one of "UTF-8", "UTF-16", "ISO-8859-1", "ASCII", "BINARY". Any other "charset" throws a RangeError. ## "ASCII" must properly transcode all 7-bit ASCII code points.. ## ''Note: "ASCII" is not required to properly transcode any code points outside its seven bit domain. "ASCII" may be an alias of "UTF-8" or "ISO-8859-1". For highest performance, "ASCII" may opt to ignore bits outside its domain.'' ## "BINARY" must properly transcode all 8-bit ISO-8859-1 code points. ## ''Note: "BINARY" is not required to properly transcode any code points outside its eight bit domain. "BINARY" may be an alias of "ISO-8859-1". For highest performance, "BINARY" may opt to ignore bits outside its domain.'' # This signature of "toString" applies if the "arguments.length" is not 0. ; toSource() String # Returns "<tt>require("binary").Buffer([])</tt>" for a null buffer or "<tt>require("binary").Buffer([0, 1, 2])</tt>" for a buffer of length 3 with bytes 0, 1, and 2. ; range(Number(start_opt), Number(stop_opt)) Buffer # Returns a Buffer that views the given range of the same allocated byte buffer. # "start" is 0 if undefined or omitted. # "stop" is the length of this buffer if undefined or omitted. # "start" and "stop" may be negative numbers, in which case they correspond to an offset counting from this buffer's length. # The length of "range" is 2. ; slice(Number(start_opt), Number(stop_opt)) Buffer # Returns a Buffer with a new internal allocation, containing a copy of this buffer from "start" to "stop" offsets. # "start" is 0 if undefined or omitted. # "stop" is this buffer's length if undefined or omitted. # "start" and "stop" may be negative numbers, in which case they correspond to an offset counting from this buffer's length. ; copy(target, Number(targetStart_opt), Number(start_opt)), Number(stop_opt)) Buffer # Copies the Number values of each byte from this between "start" and "stop" to a "target" Buffer or Array at the "targetStart" offset. # "stop" is the length of this if undefined or omitted. # "targetStart", "start", and "stop" are internally coerced to Numbers with the Number constructor. # "targetStart" may be negative, in which case it corresponds to an offset counting from the length of the target. # "start" and "stop" may be negative, in which case they correspond to an offset counting from this buffer's length. # Throws a TypeError if the target is not a Buffer or Array. # Returns this. ; copyFrom(source, Number(sourceStart_opt), Number(start_opt), Number(stop_opt)) Buffer # Copies the Number values of each byte from a given Buffer or Array into this from "start" to "stop" from the given "sourceStart" offset. # "start" is 0 if undefined or omitted. # "stop" is the length of this buffer if undefined or omitted. # "sourceStart" may be negative, in which case it corresponds to an offset counting from this buffer's length. # "start" and "stop" may be negative, in which case they correspond to offsets counting from the length of the source. # "sourceStart", "start", and "stop" are internally coerced to Numbers with the Number constructor. # If the source is an Array, all values of that array are coerced to Numbers and masked with 0xFF. # Throws a TypeError if the target is not a Buffer or Array. # Returns this. ; read(String(charset), state Object, Number(start_opt), Number(stop_opt)) String # Decodes as many complete and well formed character codes as possible between "start" and "stop" to a String from the given character set. # "charset" must be one of "UTF-8", "UTF-16", "ISO-8859-1", "ASCII", "BINARY". Any other "charset" throws a RangeError. # Assumes that the given byte range begins at the beginning of a code point. # Stops decoding after the last complete code point byte sequence. # Returns the decoded String. # Sets the "bytes" property of the "state" object to the number of bytes transcoded. # Sets the "characters" property of the "state" object to the number of characters transcoded. # Sets the "error" property of the "state" object to "malformed" if reading stops at the beginning of a malformed byte sequence. # The actual stop offset must be either equal to "stop" or at the beginning of the first incomplete code point byte sequence. ; write(source String, String(charset), state Object, Number(start_opt), Number(stop_opt)) Number # Encodes as much as possible of a String in a given character set into this buffer from "source" to "stop", using the source string, and returns the actual stop index of the source string. # "charset" must be one of "UTF-8", "UTF-16", "ISO-8859-1", "ASCII", "BINARY". Any other "charset" throws a RangeError. # "start" is 0 if undefined or omitted and measures bytes. # "stop" is this buffer's length if undefined or omitted, measured in bytes. # "start" and "stop" may be negative, in which case they correspond to offsets counting from the length of the source. # Sets the "characters" property of the "state" object to the number of characters encoded. # Sets the "bytes" property of the "state" object to the number of bytes written. # Returns the number of bytes written. ; fill(Number(value), Number(start_opt), Number(stop_opt)) Buffer # Fills all of this buffer's bytes with the given value as a Number from the "start" offset to the "stop" offset. # "start" is 0 if undefined or omitted. # "stop" is the length of this buffer if undefined or omitted. # "start" and "stop" may be negative, in which case they correspond to offsets counting from the length of this buffer. # "value" is 0 if undefined or omitted. # "value" is coerced to Number and masked with 0xFF. # Returns this. ; Content # an alias of Number, indicating that Number is the type of what <nowiki>[[Get]]</nowiki> returns. == Internal Properties == ; <nowiki>[[Get]]</nowiki> Number # Returns the Number value of a the byte at the given offset. ; <nowiki>[[Put]]</nowiki> Number # Sets the byte value at the given offset. # Throws a RangeError if the index is beyond the current bounds of the buffer. # Implicitly coerces the value to a Number and masks it with 0xFF. == Instance Properties == ; length # The length in bytes. # Not <nowiki>[[Configurable]]</nowiki>, not <nowiki>[[Enumerable]]</nowiki>. <nowiki>[[ReadOnly]]</nowiki>. == Notation == # The notation <nowiki>functionName(argument Type)</nowiki> indicates that the given behavior only occurs when the argument pattern matches the given "Type". # If the <nowiki>functionName(argument Type)</nowiki> is mentioned for an argument and none of the given forms match the types of the argument, the function must throw a TypeError. # The notation <nowiki>functionName(argument_opt)</nowiki> indicates that the argument may be undefined or omitted. # The distinction between an omitted or undefined argument is only detectable by checking the <code>arguments.length</code> # The notation <nowiki>function(Type(argument))</nowiki> implies that any type matches the argument and that it must be internally coerced to the "Type". # Extra arguments are ignored. == General Requirements == # All of the properties specified on prototypes are not <nowiki>[[Enumerable]]</nowiki> on instances. # All operations that copy values to a byte in the byte buffer implicitly coerce the value to a Number and bit mask such values with 0xFF. = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal] * [http://groups.google.com/group/commonjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method] * [http://groups.google.com/group/commonjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes] * [http://groups.google.com/group/commonjs/browse_thread/thread/98c51580a47e855e Binary D ready for review] * [http://groups.google.com/group/commonjs/browse_thread/thread/f609c72c9749e2c3 Binary/D Draft 2] 382 2138 2010-03-04T09:03:20Z KrisKowal 6 Replaced content with 'Redacted SPAM.' Redacted SPAM. 383 2139 2010-03-06T10:01:57Z KrisKowal 6 Created page with 'The following is a proposal to revise [[Binary/F]] by Wes Garland for the handling of transcoding. = Design Notes = * The basic idea is that the binary API needs ** fast conve…' The following is a proposal to revise [[Binary/F]] by Wes Garland for the handling of transcoding. = Design Notes = * The basic idea is that the binary API needs ** fast conversion between Unicode buffers and Strings, without forcing intermediary object allocation ** Simple line-oriented character set encoding/decoding (iconv charsets) ** More complicated charset work (non-Unicode byte streams) should be pushed into Encodings API * Observations: ** All Unicode encodings sets can represent 100% of Unicode ** It is possible to transcode "bad" Unicode from one encoding to another ** Correcly transcoding between UTF-8, -16 and -32 can be implemented by an average programmer without difficulty or the need for libiconv ** All Unicode encodings "know" how many code points are required to represent an entire character by looking at only the first code point. This makes handling truncated sequences possible. * The reason I have added the optional Object o to some function signatures is to allow multiple out parameters without incurring new object construction overhead. * The way JavaScript Strings are treated in this specification fragment makes it possible and reasonable for implementations that have underlying UTF-8 Strings (like v8) to implement utf8-buffer -> String without any actual conversion. The Unicode character sets, for the purposes of this specification are: * UTF-8 * UTF-16 * UTF-32 UCS-4 will be accepted as an alias for UTF-32. UCS-2 and UTF-7 are not supported by the "Unicode" functions, although may be recognized as non-special character sets. In this specification, Strings will be considered to be UTF-16, encoded with the native byte order, with no leading BOM. This is equivalent to the iconv encoding UTF-16BE on Big-Endian machines and UTF-16LE on Little Endian machines. This consideration does not reflect actual implementation detail in the underlying engine, but rather the view offered to script. For performance reasons, this specification does not require implementations to perform transcoding validation when converting between Unicode character sets; instead, it is acceptable to transcode invalid code points from one Unicode encoding to another. Implementations are, however, encouraged to provide a method for performing transcoding validation for at least debugging builds of the underlying platform. == Definitions == ; Encode: to transform a String to a byte-oriented buffer ; Decode: to transform a byte-oriented buffer into a String ; Transcode: to transform one byte-oriented buffer into another == Constructor Methods == ; Object Buffer(String string, String charset, [Number length]) * creates and returns a new Object having a buffer of length bytes. If length is unspecified, the buffer will be exactly big enough to hold the encoded data * string is encoded to the character set identified by charset in the new buffer * throws an Error if encode fails, even if failure is due to under-sized buffer * if buffer is undersized and charset is a Unicode character set, the Error object will be augmented with a "commonjs.binary.encode_buffer_underrun" property indicating how many more bytes would have been required to succeed * if buffer is undersized and charset is not a Unicode character set (but is a valid iconv character set), the Error object will be augmented with a "commonjs.binary.encode_buffer_underrun" property having an undefined value == Static Methods == ; Object unicodeTranscode({Object buffer, [String charset, [Number offset, [Number length]]]} target, {Object buffer, [String charset, [Number offset, [Number length]]]} source, [Object o]) * Copies from source's buffer to target's buffer, transcoding from one Unicode character set to another, returning an object o * The default values for charset, offset, and length are "UTF-8", 0, and buffer.length for both source and target * Transcode behaviour is unspecified if source === target and the ranges [source.offset...source.offset + length] and [target.offset...target.offset + length] overlap * Transcode input is source.buffer[offset] through source.buffer[offset+length]; only entire characters are transcoded; a trailing partial character is not an error * o.encoded holds the number of bytes from source.buffer which were transcoded by this operation * o.used holds the number of bytes written into the target.buffer by this operation * transcoding errors will throw an exception, with the Error object augmented with a "commonjs.binary.transcode_error_offset" property containing the position in the source buffer which held the leading byte of the unencodeable character * The contents of o.encoded and o.used are unaffected if this function throws an exception * No properties other than o.encoded and o.used will be affected by this method == Instance Methods == ; String toString([String charset, [Number offset, [Number length]]]) * decodes this buffer, starting at byte offset for length bytes, as though this buffer was encoded with the character set identified by charset, returning a new String * The default values for charset, offset, and length are "UTF-8", 0, and this.length respectively. * This routine operates only on whole strings; truncated Unicode characters are to be treated as transcoding errors * A transcoding error will throw an exception, with the Error object augmented with a "commonjs.binary.transcode_error_offset" property * If charset identifies a Unicode character set, Error["commonjs.binary.transcode_error_offset"] will contain the number of bytes between the first byte to be decoded and the leading byte of the encoded character which could not be decoded. For example, a buffer containing a three-byte UTF-8 sequence with a corrupted third byte would set Error["commonjs.binary.transcode_error_offset"] to 0. * If charset does not identify a Unicode character set, Error["commonjs.binary.transcode_error_offset"] will have an undefined value. ; String unicodeToString([String charset, [Number offset, [Number length, [Object o]]]]) * decodes this buffer, starting at byte offset for length bytes, as though this buffer was encoded with the character set identified by charset, returning a new String * The default values for charset, offset, and length are "UTF-8", 0, and this.length respectively. * Specifying a non-Unicode character set name in charset will cause this function to throw an Error * Only entire characters are decoded - a trailing partial character is not an error * o.encoded holds the number of bytes from this buffer which were decoded by this operation * Decoding error will throw an exception, with the Error object augmented with a "commonjs.binary.transcode_error_offset" property containing the position in this buffer which held the leading byte of the unencodeable character * The contents of o.encoded is unaffected if this function throws an exception * No properties other than o.encoded will be affected by this method ; Object unicodeFromString(String string, [String charset, [Number offset, [Number length, [Object o]]]]) * encodes this buffer, starting at byte offset for at most length bytes, encoding string to the character set identified by charset, returning the object o * The default values for charset, offset, length, and o are "UTF-8", 0, this.length, and {} respectively * Specifying a non-Unicode character set in charset will cause this function to throw an Error * o.encoded holds the number of characters encoded from String * o.used holds the number of bytes written into this buffer by this operation * Only complete characters will be decoded: a string whose last position contains the first half of a surrogate pair will have o.encoded === string.length - 1. This is not an error condition. * transcoding error will throw an exception, with the Error object augmented with a "commonjs.binary.transcode_error_offset" property containing the position in string which held the unencodeable character * The contents of o.encoded and o.used are unaffected if this function throws an exception * No properties other than o.encoded and o.used will be affected by this method 384 2405 2010-03-15T19:13:31Z Mvalente 14 * Proposal A http://wiki.commonjs.org/images/b/bc/Wiki.png Daniel Friesen * Proposal B http://commonjs.org/images/logo.png Kevin Dangoor * Proposal C http://brevityos.org/common-js-logo.html Alexander Teinum * Proposal D http://www.users.abo.fi/kherler/commonjs/logo.png Karl Herler * Proposal E http://wiki.commonjs.org/wiki/File:Commonjs-zach.png Zach Carter * Proposal F http://deanlandolt.com/cjs-logo.svg Dean Landolt * Proposal G http://dl.dropbox.com/u/1688099/commonjs.png [png] http://dl.dropbox.com/u/1688099/commonjs.svg [svg] * Proposal H http://wiki.commonjs.org/wiki/File:Logos_Common_JS.jpg Mario Valente - 1st and 2ns with a rhino. Could be a monkey. Or both :-)... 3rd one based on a stylized coffee bean * Proposal I http://wiki.commonjs.org/wiki/File:AP_CommonJS.jpg Mario Valente - Based on a stylized coffee cup * Proposal J http://wiki.commonjs.org/wiki/File:Common_JS_2leva.jpg Mario Valente - First couple based on the hedgehog/Array concept. 2nd one based on a bee for the "working community" concept. 4th one is just a plain "community" symbol. * Proposal K http://www.page.ca/~wes/coffee-cjs.jpg Mario Valente 99.999% Wes Garland 0.001% - Variant on I with coffee ring forming letter C so that badge says CJS * Proposal L http://wiki.commonjs.org/wiki/File:AP_CommonJS_2.jpg Proposal K, with designer finishing 385 2151 2010-03-10T15:38:37Z ZachCarter 23 386 2155 2010-03-12T13:23:02Z Mvalente 14 CommonJS logo proposals 1st and 2nd one with rhino. Could be a monkey... Or both :-) 3rd one is based on a stylized coffee bean CommonJS logo proposals 1st and 2nd one with rhino. Could be a monkey... Or both :-) 3rd one is based on a stylized coffee bean 387 2156 2010-03-12T13:24:06Z Mvalente 14 CommonJS logo proposal. Based on a stylized coffee cup stain. CommonJS logo proposal. Based on a stylized coffee cup stain. 388 2160 2010-03-12T18:21:03Z Mvalente 14 Another bunch of proposals for the CommonJS logo. The first two are based on the "Hedgehog" idea (a String of Hedgehogs). The 3rd one uses a "bee" (for the working community effect). The 4th one is just a plain "community" symbol. Another bunch of proposals for the CommonJS logo. The first two are based on the "Hedgehog" idea (a String of Hedgehogs). The 3rd one uses a "bee" (for the working community effect). The 4th one is just a plain "community" symbol. 389 2386 2010-03-15T12:03:31Z Dantman 1 {{Implementation |name=Narwhal |url=http://github.com/tlrobinson/narwhal |engines=Rhino, v8, JSC |authors=Tlrobinson, KrisKowal }} 390 2473 2010-03-19T08:55:20Z Dantman 1 ;Name: [[Name::{{{name|}}}]] ;URL: [[URL::{{{url|}}}]] ;Engine(s): {{#arraymap:{{{engines|}}}|,|!|[[Engine::!]]}} ;Author(s): <includeonly>{{#arraymap:{{{authors|}}}|,|!|[[Author::User:!|{{author name|!}}]]}}</includeonly> ;Implementations {{#ask: [[Implementation of::+]] [[Implemented by::{{FULLPAGENAME}}]] | mainlabel=- | ?Implementation of= | ?Implementation state= | format=ul }} {{#declare:Description=description}}{{{description|}}} <includeonly>[[Category:Implementations|{{{name|}}}]]</includeonly> 391 2472 2010-03-19T08:54:39Z Dantman 1 [[CommonJS]] [[implementations]]. See [[Special:BrowseData/Implementations]] for a drilldown. [[Has default form::Form:Implementation| ]] [[Has filter::Filter:Author| ]] [[Has filter::Filter:Engine| ]] 392 2167 2010-03-12T21:36:12Z Dantman 1 Created page with 'This [[has type::page]] property links to a author's userpage.' This [[has type::page]] property links to a author's userpage. 393 2383 2010-03-15T12:02:54Z Dantman 1 moved [[Property:Embedding]] to [[Property:Engine]] This [[has type::string]] property notes what engine is used by an implementation; SpiderMonkey/C, Rhino, etc... 394 2169 2010-03-12T21:37:09Z Dantman 1 Created page with 'This [[has type::string]] property lists the name of something.' This [[has type::string]] property lists the name of something. 395 2173 2010-03-12T21:39:31Z Dantman 1 This [[has type::URL]] property links to something's website. 396 2381 2010-03-15T12:00:46Z Dantman 1 {{Implementation |name=Flusspferd |url=http://flusspferd.org/ |engines=Spidermonkey/C++ |authors=Ashb, Aristid, Ruediger }} 397 2388 2010-03-15T12:03:39Z Dantman 1 {{Implementation |name=RingoJS |url=http://ringojs.org/ |engines=Rhino |authors=Hannesw }} 398 2479 2010-03-19T10:41:31Z Ondras 57 {{Implementation |name=v8cgi |url=http://code.google.com/p/v8cgi/ |engines=v8 |authors=Ondras |description=V8 embedding written in C++. Aims for webpage development scenarios, high CommonJS compliance and ease of use. }} 399 2482 2010-03-19T16:15:17Z Hdon 101 added myself as an author {{Implementation |name=GPSEE |url=http://code.google.com/p/gpsee/ |engines=SpiderMonkey/C |authors=Wesgarland,hdon }} 400 2483 2010-03-19T18:13:35Z KrisKowal 6 Chiron has been refactored as a Narwhal package and no longer has its own [[Modules/1.0]] implementation. - [[User:KrisKowal|Kris Kowal]] 401 2387 2010-03-15T12:03:35Z Dantman 1 {{Implementation |name=Persevere |url=http://www.persvr.org/ |engines=Rhino |authors=Kriszyp }} 402 2390 2010-03-15T12:04:04Z Dantman 1 {{Implementation |name=node.js |url=http://nodejs.org/ |engines=v8 |authors=Ry }} 403 2389 2010-03-15T12:03:45Z Dantman 1 {{Implementation |name=SproutCore 1.1/Tiki |url=http://www.sproutcore.com/ |engines=web browsers |authors=CharlesJolley }} 404 2396 2010-03-15T12:08:31Z Dantman 1 [[{{{1}}}|{{{2}}}]] ({{{3}}}; {{#arraymap:{{{4}}}|,|!|[[!|{{author name from page|!}}]]}}) 405 2729 2010-04-25T00:35:09Z Dantman 1 {{#ask: [[Category:Implementations]] |?Name |?Engine |?Author |format=ul |template=implementation-short |link=none }} ;Identifiers: {{#ask: [[Category:Implementations]] | template=page to identifier | link=none }} {{#forminput:Implementation| |<identifier>|Add implementation|super_page=Implementations}} == See also == * [[:Category:Implementations|The category]] * [[Special:BrowseData/Implementations|The drilldown page]] 406 2187 2010-03-12T22:05:32Z Dantman 1 Created page with '{{SUBPAGENAME:{{{1}}}}}' {{SUBPAGENAME:{{{1}}}}} 407 2456 2010-03-19T07:58:08Z Dantman 1 {{#if:{{NAMESPACE}}||{{#if:{{{by|}}}|{{#switch:{{uc:{{{status}}}}}|SUPERSEDED=[[Superseded by::{{#ifexist:{{BASEPAGENAME}}/{{{by}}}|{{BASEPAGENAME}}/{{{by}}}|{{{by}}}}}| ]]}}}} '''STATUS: {{uc:{{{status}}}}}{{#if:{{{by|}}}|<nowiki/> BY {{#ifexist:{{BASEPAGENAME}}/{{{by}}}|[[{{BASEPAGENAME}}/{{{by}}}|{{{by}}}]]|[[{{{by}}}]]}}}}''' {{#declare:Published=published}}[[Is standard::{{#ifeq:{{{standard|}}}|yes|Yes|No}}| ]]{{#if:{{{participants|}}}| ;Pardicipants: :{{{participants}}} ([{{{discussion}}} Discussion]) }}{{#if:{{{implementations|}}}|[[Has implementations::yes| ]] ;Implementations: {{#arraymap:{{{implementations}}}|,|!|{{#if:{{#explode:!|=|1}}|{{Spec/implementation|implementation={{#explode:!|=|0}}|state={{#explode:!|=|1}}}}|{{Spec/implementation|implementation=!|state=yes}}}}}}}} <includeonly>[[Category:Spec]]</includeonly> }}{{#if:{{{draft|}}}| * Draft {{{draft|}}}}}{{#if:{{{drafts|}}}|{{#arraymap:{{{drafts}}}|,|!| * [{{fullurl:{{FULLPAGENAME}}|oldid={{#explode:!|:|1}}}} Draft {{#explode:!|:|0}}]| }}}} 409 2204 2010-03-12T22:33:11Z Dantman 1 {{#show:Implementations/{{{1|-}}}|?Name}} 410 2205 2010-03-12T22:34:25Z Dantman 1 Created page with '[[Implementations/{{{1}}}|{{implementation name|{{{1}}}}}]]' [[Implementations/{{{1}}}|{{implementation name|{{{1}}}}}]] 411 2214 2010-03-12T22:46:20Z Dantman 1 Created page with '[[CommonJS]] specs.' [[CommonJS]] specs. 412 2366 2010-03-15T07:51:31Z Dantman 1 <includeonly>{{implementation link|{{{implementation}}}}}{{#ifeq:{{{state|yes}}}|yes||<nowiki/> ({{{state|yes}}})}}<!-- -->{{#set_internal:Implementation of |Implemented by=Implementations/{{{implementation}}} |Implementation state={{{state|yes}}} }}<!-- --></includeonly> 413 2220 2010-03-13T00:34:40Z Dantman 1 Created page with 'This [[has type::page]] property notes what spec an implementation internal object implements.' This [[has type::page]] property notes what spec an implementation internal object implements. 414 2221 2010-03-13T00:35:05Z Dantman 1 Created page with 'This [[has type::page]] property notes what implementation an implementation internal object is implemented by.' This [[has type::page]] property notes what implementation an implementation internal object is implemented by. 415 2223 2010-03-13T00:35:42Z Dantman 1 This [[has type::string]] property notes what state of implementation an implementation internal object is at. 416 2225 2010-03-13T00:41:24Z Dantman 1 Created page with ''''[[Real Name::Daniel Friesen]]''' (also known as Dantman or Nadir-Seen-Fire) ;Homepage : [http://daniel.friesen.name/ daniel.friesen.name] ;E-Mail : [mailto:nadir.seen.fire@gm…' '''[[Real Name::Daniel Friesen]]''' (also known as Dantman or Nadir-Seen-Fire) ;Homepage : [http://daniel.friesen.name/ daniel.friesen.name] ;E-Mail : [mailto:nadir.seen.fire@gmail.com nadir.seen.fire@gmail.com] ;IRC@freenode.net : Dantman, DanielFriesen, Nadir_Seen_Fire 417 2226 2010-03-13T00:42:21Z Dantman 1 Created page with 'This [[has type::string]] property lists the real name of a user.' This [[has type::string]] property lists the real name of a user. 418 2231 2010-03-13T00:51:38Z Dantman 1 <includeonly>{{or|{{#show:User:{{{1}}}| ?Real Name }}|{{{1}}}}}</includeonly> 419 2232 2010-03-13T00:52:26Z Dantman 1 Created page with '{{#if:{{{1|}}}|{{{1}}}|{{{2}}}}}' {{#if:{{{1|}}}|{{{1}}}|{{{2}}}}} 420 2234 2010-03-13T02:28:35Z Dantman 1 Created page with '[[Real Name::Ash Berlin| ]]' [[Real Name::Ash Berlin| ]] 421 2457 2010-03-19T08:05:08Z Dantman 1 ;Implementations {{#ask: [[Implementation of::+]] [[Implemented by::Implementations/Flusspferd]] | mainlabel=- | ?Implementation of= | ?Implementation state= | format=ul }} ---- {{:CommonJS:Sandbox/table |standards={{#ask: [[Category:Spec]] [[Is standard::yes]] | link=none }} |non-standards={{#ask: [[Category:Spec]] [[Is standard::no]] [[Has implementations::yes]] | link=none }} }} ---- {{#ask: [[Category:Implementations]] | mainlabel=- | ?Name= | format=ul }} ---- {{#ask: [[Implementation of::+]] [[Implemented by::+]] | mainlabel=- | ?Implemented by= | ?Implementation of= | ?Implementation state= | format=ul }} 422 2427 2010-03-17T09:11:27Z Dantman 1 = CommonJS = JavaScript is a powerful object oriented language with some of the fastest dynamic language interpreters around. The official JavaScript specification defines APIs for some objects that are useful for building browser-based applications. However, the spec does not define a standard library that is useful for building a broader range of applications. The CommonJS API will fill that gap by defining APIs that handle many common application needs, ultimately providing a standard library as rich as those of Python, Ruby and Java. The intention is that an application developer will be able to write an application using the CommonJS APIs and then run that application across different JavaScript interpreters and host environments. With CommonJS-compliant systems, you can use JavaScript to write: * Server-side JavaScript applications * Command line tools * Desktop GUI-based applications * Hybrid applications (Titanium, Adobe AIR) Read an [http://arstechnica.com/web/news/2009/12/commonjs-effort-sets-javascript-on-path-for-world-domination.ars additional introduction by Kris Kowal at Ars Technica]. == More information about CommonJS == * [[/specs|Specifications and proposals]] * [[/impl|Implementations]] * [[/process|Group Process]] * [[/history|Project History]] 423 2431 2010-03-17T09:24:35Z Dantman 1 Redirect the old 0.1 and 0.5 pages to the new /specs/ page. * /(.+/|)index.html -> /$1 * /(.+).html -> /$1/ * /specs/0\.[15](/.+)? -> /specs/ 424 2249 2010-03-13T05:56:58Z Dantman 1 moved [[Website:Home]] to [[Website:Index]] #REDIRECT [[Website:Index]] 425 2429 2010-03-17T09:22:01Z Dantman 1 Replaced content with '<--404-->' <--404--> 426 2257 2010-03-13T06:16:49Z Dantman 1 = CommonJS Modules = {{:Modules/1.0}} __NOTOC__ 427 2430 2010-03-17T09:22:24Z Dantman 1 Replaced content with '<--404-->' <--404--> 428 2468 2010-03-19T08:49:41Z Dantman 1 = Getting CommonJS = There are several implementations of the CommonJS standard, and you can choose the one that fits what you're trying to do. {{#ask: [[Category:Implementations]] | ?Name | ?URL | ?Engine | ?Author | ?Description | format=template | template=Website:Implementation template | link=none }} __NOTOC__ 429 2260 2010-03-13T07:31:22Z Dantman 1 Another page coppied from CommonJS.org = CommonJS Process = The CommonJS group has, to date, operated in an informal manner. Our goal is to make meaningful progress toward these goals: # Design reasonable APIs for common application needs # Document those designs # Implement those designs in different interpreters and environments The process followed through the development of CommonJS 0.5 has been: # Discussion of an API area is started on the mailing list # A page is created on the wiki to collect proposals and prior art # Further discussion and iteration on the proposals # A rough consensus is reached # The proposal graduates from the wiki to this website So far, achieving rough consensus among the group has been a successful route to meeting these goals. Everyone involved has interoperability on their mind and interop necessarily involves compromise and minimal [[Wikipedia:Parkinson's Law of Triviality|bikeshedding]]. As applications built upon the CommonJS APIs start appearing, we will likely need more process to handle changes to the API. == Further reading == For an interesting take on API design from a highly regarded master, take a look at [http://www.youtube.com/watch?v=aAb7hSCtvGw this tech talk by Josh Bloch]. 430 2261 2010-03-13T07:32:08Z Dantman 1 Created page with '= CommonJS Project History = * January 2009: the group was formed as "ServerJS" following a blog post on Kevin Dangoor's Blue Sky on Mars * March 2009: the dust had settled aroun…' = CommonJS Project History = * January 2009: the group was formed as "ServerJS" following a blog post on Kevin Dangoor's Blue Sky on Mars * March 2009: the dust had settled around "securable modules" as the module style for the group. This is CommonJS API 0.1 * April 2009: CommonJS modules were shown off with several implementations at the first JSConf in Washington, DC. * August 2009: The group name was formally changed to CommonJS to reflect the broader applicability of the APIs. 431 2428 2010-03-17T09:14:47Z Dantman 1 <div class="news-top"> = Site Updates = </div> <div class="news_items"> * // Formatting has been cleaned up around the site and on the [[Website:Index/specs/modules/1.0|Modules 1.0]] page. * // This website has been replaced with a new one backed by the wiki so it can be edited by the whole commonjs community. * // We are no longer using the bulk 0.1 and 0.5 specification version numbers. Specs individually are marked as standards. = CommonJS Links = * // [http://wiki.commonjs.org/ Wiki] (standards-in-training!) * // [http://groups.google.com/group/commonjs/ Mailing list] * // [http://twitter.com/commonjs Twitter] * // [irc://irc.freenode.net/commonjs #commonjs on irc.freenode.net] </div> 432 2264 2010-03-13T07:49:02Z Dantman 1 Created page with '= The CommonJS Contributors = Creating the CommonJS APIs has been a volunteer effort, and the people below have contributed their time and energy to creating a consensus around t…' = The CommonJS Contributors = Creating the CommonJS APIs has been a volunteer effort, and the people below have contributed their time and energy to creating a consensus around these APIs. Without working through the details and making compromises, we would never have standardized anything or seen any implementations come into existence. The following people have contributed substantially to the work of creating the CommonJS APIs: * Ihab Awad * Ash Berlin * Aristid Breitkreuz * Kevin Dangoor * Daniel Friesen * Wes Garland * Kris Kowal * Dean Landolt * Peter Michaux * George Moschovitis * Michael O'Brien * Tom Robinson * Hannes Wallnoefer * Mike Wilson * Ondrej Zara * Chris Zumbrunn * Kris Zyp My apologies to any contributor whose name was omitted. With thousands of messages of discussion during 2009, there are many people who have come and pitched in to the project with their ideas. Additionally, thanks are due to all of the people who have been involved in building the implementations of the CommonJS APIs. Many of the people on the list above are implementers, but there are many other people involved in their projects and many other projects that are not represented here. Thanks to you all for making this project a success! 433 2267 2010-03-13T07:51:52Z Dantman 1 = CommonJS Documentation and Code License = The output of the CommonJS group is protected under copyright laws, but is intended for the good of the JavaScript development community. CommonJS related projects are licensed under whatever terms the author(s) wish to apply, but the CommonJS specifications and test suites are all licensed under the MIT-style license presented below. Copyright © 2009 - Kevin Dangoor and many [[../contributors/|CommonJS contributors]]. == License == Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 434 2443 2010-03-19T06:58:06Z Dantman 1 @charset "UTF-8"; /** css/styles.css **/ body { background-color: #3c3c3c; font-family: Helvetica, Arial, sans-serif; margin: 0px; padding: 0px; font-size: 14px; line-height: 18px; } .col_level { font-size: 0px; clear: both; height: 1px; } /* PAGE HEADER */ .header_wrapper { height: 107px; background-image: url(http://wiki.commonjs.org/images/1/19/Header_wrapper_bg.png); background-repeat: repeat-x; } .header_bg { width: 970px; margin-right: auto; margin-left: auto; height: 107px; background-image: url(http://wiki.commonjs.org/images/9/9c/Header_gradient.jpg); background-repeat: no-repeat; background-position: center; } .tagline { float: left; margin-left: 15px; line-height: 107px; font-size: 18px; color: #9f9f9f; } img.logo { float: left; margin-top: 24px; margin-left: 0px; } .nav_wrapper { float: right; height: 107px; } .nav_item { float: right; width: 125px; color: #FFFFFF; text-align: center; padding-top: 60px; height: 47px; font-size: 22px; font-weight: normal; } .nav_item a:link, .nav_item a:visited { color: #FFFFFF; text-decoration: none; } .nav_item a:hover { color: #CCCCCC; } .nav1 { background-image: url(http://wiki.commonjs.org/images/d/d0/Nav_js.png); background-repeat: repeat-x; background-position: bottom; } body.specs .nav1 { background-image: url(http://wiki.commonjs.org/images/7/73/Nav_js_on.png); /*turn on the corresponding nav item*/ } .nav2 { background-image: url(http://wiki.commonjs.org/images/8/89/Nav_commonjs.png); background-repeat: repeat-x; background-position: bottom; } body.impl .nav2 { background-image: url(http://wiki.commonjs.org/images/6/67/Nav_commonjs_on.png); /*turn on the corresponding nav item*/ } .nav3 { background-image: url(../images/nav_browsers.png); background-repeat: repeat-x; background-position: bottom; } .nav_div { float: right; background-image: url(http://wiki.commonjs.org/images/9/97/Nav_div.png); width: 1px; background-position: bottom; height: 107px; background-repeat: no-repeat; } /* PAGE BODY */ .content_wrapper { background-image: url(http://wiki.commonjs.org/images/a/a4/Content-wrapper_bg.png); background-repeat: repeat-x; background-color: #efefef; } .content_bg { width: 1000px; margin-right: auto; margin-left: auto; background-image: url(http://wiki.commonjs.org/images/1/1e/Content_bg.png); background-repeat: repeat-y; } .content { position: relative; background-image: url(http://wiki.commonjs.org/images/2/2c/Banner_home.jpg); background-repeat: no-repeat; background-position: center 11px; } body.status404 .content { background-image: url(http://wiki.commonjs.org/images/3/3a/Banner_gray.jpg) } body.specs .content { background-image: url(http://wiki.commonjs.org/images/8/82/Banner_blue.jpg) } body.impl .content { background-image: url(http://wiki.commonjs.org/images/9/99/Banner_green.jpg) } .content-left { width: 680px; margin-left: 42px; margin-top: 180px; float: left; padding-bottom: 20px; } .content-left h1 { font-size: 28px; color: #863e3e; font-weight: normal; margin-top: 0px; margin-right: 0px; margin-bottom: 6px; margin-left: 0px; } body.status404 .content-left h1 { color: #ccc; } body.specs .content-left h1 { color: #266790; /*change the color of page headers*/ } body.impl .content-left h1 { color: #4e5d2e; /*change the color of page headers*/ } /* NEWS */ .news_wrapper { width: 219px; right: 14px; float: right; margin-right: 27px; margin-top: 152px; font-size: 12px; line-height: 13px; } .news-top { background-image: url(http://wiki.commonjs.org/images/c/c6/News_bg-top.png); background-repeat: no-repeat; height: 25px; background-position: left top; padding-left: 24px; vertical-align: bottom; padding-top: 20px; } .news_items { background-image: url(http://wiki.commonjs.org/images/a/a9/News_bg-btm.png); background-repeat: no-repeat; background-position: left bottom; padding-left: 24px; color: #9d9d9d; padding-right: 12px; } .news_items ul { list-style: none; margin-left: 0; padding-left: 1em; text-indent: -.9em; margin-top: 0px; } .news_items li { margin-bottom: 8px; margin-left: 8px; } .news_items a:link, .news_items a:visited { color: #90d5ff; text-decoration: none; } .news_items a:hover { text-decoration: underline; } .news_wrapper h1 { font-weight: normal; font-size: 16px; margin-bottom: 8px; color: #636363; margin-top: 0px; } /* PAGE FOOT */ .footer_wrapper { font-size: 10px; border-top-width: 10px; border-top-style: solid; border-top-color: #636363; text-align: center; padding-top: 10px; padding-bottom: 10px; color: #999999; } .footer_wrapper a { color: #bbb } .footer_bg { width: 970px; margin-right: auto; margin-left: auto; } /** css/colorful.css **/ .codehilite .hll { background-color: #ffffcc } .codehilite .c { color: #808080 } /* Comment */ .codehilite .err { color: #F00000; background-color: #F0A0A0 } /* Error */ .codehilite .k { color: #008000; font-weight: bold } /* Keyword */ .codehilite .o { color: #303030 } /* Operator */ .codehilite .cm { color: #808080 } /* Comment.Multiline */ .codehilite .cp { color: #507090 } /* Comment.Preproc */ .codehilite .c1 { color: #808080 } /* Comment.Single */ .codehilite .cs { color: #cc0000; font-weight: bold } /* Comment.Special */ .codehilite .gd { color: #A00000 } /* Generic.Deleted */ .codehilite .ge { font-style: italic } /* Generic.Emph */ .codehilite .gr { color: #FF0000 } /* Generic.Error */ .codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */ .codehilite .gi { color: #00A000 } /* Generic.Inserted */ .codehilite .go { color: #808080 } /* Generic.Output */ .codehilite .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ .codehilite .gs { font-weight: bold } /* Generic.Strong */ .codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ .codehilite .gt { color: #0040D0 } /* Generic.Traceback */ .codehilite .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ .codehilite .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ .codehilite .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ .codehilite .kp { color: #003080; font-weight: bold } /* Keyword.Pseudo */ .codehilite .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ .codehilite .kt { color: #303090; font-weight: bold } /* Keyword.Type */ .codehilite .m { color: #6000E0; font-weight: bold } /* Literal.Number */ .codehilite .s { background-color: #fff0f0 } /* Literal.String */ .codehilite .na { color: #0000C0 } /* Name.Attribute */ .codehilite .nb { color: #007020 } /* Name.Builtin */ .codehilite .nc { color: #B00060; font-weight: bold } /* Name.Class */ .codehilite .no { color: #003060; font-weight: bold } /* Name.Constant */ .codehilite .nd { color: #505050; font-weight: bold } /* Name.Decorator */ .codehilite .ni { color: #800000; font-weight: bold } /* Name.Entity */ .codehilite .ne { color: #F00000; font-weight: bold } /* Name.Exception */ .codehilite .nf { color: #0060B0; font-weight: bold } /* Name.Function */ .codehilite .nl { color: #907000; font-weight: bold } /* Name.Label */ .codehilite .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ .codehilite .nt { color: #007000 } /* Name.Tag */ .codehilite .nv { color: #906030 } /* Name.Variable */ .codehilite .ow { color: #000000; font-weight: bold } /* Operator.Word */ .codehilite .w { color: #bbbbbb } /* Text.Whitespace */ .codehilite .mf { color: #6000E0; font-weight: bold } /* Literal.Number.Float */ .codehilite .mh { color: #005080; font-weight: bold } /* Literal.Number.Hex */ .codehilite .mi { color: #0000D0; font-weight: bold } /* Literal.Number.Integer */ .codehilite .mo { color: #4000E0; font-weight: bold } /* Literal.Number.Oct */ .codehilite .sb { background-color: #fff0f0 } /* Literal.String.Backtick */ .codehilite .sc { color: #0040D0 } /* Literal.String.Char */ .codehilite .sd { color: #D04020 } /* Literal.String.Doc */ .codehilite .s2 { background-color: #fff0f0 } /* Literal.String.Double */ .codehilite .se { color: #606060; font-weight: bold; background-color: #fff0f0 } /* Literal.String.Escape */ .codehilite .sh { background-color: #fff0f0 } /* Literal.String.Heredoc */ .codehilite .si { background-color: #e0e0e0 } /* Literal.String.Interpol */ .codehilite .sx { color: #D02000; background-color: #fff0f0 } /* Literal.String.Other */ .codehilite .sr { color: #000000; background-color: #fff0ff } /* Literal.String.Regex */ .codehilite .s1 { background-color: #fff0f0 } /* Literal.String.Single */ .codehilite .ss { color: #A06000 } /* Literal.String.Symbol */ .codehilite .bp { color: #007020 } /* Name.Builtin.Pseudo */ .codehilite .vc { color: #306090 } /* Name.Variable.Class */ .codehilite .vg { color: #d07000; font-weight: bold } /* Name.Variable.Global */ .codehilite .vi { color: #3030B0 } /* Name.Variable.Instance */ .codehilite .il { color: #0000D0; font-weight: bold } /* Literal.Number.Integer.Long */ /** Geshi; We only use a few langs so we'll just hardcode them into the site styles **/ .source-javascript {line-height: normal;} .source-javascript li, .source-javascript pre { line-height: normal; border: 0px none white; } /** * GeSHi Dynamically Generated Stylesheet * -------------------------------------- * Dynamically generated stylesheet for javascript * CSS class: source-javascript, CSS id: * GeSHi (C) 2004 - 2007 Nigel McNie, 2007 - 2008 Benny Baumann * (http://qbnz.com/highlighter/ and http://geshi.org/) * -------------------------------------- */ .javascript.source-javascript .de1, .javascript.source-javascript .de2 {font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;} .javascript.source-javascript {font-family:monospace;} .javascript.source-javascript .imp {font-weight: bold; color: red;} .javascript.source-javascript li, .javascript.source-javascript .li1 {font-weight: normal; vertical-align:top;} .javascript.source-javascript .ln {width:1px;text-align:right;margin:0;padding:0 2px;vertical-align:top;} .javascript.source-javascript .li2 {font-weight: bold; vertical-align:top;} .javascript.source-javascript .kw1 {color: #000066; font-weight: bold;} .javascript.source-javascript .kw2 {color: #003366; font-weight: bold;} .javascript.source-javascript .kw3 {color: #000066;} .javascript.source-javascript .co1 {color: #006600; font-style: italic;} .javascript.source-javascript .co2 {color: #009966; font-style: italic;} .javascript.source-javascript .coMULTI {color: #006600; font-style: italic;} .javascript.source-javascript .es0 {color: #000099; font-weight: bold;} .javascript.source-javascript .br0 {color: #009900;} .javascript.source-javascript .sy0 {color: #339933;} .javascript.source-javascript .st0 {color: #3366CC;} .javascript.source-javascript .nu0 {color: #CC0000;} .javascript.source-javascript .me1 {color: #660066;} .javascript.source-javascript .ln-xtra, .javascript.source-javascript li.ln-xtra, .javascript.source-javascript div.ln-xtra {background-color: #ffc;} .javascript.source-javascript span.xtra { display:block; } table.wikitable { margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; } table.wikitable th, .wikitable td { border: 1px #aaa solid; padding: 0.2em; } table.wikitable th { background: #f2f2f2; text-align: center; } table.wikitable caption { font-weight: bold; } 435 2270 2010-03-13T08:11:59Z Dantman 1 Protected "[[File:Website-Logo.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 436 2272 2010-03-13T08:20:17Z Dantman 1 Protected "[[File:News bg-top.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 437 2293 2010-03-13T08:31:49Z Dantman 1 Protected "[[File:News bg-btm.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 438 2292 2010-03-13T08:31:45Z Dantman 1 Protected "[[File:Nav js.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 439 2291 2010-03-13T08:31:41Z Dantman 1 Protected "[[File:Nav div.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 440 2290 2010-03-13T08:31:36Z Dantman 1 Protected "[[File:Nav commonjs.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 441 2289 2010-03-13T08:31:32Z Dantman 1 Protected "[[File:Header wrapper bg.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 442 2288 2010-03-13T08:31:28Z Dantman 1 Protected "[[File:Header gradient.jpg]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 443 2287 2010-03-13T08:31:23Z Dantman 1 Protected "[[File:Content bg.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 444 2286 2010-03-13T08:31:19Z Dantman 1 Protected "[[File:Content-wrapper bg.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 445 2285 2010-03-13T08:31:14Z Dantman 1 Protected "[[File:Banner home.jpg]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 446 2283 2010-03-13T08:29:27Z Dantman 1 Protected "[[File:Banner gray.jpg]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 447 2301 2010-03-13T08:45:38Z Dantman 1 Protected "[[File:Banner blue.jpg]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 448 2302 2010-03-13T08:46:08Z Dantman 1 Protected "[[File:Banner green.jpg]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 450 2304 2010-03-13T08:49:54Z Dantman 1 Created page with '= 404 = Sorry the page you requested could not be found.' = 404 = Sorry the page you requested could not be found. 451 2306 2010-03-13T08:59:03Z Dantman 1 Protected "[[File:Nav js on.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 452 2308 2010-03-13T09:03:23Z Dantman 1 Protected "[[File:Nav commonjs on.png]]" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) 453 2317 2010-03-13T12:00:02Z Dantman 1 Created page with 'This filter covers the property [[Covers property::Author]].' This filter covers the property [[Covers property::Author]]. 455 2322 2010-03-13T13:14:47Z Dantman 1 Created page with 'Status' Status 456 2323 2010-03-13T13:15:12Z Dantman 1 Created page with 'Unpublished' Unpublished 457 2324 2010-03-13T13:15:31Z Dantman 1 Created page with 'Published' Published 458 2327 2010-03-13T13:16:33Z Dantman 1 Pristine 459 2340 2010-03-13T20:09:41Z Dantman 1 moved [[User:MrN]] to [[User:Aristid]] #REDIRECT [[User:Aristid]] 460 2345 2010-03-14T06:33:12Z Dantman 1 Created page with ' # <pre> # CommonJS.org Robots.txt User-agent: * Disallow: # </pre>' # <pre> # CommonJS.org Robots.txt User-agent: * Disallow: # </pre> 462 2353 2010-03-14T08:33:13Z Dantman 1 jQuery(function($) { var showDraft = wgCurRevisionId !== wgStableRevisionId && wgViewRevisionId === wgCurRevisionId; if ( /^Website:Index(\/.+)?$/.test(wgPageName) ) { $("<a class=website_link>View on "+(showDraft?"draft ":"")+"website</a>").attr({href: wgPageName.replace("Website:Index", showDraft?"http://draft.commonjs.org":"http://commonjs.org")+"/"}).prependTo("#firstHeading"); } }); 463 2370 2010-03-15T11:00:16Z Dantman 1 Redirected page to [[CommonJS:Sandbox]] #REDIRECT [[Project:Sandbox]] 464 2384 2010-03-15T12:02:54Z Dantman 1 moved [[Property:Embedding]] to [[Property:Engine]] #REDIRECT [[Property:Engine]] 465 2394 2010-03-15T12:06:30Z Dantman 1 Created page with 'This filter covers the property [[Covers property::Engine]].' This filter covers the property [[Covers property::Engine]]. 466 2398 2010-03-15T12:09:57Z Dantman 1 <includeonly>{{or|{{#show:{{{1}}}| ?Real Name }}|{{#explode:{{{1}}}|:|1}}}}</includeonly> 467 2404 2010-03-15T19:11:42Z Mvalente 14 CommonJS logo proposal, a reworked and finished version of the 99% Mario,1% Wes solution CommonJS logo proposal, a reworked and finished version of the 99% Mario,1% Wes solution 468 2775 2010-05-17T11:11:10Z Jhuni 106 I changed my mind, nothing wrong with any particular transport format... {{Spec |status=proposal |implementations=Yabble }} Module transport format is a content format that can be used to send module factories from a server to an asynchronous client-side module loader. A module factory can then be used on the client to instantiate modules. == Example == require.define({ // transport the math/add module "math/add": function(require, exports, module){ var sum = require("./general").sum; exports.plusTwo = function(a){ return sum(a, 2); }; } },["math/general"]); // list deps == Specification == This specification defines a require.define function that can be called to provide modules to a loader. # JavaScript script may consist of any number of calls to a "require.define" function. # "require.define" accepts a module set, which is an object where each property name represents a top-level module identifier and every value is a "module descriptor". # A "module descriptor" can be a function or an object: ## If the "module descriptor" is a function, it is is the factory function. ## If the "module descriptor" is an object, it can have the following properties ## An "injects" array of the known free-variables that are applicable ("require", "exports", or "module"). Each of these variables should be passed to the factory function at the corresponding parameter positions. ## A "factory" function. The factory function for the module. The "injects" property may define the arguments passed to the factory function. If "injects" is omitted then the arguments should default to the free variables for the module format ("require", "exports", or "module" for CommonJS modules). # The second parameter of require.define is an array of top-level module identifiers corresponding to the shallow dependencies of the given module factory, those that it directly "requires". Module factories must not be called until all of the module desciptors mentioned in the transitive "requires" have been given to a loader by calls to "require.define". This parameter is optional. If omitted, the set of dependencies is empty. Calling require.define does not guarantee that the module's factory will be immediately executed even if the dependencies are available. Module factories generally should not be executed until they are requested by a require, require.ensure, or other module requesting mechanism. If multiple require.define exists in one script, care must be taken to ensure the correct order, module transport writers must not assume that the modules from future require.define (later in a script) calls will be available to previous calls. In other words this will likely trigger an unnecessary request for module "b": require.define({'a': function() {}}, ['b']); require.define({'b': function() {}}); === Non-Normative Optional Extensions === These capabilities are not required, but some loaders may support: # If the factory value is a string, some loaders may support evaluating the string to a factory function # Some loaders may support module-specific dependency lists, read from the module descriptor object's "dependencies" property. == Format == require.define({ "MODULE_ID": FACTORY_FUNCTION or {injects: [INJECTIONS], factory: FACTORY_FUNCTION}, ... }, [ARRAY_OF_DEPENDENCY_MODULE_IDS]); == Examples == === Transporting a set of CommonJS modules === Transports CommonJS modules "alpha" and "beta", which depend on "gamma": require.define({ "alpha": function (require, exports, module) { exports.verb = function() { return require("beta").action(); } }, "beta": function (require, exports, module) { exports.action = function() { return require("gamma").something(); } }, }, ["gamma"]); === Defining a module === Defining a module using module injection: require.define({ "alpha": { injects: ["require", "module", "exports"], factory: function (require, module, exports) { exports.verb = function() { return require("beta").action(); } } } }); = Implementation/Usage Notes = Just like any JavaScript object literal, the use of property names that correspond to the property names on Object.prototype will not be enumerable in older versions of Internet Explorer, and modules with such names might not be detected by a loader unless it specifically checks for them. Also, duplicate module ids MUST not be included in object literals, different JavaScript VMs treat duplicates differently. = Philosophy = Module Transport Format is optimized for auto-generated transportation of modules, but can be written by hand if necessary. It is intended that modules conforming to the CommonJS [[Modules/1.1]] specification can be programmatically wrapped and bundled to Module Transport Format. Crafting by hand in this format introduces fragility because individual modules and trees of modules become autonomous and therefore tightly coupled to their module name space. * modules can be dynamically compiled to Module Transport Format by simply wrapping, internal modification to modules is not necessary * all module factories can be registered in a single call with minimal boilerplate, but also * module transport format is concatenatable. * module namespace domain for declaring modules and specifying dependencies is not reduced by free variables (like require, exports, module). * modules can be injected as arguments to the factory to ease referencing other modules. * the module descriptor is an extensible name space. * dependency sets can be defined after modules to reduce memory usage in generation implementors. == Considerations for transport when used in the browser == * Relative module names that start with "." and ".." are not supported in the top level module IDs, particularly if many modules are being transported from different paths. == Show of Hands == * In favor of Transport/D: ** Kris Zyp ** Kris Kowal * Opposed to Transport/D: ** Tobie Langel If opposed or in favor with reservations, vote on changes that you want: * A bundle should consist of a '''single''' call to a "require.define" function. ** Tobie Langel * require.define should only take a single module (instead of module set hash). require.pause and require.resume should be added to define modules with circular dependencies. * Each module descriptor should allow for a dependency list ** Tobie Langel (this list should be somehow made optional) * The dependency list should be the first argument * Strings should be accepted as factory values (and eval'd with a CommonJS wrapper) * Allow for module ids in the injects array 469 2412 2010-03-17T08:15:33Z Dantman 1 Created page with 'This [[has type::boolean]] property notes whether a spec has become a final standard or not.' This [[has type::boolean]] property notes whether a spec has become a final standard or not. 470 2416 2010-03-17T08:42:52Z Dantman 1 Created page with 'This [[has type::page]] property lists the published version of a spec.' This [[has type::page]] property lists the published version of a spec. 471 2425 2010-03-17T09:08:31Z Dantman 1 {{#if:{{{5}}} |{{#if:{{{3|}}}|[[{{{3}}}|{{or|{{{2}}}|{{{1}}}}}]]|{{or|{{{2}}}|{{{1}}}}}}} ^{[[{{{1}}}|&#91;draft&#93;]]}{{#if:{{{4|}}}|<nowiki/> ^{(Superseded by {{spec name|{{{4}}}}})}}} |[[{{{1}}}|{{or|{{{2}}}|{{{1}}}}}]] }} 472 2422 2010-03-17T09:06:00Z Dantman 1 Created page with 'This [[has type::page]] property defines a spec that has superseded the spec it is placed on.' This [[has type::page]] property defines a spec that has superseded the spec it is placed on. 473 2423 2010-03-17T09:07:28Z Dantman 1 Created page with '<includeonly>{{or|{{#show:{{{1}}}| ?Name }}|{{{1}}}}}</includeonly>' <includeonly>{{or|{{#show:{{{1}}}| ?Name }}|{{{1}}}}}</includeonly> 474 2426 2010-03-17T09:08:58Z Dantman 1 Created page with '= CommonJS API = == Current Specifications == {{#ask: [[Category:Spec]] [[Is standard::yes]] | ?Name | ?Published | ?Superseded by | ?Is standard#yes, | format=ul | template=spec…' = CommonJS API = == Current Specifications == {{#ask: [[Category:Spec]] [[Is standard::yes]] | ?Name | ?Published | ?Superseded by | ?Is standard#yes, | format=ul | template=spec-list-item | link=none }} == Proposals and standards in development == {{#ask: [[Category:Spec]] [[Is standard::no]] | ?Name | ?Published | ?Superseded by | ?Is standard#yes, | format=ul | template=spec-list-item | link=none }} 475 2439 2010-03-19T06:50:54Z Dantman 1 Created page with '{{#expr:{{#arraymap:{{{1}}}|{{{2|,}}}|!|1|+}}}}' {{#expr:{{#arraymap:{{{1}}}|{{{2|,}}}|!|1|+}}}} 476 2451 2010-03-19T07:28:54Z Dantman 1 {| class=wikitable |- !rowspan=2| Implementations !colspan={{arraycount|{{{standards}}}}}| Standards !colspan={{arraycount|{{{non-standards}}}}}| Proposals and standards in development |- ! {{#arraymap:{{{standards}}}|,|!|[[!]]| !! }} ! {{#arraymap:{{{non-standards}}}|,|!|[[!]]| !! }} {{#arraymap:{{#ask:[[Category:Implementations]]|link=none}}|,|!|<nowiki/> {{CommonJS:Sandbox/table/row |implementation=! |standards={{{standards}}} |non-standards={{{non-standards}}} }} | }} |} 477 2455 2010-03-19T07:55:07Z Dantman 1 |- | {{implementation link|{{page to identifier|{{{implementation}}}}}}}<!-- -->{{#arraymap:{{{standards}}}, {{{non-standards}}}|,|%spec%|<nowiki/> {{!}} {{#ask: [[Implementation of::%spec%]] [[Implemented by::{{{implementation}}}]] | mainlabel=- | ?Implementation state= }} | }} 478 2448 2010-03-19T07:21:20Z Dantman 1 Created page with '|' | 479 2546 2010-04-01T20:32:35Z Dantman 1 {| class=wikitable width=100% |- !rowspan=2| [[Implementations]] !colspan={{arraycount|{{{standards}}}}}| Standards !colspan={{arraycount|{{{non-standards}}}}}| Proposals and standards in development |- ! {{#arraymap:{{{standards}}}|,|!|[[!]]| !! }} ! {{#arraymap:{{{non-standards}}}|,|!|[[!]]| !! }} {{#arraymap:{{#ask:[[Category:Implementations]]|link=none}}|,|!|<nowiki/> {{ImplementationsTable/row |implementation=! |standards={{{standards}}} |non-standards={{{non-standards}}} }} | }} |} 480 2459 2010-03-19T08:13:17Z Dantman 1 Created page with '|- | {{implementation link|{{page to identifier|{{{implementation}}}}}}}<!-- -->{{#arraymap:{{{standards}}}, {{{non-standards}}}|,|%spec%|<nowiki/> {{!}} {{#ask: [[Implementation…' |- | {{implementation link|{{page to identifier|{{{implementation}}}}}}}<!-- -->{{#arraymap:{{{standards}}}, {{{non-standards}}}|,|%spec%|<nowiki/> {{!}} {{#ask: [[Implementation of::%spec%]] [[Implemented by::{{{implementation}}}]] | mainlabel=- | ?Implementation state= }} | }} 481 2476 2010-03-19T09:03:28Z Dantman 1 <nowiki/> == {{{2}}} == {{{3}}} ;Engine(s): {{{4}}} ;Author(s): {{#arraymap:{{{5}}}|,|!|[[!|{{author name|{{PAGENAME:!}}}}]]}} ;Implementations: {{#ask: [[Implementation of::+]] [[Implemented by::{{{1}}}]] | mainlabel=- | ?Implementation of= | ?Implementation state= | format=list | link=none }} {{{6|}}} 482 2475 2010-03-19T08:57:48Z Dantman 1 <noinclude> This is the 'Implementation' form. To add a page with this form, enter the page name below; if a page with that name already exists, you will be sent to a form to edit that page. {{#forminput:Implementation}} </noinclude><includeonly> {{{for template|Implementation}}} {| class="formtable" ! Name: | {{{field|name|mandatory}}} |- ! URL: | {{{field|url}}} |- ! Engine(s): | {{{field|engines|list|autocomplete}}} |- ! Author(s):<br>(Please use usernames only) | {{{field|authors|list|autocomplete on namespace=User}}} |- ! Description: | {{{field|description|input type=textarea}}} |} {{{end template}}} {{{standard input|summary}}} {{{standard input|minor edit}}} {{{standard input|watch}}} {{{standard input|save}}} {{{standard input|preview}}} {{{standard input|changes}}} {{{standard input|cancel}}} </includeonly> 483 2478 2010-03-19T09:12:28Z Dantman 1 Created page with 'Implementations' Implementations 484 2481 2010-03-19T11:58:23Z Wesgarland 13 Created page with '[[Real Name::Wes Garland]]' [[Real Name::Wes Garland]] 485 2805 2010-05-27T09:29:57Z Alexandre.Morgaut 33 {{Spec |status=proposed, discussed, some implementations |implementations=Wakanda }} = console = console is a well known logging facility to all the JS devs. By utilizing this standard interface which is almost identical across all major browsers, we will gain from familiarity from the developers. console is not a replacement for a `print` or any other full featured logging API, it may be an easily available default instance of a logger or a wrapper on `print`. Message representation and implementation is up to the platform provider. == Prior Art == * [http://getfirebug.com/wiki/index.php/Console_API] Console API in FireBug * [http://developer.apple.com/safari/library/documentation/AppleApplications/Reference/WebKitDOMRef/Console_idl/Classes/Console/index.html]. Console API in Webkit inspector. == Proposals == * [[console/A]] by Irakli Gozalishvili All platforms must support a module, `console`, that MUST export following: === log(object[, object, ...]) === logs a message to with visual "log" representation allowing user to distinguish form other message types. You may pass as many arguments as you'd like, and they will be joined together in a space-delimited line. The first argument to <code>log</code> may be a string containing printf-like string substitution patterns. For example: <pre class="code">require("console").log("The %s jumped over %d tall buildings", animal, count);</pre> The example above can be re-written without string substitution to achieve the same result: <pre class="code">require("console").log("The", animal, "jumped over", count, "tall buildings");</pre> These two techniques can be combined. If you use string substitution but provide more arguments than there are substitution patterns, the remaining arguments will be appended in a space-delimited line, like so: <pre class="code">require("console").log("I am %s and I have:", myName, thing1, thing2, thing3);</pre> If objects are logged, platform provider may write the as static text, or a representation of an object, some platforms might dump interactive hyperlinks that can be inspected. Here is the complete set of patterns that you may use for string substitution: <table width="600"> <tr><td class="keyHead" colspan="2">String Substitution Patterns</td></tr> <tr><td class="keyType">%s</td><td class="keyCode">String</td></tr> <tr><td class="keyType">%d, %i</td><td class="keyCode">Integer (numeric formatting is not yet supported)</td></tr> <tr><td class="keyType">%f</td><td class="keyCode">Floating point number (numeric formatting is not yet supported)</td></tr> <tr><td class="keyType">%o</td><td class="keyCode">Object hyperlink</td></tr> </table> === debug(object[, object, ...]) === Logs a message, with a visual "debug" representation. Optionally includes an info of a caller (file, line where it was called from). === info(object[, object, ...]) === Logs a message with the visual "info" representation. Optionally includes an info of a caller (file, line where it was called from). === warn(object[, object, ...]) === Logs a message with the visual "warning" representation. Optionally includes an info of a caller (file, line where it was called from). === error(object[, object, ...]) === Logs a message with the visual "error" representation. Optionally includes an info of a caller (file, line where it was called from). === assert(expression[, object, ...]) === Tests that an expression is true. If not, logs a message and throws an exception. === dir(object) === Logs a static / interactive listing of all properties of the object. === dirxml(node) === Logs the XML source tree of an HTML or XML element. Even though there is no CommonJS standards for XML, HTML yet most likely there will be one at some point. In order to keep compatibility with well known console from browsers, platform should implement this and may decide to default for a log or dir described above. === trace() === Logs a static / interactive stack trace of JavaScript execution at the point where it is called. Details that platform is able to provide is most likely will be different there for it's up to platform, some may provide full stack trace like the functions on the stack, as well as the values that were passed as arguments to each function. While others may log just a module require graph. === group(object[, object, ...]) === Logs a message to and opens a nested block to indent all future messages sent. Call <code>require("console").groupEnd()</code> to close the block. Representation of block is up to the platform, it can be an interactive block or just a set of indented sub messages. === groupEnd() === Closes the most recently opened block created by a call to <code>require("console").group()</code> or <code>require("console").groupCollapsed()</code> === time(name) === Creates a new timer under the given name. Call <code>require("console").timeEnd(name)</code> with the same name to stop the timer and log the time elapsed.. === timeEnd(name) === Stops a timer created by a call to <code>require("console").time(name)</code> and logs the time elapsed. === profile([title]) === Turns on profiler. The optional argument <code>title</code> would contain the text to be logged in the header of the profile report. Data included in a report generated by a profiler is up to platform. === profileEnd() === Turns off profiler and logs its report. === count([title]) === Writes the number of times that the line of code where <code>count</code> was called was executed. The optional argument <code>title</code> will print a message in addition to the number of the count. == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/160225ffabe4c2a4# console API] 486 2719 2010-04-20T14:21:37Z Jbrantly 109 {{Spec |status=proposal |drafts=3 |drafts=2:2515 |drafts=1:2487 |implementations=Yabble }} This a proposal for the specification of the "require.ensure" method. (Formerly "require.async".) == Contract == # "require.ensure" accepts an array of module identifiers as first argument and a callback function as second argument. # The callback function must be called as soon as all of the foreign modules, and their shallow and deep dependencies are available for synchronous require. ## The callback function must be passed the "require" function as its first argument. === Unspecified === This specification leaves the following important points of interoperability unspecified: # the return value of "require.ensure" to allow for future modifications of the specification, notably the inclusion of promises, # the means by which the foreign modules are loaded, and # the presence of a timeout. == Sample Code == ;math.js: <source> exports.add = function() { var sum = 0, i = 0, args = arguments, l = args.length; while (i < l) { sum += args[i++]; } return sum; }; </source> ;increment.js: <source> var add = require('math').add; exports.inc = function(val) { return add(val, 1); }; </source> ;program.js: <source> require.ensure(['increment'], function(require) { var inc = require('increment').inc; var a = 1; inc(a); // 2 }); </source> <noinclude> == Notes == * Given the semantic shift this method has taken thanks to Wes Garland's suggestions, the name "require.async" no longer seemed appropriate. We ended up agreeing on "require.ensure" instead. == Related Discussion == * [http://groups.google.com/group/commonjs/browse_thread/thread/3cab4886bb39c28e Updated Transport proposals] * [http://chat.commonjs.org/mochabot/2010-03-25 IRC log]. Discussion starts at 00:34. 487 2489 2010-03-22T19:40:19Z KrisKowal 6 moved [[Modules/require/async/A]] to [[Modules/Async/A]]:&#32;reorg #REDIRECT [[Modules/Async/A]] 488 2799 2010-05-27T09:09:26Z Alexandre.Morgaut 33 {{Spec |status=approved by discussion participants |standard=yes |implementations=Yabble, CouchDB, Narwhal=0.2, Wakanda }} '''Show of hands: Mikeal, Gozala, Zach Carter, Hannesw, Tobie, Ondřej Žára, Charles Jolley, KrisKowal, Chris Zumbrunn, Gmsox''' This specification addresses how modules should be written in order to be interoperable among a class of module systems that can be both client and server side, secure or insecure, implemented today or supported by future systems with syntax extensions. These modules are offered privacy of their top scope, facility for importing singleton objects from other modules, and exporting their own API. By implication, this specification defines the minimum features that a module system must provide in order to support interoperable modules. == Contract == === Require === # require is a Function ## The "require" function accepts a module identifier. ## "require" returns the exported API of the foreign module. ## If there is a dependency cycle, the foreign module may not have finished executing at the time it is required by one of its transitive dependencies; in this case, the object returned by "require" must contain at least the exports that the foreign module has prepared before the call to require that led to the current module's execution. ## If the requested module cannot be returned, "require" must throw an error. ## The "require" function may have a "main" property. ### This attribute, when feasible, should be read-only, don't delete. ### The "main" property must either be undefined or be identical to the "module" object in the context of one loaded module. ## The "require" function may have a "paths" attribute, that is a prioritized Array of path Strings, from high to low, of paths to top-level module directories. ### The "paths" property must not exist in "sandbox" (a secured module system). ### The "paths" attribute must be referentially identical in all modules. ### Replacing the "paths" object with an alternate object may have no effect. ### If the "paths" attribute exists, in-place modification of the contents of "paths" must be reflected by corresponding module search behavior. ### If the "paths" attribute exists, it may not be an exhaustive list of search paths, as the loader may internally look in other locations before or after the mentioned paths. ### If the "paths" attribute exists, it is the loader's prorogative to resolve, normalize, or canonicalize the paths provided. === Module Context === # In a module, there is a free variable "require", which conforms to the above definiton. # In a module, there is a free variable called "exports", that is an object that the module may add its API to as it executes. ## modules must use the "exports" object as the only means of exporting. # In a module, there must be a free variable "module", that is an Object. ## The "module" object must have a "id" property that is the top-level "id" of the module. The "id" property must be such that <tt>require(module.id)</tt> will return the exports object from which the <tt>module.id</tt> originated. (That is to say module.id can be passed to another module, and requiring that must return the original module). When feasible this property should be read-only, don't delete. ## The "module" object may have a "uri" String that is the fully-qualified URI to the resource from which the module was created. The "uri" property must not exist in a sandbox. === Module Identifiers === # A module identifier is a String of "terms" delimited by forward slashes. # A term must be a camelCase identifier, ".", or "..". # Module identifiers may not have file-name extensions like ".js". # Module identifiers may be "relative" or "top-level". A module identifier is "relative" if the first term is "." or "..". # Top-level identifiers are resolved off the conceptual module name space root. # Relative identifiers are resolved relative to the identifier of the module in which "require" is written and called. === Unspecified === This specification leaves the following important points of interoperability unspecified: # Whether modules are stored with a database, file system, or factory functions, or are interchangeable with link libraries. # Whether a PATH is supported by the module loader for resolving module identifiers. == Unit Tests == * [http://github.com/commonjs/commonjs/tree/master/tests/modules Unit tests on CommonJS Github Repository] == Sample Code == ;math.js: <source> exports.add = function() { var sum = 0, i = 0, args = arguments, l = args.length; while (i < l) { sum += args[i++]; } return sum; }; </source> ;increment.js: <source> var add = require('math').add; exports.increment = function(val) { return add(val, 1); }; </source> ;program.js: <source> var inc = require('increment').increment; var a = 1; inc(a); // 2 module.id == "program"; </source> == Notes == * [[Modules/Secure|Secure Modules]] * [[Modules/Natives|How Modules relate to global natives like String]] * [[Modules/Natives|How do you extend native prototypes from a Module?]] * [[Modules/CompiledModules|Notes on compiling modules for browsers]] * [[Modules/ScriptModules|On writing modules that also work as <script>s]] == Related Documents == * Proposal to ECMA TC39: [http://docs.google.com/Doc?id=dfgxb7gk_34gpk37z9v&hl=en Module System for ES-Harmony] * Presentation to ECMA TC39: [http://docs.google.com/Presentation?docid=dcd8d5dk_0cs639jg8&hl=en Modules] == Related Discussion == * [http://groups.google.com/group/commonjs/browse_thread/thread/6ad5c2c3b005cb3b/5a0f17e43d347673 RFC require.paths behaviour] * [http://groups.google.com/group/commonjs/browse_thread/thread/c3682135d72b1f8 Module meta data Proposal.] (resurrection of this discussion) * [http://groups.google.com/group/commonjs/browse_thread/thread/6e6eeb9b3d2990f1 require.main === undefined Options] * [http://groups.google.com/group/commonjs/browse_thread/thread/0f9e8fc585211f6a Modules 1.1 Comments] * [http://groups.google.com/group/commonjs/browse_thread/thread/2f6c87b65e30fb71 Modules/1.1.1 Show of Hands] 489 2847 2010-07-10T18:23:35Z KrisKowal 6 Expliciated that the "lib" property is a subproperty of the "directories" mapping. {{Spec |status=draft }} == Packages == This specification describes the CommonJS package format for distributing CommonJS programs and libraries. A CommonJS package is a cohesive wrapping of a collection of modules, code and other assets into a single form. It provides the basis for convenient delivery, installation and management of CommonJS components. This specifies the CommonJS package descriptor file and package file format. It does not specify a package catalogue file or format; this is an exercise for future specifications. The package descriptor file is a statement of known fact at the time the package is published and may not be modified without publishing a new release. == Package Descriptor File == Each package must provide a top-level package descriptor file called "package.json". This file is a JSON format file. Each package must provide all the following fields in its package descriptor file. * name - the name of the package. This must be a unique, lowercase alpha-numeric name without spaces. It may include "." or "_" or "-" characters. It is otherwise opaque. * version - a version string conforming to the Semantic Versioning requirements (http://semver.org/). One of the following must also be in the package description file in order for it to be valid. * main - module that must be loaded when require(name) is called. Definition must be relative to the package description file. * directories.lib - directory of modules to be loaded under the packages namespace. require(name/subfilename) must return modules from this directory. Definition must be relative to the package description file. Optional Keywords * maintainers - Array of maintainers of the package. Each maintainer is a hash which must have a "name" property and may optionally provide "email" and "web" properties. For example: "maintainers":[ { "name": "Bill Bloggs", "email": "billblogs@bblogmedia.com", " web": "http://www.bblogmedia.com", }] * description - a brief description of the package. By convention, the first sentence (up to the first ". ") should be usable as a package title in listings. * licenses - array of licenses under which the package is provided. '''This property is not legally binding and does not necessarily mean your package is licensed under the terms you define in this property.''' Each license is a hash with a "type" property specifying the type of license and a url property linking to the actual text. If the license is one of the [http://www.opensource.org/licenses/alphabetical official open source licenses] the official license name or its abbreviation may be explicated with the "type" property. If an abbreviation is provided (in parentheses), the abbreviation must be used. "licenses": [ { "type": "GPLv2", "url": "http://www.example.com/licenses/gpl.html", } ] * "bugs" - URL for submitting bugs. Can be mailto or http. * "keywords" - an Array of string keywords to assist users searching for the package in catalogs. * "repositories" - Array of repositories where the package can be located. Each repository is a hash with properties for the "type" and "url" location of the repository to clone/checkout the package. A "path" property may also be specified to locate the package in the repository if it does not reside at the root. For example: "repositories": [ { "type": "git", "url": "http://github.com/example.git", "path": "packages/mypackage" } ] * "contributors" - an Array of hashes each containing the details of a contributor. Format is the same as for maintainer. By convention, the first contributor is the original author of the package. * "dependencies" - Hash of prerequisite packages on which this package depends in order to install and run. Each dependency defines the lowest compatible MAJOR[.MINOR[.PATCH]] dependency versions (only one per MAJOR version) with which the package has been tested and is assured to work. The version may be a simple version string (see the version property for acceptable forms), or it may be a hash group of dependencies which define a set of options, any one of which satisfies the dependency. The ordering of the group is significant and earlier entries have higher priority. For example: "dependencies": { "webkit": "1.2", "ssl": { "gnutls": ["1.0", "2.0"], "openssl": "0.9.8", }, } * "homepage" - URL string for the package web site * "os" - Array of supported operating systems. If absent or set to the empty set, the package makes no platform assumptions. The set of valid os names includes: aix, freebsd, linux, macos, solaris, vxworks, windows. * "cpu" - Array of supported CPU architectures. If absent or set to the empty set, the package makes no platform assumptions. The set of valid cpu names includes: arm, mips, ppc, sparc, x86, x86_64. * "engine" - Array of supported JavaScript engines. If absent or set to the empty set, the package makes no platform assumptions. The set of valid engine names includes: ejs, flusspferd, gpsee, jsc, spidermonkey, narwhal, node, rhino, v8. * "builtin"- Boolean value indicating the package is built in as a standard component of the underlying platform * directories - Object hash of package directories. Typical directories include "lib", "src", "doc", "jars", "test" and "bin". Package manager tools must use these directory definitions to find various package components. * implements - Array of relevant CommonJS specifications this package supports. A specification identifier is the WikiName of the specification prefixed by "CommonJS/". Arbitrary URLs may also be specified to indicate support for externally published specifications. "implements": [ "CommonJS/Modules/1.0", "CommonJS/JSGI/1.0"] * scripts - Object hash of scripts used in managing the package. A package manager tool may use these scripts to install, build, test or uninstall the package. For example: "scripts": { "install": "install.js", "uninstall": "uninstall.js", "build": "build.js", "doc": "make-doc.js", "test": "test.js", } * overlay - Object hash of identifiers for conditional replacements of top level properties. For example: "overlay": { "node" : {"dependencies":[...]}, "npm" : {"scripts":{"install":"./npm-install.sh"} } Package managers and loaders should ignore unknown fields in the package descriptor file. == Reserved Properties == The following fields are reserved for future expansion: build, default, email, external, files, imports, maintainer, paths, platform, require, summary, test, using, downloads, uid. Extensions to the package descriptor specification should strive to avoid collisions for future standard names by name spacing their properties with innocuous names that do not have meanings relevant to general package management. The following fields are reserved for package registries to use at their discretion: id, type. All properties beginning with _ or $ are also reserved for package registries to use that their discretion. == Catalog Properties == When a package.json is included in a catalog of packages, the following fields should be present for each package. * checksums - Hash of package checksums. This checksum is used by package manager tools to verify the integrity of a package. For example: checksums: {"md5": "841959b03e98c92d938cdeade9e0784d"} == Package File Format == The package files shall be a simple archive of the package directory including the package.json file in a relative, ZIP archive format (Though this format may change in future revisions of this specification). The archive must have a single top level directory. == Package Directory Layout == A CommonJS package will observe the following: * A package.json file must be in the top level directory * Binary files should be in the "bin" directory, * Javascript code should be under the "lib" directory * Documentation should be under the "doc" directory * Unit tests should be under the "test" directory == Package Files == To install and uninstall a CommonJS package some local installation steps may be required. A package may specify various scripts to run via the "scripts" package.json field. == Other Requirements == * All modules contained in packages must conform to the CommonJS Securable Modules specification. == Minimal Example Package Descriptor File == { "name" : "mypackage", "version" : "0.7.0", "main" : "./lib/main", } == Large Example Package Descriptor File == { "name": "mypackage", "version": "0.7.0", "description": "Sample package for CommonJS. This package demonstrates the required elements of a CommonJS package.", "keywords": [ "package", "example" ], "maintainers": [ { "name": "Bill Smith", "email": "bills@example.com", "web": "http://www.example.com" } ], "contributors": [ { "name": "Mary Brown", "email": "maryb@embedthis.com", "web": "http://www.embedthis.com" } ], "bugs": { "mail": "dev@example.com", "web": "http://www.example.com/bugs" }, "licenses": [ { "type": "GPLv2", "url": "http://www.example.org/licenses/gpl.html" } ], "repositories": [ { "type": "git", "url": "http://hg.example.com/mypackage.git" } ], "dependencies": { "webkit": "1.2", "ssl": { "gnutls": ["1.0", "2.0"], "openssl": "0.9.8" } }, "implements": ["cjs-module-0.3", "cjs-jsgi-0.1"], "os": ["linux", "macos", "win"], "cpu": ["x86", "ppc", "x86_64"], "engines": ["v8", "ejs", "node", "rhino"], "scripts": { "install": "install.js", "uninstall": "uninstall.js", "build": "build.js", "test": "test.js" }, "directories": { "lib": "src/lib", "bin": "local/binaries", "jars": "java" } } == Editor Macros/Scripts == Remembering the format and typing the common bits can be boring. So listed below are know editor scripts to make this easier: * [http://gist.github.com/311512 commonjs-package-json.vim] written by Ashb. == Background == * [[Packages-Background]] (discussion) * [http://groups.google.com/group/commonjs/browse_thread/thread/9f73afe65dc33df7 modules packaging] * [http://semver.org/ Semantic Versioning] * [http://github.com/280north/narwhal/blob/master/docs/packages-howto.md How to make packages in Narwhal] == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/a1abe3ffb7203ef4 Packages 1.1 version range definitions] * [http://groups.google.com/group/commonjs/browse_thread/thread/9d714a00f5591efb Packages 1.1 Draft] * [http://groups.google.com/group/commonjs/browse_thread/thread/ca0e9da69a33b519 Transport & Packages] * [http://groups.google.com/group/commonjs/browse_thread/thread/c70af7ad188d6082 Packages 1.0 Comments] 490 2510 2010-03-24T22:06:19Z KrisKowal 6 moved [[Modules/1.2]] to [[Modules/1.1.1]] #REDIRECT [[Modules/1.1.1]] 491 2550 2010-04-01T20:49:13Z Dantman 1 *sigh* This needs a language. {{Implementation |name=CouchDB |url=http://couchdb.apache.org/ |engines=SpiderMonkey |authors=Mikeal }} 492 2780 2010-05-23T23:38:24Z KrisKowal 6 {{Spec |status=proposal |standard=no |implementations=Narwhal=0.5 }} == Specification == # A promise is an opaque object: ## How to send messages to a promise object is beyond the scope of this specification. ## How to detect whether a value is a promise object is beyond the scope of this specification. ## These behaviors are an exercise left to implementors. ## Users of promises must not depend on any particular implementation's behavior. The "promise" (provisionally "promise-b") module exports the following API: ; when(object, callback, errback_opt) # Arranges for callback to be called: ## with the fully resolved value of the given object ## in a future turn of the event loop ## if and when the object is or becomes a fully resolved value accessible to the caller. # Arranges for errback to be called: ## with a value representing the reason why the object will never be fully resolved ## in a future turn of the event loop ## if the object is a promise and ## if that promise is resolved with a rejection ("reject"). # Returns a promise that may be eventually resolved with the value returned by either the callback or the errback. # The object may be any value. # If the object is a promise, sends a "when" message to that promise with a callback and an errback that intercept the resolution of that promise and resolve the promise returned by "when": ## with the value received by the callback ## or with a rejection ("reject") with the reason given to the errback. # Callback must not be called before when returns. # Errback must not be called before when returns. # Callback must only be called once. # Errback must only be called once. # If callback is called, errback must never be called. # If errback is called, callback must never be called. # "when" does not guarantee that callback or errback will ever be called. ; asap(object, callback, errback_opt) # Arranges for callback to be called with the fully resolved value of the given object when the object is or becomes a fully resolved value accessible to the caller. # The object may be any value. # If the object is a promise, "asap" sends a "when" message to that promise with a callback and an errback that intercept the resolution of that promise and resolve the promise returned by "asap": ## with the value given to the callback ## or with a rejection ("reject") with the reason given to the errback. # If the object is not a promise, "asap" must call the callback immediately. ## If the callback does not return a promise, "asap" returns the value returned by "callback". ## If the callback returns a promise, "asap" sends a a "when" message to that promise with a callback and errback that intercept the resolution of that promise and resolve the promise returned by "asap": ### with the value given to the callback ### or with a rejection ("reject") with the reason given to the errback. # "asap" does not guarantee that callback or errback will ever be called. # Callback must only be called once. # Errback must only be called once. # If callback is called, errback must never be called. # If errback is called, callback must never be called. # Callback and errback may never be called. ; enqueue(task Function) # causes a function to be called as soon as possible in a future turn. ; get(object, name) # Returns a promise for a property of the given object. ; post(object, name, args) # Returns a promise for the return value of calling a member function of the given object with the given arguments. # <code>args</code> are not variadic. ; put(object, name, value) # returns a promise to set the value of a named property of the object and to forward the value when that has been completed. ; del(object, name) # Returns a promise to delete the named property of the object and to forward <code>undefined</code> when that has been completed. ; Promise(descriptor Object, fallback Function) # Returns a Promise object # Must be callable as a function # May be instantiable as a constructor # Accepts a descriptor Object that maps message names to handler functions, particularly: ## when(errback) ## get(name) ## put(name, value) ## post(name, args) ## del(name) # Each of the above handler functions must <em>return</em> a more resolved object or promise. # Accepts a fallback(message, ...args) function that receives all messages that are not handled by the promise descriptor. # Returns a promise object. ; defer() # Returns an Object with a "resolve(object)" property function, and a "promise" object. # The first time that "resolve(object)" is called, the state of the "promise" advances to "resolved" and all previous and future promises observing the "promise" are resolved. ## If the "object" is not a promise, the resolved value of the "promise" becomes a reference ("ref") to the given object. # All subsequent calls to resolve must be silently ignored. ; reject(reason String) # Returns a rejected promise with the given reason. # A rejected promise handles the "when(errback)" message in one of two ways: ## If an errback is provided, the errback is called with the reason as its argument, and the "when" message handler must return the value returned by the errback. ## If no errback is provided, the "when" message handler must return a new rejection ("reject") with the same reason. # Rejects all other messages. ; ref(object) # If object is a promise, returns that promise. # If the object is not a promise, returns a resolved promise that handles the following messages: ## when(errback) ignores the errback and forwards the resolved object. ## get(name) forwards the named property of the resolved object. ## put(name, value) sets the named property to the given value of the resolved object and forwards the value. ## del(name) deletes the named property of the resolved object and forwards <code>undefined</code> ## post(name, args) calls the named method of the object and forwards the returned value. ## all other messages forward a rejection ("reject") with the reason "Promise does not handle NAME" where NAME is the name of the message. ; isPromise(object) Boolean : returns whether the given object is a promise. ; method(name String) # returns a function like "get", "put", "del", and "post" except with the given name that must forward a message to a promise in a future turn. ; defined(object) # Returns a promise that the given object, when resolved, will not be <code>null</code> or <code>undefined</code>. 493 2724 2010-04-22T00:41:22Z KrisKowal 6 Replaced content with '*redacted*' *redacted* 494 2578 2010-04-07T06:44:14Z Konobi 105 {{Implementation |name=Smart Platform |url=http://github.com/joyent/smart-platform/ |engines=SpiderMonkey/C |authors=Konobi, Joyent }} 495 2810 2010-05-27T12:01:21Z Alexandre.Morgaut 33 /* Constructor: XMLHttpRequest(settings) */ {{Spec |status=discussed, some implementations |implementations=Wakanda }} Proposal B, Draft 1 '''Status: Proposal''' An HTTP Client module which might be called "xhr" exposes an XMLHttpRequest constructor that creates an xhr object. It is designed to be useable with Object.create() == Introduction == The purpose to this proposal is to provide an interface which would be: * compatible with lot of existing JavaScript libraries and scripts * very easy to learn because : ** mostly already known ** already described in lot of JavaScript, Ajax, and Web books and Web sites ** already documented as W3C recommendations ([http://www.w3.org/TR/XMLHttpRequest/ XMLHttpRequest] & [http://www.w3.org/TR/XMLHttpRequest2/ XMLHttpRequest Level 2]) "XML" in "XMLHttpRequest" is only used for historical compatibility. An alias could be "HttpRequest". The main difference between XMLHttpRequest and HttpRequest would then be the value returned by the toString() method. For better user experience while using this API, It would be recommended: * to be abble to set default values of the open() method as settings * to let the constructor return an instance without the "new" operator * to allow chaining Example of intuitive use: <pre> var HttpRequest = require("xhr").XMLHttpRequest; var settings = HttpRequest.defaultSettings; var cookies = {}; // these are some proposed setting properties settings.async = false; settings.cookies = cookies; settings.host = "http://www.foo.com/"; var client = HttpRequest(); // as these requests are synchronous, open() doesn't abort previous send() var txt = client.open("GET", "license.txt").send().responseText; var obj = client.open("GET", "data.json").send().responseObject; var doc = client.open("GET", "doc.html").send().responseXML; var img = client.open("GET", "img.jpg").send().responseBody; ... // be aware that obj and doc may be set to null if the requests failed </pre> NOTE: the upload property and the XMLHttpRequestUpload, as primarly used for DOM elements, are not defined in this proposal. It may be defined if an implementation wants to set upload progress properties to a server component (like a folder). == Constructor: XMLHttpRequest(settings) == If called as a simple function, then return a new XMLHttpRequest(settings). The settings parameter can be an object or undefined * The settings parameter can have a "custom" property which is an object. ** Each implementor may define its own plate-form dependent object to carry its own specific settings * Some standard setting properties may be defined later once a consensus is done regarding settings defined in plate-form dependent objects Some suggested setting properties are: * <code>acceptType</code>: String. Default: "*/*" * <code>async</code>: Boolean. Default: true * <code>authType</code>: String. Default: "Basic" * <code>body</code>: String, ByteArray, Document, Object, or null. Default: null * <code>contentCharset</code>: String or null. Default: null * <code>contentType</code>: String or null. Default: null * <code>cookies</code> * <code>dom</code>: Object or null. Provide the Document and/or HTMLDocument constructors in an object if available * <code>headers</code>: String or null * <code>host</code>: String or null. Would be used as the base URL * <code>jsonHandler</code>: Function or null. Used by JSON.parse for responseObject * <code>keepAlive</code>: String or null. Default: "115" * <code>maxRedirects</code>: Number or null * <code>proxy</code>: String, Location, or null. * <code>timeout</code>: Number. * <code>user</code>: String or null * <code>password</code>: String or null These ones would break the standard minimal open() signature: * <code>method</code>: String or null. * <code>url</code> * <code>location</code>: a BOM like Location object Another constructor named HttpRequest, with the same properties and behaviors could also be available. == Constructor properties == === prototype === The constructor has a prototype property described as bellow == Prototype Read Only properties == === UNSENT === Read-Only. Its value is the number 0. This represent the original value of the <code>[[#readyState]]</code> property of <code>XMLHttpRequest</code> instances. === OPENED === Read-Only. Its value is the number 1. This represent the value of the <code>[[#readyState]]</code> property of <code>XMLHttpRequest</code> instances once its <code>[[#open()]]</code> method has been successfully invoked. When an instance is in this state, the <code>[[#setRequestHeader()]]</code> method can be used to fix HTTP header field values. === HEADERS_RECEIVED === Read-Only. Its value is the number 2. This represent the value of the <code>[[#readyState]]</code> property of <code>XMLHttpRequest</code> instances once all HTTP headers have been received. When an instance is in this state, the informations returned by these properties and methods are reliable: Properties * <code>[[#status]]</code> * <code>[[#statusText]]</code> Methods * <code>[[#getResponseHeader()]]</code> * <code>[[#getAllResponseHeaders()]]</code> Some scripts may wait this state when an <code>Expect: 101-continue</code> header were set in the request to send big content or chuncked data. === LOADING === Read-Only. Its value is the number 3. This represent the value of the <code>[[#readyState]]</code> property of <code>XMLHttpRequest</code> instances once the HTTP body started to be received. This state is interesting to read a response while it is being received. It would be useful but requires the support of <code>[[#responseStream]]</code> and/or <code>[[#responseTextStream]]</code> properties === DONE === Read-Only. Its value is the number 4. This represent the value of the <code>[[#readyState]]</code> property of <code>XMLHttpRequest</code> instances once the HTTP body is fully received. === defaultSettings === The constructor MAY have a defaultSettings object property which properties would be Read-Write and accept the same settings as the ones defined for the constructor. Any setting fixed in this constructor property is used by all future instances if not overridden by a different value fixed in the constructor parameter. == Prototype Event Handler properties == Quite all Client-Side JavaScript libraries are based on asynchronous requests. When implementing XMLHttpRequest on server-side, the implementor can either: * support asynchronous execution * simulated asynchronous execution, blocking the execution and calling the handlers each time the state of the request change === onreadystatechange === A <code>onreadystatechange</code> event handler attribute handling the <code>readystatechange</code> event MUST be supported. The handler is called each time the value of the [[#readyState]] constructor property change. == Prototype properties == === constructor === Read-Only. The <code>[[#prototype]]</code> property SHOULD have a <code>constructor</code> property which default value is the <code>XMLHttpRequest</code> constructor. If an <code>HttpRequest</code> constructor is provided as well, its prototype should have a constructor set to <code>HttpRequest</code>. === timeout === Read-Write. The amount of milliseconds a request can take before being terminated. By default this is 0 and has no observable effect. On setting the <code>timeout</code> property these steps must be run: # If the state is not [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <code>send()</code> flag is true raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # Set <var>request timeout</var> to the given value. On getting, the <code>timeout</code> property must return the value of the <var>request timeout</var>. ([http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#the-timeout-attribute from XMLHttpRequest Level 2 W3C Editor's Working Draft]) === readyState === Read-Only. Its default value is 0 ([[#UNSENT]]). This instance property value is changed automatically to 1 ([[#OPENED]]), 2 ([[#HEADERS_RECEIVED]]), 3 ([[#LOADING]]), and 4 ([[#DONE]]). These changes can be handled by function set to the [[#onreadystatechange]] property. === withCredentials === Read-Write. Boolean. The default value is false. The <code>withCredentials</code> property controls the <var>credentials</var> flag which indicates whether a cross-origin request will include cookie and HTTP authentication data and whether cookies can be set. It should be supported/simulated for compatibility with client libraries On getting, the <code>withCredentials</code> attribute must return the value of the <var>credentials</var> flag. This property can be set once <code>[[#open()]]</code> has been called, until <code>[[#send()]]</code> is called. When the <code>withCredentials</code> property is set, the implementation MUST run these steps: # If the state is not [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>send()</var> flag is true raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the given value is true, set the <var>credentials</var> flag to true. For any other value, set the <var>credentials</var> flag to false. === status === Read-Only. Number. The <code>status</code> property must return the result of running these steps: # If the state is [[#UNSENT]] or [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>error</var> flag is true return 0 and terminate these steps. # Return the HTTP status code. === statusText === Read-Only. String. The <code>statusText</code> property must return the result of running these steps: # If the state is [[#UNSENT]] or [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>error</var> flag is true return the empty string and terminate these steps. # Return the HTTP status text. === responseBody === Read-Only. ByteArray | null. The <code>responseBody</code> property, on getting, must return the result of running the following steps: # If the state is not [[#LOADING]] or [[#DONE]] return <code>null</code> and terminate these steps. # Return a <code>ByteArray</code> object representing the response entity body or return <code>null</code> if the response entity body is null. === responseText === Read-Only. String. It's default value is the empty string. The <code>responseText</code> property, on getting, must return the result of running the following steps: # If the state is not [[#LOADING]] or [[#DONE]], return the empty string and terminate these steps. # Return the text response entity body. === responseXML === Read-Only. Document | null. It's default value is null. The <code>responseXML</code> property has XML in its name for historical reasons. It also returns documents created using an HTML parser. The <code>responseXML</code> property, on getting, must return the result of running the following steps: # '''If DOM is not implemented and no Document nor HTMLDocument constructors have been provided, return <code>null</code> and terminate these steps.''' # If the state is not [[#DONE]], return <code>null</code> and terminate these steps. # If the response entity body is null, return <code>null</code> and terminate these steps. # If final MIME type is not null, <code>text/html</code>, <code>text/xml</code>, <code>application/xml</code>, and does not end in <code>+xml</code>, return <code>null</code> and terminate these steps. # If final MIME type is <code>text/html</code> or <code>application/xhtml+xml</code>, let <var>document</var> be an object implementing the <code>HTMLDocument</code> interface that represents the response entity body parsed following the rules set forth in the HTML specification for an HTML parser with scripting disabled and then terminate this algorithm. # Otherwise, let <var>document</var> be an object implementing the <code>Document</code> interface that represents the result of parsing the response entity body into a document tree following the rules from the XML specifications. If this fails (unsupported character encoding, namespace well-formedness error et cetera), return <code>null</code> and terminate these steps. # Return <var>document</var>. === responseObject === Read-Only. Object | null. It's default value is null. The <code>responseObject</code> property, on getting, must return the result of running the following steps: # If the state is not [[#DONE]], return <code>null</code> and terminate these steps. # If the response entity body is null, return <code>null</code> and terminate these steps. # If final MIME type is not null, <code>text/json</code>, <code>application/json</code>, <code>application/json-rpc</code>, <code>application/jsonrequest</code> and does not end in <code>+json</code>, return <code>null</code> and terminate these steps. # Otherwise, let <var>object</var> be the result of a JSON parse on the response entity body following the rules from the JSON specification. If this fails, return <code>null</code> and terminate these steps. # Return the resulting Object. === responseStream === Read-Only. Reserved for a binary Stream object === responseTextStream === Read-Only. Reserved for a text Stream object === upload === Read-Only This property should return null if <code>XMLHttpRequestUpload</code> is not supported == Prototype methods == === open() === <code>open(method:String, url:String[, async:Boolean[, user:String[, password:String]]])</code> Parameters description: * <var>method</var>: The method used in the request (ex: "POST", "GET", "PUT", ...) * <var>url</var>: The URL used in the request (ex: "http://wiki.commonjs.org/") * <var>async</var>: A flag that is either true or false that indicates whether the request is done asynchronously (default: true) * <var>user</var>: The username used in the request (default: null) * <var>password</var>: The password used in the request (default: null) When the open(method, url, async, user, password) method is invoked, the implementation must run these steps (unless otherwise indicated): # If method is not a valid token as defined in RFC 2616 section 5.1.1, raise a [[#SYNTAX_ERR]] exception and terminate these steps. # If method is an ASCII case-insensitive match for <code>CONNECT</code>, <code>DELETE</code>, <code>GET</code>, <code>HEAD</code>, <code>OPTIONS</code>, <code>POST</code>, <code>PUT</code>, <code>TRACE</code>, or <code>TRACK</code>, convert <var>method</var> to ASCII uppercase. <div><em>If it does not match any of the above, it is passed through literally, including in the final request.</em></div> # Let <var>url</var> be a URL and its character encoding be UTF-8. # If the implementation is an HTTP server, it MAY resolve relative URLs to its host (or virtual host) hostname setting. <div><em>If the algorithm returns an error, raise a [[#SYNTAX_ERR]] exception and terminate these steps.</em></div> # Drop <fragment> from <var>url</var> (servers don't expect to receive a fragment like "#here" in URLs) # If <var>url</var> contains an unsupported <scheme> (like "ftp://") raise a [[#NOT_SUPPORTED_ERR]] and terminate these steps. # If the "user:password" format is not supported for the relevant scheme and url contains this format raise a [[#SYNTAX_ERR]] and terminate these steps. # If <var>url</var> contains the "user:password" format let <var>temp user</var> be the user part and <var>temp password</var> be the password part. # If <var>url</var> just contains the "user" format let temp user be the user part. # Let <var>async</var> be the value of the <var>async</var> argument # If the <var>user</var> argument was not omitted follow these sub steps: <div><em>These steps override anything that may have been set by the <var>url</var> argument (<var>user</var> parameter of the <code>[[#open()]]</code> method override the potential one defined in the URL)</em></div> ## If the syntax of <var>user</var> does not match the syntax specified by the relevant authentication scheme, raise a [[#SYNTAX_ERR]] exception and terminate the overall set of steps. ## If <var>user</var> is null let <var>temp user</var> be null. ## Otherwise let <var>temp user</var> be <var>user</var>. # If the <var>password</var> argument was not omitted follow these sub steps:<div><em>These steps override anything that may have been set by the <var>url</var> argument (<var>password</var> parameter of the <code>[[#open()]]</code> method override the potential one defined in the URL) </em></div> ## If the syntax of <var>password</var> does not match the syntax specified by the relevant authentication scheme, raise a [[#SYNTAX_ERR]] exception and terminate the overall set of steps. ## If <var>password</var> is null let <var>temp password</var> be null. ## Otherwise let <var>temp password</var> be <var>password</var>. # Abort the <code>[[#send()]]</code> algorithm (if <code>[[#send()]]</code> was called before this <code>[[#open()]]</code> invocation) # The implementation should cancel any network activity for which the object is responsible. # Set variables associated with the object as follows: ## Set the <var>send()</var> flag to false. ## Set <var>response entity body</var> to null. ## Empty the list of author request headers. ## Set the <var>request method</var> to <var>method</var>. ## Set the <var>request URL</var> to <var>url</var>. ## Set the <var>request username</var> to <var>temp user</var>. ## Set the <var>request password</var> to <var>temp password</var>. ## Set the <var>asynchronous</var> flag to true if <var>async</var> is true. Otherwise set it to false. # Switch the the state to [[#OPENED]] # Dispatch a <code>readystatechange</code> event === setRequestHeader() === <code>setRequestHeader(header:String, value:String)</code> As indicated in the algorithm below certain headers cannot be set and are left up to the implementation. In addition there are certain other headers the implementation will take control of if they are not set by the author as indicated at the end of the <code>[[#send()]]</code> method section. The <code>setRequestHeader()</code> method appends a value if the HTTP header given as argument is already part of the author request headers list. When the <code>setRequestHeader(header, value)</code> method is invoked, the implementation must run these steps (unless otherwise indicated): # If the state is not [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>send()</var> flag is true raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>header</var> argument does not match a valid field-name syntax (section 4.2 of RFC 2616) raise a [[#SYNTAX_ERR]] exception and terminate these steps. # If the <var>value</var> argument does not match a valid field-value syntax (section 4.2 of RFC 2616) raise a [[#SYNTAX_ERR]] exception and terminate these steps. (The empty string is legal and represents the empty header value) # The following headers are not allowed to be set as they are better controlled by the implementation as it knows best what value they should have. Header names starting with <code>Sec-</code> are not allowed to be set to allow new headers to be minted in the future that are guaranteed not to come from <code>XMLHttpRequest</code>. If <var>header</var> is an ASCII case-insensitive match for one of the following headers, or if the start of <var>header</var> is an ASCII case-insensitive match for <code>Sec-</code> (including when <var>header</var> is just <code>Sec-</code>), raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. ## <code>Accept-Encoding</code> (it is implementation specific) ## <code>Connection</code> (it is generated by the <code>[[#send()]]</code> method, should be customizable via a keepAlive setting) ## <code>Content-Length</code> (it is fixed by from the length of the data parameter of the <code>[[#send()]]</code> method) ## <code>Content-Transfer-Encoding</code> (it is generated by the <code>[[#send()]]</code> method) ## <code>Host</code> (it is fixed by from URL parameter of the <code>[[#open()]]</code> method) ## <code>Keep-Alive</code> (it is generated by the <code>[[#send()]]</code> method, should be customizable via a keepAlive setting) ## <code>TE</code> (it is generated by the <code>[[#send()]]</code> method) ## <code>Transfer-Encoding</code> (it is generated by the <code>[[#send()]]</code> method) ## <code>Upgrade</code> # If <var>header</var> is not in the author request headers list append <var>header</var> with its associated <var>value</var> to the list and return the XMLHttpRequest instance. # If <var>header</var> is in the author request headers list either use multiple headers, combine the values or use a combination of those (section 4.2, RFC 2616) # Return the XMLHttpRequest instance to provide chaining See also the <code>[[#send()]]</code> method regarding implementation header handling for caching, authentication, proxies, and cookies. The following script: <pre> var client = new XMLHttpRequest(); client.open('GET', 'demo.cgi'); client.setRequestHeader('X-Test', 'one'); client.setRequestHeader('X-Test', 'two'); client.send(); </pre> Would result in the following header being sent: <pre> ... X-Test: one, two ... </pre> === send() === <code>send([data:(Document|String|ByteArray|Object)[, complete:Boolean]])</code> The send(data, complete) method initiates the request Arguments description: * data: entity body for the request (default: null) * complete: If false, the request's body is chunked and will be complete only once <code>[[#send()]]</code> is called with complete set to true (default: true) Authors are encouraged to ensure that they have specified the Content-Type header via <code>[[#setRequestHeader()]]</code> before invoking <code>[[#send()]]</code> with a non-null data argument. When invoked, the implementation must run these steps (unless otherwise noted). This algorithm might get aborted if the <code>[[#open()]]</code> or <code>[[#abort()]]</code> method is invoked. When the <code>[[#send()]]</code> algorithm is aborted the user agent must terminate the algorithm after finishing the step it is on. The <code>[[#send()]]</code> algorithm can only be aborted when async is true (i.e., the request is done asynchronously) and only after the method call has returned. # If the state is not [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>send()</var> flag is true raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If stored method is <code>GET</code>, <code>HEAD</code>, or <code>TRACE</code>, act as if the <var>data</var> argument is null. # If the <var>data</var> argument has not been omitted and is not null use it for the entity body observing the following rules: ## <var>data</var> is a <code>ByteArray</code>: This will be done in terms of the File API in due course. Use data literally for transmission. ## <var>data</var> is a String: ### if a <var>charset</var> is defined in the <code>Content-Type</code> header field: Encode <var>data</var> using it for transmission, otherwise, encode data using UTF-8 for transmission. ## <var>data</var> is a <code>Document</code> (meaning DOM is supported): ### Let <var>tempdata</var> be the result of getting the innerHTML attribute on the <var>data</var> object and encode it using <code>data.inputEncoding</code> or UTF-8 if <code>data.inputEncoding</code> is null. Re-raise any exception this raises. ### If the document cannot be serialized an [[#INVALID_STATE_ERR]] exception is raised. ### Let <var>data</var> be <var>tempdata</var>. ### If no <code>Content-Type</code> header has been set using <code>[[#setRequestHeader()]]</code> set a <code>Content-Type</code> request header with a value of <code>application/xml;charset=charset</code> where <code>charset</code> is the encoding used to encode the document. ### Subsequent changes to the document have no effect on what is submitted. ## <var>data</var> is an Object (neither <code>ByteArray</code> or <code>Document</code>): ### Let <var>tempdata</var> be the result of computing a JSON stringify on the <var>data</var> object and encode it with the charset defined in the <code>Content-Type</code> or UTF-8 if not defined. Re-raise any exception this raises. ### If the object cannot be serialized an [[#INVALID_STATE_ERR]] exception is raised. ### Let <var>data</var> be <var>tempdata</var>. ### If no <code>Content-Type</code> header has been set using <code>[[#setRequestHeader()]]</code> set a <code>Content-Type</code> request header with a value of <code>application/json;charset=UTF-8</code> ### Subsequent changes to the object have no effect on what is submitted. ## If the <var>data</var> argument has been omitted, or is null, no entity body is used in the request. # If the <var>asynchronous</var> flag is false release the storage mutex. # Set the <var>error</var> flag to false. # If the <var>asynchronous</var> flag is true run these substeps: ## '''Set the <var>send()</var> flag to true.''' ## Dispatch a <code>readystatechange</code> event. (The state does not change. The event is dispatched for historical reasons.) ## Return the <code>[[#send()]]</code> method call, but continue running the steps in this algorithm. If request timeout is not 0 and since the request started the amount of milliseconds specified by request timeout has passed before the response is fully received, raise a [[#TIMEOUT_ERR]] exception and terminate these steps. If the implementation allows the end user to configure a proxy it should modify the request appropriately; i.e., connect to the proxy host instead of the origin server, modify the Request-Line and send <code>Proxy-Authorization</code> headers as specified. If the user agent supports HTTP Authentication and Authorization is not in the list of author request headers, it should consider requests originating from the XMLHttpRequest object to be part of the protection space that includes the accessed URIs and send Authorization headers and handle <code>401 Unauthorized</code> response appropriately. If authentication fails the implementation must raise an [[#UNAUTHORIZED_ERR]] exception. If the implementation supports HTTP State Management it should persist, discard and send cookies (as received in the <code>Set-Cookie</code> and <code>Set-Cookie2</code> response headers, and sent in the <code>Cookie</code> header) as applicable. For compatibility with Client-side JavaScript libraries, it is recommended to provide a <code>document</code> object with a <code>cookie</code> property as available in browsers. If the implementation implements a HTTP client cache it should respect <code>Cache-Control</code> request headers set by the <code>[[#setRequestHeader()]]</code> (e.g., <code>Cache-Control: no-cache</code> bypasses the cache). It must not send <code>Cache-Control</code> or <code>Pragma</code> request headers automatically unless the end user explicitly requests such behavior. For <code>304 Not Modified</code> responses that are a result of an implementation generated conditional request the user agent must act as if the server gave a <code>200 OK</code> response with the appropriate content. The implementation must allow <code>[[#setRequestHeader()]]</code> to override automatic cache validation by setting request headers (e.g.,<code>If-None-Match</code>, <code>If-Modified-Since</code>), in which case <code>304 Not Modified</code> responses must be passed through. If the implementations support server-driven content-negotiation it should set <code>Accept-Encoding</code> and <code>Accept-Charset</code> headers as appropriate. Unless set through <code>[[#setRequestHeader()]]</code> implementations should set the <code>Accept</code> and <code>Accept-Language</code> headers as well. Responses must have the content-encodings automatically decoded. Besides the author request headers implementation should not include additional request headers other than those mentioned above or other than those authors are not allowed to set using <code>[[#setRequestHeader()]]</code>. This ensures that authors have a reasonably predictable API. === abort() === When the <code>abort()</code> method is invoked, the implementation must run these steps (unless otherwise noted): # Abort the send() algorithm # The implementation SHOULD cancel any network activity for which the object is responsible. # Set the response entity body to null. # Set the error flag to true. # Empty the list of author request headers. # If the state is [[#UNSENT]], [[#OPENED]] with the <code>send()</code> flag being false, or [[#DONE]] go to the next step. Otherwise run these substeps: ## Switch the state to [[#DONE]]. ## Set the <var>send()</var> flag to false. ## Dispatch a <code>readystatechange</code> event. # Switch the state to [[#UNSENT]]. No <code>readystatechange</code> event is dispatched. === getResponseHeader() === <code>getResponseHeader(header:String)</code> When the getResponseHeader(header) is invoked, the implementation must run these steps: # If the state is [[#UNSENT]] or [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>header</var> argument does not match a valid field-name syntax (section 4.2 of RFC 2616), return null and terminate these steps. # If the <var>error</var> flag is true return null and terminate these steps. # If <var>header</var> is an ASCII case-insensitive match for multiple HTTP response headers, return the values of these headers as a single concatenated string separated from each other by a U+002C COMMA U+0020 SPACE character pair and terminate these steps. # If <var>header</var> is an ASCII case-insensitive match for a single HTTP response header, return the value of that header and terminate these steps. # Return null. // The following script: <pre> var client = new XMLHttpRequest(); client.open("GET", "test.txt", true); client.send(); client.onreadystatechange = function() { if (this.readyState == XMLHttpRequest.HEADERS_RECEIVED) { print(client.getResponseHeader("Content-Type")); } } </pre> // ...should output something similar to the following text: <pre> Content-Type: text/plain; charset=utf-8 </pre> === getAllResponseHeaders() === When the <code>getAllResponseHeaders()</code> method is invoked, the implementation must run the following steps: # If the state is [[#UNSENT]] or [[#OPENED]] raise an [[#INVALID_STATE_ERR]] exception and terminate these steps. # If the <var>error</var> flag is true return the empty string and terminate these steps. # Return all the HTTP headers as a single string, with each header line separated by a U+000D CR U+000A LF pair, and with each header name and header value separated by a U+003A COLON U+0020 SPACE pair. // The following script: <pre> var client = new XMLHttpRequest(); client.open("GET", "test.txt", true); client.send(); client.onreadystatechange = function() { if(this.readyState == XMLHttpRequest.HEADERS_RECEIVED) { print(this.getAllResponseHeaders()); } } </pre> // ...should output something similar to the following text: <pre> Date: Sun, 24 Oct 2004 04:58:38 GMT Server: Apache/1.3.31 (Unix) Keep-Alive: timeout=15, max=99 Connection: Keep-Alive Transfer-Encoding: chunked Content-Type: text/plain; charset=utf-8 </pre> === overrideMimeType() === <code>overrideMimeType(mime:String)</code> When the <code>overrideMimeType(mime)</code> method is invoked, the user implementation run the following steps: # If parsing <var>mime</var> analogously to the value of the <code>Content-Type</code> headers fails raise a [[#SYNTAX_ERR]] exception and abort this algorithm. # If a MIME type (without any parameters) is successfully parsed set override MIME type to that MIME type. # If a <var>charset</var> parameter is successfully parsed set override <var>charset</var> to its value. === toString() === If the constructor is XMLHttpRequest, the returned value must be "[object XMLHttpRequest]". If the constructor is HttpRequest, the returned value must be "[object HttpRequest]". == Exceptions == This API requires to send Exceptions which error code can be defined in DOM. Here are the description of these required Exceptions and their error code value: [http://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-17189187 Exceptions of DOM Level 2 Core] This API requires new Exceptions defined in the W3C Editor's Draft of XMLHttpRequest Level 2 [http://dev.w3.org/2006/webapi/XMLHttpRequest-2/#exceptions Exceptions of the W3C Editor's Draft of XMLHttpRequest Level 2] === NOT_SUPPORTED_ERR === Code value: 9 This is a DOM level 1 error meaning: "The implementation does not support the requested type of object or operation." === INVALID_STATE_ERR === Code value: 11 This is a DOM level 2 error meaning: "An attempt is made to use an object that is not, or is no longer, usable." === SYNTAX_ERR === Code value: 12 This is a DOM level 2 error meaning: "An invalid or illegal string is specified." === TIMEOUT_ERR === Code value: 23 This is a XMLHttpRequest Level 2 error meaning: "The author specified timeout has passed before the request could complete in synchronous requests." This exception will be folded into an update of DOM Level 3 Core in due course, as they are appropriate for other API specifications as well. 496 2771 2010-05-12T13:13:40Z Hannesw 10 ''Draft 1'' This document describes an interface for converting streams of bytes to characters and vice versa. It pays special attention on the requirements of asynchronous streaming where no assumptions can be made about character alignment. The Decoder and Encoder classes also provide convenience methods to attach them to input or output streams for synchonous operation. = Specification = Platforms implementing this specifications provide an '''encoding''' module exporting the classes described below. == Decoder == ==== Constructor ==== ;[new] Decoder(encoding string, [strict boolean], [capacity number]) Decoder :Create a new Decoder instance that will decode bytes to characters using the given encoding. :A decoder encapsulates an character buffer for decoded output, and a binary input buffer for storing partial character input between invocations of decode(). The initial size of the output buffer is set to capacity or a default value if capacity is undefined. All buffers are growable and will be resized as required. :If strict is true, the decoder will throw Errors on illegal input; otherwise, it will silently accept illegal input. ==== Instance Methods ==== ;decode(buffer Binary, [start number], [end number]) Decoder :Try to decode the content of buffer, appending the result to the internal character buffer. If start and end are defined and valid indices for buffer, only the region between start (inclusive) and end (exclusive) are decoded. :If the Decoder was constructed with true as strict argument, this method throws an Error if the input is not valid for the decoder's encoding. :The method returns this decoder for chainability. ;toString() string :Return the content of the internal character buffer as string. This includes all content decoded since the Decoder was created or clear() was invoked on it. ;clear() Decoder :Reset the output buffer, discarding all content decoded so far. This does not reset the input buffer, so any bytes representing a partial character are kept for later invocations of decode(). :The method returns this decoder for chainability. ;hasPendingInput() boolean :Return true if there any bytes representing a partial character in the decoder's internal input buffer, false otherwise. ;close() Decoder :Closes the decoder. The decoder must not be used after close() was invoked. :If the Decoder was constructed in strict mode, this method throws an Error if there are any pending bytes in its input buffer. :The method returns this decoder for chainability. ;readFrom(source Stream) :If this method is invoked, input is read from source which must be a readable stream. ;readLine(includeNewline) string :Return a string containing all decoded characters up to the first line break, or null if no line break was found in the current output buffer. A line break is either "\n", "\r", or "\r\n". If Boolean(includeNewline) is true the line break is included with the return value. :If a source stream was defined using the readFrom method, more bytes are read form the source stream until a line break or EOF is encountered. ==== Instance Properties ==== ;length number :Return the length of the decoded output in character units. This property is not writable. == Encoder == ==== Constructor ==== ;[new] Encoder(encoding string, [strict boolean], [capacity number]) Encoder :Create a new Encoder instance that will encode characters to bytes using the given encoding. :An encoder encapsulates an byte buffer for encoded output. The initial size of the size of the buffer is set to capacity or a default value if capacity is undefined, and will grow to accommodate encoded output as required. :If strict is true, the decoder will throw Errors on illegal input; otherwise, it will silently accept illegal input. ==== Instance Methods ==== ;encode(str string, [start number], [end number]) Encoder :Try to encode the content of str, appending the result to the internal byte buffer. If start and end are defined and valid indices for str, only the region between start (inclusive) and end (exclusive) are decoded. :If the Encoder was constructed with true as strict argument, this method throws an Error if the input is not valid for the decoder's encoding. :The method returns this encoder for chainability. ;toBuffer|ByteArray|ByteString() Buffer|ByteArray|ByteString :Return the content of the internal byte buffer as a binary buffer. This includes all content encoded since the Encoder was created or clear() was invoked on it. ;clear() Encoder :Reset the output buffer, discarding all content encoder so far. :The method returns this decoder for chainability. ;close() Encoder :Closes the encoder. The encoder must not be used after close() was invoked. :If the Decoder was constructed in strict mode, this method throws an Error if the encoder . :The method returns this decoder for chainability. ;writeTo(sink Stream) :If this method is invoked, all output is directly written to the sink which must be a writable stream instead of keeping it in the internal output buffer. ==== Instance Properties ==== ;length number :Return the length of the encoded output in bytes. This property is not writable. = Implementations = An implementation of this proposal is available and used for all text streams [http://github.com/hns/ringojs/blob/master/modules/ringo/encoding.js in RingoJS] 497 2892 2010-09-07T23:02:52Z KrisKowal 6 moved [[Packages/Mappings]] to [[Packages/Mappings/A]]:&#32;This location needs to be an index since there are three other proposals. {{Spec |status=proposal }} == Package Mappings == This specification describes an addition to the CommonJS package format for packages to define how they expect their module namespace to be mapped to referenced modules. This defines a new "mappings" property that how a set of module ids should be mapped to canonical URIs of target modules. This specification does not define how the URI target modules are installed or retrieved, and it does not define how any module ids are resolved outside of the mappings. == Simple Example Package Descriptor File == { "name": "mypackage", "mappings": { "other": "jar:http://github.com/someone/other/zipball/master!/lib/" }, ... } == Package Descriptor File Mappings Property== The "mappings" property may be defined in a package's package.json file and defines the expected translation of module ids for all modules within the package. The "mappings" property value should be an object, where each property represents a mapping. The name of the property indicates the string to use to match module ids for the mapping. Module ids that begin with a "." should never be translated by mappings. The mapping with the longest property in the mappings object that matches should be applied, and subsequent mapping objects may then be ignored. If no mappings are applicable for a module id, then the id should be looked up per the default id lookup scheme. A require statement from a module in this package that uses an id that begins with the name of the property may be translated with this mapping if one of the following certain conditions: * If the module id is identical to the property name and the "to" value (the mapping target) does not end with a slash, the module id should be translated to the resolved "to" value as the URI for the module. * If the module ids starts with the property name followed by slash (/) and the "to" value does not end with a dot (.) followed exclusively by word characters ([a-zA-Z0-9]), then the module id should be translated. If the "to" value does not end with a slash, a slash should be appended. Then the remaining string after the property name and slash should be appended to the resolved "to" value (and slash if needed) as the URI for the module. Finally, the extension (default of ".js") should be appended to create the full URI for the module if the URI does not end with a dot (.) followed exclusively by word characters ([a-zA-Z0-9]). The value of the property may be a string that defines the target of the mapping or may be a mapping object. The meaning of a string value is identical to the "to" property of a mapping object. If the value is an object (a mapping object), it must contain the following properties: * to - This indicates the target id of the translation. The remainder of the string after the part that matches the property name should be appended to the "to" value. The "to" value may be a relative URI, in which case it should be resolved against the location of this package.json file. The mapping object may contain the following optional properties, that are optionally supported by module loaders or package managers: * verify - Provides hash-based verification of the contents of a target archive or file. The value of the "verify" property should be an object with two properties: ** signature - The signature or hash of the target file/archive. ** algorithm - The algorithm to use to compute the signature or hash of the target file/archive. * mirrors - This denotes alternate URLs that can be used to access the target modules. It is recommended that files downloaded from a mirror only be used if the system ensures that all other packages that reference the target modules provide the same mirror URL in their list of mirrors or provide a secure hash that matches the contents of the files downloaded from mirror. This is to protect poisoning the cache for modules with a malicious files from a mirror. * extension - This indicates the extension to append to module ids to create full URIs. This defaults to ".js". == Example Package Descriptor File == { "name": "mypackage", "mappings": { "other": "jar:http://github.com/someone/other/zipball/master!/lib", "favorite": "jar:http://github.com/someone/other/zipball/master!/lib/favorite.js", "foo": { "to": "jar:http://downloads.sourceforge.net/project/foo/foo/rc1/foo-v1.zip!/lib/", "mirrors": [ "jar:http://another-download-site.com/foo-v1.zip!/lib/ ], "verify": { "signature": "c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87", "algorithm": "rsa-sha1" } } }, "overlay": { "rhino": { "mappings": { "http-client": "./engines/rhino/http-client" } } }, ... } == Determining Package Information From URIs/modules == When a module's id is a URI, the loader should attempt to associate it with a package, if one exists for the module. The containing package and any directives (like mappings) from its package.json should be read and observed for the target modules. However, it is beyond the normative scope of this proposal to exhaustively define all the ways that a module loader may load or install packages, which may include package management tools, on-demand downloading, packages bundled in a distribution, etc. But, the following conventions should be observed: * If a module's URL is within an archive (using the jar URI scheme), then the archive should be correspond to the package for the module (with package.json in the root folder). * If a module includes a literal in a comment of the form: package root: <url> The URL indicates the URL of the root of the package: * If a request is made to server for a module the response may includes a Link header that defines "package" relation to the package root. * If a module's URL contains "lib" in one of the path identifiers, then the parent path should be considered to be the package root. == Other Considerations == * It is recommended that when web servers and module loaders resolve and fulfill a URI request to a file system directory, that they look for an "index.js" in the directory to provide as the response for the module request. For example, a web server may look for a index.js in the "my-modules" directory to fulfill a URI request like "http://somesite.com/my-modules/". However, dictating web server behavior like this in beyond the scope of this specification. * If an "overlay" is used, the mappings from both the overlay and the base structure should be applied, with the overlay taking precedent. * Implementations may treat some URIs with known server URIs structures as equivalent. For example, one can generally assume that the following URIs are the same (and prefer the use of the latter): http://github.com/{a}/{b}/raw/{c}/{d} jar:http://github.com/{a}/{b}/zipball/{c}!/{d} Implementations may also utilize trusted mirrors or repositories for alternate equivalent URLs. * This proposal does not dictate how module ids should be interpreted or mapped to packages outside of the mappings (with different mechanisms like package URI schema, two argument require, or other conventions). This proposal only provides a means for a package to declare how its modules expect an explicitly declared ranges of module ids to be mapped to URIs. These mappings only need to be applied to modules within the package. * This proposal does not define how or when modules with URIs for different versions of the modules should be treated as a single module (to maintain a singleton even when different versions are requested). Normally modules with different URIs should be considered separate modules, but there may be situations where implementations provide a means for enforcing a single module for a range of URIs. This is outside the scope of the mappings property. == Background == * [http://groups.google.com/group/commonjs/browse_thread/thread/3b6cf9d18df7379d package.json mappings] 498 2844 2010-07-09T00:06:18Z Dantman 1 Reverted edits by [[Special:Contributions/DeloresReese|DeloresReese]] ([[User talk:DeloresReese|Talk]]) to last revision by [[User:Jhuni|Jhuni]] '''STATUS: PROPOSALS''' == Overview == [[Packages/1.0]] specifies a JSON format for describing packages, this page proposes that we extend that benefit to modules, for the purposes and goals of this proposal see: [[Modules/Metadata/Purpose]]. == Format == Module metadata should be stored in JSON as package metadata is, since JSON is built right into JavaScript. <source> { // This manually specifies how this metadata will be handled. // See the "handlers section" "handler": "http://github.com/jhuni/Module-Metadata/blob/master/lib/META/Handlers/bundler.js", // Extends is basically a way of combining JSON files. "extends": "json-Modules-1.1.1-common", // This uses the format: // language, name, version, authority "id": "js-Utils.slurp-1.0-jsan+jhuni", // This makes the module return exports like in Modules/1.0. "returns": "exports", // This will pass the variables io and each to your module. "use": { "each": "js-Utils.each-1.0-jsan+jhuni", // This is for rhino users: "io.java": "java-java.io-1.4-sun", // This is for parrot users: "io.perl": "perl-File::Slurp-1.2-cpan+DROLSKY" }, // This will make sure XMLHttpRequest works in IE. "builtins": [ "XMLHttpRequest" ], // This is to aid some implementations of require() "requires": [ "js-Utils.more-1.2-jsan+jhuni" ] } </source> == Examples == === Sample Code === ;math.js: <source> META({ "id": "js-Utils.add-1.0-jsan+jhuni", "builtins": [ "Array.prototype.reduce", "Function.prototype.call" ] }); // Package return function() { return( Array.prototype.reduce.call(arguments, function(a, b) { return a + b; }) ); }; </source> ;increment.js: <source> META({ "id": "js-Utils.inc-1.0-jsan+jhuni", "use": { "add": "js-Utils.add-1.0-jsan+jhuni" } }); // Package: return function(val) { return add(val, 1); }; </source> ;program.js: <source> META({ "id": "js-Utils.program-1.0-jsan+jhuni", "use": { "inc": "js-Utils.inc-1.0-jsan+jhuni" } }); // Package var a = 1; inc(a); // 2 </source> === Modules/1.1.1 === <source> META({ // Specify what version of the CommonJS module system you are using "extends": "json-Modules-1.1.1-common", // Aid some static analysis tools by giving them shallow-deps "requires": [ "inc" ] }); /* Modules/1.1.1 code */ </source> === Loader === One of the advantages of this proposal is that even the loader script can have metadata, because usually loader scripts require lots of utilities, builtins, and other functionality. The yabble loader actually manually includes utilities similar to the ones below, furthermore the JSAN loader also requires lots of utilities. This sort of practice will leave normalizing XMLHttpRequest, and other builtins to external scripts. For example there may be special normalizers for some server-side platforms which don't have XMLHttpRequest, and some old browsers such as Opera 7.0 have normalizers based upon java. [http://www.scss.com.au/family/andrew/webdesign/xmlhttprequest] ;loader.js: <source> META({ "id": "js-ensure-1.2-commonjs", "returns": "exports", "builtins": [ "XMLHttpRequest", "Array.prototype.indexOf", "Array.prototype.filter" ], "use": { "loadModuleByScript": "js-Get.script-1.0-jsan+jhuni" } }); exports.ensure = function(modules, callback) { /* ... */ }; </source> Most modules won't even need to have access to on-demand JavaScript, they just need the ability to handle dependencies, so you will rarely have to use such an ensure function. <source> META({ "use": { "ensure": "js-ensure-1.2-commonjs" } }); ensure(['Utils.inc', 'Utils.add'], callback); </source> Furthermore, when you request the above script that requires Utils.add, and Utils.inc it will just combine the ensure like any other module, this is one case where this metadata proposal will boost the performance of client-side websites. == Handlers == === Overview === A handler is a function in which handles a metadata format, there may be multiple handlers which handle the same data differently, or handlers built to handle an entirely different metadata format. === Bundler === The bundler is a handler in which takes a module, removes its metadata and includes any of its dependencies to build a completely standalone file, for example the file Utils.program might look something like this if it was stand-alone: <source> (function() { // From "use": {"add": js-Utils.add-1.0-jsan+jhuni"} var deps1 = (function() { return function() { return( Array.prototype.reduce.call(arguments, function(a, b) { return a + b; }) ); }; })(); // From "use": {"inc": "js-Utils.inc-1.0-jsan+jhuni"} var deps2 = (function(add) { return function(val) { return add(val, 1); }; })(deps1); // This is the package itself: var requestedModule = (function(inc) { var a = 1; inc(a); // 2 })(deps2); // Now lets register the requested modules // Using some register handler: if (typeof Utils === 'undefined') { Utils = {}; } Utils.add = deps1; Utils.inc = deps2; Utils.program = requestedModule; })(); </source> Implementation: http://github.com/jhuni/Module-Metadata/blob/master/lib/META/Handlers/bundler.js === Modules/Transport === Furthermore you can write META handlers to turn scripts into one of the [[Modules/Transport]] formats. Transport D: http://github.com/jhuni/Module-Metadata/blob/master/lib/META/Handlers/transportD.js == Usage == === Local Scripts === On the server-side where you don't suffer from serious IO costs, you can just fetch all of a modules dependencies using asynchronous slurping and do the META handling locally. Localized metadata system: http://github.com/jhuni/Module-Metadata/blob/master/lib/META.js === External Scripts === If you are getting a script from an external location then you should be able to delegate the META handling process to the server who is delivering the script. <source> // Possible Example: script.src = "http://openjsan.org/?v=Utils.program-1.0&b=Firefox-3.5.9" </source> Then it that case the server in which contains that script will go through the META handling process for you and it will perform combo loading and packing to optimize performance. === Package Managers === Package managers may create separate JSON files for module metadata, for example for the module /Module/Stub.js the package manager may create /data/Module/Stub.json which stores the module's metadata. 501 2715 2010-04-20T13:57:54Z Jbrantly 109 {{Implementation |name=Yabble |url=http://github.com/jbrantly/yabble |engines=web browsers |authors=jbrantly }} 502 2723 2010-04-21T11:43:06Z Jhuni 106 == Goals == === Performance === The Modules/Metadata proposal was developed with client-side performance in mind. === Extensibility === It is easy to extend the metadata format to add new features, such as ways of handling css, images, or other forms of external dependencies, furthermore the metadata can also be used by developers for all sorts of other purposes. == Problems Solved == === Synchronicity === The require statement of [[Modules/1.0]] is too tied to blocking IO and the server side. One of the principles of this proposal is that IO should be asynchronous and non-blocking on the server-side as well as the client-side. <source> // Block the UI and all processing until we load the add module // Also if the add module happens to be online at the time, then everything might hang. var add = require('math').add; </source> '''Solution:''' This proposal solves this problem by using a source filter to build a function wrapper that is friendly to asynchronous loaders, or by wrapping a module in one of the [[Module/Transport]] schemes. === Dependency Resolution === [[Modules/1.1.1]] specifies that you should handle your dependencies by placing require statements around your module, perhaps this works on the server-side, however, on the client-side you need to get the dependencies pre-runtime, so in order to get the dependencies it is recommended that you use regular expressions such as this one: <source> // from: http://github.com/jbrantly/yabble/blob/master/yabbler.js var requireRegex = /(?:^|[^\w\$_.])require\s*\(\s*("[^"\\]*(?:\\.[^"\\]*)*"|'[^'\\]*(?:\\.[^'\\]*)*')\s*\)/g; </source> The dependencies are not that accessible if you have to use regular expressions to get them, and some specifications state that you have to use string literals in your require statements to aid such static analysis tools, this is confusing to JavaScript users who expect functions to behave as functions. <source> // Error: only use a string literal in your require statements: require( moduleName ); require( isPositive ? "Utils.inc" : "Utils.dec" ); (require ? require : function() {})("Utils.inc"); eval( "require('Utils.inc')" ); var alternativeName = require; alternativeName("Utils.inc"); </source> '''Solution:''' This proposal solves this problem by storing all metadata as JSON a format which is widely accepted and its parser is built right into JavaScript, that way if you want you can get the metadata without any regular expressions or string handling functions. === Keyword Dependency === Some users may be discouraged by the [[Modules/1.1.1]] dependency on introduced keywords such as exports, require, and module. This proposal gives you all the features of the Modules specification without depending on any keywords. <source> META({ "returns": "exports", "use": { // Specify that you want to use an old version of require() // that is to use the 1.0 version. "require": "js-require-1.0-commonjs" } }); </source> '''Solution''': this proposal solves this by assuming that you don't want any keywords unless you specify that you want them in your META header, however, if you completely omit your META header from your file then some implementations may assume that you are using a commonjs module. 503 2743 2010-04-26T20:20:44Z Mob 56 Created page with '{{Implementation |name=Ejscript |url=http://github.com/embedthis/ejs-2 |engines=Ejscript |authors=mob }}' {{Implementation |name=Ejscript |url=http://github.com/embedthis/ejs-2 |engines=Ejscript |authors=mob }} 504 2748 2010-04-27T18:31:01Z Alexanderteinum 112 Change assert.ok() and assert.equal() to use strict equality by default, add assert.looseEqual() and notLooseEqual(), remove assert.strictEqual() and assert.notStrictEqual() {{Spec |status=proposal |specification=yes |participants= |discussion= |implementations= }} = Specification = Not yet versioned. Based on [[Unit_Testing/1.0|1.0]]. == Assert == 1. The <tt>assert</tt> module provides functions that throw <tt>AssertionError</tt>'s when particular conditions are not met. The <tt>assert</tt> module must conform to the following interface. <source>var assert = require("assert");</source> 2. The AssertionError is defined in <tt>assert</tt>. <source> new assert.AssertionError({message: message, actual: actual, expected: expected}) assert.AssertionError instanceof Error </source> At present only the three keys mentioned above are used and understood by the spec. Implementations or sub modules can pass other keys to the AssertionError's constructor - they will be ignored. 3. All of the following functions must throw an <tt>AssertionError</tt> when a corresponding condition is not met, with a message that may be undefined if not provided. All assertion methods provide both the actual and expected values to the assertion error for display purposes. 4. Pure assertion tests whether a value is <code>true</code>, as determined by <code>guard === true</code>. <source>assert.ok(guard, message_opt);</source> This statement is equivalent to <code>assert.equal(guard, true, message_opt);</code>. To test loosely for the value <code>true</code>, use <code>assert.looseEqual(guard, true, message_opt);</code>. 5. The equality assertion tests shallow equality with <code>===</code>. <source>assert.equal(actual, expected, message_opt);</source> 6. The non-equality assertion tests for whether two objects are not equal with <code>!==</code>. <source>assert.notEqual(actual, expected, message_opt);</source> 7. The equivalence assertion tests a deep equality relation. * 7.1. All identical values are equivalent, as determined by <tt>===</tt>. * 7.2. If the expected value is a Date object, the actual value is equivalent if it is also a Date object that refers to the same time. * 7.3. Other pairs that do not both pass <tt>typeof value == "object"</tt>, equivalence is determined by <tt>==</tt>. * 7.4. For all other <tt>Object</tt> pairs, including <tt>Array</tt> objects, equivalence is determined by having the same number of owned properties (as verified with <tt>Object.prototype.hasOwnProperty.call</tt>), the same set of keys (although not necessarily the same order), equivalent values for every corresponding key, and an identical "prototype" property. Note: this accounts for both named and indexed properties on Arrays. <source>assert.deepEqual(actual, expected, message_opt);</source> 8. The non-equivalence assertion tests for any deep inequality. <source>assert.notDeepEqual(actual, expected, message_opt);</source> 9. The loose equality assertion tests loose equality, as determined by <tt>==</tt>. <source>assert.looseEqual(actual, expected, message_opt);</source> 10. The loose non-equality assertion tests for loose inequality, as determined by <tt>!=</tt>. <source>assert.notLooseEqual(actual, expected, message_opt);</source> 11. Expected to throw an error: <source>assert.throws(block, Error_opt, message_opt);</source> == Test == 12. The "test" module provides a "run" method that runs unit tests and catalogs their results. The "run" method must return the total number of failures, suitable for use as a process exit status code. The idiom for a self-running test module program would be: <source> if (module === require.main) require("test").run(exports); </source> 13. <tt>run</tt> must accept any <tt>Object</tt>, usually a unit test module's exports. "run" will scan the object for all functions and object properties that have names that begin with but are not equal to "test", and other properties for specific flags. Sub-objects with names that start with but are not equal to "test" will be run as sub-tests. A future version of this specification may add a mechanism for changing the mode of test functions from fail-fast (where failed assertions throw) to fail-slow (where failed assertions just log/print) via a <tt>logger</tt> argument or similar, but in the interim, this is implementation specific. <source> // ./sub-test exports.testPatience = function () { require('os').sleep(1000); }; </source> <source> // ./test exports.testSubTest = require("./sub-test"); </source> 14. Test names may be any String that begins with "test", not necessarily respecting a case convention. <source> [ [{"a": 10}, {"a": 10}], [[1, 2, 3], [1, 2, 3]] ].forEach(function (pair) { exports['test ' + pair[0].toSource()] = function () { assert.equal.apply(assert, pair); }; }); exports["test behaviour X"] = function() { behaviour.X() } </source> = Notes = == Custom Assert Modules == The assertions defined above will not be to everyone's taste style wise (or infact behaviour wise.) Authors are free to define their own assertion methods in new modules as desired. To make it possible to combine assertions from different modules in one test suite, all assert methods must throw a <tt>AssertionError</tt> (or something that is an <tt>instanceof AssertionError</tt>). Below is an example of how a custom assert module could be defined: <source> // file: my-check.js exports.check = function(actual) { return { is: function(expect, message) { if (actual != expect) throw new AssertionError({actual: actual, expected: expected, message: message}); }, } } </source> <source> // This would be used as follows: var check = require("my-check").check; exports.testSomething = function() { var sq = Math.pow(3, 2); check(sq).is(9, "3 squared is 9"); } </source> If future versions of this spec add a logger mechanism (with the intent of making it so that a failed assertion doesn't abort the above case) then the implementation above for <tt>check.is</tt> will need to be updated. == Implementations == None as yet. == Unit Tests == # http://github.com/commonjs/commonjs/tree/master/tests/unit-testing/1.0/ # None yet for this version. == Relevant Discussions == Up to [[Unit_Testing/1.0|1.0]]: * [http://groups.google.com/group/commonjs/browse_thread/thread/2952de9982fc2b55 Unit Testing 1.0 Candidate] * [http://groups.google.com/group/commonjs/browse_thread/thread/77abf61133d26c22 Recount on Unit Testing API (was: Vote: use QUnit API or Unit Testing/A)] * [http://groups.google.com/group/commonjs/browse_thread/thread/236024c7269bc9ec Vote: use QUnit API or Unit Testing/A] * [http://groups.google.com/group/commonjs/browse_thread/thread/bf1e7ce55320f0b8 Revisiting "include" (was: QUnit and CommonJS)] * [http://groups.google.com/group/commonjs/browse_thread/thread/269253f5b713c5c5 QUnit and CommonJS] * [http://groups.google.com/group/commonjs/browse_thread/thread/daee7099261d8d9a Unit Testing A Show of Hands III] * [http://groups.google.com/group/commonjs/browse_thread/thread/77ca421f63017b3f Unit Testing Show of Hands II] * [http://groups.google.com/group/commonjs/browse_thread/thread/a0db8fb0a815a6fe Unit Testing, Testing for Missing "var"s.] * [http://groups.google.com/group/commonjs/browse_thread/thread/07c69484abc8a560 Unit Testing Show of Hands] 505 2755 2010-04-29T19:10:59Z Aristid 46 /* Stateful encodings */ {{Spec |status=proposal |implementations= }} '''Derived from [[Encodings/A]] to support [[Binary/F]]. Some convenience has been removed to allow this.''' For Streams, we need encodings support. There also should be a low-level API available for this. It should support asynchronicity. = Specification = == Encoding Names == The encoding names should be among those supported by ICONV, which seem to be a superset of http://www.iana.org/assignments/character-sets. The following encodings are required: * US-ASCII * UTF-8 * UTF-16 * ISO-8859-1 Encoding names <b>must</b> be case <b>insensitive</b> == API == OK, so probably this should be a module: <source> var enc = require('encodings') </source> === Simple methods === For convenience, there should be these easy methods for converting between encodings: ; string = enc.convertToString(sourceEncoding, buffer) : Converts a Buffer to a Javascript string. ; buffer = enc.convertFromString(targetEncoding, string) : Converts a Javascript string to a Buffer. ; out_buffer = enc.convert(sourceEncoding, targetEncoding, in_buffer) : Converts a Buffer to a Buffer. === Checking for available encodings === ; enc.supports(encodingName) : Checks if encodingName is supported and return true if so, false otherwise. ; enc.listEncodings([encodingCheckerFunction or regex]) : encodingCheckerFunction takes the encoding name as a parameter and returns true-ish if the encoding should be listed. Regexes should also be supported. If the parameter is missing, returns all supported encodings. === Class: Transcoder === There also should be a class enc.Transcoder for general transcoding conversion (between ByteStrings or ByteArrays). ; [Constructor] Transcoder(from, to) : Where from and to are the encoding names. ; [Constant] sourceCharset : String containing the (possibly normalised) source charset name. ; [Constant] destinationCharset : String containing the (possibly normalised) destination charset name. ; [Method] push(buffer) : Convert input from a Buffer. Those parts of buffer that could not be converted (for multi-byte encodings) are stored in a buffer. : Returns the converted bytes as a Buffer. ; [Method] close() : Close the stream. Throws an exception if there was a conversion error (specifically, a partial multibyte character). : Writes the remaining output bytes into a Buffer and returns that Buffer. : <i>Also adds initial shift state sequences if required by the encoding.</i> '''TODO''': Which exception to throw on error? = Usage examples = Example: <source> Transcoder = require('encodings').Transcoder transcoder = new Transcoder('iso-8859-1', 'utf-32') output = [] output[0] = transcoder.push(input) // input is a Buffer output[1] = transcoder.close() // and output is an array of Buffers </source> Another example: <source> transcoder = new Transcoder('utf-32', 'utf-8') output = [] while (input = readSomeByteFromSomewhere()) { buf = transcoder.push(input, output) output.push(buf) } output.push(transcoder.close()) output = Buffer.CONCATENATE_MANY(output) // output is the complete conversion of all the input chunks concatenated now </source> == Stateful encodings == Some encodings can carry state across many characters - state which has to be reset at the end of a conversion. This creates the need to ''always'' call transcoder.close() after converting. The simple methods take care of that already. An example of such an encoding would be [http://en.wikipedia.org/wiki/ISO/IEC_2022 ISO-2022-JP], a Japanese encoding. This encoding is compatible with ASCII as long as it is in the initial state. But there is an escape sequence (actually more than one: <tt>ESC ( J</tt>, <tt>ESC $ @</tt> and <tt>ESC $ B</tt>) to get into Kana/Kanji mode, and another escape sequence to get back into ASCII mode: <tt>ESC ( B</tt>. So a reader of ISO-2022-JP content assumes that, initially, the encoding is in ASCII mode, and as soon as it sees an escape sequence, switches into another mode. Therefore, in order to be able to concatenate files, ISO-2022-JP files should end with <tt>ESC ( B</tt> if they are in non-ASCII mode at the end. <source> // Te Su To - thanks to miwagawa katakana_string = "\u30c6\u30b9\u30c8", katakana_shift_jis = binary.ByteString([ 0x83,0x65, 0x83,0x58, 0x83,0x67 ]), // Shift to JIS X 0208-1983 iso2022_FROM_ascii = [ 0x1b,0x24,0x42 ], // Shift to ASCII iso2022_TO_ascii = [ 0x1b,0x28,0x42 ], katakana_iso2022 = binary.ByteString( iso2022_FROM_ascii.concat([ 0x25,0x46, 0x25,0x39, 0x25,0x48, ], iso2022_TO_ascii) ); </source> If you transcode as in the examples above, this should work. Flusspferd has some tests for these things in http://github.com/ruediger/flusspferd/blob/master/test/js/encodings.t.js = Implementation Recommendations = First of all, it is recommended to implement convertToString, convertFromString and convert with Transcoder. Secondly, you should make sure that initial shift state support is properly implemented. When you're using iconv, you need to call iconv(cd, 0, 0, &ob, &ol) in Transcoder.close(). An example of what an initial shift state is: In the Japanese ISO-2022-JP encoding, the default state are ASCII bytes. However, the state can be switched to Japanese with an escape sequence. To make sure that at the end of the text, the state is ASCII again, iconv will emit another escape sequence to switch back again. This is important if you want to concatenate ISO-2022-JP texts, and an implementation of Transcoder that doesn't properly emit these sequences is <b>broken</b>. = Relevant Discussions = * [http://groups.google.com/group/commonjs/browse_thread/thread/6365b2a54615a134 Proposal: Encodings API (independent from Streams)] * [http://groups.google.com/group/commonjs/browse_thread/thread/3faf4a067973a71a How to make Encodings] * [http://groups.google.com/group/commonjs/browse_thread/thread/f9fcf27e1dd4a8b1 Who's implementing the Encodings API?] = Other = [http://flusspferd.org Flusspferd]'s implementation is documented [http://flusspferd.org/docs/js/commonjs%20core/encodings.html here] and [http://flusspferd.org/docs/js/commonjs%20core/encodings/transcoder.html here]. 506 2760 2010-05-02T02:10:23Z KrisKowal 6 related discussions = Proposals = * [[Events/A]] NameEmitter, Emitter, Event * [[Events/B]] Emitter, Signal * [[Events/C]] Emitter, NameEmitter * [[Events/D]] strict subset of w3c events == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/9bd7b457d0bdc85f/bfccd9961dea4335 Events A] * [http://groups.google.com/group/commonjs/browse_thread/thread/70c0d276dc5fa267/6118058542d95d78 Events A Continued] * [http://groups.google.com/group/commonjs/browse_thread/thread/36b5533cb6faf77c/a2053581a99aa21b Proposal: Timer] * [http://groups.google.com/group/commonjs/browse_thread/thread/c6e414e296d3a69a Event API Proposals] 507 2777 2010-05-20T06:54:51Z Gentleman Flying 117 Created page with 'Every NFL fan has a admired player. Someone that they admire, attending up to, and ambition they could alike be. Well, while your affairs of actuality your admired football amate…' Every NFL fan has a admired player. Someone that they admire, attending up to, and ambition they could alike be. Well, while your affairs of actuality your admired football amateur may be continued gone, that doesn't beggarly that you can't dress like them and represent them everywhere you go. That is absolutely why bargain NFL jerseys are absolute for the NFL football fan whether adolescence or adult. Nothing says fan like cutting somebody's clothing, apperceive what I mean? So if you are attractive for abatement accoutrement and uniforms for your admired amateur or team, you accept appear to the appropriate place.<br><br> Let's booty a attending at some of the best accepted official bargain nfl jerseys for auction at absolutely absurd prices.<br><br> The Adrian Peterson jersey of the Minnesota Vikings is one of the best accepted uniforms there are. This is a replica adolescence jersey that appearance the logo and colors or the Vikings forth with Adrian's cardinal and name. Or you can accept this compatible alone and customized with your own cardinal and name printed on it if you would like.<br><br> This replica compatible is fabricated of able polyester cobweb that can be apparatus done with no problem. Its bolt is fabricated to abide tearing, ripping, and staining. It additionally has a able close to abate stretching. As we know, football admirers tend to comedy football, and they appetite to do it in their admired player's apparel, so this accouterment is fabricated to ensure a lot of stress. Of course, this bargain NFL jersey is clearly accountant by the NFL. By the way, barter who bought this NFL accouterment were blessed with the chump account and quick delivery. And they said the uniforms attending 100% authentic.<br><br> One of the best accepted bargain NFL jerseys and [http://www.jordanshoesebay.com cheap jordans] anytime is the Peyton Manning compatible and the Indianapolis Colts. This is a dejected replica Reebok jersey with the #18 and the Manning name on the back. This accoutrement is additionally fabricated of able polyester to bear the asperous apartment of the youths and adults that abrasion it. It has a able v-beck with the NFL football adumbration at the basal of V. The breach bead appendage replicates the authentic, official NFL jersey perfectly. The Reebock logo is printed on anniversary sleeve to add to the actuality of this clothing. Of course, this compatible is official and accountant by the National Football League.<br><br> You can acquirement this compatible anywhere from $70 - $80. Everyone that has bought and advised this jersey gave it a 5-star review. They say that jersey looked aloof like it did on the Internet, and that the aggregation was a amusement to accord with. This is a absolute allowance for anyone adolescent or old, adolescence or adult.<br><br> For alone $55, you can own of the best accepted football uniforms on the bazaar today. That is the jersey of Ben Roethlisberger of the Pittsburgh Steelers. The polyester cobweb of this compatible forth with the abundant stitch assignment makes it assume like this is abundant added than a replica jersey - it seems like it is absolutely authentic.<br><br> You can get this Steelers accoutrement alone and customized with your own name and cardinal if you would like, or you can leave it with Roethlisberger's name and cardinal on it. Either way, you won't be aghast as this is one of the best bargain NFL jerseys and bargain jordans available. Oh yeah, it is apparatus washable as able-bodied which agency that you can accumulate it apple-pie and attractive brand-spanking new.<br><br> Want to go old academy and but some bequest NFL uniforms? No botheration - we accept aggregate you charge including accurate jerseys appropriate here. Bequest legends such as Walter Payton, Lawrence Taylor, John Elway, Joe Montana, Walter Payton - you can get all of these bequest uniforms and added alignment from $60 - $150. Of course, you are activity to get the abstract NFL shield, the bequest attractive jerseys with the player's name and cardinal on it, and these are all clearly accountant by the NFL.<br><br> Sizes of these throwbacks uniforms will alpha at baby and go to 5X large. With 8 altered sizes, you won't accept any botheration at all award absolutely what you are attractive for. These jerseys are absolutely alleged replithentic jerseys. Of course, it is replica accouterment for adolescence and adults to enjoy, but they assume so absolute and official that you would affirm they were all 100% accurate apparel. Best of these bequest uniforms cannot be alone and customized with your name.<br><br> And don't anticipate this is all of your choices for bargain NFL jerseys. There are a ton added players [http://www.jordanshoesebay.com jordan shoes sale] you can buy. With abounding of them, you accept the advantage of accepting your player's name and cardinal on them, or you can personalize and adapt them with you own name and number. We are talking players like Tony Romo, Brett Favre, Drew Brees, Braylon Edwards, Ricky Williams, Joe Flacco, and Tom Brady aloof to name a few.<br><br> Most of these bargain NFL jerseys are fabricated by Reebok, one of the best trusted makers of football apparel. Reebok was absolutely amorphous in 1890 in England by a man who added spikes to shoes so athletes could run faster and quicker. Athletes such as Allen Iverson, Peyton Manning, Yao Ming, and Josh Beckett currently abrasion Reebok accoutrement and shoes. 508 2784 2010-05-23T23:54:10Z KrisKowal 6 Created page with '{{Implementation |name=Narwhal on Rhino |url=http://github.com/tlrobinson/narwhal |engines=Rhino |authors=Tlrobinson, KrisKowal }}' {{Implementation |name=Narwhal on Rhino |url=http://github.com/tlrobinson/narwhal |engines=Rhino |authors=Tlrobinson, KrisKowal }} 509 2785 2010-05-23T23:54:58Z KrisKowal 6 Created page with '{{Implementation |name=Narwhal on JSC |url=http://github.com/280north/narwhal-jsc |engines=JSC |authors=Tlrobinson }} Adapters for JavaScriptCore' {{Implementation |name=Narwhal on JSC |url=http://github.com/280north/narwhal-jsc |engines=JSC |authors=Tlrobinson }} Adapters for JavaScriptCore 510 2786 2010-05-23T23:55:50Z KrisKowal 6 Created page with '{{Implementation |name=Narwhal on Node |url=http://github.com/kriskowal/narwhal-node |engines=v8 |authors=KrisKowal, Paul Baumgart }} Adapters for running Narwhal on Node on v8.' {{Implementation |name=Narwhal on Node |url=http://github.com/kriskowal/narwhal-node |engines=v8 |authors=KrisKowal, Paul Baumgart }} Adapters for running Narwhal on Node on v8. 511 2792 2010-05-26T06:57:25Z Created page with 'The National Football League season matches occur once every year. Beginning the weekend after Labor Day, the football madness rages for full seventeen weeks, but when it all end…' The National Football League season matches occur once every year. Beginning the weekend after Labor Day, the football madness rages for full seventeen weeks, but when it all ends the fans will have to make do with memories until next year. For some being able to achieve what their heroes are doing is a life time dream. Even though you can only imagine being them, you can buy [http://www.godiscount.us nfl jerseys] jerseys that are replicas of your favorite footballer's jerseys. If you want to find out some tips, read the rest of this article.<br><br> The first thing to do when you decide to buy one is to get on a computer and search for the different options available. By comparing the different options available online you may even be able to land a bargain. It also makes sense to buy in bulk with a few of your friends. Some sellers will give free shipping as well as lower costs if you buy in bulk.<br><br> But before you can make your buying decision you have to decide which player's name you want on your jersey. Better still you can even have your own name printed on the shirt with your favorite player's number on it.<br><br> Some sellers will also offer you the option of customizing your jerseys even as far as club colors go. So you can get your name, with your lucky number and your preferred clubs colors. It is also possible to order jerseys for you and your friends with your very own colors. The internet opens a whole new way of buying products; it can help you get exactly what you want if you have the money to afford it.<br><br> When spending on jerseys try to avoid the temptation to just buy the cheapest ones. Good quality jerseys are made from polyester and can be used to play in actual games as well. The best part is that if you can get autographs of a star player on one of the jerseys, several years down the road it could become a collector's item.<br><br> The value of a collector's jersey at that time will also be based on the quality of the Jersey. Not only that, Even though they may cost a few extra bucks to get good quality jerseys are durable and very comfortable to wear.<br><br> Replicas that are available are priced based on the closeness of details to the original. So a Jersey that looks exactly like the original ones worn by the player will cost a lot. But it's always a good idea to buy as close to original as possible. It's worth it when you and your buddies show up to the games wearing these - you never know they might even mistake you for the stars themselves.<br><br> The effort that you have spent in searching for this page and reading it till now shows exactly how interested in getting the best for yourself. And to be very frank with you, [http://www.veryverycheap.us cheap nfl] Jerseys are the easiest way to step into the shoes of your favorite player. 512 2809 2010-05-27T11:51:40Z Alexandre.Morgaut 33 {{Implementation |name=Wakanda |url=http://www.wakandasoft.com |engines=JavaScriptCore/C++ |authors=Alexandre.Morgaut }} The '''Wakanda project''' include a '''Server''' with a '''NoSQL data store''', a '''Studio''', and an '''Ajax Framework'''. It is a [http://www.4D.com 4D] project created by '''Laurent Ribardiere''' It was presented at: # the Ajax Experience 2009 # the JSConf.eu 2009 (JSConf.us 2010 was missed because of the volcano...) [http://www.slideshare.net/alexandre_morgaut/wakanda-js-conf-eu-09-slideshare Slide's of the JSConf presentation] Twitter contacts: # [http://twitter.com/wakandasoft @wakandasoft] # [http://twitter.com/amorgaut @amorgaut] 513 2828 2010-06-15T23:23:07Z KrisKowal 6 Charles shows his hand {{Spec |status=proposal }} '''-1: Ash Berlin, Isaac Schlueter, Charles Jolley''' '''+1: Kris Zyp, ChristophDorn, Irakli Gozalishvili, Kris Kowal''' == Package Mappings == This specification describes an addition to the CommonJS package format for packages to define how they expect their module namespace to be mapped into the module name spaces of referenced packages. This specification introduces a "mappings" property that describes special behavior of the "require" function that is scoped to all modules in the given package, such that top level identifiers starting with particular values for their first slash-delimited term correspond to top-level modules in the respectively mapped package. This specification does not define how the modules of referenced packages are installed or retrieved, and it does not define how any module identifiers are resolved apart from those that are mapped. Example: { "name": "mypackage", "mappings": { "theirpackage": "http://github.com/them/theirpackage/zipball/master" } } == Specification == The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. === Packages === # The <code>package.json</code> at the root of a package directory tree or archive MAY have a <code>"mappings"</code> property. # The <code>"mappings"</code> property maps single-term top-level module identifiers to external package references. # A single-term top-level module identifier MUST consist of only lower-case letters, digits, underscore, and hyphen. ''Note: It MUST not include a slash (<code>"/"</code>) or dot (<code>"."</code>).'' # If an external package reference is a string, it is equivalent to an object with that string as its <code>"location"</code> property. # An external package reference MUST have a <code>"location"</code> property. ## The <code>"location"</code> MUST be an HTTP URL String. ## If the <code>"location"</code> ends with a slash (<code>"/"</code>), it MUST refer to the root of a directory tree conforming to the content of a package as described by [[Packages]] and where every contained file is retrievable with an HTTP GET request for a path resolved based on the given location. ## If the <code>"location"</code> does not end with a slash (<code>"/"</code>), it MUST refer to an archive as described by [[Packages]] and retrievable with a single HTTP GET request. # An external package reference MAY have a <code>"descriptor"</code> property that is a limited package descriptor object, a strict subset of the <code>package.json</code> schema as described in [[Packages]]. ## A package descriptor MAY have a <code>"index"</code> property <code>String</code> that is a path relative to the root of the package URL or archive. ## A package descriptor MAY have a <code>"directories"</code> property. ### The <code>"directories"</code> Object MAY have a <code>"lib"</code> property, which MUST be a <code>String</code> describing a relative path, resolved from the root of a package or archive. # If <code>package.json</code> contains an <code>"overlay"</code> property, and any of the applicable values of the overlay property (as defined by [[Packages]]) contain a "mappings" property, the (key, value) pairs of the main "mappings" property MUST be updated with each applicable overlaid mappings property, overriding existing (key, value) pairs. # If the <code>"location"</code> of the package refers to a retrievable archive, an external package reference MAY have a <code>"verify"</code> property that is an <code>Object</code>. ## The <code>"verify"</code> object MUST have a <code>"algorithm"</code> property that refers to the algorithm with which the <code>"signature"</code> was generated. ## The <code>"verify"</code> object MUST have a <code>"signature"</code> property that is a signature or hash of the referenced archive. ## The <code>"signature"</code> MUST be a lower-case base-16 value represented as a string of colon-delimited bytes. ## The <code>"algorithm"</code> MAY be <code>"md5"</code>, in which case the <code>"signature"</code> MUST be a MD5 digest of the package archive file, computed as described in RFC 1321. ## The <code>"algorithm"</code> MAY be <code>"sha1"</code>, in which case the <code>"signature"</code> MUST be an SHA-1 digest of the package archive file, computed as described in RFC 3174. ''Note: this specification does not define the behavior of any other verification algorithms. These may be amended in a future revision.'' ''Note: this specification does not define any archival formats apart from zip since this is the only standard format described in [[Packages]], and may be amended in a future revision of that specification, in which case corresponding verbiage must be added to this specification to indicate the archival format of the an external package.'' === Modules === Within a package, the semantics of the <code>require</code> function are augmented as follows: # If the required module identifier is not relative, it is a candidate for referencing a module in an external package. ## If the identifier has only one term (''That is, contains no slashes (<code>"/"</code>'')), it is a candidate for referencing the index module of an external package. ### If this package is external to another package, and the parent package has an <code>"index"</code> property in its mapping for this package, <code>require</code> MUST return the exports of the specified index module of the external package. ### Otherwise, if the external package does have an <code>"index"</code> property in its <code>package.json</code> file, <code>require</code> MUST return the exports of the index module of the external package. ### Otherwise, <code>require</code> MUST throw an <code>Error</code>. ## If the identifier has multiple terms delimited by slashes, it is a candidate for referencing a module in the library directory of an external package. ### If the first term of the module identifier as delimited by slashes is not a property of the <code>"mappings"</code> object in the current package's <code>package.json</code>, the behavior of <code>require</code> is beyond the scope of this specification and follows through with the behavior defined in [[Packages]] in the context of the current package. ### If the first term of the module identifier as delimited by slashes is a property of the <code>"mappings"</code> object in the current package's <code>package.json</code>, <code>require</code> MUST return the exports of the module with the top-level identifier composed of all subsequent slash-delimited terms in the required module identifier in the context of the referenced external package as defined in [[Packages]]. #### If the external package reference contains a <code>descriptor.directories.lib</code> property, the modules from the external package MUST be found in the named lib directory, resolved relative to the root of the external package. === The Index Module === # In the evaluation context of an index module, the value of the <code>module</code> free variable does not have an <code>"id"</code> property. == Examples == { "name": "mypackage", "mappings": { "theirpackage": "http://github.com/them/theirpackage/zipball/master" } } This example is equivalent to the above example, by virtue of rotating the package location into an external package reference object. { "name": "mypackage", "mappings": { "theirpackage": { "location": "http://github.com/them/theirpackage/zipball/master" } } } This example includes an annotation on where to find the index module of a legacy Narwhal external package, and an annotation describing the SHA-1 hash of the package archive for verification purposes. { "name": "jill", "mappings": { "jack": { "location": "http://github.com/280north/jack/zipball/master", "descriptor": "index": "lib/jack.js", "directories": { "lib": "lib/jack" } }, "verify": { "signature": "c1:b1:30:29:d7:b8:de:6c:97:77:10:d7:46:41:63:87", "algorithm": "sha1" } } } } The following example indicates how you might externally reference a package that was not designed for CommonJS: { "name": "mypackage", "mappings": { "dojox": { "location": "http://download.dojotoolkit.org/release-1.4.3/dojo-release-1.4.3.zip", "descriptor": { "directories": { "lib": "dojox" } } } } } == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/3b6cf9d18df7379d package.json mappings] * [http://groups.google.com/group/commonjs/browse_thread/thread/c3aaaa406d794b79 packages] 514 2874 2010-08-04T02:38:45Z Kriszyp 39 Define behavior for string values in mappings for relative and absolute URLs {{Spec |status=proposal }} == Package Mappings == This specification describes an addition to the CommonJS package format for packages to define how they expect their module namespace to be mapped into the module name spaces of referenced packages. This specification introduces a "mappings" property that describes special behavior of the "require" function that is scoped to all modules in the given package, such that top level identifiers starting with particular values for their first slash-delimited term correspond to top-level modules in the respectively mapped package. This specification does not define how the modules of referenced packages are installed or retrieved, and it does not define how any module identifiers are resolved apart from those that are mapped. == Examples == A package that provides the URL of an archive that is known to work as a subpackage. { "name": "mypackage", "mappings": { "theirpackage": { "archive": "http://github.com/them/theirpackage/zipball/master" } } } This can be written more tersely: { "name": "mypackage", "mappings": { "theirpackage": "http://github.com/them/theirpackage/zipball/master" } } A package that provides the exact version number of a subpackage that is known to work. A version number implies that this package is a member of some registry or catalog with consistently named and versioned packages. { "name": "mypackage", "mappings": { "theirpackage": { "version": "0.0.1" } } } The URL of the registry or catalog may be provided for informational purposes, but this specification does not impose any restrictions on the format or content of the registry. { "name": "mypackage", "mappings": { "theirpackage": { "version": "0.0.1" } }, "catalog": "http://example.com/packages-catalog.json" } If a package uses sub-packages from a variety of catalogs, the informational catalog URL may be provided for specific mappings. { "name": "mypackage", "mappings": { "theirpackage": { "version": "0.0.1" }, "otherpackage": { "version": "0.0.1", "catalog": "http://example.org/some/other/catalog.json" } }, "catalog": "http://example.com/packages-catalog.json" } The key of the mapping indicates how the package will be known in modules. In these examples, the "main" module of "theirpackage" would be imported as "theirpackage". require("theirpackage"); If the package comes from a registry of coordinated package names, the name of the package in the repository is assumed to be the same as the key of the mapping. However, it may be overridden. { "name": "mypackage", "mappings": { "theirpackage": { "version": "0.0.1", "name": "theirpackagename" } }, "catalog": "http://example.com/packages-catalog.json" } Some package managers can fetch individual files from an unpacked package, provided over HTTP at a particular location. The <code>"location"</code> key indicates the URL of an unpacked package that is known to work as a subpackage. { "name": "mypackage", "mappings": { "theirpackage": { "location": "http://example.com/packages/theirpackage/" } } } To be compatible with a wide variety of package managers, packages should include a variety of metadata, and may provide all of the defined attributes. { "name": "mypackage", "mappings": { "theirpackage": { "name": "theirpackagename", "version": "0.0.1", "archive": "http://example.com/packages/theirpackage.zip", "location": "http://example.com/packages/theirpackage/" } }, "catalog": "http://example.com/packages-catalog.json" } # To be compliant with this specification, a package manager must be able to handle any package that provides all of the recommended metadata. # To be usable by any package manager, a package must provide all of the recommended metadata. == Specification == The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. === Packages === # The <code>package.json</code> at the root of a package directory tree or archive MAY have a <code>"mappings"</code> property. # <code>package.json</code>'s <code>"mappings"</code> property maps single-term top-level module identifiers to external package references. # A single-term top-level module identifier MUST consist of only lower-case letters, digits, underscore, and hyphen. ''Note: It MUST not include a slash (<code>"/"</code>) or dot (<code>"."</code>).'' # If an external package reference is a string and the string is an absolute URL, it is equivalent to an object with that string as its <code>"archive"</code> property. # If an external package reference is a string and the string is a relative URL, it is equivalent to an object with that string as its <code>"location"</code> property. # An external package reference SHOULD have an <code>"archive"</code> property. Package managers MAY depend on the provision of this property. ## The <code>"archive"</code> property MUST be an URL String from which an archive as described by [[Packages]] can be downloaded with an HTTP GET request. # An external package reference SHOULD have a <code>"location"</code> property. Package managers MAY depend on the provision of this property. ## The <code>"location"</code> property MUST refer to the root of a directory tree conforming to the content of a package as described by [[Packages]] and where every contained file is retrievable by the URL resolved based on the given location. If the <code>"location"</code> property is a relative URL, it MUST be resolved relative to the package root of the parent package that is being described and contains the mappings (i.e. relative to this package.json file). If the package has been expanded from an archive, the relative URLs MAY point to another directory within the archive. # An external package reference MAY have a <code>"version"</code> property. Package managers MAY depend on the provision of this property. ## If <code>"version"</code> exists, an external package reference MAY contain a <code>"name"</code> property that indicates the name of the package in a coordinated registry of packages. If omitted, this property defaults to the key of the mapping. # An external package reference MAY have a <code>"descriptor"</code> property that is a package descriptor object, conforming to the <code>package.json</code> schema as described in [[Packages]]. # An external package reference MAY have a <code>"catalog"</code> property that notes the URL of the catalog or registry with which a package manager is expected to associate this external package reference with additional or missing details. # <code>package.json</code> may have a "catalog" property that notes the URL of the catalog or registry with which to associate package names and versions with further corresponding external package reference details. # If the external package reference has a <code>"archive"</code> property, an external package reference MAY have a <code>"verify"</code> property that is an <code>Object</code>. ## The <code>"verify"</code> object MUST have a <code>"algorithm"</code> property that refers to the algorithm with which the <code>"signature"</code> was generated. ## The <code>"verify"</code> object MUST have a <code>"signature"</code> property that is a signature or hash of the referenced archive. ## The <code>"signature"</code> MUST be a lower-case base-16 value represented as a string of colon-delimited bytes. ## The <code>"algorithm"</code> MAY be <code>"md5"</code>, in which case the <code>"signature"</code> MUST be a MD5 digest of the package archive file, computed as described in RFC 1321. ## The <code>"algorithm"</code> MAY be <code>"sha1"</code>, in which case the <code>"signature"</code> MUST be an SHA-1 digest of the package archive file, computed as described in RFC 3174. ''Note: this specification does not define the behavior of any other verification algorithms. These may be amended in a future revision.'' ''Note: this specification does not define any archival formats apart from zip since this is the only standard format described in [[Packages]], and may be amended in a future revision of that specification, in which case corresponding verbiage must be added to this specification to indicate the archival format of the an external package.'' ''Note: This specification does not impose any restrictions on the format of the catalog file, nor even whether it is retrievable. Package registries or catalogs may opt to disqualify a package based on whether it supports a particular catalog URL, the format of the catalog, or for not providing a catalog URL.'' ''Note: An external package reference may contain further properties. This specification recommends that these properties be prefixed with an implementation name to avoid collisions with properties of other implementations and future versions of this specification.'' === Modules === Within a package, the semantics of the <code>require</code> function are augmented as follows: # If the required module identifier is not relative, it is a candidate for referencing a module in an external package. ## If the identifier has only one term (''That is, contains no slashes (<code>"/"</code>'')), it is a candidate for referencing the main module of an external package. ### If this package is external to another package, and the parent package has an <code>"main"</code> property in its mapping for this package, <code>require</code> MUST return the exports of the specified main module of the external package. ### Otherwise, if the external package does have an <code>"main"</code> property in its <code>package.json</code> file, <code>require</code> MUST return the exports of the main module of the external package. ### Otherwise, <code>require</code> MUST throw an <code>Error</code>. ## If the identifier has multiple terms delimited by slashes, it is a candidate for referencing a module in the library directory of an external package. ### If the first term of the module identifier as delimited by slashes is not a property of the <code>"mappings"</code> object in the current package's <code>package.json</code>, the behavior of <code>require</code> is beyond the scope of this specification and follows through with the behavior defined in [[Packages]] in the context of the current package. ### If the first term of the module identifier as delimited by slashes is a property of the <code>"mappings"</code> object in the current package's <code>package.json</code>, <code>require</code> MUST return the exports of the module with the top-level identifier composed of all subsequent slash-delimited terms in the required module identifier in the context of the referenced external package as defined in [[Packages]]. #### If the external package reference contains a <code>descriptor.directories.lib</code> property, the modules from the external package MUST be found in the named lib directory, resolved relative to the root of the external package. == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/3b6cf9d18df7379d package.json mappings] * [http://groups.google.com/group/commonjs/browse_thread/thread/c3aaaa406d794b79 packages] * [http://groups.google.com/group/commonjs/browse_thread/thread/f58a017810ffdb78 Towards a Simplified Packages Spec] * [http://groups.google.com/group/commonjs/browse_thread/thread/d523333df583d11b Packages/1.1 tire kick] * [http://groups.google.com/group/commonjs/browse_thread/thread/cb8db969eb2dcf7e Semi-related packages question] 517 2840 2010-06-29T08:24:00Z Fgm 53 Created page with 'Following CommonJS dev but not coding for it (yet ?)' Following CommonJS dev but not coding for it (yet ?) 518 2889 2010-09-06T17:10:58Z Zimbatm 72 /* Engines */ Hi, the following has sprung to my eyes: * Keyword ''engine'', but the example says ''engines'', which sounds more reasonable due to the array value * Keyword ''contributors'' mentions ''author''; did you mean ''maintainers''? * ''" web"'' in the ''maintainers'' example contains a spurious whitespace character --[[User:Astro|Astro]] 03:27, 14 July 2010 (UTC) == Engines == * What is the engine name for browsers ? --[[User:Zimbatm|Zimbatm]] 17:10, 6 September 2010 (UTC) 519 2849 2010-07-14T03:27:25Z Astro 125 Created page with 'Mail & XMPP: astro@spaceboyz.net' Mail & XMPP: astro@spaceboyz.net 520 2850 2010-07-14T03:41:51Z Astro 125 errata? Oops, I accidently read & commented on Packages/1.0. Why do you link to old versions? 2/3 questions remain though: * Is ''" web"'' a typo? * Is it ''"engine"'' or ''"engines"''? --[[User:Astro|Astro]] 03:41, 14 July 2010 (UTC) 521 2858 2010-07-15T11:45:37Z Dantman 1 Undo revision 2855 by [[Special:Contributions/Gozala|Gozala]] ([[User talk:Gozala|Talk]]); If you intend for the removal of a page please tag it for deletion. {{Spec |status=proposal }} == Package Mappings / Dependencies == This specification extends CommonJS package format for packages to define how they expect their dependencies to be mapped into the module name spaces. This specification extends "dependencies" property in package descriptor and expects that implementers will organize dependencies in way that all modules from the "dependencies" can be required by a top level identifiers, whose first slash-delimited term correspond to a key in the "dependencies" map. This specification does not define how the modules of referenced packages are installed or retrieved. == Examples == { "name": "mypackage", "dependencies": { "theirpackage": "http://github.com/Gozala/github/blob/gh-pages/" } } Values in the "dependencies" map MUST represent URI's and have to refer to the root of a dependent package. There for appending 'package.json' to the dependency URI should give URI to a package descriptor. Appending 'manifest.json' to a dependency URI MUST give URI to a package manifest, that is a JSON containing list of modules that package contains. [ "index", "foo/bar", "foo/main" ] Way of expressing version or other information about dependency is by intension left to a package registries / managers and expected to be embedded into URI itself. { "name": "mypackage", "dependencies": { "theirpackage": "http://npm.com/foo@1.2.3/" } } { "name": "mypackage", "dependencies": { "theirpackage": "http://mozillalabs.com/jetpack/libs/bar/1.2.3/" } } The key for this proposal is to provide a form of requiring modules form a dependency, regardless of the package manager and registry they come from. require("theirpackage/theirmodule"); How does package managers register or install individual packages / modules is out of the scope of this proposal. # To be compliant with this specification, package manager must be able to handle any package that provides all of the recommended metadata. # To be usable by any package manager, a package must provide all of the recommended metadata. == Specification == The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. === Packages === # The <code>package.json</code> at the root of a package directory tree or archive MAY have a <code>"dependencies"</code> property. # <code>package.json</code>'s <code>"dependencies"</code> property maps single-term top-level module identifiers to external package references. # A single-term top-level module identifier MUST consist of only lower-case letters, digits, underscore, and hyphen. ''Note: It MUST not include a slash (<code>"/"</code>) or dot (<code>"."</code>).'' # An external package reference SHOULD have an <code>"archive"</code> property. Package managers MAY depend on the provision of this property. ## The <code>"archive"</code> property MUST be an URL String from which an archive as described by [[Packages]] can be downloaded with an HTTP GET request. # An external package reference SHOULD have a <code>"location"</code> property. Package managers MAY depend on the provision of this property. ## The <code>"location"</code> property MUST refer to the root of a directory tree conforming to the content of a package as described by [[Packages]] and where every contained file is retrievable with an HTTP GET request for a path resolved based on the given location. # An external package reference MAY have a <code>"version"</code> property. Package managers MAY depend on the provision of this property. ## If <code>"version"</code> exists, an external package reference MAY contain a <code>"name"</code> property that indicates the name of the package in a coordinated registry of packages. If omitted, this property defaults to the key of the mapping. # An external package reference MAY have a <code>"descriptor"</code> property that is a package descriptor object, conforming to the <code>package.json</code> schema as described in [[Packages]]. # An external package reference MAY have a <code>"catalog"</code> property that notes the URL of the catalog or registry with which a package manager is expected to associate this external package reference with additional or missing details. # <code>package.json</code> may have a "catalog" property that notes the URL of the catalog or registry with which to associate package names and versions with further corresponding external package reference details. # If the external package reference has a <code>"archive"</code> property, an external package reference MAY have a <code>"verify"</code> property that is an <code>Object</code>. ## The <code>"verify"</code> object MUST have a <code>"algorithm"</code> property that refers to the algorithm with which the <code>"signature"</code> was generated. ## The <code>"verify"</code> object MUST have a <code>"signature"</code> property that is a signature or hash of the referenced archive. ## The <code>"signature"</code> MUST be a lower-case base-16 value represented as a string of colon-delimited bytes. ## The <code>"algorithm"</code> MAY be <code>"md5"</code>, in which case the <code>"signature"</code> MUST be a MD5 digest of the package archive file, computed as described in RFC 1321. ## The <code>"algorithm"</code> MAY be <code>"sha1"</code>, in which case the <code>"signature"</code> MUST be an SHA-1 digest of the package archive file, computed as described in RFC 3174. ''Note: this specification does not define the behavior of any other verification algorithms. These may be amended in a future revision.'' ''Note: this specification does not define any archival formats apart from zip since this is the only standard format described in [[Packages]], and may be amended in a future revision of that specification, in which case corresponding verbiage must be added to this specification to indicate the archival format of the an external package.'' ''Note: This specification does not impose any restrictions on the format of the catalog file, nor even whether it is retrievable. Package registries or catalogs may opt to disqualify a package based on whether it supports a particular catalog URL, the format of the catalog, or for not providing a catalog URL.'' ''Note: An external package reference may contain further properties. This specification recommends that these properties be prefixed with an implementation name to avoid collisions with properties of other implementations and future versions of this specification.'' === Modules === Within a package, the semantics of the <code>require</code> function are augmented as follows: # If the required module identifier is not relative, it is a candidate for referencing a module in an external package. ## If the identifier has only one term (''That is, contains no slashes (<code>"/"</code>'')), it is a candidate for referencing the main module of an external package. ### If this package is external to another package, and the parent package has an <code>"main"</code> property in its mapping for this package, <code>require</code> MUST return the exports of the specified main module of the external package. ### Otherwise, if the external package does have an <code>"main"</code> property in its <code>package.json</code> file, <code>require</code> MUST return the exports of the main module of the external package. ### Otherwise, <code>require</code> MUST throw an <code>Error</code>. ## If the identifier has multiple terms delimited by slashes, it is a candidate for referencing a module in the library directory of an external package. ### If the first term of the module identifier as delimited by slashes is not a property of the <code>"mappings"</code> object in the current package's <code>package.json</code>, the behavior of <code>require</code> is beyond the scope of this specification and follows through with the behavior defined in [[Packages]] in the context of the current package. ### If the first term of the module identifier as delimited by slashes is a property of the <code>"mappings"</code> object in the current package's <code>package.json</code>, <code>require</code> MUST return the exports of the module with the top-level identifier composed of all subsequent slash-delimited terms in the required module identifier in the context of the referenced external package as defined in [[Packages]]. #### If the external package reference contains a <code>descriptor.directories.lib</code> property, the modules from the external package MUST be found in the named lib directory, resolved relative to the root of the external package. == Related Discussions == * [http://groups.google.com/group/commonjs/browse_thread/thread/3b6cf9d18df7379d package.json mappings] * [http://groups.google.com/group/commonjs/browse_thread/thread/c3aaaa406d794b79 packages] * [http://groups.google.com/group/commonjs/browse_thread/thread/f58a017810ffdb78 Towards a Simplified Packages Spec] * [http://groups.google.com/group/commonjs/browse_thread/thread/d523333df583d11b Packages/1.1 tire kick] * [http://groups.google.com/group/commonjs/browse_thread/thread/cb8db969eb2dcf7e Semi-related packages question] 522 2865 2010-07-16T07:41:18Z Dantman 1 6 revisions:&#32;Import my HTTP-Gateway proposal, decommissioning the accessjs wiki This is an interface used by any http gateway handler. A handler's job is to talk with a webserver (or act as one) in some way (mod_ handler, CGI handler, FastCGI handler, built-in http server, Servlet handler, etc...) and provide an api conforming to this spec which it makes a call to the gateway using app with to handle the http request and response. The API used in this spec was designed arround an inverted XMLHttpRequest object, with some high-level things removed, static content properties and events converted to streaming, and some server functionality patterns from the JSGI/Rack/WSGI group of protocols. Middleware is NOT a target of this spec, middleware is a semi-high level funcationality, this spec's target is low-level functionality only. Middleware can be implemented inside of a gateway interface built on top of this gateway interface written in pure-js (ie: You can write JSGI entirely using this http-gateway, heck you could write a node compatible API port using this http-gateway). This API is independent of sync or async code. It works purely on a streaming basis. The implementation is expected to: # read the status line and the headers (or grab them from whatever api) # look for a content-length header and use it to wrap the input stream (or make the input stream return EOF right away if no content-length is present) # wrap the output stream in this api # then pass it to the gateway app Once the api leaves the gateway handler control over the response is completely up to the gateway app. It is the gateway app's responsibility to end the request by calling .close(); The function returning signifies nothing to the handler other than the gateway being ready to accept another request. So it doesn't matter to the handler whether the gateway app is streaming or doing some other action asynchronously. == Quick Overview == <source> exports.(app|gateway?) = function(r) { r.gateway.version = [1, 0]; r.gateway.multithread; r.gateway.multiprocess; r.gateway.runonce; r.env; // An object containing various pieces of data from the server; // Env variables for CGI, passed faux env for FastCGI, handler dependant on other types of handlers. r.connected; // boolean true, will change to boolean false if the client has disconnected // Request (all keys must be present and of the correct type) r.method === "GET"; // must be uppercase string r.scheme === "http"; // must be lowercase string r.serverName; // string; ip, static hostname, etc... (NOT the value of the Host: header) r.serverPort; // 80, etc... r.scriptName; // String coresponding to the application location. "" if at site root, string starting with / otherwise. (decoded) r.pathInfo; // ... (decoded) r.queryString; // string r.getRequestHeader('Content-Type'); r.read(#); r.read(); // Response r.status = 200; r.statusText = "OK"; // optional status text. Some handlers may ignore this, // handlers should understand the relation of basic http status codes // to their status text in some way (even if that is allowing apache or something else handle that) r.addResponseHeader('Content-Type', 'text/html'); // Should throw an error if .flush() has already been called. r.write(data); // First call implies a call to .flush() r.flush(); // Flushes buffered data if buffering is used and flushing is possible; // First call sends status and headers through handler and signifies finalization of them, rejection of headers after that is enforced. r.close(); }; </source> == API == ;connected: A boolean indicating if the client is still connected. Checking this periodically is useful to understand if you should abort what you are doing. ;method: The method of request used as an uppercase string. ;scheme: The protocol used in the request as a lowercase string. This is normally only ever "http" or "https". ;serverName: ;serverPort: ;scriptName: (decoded) ;pathInfo: (decoded) ;queryString: The query string from the response. ;getRequestHeader(headerName); : ;read(max); : ;status :The numeric http status code to return. This is the only necessary interface for defining the return status. The handler must map the standard HTTP numeric status codes to their default status text. ;statusText :An optional extra interface to the status text. You may set this to override the status text printed beside the status code. This interface is not necessary for use for the standard http headers, the handler must know how to map status codes to status text when overrides are not specified. :Note that some handlers may ignore this property if the system they connect does not provide a way to set the status text. ;addResponseHeader(headerName, headerValue); :Adds a response header to the headers in the response. Multiple headers of the same kind can be written with separate calls. New calls will not overwrite old headers. ;flush(); :Ensures current buffered data is flushed to the output stream. :On first call this method forces the status line and headers to be sent, and terminates headers (the blank line indicating the start of the body). After this is called all calls to addResponseHeader will throw. ;write(data); :Writes a chunk of data to the output stream. :Data must be a object that returns a Blob on valueOf("blob"); :On first call this implies a call to .flush(); ;close(); :This closes the connection with the browser ending the response. == ToFix == * getRequestHeader is implemented for the most flexibility, however to implement JSGI's env/req object with HTTP-Gateway we'll need a method that allows the list of all sent headers to be obtained so that the .headers object can be created. * Should we note that calls to addResponseHeader with newlines in the headerValue should write out the header in extended header format (ie: A single header where it is extended to multiple lines by prepending each line with leading whitespace): <pre>X-Example: asdf asdf</pre> 523 2866 2010-07-16T09:11:28Z Dantman 1 Created page with ''''AIO''' (Advanced IO) is an API idea based on Java's NIO as well as some high-level ideas. The intent is to provide a powerful api which is clean to use and can be optimized we…' '''AIO''' (Advanced IO) is an API idea based on Java's NIO as well as some high-level ideas. The intent is to provide a powerful api which is clean to use and can be optimized well by the implementation. * [[/ByteBuffer/]] * [[/Stream/]] * [[/Patterns and Examples/]] * [[/Multi-Thread/]] 524 2869 2010-07-16T09:19:22Z Dantman 1 Buffer; Abstract ByteBuffer is an abstract, potentially virtual, optimized binary storage object. We say a ByteBuffer can be "virtual" because a ByteBuffer does not care that it's data be non-shared, be located in mem with the same capacity as the buffer says it is, or even be aranged in memory in the way it looks. The only thing that matters is that the API works as expected. This is why we have duplicate methods like reset() and clear(). If a ByteBuffer had been optimizing in a special way to avoid the need to copy data to the start of the buffer and was instead artificially shrinking the capacity of the buffer and using an internal offset the act of calling reset() on it which has an implied contract that the data will not be scrambled would force the buffer to copy the data to the start of the buffer in order to avoid scrambling the data unexpectedly. However the clear() operation behaves the same as reset() except it does not have the contract of maintaining that data, the ByteBuffer is free to do whatever it wants with the data. In this case because the ByteBuffer does not have to worry about the data being scrambled instead of copying the data to the start of the buffer in memory it could instead leave the data where it is and reset the internal offset, this would have the effect of making it look to a programa as if the start of the buffer was shifted forward an arbatrary length, however it is a faster operation than reset() because it doesn't need to copy the data to the start of the buffer to avoid creating that false impression. We also say that it can be "virtual" because it doesn't care that the data is actually a managed buffer in memory mirroring the data. ByteBuffer works fine with a section of memory that is actually mmaped, actually belongs to the os' filesystem cache, etc... as long as the ByteBuffer behaves in the way it is expected to. So it is possible to optimize it to shuffle data around while avoiding various inefficient operations. It is also possible to use .range to create a buffer which is actually backed by a portion of another ByteBuffer and which will modify it's data. ;ByteBuffer.cast(data); :Converts data into a ByteBuffer. If the data cannot be converted into a byte buffer a TypeError is thrown (a RangeError is thrown if a number not within 0-255 was passed or used in an array). Generally cast supports passing in a single number (turned into a cap=1 buffer with that 0-255 number as it's only byte) : ;new ByteBuffer(capacity); ;new ByteBuffer(data); :Create a new ByteBuffer, you can also omit the `new` keyword and get the same result. ByteBuffer's constructor accepts any data that .cast accepts however using a number creates a buffer with that capacity, not a single byte buffer with that number inside it. Please use ByteBuffer.cast instead of the ByteBuffer constructor if you are trying to take foreign data and cast it to a ByteBuffer to use. Please note that calling ByteBuffer's constructor with an instance of another byte buffer will not create a copy of that buffer, it will create a buffer instance which is backed by the other buffer. In other words operations on the new buffer will affect the content of the buffer that was passed to it. ;.position; :The current position which relative operations will start at. Relative operations will throw an error when called if position is less than 0 or greater than limit. ;.limit; :The position where relative operations will stop. Relative operations will throw an error when called if limit is less than 0 or greater than capacity. ;.capacity; read-only; :The capacity this buffer has. ;.remaining; getter; :The number of elements remaining between the position and the limit. ;.reset(); :resets the position to 0, the limit to the capacity, and discards the mark. Use of this method implies that the data inside the ByteBuffer will still be the same after calling the method. Use this operation if you want to make sure that after the reset the actual data inside the buffer is the same. If you don't care about the actual content of the buffer please use .clear() instead, in some cases clear() can be more efficient than using .reset() because without the requirement of maintaining the content of the buffer it is sometimes possible for the implementation to optimise by avoiding heavy operations required to maintain the data when resetting the position and limit at the cost of scrambling the data within the buffer causing it to appear to the app differently than it was before the use of clear() ;.clear(); :resets the position to 0, the limit to the capacity, and discards the mark. Use of this method does not require that the data inside the buffer be the same after the method is called, the implementation is free to scramble the content of the buffer to anything it wants if it will optimise the performance of the buffer. If you do not care about the content of the buffer, please use this method instead of using .reset() or manually resetting the position and limit yourself. .reset() should only be used instead of .clear() if you require that the buffer's content be the same after calling it. ;.clone(); :Creates a new ByteBuffer with the same content, capacity, position, limit, and mark values. The new ByteBuffer is not backed by the content of this buffer, it is independent (writing to either buffer will not modify the contents of the other buffer). Please note that use of this method is preferable to manually creating a buffer with the same content. Manually copying the data will likely require that the data is actually copied. However using .clone only mandates that it looks like the data has been copied. This means that if a half-decent Copy-On-Write setup is used, it is possible for the act of using .clone() on a buffer, and then reading data from it may actually never to an expensive memory copy if the original buffer is never modified during that time. If you want to create a copy of a buffer with the same content but using an initial set of cap, pos, limit, and mark values it is potentially more efficient to call .clone().reset() than it is to create a new buffer and copy the data from the buffer into the new one. ;.range(); ;.range(start, stop); :Returns a new Buffer of the same class backed by a portion of this buffer. The new buffer will have a capacity and limit set to the size of the data the buffer is backing, and position of 0, the mark will be unset. If start and stop are not specified the new buffer will back the portion of the buffer which is currently between .position and .limit and the new buffer's capacity and limit will be equivalent to what this buffer's .remaining was. 525 2871 2010-07-16T09:43:29Z Dantman 1 <source> // Starts piping from streamA into streamB in the background and returns a concurrent promise streamA.pipeTo(streamB); // Start up two processes var cmdA = Process.start("cmdA"); var cmdB = Process.start("cmdB"); // Wrap some data in a ByteBufferStream and pipe it into the stdin of the first command new ByteBufferStream(someData).pipeTo(cmdA.stdin); // Pipe the first command's stdout into the second command's stdin cmdA.stdout.pipeTo(cmdB.stdin); // The stdout of the second command can be read cmdB.stdout; // ... // An example use... a poor man's gzip libraryless gzip var gzip = Process.start("gzip"); new ByteBufferStream(someData).pipeTo(gzip.stdin); gzip.stdout.pipeTo(...); // ... would be a stream such as the output stream for a http request /** Transfering data from one stream to another **/ // High-Level // // This starts the piping in the background in a separate thread, it returns a // concurrent promise you can wait on or register an async callback from.pipeTo(to); // Mid-Level // // This transfers data from one stream to another without using any js level buffer // In some cases like in Java where one of the streams is backed by a file // this can even try and avoid a deal of unnecessary copying. while ( !from.eof ) from.transferTo(to, 1024); // Low-Level var buf = new ByteBuffer(1024); // ... buf.clear(); while ( from.read(buf) >= 0 || buf.position ) { // If we read some data, or still have unwritten data buf.???(); // java calls it flip; We ready the buffer for writing by setting the limit to the position and resetting the position to 0 to.write(buf); buf.???(); // java calls it compact; The buffer is prepared in a way so that the next .read will put data into the unused portion of the buffer } </source> 526 2872 2010-07-22T18:32:21Z Wesgarland 13 Created page with '[[Real Name::Donny Viszneki]]' [[Real Name::Donny Viszneki]] 528 2880 2010-08-30T10:08:54Z Temsa 132 creation {{Implementation |name=RequireJS |url=http://requirejs.org |engines=web browsers, rhino }} 529 2887 2010-09-01T17:37:28Z IsaacSchlueter 52 tabs <h1 id="packages_registry">Packages/Registry</h1> <p>This specification describes a method for identifying package descriptors by a combination of name, version, and registry base URL.</p> <p>A package registry is considered &#8220;CommonJS Compliant package registry&#8221; if it implements the API described in this specification.</p> <p>The &#8220;client&#8221; refers to a package.json-aware system that uses a CommonJS Compliant package registry to locate packages.</p> <h2 id="scope">Scope</h2> <p>This API <em>only</em> describes identifying and locating packages. It specifically does not describe the mechanisms by which packages are added <em>to</em> the registry. It is assumed that each registry may implement different mechanisms for user authentication, package acceptance, package removal, and so on.</p> <p>Furthermore, this specification <em>only</em> dictates the behavior for the URLs it describes. Any URL which is not a valid registry root url, package root url, or package version url, is not defined by this specification.</p> <p>This API does not assume any particular implementation technology.</p> <h2 id="http_request_method_and_headers">HTTP Request Method and Headers</h2> <p>HTTP GET is the only method required for consuming the data in a package registry. Registries MAY use other methods for entering data into the registry, authenticating user accounts, and so on, but that is outside the scope of this specification.</p> <p>Clients SHOULD send an Accept header of <code>application/json</code>. Behavior of the registry in the presence of other Accept headers is undefined. For instance, a Compliant registry MAY send an HTML document description of a package if given the Accept value of <code>text/html</code>, or it MAY send JSON in all cases.</p> <p>Registries MUST send responses with an <code>application/json</code> Content-Type if the client sends an Accept header value of <code>application/json</code>.</p> <h2 id="http_errors">HTTP Errors</h2> <p>In the case of errors, registries SHOULD still send any response body in the form of valid JSON with an <code>error</code> member, and optionally any other useful information. For instance:</p> <pre>HTTP/1.1 404 Object Not Found Content-Length: 52 {"error":"not found","reason":"document not found"} </pre> <p>Registries MAY send back an empty response body, but any response body that is sent MUST be valid JSON.</p> <h2 id="urls">URLs</h2> <p>The following classes of urls are described:</p> <ul> <li>registry root url</li> <li>package root url</li> <li>package version url</li> </ul> <h3 id="registry_root_url">registry root url</h3> <p>Examples: <code>http://registry.npmjs.org/</code> <code>http://js.packag.es/registry/</code></p> <p>The root URL is the base of the package registry. Given this url, a name, and a version, a package can be uniquely identified, assuming it exists in the registry.</p> <p>When requested, the package root URL SHOULD return a list of packages in the registry in the form of a hash of package names to package root descriptors.</p> <p>The package root descriptor MUST be either: an Object that would be valid for the &#8220;package root url&#8221; contents for the named package, or a string URL that should be used as the <code>package root url</code>.</p> <p>In the case of a string URL, it MAY refer to a different registry. In that case, a request for <code>{registry root url}/{package name}</code> SHOULD be EITHER a 301 or 302 redirect to the same URL as named in the string value, OR a valid &#8220;package root url&#8221; response.</p> <p>The following would be a valid response for the package root url at <code>http://example.com/</code>.</p> <pre>{ "foo" : "http://foo.com/package/versions/foo" , "quux" : "http://example.com/quux" , "asdf" : "http://example.com/-/third-party/asdf" , "bar" : { "name" : "bar" , "maintainers" : [ { "name" : "isaacs", "email" : "i@izs.me" } ] , "mtime": "2010-08-29T23:10:47Z" , "versions" : { "1.0.0" : "http://example.com/bar/1.0.0" } } , "baz" : { "name" : "baz" , "versions" : { "1.0.0" : { "name" : "baz" , "version" : "1.0.0" , "main" : "./lib/baz.js" , "description" : "The bazziest!" , "dist" : { "tarball" : "http://example.com/-/baz-1.0.0.tgz" } } } } } </pre> <p>The &#8220;foo&#8221; package is a redirect to another registry. The &#8220;quux&#8221; package is served from the typical URL on this registry, but not listed in the registry root response. The &#8220;asdf&#8221; package is served from this registry, but at a different URL. The &#8220;bar&#8221; package lists top-level information but supplies a URL for specific versions. The &#8220;baz&#8221; package lists top-level information as well as package descriptors for specific versions.</p> <h3 id="package_root_url">package root url</h3> <p>The package root url is the base URL where a client can get top-level information about a package and all of the versions known to the registry.</p> <p>A valid &#8220;package root url&#8221; response MUST be returned when the client requests <code>{registry root url}/{package name}</code></p> <h4 id="redirection">Redirection</h4> <p>The package root URL SHOULD be found at <code>{registry root url}/{package name}</code>. If the registry would rather proxy to a different URL for a specific package, then it MUST respond with a 301 or 302 status code and a Location header to the desired address. It MAY send a JSON response body with a &#8220;location&#8221; field containing the intended location. For example, requesting <code>http://example.com/foo</code> in the previous example might return this:</p> <pre>HTTP 1.1/302 Found Location: http://foo.com/package/versions/foo Content-Type: application/json Content-Length: 54 { "location" : "http://foo.com/package/versions/foo" } </pre> <p>Redirection may also be used within the same host if the registry wishes to serve package root information from a different location than <code>{registry root url}/{package name}</code>.</p> <h4 id="package_root_object">Package Root Object</h4> <p>The root object that describes all versions of a package MUST be a JSON object with the following fields:</p> <ul> <li>name: The name of the package. When both are decoded, this MUST match the &#8220;package name&#8221; portion of the URL. That is, packages with irregular characters in their names would be URL-Encoded in the request, and JSON-encoded in the data. So, a request to <code>/%C3%A7%C2%A5%C3%A5%C3%B1%C3%AE%E2%88%82%C3%A9</code> would show a package root object with &#8220;\u00e7\u00a5\u00e5\u00f1\u00ee\u2202\u00e9&#8221; as the name, and would refer to the &#8220;ç¥åñî∂é&#8221; project.</li> <li>versions: An object hash of version identifiers to valid &#8220;package version url&#8221; responses: either URL strings or package descriptor objects.</li> </ul> <p>The following fields are optional, and thus MAY be present in the package root response. If they are present, then they MUST have the meanings described:</p> <ul> <li>mtime: The last modified time of the package root object, expressed as an ISO String.</li> <li>ctime: The creation time of the package root object, expressed as an ISO String.</li> <li>maintainers: An array of identifiers of package registry users who maintain the package described.</li> <li>repository: The repository where the project source is managed. This SHOULD match the repository field on the most recently published version of the package.</li> <li>url: A URL where the package root object can be found. (This is largely unnecessary in the case of requesting a package root object directly, but can be helpful with abbreviated package root objects are returned in the registry root response.)</li> <li>description: A description of the project. This SHOULD match the description field on the most recently published version of the package.</li> </ul> <h3 id="package_version_url">package version url</h3> <p>The package version url is the base URL where a client can get package descriptor information about a specific version of a package.</p> <p>A valid &#8220;package version url&#8221; response MUST be returned when the client requests <code>{registry root url}/{package name}/{package version}</code></p> <h4 id="redirection">Redirection</h4> <p>The package version URL SHOULD be found at <code>{registry root url}/{package name}/{package version}</code>. If the registry would rather proxy to a different URL for a specific package version, then it MUST respond with a 301 or 302 status code and a Location header to the desired address. It MAY send a JSON response body with a &#8220;location&#8221; field containing the intended location. For example, requesting <code>http://example.com/foo/1.0.0</code> in the previous example might return this:</p> <pre>HTTP 1.1/302 Found Location: http://foo.com/package/versions/foo/1.0.0 Content-Type: application/json Content-Length: 60 { "location" : "http://foo.com/package/versions/foo/1.0.0" } </pre> <p>Redirection may also be used within the same host if the registry wishes to serve package root information from a different location than <code>{registry root url}/{package name}/{package version}</code>.</p> <p><strong>Note</strong>: In this example, the &#8220;foo&#8221; package root was served on a different registry. If that registry is also a CommonJS Compliant Package Registry, then tacking <code>/1.0.0</code> onto the package root URL would be a valid package version url.</p> <h4 id="package_version_object">Package Version Object</h4> <p>The Package Version Object is almost identical to the Package Descriptor object described in the CommonJS Packages specification. For the purposes of the package registry, the following fields are required. Note that some of these do not exist in the Packages specification.</p> <ul> <li>name: The package name. This MUST match the <code>{package name}</code> portion of the URL.</li> <li>version: The package version. This MUST match the <code>{package version}</code> portion of the URL.</li> <li>dist: An object hash with urls of where the package archive can be found. The key is the type of archive. At the moment the following archive types are supported, but more may be added in the future: <ul> <li>tarball: A url to a gzipped tar archive containing a single folder with the package contents (including the package.json file in the root of said folder)</li> </ul></li> </ul> <h2 id="changes_to_packages_spec">Changes to Packages Spec</h2> <p>Besides the addition of fields to the Package Version Object, this addition to the Packages spec imposes the following restrictions on the &#8220;name&#8221; and &#8220;version&#8221; fields:</p> <ol> <li>MUST NOT start with &#8220;-&#8220;</li> <li>MUST NOT contain any &#8220;/&#8221; characters</li> <li>MUST NOT be &#8220;.&#8221; or &#8220;..&#8221;</li> <li>SHOULD contain only URL-safe characters</li> </ol> <p>This makes it simpler for package names and versions to map to a URL scheme. Since they may not start with &#8220;-&#8220;, this makes it possible for registry owners to &#8220;escape&#8221; from the package registry on the same hostname.</p> <p>For example, a package registry owner might wish to serve the tarball for &#8220;foo&#8221; version 1.0.0 from <code>http://example.com/foo/-/foo-1.0.0.tgz</code>. Since <code>-</code> is never a valid version, this will not be interpreted as a request for package data. (See &#8220;Scope&#8221; above.)</p> <h3 id="changes_to_package_dependencies">Changes to Package Dependencies</h3> <p>The package <code>dependencies</code> hash may now be augmented with information about which registry is to be queried for matching dependencies. A <code>registry</code> field may be provided:</p> <ol> <li>at the top level of the package.json descriptor</li> <li>individually for each dependency. In this case, the dependency name is the key, and the value is an object with &#8220;version&#8221; and &#8220;registry&#8221; strings.</li> </ol> <p>If a registry is provided, then it MUST be the registry root url of a CommonJS Compliant Package Registry. If provided, clients SHOULD query this registry for package data. If not provided, then clients MAY default to any or no registry URL.</p> <p>For example:</p> <pre>{ "name" : "foo" , "registry" : "http://example.com/registry/" , "dependencies" : { "bar" : "1.0.2" , "baz" : { "version" : "1.2.3" , "registry" : "http://baz.com/packages/" } } } </pre> <h2 id="prior_art">Prior Art</h2> <ul> <li>npm Registry http://registry.npmjs.org/</li> </ul> 530 2891 2010-09-07T03:28:36Z Kriszyp 39 {{Spec |status=proposal |standard=yes }} == Packages Transport == This specification describes how to transport contents of a CommonJS package from a server to an asynchronous browser-based client side loader. Given the URL of a package, regardless of the domain of the package (whether it be the same as the requested page or not) a client side loader should be able to load the metadata of the package and modules within that package based on a module id within the package. == Specification == A package that is intended to be available for client side usage and complies with this specification SHOULD provide a "package.js" resource at the root URL of the package. This module SHOULD provide the client with package metadata by calling the require.package function. A package.js resource, as well as any other JavaScript resource in the package, may call require.def or require.define, as defined by the Modules Transport specification to register modules (package.js may include module definitions in order to avoid multiple requests). However, the require.package call SHOULD proceed any require.def calls. == require.package == The require.package function must take a single argument that is a JavaScript object that corresponds to the package metadata. The properties of the package metadata object should follow the CommonJS package specification. For example, a package.js could include: require.package({ name: "foo", description: "some package" }); Any require.def calls that exist in the package.js after the require.package call MAY use relative module ids to identify themselves. The module id should be resolved relative to the lib root of the package. == Background == * [http://groups.google.com/group/commonjs/browse_thread/thread/51e760229cd0d933 Cross-domain loading of package metadata] 531 2894 2010-09-07T23:07:51Z KrisKowal 6 Created an index for the mappings topic = Proposals = * [[/A]] Kris Zyp * [[/B]] Kris Kowal based on A * [[/C]] Kris Kowal based on B * [[/D]] Gozala based on C 532 2907 2010-09-28T01:29:40Z Kriszyp 39 {{Spec |status=proposal |implementations=RequireJS, Nodules, Yabble }} The Asynchronous Module Definition API specifies a mechanism for defining modules such that the module and it's dependencies can be asynchronously loaded. This is particularly well suited for the browser environment where synchronous loading of modules incurs performance, usability, debugging, and cross-domain access problems. This specification used to be called Modules Transport/C, but this is specification is not primarily geared for transported existing CommonJS modules, but for defining modules (although it can be used as a transport). == Specification == The specification defines a single function "def" that should be available on the "require" free variable. The signature of the function: require.def(id?, dependencies?, factory); The first argument, id, specifies the id of the module being defined. This argument is optional, and if it not present, the module id should default to the id of the module that the loader was requesting for the given response script. When present, the module id MUST be an absolute id (relative ids are not allowed. The second argument, dependencies, is an array of the dependencies that are required by the module that is being defined. The dependencies must be resolved prior to execution of the module factory function, and the resolved values should be passed as arguments to the factory function with argument positions corresponding to index in the dependencies array. The dependencies ids may be relative ids, and should be resolved relative the module being defined. This specification defines three special dependency names that have a distinct resolution. If the value of "require", "exports", or "module" appear in the dependency list, the argument should be resolved to the corresponding free variable as defined by the CommonJS modules specification. This argument is optional. If omitted, it should default to ["require", "exports", "module"]. However, if the factory function's arity (length property) is less than 3, than the loader may choose to only call the factory with the number of arguments corresponding to the function's arity or length. The third argument, factory, is a function that should be executed to instantiate the module or an object. If the factory is a function it should only be executed once. If the factory argument is an object, that object should be assigned as the exported value of the module. If the factory function returns a value (an object, function, or any value that coerces to true), and then that value should be assigned as the exported value for the module. If both the first argument (module id) and the second argument (dependencies) are omitted, the module loader MAY choose to scan the factory function for dependencies in the form of require statements (literally in the form of require("module-string")). The first argument must literally be named require for this to work. In some situations module loaders may choose not to scan for dependencies due to code size limitations or lack of toString support on functions (Opera Mobile is known to lack toString support for functions). If either the first or second argument is present, the module loader SHOULD NOT scan for dependencies within the factory function. === Transporting more than one module at a time === Multiple require.def calls can be made within a single script. The order of the require.def calls SHOULD NOT be significant. Earlier module definitions may specify dependencies that are defined later in the same script. It is the responsibility of the module loader to defer loading unresolved dependencies until the entire script is loaded to prevent unnecessary requests. == Examples == === Using require and exports === Sets up the module with ID of "alpha", that uses require, exports and the module with ID of "beta": require.def("alpha", ["require", "exports", "beta"], function (require, exports, beta) { exports.verb = function() { return beta.verb(); //Or: return require("beta").verb(); } }); === Usage notes === It is recommended that require.def calls be in the literal form of 'require.def(...)' in order to work properly with static analysis tools (like build tools). 533 2899 2010-09-10T02:01:54Z Kriszyp 39 {{Spec |status=proposal |standard=yes }} == Asynchronous Package Definition == This specification describes how to define the contents of a CommonJS package with an asynchronous API, specifically to facilitate loading packages in a browser. Given the URL of a package, regardless of the domain of the package (whether it be the same as the requested page or not) a client side browser-based loader should be able to load the metadata of the package and modules within that package based on a module id within the package. == Specification == A package that is intended to be available for client side usage and complies with this specification SHOULD provide a "package.js" resource at the root URL of the package. This module SHOULD provide the client with package metadata by calling the require.package function. A package.js resource, as well as any other JavaScript resource in the package, may call require.def or require.define, as defined by the Asynchronous Module Definition [http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition] specification or Modules Transport [http://wiki.commonjs.org/wiki/Modules/Transport/D] specification to register modules (package.js may include module definitions in order to avoid multiple requests). However, the require.package call SHOULD proceed any require.def calls. == require.package == The require.package function must take a single argument that is a JavaScript object that corresponds to the package metadata. The properties of the package metadata object should follow the CommonJS package specification. == Example == A package.js could include: require.package({ name: "foo", description: "some package" }); Any require.def calls that exist in the package.js after the require.package must use provide module ids (they can not be anonymous, without their first parameter) to identify themselves. == Background == * [http://groups.google.com/group/commonjs/browse_thread/thread/51e760229cd0d933 Cross-domain loading of package metadata] 534 2901 2010-09-21T14:26:27Z Gozala 22 Created page with '=Unit Testing/1.1= ==STATUS: Draft== ==Specification== This specification adds following features no top of [http://wiki.commonjs.org/wiki/Unit\_Testing/1.0,Unit Testing/1.0]:…' =Unit Testing/1.1= ==STATUS: Draft== ==Specification== This specification adds following features no top of [http://wiki.commonjs.org/wiki/Unit\_Testing/1.0,Unit Testing/1.0]: * Mechanism for running tests in <strong>fail-slow</strong> mode (where failed assertions just log) on the side to <strong>fail-fast</strong> mode (where failed assertions fails entire test). * Mechanism for running tests in <strong>asynchronous</strong> mode. ==="Fail-slow" Mode=== All the test functions that would like to run tests in <strong>fail-slow</strong> mode <strong>must</strong> expect to be called by test runner with a first special argument (for simplicity we'll be referring to it as <tt>test</tt> named argument): * <tt>typeof</tt> <tt>test</tt> is <tt>"function"</tt>. It <strong>may</strong> be called with an arguments: assertion function described by [http://wiki.commonjs.org/wiki/Unit\_Testing/1.0,Unit Testing/1.0] followed by any number of arguments. * <tt>test</tt> function <strong>must</strong> perform assertion by calling first argument (assertion function) by passing through all the arguments starting form second (including all the optional defaulting to <tt>undefined</tt> even if they where not passed to <tt>test</tt>) plus <tt>test</tt> as a last argument. * <tt>test</tt> function <strong>must</strong> log results for the performed assertion instead of failing a test. * <tt>test</tt> function <strong>must</strong> log test failure if performed assertion throws exception other then <tt>AssertionError</tt>. * <tt>test</tt> named argument <strong>must</strong> contain following own properties: <tt>passes</tt>, <tt>fails</tt>, <tt>errors</tt>. <tt>typeof</tt> of all this properties must be <tt>number</tt> and they should represent number of assertions passed, assertions failed, errors occurred. <source>var assert = require("assert") , planned = require('test-addons').planned exports.testSample = function(test) { test(assert.equal, actual, expected, message_opt) test(assert.notEqual, actual, expected) test(planned, actual, expected, message_opt) } </source> <strong>Notes:</strong> * Future versions of this spec <strong>may</strong> add additional properties to the first named argument <tt>test</tt>. * Test functions are backwards compatible and <strong>must</strong> allow running tests in mixed (<strong>fail-slow</strong>, <strong>fail-fast</strong>) mode. ===Asynchronous Mode=== All the test functions that would like to run tests in <strong>asynchronous</strong> mode must expect second named argument. Such test functions will have special behavior: * Asynchronous test functions <strong>must</strong> be called with a second argument (for simplicity we'll be referring to it as <tt>done</tt> named argument). * <tt>typeof</tt> <tt>done</tt> named argument passed to the asynchronous test functions must be <tt>"function"</tt>. * Test runner <strong>must</strong> consider asynchronous test being finished only after calling <tt>done</tt> named argument. * All the assertions performed for the test that is finished (after it called <tt>done</tt>) <strong>must</strong> be logged as errors for that test. * All the calls to the <tt>done</tt> function for the test that is finished (after it called <tt>done</tt>) <strong>must</strong> be logged as an errors for that test. <source>var assert = require("assert") exports.testAsync = function(test, done) { var xhr = new XMLHttpRequest() xhr.open('GET', 'http://foo.com/', true) xhr.onreadystatechange = function listener(e) { if (req.readyState == 4) { test(assert.equal, xhr.status, 200) test(assert.equal, xhr.responseText, 'bar') } } xhr.send(null) // verify results setTimeout(function timeout() { test(assert.equal, test.passes + test.fails, 2, 'two assertions expected') done() }, 3000) } </source> 535 2906 2010-09-28T01:26:43Z Kriszyp 39 Created page with '{{Implementation |name=Nodules |url=http://github.com/kriszyp/nodules |engines=node, narwhal }}' {{Implementation |name=Nodules |url=http://github.com/kriszyp/nodules |engines=node, narwhal }} 538 2912 2010-09-30T22:00:38Z Hypernado 135 Work-in-progress JavaScript platform. {{Implementation |name=Dasquillette |url=http://dasquillette.hypernado.com/ |engines=JSC |authors=Hypernado |description=Work-in-progress open-source, JavaScriptCore-based, CommonJS-complying JavaScript platform. Will eventually implement the entire CommonJS standard. Also will include a full JavaScriptCore Objective-C wrapper. }}