Class UpdateChecker

Description

Checking the version requires an access to the packages registry, which might take some time to complete.

Given that the result is needed later, before exiting, the operation can be started asynchronously and awaited at the end.

Constructors

constructor

Properties

latestVersion envVariableName timestampFilePath returnedError log packageName packageVersion timestampsFolderPath checkUpdatesIntervalMilliseconds latestVersionPromise processEnv isCI isTTY isRunningAsRoot isInstalledGlobally isInstalledAsRoot testEnvironment

Methods

initiateVersionRetrieval notifyIfUpdateIsAvailable sendNotification didIntervalExpire readTimestampFileStats clearTimestamp createTimestamp

Constructors

constructor

  • new UpdateChecker(
        params: {
            log: Logger;
            packageName: string;
            packageVersion: string;
            envVariableName?: string;
            timestampsFolderPath?: string;
            checkUpdatesIntervalSeconds?: number;
        },
    ): UpdateChecker

  • Parameters

    • params: {
          log: Logger;
          packageName: string;
          packageVersion: string;
          envVariableName?: string;
          timestampsFolderPath?: string;
          checkUpdatesIntervalSeconds?: number;
      }

      The generic object used to pass parameters to the constructor.

      • log: Logger

        A reference to a Logger instance.

      • packageName: string

        A string with the full package name, as from the name property in the package.json file.

      • packageVersion: string

        A string with the package version, in semver, as from the version property in the package.json file.

      • OptionalenvVariableName?: string

        A string with the name of an environment variable which, when present disables the update checks.

        If missing, NO_<packageName>_UPDATE_NOTIFIER is used.

      • OptionaltimestampsFolderPath?: string

        A string with the path to the folder where the timestamps are located.

        If missing, by default, timestamps are created in the $HOME/.config/timestamps folder.

      • OptionalcheckUpdatesIntervalSeconds?: number

        A number with the minimum interval between checks, in milliseconds,

        If missing, by default, checks are performed no sooner than 24 hours.

    Returns UpdateChecker

    Description

    This function initialises the internal variables with lots of conditions tested later to determine if the update must be performed.

    To improve testability, a mock environment can be passed via a a static property.

Properties

latestVersion

latestVersion: undefined | string = undefined

Description

This variable holds the result of calling the latest-version module.

The content is a string in semver format.

envVariableName

envVariableName: string

Description

This variable provides an external method to control whether the checks are performed or not.

If the variable is present in the environment, the update checks are disabled.

timestampFilePath

timestampFilePath: string

Description

To avoid repeating the check too often, the timestamp of the latest check is remembered as the creation file of a file, in the $HOME/.config/timestamps folder.

The content is a string with the absolute path of the file created after checking the version.

returnedError

returnedError: any = undefined

Description

In case an error occurs while retrieving the version, the error message is logged, but the Error object is also stored in this variable, accessible to the caller.

Protectedlog

log: Logger

A reference to a Logger instance.

ProtectedpackageName

packageName: string

A string with the full package name, as from the package.json.

ProtectedpackageVersion

packageVersion: string

A string with the package version, in semver, as from the package.json.

ProtectedtimestampsFolderPath

timestampsFolderPath: string

A string with the path to the folder where the stamps are created.

ProtectedcheckUpdatesIntervalMilliseconds

checkUpdatesIntervalMilliseconds: number

A number with the minimum interval to check for the updates, in milliseconds

ProtectedlatestVersionPromise

latestVersionPromise: undefined | Promise<string> = undefined

A promise which resolves to a string with the latest version.

ProtectedprocessEnv

processEnv: any

A map with environment variables.

ProtectedisCI

isCI: boolean = false

A boolean True when running in a CI environment.

ProtectedisTTY

isTTY: boolean = false

A boolean True when running in a terminal.

ProtectedisRunningAsRoot

isRunningAsRoot: boolean = false

A boolean True when running with administrative credentials.

ProtectedisInstalledGlobally

isInstalledGlobally: boolean = false

A boolean True when the package is installed globally.

ProtectedisInstalledAsRoot

isInstalledAsRoot: boolean = false

A boolean True when the package is installed with administrative rights.

StatictestEnvironment

testEnvironment: undefined | UpdateCheckerTestEnvironment

Description

This property is normally undefined, but it can be set to a mock environment, during tests.

Methods

initiateVersionRetrieval

  • initiateVersionRetrieval(): Promise<void>

  • Returns Promise<void>

    Nothing.

    Description

    The operation is performed by the third party package latest-version, which accesses the location where the package is stored (like the npmjs.com server, or GitHub).

    Since this is a potentially long operation, it is expected to be started at the beginning of a CLI application and completed at the end, giving it a good chance to run in parallel.

    The operation is not started if it is considered not useful, like when running in a CI environment, when not running from a console, or an environment variable like NO_<packageName>_UPDATE_NOTIFIER is defined.

notifyIfUpdateIsAvailable

  • notifyIfUpdateIsAvailable(): Promise<void>

  • Returns Promise<void>

    Nothing.

    Description

    Await for the actual version to be retrieved, compare it with the current version, possibly notify and create a new timestamp.

sendNotification

  • sendNotification(): void

  • Returns void

    Nothing.

    Description

    The notification message is composed using the values stored in the instance properties.

    The message is sent out by writing to the log, using the info level. This can be silenced by lowering the log level.

    The notification message looks like this:

    >>> New version 0.14.9 -> 0.15.0 available. <<<
>>> Run 'npm install --global xpm@0.15.0' to update. <<<

    To customise the notification message, this function can be redefined in a class derived from this one.

ProtecteddidIntervalExpire

  • didIntervalExpire(ageMilliseconds: number): Promise<boolean>

  • Parameters

    • ageMilliseconds: number

      Age in milliseconds.

    Returns Promise<boolean>

    True if there is no timestamp or if it is older than the given age.

    Description

    Compute the timestamp age (as the time difference between the current time and the timestamp) and compare to the given age.

ProtectedreadTimestampFileStats

  • readTimestampFileStats(): Promise<null | Stats>

  • Returns Promise<null | Stats>

    A promise that resolves to a fs.Stats object or null.

ProtectedclearTimestamp

  • clearTimestamp(): Promise<void>

  • Returns Promise<void>

    Nothing.

    Description

    The main reason for this to be a separate function is testability.

ProtectedcreateTimestamp

  • createTimestamp(): Promise<void>

  • Returns Promise<void>

    Nothing.

    Description

    Create an empty file. The timestamp is the creation date.

Settings

Member Visibility

On This Page

Constructors
Properties
Methods