New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

lethargy-ts

Package Overview
Dependencies
Maintainers
1
Versions
11
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

lethargy-ts - npm Package Compare versions

Comparing version

0.0.3
to
0.0.4

lib/types/codes.d.ts
lib/types/tests/helpers.d.ts
lib/types/tests/lethargy.test.d.ts
lib/types/tests/utils.test.d.ts

98

lib/index.esm.js

@@ -35,22 +35,37 @@ /** Converts default WheelEvent to our custom IWheelEvent */

};
/** If e2 event is inertia, it's delta will be no more than treshold slower */
const isAnomalyInertia = (e1, e2, treshold = 10) => {
const v1 = getDeltas(e1);
const v2 = getDeltas(e2);
return v1.some((delta, i) => {
const diff = delta - v2[i];
const maxDiff = Math.max(10, (delta * treshold) / 100);
return diff > maxDiff;
/** If e2 event is inertia, it's delta will be no more than threshold slower */
const isAnomalyInertia = (e1, e2, threshold = 10) => {
const v1 = getDeltas(e1).map(Math.abs);
const v2 = getDeltas(e2).map(Math.abs);
return v2.some((delta, i) => {
const actualDiff = v1[i] - delta;
const believableDiff = Math.max(10, v1[i] * (threshold / 100));
return actualDiff > believableDiff;
});
};
var CHECK_RESULT_CODES;
(function (CHECK_RESULT_CODES) {
CHECK_RESULT_CODES["ALL_OTHER_CHECKS_FAILED"] = "ALL_OTHER_CHECKS_FAILED";
CHECK_RESULT_CODES["NO_PREVIOUS_EVENT_TO_COMPARE"] = "NO_PREVIOUS_EVENT_TO_COMPARE";
CHECK_RESULT_CODES["PAST_TIMESTAMP_EVENT"] = "PAST_TIMESTAMP_EVENT";
CHECK_RESULT_CODES["ENOUGH_TIME_PASSED"] = "ENOUGH_TIME_PASSED";
CHECK_RESULT_CODES["DELTA_MODULE_IS_BIGGER"] = "DELTA_MODULE_IS_BIGGER";
CHECK_RESULT_CODES["VECTORS_DONT_MATCH"] = "VECTORS_DONT_MATCH";
CHECK_RESULT_CODES["HIGH_VELOCITY_NON_DECREASING_DELTAS"] = "HIGH_VELOCITY_NON_DECREASING_DELTAS";
CHECK_RESULT_CODES["NON_DECREASING_DELTAS_OF_KNOWN_HUMAN"] = "NON_DECREASING_DELTAS_OF_KNOWN_HUMAN";
CHECK_RESULT_CODES["ANOMALY_INERTIA_JUMP"] = "ANOMALY_INERTIA_JUMP";
})(CHECK_RESULT_CODES || (CHECK_RESULT_CODES = {}));
class Lethargy {
constructor({ sensitivity = 20, inertiaDecay = 10, delay = 100 } = {}) {
constructor({ sensitivity = 2, inertiaDecay = 20, delay = 100, highVelocity = 100, } = {}) {
this.sensitivity = Math.max(1, sensitivity);
this.inertiaDecay = Math.max(1, inertiaDecay);
this.delay = Math.max(1, delay);
this.highVelocity = Math.max(1, highVelocity);
// Reset inner state
this.previousEvents = [];
}
/** Checks whether the mousewheel event is an intent */
/** Checks whether the wheel event is an intent.
* Remembers a passed event to compare future events with it */
check(e) {

@@ -61,3 +76,3 @@ var _a;

if (!isEvent)
return null;
throw new Error("No event provided");
const event = getWheelEvent(e);

@@ -68,3 +83,3 @@ // DeltaModule is too small

}
const isHuman = this.isHuman(event);
const { isHuman } = this.isHuman(event);
// If event is human, reset previousEvents

@@ -80,2 +95,3 @@ if (isHuman) {

}
/** Checks whether the wheel event is an intent */
isHuman(event) {

@@ -85,7 +101,21 @@ const previousEvent = this.previousEvents.at(-1);

if (!previousEvent) {
return true;
return {
isHuman: true,
reason: CHECK_RESULT_CODES.NO_PREVIOUS_EVENT_TO_COMPARE,
};
}
// Wtf, event from the past? o_O
// Skip all checks
if (event.timeStamp < previousEvent.timeStamp) {
return {
isHuman: true,
reason: CHECK_RESULT_CODES.PAST_TIMESTAMP_EVENT,
};
}
// Enough of time passed from the last event
if (event.timeStamp > previousEvent.timeStamp + this.delay) {
return true;
return {
isHuman: true,
reason: CHECK_RESULT_CODES.ENOUGH_TIME_PASSED,
};
}

@@ -96,27 +126,47 @@ const biggestDeltaModule = getBiggestDeltaModule(event);

if (biggestDeltaModule > previousBiggestDeltaModule) {
return true;
return {
isHuman: true,
reason: CHECK_RESULT_CODES.DELTA_MODULE_IS_BIGGER,
};
}
// Vectors don't match
if (!compareVectors(event, previousEvent)) {
return true;
return {
isHuman: true,
reason: CHECK_RESULT_CODES.VECTORS_DONT_MATCH,
};
}
// Non-decreasing deltas above 100 are likely human
if (biggestDeltaModule >= 100 && biggestDeltaModule === previousBiggestDeltaModule) {
return true;
// High velocity non-decreasing deltas are likely human
if (biggestDeltaModule >= this.highVelocity &&
biggestDeltaModule === previousBiggestDeltaModule) {
return {
isHuman: true,
reason: CHECK_RESULT_CODES.HIGH_VELOCITY_NON_DECREASING_DELTAS,
};
}
const lastKnownHumanEvent = this.previousEvents[0];
// Non-decreasing deltas of known human event are likely human
if (biggestDeltaModule === getBiggestDeltaModule(lastKnownHumanEvent)) {
return true;
if (this.previousEvents.length === 1 &&
biggestDeltaModule === getBiggestDeltaModule(lastKnownHumanEvent)) {
return {
isHuman: true,
reason: CHECK_RESULT_CODES.NON_DECREASING_DELTAS_OF_KNOWN_HUMAN,
};
}
// If speed of delta's change suddenly jumped, it's likely human
if (isAnomalyInertia(previousEvent, event, this.inertiaDecay)) {
return true;
return {
isHuman: true,
reason: CHECK_RESULT_CODES.ANOMALY_INERTIA_JUMP,
};
}
// No human checks passed. It's probably inertia
return false;
return {
isHuman: false,
reason: CHECK_RESULT_CODES.ALL_OTHER_CHECKS_FAILED,
};
}
}
export { Lethargy };
export { CHECK_RESULT_CODES, Lethargy, compareVectors, getBiggestDeltaModule, getDeltas, getSign, getWheelEvent, isAnomalyInertia };
//# sourceMappingURL=index.esm.js.map

102

lib/index.js

@@ -37,22 +37,37 @@ 'use strict';

};
/** If e2 event is inertia, it's delta will be no more than treshold slower */
const isAnomalyInertia = (e1, e2, treshold = 10) => {
const v1 = getDeltas(e1);
const v2 = getDeltas(e2);
return v1.some((delta, i) => {
const diff = delta - v2[i];
const maxDiff = Math.max(10, (delta * treshold) / 100);
return diff > maxDiff;
/** If e2 event is inertia, it's delta will be no more than threshold slower */
const isAnomalyInertia = (e1, e2, threshold = 10) => {
const v1 = getDeltas(e1).map(Math.abs);
const v2 = getDeltas(e2).map(Math.abs);
return v2.some((delta, i) => {
const actualDiff = v1[i] - delta;
const believableDiff = Math.max(10, v1[i] * (threshold / 100));
return actualDiff > believableDiff;
});
};
exports.CHECK_RESULT_CODES = void 0;
(function (CHECK_RESULT_CODES) {
CHECK_RESULT_CODES["ALL_OTHER_CHECKS_FAILED"] = "ALL_OTHER_CHECKS_FAILED";
CHECK_RESULT_CODES["NO_PREVIOUS_EVENT_TO_COMPARE"] = "NO_PREVIOUS_EVENT_TO_COMPARE";
CHECK_RESULT_CODES["PAST_TIMESTAMP_EVENT"] = "PAST_TIMESTAMP_EVENT";
CHECK_RESULT_CODES["ENOUGH_TIME_PASSED"] = "ENOUGH_TIME_PASSED";
CHECK_RESULT_CODES["DELTA_MODULE_IS_BIGGER"] = "DELTA_MODULE_IS_BIGGER";
CHECK_RESULT_CODES["VECTORS_DONT_MATCH"] = "VECTORS_DONT_MATCH";
CHECK_RESULT_CODES["HIGH_VELOCITY_NON_DECREASING_DELTAS"] = "HIGH_VELOCITY_NON_DECREASING_DELTAS";
CHECK_RESULT_CODES["NON_DECREASING_DELTAS_OF_KNOWN_HUMAN"] = "NON_DECREASING_DELTAS_OF_KNOWN_HUMAN";
CHECK_RESULT_CODES["ANOMALY_INERTIA_JUMP"] = "ANOMALY_INERTIA_JUMP";
})(exports.CHECK_RESULT_CODES || (exports.CHECK_RESULT_CODES = {}));
class Lethargy {
constructor({ sensitivity = 20, inertiaDecay = 10, delay = 100 } = {}) {
constructor({ sensitivity = 2, inertiaDecay = 20, delay = 100, highVelocity = 100, } = {}) {
this.sensitivity = Math.max(1, sensitivity);
this.inertiaDecay = Math.max(1, inertiaDecay);
this.delay = Math.max(1, delay);
this.highVelocity = Math.max(1, highVelocity);
// Reset inner state
this.previousEvents = [];
}
/** Checks whether the mousewheel event is an intent */
/** Checks whether the wheel event is an intent.
* Remembers a passed event to compare future events with it */
check(e) {

@@ -63,3 +78,3 @@ var _a;

if (!isEvent)
return null;
throw new Error("No event provided");
const event = getWheelEvent(e);

@@ -70,3 +85,3 @@ // DeltaModule is too small

}
const isHuman = this.isHuman(event);
const { isHuman } = this.isHuman(event);
// If event is human, reset previousEvents

@@ -82,2 +97,3 @@ if (isHuman) {

}
/** Checks whether the wheel event is an intent */
isHuman(event) {

@@ -87,7 +103,21 @@ const previousEvent = this.previousEvents.at(-1);

if (!previousEvent) {
return true;
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.NO_PREVIOUS_EVENT_TO_COMPARE,
};
}
// Wtf, event from the past? o_O
// Skip all checks
if (event.timeStamp < previousEvent.timeStamp) {
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.PAST_TIMESTAMP_EVENT,
};
}
// Enough of time passed from the last event
if (event.timeStamp > previousEvent.timeStamp + this.delay) {
return true;
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.ENOUGH_TIME_PASSED,
};
}

@@ -98,23 +128,43 @@ const biggestDeltaModule = getBiggestDeltaModule(event);

if (biggestDeltaModule > previousBiggestDeltaModule) {
return true;
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.DELTA_MODULE_IS_BIGGER,
};
}
// Vectors don't match
if (!compareVectors(event, previousEvent)) {
return true;
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.VECTORS_DONT_MATCH,
};
}
// Non-decreasing deltas above 100 are likely human
if (biggestDeltaModule >= 100 && biggestDeltaModule === previousBiggestDeltaModule) {
return true;
// High velocity non-decreasing deltas are likely human
if (biggestDeltaModule >= this.highVelocity &&
biggestDeltaModule === previousBiggestDeltaModule) {
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.HIGH_VELOCITY_NON_DECREASING_DELTAS,
};
}
const lastKnownHumanEvent = this.previousEvents[0];
// Non-decreasing deltas of known human event are likely human
if (biggestDeltaModule === getBiggestDeltaModule(lastKnownHumanEvent)) {
return true;
if (this.previousEvents.length === 1 &&
biggestDeltaModule === getBiggestDeltaModule(lastKnownHumanEvent)) {
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.NON_DECREASING_DELTAS_OF_KNOWN_HUMAN,
};
}
// If speed of delta's change suddenly jumped, it's likely human
if (isAnomalyInertia(previousEvent, event, this.inertiaDecay)) {
return true;
return {
isHuman: true,
reason: exports.CHECK_RESULT_CODES.ANOMALY_INERTIA_JUMP,
};
}
// No human checks passed. It's probably inertia
return false;
return {
isHuman: false,
reason: exports.CHECK_RESULT_CODES.ALL_OTHER_CHECKS_FAILED,
};
}

@@ -124,2 +174,8 @@ }

exports.Lethargy = Lethargy;
exports.compareVectors = compareVectors;
exports.getBiggestDeltaModule = getBiggestDeltaModule;
exports.getDeltas = getDeltas;
exports.getSign = getSign;
exports.getWheelEvent = getWheelEvent;
exports.isAnomalyInertia = isAnomalyInertia;
//# sourceMappingURL=index.js.map

2

lib/types/index.d.ts
export * from "./lethargy";
export * from "./utils";
export * from "./codes";
export * from "./types";

17

lib/types/lethargy.d.ts

@@ -0,1 +1,2 @@

import type { LethargyConfig } from "./types";
export declare class Lethargy {

@@ -8,12 +9,12 @@ /** The wheelDelta threshold. If an event has a wheelDelta below this value, it will not register */

inertiaDecay: number;
/** [lastKnownHumanEvent, ...inertiaEvents] */
/** `[lastKnownHumanEvent, ...inertiaEvents]` */
private previousEvents;
constructor({ sensitivity, inertiaDecay, delay }?: {
sensitivity?: number | undefined;
inertiaDecay?: number | undefined;
delay?: number | undefined;
});
/** Checks whether the mousewheel event is an intent */
check(e: WheelEvent): boolean | null;
/** Deltas above this are considered high velocity */
private highVelocity;
constructor({ sensitivity, inertiaDecay, delay, highVelocity, }?: LethargyConfig);
/** Checks whether the wheel event is an intent.
* Remembers a passed event to compare future events with it */
check(e: WheelEvent): boolean;
/** Checks whether the wheel event is an intent */
private isHuman;
}

6

lib/types/types.d.ts
/** [deltaX, deltaY, deltaZ] */
export type Deltas = [number, number, number];
export type IWheelEvent = Pick<WheelEvent, "deltaX" | "deltaY" | "deltaZ" | "timeStamp">;
export interface LethargyConfig {
sensitivity?: number;
inertiaDecay?: number;
delay?: number;
highVelocity?: number;
}

6

lib/types/utils.d.ts

@@ -8,5 +8,7 @@ import type { Deltas, IWheelEvent } from "./types";

export declare const getBiggestDeltaModule: (e: IWheelEvent) => number;
/** Values below treshhold are considered 0 */
export declare const getSign: (num: number, treshhold?: number) => number;
/** Returns true if two vectors are equal */
export declare const compareVectors: (e1: IWheelEvent, e2: IWheelEvent, treshhold?: number) => boolean;
/** If e2 event is inertia, it's delta will be no more than treshold slower */
export declare const isAnomalyInertia: (e1: IWheelEvent, e2: IWheelEvent, treshold?: number) => boolean;
/** If e2 event is inertia, it's delta will be no more than threshold slower */
export declare const isAnomalyInertia: (e1: IWheelEvent, e2: IWheelEvent, threshold?: number) => boolean;

20

package.json
{
"name": "lethargy-ts",
"version": "0.0.3",
"version": "0.0.4",
"description": "Distinguish between scroll events initiated by the user, and those by inertial scrolling",

@@ -29,2 +29,4 @@ "repository": "https://github.com/snelsi/lethargy-ts",

"fix": "npm run prettier && npm run lint-fix",
"test": "vitest",
"coverage": "vitest run --coverage",
"pre-commit": "npm run lint && lint-staged",

@@ -35,6 +37,8 @@ "prepublishOnly": "npm run rollup"

"@rollup/plugin-typescript": "^11.0.0",
"@typescript-eslint/eslint-plugin": "^5.52.0",
"@typescript-eslint/parser": "^5.52.0",
"eslint": "^8.34.0",
"eslint-config-prettier": "^8.6.0",
"@typescript-eslint/eslint-plugin": "^5.54.1",
"@typescript-eslint/parser": "^5.54.1",
"@vitest/coverage-c8": "^0.29.2",
"eslint": "^8.35.0",
"eslint-config-prettier": "^8.7.0",
"happy-dom": "^8.9.0",
"husky": "^8.0.3",

@@ -44,4 +48,6 @@ "lint-staged": "^13.1.2",

"pretty-quick": "^3.1.3",
"rollup": "^3.17.0",
"typescript": "^4.9.5"
"rollup": "^3.18.0",
"typescript": "^4.9.5",
"vite": "^4.1.4",
"vitest": "^0.29.2"
},

@@ -48,0 +54,0 @@ "lint-staged": {

55

README.md
# ⭐ Lethargy-TS
`lethargy-ts` is a modern rewrite of `lethargy` – a popular JavaScript library to help distinguish between scroll events initiated by the user, and those by inertial scrolling.
`lethargy-ts` is a modern TypeScript rewrite of `lethargy` – a popular JavaScript library to help distinguish between scroll events initiated by the user, and those by inertial scrolling.

@@ -10,7 +10,7 @@ [![npm (scoped)](https://img.shields.io/npm/v/lethargy-ts?style=flat-square)](https://www.npmjs.com/package/lethargy-ts)

🌳 Tiny and Easy to use
🌳 Tiny and easy to use
🦄 Written in TypeScript
🎏 Highly Customizable
🎏 Highly customizable

@@ -21,2 +21,4 @@ 🏖 No external dependencies

Install with Yarn:
```ssh

@@ -26,3 +28,3 @@ yarn add lethargy-ts

or
Or with npm:

@@ -35,3 +37,3 @@ ```ssh

Import and create an instance of `Lethargy`. It will remember previously checked `wheelEvents` to help to determine if they are inertial or not:
Import and create an instance of `Lethargy`. It will remember previously checked `wheelEvents` to help determine if they are inertial or not:

@@ -44,13 +46,13 @@ ```tsx

You can customize parameters to better match your application's needs:
You can customize the sensitivity, delay, and inertia decay parameters to better match your application's needs:
```tsx
const lethargy = new Lethargy({
sensitivity: 20,
sensitivity: 2,
delay: 100,
inertiaDecay: 10,
inertiaDecay: 20,
});
```
> 😉 If you found optimizations for the defaults, please share them in this [ticket](https://github.com/d4nyll/lethargy/issues/2)!
> 😉 If you find optimizations for the defaults, please share them in this [ticket](https://github.com/snelsi/lethargy-ts/issues/1)!

@@ -73,26 +75,41 @@ Bind the wheel event and pass the event to `Lethargy`:

`Lethargy` focus on preventing false positives (saying it's a normal scroll event when it wasn't), but tolerates false negatives (saying it's not a normal scroll event when it is).
## Options
All options are optional:
All parameters are optional:
- `sensitivity` - Specifies the minimum value for `wheelDelta` for it to register as a valid scroll event. Because the tail of the curve has low `wheelDelta` values, this will stop them from registering as valid scroll events.
- `delay` - Threshold for the amount of time between mouse wheel events for them to be deemed separate.
- `delay` - Threshold for the amount of time between wheel events for them to be deemed separate.
- `inertiaDecay` - Inertia event may be no more than this percents smaller that previous event.
- `inertiaDecay` - Inertia event may be no more than this percent smaller than the previous event.
## What problem does it solve?
Scroll plugins such as [smartscroll](https://github.com/d4nyll/smartscroll), [jquery-mousewheel](https://github.com/jquery/jquery-mousewheel), or [fullPage.js](http://alvarotrigo.com/fullPage/) work by detecting scroll events and then doing something with them, such as scroll to the next frame. However, inertial scrolling continues to emit scroll events even after the user stopped, and this can often lead to problems, such as scrolling two to three frames when the user only scrolled once.
Scroll plugins such as [smartscroll](https://github.com/d4nyll/smartscroll), [jquery-mousewheel](https://github.com/jquery/jquery-mousewheel), or [fullPage.js](http://alvarotrigo.com/fullPage/) work by detecting scroll events and then doing something with them, such as scrolling to the next frame. However, inertial scrolling continues to emit scroll events even after the user stopped, and this can often lead to problems, such as scrolling multiple frames when the user only intended to scroll once. `lethargy-ts` helps distinguish between scroll events initiated by the user and those by inertial scrolling, making it easier to create smooth and accurate scrolling experiences.
## How does it work?
## How it works
Lethargy keeps a record of the last few `wheelDelta` values that are passed through it, it will then work out whether these values are decreasing (decaying), and if so, concludes that the scroll event originated from inertial scrolling, and not directly from the user.
`lethargy-ts` uses a set of checks to determine if a scroll event is initiated by the user or by inertial scrolling. The following checks are performed:
- Enough time has passed between two events.
- The delta of the event is bigger than the delta of the previous event.
- The vector of the event differs from the previous event.
- The delta of the event has a high velocity and doesn't decrease.
- The delta of the event doesn't decrease and immediately follows a known human event.
- The speed of the delta's change suddenly jumped.
If any of these checks are true, the event is considered intentional. Otherwise, it is considered to be initiated by inertial scrolling.
## Limitations
Not all trackpads work the same, some trackpads do not have a decaying `wheelDelta` value, so our method of decay detection would not work. Instead, to cater to this situation, we had to, grudgingly, set a very small time delay between when events will register. We have tested this and normal use does not affect user experience more than usual.
Not all trackpads work the same, so `Lethargy` makes its best effort to cover as many use cases as possible, but full coverage is not guaranteed. `Lethargy` focuses on preventing false positives (i.e., saying it's a normal scroll event when it wasn't) but tolerates false negatives (i.e., saying it's not a normal scroll event when it is).
Sadly, right now there is no easy native way to tell if the wheel event was generated by the user or by inertia.
You can change this by leaving an upvote and a comment in the [w3c proposal ticket](https://github.com/w3c/uievents/issues/58). 👈
## TypeScript

@@ -108,3 +125,3 @@

Give a ⭐️ if you like this project!
If you find this project useful, please give it a star on GitHub! ⭐️

@@ -111,0 +128,0 @@ ## LICENSE

lib/index.esm.js.map

Sorry, the diff of this file is not supported yet

lib/index.js.map

Sorry, the diff of this file is not supported yet