feat(predicates): Check has been deprecated in favour of Ensure. New …

…"deprecated" decorator can be u

package.json

@@ -42,6 +42,8 @@
     "@types/chai": "4.1.2",
     "@types/mocha": "2.2.48",
     "@types/node": "9.4.0",
+    "@types/sinon": "4.1.3",
+    "@types/sinon-chai": "2.7.29",
     "chai": "4.1.2",
     "cheerio": "1.0.0-rc.2",
     "commitizen": "2.9.6",
@@ -58,6 +60,8 @@
     "rimraf": "2.6.2",
     "semantic-release": "^12.4.1",
     "semantic-release-cli": "3.6.2",
+    "sinon": "4.4.2",
+    "sinon-chai": "2.14.0",
     "travis-deploy-once": "^4.3.3",
     "ts-node": "5.0.0",
     "tslint": "5.9.1",

spec/chec.spec.ts → spec/ensure.ts

@@ -1,15 +1,15 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, hasLengthOf, isArray, isDefined, isGreaterThan, isInteger, TinyType } from '../src';
+import { ensure, hasLengthOf, isArray, isDefined, isGreaterThan, isInteger, TinyType } from '../src';
 import { expect } from './expect';
 
-/** @test {check} */
-describe('::check', () => {
+/** @test {ensure} */
+describe('::ensure', () => {
 
     it(`advises the developer if they've forgotten to specify the checks`, () => {
         const value = 2;
-        expect(() => check('SomeProperty', value))
+        expect(() => ensure('SomeProperty', value))
             .to.throw(`Looks like you haven't specified any predicates to check the value against?`);
     });
 });

spec/expect.ts

@@ -1,3 +1,6 @@
 import * as chai from 'chai';
+import * as sinonChai from 'sinon-chai';
+
+chai.use(sinonChai);
 
 export const expect = chai.expect;

spec/objects/deprecated.spec.ts

@@ -0,0 +1,151 @@
+import 'mocha';
+import * as sinon from 'sinon';
+import { deprecated } from '../../src/objects';
+import { expect } from '../expect';
+
+/** @test {deprecated} */
+describe('deprecated', () => {
+
+    describe('when used to annotate a class', () => {
+        it('logs a warning when the class is constructed', () => {
+            const consoleWarn = sinon.spy();
+
+            @deprecated(undefined, consoleWarn)
+            class Foo {
+            }
+
+            const foo = new Foo();
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('Foo has been deprecated.');
+        });
+
+        it('can provide additional suggestion on what other class should be used instead', () => {
+            const consoleWarn = sinon.spy();
+
+            @deprecated('Please use Bar instead.', consoleWarn)
+            class Foo {
+            }
+
+            const foo = new Foo();
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('Foo has been deprecated. Please use Bar instead.');
+        });
+
+        it('maintains the type and behaviour of the annotated class', () => {
+            const consoleWarn = sinon.spy();
+
+            @deprecated('Please use Client instead.', consoleWarn)
+            class Person {
+                constructor(public readonly name: string) {
+                }
+            }
+
+            const p = new Person('Alice');
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('Person has been deprecated. Please use Client instead.');
+
+            expect(p).to.be.instanceOf(Person);
+        });
+    });
+
+    describe('when used to annotate a method', () => {
+
+        it('logs a warning when the method is used', () => {
+            const consoleWarn = sinon.spy();
+
+            class Person {
+                @deprecated('', consoleWarn)
+                greet()   { return null; }
+                welcome() { return null; }
+            }
+
+            const p = new Person();
+            p.greet();
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('Person#greet has been deprecated.');
+        });
+
+        it('can provide additional suggestion on what other method should be used instead', () => {
+            const consoleWarn = sinon.spy();
+
+            class Person {
+
+                @deprecated('Please use Person#welcome instead.', consoleWarn)
+                greet()   { return null; }
+                welcome() { return null; }
+            }
+
+            const p = new Person();
+            p.greet();
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('Person#greet has been deprecated. Please use Person#welcome instead.');
+        });
+
+        it('maintains the behaviour of the annotated method', () => {
+            const consoleWarn = sinon.spy();
+
+            class Person {
+                constructor(public readonly name: string) {
+                }
+
+                @deprecated('Please use Person#welcome instead.', consoleWarn)
+                greet(greeting: string) {
+                    return `${ greeting }, my name is ${this.name}`;
+                }
+            }
+
+            const p = new Person('Alice');
+
+            expect(p.greet('Hi')).to.equal('Hi, my name is Alice');
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('Person#greet has been deprecated. Please use Person#welcome instead.');
+        });
+    });
+
+    describe('when used to deprecate a function', () => {
+        it('logs a warning when the function is used', () => {
+            const consoleWarn = sinon.spy();
+
+            function foo() {
+                return null;
+            }
+
+            const deprecatedFoo = deprecated('Please use bar instead.', consoleWarn)(foo);
+
+            deprecatedFoo();
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('foo has been deprecated. Please use bar instead.');
+
+        });
+
+        it('logs a warning when an arrow function is used', () => {
+            const consoleWarn = sinon.spy();
+
+            const foo = () => null;
+
+            const deprecatedFoo = deprecated('Please use bar instead.', consoleWarn)(foo);
+
+            deprecatedFoo();
+
+            expect(consoleWarn)
+                .to.have.been.calledWith('foo has been deprecated. Please use bar instead.');
+        });
+    });
+
+    describe('when used incorrectly', () => {
+
+        it('complains', () => {
+            const consoleWarn = sinon.spy();
+
+            expect(() => deprecated('something that does not make sense')(42))
+                .to.throw(`Only a class, method or function can be marked as deprecated. number given.`);
+        });
+    })
+});

spec/predicates/and.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { and, check, isDefined, isGreaterThan, isInteger, isLessThan, or, TinyType } from '../../src';
+import { and, ensure, isDefined, isGreaterThan, isInteger, isLessThan, or, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -12,7 +12,7 @@ describe('predicates', () => {
         class InvestmentLengthInYears extends TinyType {
             constructor(public readonly value: number) {
                 super();
-                check('InvestmentLengthInYears', value, and(
+                ensure('InvestmentLengthInYears', value, and(
                     isDefined(),
                     isInteger(),
                     isGreaterThan(0),

spec/predicates/hasLengthOf.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, hasLengthOf, TinyType } from '../../src';
+import { ensure, hasLengthOf, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -15,7 +15,7 @@ describe('predicates', () => {
                 constructor(public readonly value: string) {
                     super();
 
-                    check('Password', value, hasLengthOf(8));
+                    ensure('Password', value, hasLengthOf(8));
                 }
             }
 
@@ -46,7 +46,7 @@ describe('predicates', () => {
                 constructor(public readonly values: string[]) {
                     super();
 
-                    check('Collection', values, hasLengthOf(2));
+                    ensure('Collection', values, hasLengthOf(2));
                 }
             }
 

spec/predicates/isArray.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, isArray, TinyType } from '../../src';
+import { ensure, isArray, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -13,7 +13,7 @@ describe('predicates', () => {
             constructor(public readonly values: string[]) {
                 super();
 
-                check('Collection', values, isArray());
+                ensure('Collection', values, isArray());
             }
         }
 

spec/predicates/isDefined.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, isDefined, TinyType } from '../../src';
+import { ensure, isDefined, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -12,7 +12,7 @@ describe('predicates', () => {
             constructor(public readonly value: string) {
                 super();
 
-                check('UserName', value, isDefined());
+                ensure('UserName', value, isDefined());
             }
         }
 

spec/predicates/isEqualTo.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, isEqualTo, TinyTypeOf } from '../../src';
+import { ensure, isEqualTo, TinyTypeOf } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -19,7 +19,7 @@ describe('predicates', () => {
             class AccountsService {
                 constructor(public readonly loggedInUser: AccountId) {}
                 handle(command: Command) {
-                    check('AccountId', command.value, isEqualTo(this.loggedInUser));
+                    ensure('AccountId', command.value, isEqualTo(this.loggedInUser));
                 }
             }
 
@@ -58,7 +58,7 @@ describe('predicates', () => {
                 [],
             ).
             it('ensures they are equal', (value: any) => {
-                expect(check('Val', value, isEqualTo(value))).to.not.throw;  // tslint:disable-line:no-unused-expression
+                expect(ensure('Val', value, isEqualTo(value))).to.not.throw;  // tslint:disable-line:no-unused-expression
             });
 
             given(
@@ -69,7 +69,7 @@ describe('predicates', () => {
                 [],
             ).
             it('complains if they are not equal', (value: any) => {
-                expect(() => check('Value', value, isEqualTo('expected value')))
+                expect(() => ensure('Value', value, isEqualTo('expected value')))
                     .to.throw('Value should be equal to expected value');
             });
         });

spec/predicates/isGreaterThan.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, isGreaterThan, TinyType } from '../../src';
+import { ensure, isGreaterThan, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -12,7 +12,7 @@ describe('predicates', () => {
             constructor(public readonly value: number) {
                 super();
 
-                check('InvestmentLength', value, isGreaterThan(0));
+                ensure('InvestmentLength', value, isGreaterThan(0));
             }
         }
 

spec/predicates/isGreaterThanOrEqualTo.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, isGreaterThanOrEqualTo, TinyType } from '../../src';
+import { ensure, isGreaterThanOrEqualTo, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -12,7 +12,7 @@ describe('predicates', () => {
             constructor(public readonly value: number) {
                 super();
 
-                check('InvestmentLength', value, isGreaterThanOrEqualTo(0));
+                ensure('InvestmentLength', value, isGreaterThanOrEqualTo(0));
             }
         }
 

spec/predicates/isInRange.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, isInRange, TinyType } from '../../src';
+import { ensure, isInRange, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -13,7 +13,7 @@ describe('predicates', () => {
             constructor(public readonly value: number) {
                 super();
 
-                check('InvestmentLength', value, isInRange(1, 5));
+                ensure('InvestmentLength', value, isInRange(1, 5));
             }
         }
 

spec/predicates/isInteger.spec.ts

@@ -1,7 +1,7 @@
 import 'mocha';
 import { given } from 'mocha-testdata';
 
-import { check, isInteger, TinyType } from '../../src';
+import { ensure, isInteger, TinyType } from '../../src';
 import { expect } from '../expect';
 
 describe('predicates', () => {
@@ -12,7 +12,7 @@ describe('predicates', () => {
             constructor(public readonly value: number) {
                 super();
 
-                check('AgeInYears', value, isInteger());
+                ensure('AgeInYears', value, isInteger());
             }
         }