From cb03a9fd4163ea57b9cb945fd2fd79c779cbac4a Mon Sep 17 00:00:00 2001
From: "Masahiro Miyashiro (3846masa)" <3846masahiro+git@gmail.com>
Date: Sun, 8 May 2022 00:43:25 +0900
Subject: [PATCH] feat: update README and add MIGRATION GUIDES (#110)

* docs: update README

* chore: update examples

* feat(docs): add MIGRATION.md

BREAKING CHANGE: see MIGRATION.md for more details.
---
 MIGRATION.md                        | 48 +++++++++++++++++++++++
 README.md                           | 60 +++++++++++++++++++----------
 examples/agentkeepalive/basic.mjs   |  2 +-
 examples/axios/basic.mjs            |  4 +-
 examples/axios/default.mjs          |  4 +-
 examples/axios/instance.mjs         |  4 +-
 examples/got/basic.mjs              |  4 +-
 examples/got/instance.mjs           |  4 +-
 examples/http-proxy-agent/basic.mjs |  2 +-
 examples/needle/basic.mjs           |  2 +-
 examples/node-fetch/basic.mjs       |  4 +-
 examples/node/http.mjs              |  2 +-
 examples/node/https.mjs             |  2 +-
 examples/phin/basic.mjs             |  2 +-
 examples/phin/instance.mjs          |  2 +-
 examples/request/basic.mjs          |  2 +-
 examples/request/instance.mjs       |  2 +-
 examples/superagent/basic.mjs       |  2 +-
 examples/superagent/instance.mjs    |  2 +-
 examples/urllib/basic.mjs           |  4 +-
 examples/urllib/instance.mjs        |  4 +-
 examples/wreck/basic.mjs            |  2 +-
 examples/wreck/default.mjs          |  6 +--
 examples/wreck/instance.mjs         |  6 +--
 24 files changed, 122 insertions(+), 54 deletions(-)
 create mode 100644 MIGRATION.md

diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 00000000..6b0f0178
--- /dev/null
+++ b/MIGRATION.md
@@ -0,0 +1,48 @@
+# MIGRATION GUIDES
+
+## Migration guide from v2.x.x to v3.0.0
+
+- [The import path has been changed.](#the-import-path-has-been-changed)
+- [The property name for passing cookiejar to agent has been changed.](#the-property-name-for-passing-cookiejar-to-agent-has-been-changed)
+- [Using synchronous CookieJar functions by default.](#using-synchronous-cookiejar-functions-by-default)
+
+### The import path has been changed.
+
+You should import from `'http-cookie-agent/node:http'` instead of `'http-cookie-agent'`.
+
+```diff
+  // CommonJS
+- const { HttpCookieAgent } = require('http-cookie-agent');
++ const { HttpCookieAgent } = require('http-cookie-agent/node:http');
+```
+
+```diff
+  // ES Module
+- import { HttpCookieAgent } from 'http-cookie-agent';
++ import { HttpCookieAgent } from 'http-cookie-agent/node:http';
+```
+
+### The property name for passing CookieJar to Agent has been changed.
+
+```diff
+  const jar = new CookieJar();
+  const agent = new HttpCookieAgent({
+-   jar,
++   cookies: { jar },
+  });
+```
+
+### Using synchronous CookieJar functions by default.
+
+If you use an asynchronous cookie store (e.g. `redis-cookie-store`), set `cookies.async_UNSTABLE` to true.
+
+```diff
+  const client = redis.createClient();
+  const store = new RedisCookieStore(client);
+
+  const jar = new CookieJar(store);
+  const agent = new HttpCookieAgent({
+-   cookies: { jar },
++   cookies: { async_UNSTABLE: true, jar },
+  });
+```
diff --git a/README.md b/README.md
index 1e48c6dc..33441631 100644
--- a/README.md
+++ b/README.md
@@ -34,13 +34,13 @@ import { HttpCookieAgent, HttpsCookieAgent, MixedCookieAgent } from 'http-cookie
 
 const jar = new CookieJar();
 
-const httpAgent = new HttpCookieAgent({ jar });
+const httpAgent = new HttpCookieAgent({ cookies: { jar } });
 
 // To access via HTTPS, use HttpsCookieAgent instead.
-const httpsAgent = new HttpsCookieAgent({ jar });
+const httpsAgent = new HttpsCookieAgent({ cookies: { jar } });
 
 // If the client library cannot switch Agents based on the protocol, use MixedCookieAgent instead.
-const mixedAgent = new MixedCookieAgent({ jar });
+const mixedAgent = new MixedCookieAgent({ cookies: { jar } });
 
 // Pass agent to HTTP client.
 client.request('https://example.com', { agent: httpAgent });
@@ -80,7 +80,7 @@ import { CookieJar } from 'tough-cookie';
 import { HttpsCookieAgent } from 'http-cookie-agent/node:http';
 
 const jar = new CookieJar();
-const agent = new HttpsCookieAgent({ jar });
+const agent = new HttpsCookieAgent({ cookies: { jar } });
 
 https.get('https://example.com', { agent }, (res) => {
   // ...
@@ -97,8 +97,8 @@ import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/node:http';
 const jar = new CookieJar();
 
 const client = axios.create({
-  httpAgent: new HttpCookieAgent({ jar }),
-  httpsAgent: new HttpsCookieAgent({ jar }),
+  httpAgent: new HttpCookieAgent({ cookies: { jar } }),
+  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
 });
 
 await client.get('https://example.com');
@@ -113,8 +113,8 @@ import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/node:http';
 
 const jar = new CookieJar();
 
-const httpAgent = new HttpCookieAgent({ jar });
-const httpsAgent = new HttpsCookieAgent({ jar });
+const httpAgent = new HttpCookieAgent({ cookies: { jar } });
+const httpsAgent = new HttpsCookieAgent({ cookies: { jar } });
 
 await fetch('https://example.com', {
   agent: ({ protocol }) => {
@@ -138,8 +138,8 @@ const jar = new CookieJar();
 
 const client = got.extend({
   agent: {
-    http: new HttpCookieAgent({ jar }),
-    https: new HttpsCookieAgent({ jar }),
+    http: new HttpCookieAgent({ cookies: { jar } }),
+    https: new HttpsCookieAgent({ cookies: { jar } }),
   },
 });
 
@@ -158,7 +158,7 @@ import { CookieJar } from 'tough-cookie';
 import { MixedCookieAgent } from 'http-cookie-agent/node:http';
 
 const jar = new CookieJar();
-const mixedAgent = new MixedCookieAgent({ jar });
+const mixedAgent = new MixedCookieAgent({ cookies: { jar } });
 
 const client = superagent.agent().use((req) => req.agent(mixedAgent));
 
@@ -179,7 +179,7 @@ import { MixedCookieAgent } from 'http-cookie-agent/node:http';
 const jar = new CookieJar();
 
 const client = request.defaults({
-  agent: new MixedCookieAgent({ jar }),
+  agent: new MixedCookieAgent({ cookies: { jar } }),
 });
 
 client.get('https://example.com', (_err, _res) => {
@@ -197,7 +197,7 @@ import { MixedCookieAgent } from 'http-cookie-agent/node:http';
 const jar = new CookieJar();
 
 await needle('get', 'https://example.com', {
-  agent: new MixedCookieAgent({ jar }),
+  agent: new MixedCookieAgent({ cookies: { jar } }),
 });
 ```
 
@@ -213,7 +213,7 @@ const jar = new CookieJar();
 await phin({
   url: 'https://example.com',
   core: {
-    agent: new MixedCookieAgent({ jar }),
+    agent: new MixedCookieAgent({ cookies: { jar } }),
   },
 });
 ```
@@ -229,9 +229,9 @@ const jar = new CookieJar();
 
 const client = Wreck.defaults({
   agents: {
-    http: new HttpCookieAgent({ jar }),
-    https: new HttpsCookieAgent({ jar }),
-    httpsAllowUnauthorized: new HttpsCookieAgent({ jar }),
+    http: new HttpCookieAgent({ cookies: { jar } }),
+    https: new HttpsCookieAgent({ cookies: { jar } }),
+    httpsAllowUnauthorized: new HttpsCookieAgent({ cookies: { jar } }),
   },
 });
 
@@ -248,13 +248,33 @@ import { HttpCookieAgent, HttpsCookieAgent } from 'http-cookie-agent/node:http';
 const jar = new CookieJar();
 
 const client = urllib.create({
-  agent: new HttpCookieAgent({ jar }),
-  httpsAgent: new HttpsCookieAgent({ jar }),
+  agent: new HttpCookieAgent({ cookies: { jar } }),
+  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
 });
 
 await client.request('https://example.com');
 ```
 
+### Using with an asynchronous Cookie store
+
+`http-cookie-agent` use synchronous CookieJar functions by default.
+
+Therefore, you cannot use an asynchronous Cookie store (e.g. `redis-cookie-store`) by default.
+
+If you want to use an asynchronous Cookie store, set `cookies.async_UNSTABLE` to true.
+
+```js
+// node:http, node:https
+const jar = new CookieJar();
+const agent = new HttpsCookieAgent({ cookies: { async_UNSTABLE: true, jar } });
+```
+
+```js
+// undici
+const jar = new CookieJar();
+const agent = new CookieAgent({ cookies: { async_UNSTABLE: true, jar } } });
+```
+
 ### Using with another Agent library
 
 If you want to use another Agent library, wrap the agent in `createCookieAgent`.
@@ -269,7 +289,7 @@ import { createCookieAgent } from 'http-cookie-agent/node:http';
 const Agent = createCookieAgent(KeepAliveAgent);
 
 const jar = new CookieJar();
-const agent = new Agent({ jar });
+const agent = new Agent({ cookies: { jar } });
 
 https.get('https://example.com', { agent }, (res) => {
   // ...
diff --git a/examples/agentkeepalive/basic.mjs b/examples/agentkeepalive/basic.mjs
index c8c6217f..543e52b3 100644
--- a/examples/agentkeepalive/basic.mjs
+++ b/examples/agentkeepalive/basic.mjs
@@ -7,7 +7,7 @@ import { CookieJar } from 'tough-cookie';
 const KeepAliveCookieAgent = createCookieAgent(KeepAliveAgent);
 
 const jar = new CookieJar();
-const agent = new KeepAliveCookieAgent({ jar });
+const agent = new KeepAliveCookieAgent({ cookies: { cookies: { jar } } });
 
 https.get('https://httpbin.org/cookies/set/session/userid', { agent }, (_res) => {
   jar.getCookies('https://httpbin.org').then((cookies) => {
diff --git a/examples/axios/basic.mjs b/examples/axios/basic.mjs
index 0dc8d23f..3644f3f7 100644
--- a/examples/axios/basic.mjs
+++ b/examples/axios/basic.mjs
@@ -5,8 +5,8 @@ import { CookieJar } from 'tough-cookie';
 const jar = new CookieJar();
 
 await axios.get('https://httpbin.org/cookies/set/session/userid', {
-  httpAgent: new HttpCookieAgent({ jar }),
-  httpsAgent: new HttpsCookieAgent({ jar }),
+  httpAgent: new HttpCookieAgent({ cookies: { jar } }),
+  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
 });
 
 const cookies = await jar.getCookies('https://httpbin.org');
diff --git a/examples/axios/default.mjs b/examples/axios/default.mjs
index dc11e7e6..f065dd35 100644
--- a/examples/axios/default.mjs
+++ b/examples/axios/default.mjs
@@ -5,8 +5,8 @@ import { CookieJar } from 'tough-cookie';
 const jar = new CookieJar();
 
 Object.assign(axios.defaults, {
-  httpAgent: new HttpCookieAgent({ jar }),
-  httpsAgent: new HttpsCookieAgent({ jar }),
+  httpAgent: new HttpCookieAgent({ cookies: { jar } }),
+  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
 });
 
 await axios.get('https://httpbin.org/cookies/set/session/userid');
diff --git a/examples/axios/instance.mjs b/examples/axios/instance.mjs
index 51bc730a..8f89aafb 100644
--- a/examples/axios/instance.mjs
+++ b/examples/axios/instance.mjs
@@ -5,8 +5,8 @@ import { CookieJar } from 'tough-cookie';
 const jar = new CookieJar();
 
 const client = axios.create({
-  httpAgent: new HttpCookieAgent({ jar }),
-  httpsAgent: new HttpsCookieAgent({ jar }),
+  httpAgent: new HttpCookieAgent({ cookies: { jar } }),
+  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
 });
 
 await client.get('https://httpbin.org/cookies/set/session/userid');
diff --git a/examples/got/basic.mjs b/examples/got/basic.mjs
index 7cd79029..ccddf94c 100644
--- a/examples/got/basic.mjs
+++ b/examples/got/basic.mjs
@@ -6,8 +6,8 @@ const jar = new CookieJar();
 
 await got('https://httpbin.org/cookies/set/session/userid', {
   agent: {
-    http: new HttpCookieAgent({ jar }),
-    https: new HttpsCookieAgent({ jar }),
+    http: new HttpCookieAgent({ cookies: { jar } }),
+    https: new HttpsCookieAgent({ cookies: { jar } }),
   },
 });
 
diff --git a/examples/got/instance.mjs b/examples/got/instance.mjs
index bf94fab6..96d431fb 100644
--- a/examples/got/instance.mjs
+++ b/examples/got/instance.mjs
@@ -6,8 +6,8 @@ const jar = new CookieJar();
 
 const client = got.extend({
   agent: {
-    http: new HttpCookieAgent({ jar }),
-    https: new HttpsCookieAgent({ jar }),
+    http: new HttpCookieAgent({ cookies: { jar } }),
+    https: new HttpsCookieAgent({ cookies: { jar } }),
   },
 });
 
diff --git a/examples/http-proxy-agent/basic.mjs b/examples/http-proxy-agent/basic.mjs
index 35a481b3..eaa52888 100644
--- a/examples/http-proxy-agent/basic.mjs
+++ b/examples/http-proxy-agent/basic.mjs
@@ -23,7 +23,7 @@ proxyServer.listen(9000);
 const HttpProxyCookieAgent = createCookieAgent(httpProxyAgent.HttpProxyAgent);
 
 const jar = new CookieJar();
-const agent = new HttpProxyCookieAgent({ host: '127.0.0.1', jar, port: 9000 });
+const agent = new HttpProxyCookieAgent({ cookies: { jar }, host: '127.0.0.1', port: 9000 });
 
 http.get('http://httpbin.org/cookies/set/session/userid', { agent }, (_res) => {
   jar.getCookies('http://httpbin.org').then((cookies) => {
diff --git a/examples/needle/basic.mjs b/examples/needle/basic.mjs
index dcb1e0e5..fffa99da 100644
--- a/examples/needle/basic.mjs
+++ b/examples/needle/basic.mjs
@@ -5,7 +5,7 @@ import { CookieJar } from 'tough-cookie';
 const jar = new CookieJar();
 
 await needle('get', 'https://httpbin.org/cookies/set/session/userid', {
-  agent: new MixedCookieAgent({ jar }),
+  agent: new MixedCookieAgent({ cookies: { jar } }),
 });
 
 const cookies = await jar.getCookies('https://httpbin.org');
diff --git a/examples/node-fetch/basic.mjs b/examples/node-fetch/basic.mjs
index 41eb447c..e8a3a9b5 100644
--- a/examples/node-fetch/basic.mjs
+++ b/examples/node-fetch/basic.mjs
@@ -4,8 +4,8 @@ import { CookieJar } from 'tough-cookie';
 
 const jar = new CookieJar();
 
-const httpAgent = new HttpCookieAgent({ jar });
-const httpsAgent = new HttpsCookieAgent({ jar });
+const httpAgent = new HttpCookieAgent({ cookies: { jar } });
+const httpsAgent = new HttpsCookieAgent({ cookies: { jar } });
 
 await fetch('https://httpbin.org/cookies/set/session/userid', {
   agent: ({ protocol }) => {
diff --git a/examples/node/http.mjs b/examples/node/http.mjs
index 83408234..437bc596 100644
--- a/examples/node/http.mjs
+++ b/examples/node/http.mjs
@@ -4,7 +4,7 @@ import { HttpCookieAgent } from 'http-cookie-agent/node:http';
 import { CookieJar } from 'tough-cookie';
 
 const jar = new CookieJar();
-const agent = new HttpCookieAgent({ jar });
+const agent = new HttpCookieAgent({ cookies: { jar } });
 
 http.get('http://httpbin.org/cookies/set/session/userid', { agent }, (_res) => {
   jar.getCookies('http://httpbin.org').then((cookies) => {
diff --git a/examples/node/https.mjs b/examples/node/https.mjs
index 892df7f7..53d9d315 100644
--- a/examples/node/https.mjs
+++ b/examples/node/https.mjs
@@ -4,7 +4,7 @@ import { HttpsCookieAgent } from 'http-cookie-agent/node:http';
 import { CookieJar } from 'tough-cookie';
 
 const jar = new CookieJar();
-const agent = new HttpsCookieAgent({ jar });
+const agent = new HttpsCookieAgent({ cookies: { jar } });
 
 https.get('https://httpbin.org/cookies/set/session/userid', { agent }, (_res) => {
   jar.getCookies('https://httpbin.org').then((cookies) => {
diff --git a/examples/phin/basic.mjs b/examples/phin/basic.mjs
index cc6fb11f..60d2fad1 100644
--- a/examples/phin/basic.mjs
+++ b/examples/phin/basic.mjs
@@ -6,7 +6,7 @@ const jar = new CookieJar();
 
 await phin({
   core: {
-    agent: new MixedCookieAgent({ jar }),
+    agent: new MixedCookieAgent({ cookies: { jar } }),
   },
   url: 'https://httpbin.org/cookies/set/session/userid',
 });
diff --git a/examples/phin/instance.mjs b/examples/phin/instance.mjs
index 7286b0a0..252775d4 100644
--- a/examples/phin/instance.mjs
+++ b/examples/phin/instance.mjs
@@ -6,7 +6,7 @@ const jar = new CookieJar();
 
 const client = phin.defaults({
   core: {
-    agent: new MixedCookieAgent({ jar }),
+    agent: new MixedCookieAgent({ cookies: { jar } }),
   },
 });
 
diff --git a/examples/request/basic.mjs b/examples/request/basic.mjs
index e6dc2224..a17207f6 100644
--- a/examples/request/basic.mjs
+++ b/examples/request/basic.mjs
@@ -6,7 +6,7 @@ const jar = new CookieJar();
 
 request.get(
   'https://httpbin.org/cookies/set/session/userid',
-  { agent: new MixedCookieAgent({ jar }) },
+  { agent: new MixedCookieAgent({ cookies: { jar } }) },
   (_err, _res) => {
     jar.getCookies('https://httpbin.org').then((cookies) => {
       console.log(cookies);
diff --git a/examples/request/instance.mjs b/examples/request/instance.mjs
index 11c3252c..a6a11147 100644
--- a/examples/request/instance.mjs
+++ b/examples/request/instance.mjs
@@ -5,7 +5,7 @@ import { CookieJar } from 'tough-cookie';
 const jar = new CookieJar();
 
 const client = request.defaults({
-  agent: new MixedCookieAgent({ jar }),
+  agent: new MixedCookieAgent({ cookies: { jar } }),
 });
 
 client.get('https://httpbin.org/cookies/set/session/userid', (_err, _res) => {
diff --git a/examples/superagent/basic.mjs b/examples/superagent/basic.mjs
index 94df4f10..860c8a8e 100644
--- a/examples/superagent/basic.mjs
+++ b/examples/superagent/basic.mjs
@@ -3,7 +3,7 @@ import superagent from 'superagent';
 import { CookieJar } from 'tough-cookie';
 
 const jar = new CookieJar();
-const mixedAgent = new MixedCookieAgent({ jar });
+const mixedAgent = new MixedCookieAgent({ cookies: { jar } });
 
 await superagent.get('https://httpbin.org/cookies/set/session/userid').agent(mixedAgent);
 
diff --git a/examples/superagent/instance.mjs b/examples/superagent/instance.mjs
index 28cfe7dd..3070a89e 100644
--- a/examples/superagent/instance.mjs
+++ b/examples/superagent/instance.mjs
@@ -3,7 +3,7 @@ import superagent from 'superagent';
 import { CookieJar } from 'tough-cookie';
 
 const jar = new CookieJar();
-const mixedAgent = new MixedCookieAgent({ jar });
+const mixedAgent = new MixedCookieAgent({ cookies: { jar } });
 
 const client = superagent.agent().use((req) => req.agent(mixedAgent));
 
diff --git a/examples/urllib/basic.mjs b/examples/urllib/basic.mjs
index bdc38657..9b457f73 100644
--- a/examples/urllib/basic.mjs
+++ b/examples/urllib/basic.mjs
@@ -5,8 +5,8 @@ import urllib from 'urllib';
 const jar = new CookieJar();
 
 await urllib.request('https://httpbin.org/cookies/set/session/userid', {
-  agent: new HttpCookieAgent({ jar }),
-  httpsAgent: new HttpsCookieAgent({ jar }),
+  agent: new HttpCookieAgent({ cookies: { jar } }),
+  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
 });
 
 const cookies = await jar.getCookies('https://httpbin.org');
diff --git a/examples/urllib/instance.mjs b/examples/urllib/instance.mjs
index c2ed772a..5606cd01 100644
--- a/examples/urllib/instance.mjs
+++ b/examples/urllib/instance.mjs
@@ -5,8 +5,8 @@ import urllib from 'urllib';
 const jar = new CookieJar();
 
 const client = urllib.create({
-  agent: new HttpCookieAgent({ jar }),
-  httpsAgent: new HttpsCookieAgent({ jar }),
+  agent: new HttpCookieAgent({ cookies: { jar } }),
+  httpsAgent: new HttpsCookieAgent({ cookies: { jar } }),
 });
 
 await client.request('https://httpbin.org/cookies/set/session/userid');
diff --git a/examples/wreck/basic.mjs b/examples/wreck/basic.mjs
index 7cd69c34..6c5bbbbb 100644
--- a/examples/wreck/basic.mjs
+++ b/examples/wreck/basic.mjs
@@ -5,7 +5,7 @@ import { CookieJar } from 'tough-cookie';
 const jar = new CookieJar();
 
 await Wreck.get('https://httpbin.org/cookies/set/session/userid', {
-  agent: new MixedCookieAgent({ jar }),
+  agent: new MixedCookieAgent({ cookies: { jar } }),
 });
 
 const cookies = await jar.getCookies('https://httpbin.org');
diff --git a/examples/wreck/default.mjs b/examples/wreck/default.mjs
index 3ff6c4ee..44187629 100644
--- a/examples/wreck/default.mjs
+++ b/examples/wreck/default.mjs
@@ -4,9 +4,9 @@ import { CookieJar } from 'tough-cookie';
 
 const jar = new CookieJar();
 
-Wreck.agents.http = new HttpCookieAgent({ jar });
-Wreck.agents.https = new HttpsCookieAgent({ jar });
-Wreck.agents.httpsAllowUnauthorized = new HttpsCookieAgent({ jar });
+Wreck.agents.http = new HttpCookieAgent({ cookies: { jar } });
+Wreck.agents.https = new HttpsCookieAgent({ cookies: { jar } });
+Wreck.agents.httpsAllowUnauthorized = new HttpsCookieAgent({ cookies: { jar } });
 
 await Wreck.get('https://httpbin.org/cookies/set/session/userid');
 
diff --git a/examples/wreck/instance.mjs b/examples/wreck/instance.mjs
index 99ae89b5..27852b36 100644
--- a/examples/wreck/instance.mjs
+++ b/examples/wreck/instance.mjs
@@ -6,9 +6,9 @@ const jar = new CookieJar();
 
 const client = Wreck.defaults({
   agents: {
-    http: new HttpCookieAgent({ jar }),
-    https: new HttpsCookieAgent({ jar }),
-    httpsAllowUnauthorized: new HttpsCookieAgent({ jar }),
+    http: new HttpCookieAgent({ cookies: { jar } }),
+    https: new HttpsCookieAgent({ cookies: { jar } }),
+    httpsAllowUnauthorized: new HttpsCookieAgent({ cookies: { jar } }),
   },
 });