Packages/Mappings/D

From CommonJS Spec Wiki
Jump to: navigation, search

STATUS: PROPOSAL

Package Mappings / Dependencies

This specification extends CommonJS package format for packages to define how they expect their dependencies to be mapped into the module name spaces. This specification extends "dependencies" property in package descriptor and expects that implementers will organize dependencies in way that all modules from the "dependencies" can be required by a top level identifiers, whose first slash-delimited term correspond to a key in the "dependencies" map. This specification does not define how the modules of referenced packages are installed or retrieved.

Examples

{
    "name": "mypackage",
    "dependencies": {
        "theirpackage": "http://github.com/Gozala/github/blob/gh-pages/"
    }
}

Values in the "dependencies" map MUST represent URI's and have to refer to the root of a dependent package. There for appending 'package.json' to the dependency URI should give URI to a package descriptor.

Appending 'manifest.json' to a dependency URI MUST give URI to a package manifest, that is a JSON containing list of modules that package contains. 

[
	"index",
	"foo/bar",
	"foo/main"
]

Way of expressing version or other information about dependency is by intension left to a package registries / managers and expected to be embedded into URI itself. 

{
    "name": "mypackage",
    "dependencies": {
        "theirpackage": "http://npm.com/[email protected]/"
    }
}

{
    "name": "mypackage",
    "dependencies": {
        "theirpackage": "http://mozillalabs.com/jetpack/libs/bar/1.2.3/"
    }
}

The key for this proposal is to provide a form of requiring modules form a dependency, regardless of the package manager and registry they come from. 

require("theirpackage/theirmodule");

How does package managers register or install individual packages / modules is out of the scope of this proposal.

  1. To be compliant with this specification, package manager must be able to

handle any package that provides all of the recommended metadata.

  1. To be usable by any package manager, a package must provide all of the

recommended metadata.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Packages

  1. The package.json at the root of a package directory tree or

archive MAY have a "dependencies" property.

  1. package.json's "dependencies" property maps

single-term top-level module identifiers to external package references.

  1. A single-term top-level module identifier MUST consist of only lower-case

letters, digits, underscore, and hyphen. Note: It MUST not include a slash ("/") or dot (".").

  1. An external package reference SHOULD have an "archive" property. Package managers MAY depend on the provision of this property.
    1. The "archive" property MUST be an URL String from which an archive as described by Packages can be downloaded with an HTTP GET request.
  2. An external package reference SHOULD have a "location" property. Package managers MAY depend on the provision of this property.
    1. The "location" property MUST refer to the root of a directory tree conforming to the content of a package as described by Packages and where every contained file is retrievable with an HTTP GET request for a path resolved based on the given location.
  3. An external package reference MAY have a "version" property. Package managers MAY depend on the provision of this property.
    1. If "version" exists, an external package reference MAY contain a "name" property that indicates the name of the package in a coordinated registry of packages. If omitted, this property defaults to the key of the mapping.
  4. An external package reference MAY have a "descriptor" property that is a package descriptor object, conforming to the package.json schema as described in Packages.
  5. An external package reference MAY have a "catalog" property that notes the URL of the catalog or registry with which a package manager is expected to associate this external package reference with additional or missing details.
  6. package.json may have a "catalog" property that notes the URL of the catalog or registry with which to associate package names and versions with further corresponding external package reference details.
  7. If the external package reference has a "archive" property, an external package reference MAY have a "verify" property that is an Object.
    1. The "verify" object MUST have a "algorithm" property that refers to the algorithm with which the "signature" was generated.
    2. The "verify" object MUST have a "signature" property that is a signature or hash of the referenced archive.
    3. The "signature" MUST be a lower-case base-16 value represented as a string of colon-delimited bytes.
    4. The "algorithm" MAY be "md5", in which case the "signature" MUST be a MD5 digest of the package archive file, computed as described in RFC 1321.
    5. The "algorithm" MAY be "sha1", in which case the "signature" MUST be an SHA-1 digest of the package archive file, computed as described in RFC 3174.

Note: this specification does not define the behavior of any other verification algorithms. These may be amended in a future revision.

Note: this specification does not define any archival formats apart from zip since this is the only standard format described in Packages, and may be amended in a future revision of that specification, in which case corresponding verbiage must be added to this specification to indicate the archival format of the an external package.

Note: This specification does not impose any restrictions on the format of the catalog file, nor even whether it is retrievable. Package registries or catalogs may opt to disqualify a package based on whether it supports a particular catalog URL, the format of the catalog, or for not providing a catalog URL.

Note: An external package reference may contain further properties. This specification recommends that these properties be prefixed with an implementation name to avoid collisions with properties of other implementations and future versions of this specification.

Modules

Within a package, the semantics of the require function are augmented as follows:

  1. If the required module identifier is not relative, it is a candidate for referencing a module in an external package.
    1. If the identifier has only one term (That is, contains no slashes ("/")), it is a candidate for referencing the main module of an external package.
      1. If this package is external to another package, and the parent package has an "main" property in its mapping for this package, require MUST return the exports of the specified main module of the external package.
      2. Otherwise, if the external package does have an "main" property in its package.json file, require MUST return the exports of the main module of the external package.
      3. Otherwise, require MUST throw an Error.
    2. If the identifier has multiple terms delimited by slashes, it is a candidate for referencing a module in the library directory of an external package.
      1. If the first term of the module identifier as delimited by slashes is not a property of the "mappings" object in the current package's package.json, the behavior of require is beyond the scope of this specification and follows through with the behavior defined in Packages in the context of the current package.
      2. If the first term of the module identifier as delimited by slashes is a property of the "mappings" object in the current package's package.json, require MUST return the exports of the module with the top-level identifier composed of all subsequent slash-delimited terms in the required module identifier in the context of the referenced external package as defined in Packages.
        1. If the external package reference contains a descriptor.directories.lib property, the modules from the external package MUST be found in the named lib directory, resolved relative to the root of the external package.

Related Discussions

Retrieved from "https://wiki.commonjs.org/index.php?title=Packages/Mappings/D&oldid=5885"