@vpmedia/simplify 1.11.0 → 1.13.0

package/README.md

@@ -1,6 +1,6 @@
 # @vpmedia/simplify
 
-[![npm version](https://badge.fury.io/js/@vpmedia%2Fsimplify.svg?v=1.11.0)](https://badge.fury.io/js/@vpmedia%2Fsimplify)
+[![npm version](https://badge.fury.io/js/@vpmedia%2Fsimplify.svg?v=1.13.0)](https://badge.fury.io/js/@vpmedia%2Fsimplify)
 [![Node.js CI](https://github.com/vpmedia/simplify/actions/workflows/ci.yml/badge.svg)](https://github.com/vpmedia/simplify/actions/workflows/ci.yml)
 
 @vpmedia/simplify TBD

package/eslint.config.js

@@ -51,6 +51,7 @@ export default [
       ...js.configs.recommended.rules,
       ...jsdocPlugin.configs['flat/recommended'].rules,
       ...unicornPlugin.configs['flat/recommended'].rules,
+      'unicorn/expiring-todo-comments': 'off',
       'unicorn/filename-case': 'off',
       'unicorn/no-null': 'off',
       'unicorn/prevent-abbreviations': 'off',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpmedia/simplify",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "@vpmedia/simplify",
   "author": "Andras Csizmadia <andras@vpmedia.hu> (www.vpmedia.hu)",
   "license": "MIT",
@@ -19,17 +19,17 @@
   "types": "./types/index.d.ts",
   "type": "module",
   "devDependencies": {
-    "@babel/preset-env": "^7.25.8",
-    "@eslint/js": "^9.12.0",
+    "@babel/preset-env": "^7.26.0",
+    "@eslint/js": "^9.15.0",
     "@jest/globals": "^29.7.0",
-    "@types/jest": "^29.5.13",
-    "eslint": "^9.12.0",
-    "eslint-plugin-jsdoc": "^50.3.2",
+    "@types/jest": "^29.5.14",
+    "eslint": "^9.15.0",
+    "eslint-plugin-jsdoc": "^50.5.0",
     "eslint-plugin-unicorn": "^56.0.0",
-    "globals": "^15.11.0",
+    "globals": "^15.12.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "lefthook": "^1.7.18",
+    "lefthook": "^1.8.4",
     "prettier": "^3.3.3",
     "typescript": "^5.6.3"
   },
@@ -45,5 +45,8 @@
     "> 0.5%",
     "not dead",
     "not op_mini all"
-  ]
+  ],
+  "dependencies": {
+    "eventemitter3": "^5.0.1"
+  }
 }

package/src/index.js

@@ -1,6 +1,10 @@
 // core
 export * from './const/http_status.js';
 export { Logger } from './logging/Logger.js';
+export * from './pagelifecycle/const.js';
+export * from './pagelifecycle/event.js';
+export * from './pagelifecycle/typedef.js';
+export * from './pagelifecycle/util.js';
 export { addLeadingZero } from './util/addLeadingZero.js';
 export { capitalize } from './util/capitalize.js';
 export { deg2rad } from './util/deg2rad.js';
@@ -16,3 +20,4 @@ export { sanitizeURLParam } from './util/sanitizeURLParam.js';
 export { saveAsFile } from './util/saveAsFile.js';
 export { setObjValueByPath } from './util/setObjValueByPath.js';
 export { underscoreToCamelCase } from './util/underscoreToCamelCase.js';
+

package/src/logging/Logger.js

@@ -13,7 +13,7 @@ export class Logger {
    */
   static exceptionHandler = null;
   /**
-   * @type {(level: string, message: string, extraData: object) => void}
+   * @type {(target: string, level: string, message: string, extraData: object) => void}
    */
   static suppressedLogHandler = null;
 
@@ -38,7 +38,7 @@ export class Logger {
   debug(message, extraData = null) {
     if (this.level < LEVEL_DEBUG) {
       if (Logger.suppressedLogHandler) {
-        Logger.suppressedLogHandler('debug', message, extraData);
+        Logger.suppressedLogHandler(this.name, 'debug', message, extraData);
       }
       return;
     }
@@ -58,7 +58,7 @@ export class Logger {
   info(message, extraData = null) {
     if (this.level < LEVEL_INFO) {
       if (Logger.suppressedLogHandler) {
-        Logger.suppressedLogHandler('info', message, extraData);
+        Logger.suppressedLogHandler(this.name, 'info', message, extraData);
       }
       return;
     }
@@ -78,7 +78,7 @@ export class Logger {
   warn(message, extraData = null) {
     if (this.level < LEVEL_WARN) {
       if (Logger.suppressedLogHandler) {
-        Logger.suppressedLogHandler('warning', message, extraData);
+        Logger.suppressedLogHandler(this.name, 'warning', message, extraData);
       }
       return;
     }
@@ -98,7 +98,7 @@ export class Logger {
   error(message, extraData = null) {
     if (this.level < LEVEL_ERROR) {
       if (Logger.suppressedLogHandler) {
-        Logger.suppressedLogHandler('error', message, extraData);
+        Logger.suppressedLogHandler(this.name, 'error', message, extraData);
       }
       return;
     }

package/src/pagelifecycle/const.js

@@ -0,0 +1,11 @@
+export const PAGE_LIFECYCLE_STATE_HIDDEN = 'hidden';
+export const PAGE_LIFECYCLE_STATE_ACTIVE = 'active';
+export const PAGE_LIFECYCLE_STATE_PASSIVE = 'passive';
+export const PAGE_LIFECYCLE_STATE_FROZEN = 'frozen';
+export const PAGE_LIFECYCLE_STATE_TERMINATED = 'terminated';
+
+export const DOCUMENT_STATE_DOM_LOADED = 'domLoaded';
+export const DOCUMENT_STATE_FULLY_LOADED = 'fullyLoaded';
+export const DOCUMENT_STATE_COMPLETE = 'complete';
+export const DOCUMENT_STATE_INTERACTIVE = 'interactive';
+export const DOCUMENT_STATE_LOADING = 'loading';

package/src/pagelifecycle/event.js

@@ -0,0 +1,2 @@
+export const PAGE_LIFECYCLE_STATE_CHANGE_EVENT = 'pageLifecycleStateChange';
+export const DOCUMENT_STATE_CHANGE_EVENT = 'documentStateChange';

package/src/pagelifecycle/typedef.js

@@ -0,0 +1,9 @@
+export const TYPEDEF = true;
+
+/**
+ * @typedef {import('./const.js').PAGE_LIFECYCLE_STATE_HIDDEN | import('./const.js').PAGE_LIFECYCLE_STATE_ACTIVE | import('./const.js').PAGE_LIFECYCLE_STATE_PASSIVE | import('./const.js').PAGE_LIFECYCLE_STATE_FROZEN | import('./const.js').PAGE_LIFECYCLE_STATE_TERMINATED} PageLifecycleState
+ */
+
+/**
+ * @typedef {import('./const.js').DOCUMENT_STATE_LOADING | import('./const.js').DOCUMENT_STATE_INTERACTIVE | import('./const.js').DOCUMENT_STATE_COMPLETE | import('./const.js').DOCUMENT_STATE_DOM_LOADED | import('./const.js').DOCUMENT_STATE_FULLY_LOADED} DocumentState
+ */

package/src/pagelifecycle/util.js

@@ -0,0 +1,164 @@
+/**
+ * Page lifecycle helper.
+ * @see https://developer.chrome.com/docs/web-platform/page-lifecycle-api
+ */
+
+import { EventEmitter } from 'eventemitter3';
+import { Logger } from '../logging/Logger.js';
+import {
+  DOCUMENT_STATE_DOM_LOADED,
+  DOCUMENT_STATE_FULLY_LOADED,
+  PAGE_LIFECYCLE_STATE_ACTIVE,
+  PAGE_LIFECYCLE_STATE_FROZEN,
+  PAGE_LIFECYCLE_STATE_HIDDEN,
+  PAGE_LIFECYCLE_STATE_PASSIVE,
+  PAGE_LIFECYCLE_STATE_TERMINATED,
+} from './const.js';
+import { DOCUMENT_STATE_CHANGE_EVENT, PAGE_LIFECYCLE_STATE_CHANGE_EVENT } from './event.js';
+
+const logger = new Logger('PageLifecycle');
+
+const eventEmitter = new EventEmitter();
+
+/** @type {import('./typedef.js').PageLifecycleState} */
+let currentPageLifecycleState = null;
+
+/** @type {import('./typedef.js').DocumentState} */
+let currentDocumentState = null;
+
+let isInitialized = false;
+
+/** @type {{[key: string]: Function[]}} */
+let callbacks = {};
+
+/**
+ * Add callback for a specific state change.
+ * @param {import('./typedef.js').DocumentState | import('./typedef.js').PageLifecycleState} state - Callback state condition.
+ * @param {() => void} callback - Callback function.
+ */
+export const addCallback = (state, callback) => {
+  const stateCallbacks = callbacks[state] ?? [];
+  stateCallbacks.push(callback);
+  callbacks[state] = stateCallbacks;
+};
+
+/**
+ * Run callbacks for a specific state change.
+ * @param {import('./typedef.js').DocumentState | import('./typedef.js').PageLifecycleState} state - Callback state condition.
+ */
+const processCallbacks = (state) => {
+  const stateCallbacks = callbacks[state];
+  if (!stateCallbacks) {
+    return;
+  }
+  for (const callback of stateCallbacks) {
+    callback();
+  }
+  stateCallbacks.length = 0;
+};
+
+/**
+ * Detects the current page lifecycle state.
+ * @returns {import('./typedef.js').PageLifecycleState} Current page lifecycle state.
+ */
+const detectPageLifecycleState = () => {
+  if (document.visibilityState === 'hidden') {
+    return PAGE_LIFECYCLE_STATE_HIDDEN;
+  }
+  if (document.hasFocus()) {
+    return PAGE_LIFECYCLE_STATE_ACTIVE;
+  }
+  return PAGE_LIFECYCLE_STATE_PASSIVE;
+};
+
+/**
+ * Handles page lifecycle state change.
+ * @param {import('./typedef.js').PageLifecycleState} nextState - Next page lifecycle state.
+ */
+const onPageLifecycleStateChange = (nextState) => {
+  const previousState = currentPageLifecycleState;
+  if (nextState !== previousState) {
+    currentPageLifecycleState = nextState;
+    const eventData = { previousState, nextState };
+    logger.info(PAGE_LIFECYCLE_STATE_CHANGE_EVENT, eventData);
+    eventEmitter.emit(PAGE_LIFECYCLE_STATE_CHANGE_EVENT, eventData);
+    processCallbacks(currentPageLifecycleState);
+  }
+};
+
+/**
+ * Handles document state change.
+ * @param {import('./typedef.js').DocumentState} nextState - Next document state.
+ */
+const onDocumentStateChange = (nextState) => {
+  const previousState = currentDocumentState;
+  if (nextState !== previousState) {
+    currentDocumentState = nextState;
+    const eventData = { previousState, nextState };
+    logger.info(DOCUMENT_STATE_CHANGE_EVENT, eventData);
+    eventEmitter.emit(DOCUMENT_STATE_CHANGE_EVENT, eventData);
+    processCallbacks(currentDocumentState);
+  }
+};
+
+/**
+ * Initialize page lifecycle observer.
+ */
+export const initPageLifecycle = () => {
+  if (isInitialized) {
+    return;
+  }
+  logger.info('initPageLifecycle');
+  // DEV: capturing events are mandatory to propagate events to root window
+  const options = { capture: true };
+  onPageLifecycleStateChange(detectPageLifecycleState());
+  for (const eventType of ['pageshow', 'focus', 'blur', 'visibilitychange', 'resume']) {
+    window.addEventListener(eventType, () => onPageLifecycleStateChange(detectPageLifecycleState()), options);
+  }
+  window.addEventListener('freeze', () => onPageLifecycleStateChange(PAGE_LIFECYCLE_STATE_FROZEN), options);
+  window.addEventListener(
+    'pagehide',
+    (event) =>
+      onPageLifecycleStateChange(event.persisted ? PAGE_LIFECYCLE_STATE_FROZEN : PAGE_LIFECYCLE_STATE_TERMINATED),
+    options
+  );
+  window.addEventListener('DOMContentLoaded', () => onDocumentStateChange(DOCUMENT_STATE_DOM_LOADED), options);
+  window.addEventListener('readystatechange', () => onDocumentStateChange(document.readyState), options);
+  window.addEventListener('load', () => onDocumentStateChange(DOCUMENT_STATE_FULLY_LOADED), options);
+  isInitialized = true;
+};
+
+/**
+ * Returns the current page lifecycle state.
+ * @returns {string} Current page lifecycle state.
+ */
+export const getPageLifecycleState = () => {
+  return currentPageLifecycleState;
+};
+
+/**
+ * Returns the current document state.
+ * @returns {import('./typedef.js').DocumentState} Current document state.
+ */
+export const getDocumentState = () => {
+  return currentDocumentState;
+};
+
+/**
+ * Returns the event emitter instance.
+ * @returns {EventEmitter} Event emitter instance.
+ */
+export const getEventEmitter = () => {
+  if (!isInitialized) {
+    initPageLifecycle();
+  }
+  return eventEmitter;
+};
+
+/**
+ * Returns the page lifecycle observer initialized state.
+ * @returns {boolean} Page lifecycle observer initialized flag.
+ */
+export const isObserverInitialized = () => {
+  return isInitialized;
+};

package/types/index.d.ts

@@ -1,4 +1,8 @@
 export * from "./const/http_status.js";
+export * from "./pagelifecycle/const.js";
+export * from "./pagelifecycle/event.js";
+export * from "./pagelifecycle/typedef.js";
+export * from "./pagelifecycle/util.js";
 export { Logger } from "./logging/Logger.js";
 export { addLeadingZero } from "./util/addLeadingZero.js";
 export { capitalize } from "./util/capitalize.js";

package/types/logging/Logger.d.ts

@@ -9,9 +9,9 @@ export class Logger {
      */
     static exceptionHandler: (error: Error) => void;
     /**
-     * @type {(level: string, message: string, extraData: object) => void}
+     * @type {(target: string, level: string, message: string, extraData: object) => void}
      */
-    static suppressedLogHandler: (level: string, message: string, extraData: object) => void;
+    static suppressedLogHandler: (target: string, level: string, message: string, extraData: object) => void;
     /**
      * Creates a new Logger instance.
      * @param {string} name - The logger name.

package/types/logging/Logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/logging/Logger.js"],"names":[],"mappings":"AAGA,4BAA6B;AAC7B,2BAA4B;AAC5B,2BAA4B;AAC5B,4BAA6B;AAC7B,6BAA8B;AAE9B;IACE;;OAEG;IACH,yBAFU,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAED;IAC/B;;OAEG;IACH,6BAFU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAElC;IAEnC;;;OAGG;IACH,kBAFW,MAAM,EAShB;IANC,aAAgB;IAKhB,cAAkG;IAGpG;;;;OAIG;IACH,eAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,cAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,cAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,eAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,mBAHW,MAAM,aACN,KAAK,QAWf;CACF"}
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/logging/Logger.js"],"names":[],"mappings":"AAGA,4BAA6B;AAC7B,2BAA4B;AAC5B,2BAA4B;AAC5B,4BAA6B;AAC7B,6BAA8B;AAE9B;IACE;;OAEG;IACH,yBAFU,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAED;IAC/B;;OAEG;IACH,6BAFU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAElD;IAEnC;;;OAGG;IACH,kBAFW,MAAM,EAShB;IANC,aAAgB;IAKhB,cAAkG;IAGpG;;;;OAIG;IACH,eAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,cAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,cAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,eAHW,MAAM,cACN,MAAM,QAehB;IAED;;;;OAIG;IACH,mBAHW,MAAM,aACN,KAAK,QAWf;CACF"}

package/types/pagelifecycle/const.d.ts

@@ -0,0 +1,11 @@
+export const PAGE_LIFECYCLE_STATE_HIDDEN: "hidden";
+export const PAGE_LIFECYCLE_STATE_ACTIVE: "active";
+export const PAGE_LIFECYCLE_STATE_PASSIVE: "passive";
+export const PAGE_LIFECYCLE_STATE_FROZEN: "frozen";
+export const PAGE_LIFECYCLE_STATE_TERMINATED: "terminated";
+export const DOCUMENT_STATE_DOM_LOADED: "domLoaded";
+export const DOCUMENT_STATE_FULLY_LOADED: "fullyLoaded";
+export const DOCUMENT_STATE_COMPLETE: "complete";
+export const DOCUMENT_STATE_INTERACTIVE: "interactive";
+export const DOCUMENT_STATE_LOADING: "loading";
+//# sourceMappingURL=const.d.ts.map

package/types/pagelifecycle/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/pagelifecycle/const.js"],"names":[],"mappings":"AAAA,mDAAoD;AACpD,mDAAoD;AACpD,qDAAsD;AACtD,mDAAoD;AACpD,2DAA4D;AAE5D,oDAAqD;AACrD,wDAAyD;AACzD,iDAAkD;AAClD,uDAAwD;AACxD,+CAAgD"}

package/types/pagelifecycle/event.d.ts

@@ -0,0 +1,3 @@
+export const PAGE_LIFECYCLE_STATE_CHANGE_EVENT: "pageLifecycleStateChange";
+export const DOCUMENT_STATE_CHANGE_EVENT: "documentStateChange";
+//# sourceMappingURL=event.d.ts.map

package/types/pagelifecycle/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/pagelifecycle/event.js"],"names":[],"mappings":"AAAA,2EAA4E;AAC5E,gEAAiE"}

package/types/pagelifecycle/typedef.d.ts

@@ -0,0 +1,4 @@
+export const TYPEDEF: true;
+export type PageLifecycleState = "hidden" | "active" | "passive" | "frozen" | "terminated";
+export type DocumentState = "loading" | "interactive" | "complete" | "domLoaded" | "fullyLoaded";
+//# sourceMappingURL=typedef.d.ts.map

package/types/pagelifecycle/typedef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedef.d.ts","sourceRoot":"","sources":["../../src/pagelifecycle/typedef.js"],"names":[],"mappings":"AAAA,2BAA4B;iCAGf,QAAgD,GAAG,QAAgD,GAAG,SAAiD,GAAG,QAAgD,GAAG,YAAoD;4BAIjQ,SAA2C,GAAG,aAA+C,GAAG,UAA4C,GAAG,WAA8C,GAAG,aAAgD"}

package/types/pagelifecycle/util.d.ts

@@ -0,0 +1,8 @@
+export function addCallback(state: import("./typedef.js").DocumentState | import("./typedef.js").PageLifecycleState, callback: () => void): void;
+export function initPageLifecycle(): void;
+export function getPageLifecycleState(): string;
+export function getDocumentState(): import("./typedef.js").DocumentState;
+export function getEventEmitter(): EventEmitter;
+export function isObserverInitialized(): boolean;
+import { EventEmitter } from 'eventemitter3';
+//# sourceMappingURL=util.d.ts.map

package/types/pagelifecycle/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/pagelifecycle/util.js"],"names":[],"mappings":"AAsCO,mCAHI,OAAO,cAAc,EAAE,aAAa,GAAG,OAAO,cAAc,EAAE,kBAAkB,YAChF,MAAM,IAAI,QAMpB;AAgEM,0CAsBN;AAMM,yCAFM,MAAM,CAIlB;AAMM,oCAFM,OAAO,cAAc,EAAE,aAAa,CAIhD;AAMM,mCAFM,YAAY,CAOxB;AAMM,yCAFM,OAAO,CAInB;6BA9J4B,eAAe"}