@splendidlabz/utils 1.5.0 → 1.5.1

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,37 @@
+/**
+ * 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)
 }

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/index.js

@@ -7,6 +7,7 @@ export * from './functions/index.js'
 export * from './numbers/index.js'
 export * from './objects/index.js'
 export * from './promises/index.js'
+export * from './sse.js'
 export * from './strings/index.js'
 export * from './style/index.js'
 export * from './symbols/index.js'

package/lib/numbers/index.js

@@ -1,3 +1,5 @@
+export * from './math.js'
+
 export function splitUnit(string) {
   // If there are no units, return the number straight.
   if (typeof string === 'number') return [string, null]

package/lib/numbers/math.js

@@ -0,0 +1,9 @@
+// Convert radians to degrees
+export function toDegrees(angle) {
+  return angle * (180 / Math.PI)
+}
+
+// Convert degrees to radians
+export function toRadians(angle) {
+  return angle * (Math.PI / 180)
+}

package/lib/objects/equal.js

@@ -0,0 +1,9 @@
+import deepEqual from 'deep-eql'
+
+export function isEqual(a, b) {
+  return deepEqual(a, b)
+}
+
+export function notEqual(a, b) {
+  return !isEqual(a, b)
+}

package/lib/objects/index.js

@@ -1,5 +1,6 @@
 export * from './camelcase-keys.js'
 export * from './empty.js'
+export * from './equal.js'
 export * from './extend.js'
 export * from './flatten.js'
 export * from './json.js'

package/lib/objects/mix/mix.js

@@ -1,6 +1,8 @@
 export function mix(...sources) {
   const result = {}
   for (const source of sources) {
+    // Skip null or undefined sources
+    if (source == null) continue
     merge(result, source)
   }
   return result

package/lib/objects/mix/mix.test.js

@@ -322,3 +322,19 @@ it('Safe Merge', () => {
   expect(mixed.__proto__).toEqual({})
   /* eslint-enable */
 })
+
+it('should skip null and undefined sources', () => {
+  const obj1 = { a: 1 }
+  const obj2 = { b: 2 }
+  const expected = { a: 1, b: 2 }
+
+  expect(mix(obj1, null, obj2)).toEqual(expected)
+  expect(mix(null, obj1, obj2)).toEqual(expected)
+  expect(mix(obj1, obj2, null)).toEqual(expected)
+
+  expect(mix(obj1, undefined, obj2)).toEqual(expected)
+  expect(mix(undefined, obj1, obj2)).toEqual(expected)
+  expect(mix(obj1, obj2, undefined)).toEqual(expected)
+
+  expect(mix(null, obj1, undefined, obj2, null)).toEqual(expected)
+})

package/lib/objects/nested-property.js

@@ -34,3 +34,8 @@ export function getNestedProperty2(object, path) {
   const pathArray = path.split('.')
   return getNestedProperty(object, pathArray)
 }
+
+// Same as dot syntax, but terser and more readable name
+export function getNestedValue(object, path) {
+  return path.split('.').reduce((acc, part) => acc?.[part], object)
+}

package/lib/sse.js

@@ -0,0 +1,61 @@
+// Server Sent Events (SSE) 
+import { parseJSON } from './objects/json.js'
+import { omitEmpty } from './objects/omit-empty.js'
+
+export function createSSE({ event, data, id, retry }) {
+  const eventString = event ? `event: ${event}\n` : ''
+  const idString = id ? `id: ${id}\n` : ''
+  const retryString = retry ? `retry: ${retry}\n` : ''
+  
+  if (typeof data === 'object') data = JSON.stringify(data)
+  const dataString = data ? `data: ${data}\n` : ''
+
+  return `${eventString}${dataString}${idString}${retryString}\n`
+}
+
+/**
+ * Parses a single SSE message into a structured object
+ * @param {string} message - The raw SSE message
+ * @returns {Object|null} The parsed message or null if invalid
+ * @property {string} [event] - The event type if specified
+ * @property {string|Object} data - The message data (parsed as JSON if possible)
+ * @property {string} [id] - The message ID if specified
+ * @property {number} [retry] - The retry interval if specified
+ */
+export function parseSSE(message) {
+  const lines = message.split('\n')
+  const result = {
+    event: 'message', // Default event type
+    data: '',
+    id: null,
+    retry: null
+  }
+
+  for (const line of lines) {
+    if (line.startsWith('data:')) {
+      const data = line.slice(5).trim()
+      result.data = parseJSON(data)
+      continue
+    } 
+    
+    if (line.startsWith('event:')) {
+      result.event = line.slice(6).trim()
+      continue
+    } 
+    
+    if (line.startsWith('id:')) {
+      result.id = line.slice(3).trim()
+      continue
+    } 
+
+    if (line.startsWith('retry:')) {
+      result.retry = parseInt(line.slice(6).trim(), 10)
+      continue
+    }
+  }
+
+
+  const ret = omitEmpty(result)
+  return ret.data ? ret : null
+}
+

package/lib/strings/markdown.js

@@ -1,13 +1,34 @@
+import { marked } from 'marked'
+import { gfmHeadingId } from 'marked-gfm-heading-id'
+import { mangle } from 'marked-mangle'
+
 /**
- * Removes leading whitespaces from a Markdown content so they can be rendered appropriately.
- * @param {string} content - The content to treat
- * @param {Boolean} options.inline - Whether content is inline, not block
- * @returns
+ * Converts markdown content to HTML with whitespace handling
+ * @param {string} content - Markdown content to convert
+ * @param {Object} [options={}] - Conversion options
+ * @param {boolean} [options.inline=false] - Whether content should be treated as inline markdown
+ * @returns {string|Promise<string>} HTML string or Promise that resolves to HTML string
  */
-export function treatMarkdownWhitespace(
-  content,
-  { inline, isSlot = false } = {},
-) {
+export function markdown(content, options = {}) {
+  const defaultOptions = { inline: false }
+  const opts = { ...defaultOptions, ...options }
+
+  // Prepare Marked
+  marked.use(mangle())
+  marked.use(gfmHeadingId())
+
+  const { content: treated } = treatMarkdownWhitespace(content, opts)
+  return marked.parse(treated)
+}
+
+/**
+ * Handles whitespace in markdown content to ensure proper rendering
+ * @param {string} content - Markdown content to process
+ * @param {Object} [options={}] - Processing options
+ * @param {boolean} [options.inline=false] - Whether content is inline markdown
+ * @returns {{ content: string, inline: boolean }} Processed content and inline status
+ */
+export function treatMarkdownWhitespace(content, { inline } = {}) {
   if (!content) return { content: '', inline }
   const lines = content.split('\n')
 
@@ -19,9 +40,7 @@ export function treatMarkdownWhitespace(
   const firstLineWithLeadingSpacesIndex = lines.findIndex(line =>
     line.match(/^\s+/),
   )
-
   const firstLineWithLeadingSpaces = lines[firstLineWithLeadingSpacesIndex]
-
   const indentation =
     firstLineWithLeadingSpaces?.match(/^\s+/)?.[0]?.length ?? 0
 

package/node/dirname.js

@@ -1,5 +1,5 @@
+import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import path from 'path'
 
 /**
  * Returns __dirname