@carto/ps-utils 2.0.1 → 2.1.0

package/src/debounce/debounce.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it, vi } from 'vitest'
+import { debounce } from './debounce'
+
+describe('debounce', () => {
+  it('should debounce a function', () => {
+    vi.useFakeTimers()
+
+    const mockFn = vi.fn()
+    const debouncedFn = debounce(mockFn, 1000)
+
+    debouncedFn()
+    expect(mockFn).not.toBeCalled()
+
+    vi.advanceTimersByTime(500)
+    debouncedFn()
+    expect(mockFn).not.toBeCalled()
+
+    vi.advanceTimersByTime(1000)
+    expect(mockFn).toHaveBeenCalled()
+  })
+})

package/src/debounce/debounce.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates a debounced version of a function that delays execution until after the specified wait time has elapsed since the last invocation.
+ *
+ * @param func - The function to debounce.
+ * @param waitFor - The delay in milliseconds to wait before executing.
+ * @returns A debounced version of the provided function.
+ *
+ * @example
+ * ```ts
+ * const debouncedSearch = debounce((query: string) => {
+ *   fetchResults(query)
+ * }, 300)
+ *
+ * debouncedSearch('hello') // Only executes after 300ms of inactivity
+ * ```
+ */
+export function debounce<F extends (...args: unknown[]) => unknown>(
+  func: F,
+  waitFor: number,
+): (...args: Parameters<F>) => ReturnType<F> {
+  let timeout: ReturnType<typeof setTimeout>
+
+  const debounced = (...args: Parameters<F>) => {
+    clearTimeout(timeout)
+    timeout = setTimeout(() => func(...args), waitFor)
+  }
+
+  return debounced as (...args: Parameters<F>) => ReturnType<F>
+}

package/src/formatters/constants.ts

@@ -0,0 +1,49 @@
+/**
+ * Default configuration options for the formatter utilities (`formatNumber`, `formatCurrency`, `formatDate`).
+ *
+ * @remarks
+ * Contains preset `Intl.NumberFormatOptions` and `Intl.DateTimeFormatOptions` for three keys:
+ * - `NUMBER` - Compact decimal notation with 1 fraction digit.
+ * - `CURRENCY` - Compact USD currency with 2 fraction digits.
+ * - `DATE` - Numeric year, 2-digit month and day.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_FORMATTERS_CONFIG } from '@carto/ps-utils'
+ *
+ * // Override defaults for a custom number format
+ * const options = { ...DEFAULT_FORMATTERS_CONFIG.NUMBER, maximumFractionDigits: 3 }
+ * ```
+ */
+export type DefaultFormatterKey = 'NUMBER' | 'CURRENCY' | 'DATE'
+
+export const DEFAULT_FORMATTERS_CONFIG: Record<
+  string,
+  Intl.NumberFormatOptions | Intl.DateTimeFormatOptions
+> & {
+  NUMBER: Intl.NumberFormatOptions
+  CURRENCY: Intl.NumberFormatOptions
+  DATE: Intl.DateTimeFormatOptions
+} = {
+  NUMBER: {
+    style: 'decimal',
+    maximumFractionDigits: 1,
+    minimumFractionDigits: 0,
+    notation: 'compact',
+    compactDisplay: 'short',
+  },
+
+  CURRENCY: {
+    style: 'currency',
+    currency: 'USD',
+    maximumFractionDigits: 2,
+    minimumFractionDigits: 2,
+    notation: 'compact',
+    compactDisplay: 'short',
+  },
+  DATE: {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  },
+}

package/src/formatters/date/format-date.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'vitest'
+import { formatDate } from './format-date'
+
+describe('formatDate', () => {
+  const date = new Date(1668771515109)
+
+  test('should format in the specified locale', () => {
+    const result = formatDate(date, 'es-ES')
+    expect(result).toBe('18/11/2022')
+  })
+
+  test('should format with the specified style', () => {
+    const result = formatDate(date, 'es-ES', {
+      month: 'long',
+    })
+    expect(result).toBe('18 de noviembre de 2022')
+  })
+
+  test('should format using specific options', () => {
+    const result = formatDate(date, 'en-GB', {
+      hour: 'numeric',
+      hourCycle: 'h12',
+      dayPeriod: 'short',
+      timeZone: 'UTC',
+    })
+    expect(result).toBe('18/11/2022, 11 in the morning')
+  })
+  test('should format using explicit Y/M/D options', () => {
+    const result = formatDate(date, 'es-ES', {
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    })
+    expect(result).toBe('18/11/2022')
+  })
+})

package/src/formatters/date/format-date.ts

@@ -0,0 +1,34 @@
+import { DEFAULT_FORMATTERS_CONFIG } from '../constants'
+
+/**
+ * Formats a date or timestamp according to locale-specific conventions using the `Intl.DateTimeFormat` API.
+ *
+ * @param value - The date to format (Date object or timestamp in milliseconds).
+ * @param locales - Locale identifier(s) for formatting (e.g., `'en-US'`, `'fr-FR'`).
+ * @param options - Date/time formatting options to override the defaults (numeric year, 2-digit month and day).
+ *   When `dateStyle` or `timeStyle` is provided the defaults are not applied, as they are incompatible with
+ *   individual date/time component options.
+ * @returns The formatted date string.
+ *
+ * @example
+ * ```ts
+ * formatDate(new Date('2024-03-15'), 'en-US') // "03/15/2024"
+ * formatDate(new Date('2024-03-15'), 'en-US', { month: 'long' }) // "March 15, 2024"
+ * ```
+ */
+export function formatDate(
+  value: number | Date,
+  locales: string | string[],
+  options: Intl.DateTimeFormatOptions = {},
+): string {
+  const hasStyle = options.dateStyle !== undefined || options.timeStyle !== undefined
+
+  const formatterOptions: Intl.DateTimeFormatOptions = hasStyle
+    ? options
+    : {
+        ...DEFAULT_FORMATTERS_CONFIG.DATE,
+        ...options,
+      }
+
+  return Intl.DateTimeFormat(locales, formatterOptions).format(value)
+}

package/src/formatters/number/format-number.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'vitest'
+import { formatCurrency, formatNumber } from './format-number'
+
+describe('utils :: formatters :: number', () => {
+  describe('formatNumber', () => {
+    test('should use specified locale', () => {
+      const result = formatNumber(3001, 'es-ES')
+      expect(result).toBe('3 mil')
+    })
+
+    test('should use specified style', () => {
+      const result = formatNumber(45, 'es-ES', {
+        style: 'unit',
+        unit: 'liter',
+        unitDisplay: 'long',
+      })
+      expect(result).toBe('45 litros')
+    })
+
+    test('should use specified style', () => {
+      const result = formatNumber(45123, 'en-US')
+      expect(result).toBe('45.1K')
+    })
+  })
+  describe('formatCurrency', () => {
+    test('should return a currency formatted string', () => {
+      const result = formatCurrency(3001, 'en-US')
+      expect(result).toBe('$3.00K')
+    })
+    test('should return a currency formatted string with overrided options', () => {
+      const result = formatCurrency(3001, 'en-US', {
+        style: 'currency',
+        currency: 'USD',
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0,
+      })
+      expect(result).toBe('$3K')
+    })
+    test('should return a currency formatted string with negative number', () => {
+      const result = formatCurrency(-1, 'en-US', {
+        style: 'currency',
+        currency: 'USD',
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0,
+      })
+      expect(result).toBe('-$1')
+    })
+  })
+})

package/src/formatters/number/format-number.ts

@@ -0,0 +1,68 @@
+import { DEFAULT_FORMATTERS_CONFIG } from '../constants'
+
+/**
+ * Formats a number using `Intl.NumberFormat` with the given locale and options.
+ *
+ * @param value - The number to format.
+ * @param locale - The locale identifier (e.g., `'en-US'`, `'es-ES'`).
+ * @param options - `Intl.NumberFormatOptions` for customization (style, unit, etc.).
+ * @returns The formatted number string.
+ */
+function format(
+  value: number,
+  locale: string,
+  options?: Intl.NumberFormatOptions,
+): string {
+  return Intl.NumberFormat(locale, options).format(value)
+}
+
+/**
+ * Formats a number with locale-aware separators, compact notation, and customizable precision.
+ *
+ * @param value - The number to format.
+ * @param locale - The locale identifier (e.g., `'en-US'`, `'es-ES'`).
+ * @param options - `Intl.NumberFormatOptions` to override the defaults (compact decimal with 1 fraction digit).
+ * @returns The formatted number string.
+ *
+ * @example
+ * ```ts
+ * formatNumber(123456, 'en-US')    // "123.5K"
+ * formatNumber(1234567, 'en-US')   // "1.2M"
+ * formatNumber(123456, 'es-ES')    // "123 mil"
+ * ```
+ */
+export function formatNumber(
+  value: number,
+  locale: string,
+  options: Intl.NumberFormatOptions = {},
+): string {
+  return format(value, locale, {
+    ...DEFAULT_FORMATTERS_CONFIG.NUMBER,
+    ...options,
+  })
+}
+
+/**
+ * Formats a number as a currency value with proper symbols and regional conventions.
+ *
+ * @param value - The monetary value to format.
+ * @param locale - The locale identifier (e.g., `'en-US'`, `'fr-FR'`).
+ * @param options - `Intl.NumberFormatOptions` to override the defaults (compact USD with 2 fraction digits).
+ * @returns The formatted currency string.
+ *
+ * @example
+ * ```ts
+ * formatCurrency(123456, 'en-US')                          // "$123.46K"
+ * formatCurrency(123456, 'fr-FR', { currency: 'EUR' })     // "123,46 k €"
+ * ```
+ */
+export function formatCurrency(
+  value: number,
+  locale: string,
+  options: Intl.NumberFormatOptions = {},
+): string {
+  return format(value, locale, {
+    ...DEFAULT_FORMATTERS_CONFIG.CURRENCY,
+    ...options,
+  })
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { copy } from './clipboard/copy'
+
+export { CARTO_PALETTES } from './colors/carto-palettes/carto-palettes'
+export type { PaletteName } from './colors/carto-palettes/carto-palettes'
+export { hexToRgba } from './colors/hex-to-rgba/hex-to-rgba'
+export { paletteToHex } from './colors/palette-to-hex/palette-to-hex'
+export { rgbaToHex } from './colors/rgba-to-hex/rgba-to-hex'
+
+export { debounce } from './debounce/debounce'
+
+export { DEFAULT_FORMATTERS_CONFIG } from './formatters/constants'
+export { formatDate } from './formatters/date/format-date'
+export { formatCurrency, formatNumber } from './formatters/number/format-number'
+
+export { matchText } from './strings/match-text/match-text'
+export { normalize } from './strings/normalize/normalize'
+export type { Route, Values } from './strings/routes/types'
+export { replaceRoute } from './strings/routes/replace-route'

package/src/strings/match-text/match-text.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'vitest'
+import { matchText } from './match-text'
+
+const name = 'John'
+const data = [{ name: name }, { name: 'Jane' }]
+
+describe.each([
+  { text: 'joh', expected: [data[0]] },
+  { text: 'jane', expected: [data[1]] },
+  { text: 'jone', expected: [] },
+])('matchText: with data as array and matchFn', ({ text, expected }) => {
+  test(`returns ${JSON.stringify(expected)}`, () => {
+    expect(
+      matchText(text, data, {
+        matchFn: (data) => data.name,
+      }),
+    ).toEqual(expected)
+  })
+})
+
+describe.each([
+  { text: 'joh', expected: data[0]!.name },
+  { text: 'joh', expected: name },
+  { text: 'jah', expected: null },
+])('matchText: with simple data', ({ text, expected }) => {
+  test(`returns ${expected}`, () => {
+    expect(matchText(text, name)).toEqual(expected)
+  })
+})
+
+describe.each([{ text: 'joh', expected: [data[0]!.name] }])(
+  'matchText with data as array and without matchFn',
+  ({ text, expected }) => {
+    test(`returns ${JSON.stringify(expected)}`, () => {
+      expect(matchText(text, [data[0]!.name])).toEqual(expected)
+    })
+  },
+)

package/src/strings/match-text/match-text.ts

@@ -0,0 +1,36 @@
+import type { MatchTextOptions } from './types'
+import { normalize } from '../normalize/normalize'
+
+/**
+ * Performs intelligent text matching with optional Unicode normalization and custom matching functions.
+ *
+ * @param value - The text or RegExp pattern to match against.
+ * @param data - The data to search (array of items or a single string).
+ * @param options - Optional configuration for custom match function and normalization.
+ * @returns Matched items from an array, the original string if it matches, or `null`.
+ *
+ * @example
+ * ```ts
+ * matchText('york', ['New York', 'Los Angeles']) // ['New York']
+ * matchText('barce', locations, { matchFn: (item) => item.name })
+ * ```
+ */
+export function matchText<T>(
+  value: string | RegExp,
+  data: T[] | string,
+  { matchFn, normalizeOptions }: MatchTextOptions<T> = {},
+): T[] | string | null {
+  let regex = value
+  if (typeof value === 'string') {
+    regex = new RegExp(normalize(value.toLowerCase(), normalizeOptions), 'gi')
+  }
+
+  if (!Array.isArray(data)) {
+    return normalize(data).match(regex) ? data : null
+  }
+
+  return data.filter((match) => {
+    const newData = (matchFn ? matchFn(match) : match) as string
+    return normalize(newData).match(regex)
+  })
+}

package/src/strings/match-text/types.ts

@@ -0,0 +1,15 @@
+import type { NormalizeOptions } from '../normalize/types'
+
+/**
+ * `MatchTextOptions` is an object with an optional `matchFn` property that is a function
+ * that takes a generic type `T` and returns a string, and an optional `normalizeOptions`
+ * property that is an object with the normalize options.
+ * @property matchFn - A function that takes in the data and returns a string to match
+ * against.
+ * @property {NormalizeOptions} normalizeOptions - This is an object that contains the
+ * options for the normalize function.
+ */
+export interface MatchTextOptions<T> {
+  matchFn?: (data: T) => string
+  normalizeOptions?: NormalizeOptions
+}

package/src/strings/normalize/normalize.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'vitest'
+import { normalize } from './normalize'
+
+describe.each([
+  { text: 'test', expected: 'test' },
+  { text: 'accént', expected: 'accent' },
+  { text: 'áccént', expected: 'accent' },
+])('normalize(%s, %i)', ({ text, expected }) => {
+  test(`returns ${expected}`, () => {
+    expect(normalize(text)).toEqual(expected)
+  })
+})

package/src/strings/normalize/normalize.ts

@@ -0,0 +1,22 @@
+import type { NormalizeOptions } from './types'
+
+/**
+ * Normalizes a Unicode string by removing diacritics and special characters for consistent text comparison.
+ *
+ * @param data - The string to normalize.
+ * @param options - Normalization options including Unicode form and replacement pattern.
+ * @returns The normalized string with diacritics removed.
+ *
+ * @example
+ * ```ts
+ * normalize('café')       // 'cafe'
+ * normalize('São Paulo')  // 'Sao Paulo'
+ * ```
+ */
+export function normalize(
+  data: string,
+  { format = 'NFD', replaceUnicode = '[\u0300-\u036f]' }: NormalizeOptions = {},
+): string {
+  const unicode = new RegExp(replaceUnicode, 'g')
+  return data.normalize(format).replace(unicode, '')
+}

package/src/strings/normalize/types.ts

@@ -0,0 +1,15 @@
+/**
+ * `NormalizeOptions` is an object with optional properties `format` and `replaceUnicode`.
+ *
+ * The `format` property is a string that can be one of four values: `'NFD'`, `'NFKD'`,
+ * `'NFC'`, or `'NFKC'`.
+ *
+ * The `replaceUnicode` property is a string.
+ * @property {'NFD' | 'NFKD' | 'NFC' | 'NFKC'} format - The normalization form to use.
+ * @property {string} replaceUnicode - The unicode character to replace the unicode
+ * characters with. By default is `[\u0300-\u036f]`.
+ */
+export interface NormalizeOptions {
+  format?: 'NFD' | 'NFKD' | 'NFC' | 'NFKC'
+  replaceUnicode?: string
+}

package/src/strings/routes/replace-route.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'vitest'
+import { replaceRoute } from './replace-route'
+
+const route = '/detail/:id/:year'
+
+describe('replaceRoute: should replace route', () => {
+  test('should replace route with array', () => {
+    const result = replaceRoute(route, ['1', '2021'])
+    expect(result).toBe('/detail/1/2021')
+  })
+
+  test('should replace route with object', () => {
+    const result = replaceRoute(route, { id: '1', year: '2021' })
+    expect(result).toBe('/detail/1/2021')
+  })
+
+  test('should handle missing values in array', () => {
+    const result = replaceRoute(route, ['1'])
+    expect(result).toBe('/detail/1/')
+  })
+
+  test('should handle missing values in object', () => {
+    const result = replaceRoute(route, { id: '1' })
+    expect(result).toBe('/detail/1/')
+  })
+
+  test('should handle route with no templates', () => {
+    const result = replaceRoute('/static/path', ['1', '2'])
+    expect(result).toBe('/static/path')
+  })
+
+  test('should handle empty values', () => {
+    const result = replaceRoute(route, [])
+    expect(result).toBe('/detail//')
+  })
+
+  test('should handle undefined values', () => {
+    const result = replaceRoute(route)
+    expect(result).toBe('/detail//')
+  })
+
+  test('should handle numeric values with array', () => {
+    const result = replaceRoute(route, [123, 2024])
+    expect(result).toBe('/detail/123/2024')
+  })
+
+  test('should handle numeric values with object', () => {
+    const result = replaceRoute(route, { id: 456, year: 2025 })
+    expect(result).toBe('/detail/456/2025')
+  })
+
+  test('should handle numeric values converting to string', () => {
+    const result = replaceRoute('/user/:id', [999])
+    expect(result).toBe('/user/999')
+  })
+
+  test('should handle missing object properties', () => {
+    const result = replaceRoute('/user/:id/:name', { id: '1' } as Record<
+      string,
+      string | number
+    >)
+    expect(result).toBe('/user/1/')
+  })
+})

package/src/strings/routes/replace-route.ts

@@ -0,0 +1,39 @@
+import type { Route, Values } from './types'
+
+const regex = /:+[a-z]+/gi
+
+/**
+ * Dynamically replaces route parameters (`:paramName`) with values from an object or array.
+ *
+ * @param data - The route template string containing `:paramName` placeholders.
+ * @param values - An object or array of values to substitute into the route.
+ * @returns The route string with parameters replaced.
+ *
+ * @remarks
+ * Missing values are replaced with an empty string.
+ *
+ * @example
+ * ```ts
+ * replaceRoute('/user/:id', { id: '123' })         // '/user/123'
+ * replaceRoute('/tiles/:z/:x/:y', { z: 10, x: 512, y: 256 }) // '/tiles/10/512/256'
+ * replaceRoute('/user/:id/:name', ['123', 'john'])  // '/user/123/john'
+ * ```
+ */
+export function replaceRoute(data: Route, values: Values = []): Route {
+  let _data = data
+  const templates = _data.match(regex) ?? []
+  const isArray = Array.isArray(values)
+
+  templates.forEach((template, index) => {
+    let value
+    if (!isArray) {
+      const key = template.substring(1)
+      value = values[key]
+    } else {
+      value = values[index]
+    }
+    _data = _data.replace(template, value?.toString() ?? '')
+  })
+
+  return _data
+}

package/src/strings/routes/types.ts

@@ -0,0 +1,2 @@
+export type Route = string
+export type Values = Record<string, string | number> | (string | number)[]