obsidian-dev-utils/dist/lib/cjs/ObjectUtils.d.cts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * Contains utility functions for Objects.
 */
import type { RequiredKeysOf, UndefinedOnPartialDeep } from 'type-fest';
import type { ExactMembers, StringKeys } from './Type.cjs';
/**
 * Specifies how functions should be handled in the JSON output.
 */
export declare enum FunctionHandlingMode {
    /**
     * Excludes functions from the JSON output.
     */
    Exclude = "exclude",
    /**
     * Includes the full function definition in the JSON output.
     */
    Full = "full",
    /**
     * Includes only the function name in the JSON output.
     */
    NameOnly = "nameOnly"
}
/**
 * Options for {@link toJson}.
 */
export interface ToJsonOptions {
    /**
     * Specifies how functions should be handled in the JSON output (default: `exclude`).
     */
    functionHandlingMode: FunctionHandlingMode;
    /**
     * Specifies the maximum depth of nested objects to include in the JSON output.
     * Use `-1` for no limit.
     * Defaults to `-1`.
     */
    maxDepth: number;
    /**
     * Specifies whether to catch errors in `toJSON()` and replace them with a placeholder.
     * Defaults to `false`.
     */
    shouldCatchToJSONErrors: boolean;
    /**
     * Specifies whether to handle circular references in the JSON output.
     * Defaults to `false`.
     */
    shouldHandleCircularReferences: boolean;
    /**
     * Specifies whether to handle errors in the JSON output.
     * Defaults to `false`.
     */
    shouldHandleErrors: boolean;
    /**
     * Specifies whether to handle undefined values in the JSON output.
     * Defaults to `false`.
     */
    shouldHandleUndefined: boolean;
    /**
     * Specifies whether to sort the keys of the JSON output.
     * Defaults to `false`.
     */
    shouldSortKeys: boolean;
    /**
     * Specifies the indentation of the JSON output. This can be a number of spaces or a string. Defaults to `2`.
     */
    space: number | string;
    /**
     * Specifies the substitutions to use in the JSON output.
     */
    tokenSubstitutions: Partial<TokenSubstitutions>;
}
interface ModuleWithDefaultExport<T> {
    default: T;
}
interface TokenSubstitutions {
    circularReference: string;
    maxDepthLimitReached: string;
    toJSONFailed: string;
}
/**
 * A type that represents a generic object.
 */
export type GenericObject = Record<string, unknown>;
type KeysWithUndefined<T> = {
    [K in keyof T]-?: undefined extends T[K] ? K : never;
}[keyof T];
type MandatoryKeysWithUndefined<T extends object> = Extract<RequiredKeysOf<T> & StringKeys<T>, KeysWithUndefined<T>>;
type RemoveUndefinedOverload<T extends object> = MandatoryKeysWithUndefined<T> extends never ? [obj: T] : never;
type RemoveUndefinedWithKeysOverload<T extends object, K extends readonly string[]> = [obj: T, keysToKeep: ExactMembers<MandatoryKeysWithUndefined<T>, K>];
/**
 * Assigns properties from one or more source objects to a target object, including non-enumerable properties.
 *
 * @param target - The target object to assign properties to.
 * @param source - The source object to assign properties from.
 * @returns The target object with the assigned properties.
 */
export declare function assignWithNonEnumerableProperties<T extends object, U>(target: T, source: U): T & U;
/**
 * @param target - The target object to assign properties to.
 * @param source1 - The first source object to assign properties from.
 * @param source2 - The second source object to assign properties from.
 * @returns The target object with the assigned properties.
 */
export declare function assignWithNonEnumerableProperties<T extends object, U, V>(target: T, source1: U, source2: V): T & U & V;
/**
 * Assigns properties from one or more source objects to a target object, including non-enumerable properties.
 *
 * @param target - The target object to assign properties to.
 * @param source1 - The first source object to assign properties from.
 * @param source2 - The second source object to assign properties from.
 * @param source3 - The third source object to assign properties from.
 * @returns The target object with the assigned properties.
 */
export declare function assignWithNonEnumerableProperties<T extends object, U, V, W>(target: T, source1: U, source2: V, source3: W): T & U & V & W;
/**
 * Clones an object, including non-enumerable properties.
 *
 * @param obj - The object to clone.
 * @returns A new object with the same properties as the original object, including non-enumerable properties.
 */
export declare function cloneWithNonEnumerableProperties<T extends object>(obj: T): T;
/**
 * Compares two values to determine if they are deeply equal.
 *
 * @param a - The first value to compare.
 * @param b - The second value to compare.
 * @returns `true` if the values are deeply equal, otherwise `false`.
 */
export declare function deepEqual(a: unknown, b: unknown): boolean;
/**
 * Deletes multiple properties from an object.
 *
 * @typeParam T - The type of the object.
 * @param obj - The object to delete the properties from.
 * @param propertyNames - The names of the properties to delete.
 * @returns `true` if any of the properties were present, otherwise `false`.
 */
export declare function deleteProperties<T extends object>(obj: T, propertyNames: (keyof T)[]): boolean;
/**
 * Deletes a property from an object.
 *
 * @typeParam T - The type of the object.
 * @param obj - The object to delete the property from.
 * @param propertyName - The name of the property to delete.
 * @returns `true` if the property was present, otherwise `false`.
 */
export declare function deleteProperty<T extends object>(obj: T, propertyName: keyof T): boolean;
/**
 * Extracts the default export from a module.
 *
 * Useful to handle incorrect default export interop between ESM and CJS.
 *
 * @param module - The module to extract the default export from.
 * @returns The default export.
 */
export declare function extractDefaultExportInterop<T>(module: ModuleWithDefaultExport<T>): T;
/**
 * Gets all entries of an object.
 *
 * @param obj - The object to get the entries of.
 * @returns An array of all entries of the object.
 */
export declare function getAllEntries<T extends object>(obj: T): [StringKeys<T>, T[StringKeys<T>]][];
/**
 * Gets all keys of an object.
 * Includes fields and properties.
 *
 * @param obj - The object to get the keys of.
 * @returns An array of all keys of the object.
 */
export declare function getAllKeys<T extends object>(obj: T): StringKeys<T>[];
/**
 * Gets the value of a nested property from an object.
 *
 * @param obj - The object to get the nested property value from.
 * @param path - The path to the nested property.
 * @returns The value of the nested property.
 */
export declare function getNestedPropertyValue(obj: GenericObject, path: string): unknown;
/**
 * Gets the prototype of the specified object.
 *
 * @typeParam T - The type of the object.
 * @param instance - The object instance to retrieve the prototype of.
 * @returns The prototype of the object.
 */
export declare function getPrototypeOf<T>(instance: T): T;
/**
 * Retrieves the name of a property of a given type `T`.
 *
 * @typeParam T - The type of the object containing the property.
 * @param name - The name of the property as a string.
 * @returns The name of the property.
 */
export declare function nameof<T extends object>(name: StringKeys<T>): StringKeys<T>;
/**
 * Normalizes optional properties to allow `undefined` assignment in strict mode.
 *
 * This utility provides a workaround for the `exactOptionalPropertyTypes` TypeScript flag,
 * which prohibits directly assigning `undefined` to optional properties when the type
 * explicitly omits `undefined`.
 *
 * Example:
 * ```typescript
 * // With `exactOptionalPropertyTypes: true`
 * const x: { prop?: string } = { prop: undefined }; // Compiler error
 *
 * // Using this utility:
 * const y: { prop?: string } = normalizeOptionalProperties<{ prop?: string }>({ prop: undefined }); // Works
 * ```
 *
 * @typeParam T - The target type with optional properties to normalize.
 * @param obj - The object to normalize, allowing explicit `undefined` for optional properties.
 * @returns The normalized object, compatible with `exactOptionalPropertyTypes`.
 */
export declare function normalizeOptionalProperties<T>(obj: UndefinedOnPartialDeep<T>): T;
/**
 * Removes all undefined properties from an object when there are no mandatory keys with undefined values.
 *
 * @typeParam Type - The type of the object.
 * @param args - The arguments to the function.
 * @returns The object with all undefined properties removed.
 */
export declare function removeUndefinedProperties<Type extends object>(...args: RemoveUndefinedOverload<Type>): Type;
/**
 * Removes all undefined properties from an object when there are mandatory keys with undefined values.
 *
 * @typeParam Type - The type of the object.
 * @typeParam KeysToKeep - The keys to keep.
 * @param args - The arguments to the function.
 * @returns The object with all undefined properties removed.
 */
export declare function removeUndefinedProperties<Type extends object, const KeysToKeep extends readonly string[]>(...args: RemoveUndefinedWithKeysOverload<Type, KeysToKeep>): Type;
/**
 * Sets the value of a nested property in an object.
 *
 * @param obj - The object to set the nested property value in.
 * @param path - The path to the nested property.
 * @param value - The value to set.
 */
export declare function setNestedPropertyValue(obj: GenericObject, path: string, value: unknown): void;
/**
 * Converts a given value to a JSON string.
 *
 * @param value - The value to be converted to JSON. This can be of any type.
 * @param options - Options for customizing the JSON conversion process.
 * @returns The JSON string representation of the input value.
 */
export declare function toJson(value: unknown, options?: Partial<ToJsonOptions>): string;
export {};