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

@@ -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 },
+  });
+```

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) => {
   // ...

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) => {

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');

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');

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');

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 } }),
   },
 });
 

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 } }),
   },
 });
 

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) => {

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');

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 }) => {

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) => {

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) => {

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',
 });

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 } }),
   },
 });
 

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);

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) => {

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);
 

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));
 

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');

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');

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');