Skip to content

Commit e2db1e2

Browse files
gkalpakbriandk
authored andcommitted
Update types and docs for angular-route and angular-mocks (DefinitelyTyped#27473)
* angular-route: Update types and docs for `IRoute` * angular-mocks: Update types and docs for 1.7 Related to angular/angular.js#16603 and angular/angular.js#16640.
1 parent 83761bf commit e2db1e2

File tree

4 files changed

+233
-33
lines changed

4 files changed

+233
-33
lines changed

types/angular-mocks/angular-mocks-tests.ts

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,6 @@ timeoutService.verifyNoPendingTasks();
8787
let intervalService: ng.IIntervalService;
8888
let intervalServiceTimeActuallyAdvanced: number;
8989

90-
intervalServiceTimeActuallyAdvanced = intervalService.flush();
9190
intervalServiceTimeActuallyAdvanced = intervalService.flush(1234);
9291

9392
///////////////////////////////////////
@@ -1516,6 +1515,23 @@ requestHandler.respond(404, { key: 'value' });
15161515
requestHandler.respond(404, { key: 'value' }, { header: 'value' });
15171516
requestHandler.respond(404, { key: 'value' }, { header: 'value' }, 'responseText');
15181517

1518+
///////////////////////////////////////
1519+
// IFlushPendingTasksService
1520+
///////////////////////////////////////
1521+
let $flushPendingTasks: ng.IFlushPendingTasksService;
1522+
$flushPendingTasks();
1523+
$flushPendingTasks(42);
1524+
1525+
///////////////////////////////////////
1526+
// IVerifyNoPendingTasksService
1527+
///////////////////////////////////////
1528+
let $verifyNoPendingTasks: ng.IVerifyNoPendingTasksService;
1529+
$verifyNoPendingTasks();
1530+
$verifyNoPendingTasks('task type');
1531+
1532+
///////////////////////////////////////
1533+
// browserTrigger
1534+
///////////////////////////////////////
15191535
browserTrigger(document.body, 'click');
15201536
browserTrigger(angular.element(document.body), 'click');
15211537
browserTrigger(angular.element(document.body), 'click', { which: 1, keys: ['ctrl'] });

types/angular-mocks/index.d.ts

Lines changed: 108 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Type definitions for Angular JS (ngMock, ngMockE2E module) 1.6
1+
// Type definitions for Angular JS (ngMock, ngMockE2E module) 1.7
22
// Project: http://angularjs.org
33
// Definitions by: Diego Vilar <https://github.com/diegovilar>
44
// Tony Curtis <https://github.com/daltin>
@@ -61,7 +61,38 @@ declare module 'angular' {
6161
// Augments the original service
6262
///////////////////////////////////////////////////////////////////////////
6363
interface ITimeoutService {
64+
/**
65+
* **Deprecated** since version 1.7.3. (Use `$flushPendingTasks` instead.)
66+
*
67+
* ---
68+
* Flushes the queue of pending tasks.
69+
*
70+
* _This method is essentially an alias of `$flushPendingTasks`._
71+
*
72+
* > For historical reasons, this method will also flush non-`$timeout` pending tasks, such as
73+
* > `$q` promises and tasks scheduled via `$applyAsync` and `$evalAsync`.
74+
*
75+
* @param delay - The maximum timeout amount to flush up until.
76+
*/
6477
flush(delay?: number): void;
78+
79+
/**
80+
* **Deprecated** since version 1.7.3. (Use `$verifyNoPendingTasks` instead.)
81+
*
82+
* ---
83+
* Verifies that there are no pending tasks that need to be flushed. It throws an error if there
84+
* are still pending tasks.
85+
*
86+
* _This method is essentially an alias of `$verifyNoPendingTasks` (called with no arguments)._
87+
*
88+
* > For historical reasons, this method will also verify non-`$timeout` pending tasks, such as
89+
* > pending `$http` requests, in-progress `$route` transitions, unresolved `$q` promises and
90+
* > tasks scheduled via `$applyAsync` and `$evalAsync`.
91+
* >
92+
* > It is recommended to use `$verifyNoPendingTasks` instead, which additionally supports
93+
* > verifying a specific type of tasks. For example, you can verify there are no pending
94+
* > timeouts with `$verifyNoPendingTasks('$timeout')`.
95+
*/
6596
verifyNoPendingTasks(): void;
6697
}
6798

@@ -71,7 +102,13 @@ declare module 'angular' {
71102
// Augments the original service
72103
///////////////////////////////////////////////////////////////////////////
73104
interface IIntervalService {
74-
flush(millis?: number): number;
105+
/**
106+
* Runs interval tasks scheduled to be run in the next `millis` milliseconds.
107+
*
108+
* @param millis - The maximum timeout amount to flush up until.
109+
* @return The amount of time moved forward.
110+
*/
111+
flush(millis: number): number;
75112
}
76113

77114
///////////////////////////////////////////////////////////////////////////
@@ -415,6 +452,65 @@ declare module 'angular' {
415452
whenRoute(method: string, url: string): mock.IRequestHandler;
416453
}
417454

455+
///////////////////////////////////////////////////////////////////////////
456+
// FlushPendingTasksService
457+
// see https://docs.angularjs.org/api/ngMock/service/$flushPendingTasks
458+
///////////////////////////////////////////////////////////////////////////
459+
interface IFlushPendingTasksService {
460+
/**
461+
* Flushes all currently pending tasks and executes the corresponding callbacks.
462+
*
463+
* Optionally, you can also pass a `delay` argument to only flush tasks that are scheduled to be
464+
* executed within `delay` milliseconds. Currently, `delay` only applies to timeouts, since all
465+
* other tasks have a delay of 0 (i.e. they are scheduled to be executed as soon as possible, but
466+
* still asynchronously).
467+
*
468+
* If no delay is specified, it uses a delay such that all currently pending tasks are flushed.
469+
*
470+
* The types of tasks that are flushed include:
471+
*
472+
* - Pending timeouts (via `$timeout`).
473+
* - Pending tasks scheduled via `$applyAsync`.
474+
* - Pending tasks scheduled via `$evalAsync`.
475+
* These include tasks scheduled via `$evalAsync()` indirectly (such as `$q` promises).
476+
*
477+
* > Periodic tasks scheduled via `$interval` use a different queue and are not flushed by
478+
* > `$flushPendingTasks()`. Use `$interval.flush(millis)` instead.
479+
*
480+
* @param millis - The number of milliseconds to flush.
481+
*/
482+
(delay?: number): void;
483+
}
484+
485+
///////////////////////////////////////////////////////////////////////////
486+
// VerifyNoPendingTasksService
487+
// see https://docs.angularjs.org/api/ngMock/service/$verifyNoPendingTasks
488+
///////////////////////////////////////////////////////////////////////////
489+
interface IVerifyNoPendingTasksService {
490+
/**
491+
* Verifies that there are no pending tasks that need to be flushed. It throws an error if there
492+
* are still pending tasks.
493+
*
494+
* You can check for a specific type of tasks only, by specifying a `taskType`.
495+
*
496+
* Available task types:
497+
*
498+
* - `$timeout`: Pending timeouts (via `$timeout`).
499+
* - `$http`: Pending HTTP requests (via `$http`).
500+
* - `$route`: In-progress route transitions (via `$route`).
501+
* - `$applyAsync`: Pending tasks scheduled via `$applyAsync`.
502+
* - `$evalAsync`: Pending tasks scheduled via `$evalAsync`.
503+
* These include tasks scheduled via `$evalAsync()` indirectly (such as `$q` promises).
504+
*
505+
* > Periodic tasks scheduled via `$interval` use a different queue and are not taken into
506+
* > account by `$verifyNoPendingTasks()`. There is currently no way to verify that there are no
507+
* > pending `$interval` tasks.
508+
*
509+
* @param taskType - The type of tasks to check for.
510+
*/
511+
(taskType?: string): void;
512+
}
513+
418514
///////////////////////////////////////////////////////////////////////////
419515
// AnimateService
420516
// see https://docs.angularjs.org/api/ngMock/service/$animate
@@ -515,6 +611,11 @@ declare module 'angular' {
515611
* for keyboard events (keydown, keypress, and keyup).
516612
*/
517613
charcode?: number;
614+
/**
615+
* [data](https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent/data) for
616+
* [CompositionEvents](https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent).
617+
*/
618+
data?: string;
518619
/**
519620
* The elapsedTime for
520621
* [TransitionEvent](https://developer.mozilla.org/docs/Web/API/TransitionEvent)
@@ -568,10 +669,11 @@ declare global {
568669
* This is a global (window) function that is only available when the `ngMock` module is included.
569670
* It can be used to trigger a native browser event on an element, which is useful for unit testing.
570671
*
571-
* @param element Either a wrapped jQuery/jqLite node or a DOM element
572-
* @param eventType Optional event type. If none is specified, the function tries to determine
573-
* the right event type for the element, e.g. `change` for `input[text]`.
574-
* @param eventData An optional object which contains additional event data used when creating the event.
672+
* @param element Either a wrapped jQuery/jqLite node or a DOM element.
673+
* @param eventType Optional event type. If none is specified, the function tries to determine the
674+
* right event type for the element, e.g. `change` for `input[text]`.
675+
* @param eventData An optional object which contains additional event data used when creating the
676+
* event.
575677
*/
576678
function browserTrigger(
577679
element: JQuery | Element,

types/angular-route/angular-route-tests.ts

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,21 @@ $routeProvider
3939
return "I return a string"
4040
}
4141
})
42+
.when('/projects/:projectId/dashboard6', {
43+
resolve: {
44+
foo: () => 'foo',
45+
bar: () => 'bar',
46+
},
47+
resolveAs: 'baz',
48+
resolveRedirectTo: [
49+
'$http',
50+
($http: ng.IHttpService) => $http.get('/is-admin').then(() => '/admin/lounge', () => undefined),
51+
],
52+
})
53+
.when('/projects/:projectId/dashboard7', {
54+
reloadOnUrl: false,
55+
resolveRedirectTo: () => (Math.random() < 0.5) ? '/some/route' : undefined,
56+
})
4257
.otherwise({ redirectTo: '/' })
4358
.otherwise({ redirectTo: ($routeParams?: ng.route.IRouteParamsService, $locationPath?: string, $locationSearch?: any) => "" })
4459
.otherwise("/");

types/angular-route/index.d.ts

Lines changed: 93 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1-
// Type definitions for Angular JS (ngRoute module) 1.3
1+
// Type definitions for Angular JS (ngRoute module) 1.7
22
// Project: http://angularjs.org
33
// Definitions by: Jonathan Park <https://github.com/park9140>
4+
// George Kalpakas <https://github.com/gkalpak>
45
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
56
// TypeScript Version: 2.3
67

@@ -52,7 +53,7 @@ declare module 'angular' {
5253
*/
5354
interface IRoute {
5455
/**
55-
* {(string|function()=}
56+
* {(string|Function)=}
5657
* Controller fn that should be associated with newly created scope or the name of a registered controller if passed as a string.
5758
*/
5859
controller?: string | InlineAnnotatedFunction;
@@ -61,56 +62,122 @@ declare module 'angular' {
6162
*/
6263
controllerAs?: string;
6364
/**
64-
* Undocumented?
65-
*/
66-
name?: string;
67-
/**
68-
* {string=|function()=}
65+
* {(string|Function)=}
6966
* Html template as a string or a function that returns an html template as a string which should be used by ngView or ngInclude directives. This property takes precedence over templateUrl.
7067
*
7168
* If template is a function, it will be called with the following parameters:
7269
*
7370
* {Array.<Object>} - route parameters extracted from the current $location.path() by applying the current route
7471
*/
75-
template?: string | { ($routeParams?: angular.route.IRouteParamsService): string; }
72+
template?: string | { ($routeParams?: IRouteParamsService): string; }
7673
/**
77-
* {string=|function()=}
74+
* {(string|Function)=}
7875
* Path or function that returns a path to an html template that should be used by ngView.
7976
*
8077
* If templateUrl is a function, it will be called with the following parameters:
8178
*
8279
* {Array.<Object>} - route parameters extracted from the current $location.path() by applying the current route
8380
*/
84-
templateUrl?: string | { ($routeParams?: angular.route.IRouteParamsService): string; }
81+
templateUrl?: string | { ($routeParams?: IRouteParamsService): string; }
8582
/**
86-
* {Object.<string, function>=} - An optional map of dependencies which should be injected into the controller. If any of these dependencies are promises, the router will wait for them all to be resolved or one to be rejected before the controller is instantiated. If all the promises are resolved successfully, the values of the resolved promises are injected and $routeChangeSuccess event is fired. If any of the promises are rejected the $routeChangeError event is fired. The map object is:
87-
*
88-
* - key - {string}: a name of a dependency to be injected into the controller.
89-
* - factory - {string|function}: If string then it is an alias for a service. Otherwise if function, then it is injected and the return value is treated as the dependency. If the result is a promise, it is resolved before its value is injected into the controller. Be aware that ngRoute.$routeParams will still refer to the previous route within these resolve functions. Use $route.current.params to access the new route parameters, instead.
83+
* {Object.<string, Function>=}
84+
* An optional map of dependencies which should be injected into the controller. If any of these
85+
* dependencies are promises, the router will wait for them all to be resolved or one to be rejected before
86+
* the controller is instantiated.
87+
* If all the promises are resolved successfully, the values of the resolved promises are injected and
88+
* `$routeChangeSuccess` event is fired. If any of the promises are rejected the `$routeChangeError` event
89+
* is fired.
90+
* For easier access to the resolved dependencies from the template, the `resolve` map will be available on
91+
* the scope of the route, under `$resolve` (by default) or a custom name specified by the `resolveAs`
92+
* property (see below). This can be particularly useful, when working with components as route templates.
93+
*
94+
* > **Note:** If your scope already contains a property with this name, it will be hidden or overwritten.
95+
* > Make sure, you specify an appropriate name for this property, that does not collide with other
96+
* > properties on the scope.
97+
*
98+
* The map object is:
99+
*
100+
* - `key` – `{string}`: a name of a dependency to be injected into the controller.
101+
* - `factory` - `{string|Function}`: If `string` then it is an alias for a service. Otherwise if function,
102+
* then it is called with `$injector#invoke()` and the return value is treated as the dependency. If the
103+
* result is a promise, it is resolved before its value is injected into the controller. Be aware that
104+
* `ngRoute.$routeParams` will still refer to the previous route within these resolve functions. Use
105+
* `$route.current.params` to access the new route parameters, instead.
90106
*/
91107
resolve?: { [key: string]: any };
92108
/**
93-
* {(string|function())=}
94-
* Value to update $location path with and trigger route redirection.
109+
* {string=}
110+
* The name under which the `resolve` map will be available on the scope of the route. If omitted, defaults
111+
* to `$resolve`.
112+
*/
113+
resolveAs?: string;
114+
/**
115+
* {(string|Function)=}
116+
* Value to update `$location` path with and trigger route redirection.
117+
*
118+
* If `redirectTo` is a function, it will be called with the following parameters:
119+
*
120+
* - `{Object.<string>}` - route parameters extracted from the current `$location.path()` by applying the
121+
* current route templateUrl.
122+
* - `{string}` - current `$location.path()`
123+
* - `{Object}` - current `$location.search()`
124+
*
125+
* The custom `redirectTo` function is expected to return a string which will be used to update
126+
* `$location.url()`. If the function throws an error, no further processing will take place and the
127+
* `$routeChangeError` event will be fired.
128+
*
129+
* Routes that specify `redirectTo` will not have their controllers, template functions or resolves called,
130+
* the `$location` will be changed to the redirect url and route processing will stop. The exception to this
131+
* is if the `redirectTo` is a function that returns `undefined`. In this case the route transition occurs
132+
* as though there was no redirection.
133+
*/
134+
redirectTo?: string | { ($routeParams?: IRouteParamsService, $locationPath?: string, $locationSearch?: any): string };
135+
/**
136+
* {Function=}
137+
* A function that will (eventually) return the value to update `$location` URL with and trigger route
138+
* redirection. In contrast to `redirectTo`, dependencies can be injected into `resolveRedirectTo` and the
139+
* return value can be either a string or a promise that will be resolved to a string.
140+
*
141+
* Similar to `redirectTo`, if the return value is `undefined` (or a promise that gets resolved to
142+
* `undefined`), no redirection takes place and the route transition occurs as though there was no
143+
* redirection.
144+
*
145+
* If the function throws an error or the returned promise gets rejected, no further processing will take
146+
* place and the `$routeChangeError` event will be fired.
147+
*
148+
* `redirectTo` takes precedence over `resolveRedirectTo`, so specifying both on the same route definition,
149+
* will cause the latter to be ignored.
150+
*/
151+
resolveRedirectTo?: angular.Injectable<(...deps: any[]) => angular.IPromise<string | undefined> | string | undefined>;
152+
/**
153+
* {boolean=true}
154+
* Reload route when any part of the URL changes (including the path) even if the new URL maps to the same
155+
* route.
95156
*
96-
* If redirectTo is a function, it will be called with the following parameters:
157+
* If the option is set to `false` and the URL in the browser changes, but the new URL maps to the same
158+
* route, then a `$routeUpdate` event is broadcasted on the root scope (without reloading the route).
97159
*
98-
* - {Object.<string>} - route parameters extracted from the current $location.path() by applying the current route templateUrl.
99-
* - {string} - current $location.path()
100-
* - {Object} - current $location.search()
101-
* - The custom redirectTo function is expected to return a string which will be used to update $location.path() and $location.search().
160+
* Defaults to `true`.
102161
*/
103-
redirectTo?: string | { ($routeParams?: angular.route.IRouteParamsService, $locationPath?: string, $locationSearch?: any): string };
162+
reloadOnUrl?: boolean;
104163
/**
105-
* Reload route when only $location.search() or $location.hash() changes.
164+
* {boolean=true}
165+
* Reload route when only `$location.search()` or `$location.hash()` changes.
166+
*
167+
* If the option is set to `false` and the URL in the browser changes, then a `$routeUpdate` event is
168+
* broadcasted on the root scope (without reloading the route).
169+
*
170+
* > Note: This option has no effect if `reloadOnUrl` is set to `false`.
106171
*
107-
* This option defaults to true. If the option is set to false and url in the browser changes, then $routeUpdate event is broadcasted on the root scope.
172+
* Defaults to `true`.
108173
*/
109174
reloadOnSearch?: boolean;
110175
/**
111-
* Match routes without being case sensitive
176+
* {boolean=false}
177+
* Match routes without being case sensitive.
178+
* If the option is set to `true`, then the particular route can be matched without being case sensitive.
112179
*
113-
* This option defaults to false. If the option is set to true, then the particular route can be matched without being case sensitive
180+
* Defaults to `false`.
114181
*/
115182
caseInsensitiveMatch?: boolean;
116183
}

0 commit comments

Comments
 (0)