Skip to content

Commit f078762

Browse files
btfordIgorMinar
btford
authored and
IgorMinar
committed
chore($q): rename promise.always to promise.finally
BREAKING CHANGE: the `always` method has been renamed to `finally`. The reason for this change is to align `$q` with the Q promises library, despite the fact that this makes it a bit more difficult to use with non-ES5 browsers, like IE8. `finally` also goes well together with `catch` api that was added to $q recently and is part of the DOM promises standard. To migrate the code follow the example below: Before: $http.get('/foo').always(doSomething); After: $http.get('/foo').finally(doSomething); or for IE8 compatible code: $http.get('/foo')['finally'](doSomething);
1 parent 3ee744c commit f078762

2 files changed

Lines changed: 39 additions & 37 deletions

File tree

‎src/ng/q.js‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,12 +93,16 @@
9393
*
9494
* - `catch(errorCallback)` – shorthand for `promise.then(null, errorCallback)`
9595
*
96-
* - `always(callback)` – allows you to observe either the fulfillment or rejection of a promise,
96+
* - `finally(callback)` – allows you to observe either the fulfillment or rejection of a promise,
9797
* but to do so without modifying the final value. This is useful to release resources or do some
9898
* clean-up that needs to be done whether the promise was rejected or resolved. See the [full
9999
* specification](https://github.com/kriskowal/q/wiki/API-Reference#promisefinallycallback) for
100100
* more information.
101101
*
102+
* Because `finally` is a reserved word in JavaScript and reserved keywords are not supported as
103+
* property names by ES3, you'll need to invoke the method like `promise['finally'](callback)` to
104+
* make your code IE8 compatible.
105+
*
102106
* # Chaining promises
103107
*
104108
* Because calling the `then` method of a promise returns a new derived promise, it is easily possible
@@ -274,7 +278,7 @@ function qFactory(nextTick, exceptionHandler) {
274278
return this.then(null, callback);
275279
},
276280

277-
always: function(callback) {
281+
"finally": function(callback) {
278282

279283
function makePromise(value, resolved) {
280284
var result = defer();

‎test/ng/qSpec.js‎

Lines changed: 33 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ describe('q', function() {
4343
return map(sliceArgs(args), _argToString).join(',');
4444
}
4545

46-
// Help log invocation of success(), always(), progress() and error()
46+
// Help log invocation of success(), finally(), progress() and error()
4747
function _logInvocation(funcName, args, returnVal, throwReturnVal) {
4848
var logPrefix = funcName + '(' + _argumentsToString(args) + ')';
4949
if (throwReturnVal) {
@@ -78,14 +78,14 @@ describe('q', function() {
7878
/**
7979
* Creates a callback that logs its invocation in `log`.
8080
*
81-
* @param {(number|string)} name Suffix for 'always' name. e.g. always(1) => always
81+
* @param {(number|string)} name Suffix for 'finally' name. e.g. finally(1) => finally
8282
* @param {*=} returnVal Value that the callback should return. If unspecified, the passed in
8383
* value is returned.
8484
* @param {boolean=} throwReturnVal If true, the `returnVal` will be thrown rather than returned.
8585
*/
86-
function always(name, returnVal, throwReturnVal) {
86+
function fin(name, returnVal, throwReturnVal) {
8787
var returnValDefined = (arguments.length >= 2);
88-
name = 'always' + (name || '');
88+
name = 'finally' + (name || '');
8989
return function() {
9090
return _logInvocation(name, arguments, (returnValDefined ? returnVal : arguments[0]), throwReturnVal);
9191
}
@@ -520,8 +520,8 @@ describe('q', function() {
520520
expect(typeof promise['catch']).toBe('function');
521521
});
522522

523-
it('should have a always method', function() {
524-
expect(typeof promise.always).toBe('function');
523+
it('should have a finally method', function() {
524+
expect(typeof promise['finally']).toBe('function');
525525
});
526526

527527

@@ -733,51 +733,49 @@ describe('q', function() {
733733
});
734734

735735

736-
describe('always', function() {
736+
describe('finally', function() {
737737

738738
it('should not take an argument',
739739
function() {
740-
promise.always(always(1))
740+
promise['finally'](fin(1))
741741
syncResolve(deferred, 'foo');
742-
expect(logStr()).toBe('always1()');
742+
expect(logStr()).toBe('finally1()');
743743
});
744744

745745
describe("when the promise is fulfilled", function () {
746746

747747
it('should call the callback',
748748
function() {
749-
promise.then(success(1))
750-
.always(always(1))
749+
promise.then(success(1))['finally'](fin(1))
751750
syncResolve(deferred, 'foo');
752-
expect(logStr()).toBe('success1(foo)->foo; always1()');
751+
expect(logStr()).toBe('success1(foo)->foo; finally1()');
753752
});
754753

755754
it('should fulfill with the original value',
756755
function() {
757-
promise.always(always('B', 'b'), error('B')).
756+
promise['finally'](fin('B', 'b'), error('B')).
758757
then(success('BB', 'bb'), error('BB'));
759758
syncResolve(deferred, 'RESOLVED_VAL');
760-
expect(log).toEqual(['alwaysB()->b',
759+
expect(log).toEqual(['finallyB()->b',
761760
'successBB(RESOLVED_VAL)->bb']);
762761
});
763762

764763

765764
it('should fulfill with the original value (larger test)',
766765
function() {
767766
promise.then(success('A', 'a'), error('A'));
768-
promise.always(always('B', 'b'), error('B')).
767+
promise['finally'](fin('B', 'b'), error('B')).
769768
then(success('BB', 'bb'), error('BB'));
770-
promise.then(success('C', 'c'), error('C'))
771-
.always(always('CC', 'IGNORED'))
769+
promise.then(success('C', 'c'), error('C'))['finally'](fin('CC', 'IGNORED'))
772770
.then(success('CCC', 'cc'), error('CCC'))
773771
.then(success('CCCC', 'ccc'), error('CCCC'))
774772
syncResolve(deferred, 'RESOLVED_VAL');
775773

776774
expect(log).toEqual(['successA(RESOLVED_VAL)->a',
777-
'alwaysB()->b',
775+
'finallyB()->b',
778776
'successC(RESOLVED_VAL)->c',
779777
'successBB(RESOLVED_VAL)->bb',
780-
'alwaysCC()->IGNORED',
778+
'finallyCC()->IGNORED',
781779
'successCCC(c)->cc',
782780
'successCCCC(cc)->ccc']);
783781
});
@@ -791,12 +789,12 @@ describe('q', function() {
791789
var returnedDef = defer();
792790
returnedDef.resolve('bar');
793791

794-
promise.always(always(1, returnedDef.promise))
792+
promise['finally'](fin(1, returnedDef.promise))
795793
.then(success(2))
796794

797795
syncResolve(deferred, 'foo');
798796

799-
expect(logStr()).toBe('always1()->{}; success2(foo)->foo');
797+
expect(logStr()).toBe('finally1()->{}; success2(foo)->foo');
800798
});
801799
});
802800

@@ -805,21 +803,21 @@ describe('q', function() {
805803
function () {
806804
var returnedDef = defer()
807805
returnedDef.reject('bar');
808-
promise.always(always(1, returnedDef.promise))
806+
promise['finally'](fin(1, returnedDef.promise))
809807
.then(success(2), error(1))
810808
syncResolve(deferred, 'foo');
811-
expect(logStr()).toBe('always1()->{}; error1(bar)->reject(bar)');
809+
expect(logStr()).toBe('finally1()->{}; error1(bar)->reject(bar)');
812810
});
813811
});
814812

815813
});
816814

817815
describe("when the callback throws an exception", function() {
818816
it("should reject with this new exception", function() {
819-
promise.always(always(1, "exception", true))
817+
promise['finally'](fin(1, "exception", true))
820818
.then(success(1), error(2))
821819
syncResolve(deferred, 'foo');
822-
expect(logStr()).toBe('always1()->throw(exception); error2(exception)->reject(exception)');
820+
expect(logStr()).toBe('finally1()->throw(exception); error2(exception)->reject(exception)');
823821
});
824822
});
825823

@@ -829,17 +827,17 @@ describe('q', function() {
829827
describe("when the promise is rejected", function () {
830828

831829
it("should call the callback", function () {
832-
promise.always(always(1))
830+
promise['finally'](fin(1))
833831
.then(success(2), error(1))
834832
syncReject(deferred, 'foo');
835-
expect(logStr()).toBe('always1(); error1(foo)->reject(foo)');
833+
expect(logStr()).toBe('finally1(); error1(foo)->reject(foo)');
836834
});
837835

838836
it('should reject with the original reason', function() {
839-
promise.always(always(1), "hello")
837+
promise['finally'](fin(1), "hello")
840838
.then(success(2), error(2))
841839
syncReject(deferred, 'original');
842-
expect(logStr()).toBe('always1(); error2(original)->reject(original)');
840+
expect(logStr()).toBe('finally1(); error2(original)->reject(original)');
843841
});
844842

845843
describe("when the callback returns a promise", function() {
@@ -849,10 +847,10 @@ describe('q', function() {
849847
it("should reject with the original reason after that promise resolves", function () {
850848
var returnedDef = defer()
851849
returnedDef.resolve('bar');
852-
promise.always(always(1, returnedDef.promise))
850+
promise['finally'](fin(1, returnedDef.promise))
853851
.then(success(2), error(2))
854852
syncReject(deferred, 'original');
855-
expect(logStr()).toBe('always1()->{}; error2(original)->reject(original)');
853+
expect(logStr()).toBe('finally1()->{}; error2(original)->reject(original)');
856854
});
857855

858856
});
@@ -862,10 +860,10 @@ describe('q', function() {
862860
it("should reject with the new reason", function() {
863861
var returnedDef = defer()
864862
returnedDef.reject('bar');
865-
promise.always(always(1, returnedDef.promise))
863+
promise['finally'](fin(1, returnedDef.promise))
866864
.then(success(2), error(1))
867865
syncResolve(deferred, 'foo');
868-
expect(logStr()).toBe('always1()->{}; error1(bar)->reject(bar)');
866+
expect(logStr()).toBe('finally1()->{}; error1(bar)->reject(bar)');
869867
});
870868

871869
});
@@ -875,10 +873,10 @@ describe('q', function() {
875873
describe("when the callback throws an exception", function() {
876874

877875
it("should reject with this new exception", function() {
878-
promise.always(always(1, "exception", true))
876+
promise['finally'](fin(1, "exception", true))
879877
.then(success(1), error(2))
880878
syncResolve(deferred, 'foo');
881-
expect(logStr()).toBe('always1()->throw(exception); error2(exception)->reject(exception)');
879+
expect(logStr()).toBe('finally1()->throw(exception); error2(exception)->reject(exception)');
882880
});
883881

884882
});

0 commit comments

Comments
 (0)