require.md

From System Module

require('<module>')  // search require.paths
require('./<module>')  // resolve relative then search require.paths
require('<module>', '<package>') // module from package

or

require('system#<module>')  // search require.paths
require('./<module>')  // resolve relative then search package (system package == require.paths)
require('<package>#<module>') // module from package

From Using Module

require('<module>')  // search require.paths
require('./<module>')  // resolve relative then search package
require('<module>', '<package>') // module from package

or

require('system#<module>')  // search require.paths
require('./<module>')  // resolve relative then search package
require('<package>#<module>') // module from package

Notes

• Whenever <package> is specified the module loads within a package context limiting relative searches to the package. The owning package of a module can be identified by module["package"]
• On startup the package context is undefined defaulting to system module behaviour. No module["package"] defined
• Relative paths ../../../../ may not point outside of require.paths nor package
• If <package> does not match an alias for a package descriptor in package.json it is matched against <sea>/using/<package>/package.json in which case <package> is called a top-level ID

Links

• http://groups.google.com/group/commonjs/browse_thread/thread/17442874b369da5d/4889f98435c52fc2
• http://pastie.org/716205
  • (cadorn) the canonical form is the top-level ID which is determined based on /using//package.json my pitch is to add to form /using///package.json where is the "version" (keyword (e.g. master as in master branch), git ref, svn revision, ...) to identify the package identified by at a particular point in time