wakanda-node

About

Wakanda

Wakanda is a Web Application platform that propose a sever at its core with a NoSQL Object JS/REST database engine, some HTTP services, a facultative front-end framework, and a development tool suite. It integrates nicely with third party frameworks and dev tools and is highly customisable.

To make its Server-Side JavaScript as most standard and compatible with Client-Side JavaScript as possible, Wakanda has been mostly based on the native support of CommonJS and HTML5 API on the server like

• W3C Blob
• W3C FileSystem
• W3C Web Sockets (from Wakanda 9)
• W3C Web Storage
• W3C Web Workers
• W3C XMLHttpRequest

but it still already support some node.js API including:

• Assertion Testing
• Buffer
• Crypto (partial)
• Events
• Net
• Process (partial & partial documentation)
• TLS (partial)

wakanda-node

This wakanka-node package is meant to add more node.js API support to Wakanda Server to make more node.js modules compatible with Wakanda (and to also directly bring additionnal nice features for your own code).

This is mostly done using some original node.js JavaScript source files from its official github repository (MIT licensed), but also includes some patches and polyfils to make Wakanda even more node compliant.

Current wakanda-node version is based on Wakanda 8 & node.js 0.11.13

Additional Node.js API

This version of the package add the following API:

• Globals (local node doc) (partial support)
  • global (ok)
• Os (local node doc) (partial support)
  • used via the global os variable or via require('os')
  • works on MacOS, should work on Linux, not yet on Windows (in progress)
  • only miss os.cpus(), os.freemem(), and os.uptime()
• Punycode: (local node doc) (experimental)
  • used via require('punnycode')
  • unit tests: UNSTABLE (fail first, then pass)
• Path (local node doc)
• Process (local node doc) (partial support)
  • used via the global process variable
  • process.arch (ok)
  • process.platform (ok)
  • process.env (ok)
  • process.versions (partial, wakanda don't have all the same components)
  • process.binding (ok to load internal modules ported in JS, may also use requireNative() in the future)
• Query Strings: (local node doc)
  • used via require('querystring')
  • unit tests: PASSED
• Url: (local node doc)
  • used via require('url')
  • unit tests: PASSED
• Utilities: (local node doc)
  • used via require('util')
  • unit tests: PASSED

How to use

Once installed, just start your code with this simple line

require('wakanda-node');

All code that will then be executed in this thread, either from the same file, included files, or modules loaded with require()), will have access to the additionnal Node.js API.

If you call a dedicated or shared worker that need such additionnal node.js API, make sure to initialize them with this line too

TIPS:

This code be added to the required.js file at the project or solution level to automatically initialise all of their Wakanda threads with wakanda-node

Architecture

index.js

• Add lib_node and lib to the require() paths so it can find the additionnal core node modules
• Load polyfils for global and process

binding

• Polyfils written in JS of C node.js modules called from JavaScript via process.binding(id)

doc_node

• Contains conform copies of some node.js Markdown doc files from the "doc/api" folder of its official github repository

lib

• Polyfil files to extend current Wakanda support of some node.js API

lib_node

• Contains conform copies of some node.js JavaScript source files from the "lib" folder of its official github repository

test

• Script used to launch the official node.js unit tests (see folder test_node)

test_node

• Contains conform copies of the node.js test suite files from the "test" folder of its official github repository

What next?

wakanda-node future

One of the goals of wakanda node (as is the one of Apache Cordova), is to become useless because of future full native node API support. In a perfect world such package would also make wakanda 100% node.js compliant, as perfect polyfill. Unfortunatly few things can not be done that easily like __filenameand __dirname (I'd recommend modules authors to use module.filename instead).

There is still few interestings things that could potentially be done in pure JS in this package

• integration of String Decoder, Stream (in progress)
• an alternative require() version to support nodes_modules folders and a node specific caching mechanism
• a File System (fs) polyfil via the Wakanda/W3C Filesystem API
  • -> may also partially work client-side
• a Child Processes (child_process) polyfil via the Wakanda/W3C Web Worker API
  • -> may also partially work client-side
• few more...

Might be interesting to see if emscripten could convert some of the node.js C modules into some working JS ones, but I must confess I don't put much hope in that (worth at least a try for fun).

wakanda future

In the meantime, the Wakanda team will probably add more node.js API support too. It looks like the command line API is going to get better in Wakanda 9, potentially via more node.js process API support (stdin, stdout, stderr, and env ?)

Contributions

Any contribution is welcome :-)

Communication

If it looks interesting to you, don't hesitate to watch it, start it, and share it with your communities via twitter, G+, linkedin, facebook, your forums, mailing lists, or blog. The more people use it, the more I will be able to enhance it.

Feedbacks

Please if you need it, or want to have fun, test it, use it, and post me issues, either to give your own implementation priorities (feature requests) or some bug reports.

Feel free to participate to the wakanda-node community wiki to share a list of node modules you successfully used on wakanda, with or without wakanda-node (some working without wakanda-node are already listed in the Wakanda-Packages/wakanda-modules github repository)

Pull Requests

You know node.js, or wakanda, or JavaScript, or some of the internal libraries used by node (ares, uv, http_parser, ...)? You can probably participate, make a fork, and send Pull Requests. Please consider creating dedicated branches, integrating unit tests and documentation, by I still will look at anything you'll submit (as long as it is pertinent). By sending "Pull Requests", you give permissions to use your code under the wakanda-node MIT License.

License

Copyright (c) 2014 Alexandre Morgaut

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.