Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pureartisan/user-intents

A light-weight library for User Intents on Web Applications
https://github.com/pureartisan/user-intents

monitoring npm-package typescript user-intent

Last synced: 6 months ago
JSON representation

A light-weight library for User Intents on Web Applications

Awesome Lists containing this project

README 

          
# User Intents



[![npm version](https://badge.fury.io/js/user-intents.svg)](https://badge.fury.io/js/user-intents) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=pureartisan_user-intents&metric=coverage)](https://sonarcloud.io/dashboard?id=pureartisan_user-intents) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=pureartisan_user-intents&metric=alert_status)](https://sonarcloud.io/dashboard?id=pureartisan_user-intents) [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)



A light-weight javascript library for User Intents on Web Applications. Supports ES6 and TypeScript.



## What is an Intent?



A user's intention to perform an action is considered an "Intent". For example, a user clicking a the "save" button on the settings page would be the "save-settings" intent.



In the above example, we would expect the settings to be saved in less than 30 seconds, or the user experience is interrupted. If everything goes well, we will get a `completed` event (which can be listened to). However, if the action to save settings takes more than 30 seconds, we would get a `timedout` event when the timeout is reached.



Therefore, we will consider the "user intent" to be `save-settings` with a timeout of `30000 miliseconds` (or 30 seconds).



When such events occur, we can decide what we want to do with them. For exmaple, log an error, or perhaps even let the user know the action is taking a bit longer than usual, etc.



## Getting started



```

npm install --save user-intents

```



## Usage



```

import {

    addEventListener,

    startIntent, completeIntent, cancelIntent, failIntent

} from 'user-intents';



// or using `require`

// const userIntents = require('user-intents');



addEventListener('failed', (intent, timeout, data) => {

    console.error(`${intent} failed`, data);

});



...



const SAVE_SETTINGS_INTENT_NAME = 'save-settings';



...



function onUserClicksSaveButton() {

    // save settings via API call or any asynchronous action

    callAsyncActionToSave();



    // ---- start user intent

    const timeuot = 30000;

    // arbitarary data passed to events, can be anything you want

    const data = { profile: true };

    startIntent(SAVE_SETTINGS_INTENT_NAME, timeuot, data);

}



function onUserClicksCancelButtonWhileSavingInProgress() {

    // intent is cancelled

    // it will trigger the `cancelled` event

    cancelIntent(SAVE_SETTINGS_INTENT_NAME);

}



function onSaveSuccessful() {

    // intent was successful

    // it will trigger the `completed` event

    completeIntent(SAVE_SETTINGS_INTENT_NAME);

}



function onSaveError() {

    // user intented to save, but it failed

    // so mark it as failed, it will trigger the `failed` event

    failIntent(SAVE_SETTINGS_INTENT_NAME);

}



```



## Intents



### `startIntent(name, timeout, data?)`



Starts an intent with a given name. Stating an intent with the same name, while the previous intent is still pending will trigger an `incompleted` event for the previously pending intent.



| Parameter | Type | Description |

|-----------|--------|----------------------------------------------------------------------------------------------------------------------|

| `name` | string | Name of the intent, and this is case sensitive. |

| `timeout` | number | The timeout (max duration) this intent should be completed within. Otherwise the `timedout` event will be triggered. |

| `data` | any | [Optional] Arbitaray data that will be passed to events, when an event is triggered for this intent |



### `completeIntent(name)`



Completes a pending intent. If no intent by that name is pending, a warning will be logged in console. Use `disableWarnings()` to suppress the warnings. Completing an intent will trigger the `completed` event for that intent.



| Parameter | Type | Description |

|-----------|--------|----------------------------------------------------------------------------------------------------------------------|

| `name` | string | Name of the intent, and this is case sensitive. |



### `cancelIntent(name)`



Cancels a pending intent. If no intent by that name is pending, a warning will be logged in console. Use `disableWarnings()` to suppress the warnings. Cancelling an intent will trigger the `cancelled` event for that intent.



| Parameter | Type | Description |

|-----------|--------|----------------------------------------------------------------------------------------------------------------------|

| `name` | string | Name of the intent, and this is case sensitive. |



### `failIntent(name)`



Fails a pending intent. If no intent by that name is pending, a warning will be logged in console. Use `disableWarnings()` to suppress the warnings. Failing an intent will trigger the `failed` event for that intent.



| Parameter | Type | Description |

|-----------|--------|----------------------------------------------------------------------------------------------------------------------|

| `name` | string | Name of the intent, and this is case sensitive. |



## Events



You can listen to any of the following events using `addEventListener` or remove an existing event listener using `removeEventListener`.



| Event         | Description |

|---------------|-------------|

| `completed`   | Triggered when the `completeIntent` method is called on a pending intent |

| `failed`      | Triggered when the `failIntent` method is called on a pending intent |

| `timedout`    | Triggered when a pending intent reaches the timeout |

| `cancelled`   | Triggered when the `cancelIntent` method is called on a pending intent |

| `incompleted` | Triggered when the `startIntent` method is called for the same intent name while the previous intent is still pending |



### `addEventListener(event, listener)`



Adds an event listener for a given event.



| Parameter | Type | Description |

|------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|

| `event` | string | Event name and has to be one of the following: [`completed`, `incompleted`, `cancelled`, `failed`, `timedout`] |

| `listener` | function | The callback function. The following will be passed as arguments: [ `name`, `timeout`, `data` ], same as what was passed in when `startIntent()` was called. |



### `removeEventListener(event, listener)`



| Parameter | Type | Description |

|------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|

| `event` | string | Event name and has to be one of the following: [`completed`, `incompleted`, `cancelled`, `failed`, `timedout`] |

| `listener` | function | The callback function. Should the the same reference to the previously added callback function, otherwise this action is ignored. |



## Miscellaneous



### `disableWarnings()`



Warnings are enabled by default. Calling this method will disable logging warnings to console by this library. See `Intents` section above for more descriptions of what kind of warnings are logged to console. To re-enable warnings, simply call `enableWarnings()`



### `enableWarnings()`



Warnings are enabled by default. This method can be used to re-enable warnings if it was disabled at some point during runtime. See above for more details.



### `ignoreFirstWarning()`



This method will ignore the first warning from being logged, and is useful in certain sitautions. In those cases, this method must be called at the start of the application, as early as possible. This method is unnecessary if warnings are disable completely using `disableWarnings()`.



Let's look at an example:

We are tracking intents of the user going between pages/screens in the application. This is usually handled by `startIntent()` when the user clicks on a navigation link on the application to take the user to a certain page. When the page transitions/changes and the user is on the new page, we will call the `completeIntent()` method. However, if we come to this page the very first time and there was no `startIntent()` called at page load, there will be a warning. Calling `ignoreFirstWarning()` allows you to ignore logging this very first warning.