update documentation

bump patch version

README.md

@@ -2,28 +2,51 @@
 A [node-fetch](https://github.com/bitinn/node-fetch) wrapper with support for cookies.
 It supports reading/writing from/to a JSON cookie jar and keeps cookies in memory until you call `CookieJar.save()` to reduce disk I/O.
 
-## Usage Example
+## Usage Examples
+### with file...
 ```javascript
 import {fetch, CookieJar} from "node-fetch-cookies";
 
 (async () => {
     // creates a CookieJar instance
-    let cookieJar = new CookieJar("rw", "jar.json");
+    const cookieJar = new CookieJar("rw", "jar.json");
 
     // usual fetch usage, except with one or multiple cookie jars as first parameter
-    const response = await fetch(cookieJar, "https://google.de");
+    const response = await fetch(cookieJar, "https://example.com");
 
     // save the received cookies to disk
     cookieJar.save();
 })();
 ```
 
+### ...or without
+```javascript
+import {fetch, CookieJar} from "node-fetch-cookies";
+
+(async () => {
+    const cookieJar = new CookieJar("rw");
+
+    // log in to some api
+    let response = await fetch(cookieJar, "https://example.com/api/login", {
+        method: "POST",
+        body: "credentials"
+    });
+
+    // do some requests you require login for
+    response = await fetch(cookieJar, "https://example.com/api/admin/drop-all-databases");
+
+    // and optionally log out again
+    response = await fetch(cookieJar, "https://example.com/api/logout");
+})();
+```
+
 ## Documentation
 
-### fetch(cookieJar, url, options)
+### async fetch(cookieJar, url, options)
 - `cookieJar` A [CookieJar](#class-cookiejar) instance, an array of CookieJar instances or null, if you don't want to send or store cookies.
 - `url` and `options` as in https://github.com/bitinn/node-fetch#fetchurl-options
 
+Returns a Promise resolving to a [Response](https://github.com/bitinn/node-fetch#class-response) instance on success.
 
 ### Class: CookieJar
 A class that stores cookies.
@@ -31,7 +54,7 @@ A class that stores cookies.
 #### Properties
 - `flags` The read/write flags as specified below.
 - `file` The path of the cookie jar on the disk.
-- `cookies` A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) mapping cookie names to their properties.
+- `cookies` A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) mapping hostnames to maps, which map cookie names to the respective [Cookie](#class-cookie) instance.
 
 #### new CookieJar(flags[, file, cookies])
 - `flags` A string specifying whether cookies should be read and/or written from/to the jar when passing it as parameter to [fetch](#fetchcookiejar-url-options).
@@ -41,16 +64,18 @@ A class that stores cookies.
 - `file` An optional string containing a relative or absolute path to the file on the disk to use.
 - `cookies` An optional initializer for the cookie jar - either an array of [Cookie](#class-cookie) instances or a single Cookie instance.
 
-#### addCookie(cookie[, url])
+#### addCookie(cookie[, fromURL])
 Adds a cookie to the jar.
-- `cookie` A [Cookie](#class-cookie) instance to add to the cookie jar. Alternatively this can also be a string, for example a serialized cookie received from a website. In this case `url` should be specified.
-- `url` The url a cookie has been received from.
+- `cookie` A [Cookie](#class-cookie) instance to add to the cookie jar.
+Alternatively this can also be a string, for example a serialized cookie received from a website.
+In this case `fromURL` must be specified.
+- `fromURL` The url a cookie has been received from.
 
 Returns `true` if the cookie has been added successfully. Returns `false` otherwise.
 Will log a warning to console if a cookie fails to be parsed.
 
 #### addFromFile(file)
-Reads a cookie jar from the disk and adds the contained cookies.
+Reads cookies from `file` on the disk and adds the contained cookies.
 
 #### domains()
 Returns an iterator over all domains currently stored cookies for.
@@ -59,7 +84,8 @@ Returns an iterator over all domains currently stored cookies for.
 Returns an iterator over all cookies currently stored for `domain`.
 
 #### *cookiesValid(withSession)
-Returns an iterator over all valid (non-expired) cookies. Includes session cookies if `withSession` is `true`.
+Returns an iterator over all valid (non-expired) cookies.
+- `withSession`: A boolean. Iterator will include session cookies if set to `true`.
 
 #### *cookiesAll()
 Returns an iterator over all cookies currently stored.
@@ -68,7 +94,8 @@ Returns an iterator over all cookies currently stored.
 Returns an iterator over all cookies valid for a request to `url`.
 
 #### deleteExpired(sessionEnded)
-Removes all expired cookies from the jar (including session cookies, if `sessionEnded` is `true`).
+Removes all expired cookies from the jar.
+- `sessionEnded`: A boolean. Also removes session cookies if set to `true`.
 
 #### save()
 Saves the cookie jar to disk. Only non-expired non-session cookies are saved.
@@ -86,11 +113,12 @@ An abstract representation of a cookie.
 - `secure` A boolean value representing the cookie's secure attribute. If set the cookie will only be used for `https` requests.
 - `subdomains` A boolean value specifying whether the cookie should be used for requests to subdomains of `domain` or not.
 
-#### new Cookie(cookie, url)
-- `cookie` The string representation of a cookie as send by a webserver.
+#### new Cookie(str, url)
+Creates a cookie instance from the string representation of a cookie as send by a webserver.
+- `str` The string representation of a cookie.
 - `url` The url the cookie has been received from.
 
-Will throw a `CookieParseError` if the input couldn't be parsed.
+Will throw a `CookieParseError` if `str` couldn't be parsed.
 
 #### static fromObject(obj)
 Creates a cookie instance from an already existing object with the same properties.
@@ -99,10 +127,11 @@ Creates a cookie instance from an already existing object with the same properti
 Serializes the cookie, transforming it to `name=value` so it can be used in requests.
 
 #### hasExpired(sessionEnded)
-Returns whether the cookie has expired or not. `sessionEnded` specifies whether the current session has ended, meaning if set to `true`, the function will return `true` for session cookies.
+Returns whether the cookie has expired or not.
+- `sessionEnded`: A boolean that specifies whether the current session has ended, meaning if set to `true`, the function will return `true` for session cookies.
 
 #### isValidForRequest(url)
-Returns whether the cookie is valid for a request to `url`. If not, it won't be send by the fetch wrapper.
+Returns whether the cookie is valid for a request to `url`.
 
 
 ## License

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "node-fetch-cookies",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-fetch-cookies",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "node-fetch wrapper that adds support for cookie-jars",
   "main": "src/index.mjs",
   "engines": {