add a proper documentation

featuring an actually working usage example!

also: change exports in index.mjs for easier import

README.md

@@ -1,13 +1,85 @@
 # node-fetch-cookies
-node-fetch wrapper that adds support for cookie-jars
+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.
 
-## Example Usage
+## Usage Example
 ```javascript
-import cookies from "node-fetch-cookies";
+import {fetch, CookieJar} from "node-fetch-cookies";
-// "rw" are the flags, meaning cookies will be read and written from/to the cookie jar. r = read, w = write
+
-// second argument is the filename, can also be undefined if you don't want to read/write the cookies from/to a file
+(async () => {
-let cookieJar = new cookies.CookieJar("rw", "path/to/file.json");
+    // creates a CookieJar instance
-// first parameter is the url, second the options, just like node-fetch. third parameter is the cookie jar (can also be an array)
+    let cookieJar = new CookieJar("rw", "jar.json");
-// returns a response object just like node-fetch
+
-cookies.fetch("https://example.page/example/path", null, cookieJar);
+    // usual fetch usage, except with one or multiple cookie jars as first parameter
+    const response = await fetch(cookieJar, "https://google.de");
+
+    // save the received cookies to disk
+    cookieJar.save();
+})();
 ```
+
+## Documentation
+
+### fetch(cookieJar, url, options)
+- `cookieJar` A [CookieJar](#class-cookiejar) instance or an array of CookieJar instances
+- `url` and `options` as in https://github.com/bitinn/node-fetch#fetchurl-options
+
+
+### Class: CookieJar
+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.
+
+#### 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).
+    - `r`: only read from this jar
+    - `w`: only write to this jar
+    - `rw` or `wr`: read/write from/to this jar
+- `file` A 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])
+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 the string received from a website. In this case `url` should be specified.
+- `url` The url a cookie has been received from.
+
+#### forEach(callback)
+Just a wrapper for `CookieJar.cookies.forEach(callback)`.
+
+#### save()
+Saves the cookie jar to disk. Only non-expired cookies are saved.
+
+
+### Class: Cookie
+An abstract representation of a cookie.
+
+#### Properties
+- `name` The identifier of the cookie.
+- `value` The value of the cookie.
+- `expiry` A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object of the cookies expiry date.
+- `domain` The domain the cookie is valid for.
+- `path` The path the cookie is valid for.
+- `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 subdomains of the domain or not.
+
+#### new Cookie(cookie, url)
+- `cookie` The string representation of a cookie as send by a webserver.
+- `url` The url the cookie has been received from.
+
+#### static fromObject(obj)
+Creates a cookie instance from an already existing object with the same properties.
+
+#### serialize()
+Serializes the cookie, transforming it to `name=value` so it can be used in requests.
+
+#### hasExpired()
+Returns whether the cookie has expired or not.
+
+#### isValidForRequest(url)
+Returns whether the cookie is valid for a request to `url`. If not, it won't be send by the fetch wrapper.
+
+## License
+This project is licensed under the MIT license, see [LICENSE](LICENSE).

package-lock.json

@@ -1,13 +1,13 @@
 {
   "name": "node-fetch-cookies",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {
     "node-fetch": {
-      "version": "2.3.0",
+      "version": "2.6.0",
-      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.3.0.tgz",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.0.tgz",
-      "integrity": "sha512-MOd8pV3fxENbryESLgVIeaGKrdl+uaYhCSSVkjeOb/31/njTpcis5aWfdqgNlHIrKOLRbMnfPINPOML2CIFeXA=="
+      "integrity": "sha512-8dG4H5ujfvFiqDmVu9fQ5bOHUC15JMjMY/Zumv26oOvvVJjM67KF8koCWIabKQ1GJIa9r2mMZscBq/TbdOcmNA=="
     }
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-fetch-cookies",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "node-fetch wrapper that adds support for cookie-jars",
   "main": "src/index.mjs",
   "engines": {
@@ -26,6 +26,6 @@
   },
   "homepage": "https://github.com/jkhsjdhjs/node-fetch-cookies#readme",
   "dependencies": {
-    "node-fetch": "^2.3.0"
+    "node-fetch": "^2.6.0"
   }
 }

src/cookie-jar.mjs

@@ -35,7 +35,7 @@ export default class CookieJar {
         // only save cookies that haven't expired
         let cookiesToSave = new Map();
         this.forEach(cookie => {
-            if(cookie.expiry && cookie.expiry > new Date())
+            if(!cookie.hasExpired())
                 cookiesToSave.set(cookie.name, cookie);
         });
         fs.writeFileSync(this.file, JSON.stringify([...cookiesToSave]));

src/cookie.mjs

@@ -90,8 +90,11 @@ export default class Cookie {
     serialize() {
         return this.name + "=" + this.value;
     }
+    hasExpired() {
+        return this.expiry && this.expiry < new Date();
+    }
     isValidForRequest(url) {
-        if(this.expiry && this.expiry < new Date())
+        if(this.hasExpired())
             return false;
         const parsedURL = urlParser.parse(url);
         if(parsedURL.protocol !== "http:" && parsedURL.protocol !== "https:")

src/index.mjs

@@ -2,8 +2,7 @@ import fetch from "node-fetch";
 import CookieJar from "./cookie-jar";
 import Cookie from "./cookie";
 
-export default {
+async function cookieFetch(cookieJars, url, options) {
-    fetch: async (url, options, cookieJars) => {
     let cookies = "";
     if(Array.isArray(cookieJars) && cookieJars.every(c => c instanceof CookieJar)) {
         cookieJars.forEach(jar => {
@@ -29,7 +28,7 @@ export default {
                 headers: {}
             };
         }
-            if(!options.headers)
+        else if(!options.headers)
             options.headers = {};
         options.headers.cookie = cookies.slice(0, -2);
     }
@@ -49,7 +48,6 @@ export default {
         }
     }
     return result;
-    },
+}
-    CookieJar: CookieJar,
+
-    Cookie: Cookie
+export {cookieFetch as fetch, CookieJar, Cookie};
-};