@splendidlabz/utils 1.5.0 → 1.6.0

package/lib/arrays/sort.js

@@ -0,0 +1,88 @@
+import { getNestedValue } from '../objects/nested-property.js'
+
+/**
+ * Sorts an array of objects, numbers, or strings without mutating the original array.
+ * Supports nested properties, multiple sort keys, and various data types.
+ * 
+ * @template T
+ * @param {T[]} array - Array to sort
+ * @param {Object} [options] - Sort options
+ * @param {string|string[]|null} [options.props=null] - Property or array of properties to sort by. If null, sorts simple arrays
+ * @param {boolean} [options.reverse=false] - Whether to sort in reverse order
+ * @returns {T[]} New sorted array
+ * @example
+ * // Sort simple array
+ * sort([3, 1, 2]) // [1, 2, 3]
+ * 
+ * // Sort objects by single property
+ * sort(users, { props: 'name' })
+ * 
+ * // Sort objects by multiple properties
+ * sort(users, { props: ['age', 'name'] })
+ * 
+ * // Sort in reverse order
+ * sort(users, { props: 'age', reverse: true })
+ * 
+ * // Sort by nested property
+ * sort(users, { props: 'address.city' })
+ */
+export function sort(array, { props = null, reverse = false } = {}) {
+  const clone = array.slice()
+
+  // Handle simple arrays (numbers or strings)
+  if (props === null) {
+    return clone.sort((a, b) => {
+      const comparison = compareValues(a, b)
+      return reverse ? -comparison : comparison
+    })
+  }
+
+  // Handle objects in arrays
+  const properties = Array.isArray(props) ? props : [props]
+
+  return clone.sort((a, b) => {
+    for (const property of properties) {
+      const aValue = getNestedValue(a, property)
+      const bValue = getNestedValue(b, property)
+
+      // Skip if values are equal
+      if (aValue === bValue) continue
+
+      // Push null/undefined values to the end
+      if (aValue == null) return 1
+      if (bValue == null) return -1
+
+      // Compare values and handle reverse sort
+      const comparison = compareValues(aValue, bValue)
+      return reverse ? -comparison : comparison
+    }
+    return 0
+  })
+}
+
+/**
+ * Compares two values for sorting, handling different data types.
+ * Supports numbers, strings, dates, and falls back to string comparison.
+ * 
+ * @param {*} a - First value to compare
+ * @param {*} b - Second value to compare
+ * @returns {number} -1 if a < b, 0 if a === b, 1 if a > b
+ * @private
+ */
+function compareValues(a, b) {
+  // Compare numbers
+  if (typeof a === 'number' && typeof b === 'number') return a - b
+
+  // Compare strings
+  if (typeof a === 'string' && typeof b === 'string') return a.localeCompare(b)
+
+  // Compare dates
+  const aDate = new Date(a)
+  const bDate = new Date(b)
+  const aTime = aDate.getTime()
+  const bTime = bDate.getTime()
+  if (!isNaN(aTime) && !isNaN(bTime)) return aTime - bTime
+
+  // Convert into strings and compare
+  return String(a).localeCompare(String(b))
+}

package/lib/arrays/sort.spec.js

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest'
+
+import { sort } from './index.js'
+
+describe('Sort by', _ => {
+  it('Standard array - numbers', async () => {
+    const array = [3, 1, 2]
+    const sorted = sort(array)
+    const reversed = sort(array, { reverse: true })
+    expect(sorted).toEqual([1, 2, 3])
+    expect(reversed).toEqual([3, 2, 1])
+  })
+
+  it('Standard array - strings', async () => {
+    const array = ['c', 'a', 'b']
+    const sorted = sort(array)
+    const reversed = sort(array, { reverse: true })
+    expect(sorted).toEqual(['a', 'b', 'c'])
+    expect(reversed).toEqual(['c', 'b', 'a'])
+  })
+
+  it('Standard array - dates', async () => {
+    const array = [
+      new Date('2021-05-18'),
+      new Date('2022-01-01'),
+      new Date('2025-03-09'),
+    ]
+    const sorted = sort(array)
+    const reversed = sort(array, { reverse: true })
+    expect(sorted).toEqual([
+      new Date('2021-05-18'),
+      new Date('2022-01-01'),
+      new Date('2025-03-09'),
+    ])
+    expect(reversed).toEqual([
+      new Date('2025-03-09'),
+      new Date('2022-01-01'),
+      new Date('2021-05-18'),
+    ])
+  })
+  it('Array of objects — simple integer', async () => {
+    const array = [
+      { name: 'Ace', age: 30 },
+      { name: 'Betty', age: 25 },
+      { name: 'Candy', age: 35 },
+    ]
+    const sorted = sort(array, { props: 'age' })
+    const reversed = sort(array, { props: 'age', reverse: true })
+    expect(sorted).toEqual([
+      { name: 'Betty', age: 25 },
+      { name: 'Ace', age: 30 },
+      { name: 'Candy', age: 35 },
+    ])
+    expect(reversed).toEqual([
+      { name: 'Candy', age: 35 },
+      { name: 'Ace', age: 30 },
+      { name: 'Betty', age: 25 },
+    ])
+  })
+
+  it('Array of objects — simple string', async () => {
+    const array = [
+      { name: 'Ace', age: 30 },
+      { name: 'Betty', age: 25 },
+      { name: 'Candy', age: 35 },
+    ]
+    const sorted = sort(array, { props: 'name' })
+    const reversed = sort(array, { props: 'name', reverse: true })
+    expect(sorted).toEqual([
+      { name: 'Ace', age: 30 },
+      { name: 'Betty', age: 25 },
+      { name: 'Candy', age: 35 },
+    ])
+    expect(reversed).toEqual([
+      { name: 'Candy', age: 35 },
+      { name: 'Betty', age: 25 },
+      { name: 'Ace', age: 30 },
+    ])
+  })
+
+  it('Double property', async () => {
+    const array = [
+      { name: 'Ace', age: 30 },
+      { name: 'Betty', age: 25 },
+      { name: 'Candy', age: 35 },
+      { name: 'Danny', age: 30 },
+    ]
+    const sorted = sort(array, { props: ['age', 'name'] })
+    const reversed = sort(array, { props: ['age', 'name'], reverse: true })
+    expect(sorted).toEqual([
+      { name: 'Betty', age: 25 },
+      { name: 'Ace', age: 30 },
+      { name: 'Danny', age: 30 },
+      { name: 'Candy', age: 35 },
+    ])
+    expect(reversed).toEqual([
+      { name: 'Candy', age: 35 },
+      { name: 'Danny', age: 30 },
+      { name: 'Ace', age: 30 },
+      { name: 'Betty', age: 25 },
+    ])
+  })
+
+  it('Nested value', async () => {
+    const array = [
+      { data: { value: 1 } },
+      { data: { value: 2 } },
+      { data: { value: 3 } },
+    ]
+    const sorted = sort(array, { props: 'data.value' })
+    const reversed = sort(array, { props: 'data.value', reverse: true })
+    expect(sorted).toEqual([
+      { data: { value: 1 } },
+      { data: { value: 2 } },
+      { data: { value: 3 } },
+    ])
+    expect(reversed).toEqual([
+      { data: { value: 3 } },
+      { data: { value: 2 } },
+      { data: { value: 1 } },
+    ])
+  })
+})

package/lib/arrays/unique.js

@@ -0,0 +1,3 @@
+export function uniqueArray(array) {
+  return Array.from(new Set(array))
+}

package/lib/checks.js

@@ -1,11 +1,53 @@
+/**
+ * Checks if a value is a plain object (not an array or null)
+ * @param {unknown} x - The value to check
+ * @returns {boolean} True if the value is a plain object
+ * @example
+ * isObject({}) // true
+ * isObject([]) // false
+ * isObject(null) // false
+ */
 export function isObject(x) {
   return typeof x === 'object' && !Array.isArray(x) && x !== null
 }
 
+/**
+ * Checks if a value is an array
+ * @param {unknown} x - The value to check
+ * @returns {boolean} True if the value is an array
+ * @example
+ * isArray([]) // true
+ * isArray({}) // false
+ */
 export function isArray(x) {
   return Array.isArray(x)
 }
 
+/**
+ * Checks if a value is not a plain object
+ * @param {unknown} x - The value to check
+ * @returns {boolean} True if the value is not a plain object
+ * @example
+ * notObject([]) // true
+ * notObject(null) // true
+ * notObject({}) // false
+ */
 export function notObject(x) {
   return !isObject(x)
 }
+
+export function getType(x) {
+  if (typeof x === 'string') return 'string'
+  if (typeof x === 'number') {
+    if (Number.isInteger(x)) return 'integer'
+    return 'float'
+  }
+  if (typeof x === 'boolean') return 'boolean'
+  if (typeof x === 'function') return 'function'
+  if (typeof x === 'undefined') return 'undefined'
+  if (typeof x === 'symbol') return 'symbol'
+  if (typeof x === 'bigint') return 'bigint'
+  if (Array.isArray(x)) return 'array'
+  if (typeof x === 'object') return 'object'
+  return 'unknown'
+}

package/lib/date/index.js

@@ -1,2 +1,3 @@
-export * from './months.js'
 export * from './days.js'
+export * from './months.js'
+export * from './time.js'

package/lib/date/time.js

@@ -0,0 +1,50 @@
+import { splitUnit } from '../numbers/index.js'
+
+/**
+ * Convert a time string to milliseconds
+ * @param {string} arg - The time string to convert
+ * @returns {number}
+ */
+export function ms(arg) {
+  const [value, unit] = splitUnit(arg)
+  if (unit === 'd') return getTimeInMs(value, 'days')
+  if (unit === 'day') return getTimeInMs(value, 'days')
+  if (unit === 'days') return getTimeInMs(value, 'days')
+  if (unit === 'h') return getTimeInMs(value, 'hours')
+  if (unit === 'hr') return getTimeInMs(value, 'hours')
+  if (unit === 'hour') return getTimeInMs(value, 'hours')
+  if (unit === 'hours') return getTimeInMs(value, 'hours')
+  if (unit === 'm') return getTimeInMs(value, 'minutes')
+  if (unit === 'min') return getTimeInMs(value, 'minutes')
+  if (unit === 'minute') return getTimeInMs(value, 'minutes')
+  if (unit === 'minutes') return getTimeInMs(value, 'minutes')
+  if (unit === 's') return getTimeInMs(value, 'seconds')
+  if (unit === 'sec') return getTimeInMs(value, 'seconds')
+  if (unit === 'second') return getTimeInMs(value, 'seconds')
+  if (unit === 'seconds') return getTimeInMs(value, 'seconds')
+
+  // The rest are for milliseconds
+  return value
+}
+
+export function seconds(arg) {
+  const value = ms(arg)
+  return value / 1000
+}
+
+export function getTimeInMs(value, unit = 'ms') {
+  switch (unit) {
+    case 'ms':
+      return value
+    case 'seconds':
+      return value * 1000
+    case 'minutes':
+      return value * 1000 * 60
+    case 'hours':
+      return value * 1000 * 60 * 60
+    case 'days':
+      return value * 1000 * 60 * 60 * 24
+    case 'weeks':
+      return value * 1000 * 60 * 60 * 24 * 7
+  }
+}

package/lib/form/sanitize.js

@@ -1,47 +1,80 @@
-import DOMPurify from 'dompurify'
-
 /**
- * Sanitizes HTML string using DOMPurify.
- * @param {string} html - The HTML string to sanitize.
- * @param {Object} [options={}] - DOMPurify configuration options.
- * @returns {string} The sanitized HTML string.
+ * @typedef {Object} SanitizeOptions
+ * @property {Function} [sanitizer] - Function to sanitize strings
+ * @property {*} [additional] - Any additional properties are passed through to the sanitizer function
  */
-export function sanitize(html, options = {}) {
-  return DOMPurify.sanitize(html, options)
-}
 
 /**
- * Recursively sanitizes entries in an object or array.
- * @param {Array} entries - The entries to sanitize.
- * @param {Object} [options={}] - DOMPurify configuration options.
- * @returns {Array} The sanitized entries.
+ * Core sanitization function that handles different value types.
+ * Throws if no sanitizer function is provided.
+ * Any additional properties in options are passed through to the sanitizer function.
+ * 
+ * @param {*} value - The value to sanitize
+ * @param {SanitizeOptions} [options={}] - Sanitization options
+ * @throws {Error} If sanitizer function is not provided
+ * @returns {*} Sanitized value
+ * @example
+ * // Basic sanitization
+ * sanitize('hello', { sanitizer: str => str.trim() })
+ * 
+ * // With additional options passed to sanitizer
+ * sanitize('hello', { 
+ *   sanitizer: (str, length, char) => str.padEnd(length, char),
+ *   length: 10,
+ *   char: '-'
+ * })
  */
-export function sanitizeEntries(entries, options = {}) {
-  return entries.map(([key, value]) => {
-    if (Array.isArray(value)) {
-      return [
-        key,
-        value.map(item => sanitizeEntries(Object.entries(item), options)),
-      ]
-    }
+export function sanitize(value, options = {}) {
+  const { sanitizer, ...rest } = options
+  if (!sanitizer) throw new Error('sanitizer function is required')
 
-    if (value && typeof value === 'object') {
-      return [
+  if (typeof value === 'string') return sanitizer(value, rest)
+  if (Array.isArray(value)) return sanitizeArray(value, { sanitizer, ...rest })
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, val]) => [
         key,
-        Object.fromEntries(sanitizeEntries(Object.entries(value), options)),
-      ]
-    }
-
-    return [key, sanitize(value, options)]
-  })
+        sanitize(val, { sanitizer, ...rest }),
+      ]),
+    )
+  }
+  return value
+}
+/**
+ * Sanitizes an array by recursively sanitizing each element.
+ * Throws if no sanitizer function is provided.
+ * Any additional properties in options are passed through to the sanitizer function.
+ * 
+ * @param {Array} arr - Array to sanitize
+ * @param {SanitizeOptions} options - Sanitization options
+ * @throws {Error} If sanitizer function is not provided
+ * @returns {Array} New array with sanitized values
+ */
+function sanitizeArray(arr, { sanitizer, ...rest }) {
+  if (!sanitizer) throw new Error('sanitizer function is required')
+  return arr.map(item => sanitize(item, { sanitizer, ...rest }))
 }
 
 /**
- * Sanitizes all string values in an object.
- * @param {Object} obj - The object to sanitize.
- * @param {Object} [options={}] - DOMPurify configuration options.
- * @returns {Object} A new object with all string values sanitized.
+ * Sanitizes all string values in an object recursively.
+ * Throws if no sanitizer function is not provided.
+ * Any additional properties in options are passed through to the sanitizer function.
+ * 
+ * @param {Object} obj - Object to sanitize
+ * @param {SanitizeOptions} [options={}] - Sanitization options
+ * @throws {Error} If sanitizer function is not provided
+ * @returns {Object} New object with sanitized values
  */
-export function sanitizeObject(obj, options = {}) {
-  return Object.fromEntries(sanitizeEntries(Object.entries(obj), options))
+function sanitizeObject(obj, { sanitizer, ...options } = {}) {
+  if (!sanitizer) throw new Error('sanitizer function is required')
+  if (Array.isArray(obj)) return sanitizeArray(obj, { sanitizer, ...options })
+
+  return Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => [
+      key,
+      sanitize(value, { sanitizer, ...options }),
+    ]),
+  )
 }
+
+export { sanitizeArray, sanitizeObject }

package/lib/form/sanitize.spec.js

@@ -0,0 +1,126 @@
+import sanitizeHtml from 'sanitize-html'
+import { describe, expect, it } from 'vitest'
+import { sanitize } from './sanitize.js'
+
+// Real sanitizer using sanitize-html
+function mockSanitizer(value, options = {}) {
+  if (typeof value !== 'string') return value
+  return sanitizeHtml(value, {
+    allowedTags: ['b', 'i', 'em', 'strong', 'a'],
+    allowedAttributes: {
+      a: ['href'],
+    },
+    ...options,
+  })
+}
+
+describe('sanitize', () => {
+  it('sanitizes HTML in string values', () => {
+    const input = {
+      name: '<script>alert("xss")</script>John',
+      bio: '<p>Hello <b>World</b> <script>alert("xss")</script></p>',
+      link: '<a href="javascript:alert(1)">Click me</a>',
+      safeLink: '<a href="https://example.com">Safe link</a>',
+    }
+
+    const expected = {
+      name: 'John',
+      bio: 'Hello <b>World</b> ',
+      link: '<a>Click me</a>',
+      safeLink: '<a href="https://example.com">Safe link</a>',
+    }
+
+    expect(sanitize(input, { sanitizer: mockSanitizer })).toEqual(expected)
+  })
+
+  it('sanitizes nested objects with HTML', () => {
+    const input = {
+      user: {
+        name: '<script>alert("xss")</script>John',
+        profile: {
+          bio: '<p>Hello <b>World</b></p>',
+          links: [
+            '<a href="javascript:alert(1)">Bad</a>',
+            '<a href="https://good.com">Good</a>',
+          ],
+        },
+      },
+    }
+
+    const expected = {
+      user: {
+        name: 'John',
+        profile: {
+          bio: 'Hello <b>World</b>',
+          links: ['<a>Bad</a>', '<a href="https://good.com">Good</a>'],
+        },
+      },
+    }
+
+    expect(sanitize(input, { sanitizer: mockSanitizer })).toEqual(expected)
+  })
+
+  it('preserves non-string values and sanitizes arrays correctly', () => {
+    const input = {
+      name: '<script>alert("xss")</script>John',
+      age: 25,
+      active: true,
+      email: null,
+      role: undefined,
+      tags: ['<script>alert(1)</script>admin', 'user'],
+      numbers: [1, 2, 3],
+      mixed: ['<b>bold</b>', 42, null, '<script>alert(1)</script>text'],
+    }
+
+    const expected = {
+      name: 'John',
+      age: 25,
+      active: true,
+      email: null,
+      role: undefined,
+      tags: ['admin', 'user'],
+      numbers: [1, 2, 3],
+      mixed: ['<b>bold</b>', 42, null, 'text'],
+    }
+
+    expect(sanitize(input, { sanitizer: mockSanitizer })).toEqual(expected)
+  })
+
+  it('throws error when sanitizer is not provided', () => {
+    const input = { name: '<script>alert(1)</script>John' }
+    expect(() => sanitize(input)).toThrow('sanitizer function is required')
+  })
+
+  it('allows custom sanitizer options', () => {
+    const input = {
+      content: '<p>Hello <span>World</span> <script>alert(1)</script></p>',
+    }
+
+    const defaultOptions = {
+      allowedTags: ['b', 'i', 'em', 'strong', 'a'],
+      allowedAttributes: {
+        a: ['href'],
+      },
+    }
+
+    // Test with custom allowed tags
+    const withSpan = sanitize(input, {
+      sanitizer: v =>
+        mockSanitizer(v, {
+          ...defaultOptions,
+          allowedTags: [...defaultOptions.allowedTags, 'span'],
+        }),
+    })
+    expect(withSpan.content).toBe('Hello <span>World</span> ')
+
+    // Test with no allowed tags
+    const noTags = sanitize(input, {
+      sanitizer: v =>
+        mockSanitizer(v, {
+          ...defaultOptions,
+          allowedTags: [],
+        }),
+    })
+    expect(noTags.content).toBe('Hello World ')
+  })
+})

package/lib/hash.js

@@ -0,0 +1,18 @@
+export function isHashedValue(value, type = 'sha256') {
+  if (typeof value !== 'string') return null
+  value = value.trim()
+  type = type.toLowerCase()
+
+  if (type === 'sha256') {
+    return value.length === 64 && /^[a-fA-F0-9]{64}$/.test(value)
+  }
+
+  if (type === 'sha1') {
+    return value.length === 40 && /^[a-fA-F0-9]{40}$/.test(value)
+  }
+
+  if (type === 'md5') {
+    return value.length === 32 && /^[a-fA-F0-9]{32}$/.test(value)
+  }
+  return null
+}