From 946c711e90a7629b6c6165dfefec8608253f89e5 Mon Sep 17 00:00:00 2001 From: jkhsjdhjs Date: Thu, 15 Aug 2019 20:48:12 +0200 Subject: [PATCH] update documentation bump patch version --- README.md | 61 ++++++++++++++++++++++++++++++++++------------- package-lock.json | 2 +- package.json | 2 +- 3 files changed, 47 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index b40aa72..6b95477 100644 --- a/README.md +++ b/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 diff --git a/package-lock.json b/package-lock.json index a29bbe9..ef218ee 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "node-fetch-cookies", - "version": "1.2.0", + "version": "1.2.1", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 690053f..f35d96c 100644 --- a/package.json +++ b/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": {