docs: add readme

Author: kettanaito

README.md

@@ -0,0 +1,114 @@
+# Deferred Promise
+
+The `DeferredPromise` class is a Promise-compatible abstraction that defers resolving/rejecting promises to another closure. This class is primarily useful when one part of your system establishes as promise but another part of your system fulfills it.
+
+> This class is conceptually inspired by the [`createDeferredPromise()`](https://github.com/nodejs/node/blob/696fd4b14fc34cc2d01497a3abd9bb441b89be50/lib/internal/util.js#L468-L477) internal utility in Node.js. Unlike the Node.js implementation, however, `DeferredProimse` _extends_ a native `Promise`, allowing the consumer to handle deferred promises like regular promises (no `.promise` instance nesting).
+
+## Getting started
+
+```sh
+npm install deferred-promise
+```
+
+## Documentation
+
+- [**Class: `DeferredPromise`**](#class-deferredpromise)
+  - [`new DeferredPromise()`](#new-defferedpromise)
+  - [`deferredPromise.state`](#deferredpromisestate)
+  - [`deferredProimse.result`](#deferredpromiseresult)
+  - [`deferredPromise.resolve()`](#deferredpromiseresolve)
+  - [`deferredPromies.reject()`](#deferredpromisereject)
+
+## Class: `DeferredPromise`
+
+### `new DefferedPromise()`
+
+Creates a new instance of a deferred promise.
+
+```js
+import { DeferredPromise } from 'deferred-promise'
+
+const promise = new DeferredPromise()
+```
+
+Unlike the regular `Promise`, a deferred promise does not accept the callback function. Instead, you should use [`.resolve()`](#deferredpromiseresolve) and [`.reject()`](#deferredpromisereject) to resolve and reject the promise respectively.
+
+A deferred promise is fully compatible with the native `Promise`, which means you can pass it to the consumers that await a regular `Promise` as well.
+
+### `deferredPromise.state`
+
+- `<"pending" | "resolved" | "rejected">` **Default:** `"pending"`
+
+```js
+const promise = new DeferredPromise()
+console.log(promise.state) // "pending"
+
+promise.resolve()
+console.log(promise.state) // "resolved"
+```
+
+### `deferredPromise.result`
+
+Returns the value that has resolved the promise. If no value has been provided to the `.resolve()` call, `undefined` is returned instead.
+
+```js
+const promise = new DeferredPromise()
+promise.resolve('John')
+
+console.log(promise.result) // "John"
+```
+
+### `deferredPromise.rejectionReason`
+
+Returns the reason that has rejected the promise. If no reason has been provided to the `.reject()` call, `undefined` is returned instead.
+
+```js
+const promise = new DeferredPromise()
+promise.reject(new Error('Internal Server Error'))
+
+console.log(promise.rejectionReason) // Error
+```
+
+### `deferredPromise.resolve()`
+
+Resolves the deferred promise with a given value.
+
+```js
+function startServer() {
+  const serverReady = new DeferredPromise()
+
+  new http.Server().listen(() => {
+    // Resolve the deferred promise with the server address
+    // once the server is ready.
+    serverReady.resolve('http://localhost:8080')
+  })
+
+  // Return the deferred promise to the consumer.
+  return serverReady
+}
+
+startServer().then((address) => {
+  console.log('Server is running at "%s"', address)
+})
+```
+
+### `deferredPromise.reject()`
+
+Rejects the deferred promise with a given reason.
+
+```js
+function createBroadcast() {
+  const runtimePromise = new DeferredPromise()
+
+  receiver.on('error', (error) => {
+    // Reject the deferred promise in response
+    // to the incoming "error" event.
+    runtimePromise.reject(error)
+  })
+
+  // This deferred promise will be pending forever
+  // unless the broadcast channel receives the
+  // "error" event that rejects it.
+  return runtimePromise
+}
+```

src/DeferredPromise.ts

@@ -16,19 +16,18 @@ export type RejectFunction<Result = void> = (reason?: unknown) => Result
  * const portReady = new DeferredPromise()
  * portReady.reject(new Error('Port is already in use'))
  */
-export class DeferredPromise<Data extends any> extends Promise<Data> {
+export class DeferredPromise<Data extends any> {
   public resolve: ResolveFunction<Data>
   public reject: RejectFunction
   public state: DeferredPromiseState
   public result?: Data
   public rejectionReason?: unknown
 
-  constructor() {
-    let _resolve: ResolveFunction<Data> = () => {}
-    let _reject: RejectFunction = () => {}
+  private promise: Promise<Data>
 
-    super((resolve, reject) => {
-      _resolve = (data) => {
+  constructor() {
+    this.promise = new Promise((resolve, reject) => {
+      this.resolve = (data) => {
         if (this.state !== 'pending') {
           throw new TypeError(
             `Cannot resolve a DeferredPromise: illegal state ("${this.state}")`
@@ -40,7 +39,7 @@ export class DeferredPromise<Data extends any> extends Promise<Data> {
         resolve(data)
       }
 
-      _reject = (reason) => {
+      this.reject = (reason) => {
         if (this.state !== 'pending') {
           throw new TypeError(
             `Cannot reject a DeferredPromise: illegal state ("${this.state}")`
@@ -53,19 +52,21 @@ export class DeferredPromise<Data extends any> extends Promise<Data> {
       }
     })
 
-    this.resolve = _resolve
-    this.reject = _reject
-
     this.state = 'pending'
     this.result = undefined
     this.rejectionReason = undefined
   }
 
+  public then(onresolved?: ResolveFunction<Data>, onrejected?: RejectFunction) {
+    this.promise.then(onresolved, onrejected)
+    return this
+  }
+
   public catch<RejectReason = never>(
     onrejected?: RejectFunction<RejectReason>
-  ): DeferredPromise<Data | RejectReason> {
-    super.catch(onrejected)
-    return this as any
+  ): this {
+    this.promise.catch<RejectReason>(onrejected)
+    return this
   }
 
   static get [Symbol.species]() {

test/DeferredPromise.test.ts

@@ -4,6 +4,7 @@ it('can be listened to with ".then()"', (done) => {
   expect.assertions(1)
 
   const promise = new DeferredPromise<number>()
+
   promise.then((data) => {
     expect(data).toBe(123)
     done()
@@ -35,6 +36,7 @@ it('can be awaited', async () => {
 describe('resolve()', () => {
   it('can be resolved without data', () => {
     const promise = new DeferredPromise<void>()
+    expect(promise.state).toBe('pending')
     promise.resolve()
 
     expect(promise.state).toBe('resolved')
@@ -53,6 +55,7 @@ describe('resolve()', () => {
 
   it('throws when resolving an already resolved promise', () => {
     const promise = new DeferredPromise<number>()
+    expect(promise.state).toBe('pending')
     promise.resolve(123)
 
     expect(() => promise.resolve(456)).toThrow(
@@ -64,6 +67,7 @@ describe('resolve()', () => {
 
   it('throws when resolving an already rejected promise', () => {
     const promise = new DeferredPromise<number>().catch(() => {})
+    expect(promise.state).toBe('pending')
     promise.reject()
 
     expect(() => promise.resolve(123)).toThrow(
@@ -76,7 +80,8 @@ describe('resolve()', () => {
 
 describe('reject()', () => {
   it('can be rejected without any reason', () => {
-    const promise = new DeferredPromise<void>()
+    const promise = new DeferredPromise<void>().catch(() => {})
+    expect(promise.state).toBe('pending')
     promise.reject()
 
     expect(promise.state).toBe('rejected')
@@ -85,7 +90,7 @@ describe('reject()', () => {
   })
 
   it('can be rejected with a reason', () => {
-    const promise = new DeferredPromise()
+    const promise = new DeferredPromise().catch(() => {})
     expect(promise.state).toBe('pending')
 
     const rejectionReason = new Error('Something went wrong')