@ditojs/utils 2.86.0 → 2.87.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@ditojs/utils",
-  "version": "2.86.0",
+  "version": "2.87.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",
+  "repository": "https://github.com/ditojs/dito/tree/main/packages/utils",
   "author": "Jürg Lehni <juerg@scratchdisk.com> (http://scratchdisk.com)",
   "license": "MIT",
   "main": "./src/index.js",
@@ -38,5 +38,5 @@
   "devDependencies": {
     "typescript": "^5.9.3"
   },
-  "gitHead": "92bc92fbb077de992fe1422adee414b8a9967c09"
+  "gitHead": "cbd05e604a1d212dfc91f9686b43bef75815a409"
 }

package/types/index.d.ts

@@ -3,6 +3,11 @@
 
 /* ---------------------------------- base ---------------------------------- */
 
+/**
+ * Re-export of `Array.isArray` as a type guard.
+ */
+export const isArray: (arg: any) => arg is any[]
+
 /**
  * Determines whether both supplied values are the same value, using the
  * SameValue algorithm.
@@ -13,12 +18,17 @@ export function is(value1: any, value2: any): boolean
 /**
  * Determines whether the supplied value is a plain object.
  */
-export function isPlainObject(arg: any): boolean
+export function isPlainObject(arg: any): arg is Record<string, unknown>
+
+/**
+ * Determines whether the supplied value is a plain `Array` instance.
+ */
+export function isPlainArray(arg: any): arg is any[]
 
 /**
  * Determines whether the supplied value is an object.
  */
-export function isObject(arg: any): boolean
+export function isObject(arg: any): arg is Record<string, unknown>
 
 /**
  * Determines whether the supplied value is a function.
@@ -40,6 +50,11 @@ export function isString(arg: any): arg is string | String
  */
 export function isBoolean(arg: any): arg is boolean
 
+/**
+ * Determines whether the supplied value is an ES module object.
+ */
+export function isModule(arg: any): boolean
+
 /**
  * Determines whether the supplied value is a Date object.
  */
@@ -58,24 +73,26 @@ export function isPromise(arg: any): arg is Promise<any>
 /**
  * Determines whether the supplied value is an integer.
  */
-export function isInteger(arg: any): boolean
+export function isInteger(arg: any): arg is number
 
 /**
  * Determines whether the supplied value is an async function.
  */
-export function isAsync(arg: any): boolean
+export function isAsync(
+  arg: any
+): arg is (...args: any[]) => Promise<any>
 
 /**
    * Determines whether the supplied value is array like, i.e. it has a length
    • property between `0` and `Number.MAX_SAFE_INTEGER` and is not a function.
    */
-export function isArrayLike(arg: any): arg is any[]
+export function isArrayLike(arg: any): arg is ArrayLike<any>
 
 /**
  * Determines whether the supplied value can be considered empty,
  * i.e. undefined, null, an empty string, or an object without properties.
  */
-export function isEmpty(o: any): boolean
+export function isEmpty(arg: any): boolean
 
 /**
  * Returns the supplied value as an object. The most frequent use case is to
@@ -84,7 +101,9 @@ export function isEmpty(o: any): boolean
  *
  * @see {@link https://2ality.com/2011/04/javascript-converting-any-value-to.html JavaScript: converting any value to an object}
  */
-export function asObject<O extends {}, T extends any>(arg: T): T & O
+export function asObject<T>(
+  arg: T
+): T extends null | undefined ? T : T & Object
 
 /**
  * Returns the supplied value as an array.
@@ -93,7 +112,9 @@ export function asObject<O extends {}, T extends any>(arg: T): T & O
  * the supplied value is undefined, an empty array is returned. Otherwise an
  * array is returned containing the supplied value as its only element.
  */
-export function asArray<T>(o: T): T extends any[] ? T : T[]
+export function asArray<T>(
+  arg: T
+): T extends any[] ? T : Exclude<T, undefined>[]
 
 /**
  * Returns the supplied value as a function.
@@ -102,7 +123,7 @@ export function asArray<T>(o: T): T extends any[] ? T : T[]
  * Otherwise a function is returned that returns the value when called.
  */
 export function asFunction<T>(
-  o: T
+  arg: T
 ): T extends Function ? T : () => T
 
 /* --------------------------------- object --------------------------------- */
@@ -132,7 +153,7 @@ export function clone<T>(value: T, options?: {
   /**
    * Optional callback to process the cloned value.
    */
-  processValue?: <S>(value: T) => S
+  processValue?: (value: T) => T | undefined | void
 }): T
 
 /**
@@ -155,7 +176,12 @@ export function groupBy<T, K extends string | number | symbol>(
   callback: (item: T) => K
 ): Record<K, T[]>
 
-// TODO: document mergeDeeply
+/**
+ * Recursively merges multiple source objects into the target object. For
+ * arrays, merges objects at the same indices and concatenates
+ * non-mergeable values. Does not override root-level values with
+ * nullish values.
+ */
 export function mergeDeeply<ArgA, ArgB>(a: ArgA, b: ArgB): ArgA & ArgB
 export function mergeDeeply<ArgA, ArgB, ArgC>(
   a: ArgA,
@@ -177,7 +203,12 @@ export function mergeDeeply<ArgA, ArgB, ArgC, ArgD, ArgE>(
 ): ArgA & ArgB & ArgC & ArgD & ArgE
 export function mergeDeeply(...args: any[]): any
 
-// TODO: document assignDeeply
+/**
+ * Recursively assigns values from source objects into the target object.
+ * Similar to `mergeDeeply` but without array concatenation — overwrites
+ * array values at the same indices instead. Does not override
+ * root-level values with nullish values.
+ */
 export function assignDeeply<ArgA, ArgB>(a: ArgA, b: ArgB): ArgA & ArgB
 export function assignDeeply<ArgA, ArgB, ArgC>(
   a: ArgA,
@@ -236,12 +267,17 @@ export function pickBy<T extends Dictionary<any>, K extends keyof T[keyof T]>(
 ): Partial<T>
 export function pickBy<T extends Dictionary<any>>(
   object: T,
-  callback?: (value: T[keyof T], key: keyof T, object: T) => any
+  callback: (value: T[keyof T], key: keyof T, object: T) => any
 ): Partial<T>
 
+/**
+ * Transforms object keys by applying a callback function to each
+ * key-value pair. Returns a new object with the transformed keys and
+ * original values.
+ */
 export function mapKeys<T extends Dictionary<any>, K extends keyof any>(
   object: T,
-  callback?: (key: keyof T, value: T[keyof T], object: T) => K
+  callback: (key: keyof T, value: T[keyof T], object: T) => K
 ): Record<K, T[keyof T]>
 
 /**
@@ -257,11 +293,20 @@ export function mapValues<
 ): 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
+  callback: (value: T[keyof T], key: keyof T, object: T) => K
 ): Record<keyof T, K>
 
 /* -------------------------------- promise -------------------------------- */
 
+/**
+ * Maps an async callback over an array with controlled concurrency.
+ * Executes all promises in parallel by default, or limits concurrent
+ * execution when the `concurrency` option is set.
+ *
+ * @param input An array or a promise that resolves to an array.
+ * @param callback Async function called for each element.
+ * @param options.concurrency Max concurrent promises (0 = unlimited).
+ */
 export function mapConcurrently<T, R>(
   input: Promise<T[]> | T[],
   callback: (value: T, index: number, array: T[]) => Promise<R> | R,
@@ -270,6 +315,13 @@ export function mapConcurrently<T, R>(
   }
 ): Promise<R[]>
 
+/**
+ * Maps an async callback over an array sequentially, waiting for each
+ * promise to resolve before processing the next element.
+ *
+ * @param input An array or a promise that resolves to an array.
+ * @param callback Async function called for each element.
+ */
 export function mapSequentially<T, R>(
   input: Promise<T[]> | T[],
   callback: (value: T, index: number) => Promise<R> | R
@@ -403,7 +455,7 @@ export interface TimeFormat {
     value: string,
     type: Intl.DateTimeFormatPartTypes,
     options: Omit<TimeFormat, 'format'>
-  ) => string
+  ) => string | undefined
 }
 
 export interface DateFormat {
@@ -426,7 +478,7 @@ export interface DateFormat {
     value: string,
     type: Intl.DateTimeFormatPartTypes,
     options: Omit<DateFormat, 'format'>
-  ) => string
+  ) => string | undefined
 }
 
 export interface NumberFormat extends Intl.NumberFormatOptions {
@@ -437,11 +489,20 @@ export interface NumberFormat extends Intl.NumberFormatOptions {
   ) => string | undefined
 }
 
+/**
+ * Default format options for number, date, and time formatting.
+ */
+export const defaultFormats: {
+  number: NumberFormat
+  date: DateFormat
+  time: TimeFormat
+}
+
 /**
  * Formats the value as a string.
  */
 export function format(
-  value: Date,
+  value: Date | string | number | null | undefined,
   options?: {
     /**
      * @default 'en-US'
@@ -450,8 +511,13 @@ export function format(
     date?: boolean | DateFormat
     time?: boolean | TimeFormat
     number?: boolean | NumberFormat
+    defaults?: {
+      number?: NumberFormat
+      date?: DateFormat
+      time?: TimeFormat
+    }
   }
-): string
+): string | null | undefined
 /**
  * Formats a date value as a string. If the value is not a Date,
  * attempts to convert it to a Date first.
@@ -472,7 +538,7 @@ export function formatDate(
      */
     time?: boolean | TimeFormat
   }
-): string
+): string | null | undefined
 /* -------------------------------- function -------------------------------- */
 
 /**
@@ -646,7 +712,7 @@ export function toCallback<T1, T2>(
 ): (arg1: T1, arg2: T2, callback: (err: any) => void) => void
 export function toCallback<T1, T2, R>(
   fn: (arg1: T1, arg2: T2) => Promise<R>
-): (arg1: T1, arg2: T2, callback: (err: any | null, result: R) => void) => void
+): (arg1: T1, arg2: T2, callback: (err: any, result: R) => void) => void
 export function toCallback<T1, T2, T3>(
   fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<void>
 ): (arg1: T1, arg2: T2, arg3: T3, callback: (err: any) => void) => void
@@ -656,7 +722,7 @@ export function toCallback<T1, T2, T3, R>(
   arg1: T1,
   arg2: T2,
   arg3: T3,
-  callback: (err: any | null, result: R) => void
+  callback: (err: any, result: R) => void
 ) => void
 export function toCallback<T1, T2, T3, T4>(
   fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>
@@ -674,7 +740,7 @@ export function toCallback<T1, T2, T3, T4, R>(
   arg2: T2,
   arg3: T3,
   arg4: T4,
-  callback: (err: any | null, result: R) => void
+  callback: (err: any, result: R) => void
 ) => void
 export function toCallback<T1, T2, T3, T4, T5>(
   fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>
@@ -694,7 +760,7 @@ export function toCallback<T1, T2, T3, T4, T5, R>(
   arg3: T3,
   arg4: T4,
   arg5: T5,
-  callback: (err: any | null, result: R) => void
+  callback: (err: any, result: R) => void
 ) => void
 export function toCallback<T1, T2, T3, T4, T5, T6>(
   fn: (
@@ -723,9 +789,18 @@ export function toCallback<T1, T2, T3, T4, T5, T6, R>(
   arg4: T4,
   arg5: T5,
   arg6: T6,
-  callback: (err: any | null, result: R) => void
+  callback: (err: any, result: R) => void
 ) => void
 
+/**
+ * Creates a Node.js-style error-first callback that resolves or rejects
+ * a promise. If the error argument is truthy, rejects the promise;
+ * otherwise resolves with the result.
+ *
+ * @param resolve Promise resolve function.
+ * @param reject Promise reject function.
+ * @returns Callback with signature `(err, res) => void`.
+ */
 export function toPromiseCallback<T, R>(
   resolve: (value: T) => void,
   reject: (reason: R) => void
@@ -741,6 +816,7 @@ export function toPromiseCallback<T, R>(
  * @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.
+ * @see {@link parseDataPath} for supported path formats.
  */
 export function getEntriesAtDataPath(
   obj: any,
@@ -748,15 +824,40 @@ export function getEntriesAtDataPath(
   handleError?: (obj: any, part: string, index: number) => any
 ): Record<string, any>
 
+/**
+ * Retrieves a value from a nested object or array at a given path.
+ * Supports property access notation (`obj.arr[0].prop`), JSON pointers
+ * (`/obj/arr/0/prop`), and wildcard matching (`*` for shallow, `**`
+ * for deep recursive).
+ *
+ * @param obj The object or array to retrieve from.
+ * @param path The data path (multiple formats supported).
+ * @param handleError Optional error handler called when the path is
+ * invalid, with `(obj, part, index)`.
+ * @see {@link parseDataPath} for supported path formats.
+ */
 export function getValueAtDataPath(
   obj: any,
   path: OrArrayOf<string>,
-  handleError?: (obj: any, part: string, index: number) => void
+  handleError?: (obj: any, part: string, index: number) => any
 ): any
 
+/**
+ * Normalizes a data path to a standard format using forward slashes.
+ * Converts property access notation, JSON pointers, and relative paths
+ * to normalized relative path format. Resolves relative tokens (`..`
+ * and `.`).
+ * @see {@link parseDataPath} for supported path formats.
+ */
 export function normalizeDataPath(path: OrArrayOf<string>): string
 
-export function parseDataPath(path: OrArrayOf<string>): string
+/**
+ * Parses a data path string or array into an array of path segments.
+ * Supports property access notation (`obj.arr[0].prop`), JSON pointers
+ * (`/obj/arr/0/prop`), and relative paths. Always returns a new array
+ * to prevent mutation.
+ */
+export function parseDataPath(path: OrArrayOf<string>): string[]
 
 /**
  * Sets multiple values at data paths from an entries object.
@@ -764,12 +865,24 @@ export function parseDataPath(path: OrArrayOf<string>): string
  * @param obj The object to modify.
  * @param entries Object with data paths as keys and values to set.
  * @returns The modified object.
+ * @see {@link parseDataPath} for supported path formats.
  */
 export function setDataPathEntries<O>(
   obj: O,
   entries: Record<string, any>
 ): O
 
+/**
+ * Sets a value in a nested object or array at a given path. Parses the
+ * path, navigates to the parent location, and assigns the value.
+ * Mutates the original object.
+ *
+ * @param obj The object or array to set the value on.
+ * @param path The data path to the target location.
+ * @param value The value to set.
+ * @returns The modified object.
+ * @see {@link parseDataPath} for supported path formats.
+ */
 export function setValueAtDataPath<O>(
   obj: O,
   path: OrArrayOf<string>,
@@ -792,19 +905,19 @@ export function mixin<T extends new (...args: any[]) => any>(
 /* ---------------------------------- html ---------------------------------- */
 
 /**
-   * Escapes quotes, ampersands, and smaller/greater than signs (`&<>'"`).
+   * Escapes double quotes, ampersands, and angle brackets (`"&<>`).
 
    * @param html The html to escape.
    * @returns The newly escaped html.
    */
-export function escapeHtml(html: string): string
+export function escapeHtml(html: string | null | undefined): string
 
 /**
  * Strips HTML tags from the string.
  * @param html The string to strip.
  * @returns The newly stripped string.
  */
-export function stripHtml(html: string): string
+export function stripHtml(html: string | null | undefined): string
 
 /**
  * Strips HTML tags from the string.
@@ -812,12 +925,9 @@ export function stripHtml(html: string): string
  * @returns The newly stripped string.
  * @deprecated Use stripHtml() instead
  */
-export function stripTags(html: string): string
+export function stripTags(html: string | null | undefined): string
 
 /* -------------------------- typescript utilities -------------------------- */
-type PropertyName = string | number | symbol
-type NotVoid = {} | null | undefined
-type List<T> = ArrayLike<T>
 export interface ArrayLike<T> {
   readonly length: number
   readonly [n: number]: T

package/types/tests/base.test-d.ts

@@ -0,0 +1,172 @@
+import { assertType, describe, expectTypeOf, it } from 'vitest'
+import type {
+  isArray,
+  isPlainObject,
+  isFunction,
+  isNumber,
+  isString,
+  isBoolean,
+  isDate,
+  isRegExp,
+  isPromise,
+  isAsync,
+  isArrayLike,
+  asObject,
+  asArray,
+  asFunction
+} from '../index.d.ts'
+
+describe('type guards', () => {
+  it('isArray narrows unknown to any[]', () => {
+    const guard = {} as typeof isArray
+    const val: unknown = []
+    if (guard(val)) {
+      expectTypeOf(val).toEqualTypeOf<any[]>()
+    }
+  })
+
+  it('isPlainObject narrows union to record', () => {
+    const guard = {} as typeof isPlainObject
+    const val: string | Record<string, unknown> = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      expectTypeOf(val).toEqualTypeOf<Record<string, unknown>>()
+    }
+  })
+
+  it('isFunction narrows to callable', () => {
+    const guard = {} as typeof isFunction
+    const val: string | (() => void) = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      expectTypeOf(val).toBeCallableWith()
+    }
+  })
+
+  it('isNumber narrows union', () => {
+    const guard = {} as typeof isNumber
+    const val: string | number = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      expectTypeOf(val).toBeNumber()
+    }
+  })
+
+  it('isString narrows union', () => {
+    const guard = {} as typeof isString
+    const val: number | string = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      assertType<string | String>(val)
+    }
+  })
+
+  it('isBoolean narrows union', () => {
+    const guard = {} as typeof isBoolean
+    const val: string | boolean = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      expectTypeOf(val).toBeBoolean()
+    }
+  })
+
+  it('isDate narrows to Date', () => {
+    const guard = {} as typeof isDate
+    const val: string | Date = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      expectTypeOf(val).toEqualTypeOf<Date>()
+    }
+  })
+
+  it('isRegExp narrows to RegExp', () => {
+    const guard = {} as typeof isRegExp
+    const val: string | RegExp = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      expectTypeOf(val).toEqualTypeOf<RegExp>()
+    }
+  })
+
+  it('isPromise narrows to Promise', () => {
+    const guard = {} as typeof isPromise
+    const val: string | Promise<number> = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      assertType<Promise<any>>(val)
+    }
+  })
+
+  it('isAsync narrows to async function', () => {
+    const guard = {} as typeof isAsync
+    const val: (() => void) | (() => Promise<string>) = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      assertType<(...args: any[]) => Promise<any>>(val)
+    }
+  })
+
+  it('isArrayLike narrows to ArrayLike', () => {
+    const guard = {} as typeof isArrayLike
+    const val: string | ArrayLike<number> = {} as any
+    if (guard(val)) {
+      expectTypeOf(val).not.toBeAny()
+      expectTypeOf(val).toHaveProperty('length')
+    }
+  })
+})
+
+describe('asObject', () => {
+  it('preserves object types', () => {
+    const fn = {} as typeof asObject
+    const obj = { a: 1 }
+    const result = fn(obj)
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toHaveProperty('a')
+  })
+
+  it('returns null/undefined as-is', () => {
+    const fn = {} as typeof asObject
+    expectTypeOf(fn(null)).toBeNull()
+    expectTypeOf(fn(undefined)).toBeUndefined()
+  })
+})
+
+describe('asArray', () => {
+  it('passes arrays through unchanged', () => {
+    const fn = {} as typeof asArray
+    const arr = [1, 2, 3]
+    const result = fn(arr)
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<number[]>()
+  })
+
+  it('wraps non-array in array', () => {
+    const fn = {} as typeof asArray
+    const result = fn('hello')
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<string[]>()
+  })
+
+  it('returns empty array for undefined', () => {
+    const fn = {} as typeof asArray
+    expectTypeOf(fn(undefined)).toEqualTypeOf<never[]>()
+  })
+})
+
+describe('asFunction', () => {
+  it('passes functions through unchanged', () => {
+    const fn = {} as typeof asFunction
+    const cb = (x: number) => x * 2
+    const result = fn(cb)
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<(x: number) => number>()
+  })
+
+  it('wraps non-function in thunk', () => {
+    const fn = {} as typeof asFunction
+    const result = fn(42)
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<() => number>()
+  })
+})

package/types/tests/datapath.test-d.ts

@@ -0,0 +1,75 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import type {
+  getValueAtDataPath,
+  getEntriesAtDataPath,
+  setValueAtDataPath,
+  setDataPathEntries,
+  normalizeDataPath,
+  parseDataPath
+} from '../index.d.ts'
+
+describe('getValueAtDataPath', () => {
+  it('error handler receives correct params', () => {
+    const fn = {} as typeof getValueAtDataPath
+    fn({}, 'a.b', (obj, part, index) => {
+      expectTypeOf(part).not.toBeAny()
+      expectTypeOf(part).toBeString()
+      expectTypeOf(index).not.toBeAny()
+      expectTypeOf(index).toBeNumber()
+    })
+  })
+})
+
+describe('getEntriesAtDataPath', () => {
+  it('error handler receives correct params', () => {
+    const fn = {} as typeof getEntriesAtDataPath
+    fn({}, 'items.*', (obj, part, index) => {
+      expectTypeOf(part).not.toBeAny()
+      expectTypeOf(part).toBeString()
+      expectTypeOf(index).not.toBeAny()
+      expectTypeOf(index).toBeNumber()
+    })
+  })
+})
+
+describe('setValueAtDataPath', () => {
+  it('preserves the object type', () => {
+    const fn = {} as typeof setValueAtDataPath
+    const obj = { a: { b: 1 } }
+    const result = fn(obj, 'a.b', 2)
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<typeof obj>()
+  })
+})
+
+describe('setDataPathEntries', () => {
+  it('preserves the object type', () => {
+    const fn = {} as typeof setDataPathEntries
+    const obj = { x: 1, y: 2 }
+    const result = fn(obj, { x: 10 })
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<typeof obj>()
+  })
+})
+
+describe('parseDataPath', () => {
+  it('returns string array from string or array input', () => {
+    const fn = {} as typeof parseDataPath
+    const fromString = fn('a.b.c')
+    const fromArray = fn(['a', 'b'])
+    expectTypeOf(fromString).not.toBeAny()
+    expectTypeOf(fromString).toEqualTypeOf<string[]>()
+    expectTypeOf(fromArray).toEqualTypeOf<string[]>()
+  })
+})
+
+describe('normalizeDataPath', () => {
+  it('returns string from string or array input', () => {
+    const fn = {} as typeof normalizeDataPath
+    const fromString = fn('a.b')
+    const fromArray = fn(['a', 'b'])
+    expectTypeOf(fromString).not.toBeAny()
+    expectTypeOf(fromString).toBeString()
+    expectTypeOf(fromArray).toBeString()
+  })
+})

package/types/tests/function.test-d.ts

@@ -0,0 +1,137 @@
+import { assertType, describe, expectTypeOf, it } from 'vitest'
+import type {
+  debounce,
+  debounceAsync,
+  toAsync,
+  toCallback,
+  toPromiseCallback
+} from '../index.d.ts'
+
+describe('debounce', () => {
+  it('preserves original function signature', () => {
+    const fn = {} as typeof debounce
+    const original = (x: number, y: string) => x + y.length
+    const debounced = fn(original, 100)
+    expectTypeOf(debounced).not.toBeAny()
+    expectTypeOf(debounced).toBeCallableWith(1, 'hello')
+    expectTypeOf(debounced(1, 'a')).toBeNumber()
+  })
+
+  it('adds cancel method', () => {
+    const fn = {} as typeof debounce
+    const debounced = fn(() => {}, 100)
+    expectTypeOf(debounced.cancel).not.toBeAny()
+    expectTypeOf(debounced.cancel).toBeFunction()
+    expectTypeOf(debounced.cancel()).toBeBoolean()
+  })
+
+  it('accepts options object', () => {
+    const fn = {} as typeof debounce
+    fn((x: number) => x, { delay: 100, immediate: true })
+  })
+
+  it('rejects wrong argument types', () => {
+    const fn = {} as typeof debounce
+    const debounced = fn((x: number) => x, 100)
+    // @ts-expect-error - string not assignable to number
+    debounced('wrong')
+  })
+})
+
+describe('debounceAsync', () => {
+  it('preserves async function signature', () => {
+    const fn = {} as typeof debounceAsync
+    const original = async (id: number) => ({
+      id,
+      name: 'test'
+    })
+    const debounced = fn(original, 200)
+    expectTypeOf(debounced).not.toBeAny()
+    expectTypeOf(debounced).toBeCallableWith(1)
+    expectTypeOf(debounced(1))
+      .resolves.toHaveProperty('name')
+  })
+})
+
+describe('toAsync', () => {
+  it('converts error-first callback to promise', () => {
+    const fn = {} as typeof toAsync
+    const readFile = (
+      path: string,
+      cb: (err: any, data: Buffer) => void
+    ) => {}
+    const asyncReadFile = fn(readFile)
+    expectTypeOf(asyncReadFile).not.toBeAny()
+    expectTypeOf(asyncReadFile).toBeCallableWith('test.txt')
+    expectTypeOf(asyncReadFile('x'))
+      .resolves.toEqualTypeOf<Buffer>()
+  })
+
+  it('converts void callback to promise', () => {
+    const fn = {} as typeof toAsync
+    const doThing = (cb: (err?: any) => void) => {}
+    const asyncDoThing = fn(doThing)
+    expectTypeOf(asyncDoThing).not.toBeAny()
+    expectTypeOf(asyncDoThing())
+      .resolves.toEqualTypeOf<void>()
+  })
+
+  it('handles multiple arguments', () => {
+    const fn = {} as typeof toAsync
+    const write = (
+      path: string,
+      data: string,
+      cb: (err: any, written: number) => void
+    ) => {}
+    const asyncWrite = fn(write)
+    expectTypeOf(asyncWrite).not.toBeAny()
+    expectTypeOf(asyncWrite).toBeCallableWith('f', 'data')
+    expectTypeOf(asyncWrite('f', 'd'))
+      .resolves.toBeNumber()
+  })
+})
+
+describe('toCallback', () => {
+  it('converts async fn to callback style', () => {
+    const fn = {} as typeof toCallback
+    const asyncFn = async (x: number): Promise<string> => `${x}`
+    const cbFn = fn(asyncFn)
+    expectTypeOf(cbFn).not.toBeAny()
+    expectTypeOf(cbFn).toBeCallableWith(
+      42,
+      (err: any, result: string) => {}
+    )
+  })
+
+  it('handles void return', () => {
+    const fn = {} as typeof toCallback
+    const asyncFn = async (x: string): Promise<void> => {}
+    const cbFn = fn(asyncFn)
+    expectTypeOf(cbFn).not.toBeAny()
+    expectTypeOf(cbFn).toBeCallableWith(
+      'hello',
+      (err: any) => {}
+    )
+  })
+})
+
+describe('toPromiseCallback', () => {
+  it('returns callback matching resolve/reject types', () => {
+    const fn = {} as typeof toPromiseCallback
+    const cb = fn<string, Error>(
+      value => {
+        expectTypeOf(value).not.toBeAny()
+        expectTypeOf(value).toBeString()
+      },
+      reason => {
+        expectTypeOf(reason).not.toBeAny()
+        expectTypeOf(reason).toEqualTypeOf<Error>()
+      }
+    )
+    expectTypeOf(cb).not.toBeAny()
+    expectTypeOf(cb).toBeCallableWith(
+      new Error(),
+      'result'
+    )
+  })
+})

package/types/tests/object.test-d.ts

@@ -0,0 +1,190 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import type {
+  clone,
+  groupBy,
+  mergeDeeply,
+  assignDeeply,
+  pick,
+  pickBy,
+  mapKeys,
+  mapValues
+} from '../index.d.ts'
+
+describe('clone', () => {
+  it('preserves the input type', () => {
+    const fn = {} as typeof clone
+    const obj = { a: 1, b: 'hello' }
+    const result = fn(obj)
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<typeof obj>()
+  })
+
+  it('processValue callback receives correct type', () => {
+    const fn = {} as typeof clone
+    fn(
+      { x: 1 },
+      {
+        processValue(value) {
+          expectTypeOf(value).not.toBeAny()
+          expectTypeOf(value).toEqualTypeOf<{ x: number }>()
+          return value
+        }
+      }
+    )
+  })
+})
+
+describe('groupBy', () => {
+  it('infers callback param type from array', () => {
+    const fn = {} as typeof groupBy
+    const items = [
+      { name: 'a', category: 'x' },
+      { name: 'b', category: 'y' }
+    ]
+    fn(items, item => {
+      expectTypeOf(item).not.toBeAny()
+      expectTypeOf(item).toEqualTypeOf<{
+        name: string
+        category: string
+      }>()
+      return item.category
+    })
+  })
+
+  it('accepts property key shorthand', () => {
+    const fn = {} as typeof groupBy
+    const items = [{ type: 'a' as const, v: 1 }]
+    const result = fn(items, 'type')
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<
+      Record<string, { type: 'a'; v: number }[]>
+    >()
+  })
+
+  it('works with record input', () => {
+    const fn = {} as typeof groupBy
+    const obj: Record<string, { group: string }> = {}
+    fn(obj, item => {
+      expectTypeOf(item).not.toBeAny()
+      expectTypeOf(item).toEqualTypeOf<{ group: string }>()
+      return item.group
+    })
+  })
+})
+
+describe('mergeDeeply', () => {
+  it('produces intersection of two args', () => {
+    const fn = {} as typeof mergeDeeply
+    const result = fn(
+      {} as { a: number },
+      {} as { b: string }
+    )
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toHaveProperty('a')
+    expectTypeOf(result).toHaveProperty('b')
+  })
+
+  it('produces intersection of three args', () => {
+    const fn = {} as typeof mergeDeeply
+    const result = fn(
+      {} as { a: number },
+      {} as { b: string },
+      {} as { c: boolean }
+    )
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toHaveProperty('a')
+    expectTypeOf(result).toHaveProperty('b')
+    expectTypeOf(result).toHaveProperty('c')
+  })
+})
+
+describe('assignDeeply', () => {
+  it('produces intersection of two args', () => {
+    const fn = {} as typeof assignDeeply
+    const result = fn(
+      {} as { a: number },
+      {} as { b: string }
+    )
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toHaveProperty('a')
+    expectTypeOf(result).toHaveProperty('b')
+  })
+})
+
+describe('pick', () => {
+  it('returns union of argument types', () => {
+    const fn = {} as typeof pick
+    const result = fn(
+      {} as number | undefined,
+      {} as string
+    )
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<number | undefined | string>()
+  })
+})
+
+describe('pickBy', () => {
+  it('callback receives value, key, and object', () => {
+    const fn = {} as typeof pickBy
+    const obj: Record<string, number> = {}
+    fn(obj, (value, key, source) => {
+      expectTypeOf(value).not.toBeAny()
+      expectTypeOf(value).toBeNumber()
+      expectTypeOf(key).toBeString()
+      expectTypeOf(source).toEqualTypeOf(obj)
+      return value > 1
+    })
+  })
+
+  it('returns partial of input type', () => {
+    const fn = {} as typeof pickBy
+    const obj = {} as { a: number; b: number }
+    const result = fn(obj, () => true)
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<Partial<{ a: number; b: number }>>()
+  })
+})
+
+describe('mapKeys', () => {
+  it('callback receives key, value, and object', () => {
+    const fn = {} as typeof mapKeys
+    const obj: Record<string, number> = {}
+    fn(obj, (key, value, source) => {
+      expectTypeOf(value).not.toBeAny()
+      expectTypeOf(key).toBeString()
+      expectTypeOf(value).toBeNumber()
+      expectTypeOf(source).toEqualTypeOf(obj)
+      return `prefix_${key}`
+    })
+  })
+})
+
+describe('mapValues', () => {
+  it('callback receives value, key, and object', () => {
+    const fn = {} as typeof mapValues
+    const obj: Record<string, number> = {}
+    fn(obj, (value, key, source) => {
+      expectTypeOf(value).not.toBeAny()
+      expectTypeOf(value).toBeNumber()
+      expectTypeOf(key).toBeString()
+      expectTypeOf(source).toEqualTypeOf(obj)
+      return String(value)
+    })
+  })
+
+  it('result values match callback return type', () => {
+    const fn = {} as typeof mapValues
+    const obj: Record<string, number> = {}
+    const result = fn(obj, value => String(value))
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<Record<string, string>>()
+  })
+
+  it('property shorthand extracts nested value', () => {
+    const fn = {} as typeof mapValues
+    const obj: Record<string, { nested: number }> = {}
+    const result = fn(obj, 'nested')
+    expectTypeOf(result).not.toBeAny()
+    expectTypeOf(result).toEqualTypeOf<Record<string, number>>()
+  })
+})

package/types/tests/promise.test-d.ts

@@ -0,0 +1,66 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import type { mapConcurrently, mapSequentially } from '../index.d.ts'
+
+describe('mapConcurrently', () => {
+  it('infers callback param from input array type', () => {
+    const fn = {} as typeof mapConcurrently
+    fn([1, 2, 3], async (value, index, array) => {
+      expectTypeOf(value).not.toBeAny()
+      expectTypeOf(value).toBeNumber()
+      expectTypeOf(index).toBeNumber()
+      expectTypeOf(array).toEqualTypeOf<number[]>()
+      return String(value)
+    })
+  })
+
+  it('result type matches callback return', () => {
+    const fn = {} as typeof mapConcurrently
+    const result = fn(
+      [1, 2],
+      async value => ({ doubled: value * 2 })
+    )
+    expectTypeOf(result)
+      .resolves.items.not.toBeAny()
+    expectTypeOf(result)
+      .resolves.items.toEqualTypeOf<{ doubled: number }>()
+  })
+
+  it('accepts promise input', () => {
+    const fn = {} as typeof mapConcurrently
+    const input = Promise.resolve(['a', 'b'])
+    fn(input, async value => {
+      expectTypeOf(value).not.toBeAny()
+      expectTypeOf(value).toBeString()
+      return value.length
+    })
+  })
+
+  it('accepts synchronous callback', () => {
+    const fn = {} as typeof mapConcurrently
+    const result = fn([1, 2], value => `${value}`)
+    expectTypeOf(result).resolves.items.not.toBeAny()
+    expectTypeOf(result).resolves.items.toBeString()
+  })
+})
+
+describe('mapSequentially', () => {
+  it('infers callback param from input array type', () => {
+    const fn = {} as typeof mapSequentially
+    fn(['a', 'b'], async (value, index) => {
+      expectTypeOf(value).not.toBeAny()
+      expectTypeOf(value).toBeString()
+      expectTypeOf(index).toBeNumber()
+      return value.length
+    })
+  })
+
+  it('result type matches callback return', () => {
+    const fn = {} as typeof mapSequentially
+    const result = fn(
+      [{ id: 1 }],
+      async item => item.id
+    )
+    expectTypeOf(result).resolves.items.not.toBeAny()
+    expectTypeOf(result).resolves.items.toBeNumber()
+  })
+})