XPCOMUtils module

XPCOMUtils is a utility class that lives in resource://gre/modules/XPCOMUtils.sys.mjs.

Its name is a little confusing because it does not live in XPCOM itself, but it provides utilities that help JS consumers to make consuming sys.mjs modules and XPCOM services/interfaces more ergonomic.

class XPCOMUtils()

XPCOMUtils contains helpers to make lazily loading scripts, modules, prefs and XPCOM services more ergonomic for JS consumers.

static XPCOMUtils.declareLazy(declaration, options)

Arguments:

• declaration (L)

• options (ImportESModuleOptionsDictionary)

Examples:

const lazy = XPCOMUtils.declareLazy({
     AppConstants: "resource://gre/modules/AppConstants.sys.mjs",
     verticalTabs: { pref: "sidebar.verticalTabs", default: false },
     MIME: { service: "@mozilla.org/mime;1", iid: Ci.nsInsIMIMEService },
     expensiveThing: () => fetch_or_compute(),
   });

See also

• :any:`XPCOMUtils.defineLazy

A shorthand for above which always returns a new lazy object. Use this version if you have a global lazy const with all the getters:`

static XPCOMUtils.defineConstant(aObj, aName, aValue)

Defines a non-writable property on an object.

Arguments:

• aObj (object) – The object to define the property on.

• aName (string) – The name of the non-writable property to define on aObject.

• aValue (any) – The value of the non-writable property.

static XPCOMUtils.defineLazy(lazy, definition, options)

Defines properties on the given object which lazily import an ES module or run another utility getter when accessed.

Use this version when you need to define getters on the global this, or any other object you can’t assign to:

Arguments:

• lazy (T) – The object to define the getters on.

• definition (L) – Each key:value property defines type and parameters for getters. - “resource://module” string

• options (ImportESModuleOptionsDictionary) – When importing ESModules in devtools and worker contexts, the third parameter is required.

Examples:

XPCOMUtils.defineLazy(this, {
     AppConstants: "resource://gre/modules/AppConstants.sys.mjs",
     verticalTabs: { pref: "sidebar.verticalTabs", default: false },
     MIME: { service: "@mozilla.org/mime;1", iid: Ci.nsInsIMIMEService },
     expensiveThing: () => fetch_or_compute(),
   });

Additionally, the given object is also returned, which enables
type-friendly composition:

const existing = {
     someProps: new Widget(),
   };
   const combined = XPCOMUtils.defineLazy(existing, {
     expensiveThing: () => fetch_or_compute(),
   });

The `combined` variable is the same object reference as `existing`,
but TypeScript also knows about lazy getters defined on it.

Since you probably don't want aliases, you can use it like this to,
for example, define (static) lazy getters on a class:

const Widget = XPCOMUtils.defineLazy(
     class Widget {
       static normalProp = 3;
     },
     {
       verticalTabs: { pref: "sidebar.verticalTabs", default: false },
     }
   );

See also

• :any:`ChromeUtils.defineESModuleGetters

• () => value` - :any:`ChromeUtils.defineLazyGetter

• { service: “contract”, iid?: nsIID }` - :any:`XPCOMUtils.defineLazyServiceGetter

• { pref: “name”, default?, onUpdate?, transform? }` - XPCOMUtils.defineLazyPreferenceGetter

static XPCOMUtils.defineLazyGlobalGetters(aObject, aNames)

Defines a getter property on the given object for each of the given global names as accepted by Cu.importGlobalProperties. These properties are imported into the shared system global, and then copied onto the given object, no matter which global the object belongs to.

Arguments:

• aObject (object) – The object on which to define the properties.

• aNames (Array.<string>) – The list of global properties to define.

static XPCOMUtils.defineLazyPreferenceGetter(aObject, aName, aPreference, aDefaultPrefValue, aOnUpdate, aTransform)

Defines a getter on a specified object for preference value. The preference is read the first time that the property is accessed, and is thereafter kept up-to-date using a preference observer.

Arguments:

• aObject (object) – The object to define the lazy getter on.

• aName (string) – The name of the getter property to define on aObject.

• aPreference (string) – The name of the preference to read.

• aDefaultPrefValue (any) – The default value to use, if the preference is not defined. This is the default value of the pref, before applying aTransform.

• aOnUpdate (function) – A function to call upon update. Receives as arguments (aPreference, previousValue, newValue)

• aTransform (function) – An optional function to transform the value. If provided, this function receives the new preference value as an argument and its return value is used by the getter.

static XPCOMUtils.defineLazyScriptGetter(aObject, aNames, aResource)

Defines a getter on a specified object for a script. The script will not be loaded until first use.

Arguments:

• aObject (object) – The object to define the lazy getter on.

• aNames (string|Array.<string>) – The name of the getter to define on aObject for the script. This can be a string if the script exports only one symbol, or an array of strings if the script can be first accessed from several different symbols.

• aResource (string) – The URL used to obtain the script.

static XPCOMUtils.defineLazyServiceGetter(aObject, aName, aContract, aInterface)

Defines a getter on a specified object for a service. The service will not be obtained until first use.

Arguments:

• aObject (object) – The object to define the lazy getter on.

• aName (string) – The name of the getter to define on aObject for the service.

• aContract (string) – The contract used to obtain the service.

• aInterface (nsID|string) – The interface or name of interface to query the service to.

static XPCOMUtils.defineLazyServiceGetters(aObject, aServices)

Defines a lazy service getter on a specified object for each property in the given object.

Arguments:

• aObject (object) – The object to define the lazy getter on.

• aServices (object) – An object with a property for each service to be imported, where the property name is the name of the symbol to define, and the value is a 1 or 2 element array containing the contract ID and, optionally, the interface name of the service, as passed to defineLazyServiceGetter.

static XPCOMUtils.overrideScriptLoaderForTests(aObject)

Overrides the scriptloader definition for tests to help with globals tracking. Should only be used for tests.

Arguments:

• aObject (object) – The alternative script loader object to use.