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",
		"metadata": "metadata"
	}
}

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",
		"metadata": "metadata"
	}
}

Maqetta metadata

package layout:

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

package.json:

{
	"name": "library-maq",
	...
	"directories": {
		"metadata": "metadata"
	},
	"dependencies": {
		"library": "v1.0"
	}
}

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",
	...
	"directories": {
		"metadata": "metadata"
	},
	"dependencies": {
		"library": "v1.0"
	}
}

Maqetta metadata

package layout:

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

package.json:

{
	"name": "library-maq",
	...
	"directories": {
		"metadata": "metadata"
	},
	"dependencies": {
		"library": {
			"library-maq": "v1.0",
			"library": "v1.0"
		}
	}
}

Conditional Dependencies

Notice the dependencies structure for the Maqetta metadata package in scenario 3. The Packages spec allows a 'dependencies' to be a hash, wherein the order determines priority.

In this case, a client loading the Maqetta metadata package will first try to satisfy its library dependency with "library-maq", followed by "library". The first dependency ("library-maq") is satisfied by the widget metadata package in scenario 3. However, if that package isn't available, the Maqetta metadata package also lists "library" as the next dependency. This one is actually satisfied by the 'library + widget metadata' package specified in scenario 2.

Library Package Loading Algorithm

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

- iterate over library packages
	- if package DOES NOT contain Maqetta metadata, ignore
	- load package
	- load its dependencies
		- if simple deps, immediately load
		- if complex deps, iterate over list of deps
			- try to load current dep from full list of library packages
			- if not found, continue to next dep
		- if none of the deps 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