safe-dig/index.d.ts

A safe dig function for navigating nested objects and arrays in JavaScript, with an optional prototype method for all objects.

declare module 'safe-dig' {
  /**
   * Safely digs through an object or array to access nested properties or indices.
   * If any property or index doesn't exist, it returns `null` instead of throwing an error.
   *
   * @param obj The object or array to dig into.
   * @param args The sequence of keys or indices to access the desired value.
   * @returns The value found at the specified path, or `null` if not found.
   */
  export function safeDig<T>(obj: T, ...args: (string | number)[]): any;

  /**
   * Adds `safeDig` method to the prototype of all objects in JavaScript.
   * This allows using `obj.safeDig(...)` directly on any object.
   *
   * Usage example:
   *   const obj = { a: { b: { c: 42 } } };
   *   console.log(obj.safeDig('a', 'b', 'c')); // 42
   */
  export function addSafeDigPrototype(): void;
}