Status: BETA - Mostly stable API undergoing wider testing.
The PINF JavaScript Loader asynchronously combines what you would traditionally call a package installer and class loader and is intended to be used as the core to all your JavaScript applications no matter what platform they run on.
The loader allows for bootstrapping a state-of-the-art, consistent and portable CommonJS environment
for any supported platform (on servers, in browsers, desktop applications, secure sandboxes, and embedded) and thus
is ideally suited to be used as the target for the commonjs command (currently being standardized) and the
development of cross-platform JavaScript applications and libraries that may be shared with the CommonJS ecosystem.
This module loader brings CommonJS Modules/2 (currently in draft) plus CommonJS Packages, Package Mappings and further concepts to the following platforms:
commonjs- Use it as a target for thecommonjscommand being standardized- NodeJS - Use it in any NodeJS application (Default CLI and utility platform until API adapters come along)
- Jetpack - Use it in any Gecko/XULRunner extension or application
- v8cgi - Use it in any v8cgi application
- GPSEE - Use it in any GPSEE application
- RingoJS - Use it in any RingoJS application
- Narwhal - Use it with any Narwhal engine platform
- Titanium - Use it in any Appcelerator Titanium application
- AdobeAir - Use it in any AdobeAir application
- Wakanda (In Progress)
- CouchApp (Initial exploration)
- PhoneGap (Initial exploration)
- Rhino (Not Yet Implemented)
- Browser - For development and optimized production purposes
- BravoJS - Default browser loader with full CommonJS package support (11.8 KB minified & gziped)
- PINF Browser Loader - Optimized production browser loader with goal of < 3 to 5 KB minified & gziped (Not Yet Implemented)
- NobleJS (Not Yet Implemented)
- RequireJS (Not Yet Implemented)
- bdLoad (Not Yet Implemented)
- Dojo (Not Yet Implemented)
- Services
- no.de (Not Yet Implemented)
- NodeSocket (Not Yet Implemented)
- Google App Engine Use it to run JavaScript on the Java stack (Not Yet Implemented)
The loader implements or is compatible with the following specs:
- CommonJS Modues/1.1.1 (approved)
- CommonJS Modues/2.0draft8 (draft)
- CommonJS Modules/AsynchronousDefinition (proposal) (partial)
- CommonJS Packages/1.1 (draft)
- CommonJS Packages/Mappings/C (proposal)
- CommonJS Modules/LoaderPlugin (proposal) (partial)
The loader extends the core CommonJS platform defined by the above specifications with the following additions:
- CommonJS Programs/A (strawman) (Not Yet Documented)
- Various additions and generalizations to be able to load a wide range of packages. (Not Yet Documented)
The loader can be used:
- By calling it from the command line to run a program
- By
require()ing it from any CommonJS module to load a sub-program - By setting it up as a package server to load programs into a browser
- To export CommonJS programs to be loaded by CommonJS compliant loaders
The loader:
- Aims to be complete and fully specification compliant where possible.
- Aims to validate the CommonJS Program and Mappings approaches and inform CommonJS specifications.
- Provisions and executes programs by downloading and linking dependencies on first use.
- By default isolates the dependencies for each program.
- Can provision complex applications (programs) composed of hundreds of packages by contacting an open network of public registry and repository servers. (Not Yet Implemented)
- Can load complex applications (programs) composed of hundreds of packages from Content Delivery Networks fed by a simple program server. (Not Yet Implemented)
- Supports REMOTE LIVE application DEBUGGING and EDITING for DEPLOYED applications running on any ANY PLATFORM (
eval()or equivalent required). (Not Yet Implemented)
The loader is a sub-project of the PINF Toolchain Automation Platform where an application (program) is a view into the toolchain that statically links package-based dependencies.
The toolchain is an organized body of code & services maintained collectively for the purpose of automating software production and system operation. Any CommonJS package may be used as part of the toolchain.
Minimum Requirements:
- UNIX system (Windows support is under development but still has some way to go)
- NodeJS: http://nodejs.org/
Use any one of the following install solutions:
npm install -g pinf-loader-js
cd ~/
wget -O pinf-loader-js.tar.gz https://github.com/pinf/loader-js/tarball/master
tar -zxf pinf-loader-js.tar.gz
mv pinf-loader-js-* pinf-loader-js
alias commonjs='~/pinf-loader-js/pinf-loader.sh'
cd ~/
git clone git://github.com/pinf/loader-js.git pinf-loader-js
alias commonjs='~/pinf-loader-js/pinf-loader.sh'
Make sure it works:
commonjs -h
To install additional platforms (other than node) see:
- Individual platform projects
- PINF JavaScript Platform for OSX Lion (includes all supported platforms)
To run the loader on a different platform (other than node) use:
commonjs --platform <PlatformAlias> ...
Where <PlatformAlias> is any of node, gpsee, v8cgi, narwhal or ringo.
NOTE: Not all features are supported on all platform yet due to incomplete API adapters.
commonjs -v --platform node https://github.com/pinf/test-programs-js/zipball/master --port 8081 HelloWorld
More demos:
- User friendly: See the PINF JavaScript Test Programs project.
- Internal/development: See ./docs/Demos.md.
-
High-level Introduction (presentation slides)
-
Setup - Setup your
commonjscommand. -
Demos - Looking at the source code of the demos is a good place to start.
-
Use Cases - The loader can be used in various ways.
-
Writing Programs - A quick introduction.
-
Source Overlays - Use cloned source code instead of downloaded archive for a package.
-
Compare to other loaders (third party link)
Related Projects:
- Cross-platform tests via the PINF JavaScript Test Programs project.
- Mailing list: http://groups.google.com/group/pinf-dev/
- Twitter: http://twitter.com/pinf
- Blog: http://christophdorn.com/Blog/
- Clean hierarchical sandbox implementation.
- Refactored and abstracted program server to support various plugins.
- Consistent and reliable file and line info for errors and stack traces across all platforms.
- Run exported programs on various browser loaders (RequireJS, NobleJS) in addition to BravoJS.
- Remove color characters when printing to browser consoles and buffer until newline
- Profiling code in loader to time various things with an option to monitor interpreter spawn/load time as well.
- Refactor to leverage Q promises throughout.
- Run exported programs on all platforms (not just browser).
- Refactor, abstract and simplify various concepts like descriptors, locators, mapping resolver.
You can find a list of things to get involved with here: ./NOTES.md
Collaboration Platform: https://github.com/pinf/loader-js/
Collaboration Process:
- Discuss your change on the mailing list
- Write a patch on your own
- Send pull request on github & ping mailing list
- Discuss pull request on github to refine
You must explicitly license your patch by adding the following to the top of any file you modify in order for your patch to be accepted:
// - <GithubUsername>, First Last <Email>, Copyright YYYY, MIT License
This project is a part of the PINF project maintained by Christoph Dorn.
This project would not be possible without the following:
- CommonJS - For framing requirements into specifications
- BravoJS - For a pure and clean CommonJS Modules/2 loader implementation
- NodeJS - For providing a solid runtime used by default
- Firefox - For providing an amazing browser platform
- Jetpack - For providing a decent extension environment, API and tooling
- Firebug - For the amazing developer tool it is
- nodules - For implementing and refining CommonJS Packages/Mappings/C
- pinf - For implementing and refining various designs and specifications
- Narwhal - For providing an experimentation ground while prototyping conceps
- Github - For igniting a generation of collaborative development
- JavaScript - For the awesome language it is
This project uses code from:
- http://code.google.com/p/bravojs/
- http://narwhaljs.org/
- https://github.com/Gozala/light-traits/
- https://github.com/Gozala/jetpack-protocol/
- http://pajhome.org.uk/crypt/md5/sha1.html
- http://membres-liglab.imag.fr/donsez/cours/exemplescourstechnoweb/js_securehash/md5src.html
- http://www.webtoolkit.info/javascript-base64.html
Creative Commons Attribution-NonCommercial-ShareAlike 3.0
Copyright (c) 2011+ Christoph Dorn
Copyright (c) 2011+ Christoph Dorn
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.