@angular-wave/angular.ts 0.0.60 → 0.0.62

package/src/core/q/q.md

@@ -0,0 +1,229 @@
+/\*\*
+
+- A service that helps you run functions asynchronously, and use their return values (or exceptions)
+- when they are done processing.
+-
+- This is a [Promises/A+](https://promisesaplus.com/)-compliant implementation of promises/deferred
+- objects inspired by [Kris Kowal's Q](https://github.com/kriskowal/q).
+-
+- $q can be used in two fashions --- one which is more similar to Kris Kowal's Q or jQuery's Deferred
+- implementations, and the other which resembles ES6 (ES2015) promises to some degree.
+-
+- ## $q constructor
+-
+- The streamlined ES6 style promise is essentially just using $q as a constructor which takes a `resolver`
+- function as the first argument. This is similar to the native Promise implementation from ES6,
+- see [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+-
+- While the constructor-style use is supported, not all of the supporting methods from ES6 promises are
+- available yet.
+-
+- It can be used like so:
+-
+- ```js
+
+  ```
+
+- // for the purpose of this example let's assume that variables `$q` and `okToGreet`
+- // are available in the current lexical scope (they could have been injected or passed in).
+-
+- function asyncGreet(name) {
+-     // perform some asynchronous operation, resolve or reject the promise when appropriate.
+-     return $q(function(resolve, reject) {
+-       setTimeout(function() {
+-         if (okToGreet(name)) {
+-           resolve('Hello, ' + name + '!');
+-         } else {
+-           reject('Greeting ' + name + ' is not allowed.');
+-         }
+-       }, 1000);
+-     });
+- }
+-
+- let promise = asyncGreet('Robin Hood');
+- promise.then(function(greeting) {
+-     alert('Success: ' + greeting);
+- }, function(reason) {
+-     alert('Failed: ' + reason);
+- });
+- ```
+
+  ```
+
+-
+- Note: progress/notify callbacks are not currently supported via the ES6-style interface.
+-
+- Note: unlike ES6 behavior, an exception thrown in the constructor function will NOT implicitly reject the promise.
+-
+- However, the more traditional CommonJS-style usage is still available, and documented below.
+-
+- [The CommonJS Promise proposal](http://wiki.commonjs.org/wiki/Promises) describes a promise as an
+- interface for interacting with an object that represents the result of an action that is
+- performed asynchronously, and may or may not be finished at any given point in time.
+-
+- From the perspective of dealing with error handling, deferred and promise APIs are to
+- asynchronous programming what `try`, `catch` and `throw` keywords are to synchronous programming.
+-
+- ```js
+
+  ```
+
+- // for the purpose of this example let's assume that variables `$q` and `okToGreet`
+- // are available in the current lexical scope (they could have been injected or passed in).
+-
+- function asyncGreet(name) {
+-     let deferred = $q.defer();
+-
+-     setTimeout(function() {
+-       deferred.notify('About to greet ' + name + '.');
+-
+-       if (okToGreet(name)) {
+-         deferred.resolve('Hello, ' + name + '!');
+-       } else {
+-         deferred.reject('Greeting ' + name + ' is not allowed.');
+-       }
+-     }, 1000);
+-
+-     return deferred.promise;
+- }
+-
+- let promise = asyncGreet('Robin Hood');
+- promise.then(function(greeting) {
+-     alert('Success: ' + greeting);
+- }, function(reason) {
+-     alert('Failed: ' + reason);
+- }, function(update) {
+-     alert('Got notification: ' + update);
+- });
+- ```
+
+  ```
+
+-
+- At first it might not be obvious why this extra complexity is worth the trouble. The payoff
+- comes in the way of guarantees that promise and deferred APIs make, see
+- https://github.com/kriskowal/uncommonjs/blob/master/promises/specification.md.
+-
+- Additionally the promise api allows for composition that is very hard to do with the
+- traditional callback ([CPS](http://en.wikipedia.org/wiki/Continuation-passing_style)) approach.
+- For more on this please see the [Q documentation](https://github.com/kriskowal/q) especially the
+- section on serial or parallel joining of promises.
+-
+- ## The Deferred API
+-
+- A new instance of deferred is constructed by calling `$q.defer()`.
+-
+- The purpose of the deferred object is to expose the associated Promise instance as well as APIs
+- that can be used for signaling the successful or unsuccessful completion, as well as the status
+- of the task.
+-
+- **Methods**
+-
+- - `resolve(value)` – resolves the derived promise with the `value`. If the value is a rejection
+- constructed via `$q.reject`, the promise will be rejected instead.
+- - `reject(reason)` – rejects the derived promise with the `reason`. This is equivalent to
+- resolving it with a rejection constructed via `$q.reject`.
+- - `notify(value)` - provides updates on the status of the promise's execution. This may be called
+- multiple times before the promise is either resolved or rejected.
+-
+- **Properties**
+-
+- - promise – `{Promise}` – promise object associated with this deferred.
+-
+-
+- ## The Promise API
+-
+- A new promise instance is created when a deferred instance is created and can be retrieved by
+- calling `deferred.promise`.
+-
+- The purpose of the promise object is to allow for interested parties to get access to the result
+- of the deferred task when it completes.
+-
+- **Methods**
+-
+- - `then(successCallback, [errorCallback], [notifyCallback])` – regardless of when the promise was or
+- will be resolved or rejected, `then` calls one of the success or error callbacks asynchronously
+- as soon as the result is available. The callbacks are called with a single argument: the result
+- or rejection reason. Additionally, the notify callback may be called zero or more times to
+- provide a progress indication, before the promise is resolved or rejected.
+-
+- This method _returns a new promise_ which is resolved or rejected via the return value of the
+- `successCallback`, `errorCallback` (unless that value is a promise, in which case it is resolved
+- with the value which is resolved in that promise using
+- [promise chaining](http://www.html5rocks.com/en/tutorials/es6/promises/#toc-promises-queues)).
+- It also notifies via the return value of the `notifyCallback` method. The promise cannot be
+- resolved or rejected from the notifyCallback method. The errorCallback and notifyCallback
+- arguments are optional.
+-
+- - `catch(errorCallback)` – shorthand for `promise.then(null, errorCallback)`
+-
+- - `finally(callback, notifyCallback)` – allows you to observe either the fulfillment or rejection of a promise,
+- but to do so without modifying the final value. This is useful to release resources or do some
+- clean-up that needs to be done whether the promise was rejected or resolved. See the [full
+- specification](https://github.com/kriskowal/q/wiki/API-Reference#promisefinallycallback) for
+- more information.
+-
+- ## Chaining promises
+-
+- Because calling the `then` method of a promise returns a new derived promise, it is easily
+- possible to create a chain of promises:
+-
+- ```js
+
+  ```
+
+- promiseB = promiseA.then(function(result) {
+-     return result + 1;
+- });
+-
+- // promiseB will be resolved immediately after promiseA is resolved and its value
+- // will be the result of promiseA incremented by 1
+- ```
+
+  ```
+
+-
+- It is possible to create chains of any length and since a promise can be resolved with another
+- promise (which will defer its resolution further), it is possible to pause/defer resolution of
+- the promises at any point in the chain. This makes it possible to implement powerful APIs like
+- $http's response interceptors.
+-
+-
+- ## Differences between Kris Kowal's Q and $q
+-
+- There are two main differences:
+-
+- - $q is integrated with the {@link ng.$rootScope.Scope} Scope model observation
+- mechanism in AngularJS, which means faster propagation of resolution or rejection into your
+- models and avoiding unnecessary browser repaints, which would result in flickering UI.
+- - Q has many more features than $q, but that comes at a cost of bytes. $q is tiny, but contains
+- all the important functionality needed for common async tasks.
+-
+- ## Testing
+-
+- ```js
+
+  ```
+
+- it('should simulate promise', inject(function($q, $rootScope) {
+-      let deferred = $q.defer();
+-      let promise = deferred.promise;
+-      let resolvedValue;
+-
+-      promise.then(function(value) { resolvedValue = value; });
+-      expect(resolvedValue).toBeUndefined();
+-
+-      // Simulate resolving of promise
+-      deferred.resolve(123);
+-      // Note that the 'then' function does not get called synchronously.
+-      // This is because we want the promise API to always be async, whether or not
+-      // it got called synchronously or asynchronously.
+-      expect(resolvedValue).toBeUndefined();
+-
+-      // Propagate promise resolution to 'then' functions using $apply().
+-      $rootScope.$apply();
+-      expect(resolvedValue).toEqual(123);
+- }));
+- ```
+  */
+  ```

package/src/core/sanitize/sanitize-uri.js

@@ -28,7 +28,7 @@ export function SanitizeUriProvider() {
    * to the DOM it is inactive and potentially malicious code will not be executed.
    *
    * @param {RegExp=} regexp New regexp to trust urls with.
-   * @returns {RegExp|ng.ICompileProvider} Current RegExp if called without value or self for
+   * @returns {RegExp|SanitizeUriProvider} Current RegExp if called without value or self for
    *    chaining otherwise.
    */
   this.aHrefSanitizationTrustedUrlList = function (regexp) {
@@ -58,8 +58,7 @@ export function SanitizeUriProvider() {
    * to the DOM it is inactive and potentially malicious code will not be executed.
    *
    * @param {RegExp=} regexp New regexp to trust urls with.
-   * @returns {RegExp|ng.$compileProvider} Current RegExp if called without value or self for
-   *    chaining otherwise.
+   * @returns {RegExp|SanitizeUriProvider} Current RegExp if called without value or self for chaining otherwise.
    */
   this.imgSrcSanitizationTrustedUrlList = function (regexp) {
     if (isDefined(regexp)) {

package/src/core/scope/scope.js

@@ -28,6 +28,20 @@ export const ScopePhase = {
  * @property {Object} locals
  */
 
+/**
+ * @typedef {function(any, any, Scope): any} WatchListener
+ * Callback function triggered whenever the value of `watchExpression` changes.
+ *
+ * @param {any} newVal - The current value of the `watchExpression`.
+ * @param {any} oldVal - The previous value of the `watchExpression`.
+ * @param {Scope} scope - The current scope in which the `watchExpression` is evaluated.
+ *
+ */
+
+/**
+ * @typedef {string | ((scope: Scope) => any)} WatchExpression
+ */
+
 /**
  *
  * The default number of `$digest` iterations the scope should attempt to execute before giving up and
@@ -378,12 +392,7 @@ export class Scope {
  *
  *    - `string`: Evaluated as {@link guide/expression expression}
  *    - `function(scope)`: called with current `scope` as a parameter.
- * @param {(newVal: any, oldVal: any, scope: Scope) => any} listener Callback called whenever the value
- *    of `watchExpression` changes.
- *
- *    - `newVal` contains the current value of the `watchExpression`
- *    - `oldVal` contains the previous value of the `watchExpression`
- *    - `scope` refers to the current scope
+ * @param {WatchListener} listener
  * @param {boolean=} [objectEquality=false] Compare for object equality using {@link angular.equals} instead of
  *     comparing for reference equality.
  * @returns {function()} Returns a deregistration function for this listener.
@@ -687,7 +696,7 @@ export class Scope {
         }
       }
     }
-
+    // TODO: fix this type signature
     return this.$watch(changeDetector, $watchCollectionAction);
   }
 
@@ -1282,7 +1291,8 @@ export class Scope {
     if (expr) {
       $$applyAsyncQueue.push(() => scope.$eval(expr));
     }
-    expr = $parse(expr);
+    // TODO: investigate
+    //expr = $parse(expr);
 
     if (applyAsyncId === null) {
       applyAsyncId = $browser.defer(flushApplyAsync, null, "$applyAsync");

package/src/directive/if/if.js

@@ -17,7 +17,12 @@ export function ngIfDirective($animate) {
     terminal: true,
     restrict: "A",
     /**
-     * TODO add type for $transclude service
+     *
+     * @param {*} $scope
+     * @param {*} $element
+     * @param {*} $attr
+     * @param {*} _ctrl
+     * @param {*} $transclude
      */
     link($scope, $element, $attr, _ctrl, $transclude) {
       /** @type {{clone: import("../../shared/jqlite/jqlite").JQLite }} */

package/src/filters/limit-to.js

@@ -19,14 +19,17 @@ export function limitToFilter() {
     if (Math.abs(Number(limit)) === Infinity) {
       limit = Number(limit);
     } else {
-      limit = toInt(limit);
+      limit = toInt(/** @type {String} */ (limit));
     }
     if (isNumberNaN(limit)) return input;
 
     if (isNumber(input)) input = input.toString();
     if (!isArrayLike(input)) return input;
 
-    begin = !begin || isNaN(/** @type {any} */ (begin)) ? 0 : toInt(begin);
+    begin =
+      !begin || isNaN(/** @type {any} */ (begin))
+        ? 0
+        : toInt(/** @type {String} */ (begin));
     begin =
       begin < 0 ? Math.max(0, /** @type {[]} */ (input).length + begin) : begin;
 

package/src/filters/order-by.js

@@ -5,7 +5,6 @@ import {
   isArrayLike,
   isString,
   minErr,
-  identity,
 } from "../shared/utils";
 
 orderByFilter.$inject = ["$parse"];
@@ -75,7 +74,7 @@ export function orderByFilter($parse) {
   function processPredicates(sortPredicates) {
     return sortPredicates.map((predicate) => {
       let descending = 1;
-      let get = identity;
+      let get = (x) => x;
 
       if (isFunction(predicate)) {
         get = predicate;

package/src/index.js

@@ -4,7 +4,7 @@ import { publishExternalAPI } from "./public";
 /**
  * @type {Angular}
  */
-const angular = new Angular();
+export const angular = new Angular();
 window["angular"] = angular;
 
 publishExternalAPI();

package/src/loader.js

@@ -16,7 +16,6 @@ import {
   bind,
   fromJson,
   toJson,
-  identity,
   equals,
   assertNotHasOwnProperty,
   isBoolean,
@@ -58,58 +57,9 @@ export class Angular {
     /** @type {string} */
     this.version = VERSION;
 
-    // Utility methods kept for backwards purposes
-    /** @type {bind} */
-    this.bind = bind;
-
-    /** @type {equals} */
-    this.equals = equals;
-
     /** @type {typeof import('./shared/jqlite/jqlite').JQLite} */
     this.element = JQLite;
 
-    /** @type {extend} */
-    this.extend = extend;
-
-    /** @type {forEach} */
-    this.forEach = forEach;
-
-    /** @type {fromJson} */
-    this.fromJson = fromJson;
-
-    /** @type {toJson} */
-    this.toJson = toJson;
-
-    /** @type {identity} */
-    this.identity = identity;
-
-    /** @type {isDate} */
-    this.isDate = isDate;
-
-    /** @type {isDefined} */
-    this.isDefined = isDefined;
-
-    /** @type {isElement} */
-    this.isElement = isElement;
-
-    /** @type {isFunction} */
-    this.isFunction = isFunction;
-
-    /** @type {isNumber} */
-    this.isNumber = isNumber;
-
-    /** @type {isObject} */
-    this.isObject = isObject;
-
-    /** @type {isString} */
-    this.isString = isString;
-
-    /** @type {isUndefined} */
-    this.isUndefined = isUndefined;
-
-    /** @type {merge} */
-    this.merge = merge;
-
     /** @type {errorHandlingConfig} */
     this.errorHandlingConfig = errorHandlingConfig;
 
@@ -275,10 +225,6 @@ export class Angular {
   }
 
   /**
-   * @ngdoc function
-   * @name angular.module
-   * @module ng
-   * @description
    *
    * The `angular.module` is a global place for creating, registering and retrieving AngularJS
    * modules.
@@ -414,7 +360,7 @@ export class Angular {
 
         /**
          * @ngdoc property
-         * @name import('./types').Module#requires
+         * @type import('./types').Module#requires
          * @module ng
          *
          * @description

package/src/router/params/param-type.js

@@ -35,10 +35,11 @@ export class ParamType {
     /** @inheritdoc */
     this.inherit = true;
     Object.assign(this, def);
+    this.name = undefined;
   }
   // consider these four methods to be "abstract methods" that should be overridden
   /** @inheritdoc */
-  is() {
+  is(_val) {
     return true;
   }
   /** @inheritdoc */

package/src/router/state/views.js

@@ -97,6 +97,8 @@ export class Ng1ViewConfig {
     this.path = path;
     this.viewDecl = viewDecl;
     this.factory = factory;
+    this.component = undefined;
+    this.template = undefined;
 
     /** @type {Number} */ this.$id = id++;
     this.loaded = false;
@@ -110,6 +112,7 @@ export class Ng1ViewConfig {
           )
         : this.template;
   }
+
   load() {
     const $q = services.$q;
     const context = new ResolveContext(this.path);

package/src/router/state-provider.js

@@ -117,7 +117,7 @@ export class StateProvider {
    *   let result = {},
    *       views = parent(state);
    *
-   *   angular.forEach(views, function (config, name) {
+   *   forEach(views, function (config, name) {
    *     let autoName = (state.name + '.' + name).replace('.', '/');
    *     config.templateUrl = config.templateUrl || '/partials/' + autoName + '.html';
    *     result[name] = config;

package/src/router/transition/reject-factory.js

@@ -105,6 +105,7 @@ export class Rejection {
     this.type = type;
     this.message = message;
     this.detail = detail;
+    this.redirected = false;
   }
   toString() {
     const detailString = (d) =>

package/src/router/url/url-rule.js

@@ -192,11 +192,11 @@ export class UrlRuleFactory {
 }
 UrlRuleFactory.isUrlRule = (obj) =>
   obj && ["type", "match", "handler"].every((key) => isDefined(obj[key]));
+
 /**
  * A base rule which calls `match`
  *
  * The value from the `match` function is passed through to the `handler`.
- * @type {angular.BaseUrlRule}
  */
 export class BaseUrlRule {
   constructor(match, handler) {

package/src/router/url/url-service.js

@@ -26,7 +26,7 @@ export class UrlService {
   ];
 
   /**
-   * @param {angular.ILocationProvider} $locationProvider
+   * @param {import("../../core/location/location").$LocationProvider} $locationProvider
    */
   constructor($locationProvider, stateService, globals, urlConfigProvider) {
     this.stateService = stateService;
@@ -53,7 +53,7 @@ export class UrlService {
      * The nested [[UrlConfig]] API to configure the URL and retrieve URL information
      *
      * See: [[UrlConfig]] for details
-     * @type {angular.UrlConfig}
+     * @type {import("./url-config").UrlConfigProvider}
      */
     this.config = urlConfigProvider;
 
@@ -231,7 +231,7 @@ export class UrlService {
       hash: this.hash(),
     };
     /**
-     * @type {angular.MatchResult}
+     * @type {MatchResult}
      */
     const best = this.match(url);
     const applyResult = pattern([
@@ -313,7 +313,7 @@ export class UrlService {
    *
    * Given a URL (as a [[UrlParts]] object), check all rules and determine the best matching rule.
    * Return the result as a [[MatchResult]].
-   * @returns {angular.MatchResult}
+   * @returns {any}
    */
   match(url) {
     url = Object.assign({ path: "", search: {}, hash: "" }, url);

package/src/router/url/url-service.spec.js

@@ -2,6 +2,7 @@ import { dealoc } from "../../shared/jqlite/jqlite";
 import { Angular } from "../../loader";
 import { publishExternalAPI } from "../../public";
 import { map, find } from "../../shared/common";
+import { forEach } from "../../shared/utils";
 
 describe("UrlMatcher", () => {
   let $url;
@@ -245,7 +246,7 @@ describe("UrlMatcher", () => {
           "/url/someword/child/childParam",
       };
 
-      angular.forEach(shouldPass, function (url, route) {
+      forEach(shouldPass, function (url, route) {
         expect($url.compile(route).exec(url, {})).toEqual({
           childParam: "childParam",
           matchedParam: "someword",
@@ -261,7 +262,7 @@ describe("UrlMatcher", () => {
           "/url/someword/child/childParam",
       };
 
-      angular.forEach(shouldThrow, function (url, route) {
+      forEach(shouldThrow, function (url, route) {
         expect(() => {
           $url.compile(route).exec(url, {});
         }).toThrowError("Unbalanced capture group in route '" + route + "'");
@@ -274,7 +275,7 @@ describe("UrlMatcher", () => {
           "/url/someword/child/childParam",
       };
 
-      angular.forEach(shouldPass, function (url, route) {
+      forEach(shouldPass, function (url, route) {
         expect(() => {
           $url.compile(route).exec(url, {});
         }).not.toThrow();

package/src/services/http/http.js

@@ -275,9 +275,9 @@ function headersGetter(headers) {
  * This function is used for both request and response transforming
  *
  * @param {*} data Data to transform.
- * @param {function(string=)} headers HTTP headers getter fn.
+ * @param {function(string=):any} headers HTTP headers getter fn.
  * @param {number} status HTTP status code of the response.
- * @param {Function|Array<Function>} fns Function or an array of functions.
+ * @param {function(...any): any | Array<Function>} fns Function or an array of functions.
  * @returns {*} Transformed data.
  */
 function transformData(data, headers, status, fns) {
@@ -285,9 +285,11 @@ function transformData(data, headers, status, fns) {
     return fns(data, headers, status);
   }
 
-  forEach(fns, (fn) => {
-    data = fn(data, headers, status);
-  });
+  if (Array.isArray(fns)) {
+    /** @type {Array<function(...any): any>} */ (fns).forEach((fn) => {
+      data = fn(data, headers, status);
+    });
+  }
 
   return data;
 }

package/src/services/template-request.js

@@ -4,11 +4,6 @@ import { extend, isString, isUndefined, minErr } from "../shared/utils";
 var $templateRequestMinErr = minErr("$templateRequest");
 
 /**
- * @ngdoc provider
- * @name $templateRequestProvider
- * @this
- *
- * @description
  * Used to configure the options passed to the {@link $http} service when making a template request.
  *
  * For example, it can be used for specifying the "Accept" header that is sent to the server, when
@@ -27,8 +22,8 @@ export function TemplateRequestProvider() {
    * The {@link $templateRequest} will set the `cache` and the `transformResponse` properties of the
    * options if not overridden here.
    *
-   * @param {string=} value new value for the {@link $http} options.
-   * @returns {string|self} Returns the {@link $http} options when used as getter and self if used as setter.
+   * @param {string=} val new value for the {@link $http} options.
+   * @returns {string|TemplateRequestProvider} Returns the {@link $http} options when used as getter and self if used as setter.
    */
   this.httpOptions = function (val) {
     if (val) {

package/src/shared/common.js

@@ -345,7 +345,7 @@ export function assertFn(predicateOrMap, errMsg = "assert failure") {
   return (obj) => {
     const result = predicateOrMap(obj);
     if (!result) {
-      throw new Error(isFunction(errMsg) ? errMsg(obj) : errMsg);
+      throw new Error(errMsg);
     }
     return result;
   };

package/src/shared/utils.js

@@ -307,7 +307,7 @@ export function snakeCase(name, separator) {
    ```js
      let values = {name: 'misko', gender: 'male'};
      let log = [];
-     angular.forEach(values, function(value, key) {
+     forEach(values, function(value, key) {
        this.push(key + ': ' + value);
      }, log);
      expect(log).toEqual(['name: misko', 'gender: male']);
@@ -496,15 +496,6 @@ export function inherit(parent, extra) {
   return extend(Object.create(parent), extra);
 }
 
-/**
- *
- * @param {*} value to be returned.
- * @returns {*} the value passed in.
- */
-export function identity(value) {
-  return value;
-}
-
 /**
  * @param {*} value
  * @returns {() => *}
@@ -894,7 +885,7 @@ export function toJson(obj, pretty) {
   if (!isNumber(pretty)) {
     pretty = pretty ? 2 : null;
   }
-  return JSON.stringify(obj, toJsonReplacer, pretty);
+  return JSON.stringify(obj, toJsonReplacer, /** @type {Number} */ (pretty));
 }
 
 /**