Modules/Loaders/A

From CommonJS Spec Wiki
Jump to: navigation, search

There has been no discussion of this proposal.

Sandboxes have a very simple design and do not benefit greatly from customization for particular sandbox varieties, apart from using more advanced data structures to map interesting module identifiers to their corresponding objects. However, loaders perform a great deal of heavy lifting that can be customized for various kinds of secure and insecure sandboxes, with various kinds of storage and retrieval for module texts. This proposal includes the names that a module author may be able to use for particular load implementations and the corresponding behavior and interface they can expect when using those member functions.

Any members of a specified object (including modules, or enumerated argument options) that are not reserved by the specification must be named with "x" as their first term and a vendor-specific label as their second term, like "require.xChironCurryId" or "system.xCajaDomita".

The Require Function/Object

  • id: the "require" object MAY have an "id" member that must be the normalized identifier of the current module
  • loader: the "require" object MAY have a "loader" member that is an interface to the object used by "require" to acquire module factory functions. Tampering with this variable must not alter the behavior of "require".
  • main: the "require" object MAY have an "main" member that is the module ID of the module that was the entry point for this sandbox. Thus the common Python idiom if __name__ == '__main__': would be if (require.id == require.main), except that this strategy avoids the problem of double loading the main module if it's referred to elsewhere by its real name.
  • isLoaded: returns whether a module exports object has been loaded for a given canonical module identifier.
  • isInstance: returns whether an object is an instance of one of a module's named exports. This is a convenient shortcut to avoid loading a module when, if the module has not been loaded as yet, the instance clearly cannot have been instantiated by one of its native exports.
  • clear: forgets all loaded modules

A Loader Object

  • load: the "loader" object, if present, MUST have a "load" method that returns a module factory function.
    • a module factory function MUST accept "require", "exports", and "system" as its arguments.
  • fetch: a module loader, if present, must provide a "fetch" method that returns the text of a module for a given normalized, fully-qualified, absolute module identifier.
  • evaluate: a module loader, if present, must provide an "evaluate" method that accepts a module text and returns a module factory function
    • a module text MUST be a string that conforms to a JavaScript "program" construction.
  • resolve: a module loader, if present, MUST provide a "resolve" method that accepts a module identifier (that may be a relative module identifier) and optionally a base module identifier (that must be an absolute module identifier) and returns the corresponding absolute identifier of the former.
  • canonical: a module loader, if present, MUST provide a "normalize" method that accepts an absolute module identifier and returns that identifier in its canonical form. "canonical" MAY be an identity relation. "canonical" may return an opaque reference object to prevent information about the underlying file system from leaking into a sandbox.
  • reload: forces a module factory to be refetched, reevaluated, and memoized. Can be used by load polymorphically in response to notification that the underlying stored module text has been modified.
  • clear: forgets all loaded module factories
  • getPaths MAY be present in permissive sandboxes, but MUST not be present in a secure sandbox. Returns the list of prioritized top-level module paths.
  • setPaths MAY be present in permissive sandboxes, but MUST not be present in a secure sandbox. Sets the prioritized list of top-level paths that the loader uses to find modules.
  • getExtensions MAY be present in permissive sandbox, but MUST not be present in secure sandboxes. Gets the list of prioritized file extensions that modules may have, including the dot prefix.
  • setExtensions MAY be present in permissive sandbox, but MUST not be present in secure sandboxes. Sets the list of prioritized file extensions that modules may have, including the dot prefix.