@ayonli/jsext/types/deprecate.d.ts

A JavaScript extension package for building strong and modern applications.

/**
 * Marks a function as deprecated and emit warnings when it is called.
 * @module
 * @experimental
 */
/**
 * Marks a function as deprecated and returns a wrapped function.
 *
 * When the wrapped function is called, a deprecation warning will be emitted
 * to the stdout.
 *
 * **NOTE:** The original function must have a name.
 *
 * **NOTE:** This function is **experimental** and the warning may point to the
 * wrong file source in some environments.
 *
 * @param tip Extra tip for the user to migrate.
 * @param once If set, the warning will only be emitted once.
 *
 * @example
 * ```ts
 * import deprecate from "@ayonli/jsext/deprecate";
 *
 * const sum = deprecate(function sum(a: number, b: number) {
 *     return a + b;
 * }, "use `a + b` instead");
 * console.log(sum(1, 2));
 * // output:
 * // DeprecationWarning: sum() is deprecated, use `a + b` instead (at <anonymous>:4:13)
 * // 3
 * ```
 */
export default function deprecate<T, Fn extends (this: T, ...args: any[]) => any>(fn: Fn, tip?: string, once?: boolean): Fn;
/**
 * Emits a deprecation warning for the target, usually a parameter, an option,
 * or the function's name, etc.
 *
 * @param forFn Usually set to the current function, used to locate the call-site.
 * @param tip Extra tip for the user to migrate.
 * @param once If set, the warning will only be emitted once.
 *
 * @example
 * ```ts
 * import deprecate from "@ayonli/jsext/deprecate";
 *
 * function pow(a: number, b: number) {
 *     deprecate("pow()", pow, "use `a ** b` instead");
 *     return a ** b;
 * }
 *
 * console.log(pow(2, 3));
 * // output:
 * // DeprecationWarning: pow() is deprecated, use `a ** b` instead (at <anonymous>:5:13)
 * // 3
 * ```
 */
export default function deprecate(target: string, forFn: Function, tip?: string, once?: boolean): void;