@radio-garden/ditojs-utils 2.85.0-0.5067ad799

package/types/index.d.ts

@@ -0,0 +1,939 @@
+// Type definitions for Dito.js utils
+// Project: <https://github.com/ditojs/dito/>
+
+/* ---------------------------------- 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.
+ * @see {@link http://ecma-international.org/ecma-262/5.1/#sec-9.12 The SameValue Algorithm}
+ */
+export function is(value1: any, value2: any): boolean
+
+/**
+ * Determines whether the supplied value is a plain object.
+ */
+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): arg is Record<string, unknown>
+
+/**
+ * Determines whether the supplied value is a function.
+ */
+export function isFunction(arg: any): arg is (...args: any[]) => any
+
+/**
+ * Determines whether the supplied value is a number.
+ */
+export function isNumber(arg: any): arg is number
+
+/**
+ * Determines whether the supplied value is a string.
+ */
+export function isString(arg: any): arg is string | String
+
+/**
+ * Determines whether the supplied value is a boolean.
+ */
+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.
+ */
+export function isDate(arg: any): arg is Date
+
+/**
+ * Determines whether the supplied value is a regular expression (RegExp).
+ */
+export function isRegExp(arg: any): arg is RegExp
+
+/**
+ * Determines whether the supplied value is a Promise.
+ */
+export function isPromise(arg: any): arg is Promise<any>
+
+/**
+ * Determines whether the supplied value is an integer.
+ */
+export function isInteger(arg: any): arg is number
+
+/**
+ * Determines whether the supplied value is an async function.
+ */
+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 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(arg: any): boolean
+
+/**
+ * Returns the supplied value as an object. The most frequent use case is to
+ * add properties to a primitive. As primitives are immutable, they need to be
+ * converted to an object in order to do so.
+ *
+ * @see {@link https://2ality.com/2011/04/javascript-converting-any-value-to.html JavaScript: converting any value to an object}
+ */
+export function asObject<T>(
+  arg: T
+): T extends null | undefined ? T : T & Object
+
+/**
+ * Returns the supplied value as an array.
+ *
+ * When the supplied value is an array, the original array is returned. When
+ * 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>(
+  arg: T
+): T extends any[] ? T : Exclude<T, undefined>[]
+
+/**
+ * Returns the supplied value as a function.
+ *
+ * When the supplied value is a function, the original function is returned.
+ * Otherwise a function is returned that returns the value when called.
+ */
+export function asFunction<T>(
+  arg: T
+): T extends Function ? T : () => T
+
+/* --------------------------------- object --------------------------------- */
+
+/**
+ * Clones the supplied value.
+ */
+export function clone<T>(value: T, options?: {
+  /**
+   * Whether to clone the value shallowly.
+   *
+   * @default false
+   */
+  shallow?: boolean
+  /**
+   * Whether to clone all object properties, or only those that are defined
+   * directly on that object, and are not inherited from the object's prototype.
+   *
+   * @default true
+   */
+  enumerable?: boolean
+  /**
+   * @default `true` if `options.enumerable` is true, `false` otherwise
+   */
+  descriptors?: boolean
+  transferables?: any[]
+  /**
+   * Optional callback to process the cloned value.
+   */
+  processValue?: (value: T) => T | undefined | void
+}): T
+
+/**
+ * Determines whether the supplied values can be considered equal through
+ * recursive comparison of object properties and array elements. Non-objects
+ * and non-arrays are compared using the SameValue algorithm.
+ */
+export function equals(arg1: any, arg2: any): boolean
+
+/**
+ * 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>(
+  collection: T[] | Record<string, T>,
+  callback: (item: T) => K
+): Record<K, T[]>
+
+/**
+ * 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,
+  b: ArgB,
+  c: ArgC
+): ArgA & ArgB & ArgC
+export function mergeDeeply<ArgA, ArgB, ArgC, ArgD>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD
+): ArgA & ArgB & ArgC & ArgD
+export function mergeDeeply<ArgA, ArgB, ArgC, ArgD, ArgE>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD,
+  e: ArgE
+): ArgA & ArgB & ArgC & ArgD & ArgE
+export function mergeDeeply(...args: any[]): any
+
+/**
+ * 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,
+  b: ArgB,
+  c: ArgC
+): ArgA & ArgB & ArgC
+export function assignDeeply<ArgA, ArgB, ArgC, ArgD>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD
+): ArgA & ArgB & ArgC & ArgD
+export function assignDeeply<ArgA, ArgB, ArgC, ArgD, ArgE>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD,
+  e: ArgE
+): ArgA & ArgB & ArgC & ArgD & ArgE
+export function assignDeeply(...args: any[]): any
+
+/**
+ * Returns the first argument which is not undefined.
+ */
+export function pick<ArgA, ArgB>(a: ArgA, b: ArgB): ArgA | ArgB
+export function pick<ArgA, ArgB, ArgC>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC
+): ArgA | ArgB | ArgC
+export function pick<ArgA, ArgB, ArgC, ArgD>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD
+): ArgA | ArgB | ArgC | ArgD
+export function pick<ArgA, ArgB, ArgC, ArgD, ArgE>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD,
+  e: ArgE
+): ArgA | ArgB | ArgC | ArgD | ArgE
+export function pick(...args: any[]): any
+/**
+ * Creates an object composed of the object properties predicate returns
+ * 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),
+ * 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
+): 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
+): 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
+): 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,
+  options?: {
+    concurrency?: number
+  }
+): 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
+): Promise<R[]>
+
+/* --------------------------------- string --------------------------------- */
+
+/**
+ * Converts a string separated by spaces, dashes and underscores to camel-case
+ * (`'camelCase'`) or optionally pascal-case (`'CamelCase'`).
+ */
+export function camelize(str: string, pascalCase?: boolean): string
+/**
+ * Capitalizes words in a string.
+ */
+export function capitalize(str: string): string
+/**
+ * Convert a string from camel-case to a string separated by spaces or a
+ * supplied separator string.
+ *
+ * @param str The string to decamelize.
+ * @param {string} [sep=' '] -  The string to separate the decamelized words
+ * with.
+ */
+export function decamelize(str: string, sep?: string): string
+/**
+ * Converts a camelized string to a string separated by dashes.
+ */
+export function hyphenate(str: string): string
+/**
+ * Converts a camelized string to a string separated by underscores.
+ */
+export function underscore(str: string): string
+/**
+ * ES6 string tag that strips indentation from multi-line strings.
+ *
+ * @example
+ * const str = deindent`Such a long string that you need to break it
+ *                      over multiple lines. Such a long string that
+ *                      you need to break it over multiple lines.`
+ * console.log(str)
+ */
+export function deindent(
+  strings: OrArrayOf<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.
+ */
+export function getCommonPrefix(...strings: Array<string>): string
+/**
+ * Returns the offset of the longest prefix string that is common to the
+ * supplied strings.
+ */
+export function getCommonOffset(...strings: Array<string>): number
+/**
+ * Determines whether the supplied string is an absolute url.
+ *
+ * A URL is considered absolute if it begins with "<scheme>://" or "//"
+ * (protocol-relative URL).  RFC 3986 defines scheme name as a sequence of
+ * characters beginning with a letter and followed by any combination of
+ * letters, digits, plus, period, or hyphen.
+ */
+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.
+ */
+export function isEmail(str: string): boolean
+/**
+ * Determines whether the string is a valid hostname.
+ */
+export function isHostname(str: string): boolean
+/**
+ * Determines whether the string is a valid url.
+ */
+export function isUrl(str: string): boolean
+/**
+ * Expands hyphenated, underscored and camel-cased strings to title case.
+ */
+export function labelize(str: string | undefined): string
+
+/* ---------------------------------- array --------------------------------- */
+
+/**
+ * Recursively flattens a nested array.
+ *
+ * @param array The array to recursively flatten.
+ * @param [maxDepth] The maximum recursion depth.
+ * @return Returns the new flattened array.
+ */
+export function flatten<T>(array: RecursiveArray<T>, maxDepth?: number): T[]
+
+/**
+ * Shuffle an array using the Fisher-Yates (aka Knuth) Shuffle.
+ *
+ * @param array The array to shuffle.
+ * @returns Returns the newly shuffled array.
+ */
+export function shuffle<T>(array: T[]): T[]
+
+/* ---------------------------------- date ---------------------------------- */
+
+export interface TimeFormat {
+  /**
+   * @defaultValue `'2-digit'`
+   */
+  hour?: boolean | 'numeric' | '2-digit'
+  /**
+   * @defaultValue `'2-digit'`
+   */
+  minute?: boolean | 'numeric' | '2-digit'
+  /**
+   * @defaultValue `'2-digit'`
+   */
+  second?: boolean | 'numeric' | '2-digit'
+
+  format?: (
+    value: string,
+    type: Intl.DateTimeFormatPartTypes,
+    options: Omit<TimeFormat, 'format'>
+  ) => string | undefined
+}
+
+export interface DateFormat {
+  /**
+   * @defaultValue `'numeric'`
+   */
+  day?: boolean | 'numeric' | '2-digit'
+  /**
+   * @defaultValue `'long'`
+   */
+  month?: boolean | 'numeric' | '2-digit' | 'long' | 'short' | 'narrow'
+  /**
+   * @defaultValue `'numeric'`
+   */
+  year?: boolean | 'numeric' | '2-digit'
+  /**
+   * Format date in a custom way.
+   */
+  format?: (
+    value: string,
+    type: Intl.DateTimeFormatPartTypes,
+    options: Omit<DateFormat, 'format'>
+  ) => string | undefined
+}
+
+export interface NumberFormat extends Intl.NumberFormatOptions {
+  format?: (
+    value: string,
+    type: Intl.NumberFormatPartTypes,
+    options: 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 | string | number | null | undefined,
+  options?: {
+    /**
+     * @default 'en-US'
+     */
+    locale?: string
+    date?: boolean | DateFormat
+    time?: boolean | TimeFormat
+    number?: boolean | NumberFormat
+    defaults?: {
+      number?: NumberFormat
+      date?: DateFormat
+      time?: TimeFormat
+    }
+  }
+): 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.
+ */
+export function formatDate(
+  value: any,
+  options?: {
+    /**
+     * @default 'en-US'
+     */
+    locale?: string
+    /**
+     * @default true
+     */
+    date?: boolean | DateFormat
+    /**
+     * @default true
+     */
+    time?: boolean | TimeFormat
+  }
+): string | null | undefined
+/* -------------------------------- 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
+ * invoked. The debounced function comes with a cancel method to cancel
+ * delayed invocations. Provide an options object to indicate that func
+ * should be invoked on the leading edge of the wait timeout. Subsequent
+ * calls to the debounced function return the result of the last func
+ * invocation.
+ *
+ * @param func The function to debounce.
+ * @param options The options object or the number of milliseconds to delay.
+ * @param options.delay The number of milliseconds to delay.
+ * @param options.immediate Specify invoking on the leading edge of the timeout.
+ * @return Returns the new debounced function.
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  options:
+    | number
+    | {
+        delay: number
+        immediate?: boolean
+      }
+): T & { cancel: () => boolean }
+
+/**
+ * Creates a debounced function that delays invoking func until after wait
+ * milliseconds have elapsed since the last time the debounced function was
+ * invoked.
+ *
+ * Each time the debounced function is called, it returns a promise
+ * which will resolve to the value that the debounced async function resolves
+ * to. If the async function throws an error, the last waiting promise is
+ * rejected and all others are resolved with undefined.
+ *
+ * The debounced function comes with a cancel method to cancel
+ * delayed invocations. Provide an options object to indicate that func
+ * should be invoked on the leading edge of the wait timeout.
+ *
+ * @param func The function to debounce.
+ * @param options The options object or the number of milliseconds to delay.
+ * @param options.delay The number of milliseconds to delay.
+ * @param options.immediate Specify invoking on the leading edge of the timeout.
+ * @return Returns the new debounced function.
+ */
+export function debounceAsync<T extends (...args: any[]) => Promise<any>>(
+  func: T,
+  options:
+    | number
+    | {
+        delay: number
+        immediate?: boolean
+      }
+): T & { cancel: () => boolean }
+
+// Adjusted version of @types/node's promisify (which includes support for
+// overloaded node function types), excluding the custom promisified function
+// functionality, which toAsync does not support:
+// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/fa723dee727e433add7e700420523f0f90e87a01/types/node/util.d.ts#L86
+interface CustomPromisifyLegacy<TCustom extends Function> extends Function {
+  __promisify__: TCustom
+}
+type CustomToAsync<TCustom extends Function> = CustomPromisifyLegacy<TCustom>
+/**
+ * Takes a function following the common error-first callback style, i.e.
+ * taking an (err, value) => ... callback as the last argument, and returns a
+ * version that returns promises.
+ *
+ * @param fn function following the error-first callback style
+ */
+export function toAsync<TCustom extends Function>(
+  fn: CustomToAsync<TCustom>
+): TCustom
+export function toAsync<R>(
+  fn: (callback: (err: any, result: R) => void) => void
+): () => Promise<R>
+export function toAsync(
+  fn: (callback: (err?: any) => void) => void
+): () => Promise<void>
+export function toAsync<T1, R>(
+  fn: (arg1: T1, callback: (err: any, result: R) => void) => void
+): (arg1: T1) => Promise<R>
+export function toAsync<T1>(
+  fn: (arg1: T1, callback: (err?: any) => void) => void
+): (arg1: T1) => Promise<void>
+export function toAsync<T1, T2, R>(
+  fn: (arg1: T1, arg2: T2, callback: (err: any, result: R) => void) => void
+): (arg1: T1, arg2: T2) => Promise<R>
+export function toAsync<T1, T2>(
+  fn: (arg1: T1, arg2: T2, callback: (err?: any) => void) => void
+): (arg1: T1, arg2: T2) => Promise<void>
+export function toAsync<T1, T2, T3, R>(
+  fn: (
+    arg1: T1,
+    arg2: T2,
+    arg3: T3,
+    callback: (err: any, result: R) => void
+  ) => void
+): (arg1: T1, arg2: T2, arg3: T3) => Promise<R>
+export function toAsync<T1, T2, T3>(
+  fn: (arg1: T1, arg2: T2, arg3: T3, callback: (err?: any) => void) => void
+): (arg1: T1, arg2: T2, arg3: T3) => Promise<void>
+export function toAsync<T1, T2, T3, T4, R>(
+  fn: (
+    arg1: T1,
+    arg2: T2,
+    arg3: T3,
+    arg4: T4,
+    callback: (err: any, result: R) => void
+  ) => void
+): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<R>
+export function toAsync<T1, T2, T3, T4>(
+  fn: (
+    arg1: T1,
+    arg2: T2,
+    arg3: T3,
+    arg4: T4,
+    callback: (err?: any) => void
+  ) => void
+): (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<void>
+export function toAsync<T1, T2, T3, T4, T5, R>(
+  fn: (
+    arg1: T1,
+    arg2: T2,
+    arg3: T3,
+    arg4: T4,
+    arg5: T5,
+    callback: (err: any, result: R) => void
+  ) => void
+): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<R>
+export function toAsync<T1, T2, T3, T4, T5>(
+  fn: (
+    arg1: T1,
+    arg2: T2,
+    arg3: T3,
+    arg4: T4,
+    arg5: T5,
+    callback: (err?: any) => void
+  ) => void
+): (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<void>
+
+/**
+ * Takes an async function (or a function that returns a Promise) and returns
+ * a function following the error-first callback style, i.e. taking an
+ * (err, value) => ... callback as the last argument.
+ */
+export function toCallback(
+  fn: () => Promise<void>
+): (callback: (err: any) => void) => void
+export function toCallback<R>(
+  fn: () => Promise<R>
+): (callback: (err: any, result: R) => void) => void
+export function toCallback<T1>(
+  fn: (arg1: T1) => Promise<void>
+): (arg1: T1, callback: (err: any) => void) => void
+export function toCallback<T1, R>(
+  fn: (arg1: T1) => Promise<R>
+): (arg1: T1, callback: (err: any, result: R) => void) => void
+export function toCallback<T1, T2>(
+  fn: (arg1: T1, arg2: T2) => Promise<void>
+): (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, 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
+export function toCallback<T1, T2, T3, R>(
+  fn: (arg1: T1, arg2: T2, arg3: T3) => Promise<R>
+): (
+  arg1: T1,
+  arg2: T2,
+  arg3: T3,
+  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>
+): (
+  arg1: T1,
+  arg2: T2,
+  arg3: T3,
+  arg4: T4,
+  callback: (err: any) => void
+) => void
+export function toCallback<T1, T2, T3, T4, R>(
+  fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4) => Promise<R>
+): (
+  arg1: T1,
+  arg2: T2,
+  arg3: T3,
+  arg4: T4,
+  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>
+): (
+  arg1: T1,
+  arg2: T2,
+  arg3: T3,
+  arg4: T4,
+  arg5: T5,
+  callback: (err: any) => void
+) => void
+export function toCallback<T1, T2, T3, T4, T5, R>(
+  fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5) => Promise<R>
+): (
+  arg1: T1,
+  arg2: T2,
+  arg3: T3,
+  arg4: T4,
+  arg5: T5,
+  callback: (err: any, result: R) => void
+) => void
+export function toCallback<T1, T2, T3, T4, T5, T6>(
+  fn: (
+    arg1: T1,
+    arg2: T2,
+    arg3: T3,
+    arg4: T4,
+    arg5: T5,
+    arg6: T6
+  ) => Promise<void>
+): (
+  arg1: T1,
+  arg2: T2,
+  arg3: T3,
+  arg4: T4,
+  arg5: T5,
+  arg6: T6,
+  callback: (err: any) => void
+) => void
+export function toCallback<T1, T2, T3, T4, T5, T6, R>(
+  fn: (arg1: T1, arg2: T2, arg3: T3, arg4: T4, arg5: T5, arg6: T6) => Promise<R>
+): (
+  arg1: T1,
+  arg2: T2,
+  arg3: T3,
+  arg4: T4,
+  arg5: T5,
+  arg6: T6,
+  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
+): (err: R, res: T) => void
+
+/* -------------------------------- 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.
+ * @see {@link parseDataPath} for supported path formats.
+ */
+export function getEntriesAtDataPath(
+  obj: any,
+  path: OrArrayOf<string>,
+  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) => 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
+
+/**
+ * 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.
+ *
+ * @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>,
+  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 ---------------------------------- */
+
+/**
+   * Escapes double quotes, ampersands, and angle brackets (`"&<>`).
+
+   * @param html The html to escape.
+   * @returns The newly escaped html.
+   */
+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 | null | undefined): string
+
+/**
+ * Strips HTML tags from the string.
+ * @param html The string to strip.
+ * @returns The newly stripped string.
+ * @deprecated Use stripHtml() instead
+ */
+export function stripTags(html: string | null | undefined): string
+
+/* -------------------------- typescript utilities -------------------------- */
+export interface ArrayLike<T> {
+  readonly length: number
+  readonly [n: number]: T
+}
+export interface Dictionary<T> {
+  [index: string]: T
+}
+export type RecursiveArray<T> = Array<T | RecursiveArray<T>>
+type OrArrayOf<T> = T | T[]