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.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.defineLazyGetter(aObject, aName, aLambda)

DEPRECATED!

Use ChromeUtils.defineLazyGetter instead.

Defines a getter on a specified object that will be created upon first use.

Arguments:

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

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

  • aLambda (function) – A function that returns what the getter should return. This will only ever be called once.

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 JSM module 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.defineLazyModuleGetters(aObject, aModules)

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

Arguments:

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

  • aModules (object) – An object with a property for each module property to be imported, where the property name is the name of the imported symbol and the value is the module URI.

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, aInterfaceName)

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.

  • aInterfaceName (string) – The name of the 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.