@magic/types 0.1.23 → 0.1.25

package/src/fns.js

@@ -0,0 +1,630 @@
+/**
+ * Check if a value is an Array
+ * @param {unknown} e - value to test
+ * @returns {e is unknown[]} - true if value is an array
+ */
+export const isArray = e => Array.isArray(e)
+
+/**
+ * Check if a value is a boolean
+ * @param {unknown} e - value to test
+ * @returns {e is boolean}
+ */
+export const isBoolean = e => typeof e === 'boolean'
+
+/**
+ * Check if a value is defined (not undefined)
+ * @param {unknown} e - value to test
+ * @returns {e is NonNullable<unknown>}
+ */
+export const isDefined = e => typeof e !== 'undefined'
+
+/**
+ * Check if a value is undefined
+ * @param {unknown} e - value to test
+ * @returns {e is undefined}
+ */
+export const isUndefined = e => !isDefined(e)
+
+/**
+ * Check if a value is a function
+ * @param {unknown} e - value to test
+ * @returns {e is Function}
+ */
+export const isFunction = e => typeof e === 'function'
+
+/**
+ * Check if a value is an async function
+ * @param {unknown} e - value to test
+ * @returns {e is (...args: unknown[]) => Promise<unknown>}
+ */
+export const isAsyncFunction = e => Object.prototype.toString.call(e) === '[object AsyncFunction]'
+
+/**
+ * Check if a value is a generator function
+ * @param {unknown} e - value to test
+ * @returns {e is GeneratorFunction}
+ */
+export const isGeneratorFunction = e =>
+  Object.prototype.toString.call(e) === '[object GeneratorFunction]'
+
+/**
+ * Check if a value is a number
+ * @param {unknown} e - value to test
+ * @returns {e is number}
+ */
+export const isNumber = e => !isObject(e) && !isNull(e) && !isUndefined(e) && e === +e
+
+/**
+ * Check if a value is an integer
+ * @param {unknown} e - value to test
+ * @returns {e is number}
+ */
+export const isInteger = e => isNumber(e) && e === (e | 0)
+
+/**
+ * Check if a value is a float (any number)
+ * @param {unknown} e - value to test
+ * @returns {e is number}
+ */
+export const isFloat = e => isNumber(e)
+
+/**
+ * Check if a value is an object (but not null)
+ * @param {unknown} e - value to test
+ * @returns {e is object}
+ */
+export const isObject = e => typeof e === 'object' && !isNull(e)
+
+/**
+ * Check if a value is a plain object (`{}`)
+ * @param {unknown} e - value to test
+ * @returns {e is Record<string, unknown>}
+ */
+export const isObjectNative = e => Object.prototype.toString.call(e) === '[object Object]'
+
+/**
+ * Check if a value is mergeable (plain object, not Date or RegExp)
+ * @param {unknown} e - value to test
+ * @returns {e is Record<string, unknown>}
+ */
+export const isMergeableObject = e => isObject(e) && !isDate(e) && !isRegExp(e)
+
+/**
+ * Alias for isMergeableObject
+ * @type {(e: unknown) => e is Record<string, unknown>}
+ */
+export const isMergeable = isMergeableObject
+
+/**
+ * Check if a value is a string
+ * @param {unknown} e - value to test
+ * @returns {e is string}
+ */
+export const isString = e => typeof e === 'string'
+
+/**
+ * Check if a value is an RGB object {r,g,b}
+ * @param {unknown} e - value to test
+ * @returns {e is { r: number, g: number, b: number }}
+ */
+export const isRGBValue = e => isObjectNative(e) && [e.r, e.g, e.b].every(n => isNumber(n))
+export const isRGBObject = isRGBValue
+
+/**
+ * Check if a value is an RGBA object {r,g,b,a}
+ * @param {unknown} e - value to test
+ * @returns {e is { r: number, g: number, b: number, a: number }}
+ */
+export const isRGBAValue = e => isObjectNative(e) && [e.r, e.g, e.b, e.a].every(n => isNumber(n))
+export const isRGBAObject = isRGBAValue
+
+export const hexRegex = /#\b([a-f0-9]{3}|[a-f0-9]{4}|[a-f0-9]{6}|[a-f0-9]{8})\b/i
+
+/**
+ * Check if a string is a valid hex color (#rgb, #rgba, #rrggbb, #rrggbbaa)
+ * @param {unknown} e - value to test
+ * @returns {boolean}
+ */
+export const isHexColor = e => isString(e) && hexRegex.test(e)
+
+/**
+ * Check if a string is a 3-digit hex color
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isHexColor3 = e => isString(e) && /#\b([a-f0-9]{3})\b/i.test(e)
+
+/**
+ * Check if a string is a 4-digit hex color (#rgba)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isHexColor4 = e => isString(e) && /#\b([a-f0-9]{4})\b/i.test(e)
+
+/**
+ * Check if a string is a 6-digit hex color (#rrggbb)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isHexColor6 = e => isString(e) && /#\b([a-f0-9]{6})\b/i.test(e)
+
+/**
+ * Check if a string is an 8-digit hex color (#rrggbbaa)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isHexColor8 = e => isString(e) && /#\b([a-f0-9]{8})\b/i.test(e)
+
+/**
+ * Check if a string is an alpha hex color (#rgba or #rrggbbaa)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isHexAlphaColor = e => isString(e) && /#\b([a-f0-9]{4}|[a-f0-9]{8})\b/i.test(e)
+
+/**
+ * Check if a string is a 4-digit alpha hex color (#rgba)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isHexAlphaColor4 = e => isString(e) && /#\b([a-f0-9]{4})\b/i.test(e)
+
+/**
+ * Check if a string is an 8-digit alpha hex color (#rrggbbaa)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isHexAlphaColor8 = e => isString(e) && /#\b([a-f0-9]{8})\b/i.test(e)
+
+/**
+ * Check if a value is a color (RGB, RGBA, or hex)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isColor = e => isRGBAObject(e) || isRGBObject(e) || isHexColor(e) || isHexAlphaColor(e)
+
+/**
+ * Check if a value is truthy
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isTruthy = e => !!e
+
+/**
+ * Check if a value is falsy or empty
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isFalsy = e => !e || isEmpty(e)
+
+/**
+ * Get the length/size of a value
+ * - Arrays, strings, buffers → `.length`
+ * - Numbers → numeric value
+ * - Maps, Sets → `.size`
+ * - RegExp → pattern length
+ * - Objects → number of keys
+ * @param {unknown} arg
+ * @returns {number} - length/size or -1 if unknown
+ */
+export const getLength = arg => {
+  if (Array.isArray(arg) || typeof arg === 'string' || isBuffer(arg)) {
+    return arg.length
+  }
+  if (isInteger(arg)) {
+    return arg
+  }
+  if (arg instanceof Map || arg instanceof Set) {
+    return arg.size
+  }
+  if (arg instanceof RegExp) {
+    const str = arg.toString()
+    return str === '/(?:)/' ? 0 : str.length - 2 // length of pattern without slashes
+  }
+  if (isObjectNative(arg)) {
+    return Object.keys(arg).length
+  }
+  return -1
+}
+
+/**
+ * Compare two values by their length/size
+ * @param {unknown} len
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const compareCount = (len, e) => getLength(len) === getLength(e)
+
+/**
+ * @overload
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+/**
+ * @overload
+ * @param {unknown} a
+ * @returns {(c: unknown) => boolean}
+ */
+/**
+ * Check if length of `a` equals `b` (or return curried fn)
+ * @param {unknown} a
+ * @param {unknown} [b]
+ * @returns {boolean | ((c: unknown) => boolean)}
+ */
+export const isLengthEqual = (a, b) => (isDefined(b) ? compareCount(a, b) : b => compareCount(a, b))
+
+/**
+ * @overload
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+/**
+ * @overload
+ * @param {unknown} a
+ * @returns {(c: unknown) => boolean}
+ */
+/**
+ * Check if length of `a` > `b` (or return curried fn)
+ * @param {unknown} a
+ * @param {unknown} [b]
+ * @returns {boolean | ((c: unknown) => boolean)}
+ */
+export const isLengthGreater = (a, b) =>
+  isDefined(b) ? getLength(a) > getLength(b) : c => getLength(a) > getLength(c)
+
+/**
+ * @overload
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+/**
+ * @overload
+ * @param {unknown} a
+ * @returns {(c: unknown) => boolean}
+ */
+/**
+ * Check if length of `a` >= `b` (or return curried fn)
+ * @param {unknown} a
+ * @param {unknown} [b]
+ * @returns {boolean | ((c: unknown) => boolean)}
+ */
+export const isLengthGreaterOrEqual = (a, b) =>
+  isDefined(b) ? getLength(a) >= getLength(b) : c => getLength(a) >= getLength(c)
+
+/**
+ * @overload
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+/**
+ * @overload
+ * @param {unknown} a
+ * @returns {(c: unknown) => boolean}
+ */
+/**
+ * Check if length of `a` < `b` (or return curried fn)
+ * @param {unknown} a
+ * @param {unknown} [b]
+ * @returns {boolean | ((c: unknown) => boolean)}
+ */
+export const isLengthSmaller = (a, b) =>
+  isDefined(b) ? getLength(a) < getLength(b) : c => getLength(a) < getLength(c)
+
+/**
+ * @overload
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+/**
+ * @overload
+ * @param {unknown} a
+ * @returns {(c: unknown) => boolean}
+ */
+/**
+ * Check if length of `a` <= `b` (or return curried fn)
+ * @param {unknown} a
+ * @param {unknown} [b]
+ * @returns {boolean | ((c: unknown) => boolean)}
+ */
+export const isLengthSmallerOrEqual = (a, b) =>
+  isDefined(b) ? getLength(a) <= getLength(b) : c => getLength(a) <= getLength(c)
+
+/**
+ * Check if a value is empty
+ * - null/undefined → true
+ * - arrays, objects, regex → empty if size < 1
+ * - errors/dates → never empty
+ * - numbers, strings → falsy or 0/""
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isEmpty = e => {
+  if (isError(e) || isDate(e)) {
+    return false
+  }
+  if (isNull(e) || isUndefined(e)) {
+    return true
+  }
+  if (isArray(e)) {
+    return isLengthSmaller(e, 1)
+  }
+  if (isRegExp(e)) {
+    return isLengthSmaller(e, 1)
+  }
+  if (isObject(e)) {
+    return isLengthSmaller(e, 1)
+  }
+
+  return e === 0 || e === '' || !e
+}
+
+/**
+ * Check if a value is iterable (Array-like with forEach or implements Symbol.iterator)
+ * @param {unknown} e
+ * @returns {e is Iterable<unknown>}
+ */
+export const isIterable = e =>
+  isDefined(e) &&
+  ((isObject(e) && e !== null && isFunction(/** @type {{ forEach?: unknown }} */ (e).forEach)) ||
+    (isObject(e) &&
+      !isNull(e) &&
+      isFunction(/** @type {{ [Symbol.iterator]?: unknown }} */ (e)[Symbol.iterator])))
+
+/**
+ * Check if a string contains an `@` (naive email test)
+ * @param {unknown} e
+ * @returns {e is string}
+ */
+export const isEmail = e => isString(e) && e.indexOf('@') > -1
+
+/**
+ * Check if a value is null
+ * @param {unknown} e
+ * @returns {e is null}
+ */
+export const isNull = e => e === null
+
+/**
+ * Check if a value is undefined or null
+ * @param {unknown} e
+ * @returns {e is null | undefined}
+ */
+export const isUndefinedOrNull = e => isNull(e) || !isDefined(e)
+
+/**
+ * Check if a value is a Node.js Buffer
+ * @param {unknown} e
+ * @returns {e is Buffer}
+ */
+export const isBuffer = e => Buffer.isBuffer(e)
+
+/**
+ * Check if a value is a Promise
+ * @param {unknown} e
+ * @returns {e is Promise<unknown>}
+ */
+export const isPromise = e =>
+  Object.prototype.toString.call(e) === '[object Promise]' ||
+  (isObjectNative(e) && isFunction(e?.then))
+
+/**
+ * Alias for isPromise
+ * @type {(e: unknown) => e is Promise<unknown>}
+ */
+export const isThenable = isPromise
+
+/**
+ * Check if a value is the special `arguments` object
+ * @param {unknown} e
+ * @returns {e is IArguments}
+ */
+export const isArguments = e => Object.prototype.toString.call(e) === '[object Arguments]'
+
+/**
+ * Check if a string looks like a UUID v4 (basic structural test)
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export const isUUID = e => {
+  if (!isDefined(e)) return false
+  if (!isString(e)) return false
+
+  const split = e.split('-')
+  if (!isLengthEqual(split, 5)) return false
+
+  const lengths = [8, 4, 4, 4, 12]
+  if (lengths.some((l, i) => split[i].length !== l)) return false
+
+  if (Object.values(e).some(s => s > 'f')) return false
+
+  return true
+}
+
+/**
+ * Check if a value matches one of the given JS types
+ * @param {unknown} e
+ * @param {...string} types - typeof strings (e.g. "string", "number")
+ * @returns {boolean}
+ */
+export const isType = (e, ...types) =>
+  types.some(type => typeof e === type || Object.prototype.toString.call(e) === type)
+
+export const isTypes = isType
+
+/**
+ * Negation of isTypes
+ * @param {unknown} e
+ * @param {...string} types
+ * @returns {boolean}
+ */
+export const isNot = (e, ...types) => !isType(e, ...types)
+
+/**
+ * Check if two values have the same type
+ * @param {unknown} a - first value to compare
+ * @param {unknown} b - second value to compare
+ * @returns {boolean} - true if both values are of the same type
+ */
+export const isSameType = (a, b) => typeof a === typeof b
+
+/**
+ * Check if a value matches a type or passes a function check
+ * @template T
+ * @param {unknown} e - value to check
+ * @param {((v: unknown) => boolean) | T} t - function to validate value or a typeof string
+ * @returns {e is T} - true if value matches the type or passes the function check
+ */
+const isElementCheck = (e, t) => (isFunction(t) ? t(e) : typeof e === t)
+
+/**
+ * Check if a value is a string, number or a boolean
+ * @param {unknown} a
+ * @returns {a is string | number | boolean}
+ */
+export const isComparable = a => isBoolean(a) || isString(a) || isNumber(a)
+
+/**
+ * Check if every element of an array matches a predicate
+ * @template T
+ * @param {T | T[]} arr - value or array of values to check
+ * @param {((v: T) => boolean) | string} t - function or typeof string to validate elements
+ * @returns {boolean} - true if all elements match the predicate
+ */
+export const isEvery = (arr, t) =>
+  !isArray(arr) ? isElementCheck(arr, t) : arr.every(e => isElementCheck(e, t))
+
+/**
+ * Check if some elements of an array match a predicate
+ * @template T
+ * @param {T | T[]} arr - value or array of values to check
+ * @param {((v: T) => boolean) | string} t - function or typeof string to validate elements
+ * @returns {boolean} - true if at least one element matches the predicate
+ */
+export const isSome = (arr, t) =>
+  !isArray(arr) ? isElementCheck(arr, t) : arr.some(e => isElementCheck(e, t))
+
+/**
+ * Check if no elements of an array match a predicate
+ * @template T
+ * @param {T | T[]} arr - value or array of values to check
+ * @param {((v: T) => boolean) | string} t - function or typeof string to validate elements
+ * @returns {boolean} - true if no elements match the predicate
+ */
+export const isNone = (arr, t) => !isSome(arr, t)
+
+/**
+ * Check if a value is an instance of a given constructor
+ * @param {unknown} e - value to check
+ * @param {new (...args: any[]) => any} t - constructor function
+ * @returns {boolean} - true if value is an instance of constructor
+ */
+export const isInstanceOf = (e, t) => (!t ? false : e instanceof t)
+
+/**
+ * Check if a value is an Error
+ * @param {unknown} e - value to check
+ * @returns {e is Error} - true if value is an Error
+ */
+export const isError = e => isInstanceOf(e, Error)
+
+/**
+ * Check if a value is a Date
+ * @param {unknown} e - value to check
+ * @returns {e is Date} - true if value is a Date
+ */
+export const isDate = e => isInstanceOf(e, Date)
+
+/**
+ * Check if a value is a RegExp
+ * @param {unknown} e - value to check
+ * @returns {e is RegExp} - true if value is a RegExp
+ */
+export const isRegExp = e => isInstanceOf(e, RegExp)
+
+/**
+ * Check if a value is a Map
+ * @param {unknown} a - value to check
+ * @returns {a is Map<unknown, unknown>} - true if value is a Map
+ */
+export const isMap = a => isInstanceOf(a, Map)
+
+/**
+ * Check if a value is a Set
+ * @param {unknown} a - value to check
+ * @returns {a is Set<unknown>} - true if value is a Set
+ */
+export const isSet = a => isInstanceOf(a, Set)
+
+/**
+ * Check if a value is a WeakMap
+ * @param {unknown} a - value to check
+ * @returns {a is WeakMap<any, unknown>} - true if value is a WeakMap
+ */
+export const isWeakMap = a => isInstanceOf(a, WeakMap)
+
+/**
+ * Check if a value is a WeakSet
+ * @param {unknown} a - value to check
+ * @returns {a is WeakSet<any>} - true if value is a WeakSet
+ */
+export const isWeakSet = a => isInstanceOf(a, WeakSet)
+
+/**
+ * Check if a string is upper case
+ * @param {unknown} s - value to check
+ * @returns {s is string} - true if string is all upper case
+ */
+export const isUpperCase = s => (isString(s) ? s === s.toUpperCase() : false)
+
+/**
+ * Check if a string is lower case
+ * @param {unknown} s - value to check
+ * @returns {s is string} - true if string is all lower case
+ */
+export const isLowerCase = s => (isString(s) ? s === s.toLowerCase() : false)
+
+/**
+ * Check if an object has an own property key
+ * @template {string | number | symbol} K
+ * @param {unknown} o - object to check
+ * @param {K} k - key to check
+ * @returns {o is Record<K, unknown>} - true if object has own property key
+ */
+export const isOwnProp = (o, k) => isObjectNative(o) && k in o
+
+/**
+ * Check if an object has an own property key (alias of isOwnProp)
+ * @param {unknown} o - object to check
+ * @param {string} k - key to check
+ * @returns {boolean} - true if object has own property key
+ */
+export const isOwnProperty = isOwnProp
+
+/**
+ * A type representing a Module-like object
+ * @typedef {object & { [Symbol.toStringTag]: 'Module' }} ModuleLike
+ */
+
+/**
+ * Check if a value is a Module-like object
+ * @param {unknown} s - value to check
+ * @returns {s is ModuleLike} - true if value is a Module-like object
+ */
+export const isModule = s => Object.prototype.toString.call(s) === '[object Module]'
+
+/**
+ * Check if a string is upper or lower case depending on mode
+ * @type {((s: unknown, c?: 'up' | 'down') => boolean) & {
+ *   upper: (s: unknown) => boolean,
+ *   lower: (s: unknown) => boolean
+ * }}
+ */
+export const isCase = (s, c = 'up') => (c === 'up' ? isUpperCase(s) : isLowerCase(s))
+isCase.upper = isUpperCase
+isCase.lower = isLowerCase

package/src/index.js

@@ -0,0 +1,8 @@
+import def from './lib.js'
+
+export * from './fns.js'
+export * as deep from './deep/index.js'
+
+export const is = def
+
+export default is