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