User Intents
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.