@angular-wave/angular.ts 0.14.3 → 0.15.1

package/@types/shared/utils.d.ts

@@ -1,9 +1,22 @@
 /**
+ * @param {any} value
+ * @returns {value is Proxy<ng.Scope> | ng.Scope}
+ */
+export function isProxy(value: any): value is ProxyConstructor | ng.Scope;
+/**
+ * Unwraps a proxy if the value is a proxy, otherwise returns the value as-is.
  *
- * @param {*} value
- * @returns {boolean}
+ * @template T
+ * @param {T | (T & { $target: T })} val - A value that might be a proxy.
+ * @returns {T} The unproxied value.
  */
-export function isProxy(value: any): boolean;
+export function deProxy<T>(
+  val:
+    | T
+    | (T & {
+        $target: T;
+      }),
+): T;
 /**
  * @returns {number} an unique alpha-numeric string
  */
@@ -23,11 +36,11 @@ export function lowercase(string: string): string;
  */
 export function uppercase(string: string): string;
 /**
- * @param {*} obj Reference to check.
+ * @param {unknown} obj Reference to check.
  * @return {boolean} Returns true if `obj` is an array or array-like object (NodeList, Arguments,
  *                   String ...)
  */
-export function isArrayLike(obj: any): boolean;
+export function isArrayLike(obj: unknown): boolean;
 /**
  * Determines if a reference is undefined.
  *
@@ -36,28 +49,38 @@ export function isArrayLike(obj: any): boolean;
  */
 export function isUndefined(value: any): boolean;
 /**
- * Determines if a reference is defined.
+ * Determines if a reference is defined (not `undefined`).
  *
- * @param {*} value Reference to check.
- * @returns {boolean} True if `value` is defined.
+ * @template T
+ * @param {T | undefined} value - Reference to check.
+ * @returns {value is T} True if `value` is defined.
  */
-export function isDefined(value: any): boolean;
+export function isDefined<T>(value: T | undefined): value is T;
 /**
- * Wrapper for minification
- *
  * @template T
  * @param {any} array
  * @returns {array is T[]} true if array is an Array
  */
 export function isArray<T>(array: any): array is T[];
+/**
+ * @template T
+ * @param {any} val
+ * @param {new (...args: any[]) => T} type  The constructor to test against
+ * @returns {val is T}
+ */
+export function isInstanceOf<T>(
+  val: any,
+  type: new (...args: any[]) => T,
+): val is T;
 /**
  * Determines if a reference is an `Object`. Unlike `typeof` in JavaScript, `null`s are not
  * considered to be objects. Note that JavaScript arrays are objects.
  *
- * @param {*} value Reference to check.
- * @returns {boolean} True if `value` is an `Object` but not `null`.
+ * @template T
+ * @param {T} value - Reference to check.
+ * @returns {value is T & object} True if `value` is an `Object` but not `null`.
  */
-export function isObject(value: any): boolean;
+export function isObject<T>(value: T): value is T & object;
 /**
  * Determines if a value is an object with a null prototype
  *
@@ -65,21 +88,26 @@ export function isObject(value: any): boolean;
  * @returns {boolean} True if `value` is an `Object` with a null prototype
  */
 export function isBlankObject(value: any): boolean;
-export function isString(value: unknown): boolean;
+/**
+ * Determines if a reference is a `string`.
+ * @param {unknown} value - The value to check.
+ * @returns {value is string} True if `value` is a string.
+ */
+export function isString(value: unknown): value is string;
 /**
  * Determines if a reference is a null.
  *
- * @param {*} value Reference to check.
- * @returns {boolean} True if `value` is a null.
+ * @param {unknown} value Reference to check.
+ * @returns {value is null} True if `value` is a null.
  */
-export function isNull(value: any): boolean;
+export function isNull(value: unknown): value is null;
 /**
  * Determines if a reference is null or undefined.
  *
- * @param {*} obj Reference to check.
- * @returns {boolean} True if `value` is null or undefined.
+ * @param {unknown} obj Reference to check.
+ * @returns {obj is null | undefined} True if `value` is null or undefined.
  */
-export function isNullOrUndefined(obj: any): boolean;
+export function isNullOrUndefined(obj: unknown): obj is null | undefined;
 /**
  * Determines if a reference is not null or undefined.
  *
@@ -96,10 +124,10 @@ export function notNullOrUndefined(obj: any): boolean;
  * [`isFinite'](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isFinite)
  * method.
  *
- * @param {*} value Reference to check.
- * @returns {boolean} True if `value` is a `Number`.
+ * @param {unknown} value Reference to check.
+ * @returns {value is number} True if `value` is a `Number`.
  */
-export function isNumber(value: any): boolean;
+export function isNumber(value: unknown): value is number;
 /**
  *
  * Determines if a value is a date.
@@ -113,9 +141,9 @@ export function isDate(value: any): boolean;
  * Loosely based on https://www.npmjs.com/package/iserror
  *
  * @param {*} value Reference to check.
- * @returns {boolean} True if `value` is an `Error`.
+ * @returns {value is Error} True if `value` is an `Error`.
  */
-export function isError(value: any): boolean;
+export function isError(value: any): value is Error;
 /**
  * Determines if a reference is a `Function`.
  *
@@ -133,10 +161,10 @@ export function isRegExp(value: any): boolean;
 /**
  * Checks if `obj` is a window object.
  *
- * @param {*} obj Object to check
- * @returns {boolean} True if `obj` is a window obj.
+ * @param {unknown} obj Object to check
+ * @returns {obj is Window} True if `obj` is a window obj.
  */
-export function isWindow(obj: any): boolean;
+export function isWindow(obj: unknown): obj is Window;
 /**
  * @param {*} obj
  * @returns {boolean}
@@ -182,13 +210,23 @@ export function isArrayBuffer(obj: any): boolean;
  * @returns {string | *}
  */
 export function trim(value: any): string | any;
-export function snakeCase(name: any, separator: any): any;
+/**
+ * @param {string} name
+ * @param {string} separator
+ */
+export function snakeCase(name: string, separator: string): string;
 /**
  * Set or clear the hashkey for an object.
- * @param obj object
- * @param hashkey the hashkey (!truthy to delete the hashkey)
+ * @param {{ [x: string]: any; _hashKey?: any; }} obj object
+ * @param {any} hashkey the hashkey (!truthy to delete the hashkey)
  */
-export function setHashKey(obj: any, hashkey: any): void;
+export function setHashKey(
+  obj: {
+    [x: string]: any;
+    _hashKey?: any;
+  },
+  hashkey: any,
+): void;
 /**
  * Deeply extends a destination object with one or more source objects.
  * Safely handles Dates, RegExps, DOM nodes, arrays, and nested objects.
@@ -233,17 +271,25 @@ export function isNumberNaN(num: any): boolean;
  * @returns {Object}
  */
 export function inherit(parent: any, extra: any): any;
-export function hasCustomToString(obj: any): boolean;
+/**
+ * @param {{ toString: () => string; }} obj
+ * @returns {boolean}
+ */
+export function hasCustomToString(obj: { toString: () => string }): boolean;
 /**
  * Returns a string appropriate for the type of node.
  *
  * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/nodeName)
  *
  * @param {Element} element
- * @returns
+ * @returns {string}
  */
 export function getNodeName(element: Element): string;
-export function includes(array: any, obj: any): boolean;
+/**
+ * @param {any} array
+ * @param {string} obj
+ */
+export function includes(array: any, obj: string): boolean;
 /**
  * Removes the first occurrence of a specified value from an array.
  *
@@ -253,7 +299,11 @@ export function includes(array: any, obj: any): boolean;
  * @returns {number} - The index of the removed value, or -1 if the value was not found.
  */
 export function arrayRemove<T>(array: Array<T>, value: T): number;
-export function simpleCompare(val1: any, val2: any): boolean;
+/**
+ * @param {unknown} val1
+ * @param {unknown} val2
+ */
+export function simpleCompare(val1: unknown, val2: unknown): boolean;
 /**
  * Determines if two objects or two values are equivalent. Supports value types, regular
  * expressions, arrays and objects.
@@ -318,14 +368,34 @@ export function equals(o1: any, o2: any): boolean;
  * @param  {string} context the context in which the name is used, such as module or directive
  */
 export function assertNotHasOwnProperty(name: string, context: string): void;
-export function stringify(value: any): any;
+/**
+ * @param {unknown} value
+ * @returns {string | unknown}
+ */
+export function stringify(value: unknown): string | unknown;
 /**
  * @param {Number} maxDepth
  * @return {boolean}
  */
 export function isValidObjectMaxDepth(maxDepth: number): boolean;
-export function concat(array1: any, array2: any, index: any): any;
-export function sliceArgs(args: any, startIndex: any): any;
+/**
+ * @param {any[]} array1
+ * @param {IArguments | any[] | NodeListOf<ChildNode>} array2
+ * @param {number | undefined} [index]
+ */
+export function concat(
+  array1: any[],
+  array2: IArguments | any[] | NodeListOf<ChildNode>,
+  index?: number | undefined,
+): any[];
+/**
+ * @param {IArguments | [string, ...any[]]} args
+ * @param {number} startIndex
+ */
+export function sliceArgs(
+  args: IArguments | [string, ...any[]],
+  startIndex: number,
+): any;
 /**
  * Returns a function which calls function `fn` bound to `self` (`self` becomes the `this` for
  * `fn`). You can supply optional `args` that are prebound to the function. This feature is also
@@ -338,62 +408,53 @@ export function sliceArgs(args: any, startIndex: any): any;
  */
 export function bind(context: any, fn: any, ...args: any[]): Function;
 /**
- * Serializes input into a JSON-formatted string. Properties with leading $$ characters will be
- * stripped since AngularTS uses this notation internally.
- *
- * @param {Object|Array|Date|string|number|boolean} obj Input to be serialized into JSON.
- * @param {boolean|number} [pretty=2] If set to true, the JSON output will contain newlines and whitespace.
- *    If set to an integer, the JSON output will contain that many spaces per indentation.
- * @returns {string|undefined} JSON-ified string representing `obj`.
- * @knownIssue
- *
- * The Safari browser throws a `RangeError` instead of returning `null` when it tries to stringify a `Date`
- * object with an invalid date value. The only reliable way to prevent this is to monkeypatch the
- * `Date.prototype.toJSON` method as follows:
- *
- * ```
- * let _DatetoJSON = Date.prototype.toJSON;
- * Date.prototype.toJSON = function() {
- *   try {
- *     return _DatetoJSON.call(this);
- *   } catch(e) {
- *     if (e instanceof RangeError) {
- *       return null;
- *     }
- *     throw e;
- *   }
- * };
- * ```
- *
- * See https://github.com/angular/angular.js/pull/14221 for more information.
+ * Serializes input into a JSON-formatted string. Properties with leading `$$` characters
+ * will be stripped since AngularTS uses this notation internally.
+ *
+ * @param {Object|Array<any>|Date|string|number|boolean} obj
+ *   Input to be serialized into JSON.
+ * @param {boolean|number} [pretty=2]
+ *   If `true`, the JSON output will contain newlines and whitespace (2 spaces).
+ *   If a number, the JSON output will contain that many spaces per indentation.
+ * @returns {string|undefined}
+ *   JSON-ified string representing `obj`, or `undefined` if `obj` is undefined.
  */
 export function toJson(
-  obj: any | any[] | Date | string | number | boolean,
+  obj: any | Array<any> | Date | string | number | boolean,
   pretty?: boolean | number,
 ): string | undefined;
 /**
  * Deserializes a JSON string.
  *
  * @param {string} json JSON string to deserialize.
- * @returns {Object|Array|string|number} Deserialized JSON string.
+ * @returns {Object|Array<any>|string|number} Deserialized JSON string.
  */
-export function fromJson(json: string): any | any[] | string | number;
-export function timezoneToOffset(timezone: any, fallback: any): any;
-export function addDateMinutes(date: any, minutes: any): Date;
-export function convertTimezoneToLocal(
-  date: any,
-  timezone: any,
-  reverse: any,
-): Date;
+export function fromJson(json: string): any | Array<any> | string | number;
+/**
+ * @param {Date} date
+ * @param {number} minutes
+ */
+export function addDateMinutes(date: Date, minutes: number): Date;
 /**
  * Parses an escaped url query string into key-value pairs.
  * @param {string} keyValue
- * @returns {Object.<string,boolean|Array>}
+ * @returns {Object.<string,boolean|Array<any>>}
  */
 export function parseKeyValue(keyValue: string): {
   [x: string]: boolean | any[];
 };
-export function toKeyValue(obj: any): string;
+/**
+ * @param {string | { [s: string]: any; } | ArrayLike<any> | null} obj
+ */
+export function toKeyValue(
+  obj:
+    | string
+    | {
+        [s: string]: any;
+      }
+    | ArrayLike<any>
+    | null,
+): string;
 /**
  * Tries to decode the URI component without throwing an exception.
  *
@@ -424,15 +485,27 @@ export function encodeUriSegment(val: string): string;
  *    pct-encoded   = "%" HEXDIG HEXDIG
  *    sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
  *                     / "*" / "+" / "," / ";" / "="
+ * @param {string | number | boolean} val
+ * @param {boolean | undefined} [pctEncodeSpaces]
  */
-export function encodeUriQuery(val: any, pctEncodeSpaces: any): string;
-export function getNgAttribute(element: any, ngAttr: any): any;
+export function encodeUriQuery(
+  val: string | number | boolean,
+  pctEncodeSpaces?: boolean | undefined,
+): string;
 /**
- * Creates a shallow copy of an object, an array or a primitive.
+ * Creates a shallow copy of an object, an array, or returns primitives as-is.
+ *
+ * Assumes there are no proto properties.
  *
- * Assumes that there are no proto properties for objects.
+ * @template T
+ * @param {T} src
+ * @param {T extends any[] ? T : Record<string, unknown>} [dst]
+ * @returns {T}
  */
-export function shallowCopy(src: any, dst: any): any;
+export function shallowCopy<T>(
+  src: T,
+  dst?: T extends any[] ? T : Record<string, unknown>,
+): T;
 /**
  * Throw error if the argument is false
  * @param {boolean} argument
@@ -441,13 +514,25 @@ export function shallowCopy(src: any, dst: any): any;
 export function assert(argument: boolean, errorMsg?: string): void;
 /**
  * Throw error if the argument is falsy.
+ * @param {string | boolean | Object} arg
+ * @param {string} name
+ * @param {string | undefined} [reason]
+ */
+export function assertArg(
+  arg: string | boolean | any,
+  name: string,
+  reason?: string | undefined,
+): any;
+/**
+ * @param {string | Function | any[]} arg
+ * @param {string} name
+ * @param {boolean | undefined} [acceptArrayAnnotation]
  */
-export function assertArg(arg: any, name: any, reason: any): any;
 export function assertArgFn(
-  arg: any,
-  name: any,
-  acceptArrayAnnotation: any,
-): any;
+  arg: string | Function | any[],
+  name: string,
+  acceptArrayAnnotation?: boolean | undefined,
+): string | Function | any[];
 /**
  * Configure several aspects of error handling if used as a setter or return the
  * current configuration if used as a getter.
@@ -486,14 +571,21 @@ export function errorHandlingConfig(
  * @returns {function(string, ...*): Error} minErr instance
  */
 export function minErr(module: string): (arg0: string, ...args: any[]) => Error;
-export function toDebugString(obj: any): any;
+/**
+ * Converts a value into a simplified debug-friendly string.
+ *
+ * @template T
+ * @param {T|ng.Scope} obj
+ * @returns {string}
+ */
+export function toDebugString<T>(obj: T | ng.Scope): string;
 /**
  * Computes a hash of an 'obj'.
  * Hash of a:
  *  string is string
  *  number is number as string
- *  object is either result of calling $$hashKey function on the object or uniquely generated id,
- *         that is also assigned to the $$hashKey property of the object.
+ *  object is either result of calling _hashKey function on the object or uniquely generated id,
+ *         that is also assigned to the _hashKey property of the object.
  *
  * @param {*} obj
  * @returns {string} hash string such that the same input will have the same hash string.
@@ -565,18 +657,30 @@ export function entries<T>(
  * Wraps a function so it can only be called once.
  * Subsequent calls do nothing and return undefined.
  *
- * @param {Function} fn - The function to wrap.
- * @returns {Function} A new function that will call `fn` only once.
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - The function to wrap.
+ * @returns {(this: ThisParameterType<F>, ...args: Parameters<F>) => ReturnType<F> | undefined}
  */
-export function callBackOnce(fn: Function): Function;
+export function callBackOnce<F extends (...args: any[]) => any>(
+  fn: F,
+): (
+  this: ThisParameterType<F>,
+  ...args: Parameters<F>
+) => ReturnType<F> | undefined;
 /**
  * Wraps a function so it will only be called starting from the second invocation.
  * The first call does nothing and returns undefined.
  *
- * @param {Function} fn - The function to wrap.
- * @returns {Function} A new function that will skip the first call.
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - The function to wrap.
+ * @returns {(this: ThisParameterType<F>, ...args: Parameters<F>) => ReturnType<F> | undefined}
  */
-export function callBackAfterFirst(fn: Function): Function;
+export function callBackAfterFirst<F extends (...args: any[]) => any>(
+  fn: F,
+): (
+  this: ThisParameterType<F>,
+  ...args: Parameters<F>
+) => ReturnType<F> | undefined;
 /**
  * Delays execution for a specified number of milliseconds.
  *
@@ -614,10 +718,12 @@ export function startsWith(str: string, search: string): boolean;
 /**
  * Loads and instantiates a WebAssembly module.
  * Tries streaming first, then falls back.
+ * @param {string} src
+ * @param {WebAssembly.Imports} imports
  */
 export function instantiateWasm(
-  src: any,
-  imports?: {},
+  src: string,
+  imports?: WebAssembly.Imports,
 ): Promise<{
   instance: WebAssembly.Instance;
   exports: WebAssembly.Exports;

package/@types/shared/validate.d.ts

@@ -31,6 +31,26 @@ export function validateArray(arg: any, name: string): any;
  * @throws {TypeError} If the value does not satisfy the validator.
  */
 export function validateIsString(arg: any, name: string): any;
+/**
+ * @param {*} arg - The value to validate.
+ * @param {string} name - Parameter name (included in error message).
+ * @returns {number} The validated value.
+ * @throws {TypeError} If the value is not a number.
+ */
+export function validateIsNumber(arg: any, name: string): number;
+/**
+ * @template T
+ * @param {unknown} arg - The value to validate.
+ * @param {new (...args: any[]) => T} type - The constructor to check against.
+ * @param {string} name - Parameter name (included in error message).
+ * @returns {T} The validated instance.
+ * @throws {TypeError} If the value is not an instance of the specified type.
+ */
+export function validateInstanceOf<T>(
+  arg: unknown,
+  type: new (...args: any[]) => T,
+  name: string,
+): T;
 export const BADARG: "badarg";
 export const BADARGKEY: "badarg: key";
 export const BADARGVALUE: "badarg: value";