refactor: put isContext methods on axe.utils

axe.d.ts

@@ -70,16 +70,19 @@ declare namespace axe {
     | LabelledShadowDomSelector
     | LabelledFramesSelector;
   type SelectorList = Array<Selector | FramesSelector> | NodeList;
+  type ContextProp = Selector | SelectorList;
   type ContextObject =
     | {
-        include: Selector | SelectorList;
-        exclude?: Selector | SelectorList;
+        include: ContextProp;
+        exclude?: ContextProp;
       }
     | {
-        exclude: Selector | SelectorList;
-        include?: Selector | SelectorList;
+        exclude: ContextProp;
+        include?: ContextProp;
       };
-  type ElementContext = Selector | SelectorList | ContextObject;
+  type ContextSpec = ContextProp | ContextObject;
+  /** Synonym to ContextSpec */
+  type ElementContext = ContextSpec;
 
   type SerialSelector =
     | BaseSelector
@@ -406,6 +409,16 @@ declare namespace axe {
     shadowSelect: (selector: CrossTreeSelector) => Element | null;
     shadowSelectAll: (selector: CrossTreeSelector) => Element[];
     getStandards(): Required<Standards>;
+    isContextSpec: (context: unknown) => context is ContextSpec;
+    isContextObject: (context: unknown) => context is ContextObject;
+    isContextProp: (context: unknown) => context is ContextProp;
+    isLabelledFramesSelector: (
+      selector: unknown
+    ) => selector is LabelledFramesSelector;
+    isLabelledShadowDomSelector: (
+      selector: unknown
+    ) => selector is LabelledShadowDomSelector;
+
     DqElement: new (
       elm: Element,
       options?: { absolutePaths?: boolean }

lib/core/base/context/normalize-context.js

@@ -1,4 +1,12 @@
-import { assert as utilsAssert } from '../../utils';
+import {
+  assert as utilsAssert,
+  objectHasOwn,
+  isArrayLike,
+  isContextObject,
+  isContextProp,
+  isLabelledFramesSelector,
+  isLabelledShadowDomSelector
+} from '../../utils';
 
 /**
  * Normalize the input of "context" so that many different methods of input are accepted
@@ -29,16 +37,6 @@ export function normalizeContext(contextSpec) {
   return { include, exclude };
 }
 
-/**
- * Determine if some value can be parsed as a context
- * @private
- * @param  {Mixed} contextSpec The configuration object passed to `Context`
- * @return {boolea}
- */
-export function isContextSpec(contextSpec) {
-  return isContextObject(contextSpec) || isContextProp(contextSpec);
-}
-
 function normalizeContextList(selectorList = []) {
   const normalizedList = [];
   if (!isArrayLike(selectorList)) {
@@ -89,30 +87,6 @@ function normalizeFrameSelectors(frameSelectors) {
   return normalizedSelectors;
 }
 
-function isContextObject(contextSpec) {
-  return ['include', 'exclude'].some(
-    prop => objectHasOwn(contextSpec, prop) && isContextProp(contextSpec[prop])
-  );
-}
-
-function isContextProp(contextList) {
-  return (
-    typeof contextList === 'string' ||
-    contextList instanceof window.Node ||
-    isLabelledFramesSelector(contextList) ||
-    isLabelledShadowDomSelector(contextList) ||
-    isArrayLike(contextList)
-  );
-}
-
-function isLabelledFramesSelector(selector) {
-  return objectHasOwn(selector, 'fromFrames');
-}
-
-function isLabelledShadowDomSelector(selector) {
-  return objectHasOwn(selector, 'fromShadowDom');
-}
-
 function assertLabelledFrameSelector(selector) {
   assert(
     Array.isArray(selector.fromFrames),
@@ -157,28 +131,10 @@ function isShadowSelector(selector) {
   );
 }
 
-function isArrayLike(arr) {
-  return (
-    // Avoid DOM weirdness
-    arr &&
-    typeof arr === 'object' &&
-    typeof arr.length === 'number' &&
-    arr instanceof window.Node === false
-  );
-}
-
 // Wrapper to ensure the correct message
 function assert(bool, str) {
   utilsAssert(
     bool,
     `Invalid context; ${str}\nSee: https://github.com/dequelabs/axe-core/blob/master/doc/context.md`
   );
 }
-
-// Wrapper to prevent throwing for non-objects & null
-function objectHasOwn(obj, prop) {
-  if (!obj || typeof obj !== 'object') {
-    return false;
-  }
-  return Object.prototype.hasOwnProperty.call(obj, prop);
-}

lib/core/public/run/normalize-run-params.js

@@ -1,5 +1,4 @@
-import { clone } from '../../utils';
-import { isContextSpec } from '../../base/context/normalize-context';
+import { clone, isContextSpec } from '../../utils';
 
 /**
  * Normalize the optional params of axe.run()

lib/core/utils/index.js

@@ -43,6 +43,14 @@ export { default as getStyleSheetFactory } from './get-stylesheet-factory';
 export { default as getXpath } from './get-xpath';
 export { default as getAncestry } from './get-ancestry';
 export { default as injectStyle } from './inject-style';
+export { default as isArrayLike } from './is-array-like';
+export {
+  isContextSpec,
+  isContextObject,
+  isContextProp,
+  isLabelledShadowDomSelector,
+  isLabelledFramesSelector
+} from './is-context';
 export { default as isHidden } from './is-hidden';
 export { default as isHtmlElement } from './is-html-element';
 export { default as isNodeInContext } from './is-node-in-context';
@@ -59,6 +67,7 @@ export { default as mergeResults } from './merge-results';
 export { default as nodeSerializer } from './node-serializer';
 export { default as nodeSorter } from './node-sorter';
 export { default as nodeLookup } from './node-lookup';
+export { default as objectHasOwn } from './object-has-own';
 export { default as parseCrossOriginStylesheet } from './parse-crossorigin-stylesheet';
 export { default as parseSameOriginStylesheet } from './parse-sameorigin-stylesheet';
 export { default as parseStylesheet } from './parse-stylesheet';

lib/core/utils/is-array-like.js

@@ -0,0 +1,15 @@
+/**
+ * Checks if a value is array-like.
+ *
+ * @param {any} arr - The value to check.
+ * @returns {boolean} - Returns true if the value is array-like, false otherwise.
+ */
+export default function isArrayLike(arr) {
+  return (
+    !!arr &&
+    typeof arr === 'object' &&
+    typeof arr.length === 'number' &&
+    // Avoid DOM weirdness
+    arr instanceof window.Node === false
+  );
+}

lib/core/utils/is-context.js

@@ -0,0 +1,53 @@
+import objectHasOwn from './object-has-own';
+import isArrayLike from './is-array-like';
+
+/**
+ * Determine if some value can be parsed as a context
+ * @private
+ * @param  {Mixed} contextSpec The configuration object passed to `Context`
+ * @return {boolea}
+ */
+export function isContextSpec(contextSpec) {
+  return isContextObject(contextSpec) || isContextProp(contextSpec);
+}
+
+/**
+ * Checks if the given context specification is a valid context object.
+ *
+ * @param {Object} contextSpec - The context specification object to check.
+ * @returns {boolean} - Returns true if the context specification is a valid context object, otherwise returns false.
+ */
+export function isContextObject(contextSpec) {
+  return ['include', 'exclude'].some(
+    prop => objectHasOwn(contextSpec, prop) && isContextProp(contextSpec[prop])
+  );
+}
+
+/**
+ * Checks if the given contextList is a valid context property.
+ * @param {string|Node|Array} contextList - The contextList to check.
+ * @returns {boolean} - Returns true if the contextList is a valid context property, otherwise false.
+ */
+export function isContextProp(contextList) {
+  return (
+    typeof contextList === 'string' ||
+    contextList instanceof window.Node ||
+    isLabelledFramesSelector(contextList) ||
+    isLabelledShadowDomSelector(contextList) ||
+    isArrayLike(contextList)
+  );
+}
+
+export function isLabelledFramesSelector(selector) {
+  // This doesn't guarantee the selector is valid.
+  // Just that this isn't a runOptions object
+  // Normalization will ignore invalid selectors
+  return objectHasOwn(selector, 'fromFrames');
+}
+
+export function isLabelledShadowDomSelector(selector) {
+  // This doesn't guarantee the selector is valid.
+  // Just that this isn't a runOptions object
+  // Normalization will ignore invalid selectors
+  return objectHasOwn(selector, 'fromShadowDom');
+}

lib/core/utils/object-has-own.js

@@ -0,0 +1,7 @@
+// Wrapper to prevent throwing for non-objects & null
+export default function objectHasOwn(obj, prop) {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+  return Object.prototype.hasOwnProperty.call(obj, prop);
+}

test/core/utils/is-array-like.js

@@ -0,0 +1,30 @@
+describe('axe.utils.isArrayLike', () => {
+  const isArrayLike = axe.utils.isArrayLike;
+
+  it('is true for an array', () => {
+    assert.isTrue(isArrayLike([]));
+  });
+
+  it('is true for an array-like object', () => {
+    assert.isTrue(isArrayLike({ length: 1 }));
+  });
+
+  it('is false for strings (which also have .length)', () => {
+    assert.isFalse(isArrayLike('string'));
+  });
+
+  it('is false for a Node with .length', () => {
+    const div = document.createElement('div');
+    div.length = 123;
+    assert.isFalse(isArrayLike(div));
+  });
+
+  it('is false for non-array-like objects', () => {
+    assert.isFalse(isArrayLike({}));
+    assert.isFalse(isArrayLike(null));
+    assert.isFalse(isArrayLike(undefined));
+    assert.isFalse(isArrayLike(1));
+    assert.isFalse(isArrayLike(true));
+    assert.isFalse(isArrayLike(false));
+  });
+});