feat(utils): isArrayIndex

Signed-off-by: Lexus Drumgold <[email protected]>

.cspell.json

@@ -31,6 +31,7 @@
     "yarn.lock"
   ],
   "ignoreRegExpList": [
+    "/0x*/",
     "/@flex-development\\/.*/",
     "/from\\s+(['\"]).*\\1/",
     "import\\(.*\\)"

src/utils/__tests__/is-array-index.spec-d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Type Tests - isArrayIndex
+ * @module tutils/utils/tests/unit-d/isArrayIndex
+ */
+
+import type { Numeric } from '#src/types'
+import type testSubject from '../is-array-index'
+
+describe('unit-d:utils/isArrayIndex', () => {
+  it('should guard Numeric', () => {
+    expectTypeOf<typeof testSubject>().guards.toEqualTypeOf<Numeric>()
+  })
+})

src/utils/__tests__/is-array-index.spec.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Unit Tests - isArrayIndex
+ * @module tutils/utils/tests/unit/isArrayIndex
+ */
+
+import testSubject from '../is-array-index'
+
+describe('unit:utils/isArrayIndex', () => {
+  it('should return false if value is not an array index', () => {
+    expect(testSubject('.')).to.be.false
+  })
+
+  it('should return true if value is an array index', () => {
+    expect(testSubject(`${faker.number.int({ max: 13, min: 0 })}`)).to.be.true
+  })
+})

src/utils/index.ts

@@ -29,6 +29,7 @@ export { default as intersects } from './intersects'
 export { default as isAppEnv } from './is-app-env'
 export { default as isArray } from './is-array'
 export { default as isArrayBuffer } from './is-array-buffer'
+export { default as isArrayIndex } from './is-array-index'
 export { default as isBigInt } from './is-big-int'
 export { default as isBoolean } from './is-boolean'
 export { default as isBooleanish } from './is-booleanish'

src/utils/is-array-index.ts

@@ -0,0 +1,31 @@
+/**
+ * @file Utilities - isArrayIndex
+ * @module tutils/utils/isArrayIndex
+ */
+
+import type { Numeric } from '#src/types'
+import isNumeric from './is-numeric'
+
+/**
+ * Checks if a value is an array index by ECMAScript Language Specification
+ * standards.
+ *
+ * @see https://tc39.es/ecma262/#integer-index
+ *
+ * @todo examples
+ *
+ * @param {unknown} value - Value to check
+ * @return {value is Numeric} `true` if `value` is array index
+ */
+const isArrayIndex = (value: unknown): value is Numeric => {
+  /**
+   * Numeric value as a number.
+   *
+   * @const {number} num
+   */
+  const num: number = isNumeric(value) ? +value : Number.NaN
+
+  return `${num}` !== value ? false : num >= 0 && num < 0xffff_ffff
+}
+
+export default isArrayIndex