.config/coc/extensions/node_modules/coc-prettier/node_modules/update-notifier/readme.md

   1 # update-notifier [![Build Status](https://travis-ci.org/yeoman/update-notifier.svg?branch=master)](https://travis-ci.org/yeoman/update-notifier)
   2
   3 > Update notifications for your CLI app
   4
   5 ![](screenshot.png)
   6
   7 Inform users of your package of updates in a non-intrusive way.
   8
   9 #### Contents
  10
  11 - [Install](#install)
  12 - [Usage](#usage)
  13 - [How](#how)
  14 - [API](#api)
  15 - [About](#about)
  16 - [Users](#users)
  17
  18
  19 ## Install
  20
  21 ```
  22 $ npm install update-notifier
  23 ```
  24
  25
  26 ## Usage
  27
  28 ### Simple
  29
  30 ```js
  31 const updateNotifier = require('update-notifier');
  32 const pkg = require('./package.json');
  33
  34 updateNotifier({pkg}).notify();
  35 ```
  36
  37 ### Comprehensive
  38
  39 ```js
  40 const updateNotifier = require('update-notifier');
  41 const pkg = require('./package.json');
  42
  43 // Checks for available update and returns an instance
  44 const notifier = updateNotifier({pkg});
  45
  46 // Notify using the built-in convenience method
  47 notifier.notify();
  48
  49 // `notifier.update` contains some useful info about the update
  50 console.log(notifier.update);
  51 /*
  52 {
  53         latest: '1.0.1',
  54         current: '1.0.0',
  55         type: 'patch', // Possible values: latest, major, minor, patch, prerelease, build
  56         name: 'pageres'
  57 }
  58 */
  59 ```
  60
  61 ### Options and custom message
  62
  63 ```js
  64 const notifier = updateNotifier({
  65         pkg,
  66         updateCheckInterval: 1000 * 60 * 60 * 24 * 7 // 1 week
  67 });
  68
  69 if (notifier.update) {
  70         console.log(`Update available: ${notifier.update.latest}`);
  71 }
  72 ```
  73
  74
  75 ## How
  76
  77 Whenever you initiate the update notifier and it's not within the interval threshold, it will asynchronously check with npm in the background for available updates, then persist the result. The next time the notifier is initiated, the result will be loaded into the `.update` property. This prevents any impact on your package startup performance.
  78 The update check is done in a unref'ed [child process](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options). This means that if you call `process.exit`, the check will still be performed in its own process.
  79
  80 The first time the user runs your app, it will check for an update, and even if an update is available, it will wait the specified `updateCheckInterval` before notifying the user. This is done to not be annoying to the user, but might surprise you as an implementer if you're testing whether it works. Check out [`example.js`](example.js) to quickly test out `update-notifier` and see how you can test that it works in your app.
  81
  82
  83 ## API
  84
  85 ### notifier = updateNotifier(options)
  86
  87 Checks if there is an available update. Accepts options defined below. Returns an instance with an `.update` property there is an available update, otherwise `undefined`.
  88
  89 ### options
  90
  91 #### pkg
  92
  93 Type: `Object`
  94
  95 ##### name
  96
  97 *Required*<br>
  98 Type: `string`
  99
 100 ##### version
 101
 102 *Required*<br>
 103 Type: `string`
 104
 105 #### updateCheckInterval
 106
 107 Type: `number`<br>
 108 Default: `1000 * 60 * 60 * 24` *(1 day)*
 109
 110 How often to check for updates.
 111
 112 #### callback(error, update)
 113
 114 Type: `Function`
 115
 116 Passing a callback here will make it check for an update directly and report right away. Not recommended as you won't get the benefits explained in [`How`](#how). `update` is equal to `notifier.update`.
 117
 118 ### notifier.notify([options])
 119
 120 Convenience method to display a notification message. *(See screenshot)*
 121
 122 Only notifies if there is an update and the process is [TTY](https://nodejs.org/api/process.html#process_tty_terminals_and_process_stdout).
 123
 124 #### options
 125
 126 Type: `Object`
 127
 128 ##### defer
 129
 130 Type: `boolean`<br>
 131 Default: `true`
 132
 133 Defer showing the notification to after the process has exited.
 134
 135 ##### message
 136
 137 Type: `string`<br>
 138 Default: [See above screenshot](https://github.com/yeoman/update-notifier#update-notifier-)
 139
 140 Message that will be shown when an update is available.
 141
 142 ##### isGlobal
 143
 144 Type: `boolean`<br>
 145 Default: `true`
 146
 147 Include the `-g` argument in the default message's `npm i` recommendation. You may want to change this if your CLI package can be installed as a dependency of another project, and don't want to recommend a global installation. This option is ignored if you supply your own `message` (see above).
 148
 149 ##### boxenOpts
 150
 151 Type: `Object`<br>
 152 Default: `{padding: 1, margin: 1, align: 'center', borderColor: 'yellow', borderStyle: 'round'}` *(See screenshot)*
 153
 154 Options object that will be passed to [`boxen`](https://github.com/sindresorhus/boxen).
 155
 156 ##### shouldNotifyInNpmScript
 157
 158 Type: `boolean`<br>
 159 Default: `false`
 160
 161 Allows notification to be shown when running as an npm script.
 162
 163 ### User settings
 164
 165 Users of your module have the ability to opt-out of the update notifier by changing the `optOut` property to `true` in `~/.config/configstore/update-notifier-[your-module-name].json`. The path is available in `notifier.config.path`.
 166
 167 Users can also opt-out by [setting the environment variable](https://github.com/sindresorhus/guides/blob/master/set-environment-variables.md) `NO_UPDATE_NOTIFIER` with any value or by using the `--no-update-notifier` flag on a per run basis.
 168
 169 The check is also skipped on CI automatically.
 170
 171
 172 ## About
 173
 174 The idea for this module came from the desire to apply the browser update strategy to CLI tools, where everyone is always on the latest version. We first tried automatic updating, which we discovered wasn't popular. This is the second iteration of that idea, but limited to just update notifications.
 175
 176
 177 ## Users
 178
 179 There are a bunch projects using it:
 180
 181 - [npm](https://github.com/npm/npm) - Package manager for JavaScript
 182 - [Yeoman](http://yeoman.io) - Modern workflows for modern webapps
 183 - [AVA](https://ava.li) - Simple concurrent test runner
 184 - [XO](https://github.com/xojs/xo) - JavaScript happiness style linter
 185 - [Pageres](https://github.com/sindresorhus/pageres) - Capture website screenshots
 186 - [Node GH](http://nodegh.io) - GitHub command line tool
 187
 188 [And 1600+ more…](https://www.npmjs.org/browse/depended/update-notifier)
 189
 190
 191 ## License
 192
 193 BSD-2-Clause © Google