@xylabs/typeof 5.0.33 → 5.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/typeof",
-  "version": "5.0.33",
+  "version": "5.0.35",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "typeof",
@@ -39,7 +39,10 @@
   "types": "./dist/neutral/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "!**/*.bench.*",
+    "!**/*.spec.*",
+    "!**/*.test.*"
   ],
   "devDependencies": {
     "@xylabs/ts-scripts-yarn3": "~7.2.8",

package/dist/neutral/spec/is.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=is.spec.d.ts.map

package/dist/neutral/spec/is.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is.spec.d.ts","sourceRoot":"","sources":["../../../src/spec/is.spec.ts"],"names":[],"mappings":""}

package/src/spec/is.spec.ts

@@ -1,608 +0,0 @@
-/* eslint-disable max-lines */
-/* eslint-disable max-statements */
-import {
-  describe, expect, expectTypeOf,
-  it,
-} from 'vitest'
-
-import {
-  isArray,
-  isArrayBufferView,
-  isBigInt,
-  isBlob,
-  isBoolean,
-  isDataView,
-  isDate,
-  isDateString,
-  isDefined,
-  isDefinedNotNull,
-  isEmpty,
-  isEmptyArray,
-  isEmptyObject,
-  isEmptyString,
-  isError,
-  isFalsy,
-  isFile,
-  isFunction,
-  isMap,
-  isNull,
-  isNumber,
-  isObject,
-  isPopulatedArray,
-  isPromise,
-  isPromiseLike,
-  isRegExp,
-  isSet,
-  isString,
-  isSymbol,
-  isTruthy,
-  isUndefined,
-  isUndefinedOrNull,
-  isWeakMap,
-  isWeakSet,
-} from '../is.ts'
-
-const Undefined = undefined
-
-describe('is.ts type guards', () => {
-  describe('isUndefined', () => {
-    it('correctly identifies undefined values', () => {
-      expect(isUndefined(Undefined)).toBe(true)
-      expect(isUndefined(void 0)).toBe(true)
-
-      expect(isUndefined(null)).toBe(false)
-      expect(isUndefined(0)).toBe(false)
-      expect(isUndefined('')).toBe(false)
-      expect(isUndefined(false)).toBe(false)
-      expect(isUndefined({})).toBe(false)
-    })
-  })
-
-  describe('isDefined', () => {
-    it('correctly identifies defined values', () => {
-      expect(isDefined(null)).toBe(true)
-      expect(isDefined(0)).toBe(true)
-      expect(isDefined('')).toBe(true)
-      expect(isDefined(false)).toBe(true)
-      expect(isDefined({})).toBe(true)
-
-      expect(isDefined(Undefined)).toBe(false)
-      expect(isDefined(void 0)).toBe(false)
-    })
-  })
-
-  describe('isNull', () => {
-    it('correctly identifies null values', () => {
-      expect(isNull(null)).toBe(true)
-
-      expect(isNull(Undefined)).toBe(false)
-      expect(isNull(0)).toBe(false)
-      expect(isNull('')).toBe(false)
-      expect(isNull(false)).toBe(false)
-      expect(isNull({})).toBe(false)
-    })
-  })
-
-  describe('isDefinedNotNull', () => {
-    it('correctly identifies values that are neither undefined nor null', () => {
-      expect(isDefinedNotNull(0)).toBe(true)
-      expect(isDefinedNotNull('')).toBe(true)
-      expect(isDefinedNotNull(false)).toBe(true)
-      expect(isDefinedNotNull({})).toBe(true)
-
-      expect(isDefinedNotNull(Undefined)).toBe(false)
-      expect(isDefinedNotNull(null)).toBe(false)
-    })
-  })
-
-  describe('isUndefinedOrNull', () => {
-    it('correctly identifies undefined or null values', () => {
-      expect(isUndefinedOrNull(Undefined)).toBe(true)
-      expect(isUndefinedOrNull(null)).toBe(true)
-
-      expect(isUndefinedOrNull(0)).toBe(false)
-      expect(isUndefinedOrNull('')).toBe(false)
-      expect(isUndefinedOrNull(false)).toBe(false)
-      expect(isUndefinedOrNull({})).toBe(false)
-    })
-  })
-
-  describe('isBigInt', () => {
-    it('correctly identifies BigInt values', () => {
-      expect(isBigInt(123n)).toBe(true)
-      expect(isBigInt(123n)).toBe(true)
-
-      expect(isBigInt(123)).toBe(false)
-      expect(isBigInt('123')).toBe(false)
-      expect(isBigInt(null)).toBe(false)
-      expect(isBigInt(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isString', () => {
-    it('correctly identifies string values', () => {
-      expect(isString('')).toBe(true)
-      expect(isString('hello')).toBe(true)
-      expect(isString(String('test'))).toBe(true)
-
-      expect(isString(123)).toBe(false)
-      expect(isString(null)).toBe(false)
-      expect(isString(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isNumber', () => {
-    it('correctly identifies number values', () => {
-      expect(isNumber(0)).toBe(true)
-      expect(isNumber(123)).toBe(true)
-      expect(isNumber(-456)).toBe(true)
-      expect(isNumber(Number.NaN)).toBe(true)
-      expect(isNumber(Infinity)).toBe(true)
-
-      expect(isNumber('123')).toBe(false)
-      expect(isNumber(null)).toBe(false)
-      expect(isNumber(Undefined)).toBe(false)
-      expect(isNumber(123n)).toBe(false)
-    })
-  })
-
-  describe('isObject', () => {
-    it('correctly identifies object values', () => {
-      expect(isObject({})).toBe(true)
-      expect(isObject({ key: 'value' })).toBe(true)
-      expect(isObject(new Date())).toBe(true)
-      expect(isObject(new Map())).toBe(true)
-
-      expect(isObject([])).toBe(false) // Arrays are not objects for this function
-      expect(isObject(null)).toBe(false)
-      expect(isObject(Undefined)).toBe(false)
-      expect(isObject('object')).toBe(false)
-      expect(isObject(123)).toBe(false)
-    })
-  })
-
-  describe('isArray', () => {
-    describe('narrowing', () => {
-      const takesTuple = (_x: [number, string]): void => {}
-      const takesReadonlyTuple = (_x: readonly [1, 2]): void => {}
-      const takesNumArray = (_x: number[]): void => {}
-      const takesReadonlyNumberArray = (_x: readonly number[]): void => {}
-
-      // NOTE: We're randomly generating a value for testing purposes
-      // using Math.random() so that TypeScript can't optimize away the
-      // narrowing prematurely by knowing the type the constant is initialized to.
-      it('narrows a union with a specific tuple', () => {
-        const v: string | [number, string] = Math.random() > 0.5 ? 'x' : [1, 'y']
-
-        if (isArray(v)) {
-          // should preserve the exact tuple type, not degrade to unknown[] or []
-          expectTypeOf(v).toEqualTypeOf<[number, string]>()
-          takesTuple(v)
-
-          // access index should be allowed (would fail if v were mistakenly narrowed to [])
-          const first: number = v[0]
-          expectTypeOf(first).toEqualTypeOf<number>()
-          const second: string = v[1]
-          expectTypeOf(second).toEqualTypeOf<string>()
-        } else {
-          expectTypeOf(v).toEqualTypeOf<string>()
-          // @ts-expect-error not an array in this branch
-          takesTuple(v)
-        }
-      })
-
-      it('narrows a union with a readonly tuple', () => {
-        const v: number | (readonly [1, 2]) = Math.random() > 0.5 ? 42 : [1, 2] as const
-
-        if (isArray(v)) {
-          // preserve readonly tuple-ness
-          expectTypeOf(v).toEqualTypeOf<readonly [1, 2]>()
-          takesReadonlyTuple(v)
-
-          // index access must compile (would fail if narrowed to empty tuple [])
-          const first: 1 = v[0]
-          expectTypeOf(first).toEqualTypeOf<1>()
-          const second: 2 = v[1]
-          expectTypeOf(second).toEqualTypeOf<2>()
-        } else {
-          expectTypeOf(v).toEqualTypeOf<number>()
-          // @ts-expect-error not an array here
-          takesReadonlyTuple(v)
-        }
-      })
-
-      it('narrows to mutable array when member is number[]', () => {
-        const v: { a: 1 } | number[] = Math.random() > 0.5 ? { a: 1 } : [1, 2, 3]
-
-        if (isArray(v)) {
-          expectTypeOf(v).toEqualTypeOf<number[]>()
-          takesNumArray(v)
-
-          // element access should be number (not never)
-          const n: number = v[0]
-          expectTypeOf(n).toEqualTypeOf<number>()
-        } else {
-          expectTypeOf(v).toEqualTypeOf<{ a: 1 }>()
-          // @ts-expect-error not an array here
-          takesNumArray(v)
-        }
-      })
-
-      it('preserves readonly array types', () => {
-        const v: string | readonly number[]
-          = Math.random() > 0.5 ? 'nope' : [1, 2, 3] as const
-
-        if (isArray(v)) {
-          // preserve readonly array
-          expectTypeOf(v).toEqualTypeOf<readonly number[]>()
-          takesReadonlyNumberArray(v)
-
-          // element access should still be number
-          const n: number = v[0]
-          expectTypeOf(n).toEqualTypeOf<number>()
-        } else {
-          expectTypeOf(v).toEqualTypeOf<string>()
-          // @ts-expect-error not an array here
-          takesReadonlyNumberArray(v)
-        }
-      })
-
-      it('does not narrow non-array tuples/objects', () => {
-        const v: { x: 1 } | 'hi' = Math.random() > 0.5 ? { x: 1 } : 'hi'
-
-        if (isArray(v)) {
-          // this branch must be impossible
-          // @ts-expect-error v cannot be an array here
-          expectTypeOf(v).toEqualTypeOf<readonly unknown[]>()
-        } else {
-          // remains original union minus arrays (i.e., unchanged)
-          expectTypeOf(v).toEqualTypeOf<{ x: 1 } | 'hi'>()
-        }
-      })
-    })
-    describe('usage', () => {
-      it('correctly identifies array values', () => {
-        expect(isArray([])).toBe(true)
-        expect(isArray([1, 2, 3])).toBe(true)
-        expect(isArray(Array.from({ length: 5 }))).toBe(true)
-
-        expect(isArray({})).toBe(false)
-        expect(isArray('array')).toBe(false)
-        expect(isArray(null)).toBe(false)
-        expect(isArray(Undefined)).toBe(false)
-      })
-    })
-  })
-
-  describe('isFunction', () => {
-    it('correctly identifies function values', () => {
-      expect(isFunction(() => {})).toBe(true)
-      expect(isFunction(function () {})).toBe(true)
-      expect(isFunction(Date)).toBe(true)
-
-      expect(isFunction({})).toBe(false)
-      expect(isFunction('function')).toBe(false)
-      expect(isFunction(null)).toBe(false)
-      expect(isFunction(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isSymbol', () => {
-    it('correctly identifies symbol values', () => {
-      expect(isSymbol(Symbol())).toBe(true)
-      expect(isSymbol(Symbol('test'))).toBe(true)
-
-      expect(isSymbol('symbol')).toBe(false)
-      expect(isSymbol(null)).toBe(false)
-      expect(isSymbol(Undefined)).toBe(false)
-      expect(isSymbol({})).toBe(false)
-    })
-  })
-
-  describe('isEmptyObject', () => {
-    it('correctly identifies empty object values', () => {
-      expect(isEmptyObject({})).toBe(true)
-      expect(isEmptyObject(Object.create(null))).toBe(true)
-
-      expect(isEmptyObject({ key: 'value' })).toBe(false)
-      expect(isEmptyObject([])).toBe(false)
-      expect(isEmptyObject(null)).toBe(false)
-      expect(isEmptyObject(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isEmptyString', () => {
-    it('correctly identifies empty string values', () => {
-      expect(isEmptyString('')).toBe(true)
-
-      expect(isEmptyString(' ')).toBe(false)
-      expect(isEmptyString('hello')).toBe(false)
-      expect(isEmptyString(null)).toBe(false)
-      expect(isEmptyString(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isEmptyArray', () => {
-    it('correctly identifies empty array values', () => {
-      expect(isEmptyArray([])).toBe(true)
-      expect(isEmptyArray([])).toBe(true)
-
-      expect(isEmptyArray([1, 2, 3])).toBe(false)
-      expect(isEmptyArray({})).toBe(false)
-      expect(isEmptyArray(null)).toBe(false)
-      expect(isEmptyArray(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isPopulatedArray', () => {
-    it('correctly identifies populated array values', () => {
-      expect(isPopulatedArray([1, 2, 3])).toBe(true)
-      expect(isPopulatedArray(['test'])).toBe(true)
-
-      expect(isPopulatedArray([])).toBe(false)
-      expect(isPopulatedArray({})).toBe(false)
-      expect(isPopulatedArray(null)).toBe(false)
-      expect(isPopulatedArray(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isEmpty', () => {
-    it('correctly identifies empty values', () => {
-      expect(isEmpty('')).toBe(true)
-      expect(isEmpty([])).toBe(true)
-      expect(isEmpty({})).toBe(true)
-
-      expect(isEmpty('hello')).toBe(false)
-      expect(isEmpty([1, 2])).toBe(false)
-      expect(isEmpty({ key: 'value' })).toBe(false)
-      expect(isEmpty(0)).toBe(false)
-      expect(isEmpty(null)).toBe(false)
-      expect(isEmpty(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isFalsy', () => {
-    it('correctly identifies falsy values', () => {
-      expect(isFalsy(false)).toBe(true)
-      expect(isFalsy(0)).toBe(true)
-      expect(isFalsy('')).toBe(true)
-      expect(isFalsy(null)).toBe(true)
-      expect(isFalsy(Undefined)).toBe(true)
-      expect(isFalsy(Number.NaN)).toBe(true)
-      expect(isFalsy(0n)).toBe(true)
-
-      expect(isFalsy(true)).toBe(false)
-      expect(isFalsy(1)).toBe(false)
-      expect(isFalsy('hello')).toBe(false)
-      expect(isFalsy({})).toBe(false)
-      expect(isFalsy([])).toBe(false)
-    })
-  })
-
-  describe('isTruthy', () => {
-    it('correctly identifies truthy values', () => {
-      expect(isTruthy(true)).toBe(true)
-      expect(isTruthy(1)).toBe(true)
-      expect(isTruthy('hello')).toBe(true)
-      expect(isTruthy({})).toBe(true)
-      expect(isTruthy([])).toBe(true)
-
-      expect(isTruthy(false)).toBe(false)
-      expect(isTruthy(0)).toBe(false)
-      expect(isTruthy('')).toBe(false)
-      expect(isTruthy(null)).toBe(false)
-      expect(isTruthy(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isBoolean', () => {
-    it('correctly identifies boolean values', () => {
-      expect(isBoolean(true)).toBe(true)
-      expect(isBoolean(false)).toBe(true)
-      expect(isBoolean(Boolean(1))).toBe(true)
-
-      expect(isBoolean(0)).toBe(false)
-      expect(isBoolean(1)).toBe(false)
-      expect(isBoolean('true')).toBe(false)
-      expect(isBoolean(null)).toBe(false)
-      expect(isBoolean(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isDateString', () => {
-    it('correctly identifies date string values', () => {
-      expect(isDateString('2023-01-01')).toBe(true)
-      expect(isDateString('01/01/2023')).toBe(true)
-      expect(isDateString('January 1, 2023')).toBe(true)
-      expect(isDateString('2023-01-01T00:00:00Z')).toBe(true)
-
-      expect(isDateString('not a date')).toBe(false)
-      expect(isDateString('')).toBe(false)
-      expect(isDateString(null)).toBe(false)
-      expect(isDateString(Undefined)).toBe(false)
-      expect(isDateString(new Date())).toBe(false)
-    })
-  })
-
-  describe('isDate', () => {
-    it('correctly identifies Date objects', () => {
-      expect(isDate(new Date())).toBe(true)
-      expect(isDate(new Date(2023, 0, 1))).toBe(true)
-
-      expect(isDate('2023-01-01')).toBe(false)
-      expect(isDate(Date.now())).toBe(false)
-      expect(isDate(null)).toBe(false)
-      expect(isDate(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isRegExp', () => {
-    it('correctly identifies RegExp objects', () => {
-      expect(isRegExp(/test/)).toBe(true)
-      expect(isRegExp(new RegExp('test'))).toBe(true)
-
-      expect(isRegExp('/test/')).toBe(false)
-      expect(isRegExp('test')).toBe(false)
-      expect(isRegExp(null)).toBe(false)
-      expect(isRegExp(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isError', () => {
-    it('correctly identifies Error objects', () => {
-      expect(isError(new Error('Test'))).toBe(true)
-      expect(isError(new TypeError('Test'))).toBe(true)
-      expect(isError(new SyntaxError('Test'))).toBe(true)
-
-      expect(isError('error')).toBe(false)
-      expect(isError({ message: 'Error' })).toBe(false)
-      expect(isError(null)).toBe(false)
-      expect(isError(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isPromise', () => {
-    it('correctly identifies Promise objects', () => {
-      expect(isPromise(Promise.resolve())).toBe(true)
-      expect(isPromise(new Promise(() => {}))).toBe(true)
-
-      // eslint-disable-next-line unicorn/no-thenable
-      expect(isPromise({ then: () => {}, catch: () => {} })).toBe(false) // Not a real Promise instance
-      expect(isPromise({})).toBe(false)
-      expect(isPromise(null)).toBe(false)
-      expect(isPromise(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isPromiseLike', () => {
-    it('correctly identifies Promise-like objects', () => {
-      expect(isPromiseLike(Promise.resolve())).toBe(true)
-      expect(isPromiseLike(new Promise(() => {}))).toBe(true)
-      // eslint-disable-next-line unicorn/no-thenable
-      expect(isPromiseLike({ then: () => {} })).toBe(true) // Thenable
-
-      expect(isPromiseLike({})).toBe(false)
-      // eslint-disable-next-line unicorn/no-thenable
-      expect(isPromiseLike({ then: 5 })).toBe(false) // 'then' must be a function
-      expect(isPromiseLike(null)).toBe(false)
-      expect(isPromiseLike(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isMap', () => {
-    it('correctly identifies Map objects', () => {
-      expect(isMap(new Map())).toBe(true)
-      expect(isMap(new Map([['key', 'value']]))).toBe(true)
-
-      expect(isMap({})).toBe(false)
-      expect(isMap(new Set())).toBe(false)
-      expect(isMap(null)).toBe(false)
-      expect(isMap(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isArrayBufferView', () => {
-    it('correctly identifies ArrayBufferView objects', () => {
-      expect(isArrayBufferView(new Uint8Array())).toBe(true)
-      expect(isArrayBufferView(new Int32Array())).toBe(true)
-      expect(isArrayBufferView(new Float64Array())).toBe(true)
-      expect(isArrayBufferView(new DataView(new ArrayBuffer(10)))).toBe(true)
-
-      expect(isArrayBufferView(new ArrayBuffer(10))).toBe(false)
-      expect(isArrayBufferView({})).toBe(false)
-      expect(isArrayBufferView(null)).toBe(false)
-      expect(isArrayBufferView(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isSet', () => {
-    it('correctly identifies Set objects', () => {
-      expect(isSet(new Set())).toBe(true)
-      expect(isSet(new Set([1, 2, 3]))).toBe(true)
-
-      expect(isSet({})).toBe(false)
-      expect(isSet(new Map())).toBe(false)
-      expect(isSet(null)).toBe(false)
-      expect(isSet(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isWeakMap', () => {
-    it('correctly identifies WeakMap objects', () => {
-      expect(isWeakMap(new WeakMap())).toBe(true)
-
-      const obj = {}
-      const wm = new WeakMap([[obj, 'value']])
-      expect(isWeakMap(wm)).toBe(true)
-
-      expect(isWeakMap(new Map())).toBe(false)
-      expect(isWeakMap({})).toBe(false)
-      expect(isWeakMap(null)).toBe(false)
-      expect(isWeakMap(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isWeakSet', () => {
-    it('correctly identifies WeakSet objects', () => {
-      expect(isWeakSet(new WeakSet())).toBe(true)
-
-      const obj = {}
-      const ws = new WeakSet([obj])
-      expect(isWeakSet(ws)).toBe(true)
-
-      expect(isWeakSet(new Set())).toBe(false)
-      expect(isWeakSet({})).toBe(false)
-      expect(isWeakSet(null)).toBe(false)
-      expect(isWeakSet(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isDataView', () => {
-    it('correctly identifies DataView objects', () => {
-      const buffer = new ArrayBuffer(10)
-      expect(isDataView(new DataView(buffer))).toBe(true)
-
-      expect(isDataView(buffer)).toBe(false)
-      expect(isDataView(new Uint8Array(buffer))).toBe(false)
-      expect(isDataView({})).toBe(false)
-      expect(isDataView(null)).toBe(false)
-      expect(isDataView(Undefined)).toBe(false)
-    })
-  })
-
-  describe('isBlob', () => {
-    it('correctly identifies Blob objects', () => {
-      // In a browser environment:
-      if (typeof Blob === 'undefined') {
-        // In Node.js without Blob:
-        expect(isBlob({})).toBe(false)
-        expect(isBlob(null)).toBe(false)
-        expect(isBlob(Undefined)).toBe(false)
-      } else {
-        expect(isBlob(new Blob(['content']))).toBe(true)
-
-        expect(isBlob({})).toBe(false)
-        expect(isBlob(null)).toBe(false)
-        expect(isBlob(Undefined)).toBe(false)
-      }
-    })
-  })
-
-  describe('isFile', () => {
-    it('correctly identifies File objects', () => {
-      // In a browser environment:
-      if (typeof File === 'undefined') {
-        // In Node.js without File:
-        expect(isFile({})).toBe(false)
-        expect(isFile(null)).toBe(false)
-        expect(isFile(Undefined)).toBe(false)
-      } else {
-        expect(isFile(new File(['content'], 'filename.txt'))).toBe(true)
-
-        expect(isFile({})).toBe(false)
-        expect(isFile(null)).toBe(false)
-        expect(isFile(Undefined)).toBe(false)
-      }
-    })
-  })
-})