@ditojs/utils 2.77.0 → 2.79.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ditojs/utils",
-  "version": "2.77.0",
+  "version": "2.79.0",
   "type": "module",
   "description": "Dito.js Utility Functions – Dito.js is a declarative and modern web framework, based on Objection.js, Koa.js and Vue.js",
   "repository": "https://github.com/ditojs/dito/tree/master/packages/utils",
@@ -39,5 +39,5 @@
   "devDependencies": {
     "typescript": "^5.9.3"
   },
-  "gitHead": "d2cff77924d989aad5ab601cf08433a4e683ac6d"
+  "gitHead": "f87ce5ce121a30830776774cd447014afef5b8ec"
 }

package/src/object/asCallback.js

@@ -0,0 +1,9 @@
+import { isString } from '../base/index.js'
+
+export function asCallback(callback) {
+  if (isString(callback)) {
+    const key = callback
+    return value => value[key]
+  }
+  return callback
+}

package/src/object/groupBy.js

@@ -1,9 +1,11 @@
 import { isArray } from '../base/index.js'
+import { asCallback } from './asCallback.js'
 
 export function groupBy(collection, callback) {
   const array = isArray(collection)
     ? collection
     : Object.values(collection)
+  callback = asCallback(callback)
   return array.reduce((groups, item) => {
     const key = callback(item)
     const group = groups[key] || (groups[key] = [])

package/src/object/groupBy.test.js

@@ -31,4 +31,40 @@ describe('groupBy()', () => {
     const actual = groupBy({ a: 6.1, b: 4.2, c: 6.3 }, Math.floor)
     expect(actual).toStrictEqual({ 4: [4.2], 6: [6.1, 6.3] })
   })
+
+  it('should support string property accessor', () => {
+    const array = [
+      { category: 'fruit', name: 'apple' },
+      { category: 'vegetable', name: 'carrot' },
+      { category: 'fruit', name: 'banana' }
+    ]
+    const actual = groupBy(array, 'category')
+    expect(actual).toStrictEqual({
+      fruit: [
+        { category: 'fruit', name: 'apple' },
+        { category: 'fruit', name: 'banana' }
+      ],
+      vegetable: [
+        { category: 'vegetable', name: 'carrot' }
+      ]
+    })
+  })
+
+  it('should group by string property with numbers', () => {
+    const array = [
+      { id: 1, value: 'a' },
+      { id: 2, value: 'b' },
+      { id: 1, value: 'c' }
+    ]
+    const actual = groupBy(array, 'id')
+    expect(actual).toStrictEqual({
+      1: [
+        { id: 1, value: 'a' },
+        { id: 1, value: 'c' }
+      ],
+      2: [
+        { id: 2, value: 'b' }
+      ]
+    })
+  })
 })

package/src/object/mapValues.js

@@ -1,4 +1,7 @@
+import { asCallback } from './asCallback.js'
+
 export function mapValues(object, callback) {
+  callback = asCallback(callback)
   return Object.keys(object).reduce((mapped, key) => {
     mapped[key] = callback(object[key], key, object)
     return mapped

package/src/object/mapValues.test.js

@@ -13,4 +13,26 @@ describe('mapValues()', () => {
     const actual = mapValues(array, String)
     expect(actual).toStrictEqual({ 0: '1', 1: '2' })
   })
+
+  it('should support string property accessor', () => {
+    const users = {
+      user1: { id: 1, name: 'Alice', email: 'alice@example.com' },
+      user2: { id: 2, name: 'Bob', email: 'bob@example.com' }
+    }
+    const actual = mapValues(users, 'email')
+    expect(actual).toStrictEqual({
+      user1: 'alice@example.com',
+      user2: 'bob@example.com'
+    })
+  })
+
+  it('should extract nested properties with string accessor', () => {
+    const data = {
+      a: { value: 10 },
+      b: { value: 20 },
+      c: { value: 30 }
+    }
+    const actual = mapValues(data, 'value')
+    expect(actual).toStrictEqual({ a: 10, b: 20, c: 30 })
+  })
 })

package/src/object/pickBy.js

@@ -1,4 +1,7 @@
+import { asCallback } from './asCallback.js'
+
 export function pickBy(object, callback) {
+  callback = asCallback(callback)
   return Object.entries(object).reduce((result, [key, value]) => {
     if (callback(value, key, object)) {
       result[key] = value

package/src/object/pickBy.test.js

@@ -6,4 +6,43 @@ describe('pickBy()', () => {
     const actual = pickBy(object, n => n === 1 || n === 3)
     expect(actual).toStrictEqual({ a: 1, c: 3 })
   })
+
+  it('should support string property accessor for truthy values', () => {
+    const users = {
+      user1: { name: 'Alice', active: true },
+      user2: { name: 'Bob', active: false },
+      user3: { name: 'Charlie', active: true }
+    }
+    const actual = pickBy(users, 'active')
+    expect(actual).toStrictEqual({
+      user1: { name: 'Alice', active: true },
+      user3: { name: 'Charlie', active: true }
+    })
+  })
+
+  it('should filter by numeric property with string accessor', () => {
+    const items = {
+      a: { score: 0 },
+      b: { score: 5 },
+      c: { score: 10 }
+    }
+    const actual = pickBy(items, 'score')
+    expect(actual).toStrictEqual({
+      b: { score: 5 },
+      c: { score: 10 }
+    })
+  })
+
+  it('should filter by string property with string accessor', () => {
+    const data = {
+      a: { label: '' },
+      b: { label: 'test' },
+      c: { label: 'value' }
+    }
+    const actual = pickBy(data, 'label')
+    expect(actual).toStrictEqual({
+      b: { label: 'test' },
+      c: { label: 'value' }
+    })
+  })
 })

package/types/index.d.ts

@@ -142,9 +142,16 @@ export function clone<T>(value: T, options?: {
  */
 export function equals(arg1: any, arg2: any): boolean
 
-// TODO: document groupBy
+/**
+ * Groups items in a collection by a key returned from the callback function,
+ * or by a property name when a string is provided.
+ */
+export function groupBy<T, K extends keyof T>(
+  collection: T[] | Record<string, T>,
+  callback: K
+): Record<string, T[]>
 export function groupBy<T, K extends string | number | symbol>(
-  list: T[],
+  collection: T[] | Record<string, T>,
   callback: (item: T) => K
 ): Record<K, T[]>
 
@@ -217,10 +224,16 @@ export function pick<ArgA, ArgB, ArgC, ArgD, ArgE>(
 export function pick(...args: any[]): any
 /**
  * Creates an object composed of the object properties predicate returns
- * truthy for.
+ * truthy for. When a string is provided, filters by the truthiness of that
+ * property on each value.
  * @param object The source object.
- * @param callback Callback invoked with three arguments: (value, key, item).
+ * @param callback Callback invoked with three arguments: (value, key, item),
+ * or a property name string to check for truthiness.
  */
+export function pickBy<T extends Dictionary<any>, K extends keyof T[keyof T]>(
+  object: T,
+  callback: K
+): Partial<T>
 export function pickBy<T extends Dictionary<any>>(
   object: T,
   callback?: (value: T[keyof T], key: keyof T, object: T) => any
@@ -231,6 +244,17 @@ export function mapKeys<T extends Dictionary<any>, K extends keyof any>(
   callback?: (key: keyof T, value: T[keyof T], object: T) => K
 ): Record<K, T[keyof T]>
 
+/**
+ * Maps the values of an object using a callback function, or extracts a
+ * property when a string is provided.
+ */
+export function mapValues<
+  T extends Dictionary<any>,
+  K extends keyof T[keyof T]
+>(
+  object: T,
+  callback: K
+): Record<keyof T, T[keyof T][K]>
 export function mapValues<T extends Dictionary<any>, K>(
   object: T,
   callback?: (value: T[keyof T], key: keyof T, object: T) => K
@@ -290,8 +314,12 @@ export function underscore(str: string): string
  */
 export function deindent(
   strings: OrArrayOf<string>,
-  ...values: Array<string>
+  ...values: Array<any>
 ): string
+/**
+ * Escapes special characters in a string for use in a regular expression.
+ */
+export function escapeRegexp(string: string): string
 /**
  * Returns the longest prefix string that is common to the supplied strings.
  */
@@ -314,6 +342,11 @@ export function isAbsoluteUrl(str: string): boolean
  * Determines whether the supplied string is a valid creditcard number.
  */
 export function isCreditCard(str: string): boolean
+/**
+ * Determines whether the supplied string is a valid domain name.
+ * Supports internationalized domain names with punycode.
+ */
+export function isDomain(str: string): boolean
 /**
  * Determines whether the supplied string is a valid email address.
  */
@@ -419,8 +452,37 @@ export function format(
     number?: boolean | NumberFormat
   }
 ): string
+/**
+ * Formats a date value as a string. If the value is not a Date,
+ * attempts to convert it to a Date first.
+ */
+export function formatDate(
+  value: any,
+  options?: {
+    /**
+     * @default 'en-US'
+     */
+    locale?: string
+    /**
+     * @default true
+     */
+    date?: boolean | DateFormat
+    /**
+     * @default true
+     */
+    time?: boolean | TimeFormat
+  }
+): string
 /* -------------------------------- function -------------------------------- */
 
+/**
+ * Logs a deprecation warning message to the console. Each unique message
+ * is only logged once.
+ *
+ * @param message The deprecation message to log.
+ */
+export function deprecate(message: string): void
+
 /**
  * Creates a debounced function that delays invoking func until after wait
  * milliseconds have elapsed since the last time the debounced function was
@@ -671,6 +733,21 @@ export function toPromiseCallback<T, R>(
 
 /* -------------------------------- dataPath -------------------------------- */
 
+/**
+ * Gets entries at a data path, supporting wildcards (* and **).
+ * Wildcard * matches direct children, ** matches recursively.
+ *
+ * @param obj The object to query.
+ * @param path The data path (supports wildcards).
+ * @param handleError Optional error handler called when path is invalid.
+ * @returns Object with normalized paths as keys and values at those paths.
+ */
+export function getEntriesAtDataPath(
+  obj: any,
+  path: OrArrayOf<string>,
+  handleError?: (obj: any, part: string, index: number) => any
+): Record<string, any>
+
 export function getValueAtDataPath(
   obj: any,
   path: OrArrayOf<string>,
@@ -681,12 +758,37 @@ export function normalizeDataPath(path: OrArrayOf<string>): string
 
 export function parseDataPath(path: OrArrayOf<string>): string
 
+/**
+ * Sets multiple values at data paths from an entries object.
+ *
+ * @param obj The object to modify.
+ * @param entries Object with data paths as keys and values to set.
+ * @returns The modified object.
+ */
+export function setDataPathEntries<O>(
+  obj: O,
+  entries: Record<string, any>
+): O
+
 export function setValueAtDataPath<O>(
   obj: O,
   path: OrArrayOf<string>,
   value: any
 ): O
 
+/* --------------------------------- class ---------------------------------- */
+
+/**
+ * Creates a mixin decorator that applies a mixin function to a class.
+ * Prevents duplicate application of the same mixin in the inheritance chain.
+ *
+ * @param mixinFunction Function that takes a class and returns a mixed class.
+ * @returns Decorator function that applies the mixin to a target class.
+ */
+export function mixin<T extends new (...args: any[]) => any>(
+  mixinFunction: (targetClass: T) => T
+): (targetClass: T) => T
+
 /* ---------------------------------- html ---------------------------------- */
 
 /**