Library Packages

Library Packages

In our move to using package.json for our widget libraries, we need to consider some issues with how the library packages are constructed. Maqetta can read a library if it contains both widget metadata and maqetta metadata. However, a library may not always come with metadata (i.e. see the current content of the Dojo Foundation Registry). For that reason, Maqetta must be allowed to load a library and its metadata from different sources.

In order to accomlish this, we'll need to allow the creation of packages for metadata, with dependencies on the library package. A library and metadata can come in 3 distinct package configurations:

• A package for the library + widget metadata + Maqetta metadata.
• One package for the library + widget metadata; one package for the Maqetta metadata.
• One package for the library; one package for the widget metadata; one package for the Maqetta metadta.

1. Single package for library & metadata

Package layout:

+ package.json
+ library/
   +-- main.js
+ metadata
   |-- library/
   |    +-- main_oam.json
   +-- widgets.json

package.json:

{
	"name": "library",
	...
	"directories": {
		"lib": "library"
	},
	...
	"overlays": {
		"oam": {
			"directories": {
				"metadata": "metadata/library"
			}
		},
		"maqetta": {
			"directories": {
				"widget_metadata": "metadata/widgets.json"
			}
		}
	}
}

2. Package for library & widget metadata, another for Maqetta metadata

Library and widget metadata

package layout:

+ package.json
+ library/
   +-- main.js
+ metadata
   +-- library/
        +-- main_oam.json

package.json:

{
	"name": "library",
	"version": "v1.0",
	...
	"directories": {
		"lib": "library"
	},
	...
	"overlays": {
		"oam": {
			"directories": {
				"metadata": "metadata/library"
			}
		}
	}
}

Maqetta metadata

package layout:

+ package.json
+ metadata
   +-- widgets.json

package.json:

{
	"name": "library-maq",
	...
	"dependencies": {
		"library": "v1.0"
	},
	...
	"overlays": {
		"maqetta": {
			"directories": {
				"widget_metadata": "metadata/widgets.json"
			}
		}
	}
}

3. Individual packages for library, widget metadata and Maqetta metadata

Library

package layout:

+ package.json
+ library/
   +-- main.js

package.json:

{
	"name": "library",
	"version": "v1.0"
	...
	"directories": {
		"lib": "library"
	}
}

Widget metadata

package layout:

+ package.json
+ metadata
   +-- library/
        +-- main_oam.json

package.json:

{
	"name": "library-oam",
	"version": "v1.0",
	...
	"dependencies": {
		"library": "v1.0"
	},
	...
	"overlays": {
		"oam": {
			"directories": {
				"metadata": "metadata/library"
			}
		}
	}
}

Maqetta metadata

package layout:

+ package.json
+ metadata
   +-- widgets.json

package.json:

{
	"name": "library-maq",
	...
	"dependencies": {
		"library-oam": "v1.0"
	},
	...
	"overlays": {
		"maqetta": {
			"directories": {
				"widget_metadata": "metadata/widgets.json"
			}
		}
	}
}

Library Package Loading Algorithm

An algorithm for loading library packages from with Maqetta may look something like this:

- iterate over library packages
	- read package file, doing a mixin for "oam" and "maqetta" overlays
	- if package DOES NOT contain `directories.widget_metadata`, ignore
	- load package dependencies
		- if any dep is not found, ignore package

This should allow for the packages to come from different locations. For example, it is conceivable that a library package may come from one location, but the metadata package(s) may be listed elsewhere.

References

Packages 1.0 Specification

Packages 1.1 Proposal

Mappings/C Proposal

UncommonJs Packages spec