{"id":19168479,"url":"https://github.com/bloomberg/wsk-notify","last_synced_at":"2026-03-16T19:04:35.777Z","repository":{"id":52164783,"uuid":"109821047","full_name":"bloomberg/wsk-notify","owner":"bloomberg","description":"Simple, customizable console notifications.","archived":false,"fork":false,"pushed_at":"2023-07-11T09:53:24.000Z","size":2695,"stargazers_count":10,"open_issues_count":5,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-15T21:49:27.918Z","etag":null,"topics":["bloomberg-graphics","nodejs","wsk"],"latest_commit_sha":null,"homepage":"https://bloomberg.github.io/wsk-notify","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-07T10:31:21.000Z","updated_at":"2023-12-29T19:27:06.000Z","dependencies_parsed_at":"2024-11-09T09:42:53.848Z","dependency_job_id":null,"html_url":"https://github.com/bloomberg/wsk-notify","commit_stats":{"total_commits":14,"total_committers":2,"mean_commits":7.0,"dds":0.1428571428571429,"last_synced_commit":"6ccc63206c4ae05b9a38354ddd96593e09b8cd01"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fwsk-notify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fwsk-notify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fwsk-notify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fwsk-notify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/wsk-notify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252897568,"owners_count":21821469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bloomberg-graphics","nodejs","wsk"],"created_at":"2024-11-09T09:42:48.907Z","updated_at":"2026-03-16T19:04:35.738Z","avatar_url":"https://github.com/bloomberg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"wsk-notify [\u003cimg src=\"https://github.com/bloomberg/wsk-notify/raw/docs/src/img/wsk-notify.gif\" width=\"100\" align=\"right\" alt=\"wsk-notify\"\u003e](https://bloomberg.github.io/wsk-notify)\n===\n\n[![Build status](https://img.shields.io/travis/bloomberg/wsk-notify/master.svg?style=flat-square)](https://travis-ci.org/bloomberg/wsk-notify)\n[![Coverage](https://img.shields.io/coveralls/github/bloomberg/wsk-notify/master.svg?style=flat-square)](https://coveralls.io/github/bloomberg/wsk-notify?branch=master)\n[![npm version](https://img.shields.io/npm/v/wsk-notify.svg?style=flat-square)](https://www.npmjs.com/package/wsk-notify)\n[![js-semistandard-style](https://img.shields.io/badge/code%20style-semistandard-00b9e7.svg?style=flat-square)](https://github.com/Flet/semistandard)\n\n\u003e Simple, customizable console notifications. Used in the [wsk](https://bloomberg.github.io/wsk) build system.\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Examples](#examples)\n* [Displays \u0026 Styling](#displays--styling)\n  - [Default Displays](#default-displays)\n  - [Display Options](#display-options)\n  - [Creating Your Own Display Styles With A `.notifyrc` File](#creating-your-own-display-styles-with-a-notifyrc-file)\n  - [Extending Existing Display Styles](#extending-existing-display-styles)\n* [A Note On Style Inheritance](#a-note-on-style-inheritance)\n* [Groups](#groups)\n* [Styling The Prefix](#styling-the-prefix)\n* [Other `.notifyrc` Options](#other-notifyrc-options)\n* [Specifying An Alternate `.notifyrc`](#specifying-an-alternate-notifyrc)\n* [Shorthand](#shorthand)\n* [Piping On The Command Line](#piping-on-the-command-line)\n* [Clock](#clock)\n* [Contributors](#contributors)\n* [License](#license)\n\n## Installation\n\n```\nnpm install --save wsk-notify\n```\n\n## Usage\n\nUse the `notify` function to create formatted console messages. Simple usage:\n\n```js\nvar notify = require('wsk-notify');\n\nnotify({\n  message: 'A description of what I did...',\n  value: 'The file acted upon or the result of what happened'\n});\n```\n\nGives you:\n\n![Simple usage](screenshots/simple-usage.png)\n\nThe notification has three parts:\n\n1. Prefix (the timestamp and base directory name)\n2. Message (`message`)\n3. Value (`value`)\n\nBoth `message` and `value` are optional, in case you only need one of them. They are functionally equivalent. The only difference is `value` gets bolded by default.\n\nYou can also pass a list, shown here using the [shorthand notation](#shorthand).\n\n```js\nnotify([\n  {m: 'First message',  v: 'File one'},\n  {m: 'Second message', v: 'File two'}\n]);\n```\n\nIf you've given notify a list of objects, or you're using [groups](#groups), it will return a list of notification strings. If you've given it a single object, it will return a single string.\n\n## Examples\n\nFor a full setup, take a look at a [wsk example project](https://bloomberg.github.io/wsk.example), which uses this library to tell users when their build tasks have been completed. The different display styles allow you to establish a visual pattern of what steps have occurred in your build process:\n\n1. A file change was detected (cyan)\n2. That file was transformed, such as a Stylus file becoming a CSS file (magenta)\n3. Our live reload server detected the new file and is now refreshing (bold yellow)\n\n![wsk example](screenshots/example-project.png)\n\nHere are a bunch of `compile` processes running:\n\n![wsk build example](screenshots/build.png)\n\nAnd here is a watch process:\n\n![wsk watch example](screenshots/dev.png)\n\nLearn more about the wsk build system [here](https://bloomberg.github.io/wsk).\n\nThis library isn't just for build processes, though. You could use it whenever you want to give timestamped notification and easily want to group notifications by color. For example, if you're scraping a number of web pages, you could give a notification when a site was visited and another style notification when a data file is written.\n\n## Displays \u0026 Styling\n\nIf you don't specify a `display` style, you'll get the above: the timestamp is `gray`, the project root is `blue` and `bold`, the message is your default color and the value is bold.\n\nOut of the box, you get a number of styles, called \"displays\". Use one like so:\n\n```js\nnotify({\n  message: 'My message...',\n  value: 'value',\n  display: 'compile' // Can be any of the following: 'compile', 'watch', 'error', 'change', 'add', 'reload', 'success', 'remove', 'serve'\n});\n```\n\nYou can also pass an `Error` object to the `error` key to get a stack trace. See the display gallery below for an example. Errors are run through [clean-stack](https://npmjs.com/package/clean-stack) to cut out some of the junk.\n\n```js\nfunction cb (err, response) {\n  if (err) {\n    notify({\n      message: 'My message...',\n      value: 'value',\n      display: 'error', // This can be any display but 'error' will have it print in red.\n      error: err\n    });\n  }\n};\n```\n\nSee the specifics of these styles under `defaultDisplays` in [`src/defaults/defaultNotifyrc.js`](src/defaults/defaultNotifyrc.js).\n\n### Default Displays\n\n**`default`**\n\n![default display](screenshots/default.png)\n\n**`compile`**\n\n![compile display](screenshots/compile.png)\n\n**`watch`**\n\n![watch display](screenshots/watch.png)\n\n**`warn`**, uses console.warn\n\n![warn display](screenshots/warn.png)\n\n**`error`**, shows desktop notification and uses console.error\n\n![error display](screenshots/error.png)\n\n**`error` with an `Error` object**, shows desktop notification, stack trace and uses console.error\n\n![error-object display](screenshots/error-object.png)\n\n**`change`**\n\n![change display](screenshots/change.png)\n\n**`remove`**\n\n![remove display](screenshots/remove.png)\n\n**`add`**\n\n![add display](screenshots/add.png)\n\n**`reload`**\n\n![reload display](screenshots/reload.png)\n\n\n**`success`**\n\n![success display](screenshots/success.png)\n\n**`serve`**\n\n![serve display](screenshots/serve.png)\n\n### Display options\n\nThe `display` field can be:\n\n1. A name of a display, as shown above\n2. A string or an array of chalk codes. This is shorthand for styling the `message`.\n3. A full display object\n\nFor example:\n\n```js\n// Single color\nnotify({\n  message: 'Message...',\n  value: 'value',\n  display: 'cyan'\n});\n\n// Multiple color\nnotify({\n  message: 'Message...',\n  value: 'value',\n  display: ['magenta', 'underline']\n});\n\n// Custom display object\nnotify({\n  message: 'Message...',\n  value: 'value',\n  display: {\n    messageStyle: 'cyan',\n    valueStyle: 'stripColor' // This removes existing styling. In this case it makes it not bolded.\n  }\n});\n```\n\nGives you:\n\n![Display string](screenshots/display-string.png)\n![Display array](screenshots/display-array.png)\n![Display object](screenshots/display-object.png)\n\nHere are the full options for the `display` object showing default values. Any attribute ending in `Style` can take a string or an array of strings of [chalk color, modifier or background color style](https://www.npmjs.com/package/chalk#styles).\n\n```js\nnotify({\n  message: 'My message...',\n  value: 'value',\n  display: {\n    messageStyle: '', // Unstyled\n    valueStyle: 'bold',\n    preString: '', // Put a string before this message\n    postString: '', // Put a string after this message\n    prefixStyle: { // Change the style of the prefix\n      open: '[',\n      open: ']',\n      sep: '|',\n      timestampStyle: 'gray',\n      projectNameStyle: ['bold', 'blue']\n    },\n    desktop: false, // Send an OS desktop notification. This delegates to node-notifier. If this field is true, it will send a notification with the project name as the \"title\", the `message` as \"sub-title\" and the `value` as \"message\". You can overwrite this behavior and add more options such as sounds by setting this to an object that will be passed directly to node-notifier. See their docs for full options: https://www.npmjs.com/package/node-notifier.\n    skipPrefix: false, // If true, on't log the prefix\n    projectName: null // Defaults to your root project directory if not set here. Can also be a function that gets passed the root project directory and returns a string.\n  },\n  silent: false, // If true, don't log out the notification, but still return it as a string.\n  level: 'log' // The `console` method to use. Can be \"log\", \"warn\", \"error\", \"info\" or \"debug\".\n};\n```\n\n### Creating Your Own Display Styles With A `.notifyrc` File\n\nIf you create a `.notifyrc` and place it in your project root dirctory, you can add custom display types of your own. Any unspecified keys on a display will fall back to the defaults above.\n\n```js\n// .notifyrc\n\n// Define these two styles\nmodule.exports = {\n  customDisplays: {\n    valueUnderline: {\n      messageStyle: 'cyan',\n      valueStyle: ['underline', 'magenta'],\n      desktop: {\n        sound: 'Frog'\n      }\n    },\n    noPrefix: {\n      skipPrefix: true\n    }\n  }\n};\n```\n\n```js\nvar notify = require('wsk-notify');\n\nnotify({\n  message: 'Message...',\n  value: 'I\\'m magenta and underlined!',\n  display: 'valueUnderline'\n});\n\nnotify({\n  message: 'Message...',\n  value: 'and value only.',\n  display: 'noPrefix'\n});\n```\n\nGives you:\n\n![Value underline](screenshots/value-underline.png)\n\n![No prefix](screenshots/noPrefix.png)\n\n### Extending Existing Display Styles\n\nLet's say you really like our `valueUnderline` style above but want to tweak it slightly. You can modify a display with the `extend` key.\n\n```js\nnotify({\n  message: 'Make me bold yellow',\n  value: 'Keep me underlined magenta',\n  display: 'valueUnderline',\n  extend: {\n    messageStyle: 'cyan'\n  }\n});\n```\n\nGives you:\n\n![extend](screenshots/extend.png)\n\n## A Note on Style Inheritance\n\nDisplay styles override global styles defined in `.notifyrc` and notification-specific styles override display styles. You can see this play out in the [Styling the prefix](#styling-the-prefix) section below. The same pattern applies to `desktop` settings which, like the prefix, can be styled in a the `.notifyrc`, a display or directly in a notification.\n\n## Groups\n\nSometimes you want to log out a group of notifications together, even if the notifications don't happen at the same time. You can do this with wsk-notify using the `.group()` option.\n\n```js\nvar group = notify.group();\n// happens at 08:00\ngroup.add({\n  message: 'Message 1',\n  value: 'value',\n  display: 'add'\n});\n\n// happens at 08:02\ngroup.add({\n  message: 'Message 2',\n  value: 'value',\n  display: 'compile'\n});\n\n// Logs out notifications accurately timestamped to when they occured\n// returns the list of notification strings\nvar list = group.notify();\n```\n\nFor convenience, you can also add your first notification with your first call to `.group()`\n\n```js\nvar group = notify.group({\n  message: 'Message 1',\n  value: 'value',\n  display: 'add'\n});\n\n// continue same as above...\n```\n\n## Styling The Prefix\n\nIn addition to styling the prefix in a display, you can set it globally for all displays through the `.notifyrc` file.\n\n**Note**: You do not have to set every property on `globalPrefixStyle` or `prefixStyle` are required. Any omitted keys will take on the default value. For example, you can just set `projectNameStyle` and everything else will be the same.\n\nThese are all equivalent:\n\n```js\n// Set it globally\n\n// .notifyrc\nmodule.exports = {\n  globalPrefixStyle: {\n    open: '\u003c',\n    close: '\u003e',\n    sep: '🍰 ', // Note, emojis look better with a trailing space\n    projectNameStyle: 'yellow'\n  }\n};\n\n// and then in your code...\nnotify({\n  message: 'Message...',\n  value: 'value'\n});\n```\n\n```js\n// With a custom display\n\n// .notifyrc\nmodule.exports = {\n  customDisplays: {\n    cake: {\n      prefixStyle: {\n        open: '\u003c',\n        close: '\u003e',\n        sep: '🍰 ',\n        projectNameStyle: 'yellow'\n      }\n  }\n};\n\n// and then in your code...\nnotify({\n  message: 'Message...',\n  value: 'value',\n  display: 'cake'\n};\n```\n\nOr for a single notification:\n\n```js\n\n// For a single notification\nnotify({\n  message: 'My message',\n  value: 'value',\n  display: {\n    prefixStyle: {\n      open: '\u003c',\n      close: '\u003e',\n      sep: '🍰 ',\n      projectNameStyle: 'yellow'\n    }\n  }\n});\n\n// Modifying the existing display style for a single notification\nnotify({\n  message: 'My message',\n  value: 'value',\n  display: 'default',\n  extend: {\n    prefixStyle: {\n      open: '\u003c',\n      close: '\u003e',\n      sep: '🍰 ',\n      projectNameStyle: 'yellow'\n    }\n  }\n});\n```\n\nThese all give you:\n\n![Custom prefix](screenshots/custom-prefix.png)\n\n## Other `.notifyrc` Options\n\nAnything in the default `.notifyrc` file will be extended by yours. Here's are the defaults.\n\n**Note**: Instead of overwriting the `defaultDisplays`, it's a better practice to use `customDisplays` as described above in [Creating Your Own Display Styles With A `.notifyrc` File](#creating-your-own-display-styles-with-a-notifyrc-file).\n\n**Note**: The same as `globalPrefixStyle`, any omitted keys on `defaultDisplaySettings` will take on the default value. For example, you can just set `messageStyle: ''` to get rid of the default `bold` and everything else will be the same.\n\n```js\n{\n  time: formatTimestamp, // Defaults to formatted current time. Can be a string or function with a JavaScript date object as `(currentTime)`. Falsey values\n  projectName: projectName, // Can be string or function with signature `(rootDir)`\n  customDisplays: {},\n  globalPrefixStyle: {\n    open: '[',\n    close: ']',\n    sep: '|',\n    timestampStyle: 'gray',\n    projectNameStyle: ['blue', 'bold']\n  },\n  // Base style for any display\n  defaultDisplaySettings: {\n    messageStyle: '',\n    valueStyle: 'bold',\n    preString: '',\n    postString: '',\n    skipPrefix: false,\n    prefixStyle: {},\n    projectName: null,\n    time: null,\n    desktop: false,\n    level: 'log'\n  },\n  defaultDisplays: {...}\n};\n```\n\nHere are some examples:\n\n```js\n// .notifyrc\n\nmodule.exports = {\n  // Set a custom string\n  time: '∞'\n\n  // Or a function that returns a string\n  time: function (currentDateObject) {\n    return currentDateObject.getFullYear()\n  }\n};\n```\n\n```js\n// .notifyrc\n\nmodule.exports {\n  // Set a custom string\n  projectName: 'my-other-project-name'\n\n  // Or add to the existing project directory name.\n  // This can be useful for debugging so you know what part of the process is sending notifications without having to put that in the `message`.\n  // Or to signal a different branch\n  projectName: function (rootDir) {\n    return rootDir + '/tests'\n  }\n};\n```\n\nAnd set desktop notifications for displays or notifications that have a truthy value for `desktop`.\n\n```js\n// .notifyrc\nmodule.exports = {\n  desktop: {\n    sound: 'Glass'\n  }\n};\n\n// in your code\nnotify({\n  message: 'My message',\n  value: 'value',\n  desktop: true\n});\n\n// or this will override the `Frog` sound with `Glass`.\nnotify({\n  message: 'My message',\n  value: 'value',\n  desktop: {\n    sound: 'Frog'\n  }\n});\n```\n\n## Specifying An Alternate `.notifyrc`\n\nIf you want to use another file name or load an object directly you can use `notify.config()`.\n\n```js\nnotify.config('path/from/project/root/to/.my-notifyrc');\n\n// or\nnotify.config({\n  time: '∞'\n});\n```\n\nIf you also already have a `.notifyrc`, these options will extend your existing options. To set options back to their defaults, set your options to `null`.\n\n## Shorthand\n\nIf you get tired of writing out `message`, `value` and other top-level settings, you can use the following shorthand:\n\n* `m` --\u003e `message`\n* `v` --\u003e `value`\n* `d` --\u003e `display`\n* `s` --\u003e `silent`\n* `e` --\u003e `error`\n* `x` --\u003e `extend`\n* `k` --\u003e `desktop`\n\n## Piping On The Command Line\n\nwsk-notify supports receiving stringified JSON from other processes. Let's say you have a library that pipes single-line json strings to stdout. You can report those notifications like so:\n\n```sh\n$ my-process | wks-notify\n\n# or more explicitly (using shorthand syntax)\n$ echo '{\"m\": \"my message\", \"v\": \"my value\"}' | wsk-notify\n```\n\n## Clock\n\nwsk-notify comes with a simple clock utility to help you time how long processes took and format them nicely. Example:\n\n```js\nvar start = notify.clock();\n\n// 50 milliseconds elapse\nvar duration = notify.clock(start); // \"50ms\"\n\n// or get the raw duration in milliseconds\nvar duration = notify.clock(start, {raw: true}); // 50\n\n// Because calling `.clock` with no arguments just returns a start time, you can run multiple clocks with no change in syntax\n\nvar timerOne = notify.clock();\n// 400 ms go by\nvar timerTwo = notify.clock();\n// 900 ms go by\n\nvar duration = notify.clock(timerOne); // \"1.3s\"\nvar duration = notify.clock(timerTwo); // \"900ms\"\n```\n\n## Contributors\n\n* [Michael Keller](https://twitter.com/mhkeller)\n* [Jeremy Diamond](https://twitter.com/_jsdiamond)\n* [Julian Burgess](https://twitter.com/aubergene)\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fwsk-notify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fwsk-notify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fwsk-notify/lists"}