Mapping

Paths in 0.5

work in progress (actually, this is just notes at this point!)

Goals

1. Allow devs to place packages and resources wherever they wish
2. Allow several use cases or module and package mapping (see below)
3. Only download a given module or resource once, regardless of aliases, mappings
4. Make it simple to do the easy stuff and possible to do the edge cases

Use cases (most common first)

Package Location

• use case
  • "my package is located at this url"
• configuration
  • location of lib folder
  • location of main js file (if any)
• algorithm
  • ./moduleId and ../moduleId are first normalized to parent moduleId:
    • parentId/moduleId or grandparentId/moduleId (grandparent may be undefined)
  • normalized module ids are mapped to urls via lib location
  • urls are canonicalized

Plugin Alias

• use case
  • "I want all text! plugins to use the module named x/text" (module id)
• configuration
  • alias mapping (text --> curl/text)
• algorithm
  • matching plugin module ids are translated to alias module ids
  • alias module ids are mapped to urls via package location mappings
  • urls are canonicalized

Package Versions

• use case
  • "I want calls to 'x/a' from one package to reference 'x1.5/x/a' but calls to 'x/a' from another package to reference 'x1.6/x/a'"
• configuration
  • ? (check out commonjs proposals?)
• algorithm
  • ?

False Packages

• use case
  • "I want to alias calls to a generic 'array' module to the module named 'y/array'" (or vice versa. see chat with JD Dalton)
• configuration
  • alias/name of fake package (array)
  • actual name of module in package (y/array)
• algorithm
  • if a request is made for a false package, the actual parent module id is provided in context
  • algorithm proceeds as normal Package Location use case

Aliased Package

• use case
  • "I want to alias calls to 'my/array' to 'y/array'"
• configuration
  • alias/name of fake package (array)
  • actual name of module in package (y/array)
• algorithm
  • if a request is made for an alias package, the actual parent module id is provided in context
  • algorithm proceeds as normal Package Location use case

Root Packages

• use case
  • "I want to use root paths like in node.js ("/x/b" should be the same as "x/b" unless we implement a way to have each package specify its relative dependency paths)
• configuration
  • same as regular packages (except see comment above)
• algorithm
  • same as regular packages (except see comment above)

Monkey Patch

• use case
  • "I want to fix this module by replacing it on-the-fly with mine"
• configuration
  • mapping of original name to patched module name
• algorithm
  • if a request is made for he original module, a patched module id is provided in context
  • algorithm proceeds as normal Package Location use case

Non-module Resources

• use case
  • "I want to load this resource named x/y from url a/b/c"
• configuration
  • mapping of name to url
• algorithm
  • ?

Configuration

mappings: {

// simple package with no main module
// or main module is peer to lib folder of same name
'packageA': 'path/to/packageA',

// package with a main module
'packageB': {
	lib: 'path/to/packageB/lib',
	main: 'path/to/packageB/main'
},

// package with a versioned dependency
'packageC': {
	lib: 'path/to/packageC/lib',
	main: 'path/to/packageC/main',
	mappings: {
		'packageA': 'path/to/packageA-0.7'
	}
},

// false package
'array': 'packageA/array',

// aliased package
'my/query': 'packageB/query',

// plugin mapping
'text': 'curl/text',

// monkey patched module
'packageB/model': 'my/model',

//non-module resource
'my/templates': 'some/other/place/templates'

}

Algorithm