add to README.

Author: bromne

README.md

@@ -49,6 +49,8 @@ const optionalEmpty1: Optional<string> = Optional.empty(); // type hinting requi
 const optionalEmpty2 = Optional.empty<string>(); // or parameterize explicitly
 ```
 
+
+
 ### operations
 
 ```ts
@@ -58,16 +60,17 @@ const optional: Optional<string> = Optional.ofNullable( /* some optional value:
 // this method is not used match.
 optional.get();
 
-// be whether a payload is present or not.
+// represent whether this is present or not.
 optional.isPresent
 
-// be whether this is empty or not. (negation of `isPresent` property)
+// represent whether this is empty or not. (negation of `isPresent` property)
 optional.isEmpty
 
-// execute the given consumer if a payload is present.
+// if a payload is present, execute the given `consumer`.
 optional.ifPresent(value => console.log(value));
 
-// execute the first argument (consumer) if a payload is present, execute the second argument (emptyAction) otherwise.
+// if a payload is present, execute the first argument (`consumer`),
+// otherwise execute the second argument (emptyAction).
 optional.ifPresentOrElse(value => console.log(value), () => console.log("empty"));
 
 // filter a payload with additional predicate.
@@ -82,18 +85,87 @@ const powerIfPositive: (x: Number) => Optional<Number>
 const numberOptional: Optional<number> = Optional.ofNullable(/* some optional value: null | number */)
 numberOptional.flatMap(value => powerIfPositive(value));
 
-// return this if this is present, return the given another optional otherwise.
+// if this is present, return this, otherwise return the given another optional.
 const another: Optional<string> = Optional.ofNullable(/* ... */);
 optional.or(another);
 
-// retrieve a payload if this is present, return the given value otherwise.
+// if this is present retrieve the payload,
+// otherwise return the given value.
 optional.orElse("bar");
 
-// retrieve a payload if this is present, return a value supplied by the given function otherwise.
+// if a payload is present, retrieve the payload, 
+// otherwise return a value supplied by the given function.
 optional.orElseGet(() => "bar");
 
-// retrieve a payload if this is present, throws an exception supplied by the given function otherwise.
+// if a payload is present, retrieve the payload,
+// otherwise throw an exception supplied by the given function.
 optional.orElseThrow(() => new Error());
+
+// if a payload is present, retrieve the payload,
+// otherwise return null.
+optional.orNull();
+
+// if a payload is present, retrieve the payload,
+// otherwise return undefined.
+optional.orUndefined();
+
+// return an appropriate result by emulating pattern matching with the given cases.
+optional.matches({
+    present: value => value.length,
+    empty: () => 0, 
+})
+
+// convert this to an Option value.
+optional.toOption();
+```
+
+### prototype-free types
+
+While `Optional`'s fluent interface for method chaining with `prototype` is usually useful and elegant,
+relying on `prototype` can cause some problems in certain situations like an external function that copies such objects *except* `prototype`.
+For example, `setState` of React reflects the given value as a state except its `prototype` (and then you will see "TypeError: undefined is not a function" in runtime though TypeScript compilation has been succeeded!).
+
+To avoid this issue, you have three options that *open* an `Optional` into a *prototype-free*, or a simple JavaScript object (associative array, string etc.).
+
+- `Option.orNull`
+- `Option.orUndefined`
+- `Option.toOption`
+
+#### `Option.orNull` and `Option.orUndefined`
+
+Using `Option.orNull` or `Option.orUndefined` is the simple way to obtain prototype-free objects.
+These methods convert an Optional<T> into a value of *type union*.
+
+`Option<T>.orNull` returns `T | null`.
+
+`Optional<T>.orUndefined` returns `T | undefined`. The `T | undefined` type is compatible with [optional parameters and properties](http://www.typescriptlang.org/docs/handbook/advanced-types.html#optional-parameters-and-properties) of TypeScript.
+
+Use `Optional.ofNullable` to restore an Optional value from a value of these type unions.
+
+```ts
+const update: <T> (original: T) => T = /* some external function */
+const optional: Optional<string> = /* some Optional object */;
+
+let nullable: string | null = optional.orNull();
+let orUndefined: string | undefined = optional.orUndefined();
+
+// update using external functions!
+nullable = update(nullable);
+orUndefined = update(orUndefined);
+
+// retore from (string | null).
+const optionalFromNullable: Optional<string> = Optional.ofNullble(nullable);
+
+// restore from (string | undefined).
+const optionalFromOrUndefined: Optional<string> = Optional.ofNullble(orUndefined);
+```
+
+#### `Option.toOption`
+
+```ts
+const optional: Optional<string> = /* some Optional value */;
+const option: Option<string> = optional.toOption();
+const optionalFromOption: Optional<string> = Optional.from(option);
 ```
 
 ## License

lib/index.ts

@@ -17,28 +17,32 @@ import { Option, Cases } from "./types";
  */
 export default abstract class Optional<T> {
     /**
-     * Returns `true` if this is present, otherwise `false`.
+     * Represents whether this is present or not.
+     * 
+     * If a payload is present, be `true` , otherwise be `false`.
      */
     abstract get isPresent(): boolean;
 
     /**
-     * Returns true if this is empty, otherwise false.
-     * This method is negation of `Optional.isPresent`.
+     * Represents whether this is empty or not.
      * 
+     * If this is empty, be `true`, otherwise  be `false`.
+     * This method is negation of `Optional.isPresent`.
      */
     get isEmpty(): boolean {
         return !this.isPresent;
     }
 
     /**
+     * Force to retrieve the payload.
      * If a payload is present, returns the payload, otherwise throws `TypeError`.
      * 
      * @throws {TypeError} if this is empty.
      */
     abstract get(): T;
 
     /**
-     * If a payload is present, executes the given `consumer`, otherwise not.
+     * If a payload is present, executes the given `consumer`, otherwise does nothing.
      * 
      * @param consumer a consumer of the payload
      */
@@ -54,6 +58,8 @@ export default abstract class Optional<T> {
     abstract ifPresentOrElse(consumer: (value: T) => void, emptyAction: () => void): void;
 
     /**
+     * Filters a payload with an additional `predicate`.
+     * 
      * If a payload is present and the payload matches the given `predicate`, returns `this`,
      * otherwise returns an empty `Optional` even if this is present.
      * 
@@ -62,6 +68,8 @@ export default abstract class Optional<T> {
     abstract filter(predicate: (value: T) => boolean): Optional<T>;
 
     /**
+     * Maps a payload with a mapper.
+     * 
      * If a payload is present, returns an `Optional` as if applying `Optional.ofNullable` to the result of
      * applying the given `mapper` to the payload,
      * otherwise returns an empty `Optional`.
@@ -71,6 +79,8 @@ export default abstract class Optional<T> {
     abstract map<U> (mapper: (value: T) => U): Optional<U>;
 
     /**
+     * Maps a payload with a mapper which returns Optional as a result.
+     * 
      * If a payload is present, returns the result of applying the given `mapper` to the payload,
      * otherwise returns an empty `Optional`.
      * 
@@ -110,11 +120,6 @@ export default abstract class Optional<T> {
      */
     abstract orElseThrow<U>(errorSupplier: () => U): T;
 
-    /**
-     * Converts this to an `Option`.
-     */
-    abstract toOption(): Option<T>;
-
     /**
      * If a payload is present, returns the payload,
      * otherwise returns `null`.
@@ -127,6 +132,11 @@ export default abstract class Optional<T> {
      */
     abstract orUndefined(): T | undefined;
 
+    /**
+     * Converts this to an `Option`.
+     */
+    abstract toOption(): Option<T>;
+
     /**
      * Returns an appropriate result by emulating pattern matching with the given `cases`.
      * If a payload is present, returns the result of `present` case,

test/OptionalTest.ts

@@ -312,18 +312,6 @@ describe("Optional", () => {
         });
     });
 
-    describe("#toOption", () => {
-        it("returns a Some value when it is present.", () => {
-            let actual = sutPresent.toOption();
-            assert.equal(actual.kind, "present");
-        });
-
-        it("returns a None value when it is empty.", () => {
-            let actual = sutEmpty.toOption();
-            assert.equal(actual.kind, "empty");
-        });
-    });
-
     describe("#orNull", () => {
         it("returns the original payload when it is present.", () => {
             let actual = sutPresent.orNull();
@@ -348,6 +336,18 @@ describe("Optional", () => {
         }); 
     });
 
+    describe("#toOption", () => {
+        it("returns a Some value when it is present.", () => {
+            let actual = sutPresent.toOption();
+            assert.equal(actual.kind, "present");
+        });
+
+        it("returns a None value when it is empty.", () => {
+            let actual = sutEmpty.toOption();
+            assert.equal(actual.kind, "empty");
+        });
+    });
+
     describe("#matches", () => {
         let cases: Cases<string, number> = {
             present: x => x.length,