Merge pull request #11 from zendive/next

v1.0.7

Author: zendive

Makefile

@@ -10,21 +10,19 @@ install:
 
 dev:
 	rm -rf ./public/build
-	NODE_OPTIONS="--import=tsx" \
-		pnpm exec webpack --progress --watch --mode=development
-
-lint:
-	pnpm exec prettier . --write
-	pnpm exec svelte-check
+	NODE_ENV=development \
+		deno run --watch --allow-env --allow-read --allow-run deno-bundle.ts
 
 test:
+	pnpm exec prettier . --write
 	pnpm exec jest --config jest/jest.config.js
+	pnpm exec svelte-check
 
-prod: lint test
+prod: test
 	rm -rf ./public/build $(ZIP_CHROME_FILE)
-	NODE_OPTIONS="--import=tsx" \
-		time pnpm exec webpack --mode=production
+	NODE_ENV=production \
+		time deno run --allow-env --allow-read --allow-run deno-bundle.ts
 	zip -r $(ZIP_CHROME_FILE) ./public ./manifest.json > /dev/null
 
-.PHONY: clean install dev lint prod test
+.PHONY: clean install dev prod test
 .DEFAULT_GOAL := dev

README.md

@@ -2,33 +2,55 @@
 
 - Available in Chrome Web Store as [API Monitor](https://chromewebstore.google.com/detail/api-monitor/bghmfoakiidiedpheejcjhciekobjcjp)
 
-Whether you're developing a Single Page Application (SPA) and want to assess implementation correctness or are curious about how something works, this tool adds additional functionality to the Chrome browser DevTools to reveal timeouts, intervals, idle callbacks, animation frames and `eval` usages while mapping their invocation call stacks to a source code location. If the page has mounted `video` or `audio` media element's, their events and property state changes can be observed as they happen ([documentation](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement), [example](https://www.w3.org/2010/05/video/mediaevents.html)).
+If you're web developer and want to assess implementation correctness - this tool adds additional panel to the browser’s DevTool that enables to see scheduled timeouts and active intervals, as well as to review and navigate to initiators of: eval, setTimeout, setInterval, requestAnimationFrame, requestIdleCallback and their terminator functions.
 
-### Motivation
+#### Allows:
 
-To expedite issues discovery, here are some examples from experience:
+- to measure callback execution self-time.
+- to see `requestAnimationFrame` callback request frame rate.
+- visit every function in the call stack (if available), bypass or pause while debugging.
+- detect eval ­function usage, see its argument and return value, same for setTimeout and setInterval when called with a string instead of a function.
+- for every mounted video or audio media element's to see it’s state and properties.
 
-- A ~10ms delay interval constantly consuming approximately 10% of CPU from a third-party library, solely to check if the page was resized.
-- A bundled dependency library that utilizes the eval function, thereby preventing the removal of `unsafe-eval` from the Content Security Policy (CSP) header. It can be arguably intentional, but also may reveal a configuration issue when the package was bundled with webpack config's [devtool: 'eval'](https://webpack.js.org/configuration/devtool/) in production mode.
-- A substantial number of hidden video elements in the DOM that were consuming resources, unexpectedly limited to 100 medias per domain.
-- An unattended interval that was unintentionally left running and contributed to a slowly growing memory.
+#### Helps to spot:
 
-To explore the internals of a complex systems.
+- incorrect timeout delay.
+- bad handler for terminator function.
+- terminating non existing or elapsed timeout.
+
+#### Motivation:
+
+- To expedite issues discovery.
+
+#### Wrapped native functions:
+
+- eval (by default off)
+- setTimeout
+- clearTimeout
+- setInterval
+- clearInterval
+- requestAnimationFrame
+- cancelAnimationFrame
+- requestIdleCallback
+- cancelIdleCallback
+
+##### Note:
+
+- while measuring performance of your code – consider disabling this extension as it may affect the results.
 
 <details>
   <summary> <strong>Example</strong> </summary>
 
-![screenshot](./doc/screenshot-01.png)
 ![screenshot](./doc/screenshot-02.png)
-![screenshot](./doc/screenshot-03.png)
 ![screenshot](./doc/screenshot-04.png)
 
 </details>
 
 ### Build requirements
 
 - OS: Linux
-- Node: 20.16.0 (LTS)
+- Node: 22.12.0 (LTS)
+- Deno: 2.1.7
 
 ### Build instructions
 

deno-bundle.ts

@@ -0,0 +1,47 @@
+import { build, context, type BuildOptions } from 'esbuild';
+import esbuildSvelte from 'esbuild-svelte';
+import { sveltePreprocess } from 'svelte-preprocess';
+import manifest from './manifest.json' with { type: 'json' };
+
+const isProd = process.env.NODE_ENV === 'production';
+console.log('🚧', process.env.NODE_ENV);
+
+const buildOptions: BuildOptions = {
+  plugins: [
+    esbuildSvelte({
+      preprocess: sveltePreprocess(),
+      compilerOptions: { dev: !isProd },
+    }),
+  ],
+  entryPoints: [
+    './src/api-monitor-devtools.ts',
+    './src/api-monitor-cs-main.ts',
+    './src/api-monitor-cs-isolated.ts',
+    './src/api-monitor-devtools-panel.ts',
+  ],
+  outdir: './public/build/',
+  define: {
+    __development__: `${!isProd}`,
+    __app_name__: `"browser-api-monitor@${manifest.version}"`,
+    __app_version__: `"${manifest.version}"`,
+    __home_page__: `"${manifest.homepage_url}"`,
+  },
+  bundle: true,
+  platform: 'browser',
+  format: 'iife',
+  target: 'esnext',
+  conditions: [`${process.env.NODE_ENV}`],
+  minify: isProd,
+  sourcemap: false,
+  treeShaking: true,
+  logLevel: 'debug',
+};
+
+if (isProd) {
+  build(buildOptions).catch((error) => {
+    console.error(error);
+  });
+} else {
+  const ctx = await context(buildOptions);
+  await ctx.watch();
+}

doc/screenshot-01.png

@@ -16,8 +16,4 @@ export default {
   },
   rootDir: '..', // . - /
   roots: ['jest/tests'], // . - /jest
-  moduleNameMapper: {
-    // duplicates tsconfig.json/compilerOptions/path & webpack.config.ts/resolve/alias
-    '@/(.*)': '<rootDir>/src/$1',
-  },
 };

doc/screenshot-03.png

@@ -0,0 +1,75 @@
+import { describe, expect, test, beforeEach, afterEach } from '@jest/globals';
+import { AnimationWrapper } from '../../src/wrapper/AnimationWrapper.ts';
+import { TraceUtil } from '../../src/wrapper/TraceUtil.ts';
+import { TAG_EXCEPTION } from '../../src/api/clone.ts';
+import { TextEncoder } from 'node:util';
+
+global.TextEncoder = TextEncoder;
+
+describe('AnimationWrapper', () => {
+  const traceUtil = new TraceUtil();
+  let apiAnimation: AnimationWrapper;
+
+  beforeEach(() => {
+    apiAnimation = new AnimationWrapper(traceUtil);
+    apiAnimation.wrapRequestAnimationFrame();
+    apiAnimation.wrapCancelAnimationFrame();
+  });
+
+  afterEach(() => {
+    apiAnimation.unwrapRequestAnimationFrame();
+    apiAnimation.unwrapCancelAnimationFrame();
+  });
+
+  test('rafHistory - recorded', async () => {
+    let typeOfArgument = '';
+    const handler = await new Promise((resolve) => {
+      const handler = requestAnimationFrame((time) => {
+        typeOfArgument = typeof time;
+        resolve(handler);
+      });
+    });
+    const rec = Array.from(apiAnimation.rafHistory.values())[0];
+
+    expect(typeOfArgument).toBe('number');
+    expect(apiAnimation.rafHistory.size).toBe(1);
+    expect(rec.handler).toBe(handler);
+    expect(rec.calls).toBe(1);
+    expect(rec.trace.length).toBeGreaterThan(1);
+    expect(rec.traceId.length).toBeGreaterThan(1);
+    expect(rec.selfTime).not.toBeNull();
+    expect(apiAnimation.callCounter.requestAnimationFrame).toBe(1);
+  });
+
+  test('cafHistory - recorded', async () => {
+    const unchanged = 0,
+      changed = 1;
+    let changeable = unchanged;
+    const handler = requestAnimationFrame(() => {
+      changeable = changed;
+    });
+    cancelAnimationFrame(handler);
+
+    const rafRec = Array.from(apiAnimation.rafHistory.values())[0];
+    const cafRec = Array.from(apiAnimation.cafHistory.values())[0];
+
+    expect(changeable).toBe(unchanged);
+    expect(apiAnimation.rafHistory.size).toBe(1);
+    expect(apiAnimation.cafHistory.size).toBe(1);
+    expect(cafRec.handler).toBe(handler);
+    expect(cafRec.calls).toBe(1);
+    expect(cafRec.trace.length).toBeGreaterThan(1);
+    expect(cafRec.traceId.length).toBeGreaterThan(1);
+    expect(apiAnimation.callCounter.cancelAnimationFrame).toBe(1);
+    expect(rafRec.canceledByTraceIds?.length).toBe(1);
+    expect(rafRec.canceledCounter).toBe(1);
+  });
+
+  test('cafHistory - invalid handler', () => {
+    cancelAnimationFrame(0);
+
+    const rec = Array.from(apiAnimation.cafHistory?.values())[0];
+
+    expect(rec.handler).toBe(TAG_EXCEPTION(0));
+  });
+});

doc/screenshot-04.png

@@ -0,0 +1,89 @@
+import { describe, expect, test, beforeEach, afterEach } from '@jest/globals';
+import { EvalWrapper } from '../../src/wrapper/EvalWrapper.ts';
+import { TimerWrapper } from '../../src/wrapper/TimerWrapper.ts';
+import { TraceUtil } from '../../src/wrapper/TraceUtil.ts';
+import { TAG_UNDEFINED } from '../../src/api/clone.ts';
+import { TextEncoder } from 'node:util';
+import {
+  TAG_EVAL_RETURN_SET_INTERVAL,
+  TAG_EVAL_RETURN_SET_TIMEOUT,
+} from '../../src/api/const.ts';
+
+global.TextEncoder = TextEncoder;
+
+describe('EvalWrapper', () => {
+  const traceUtil = new TraceUtil();
+  let apiEval: EvalWrapper;
+  let apiTimer: TimerWrapper;
+
+  beforeEach(() => {
+    apiEval = new EvalWrapper(traceUtil);
+    apiEval.wrap();
+    apiTimer = new TimerWrapper(traceUtil, apiEval);
+    apiTimer.wrapSetTimeout();
+    apiTimer.wrapSetInterval();
+  });
+
+  afterEach(() => {
+    apiEval.unwrap();
+    apiTimer.unwrapSetTimeout();
+    apiTimer.unwrapSetInterval();
+  });
+
+  test('evalHistory - recorded', () => {
+    const NUMBER_OF_INVOCATIONS = 2;
+    const CODE = '(1+2)';
+    const RESULT = 3;
+
+    for (let i = 0, I = NUMBER_OF_INVOCATIONS; i < I; i++) {
+      window.eval(CODE);
+    }
+    expect(apiEval.evalHistory.size).toBe(1);
+
+    const rec = Array.from(apiEval.evalHistory.values())[0];
+
+    expect(rec.calls).toBe(NUMBER_OF_INVOCATIONS);
+    expect(rec.usesLocalScope).toBe(false);
+    expect(rec.code).toBe(CODE);
+    expect(rec.returnedValue).toBe(RESULT);
+    expect(rec.trace.length).toBeGreaterThan(1);
+    expect(rec.traceId.length).toBeGreaterThan(0);
+    expect(rec.selfTime).not.toBeNull();
+  });
+
+  test('evalHistory - detects local scope usage', () => {
+    const local_variable = 0;
+    window.eval('(local_variable++)');
+
+    const rec = Array.from(apiEval.evalHistory.values())[0];
+
+    expect(rec.calls).toBe(1);
+    expect(local_variable).toBe(0);
+    expect(rec.usesLocalScope).toBe(true);
+    expect(rec.returnedValue).toBe(TAG_UNDEFINED);
+  });
+
+  test('setTimeoutHistory - isEval recorded', () => {
+    const CODE = '(1+2)';
+    setTimeout(CODE);
+    const timerRec = Array.from(apiTimer.setTimeoutHistory.values())[0];
+    const evalRec = Array.from(apiEval.evalHistory.values())[0];
+
+    expect(timerRec.isEval).toBe(true);
+    expect(evalRec.code).toBe(CODE);
+    expect(evalRec.returnedValue).toBe(TAG_EVAL_RETURN_SET_TIMEOUT);
+  });
+
+  test('setIntervalHistory - isEval recorded', () => {
+    const CODE = '(1+2)';
+    const handler = setInterval(CODE, 123);
+    const timerRec = Array.from(apiTimer.setIntervalHistory.values())[0];
+    const evalRec = Array.from(apiEval.evalHistory.values())[0];
+
+    expect(timerRec.isEval).toBe(true);
+    expect(evalRec.code).toBe(CODE);
+    expect(evalRec.returnedValue).toBe(TAG_EVAL_RETURN_SET_INTERVAL);
+
+    clearInterval(handler);
+  });
+});