@thumbmarkjs/thumbmarkjs 1.8.1 → 1.9.1

package/src/functions/filterComponents.test.ts

@@ -161,6 +161,17 @@ describe('getExcludeList', () => {
         // Should not throw
         expect(() => getExcludeList({ ...defaultOptions }, obj)).not.toThrow();
     });
+
+    test('non-array string exclude does not throw and is ignored', () => {
+        const result = getExcludeList({ ...defaultOptions, exclude: 'one' as any, stabilize: [] });
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).not.toContain('one');
+    });
+
+    test('non-array object exclude does not throw and is ignored', () => {
+        const result = getExcludeList({ ...defaultOptions, exclude: {} as any, stabilize: [] });
+        expect(Array.isArray(result)).toBe(true);
+    });
 });
 
 // ── filterThumbmarkData ─────────────────────────────────────────
@@ -235,4 +246,28 @@ describe('filterThumbmarkData', () => {
         expect((result.audio as componentInterface).other).toBe('jkl');
         expect((result.audio as componentInterface).sampleHash).toBeUndefined();
     });
+
+    test('non-array string include does not throw and does not rescue excluded keys', () => {
+        const result = filterThumbmarkData(testData, {
+            ...defaultOptions,
+            exclude: ['one'],
+            include: 'one' as any,
+            stabilize: [],
+        });
+        // Bad include is treated as empty, so 'one' stays excluded
+        expect(result.one).toBeUndefined();
+        expect(result.two).toBe(2);
+    });
+
+    test('null include does not throw and behaves as empty include', () => {
+        const result = filterThumbmarkData(testData, {
+            ...defaultOptions,
+            exclude: ['two'],
+            include: null as any,
+            stabilize: [],
+        });
+        // null include treated as empty, so 'two' stays excluded
+        expect(result.two).toBeUndefined();
+        expect(result.one).toBe('1');
+    });
 });

package/src/functions/filterComponents.ts

@@ -27,7 +27,7 @@ export function getExcludeList(options?: optionsInterface, obj?: componentInterf
 
     const name = browser.name.toLowerCase();
     const majorVer = parseInt(browser.version.split('.')[0] || '0', 10);
-    const excludeList = [...(options?.exclude || [])];
+    const excludeList = Array.isArray(options?.exclude) ? [...options.exclude] : [];
     const stabilizationOptions = [...new Set([...(options?.stabilize || []), 'always'])];
 
     for (const option of stabilizationOptions) {
@@ -52,7 +52,7 @@ export function filterThumbmarkData(
     options?: optionsInterface,
 ): componentInterface {
     const excludeList = getExcludeList(options, obj);
-    const includeList = options?.include || [];
+    const includeList = Array.isArray(options?.include) ? options.include : [];
 
     /**
      * Inner recursive function to perform the actual filtering.
@@ -84,6 +84,5 @@ export function filterThumbmarkData(
         return result;
     }
 
-    // Start the filtering process
     return performFilter(obj);
 }

package/src/functions/index.ts

@@ -91,16 +91,18 @@ export async function getThumbmark(
       ...customComponents,
       ...instanceCustomComponents,
     } as Record<string, componentFunctionInterface>;
-    const { elapsed, resolvedComponents: clientComponentsResult, errors: componentErrors } = await resolveClientComponents(allComponents, _options);
+    const { elapsed, resolvedComponents: clientComponentsResult, errors: componentErrors, pipelineTimings: mainPipelineTimings } = await resolveClientComponents(allComponents, _options);
     allErrors.push(...componentErrors);
 
     // Resolve experimental components only when logging
     let experimentalComponents = {};
     let experimentalElapsed = {};
+    let expPipelineTimings: Record<string, number> = {};
     if (shouldLog || _options.experimental) {
-      const { elapsed: expElapsed, resolvedComponents, errors: expErrors } = await resolveClientComponents(tm_experimental_component_promises, _options);
+      const { elapsed: expElapsed, resolvedComponents, errors: expErrors, pipelineTimings: expTimings } = await resolveClientComponents(tm_experimental_component_promises, _options);
       experimentalComponents = resolvedComponents;
       experimentalElapsed = expElapsed;
+      expPipelineTimings = expTimings;
       allErrors.push(...expErrors);
     }
 
@@ -132,15 +134,29 @@ export async function getThumbmark(
       allErrors.push({ type: 'api_timeout', message: 'API request timed out' });
     }
 
-    // Only add 'elapsed' if performance is true
-    const allElapsed = { ...elapsed, ...experimentalElapsed };
-    const maybeElapsed = _options.performance ? { elapsed: allElapsed } : {};
+    const filterStart = performance.now();
     const apiComponents = filterThumbmarkData(apiResult?.components || {}, _options);
+    const filterMs = performance.now() - filterStart;
+
     const components = { ...clientComponentsResult, ...apiComponents };
     const info: infoInterface = apiResult?.info || { uniqueness: { score: 'api only' } };
 
     // Use API thumbmark if available to ensure API/client sync, otherwise calculate locally
-    const thumbmark = apiResult?.thumbmark ?? hash(stableStringify(components));
+    let thumbmark: string;
+    let stringifyMs = 0;
+    let hashMs = 0;
+    if (apiResult?.thumbmark) {
+      thumbmark = apiResult.thumbmark;
+    } else {
+      const stringifyStart = performance.now();
+      const stringified = stableStringify(components);
+      stringifyMs = performance.now() - stringifyStart;
+
+      const hashStart = performance.now();
+      thumbmark = hash(stringified);
+      hashMs = performance.now() - hashStart;
+    }
+
     const version = getVersion();
 
     // Only log to server when not in debug mode
@@ -148,6 +164,26 @@ export async function getThumbmark(
       logThumbmarkData(thumbmark, components, _options, experimentalComponents, allErrors).catch(() => { /* do nothing */ });
     }
 
+    // Accumulate _pipeline timings from both the main and (if run) experimental component phases.
+    // Filter time includes: main component filter + optional experimental filter + apiComponents filter.
+    const expFilterMs = expPipelineTimings['_pipeline.filter'] ?? 0;
+    const _pipelineTimings: Record<string, number> = {
+      '_pipeline.dispatch': mainPipelineTimings['_pipeline.dispatch'],
+      '_pipeline.resolve': mainPipelineTimings['_pipeline.resolve'],
+      '_pipeline.filter': mainPipelineTimings['_pipeline.filter'] + expFilterMs + filterMs,
+      '_pipeline.stringify': stringifyMs,
+      '_pipeline.hash': hashMs,
+      '_pipeline.assembly': 0, // placeholder, updated below after result construction
+    };
+
+    // Only add 'elapsed' if performance is true
+    // allElapsed holds a live reference to _pipelineTimings entries via spread — we update assembly after.
+    // mainPipelineTimings contains both _pipeline.* keys (overridden by _pipelineTimings below) and
+    // _dispatch.<name> keys (per-component sync prelude timings) that flow through unchanged.
+    const allElapsed: Record<string, number> = { ...elapsed, ...experimentalElapsed, ...mainPipelineTimings, ..._pipelineTimings };
+    const maybeElapsed = _options.performance ? { elapsed: allElapsed } : {};
+
+    const assemblyStart = performance.now();
     const result: ThumbmarkResponse = {
       ...(apiResult?.visitorId && { visitorId: apiResult.visitorId }),
       thumbmark,
@@ -160,6 +196,8 @@ export async function getThumbmark(
       ...(apiResult?.requestId && { requestId: apiResult.requestId }),
       ...(apiResult?.metadata && { metadata: apiResult.metadata }),
     };
+    // Update assembly timing in allElapsed directly (allElapsed is the same object referenced by result.elapsed).
+    allElapsed['_pipeline.assembly'] = performance.now() - assemblyStart;
 
     return result;
   } catch (e) {
@@ -180,12 +218,12 @@ export async function getThumbmark(
  *
  * @param comps - Map of component functions
  * @param options - Options for filtering and timing
- * @returns Object with elapsed times and filtered resolved components
+ * @returns Object with elapsed times, filtered resolved components, errors, and pipeline phase timings
  */
 export async function resolveClientComponents(
   comps: { [key: string]: (options?: optionsInterface) => Promise<componentInterface | null> },
   options?: optionsInterface
-): Promise<{ elapsed: Record<string, number>, resolvedComponents: componentInterface, errors: ThumbmarkError[] }> {
+): Promise<{ elapsed: Record<string, number>, resolvedComponents: componentInterface, errors: ThumbmarkError[], pipelineTimings: Record<string, number> }> {
   const opts = { ...defaultOptions, ...options };
   const topLevelExcludes = getExcludeList(opts).filter(e => !e.includes('.'));
   const filtered = Object.entries(comps)
@@ -197,8 +235,20 @@ export async function resolveClientComponents(
         : opts?.include?.length === 0 || opts?.include?.includes(key)
     );
   const keys = filtered.map(([key]) => key);
-  const promises = filtered.map(([_, fn]) => fn(options));
+
+  const perComponentDispatch: Record<string, number> = {};
+  const dispatchStart = performance.now();
+  const promises = filtered.map(([key, fn]) => {
+    const t0 = performance.now();
+    const p = fn(options);
+    perComponentDispatch[`_dispatch.${key}`] = performance.now() - t0;
+    return p;
+  });
+  const dispatchMs = performance.now() - dispatchStart;
+
+  const resolveStart = performance.now();
   const resolvedValues = await raceAllPerformance(promises, opts?.timeout || 5000, timeoutInstance);
+  const resolveMs = performance.now() - resolveStart;
 
   const elapsed: Record<string, number> = {};
   const resolvedComponentsRaw: Record<string, componentInterface> = {};
@@ -219,8 +269,18 @@ export async function resolveClientComponents(
     }
   });
 
+  const filterStart = performance.now();
   const resolvedComponents = filterThumbmarkData(resolvedComponentsRaw, opts);
-  return { elapsed, resolvedComponents, errors };
+  const filterMs = performance.now() - filterStart;
+
+  const pipelineTimings: Record<string, number> = {
+    '_pipeline.dispatch': dispatchMs,
+    '_pipeline.resolve': resolveMs,
+    '_pipeline.filter': filterMs,
+    ...perComponentDispatch,
+  };
+
+  return { elapsed, resolvedComponents, errors, pipelineTimings };
 }
 
 export { globalIncludeComponent as includeComponent };

package/src/utils/commonPixels.ts

@@ -1,4 +1,29 @@
 export function getCommonPixels(images: ImageData[], width: number, height: number ): ImageData {
+    // Short-circuit: single image — every byte is trivially its own mode.
+    if (images.length === 1) {
+        return images[0];
+    }
+
+    // Fast path: exactly 3 images — inline 3-way comparison that mirrors
+    // getMostFrequent's tie-breaking exactly for all 5 value-combination cases:
+    //   all-equal → that value
+    //   a===b     → a (freq 2)
+    //   a===c     → a (freq 2)
+    //   b===c     → b (freq 2)
+    //   all-diff  → a (mostFrequent stays arr[0], no key beats freq 1)
+    if (images.length === 3) {
+        const a = images[0].data;
+        const b = images[1].data;
+        const c = images[2].data;
+        const out = new Uint8ClampedArray(a.length);
+        for (let i = 0; i < a.length; i++) {
+            const x = a[i], y = b[i], z = c[i];
+            out[i] = (x === y) ? x : (x === z) ? x : (y === z) ? y : x;
+        }
+        return new ImageData(out, width, height);
+    }
+
+    // Generic fallback for any other length (no current caller uses this path).
     let finalData: number[] = [];
     for (let i = 0; i < images[0].data.length; i++) {
         let indice: number[] = [];

package/src/utils/raceAll.ts

@@ -21,21 +21,31 @@ export function raceAllPerformance<T>(
   return Promise.all(
     promises.map((p) => {
       const startTime = performance.now();
-      return Promise.race([
-        p.then((value) => ({
-          value,
-          elapsed: performance.now() - startTime,
-        })).catch((err: unknown) => ({
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+      const resultPromise = p.then((value) => {
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+        return { value, elapsed: performance.now() - startTime };
+      }).catch((err: unknown) => {
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+        return {
           value: timeoutVal,
           elapsed: performance.now() - startTime,
           error: err instanceof Error ? err.message : String(err),
-        })),
-        delay(timeoutTime, timeoutVal).then((value) => ({
-          value,
-          elapsed: performance.now() - startTime,
-          error: 'timeout' as string,
-        })),
-      ]);
+        };
+      });
+
+      const timeoutPromise = new Promise<RaceResult<T>>((resolve) => {
+        timeoutId = setTimeout(() => {
+          resolve({
+            value: timeoutVal,
+            elapsed: performance.now() - startTime,
+            error: 'timeout',
+          });
+        }, timeoutTime);
+      });
+
+      return Promise.race([resultPromise, timeoutPromise]);
     })
   );
 }

package/src/utils/stableStringify.ts

@@ -22,7 +22,9 @@
  */
 export function stableStringify(data: any): string {
 
-    const seen: any[] = [];
+    // Use a Set for O(1) cycle detection instead of O(N) array indexOf.
+    // The serialisation logic (key sorting, value recursion, output format) is unchanged.
+    const seen = new Set<any>();
 
     return (function stringify(node: any): string | undefined {
         if (node && node.toJSON && typeof node.toJSON === 'function') {
@@ -47,11 +49,11 @@ export function stableStringify(data: any): string {
 
         if (node === null) return 'null';
 
-        if (seen.indexOf(node) !== -1) {
+        if (seen.has(node)) {
             throw new TypeError('Converting circular structure to JSON');
         }
 
-        const seenIndex = seen.push(node) - 1;
+        seen.add(node);
         const keys = Object.keys(node).sort();
         out = '';
 
@@ -64,7 +66,7 @@ export function stableStringify(data: any): string {
             out += JSON.stringify(key) + ':' + value;
         }
 
-        seen.splice(seenIndex, 1);
+        seen.delete(node);
         return '{' + out + '}';
     })(data) || '';
 }