diff --git a/README.md b/README.md index c8fe8e4..3dbd77e 100644 --- a/README.md +++ b/README.md @@ -281,6 +281,27 @@ deepest(c, 'x'); // {x: null} (a) ### Promise +#### [Never](https://thalesrc.github.io/js-utils/modules/_promise_never_.html) +A promise which never resolves + +```typescript +import { never, NEVER } from '@thalesrc/js-utils/promise'; + +function foo(promise = never()) { + promise.then(val => { + ... + }); +} + +// or + +function foo(promise = NEVER) { + promise.then(val => { + ... + }); +} +``` + #### [Revert](https://thalesrc.github.io/js-utils/modules/_promise_revert_.html) Exchanges resolve state with rejection of a promise diff --git a/package.json b/package.json index e211200..06c72c8 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,8 @@ "unique id", "replace", "remove", - "deepest" + "deepest", + "never" ], "repository": { "type": "git", diff --git a/src/promise/index.ts b/src/promise/index.ts index ce044f9..5ec29ac 100644 --- a/src/promise/index.ts +++ b/src/promise/index.ts @@ -1,3 +1,4 @@ +export * from './never'; +export * from './revert'; export * from './try-catch'; export * from './timeout'; -export * from './revert'; diff --git a/src/promise/never.spec.ts b/src/promise/never.spec.ts new file mode 100644 index 0000000..3b59045 --- /dev/null +++ b/src/promise/never.spec.ts @@ -0,0 +1,42 @@ +import 'jest'; + +import { never, NEVER } from './never'; +import { timeout } from './timeout'; + +describe('Never Function', () => { + it('should not resolve', done => { + const foo = never(); + + foo.then(() => { + throw new Error(); + }, () => { + throw new Error(); + }); + + timeout(50) + .then(() => { + done(); + }); + }); + + it('should return the same `NEVER` instance', () => { + const foo = never(); + + expect(foo).toBe(NEVER); + }); +}); + +describe('Never Constant', () => { + it('should not resolve', done => { + NEVER.then(() => { + throw new Error(); + }, () => { + throw new Error(); + }); + + timeout(50) + .then(() => { + done(); + }); + }); +}); diff --git a/src/promise/never.ts b/src/promise/never.ts new file mode 100644 index 0000000..b0d0589 --- /dev/null +++ b/src/promise/never.ts @@ -0,0 +1,39 @@ +import { noop } from '../function/noop'; + +/** + * A promise which never resolves + * + * Example: + * ```typescript + * import { NEVER } from '@thalesrc/js-utils/promise'; + * + * function foo(promise = NEVER) { + * promise.then(val => { + * ... + * }); + * } + * ``` + */ +export const NEVER = new Promise(noop); + +/** + * Creates a promise which never resolves + * + * Example: + * ```typescript + * import { never } from '@thalesrc/js-utils/promise'; + * + * function foo(promise) { + * promise = promise || never(); + * + * promise.then(val => { + * ... + * }); + * } + * ``` + * + * @returns the promise which never resolves + */ +export function never(): Promise { + return NEVER; +} diff --git a/src/promise/static/never.spec.ts b/src/promise/static/never.spec.ts new file mode 100644 index 0000000..6f430b9 --- /dev/null +++ b/src/promise/static/never.spec.ts @@ -0,0 +1,43 @@ +import 'jest'; + +import './never'; + +import { timeout } from '../timeout'; + +describe('Never Function', () => { + it('should not resolve', done => { + const foo = Promise.never(); + + foo.then(() => { + throw new Error(); + }, () => { + throw new Error(); + }); + + timeout(50) + .then(() => { + done(); + }); + }); + + it('should return the same `NEVER` instance', () => { + const foo = Promise.never(); + + expect(foo).toBe(Promise.NEVER); + }); +}); + +describe('Never Constant', () => { + it('should not resolve', done => { + Promise.NEVER.then(() => { + throw new Error(); + }, () => { + throw new Error(); + }); + + timeout(50) + .then(() => { + done(); + }); + }); +}); diff --git a/src/promise/static/never.ts b/src/promise/static/never.ts new file mode 100644 index 0000000..dd2c9c5 --- /dev/null +++ b/src/promise/static/never.ts @@ -0,0 +1,44 @@ +import { never, NEVER } from '../never'; + +declare global { + export interface PromiseConstructor { + /** + * Creates a promise which never resolves + * + * Example: + * ```typescript + * import '@thalesrc/js-utils/promise/static/never'; + * + * function foo(promise) { + * promise = promise || Promise.never(); + * + * promise.then(val => { + * ... + * }); + * } + * ``` + * + * @returns the promise which never resolves + */ + never: typeof never; + + /** + * A promise which never resolves + * + * Example: + * ```typescript + * import '@thalesrc/js-utils/promise/static/never'; + * + * function foo(promise = Promise.NEVER) { + * promise.then(val => { + * ... + * }); + * } + * ``` + */ + NEVER: typeof NEVER; + } +} + +Promise.never = never; +Promise.NEVER = NEVER;