userData -> context

readme.md

@@ -174,11 +174,41 @@ Type: `object | Array | number | string | boolean | null` *(JSON-serializable va
 
 JSON body. If the `Content-Type` header is not set, it will be set to `application/json`.
 
-###### userData
+###### context
 
 Type: `unknown`
 
-User data. In contrast to other options, `userData` is not enumerable.
+User data. In contrast to other options, `context` is not enumerable. Example:
+
+```js
+const got = require('got');
+
+const instance = got.extend({
+	hooks: {
+		afterResponse: [
+			response => {
+				const {context} = response.request.options;
+				context.latestFetchedSite = response.url;
+			}
+		]
+	}
+});
+
+(async () => {
+	const context = {
+		latestFetchedSite: ''
+	};
+
+	const response = await instance('https://example.com', {context});
+
+	// Let's see our user data
+	console.log(context.latestFetchedSite); // => https://example.com/
+
+	// `context` won't be displayed here, because it's not enumerable.
+	// Of course, you can access it in the following way: response.request.options.context
+	console.log(response.request.options);
+})();
+```
 
 ###### responseType
 

source/merge.ts

@@ -38,12 +38,12 @@ export default function merge<Target extends Record<string, unknown>, Source ext
 			}
 		}
 
-		if (Reflect.has(source, 'userData')) {
-			Object.defineProperty(target, 'userData', {
+		if (Reflect.has(source, 'context')) {
+			Object.defineProperty(target, 'context', {
 				writable: true,
 				configurable: true,
 				enumerable: false,
-				value: source.userData
+				value: source.context
 			});
 		}
 	}

source/utils/types.ts

@@ -142,7 +142,7 @@ export interface Options extends Omit<https.RequestOptions, 'agent' | 'timeout'
 	useElectronNet?: boolean;
 	form?: Record<string, any>;
 	json?: Record<string, any>;
-	userData?: unknown;
+	context?: object;
 }
 
 export interface NormalizedOptions extends Omit<Required<Options>, 'timeout' | 'dnsCache' | 'retry'> {

test/arguments.ts

@@ -263,43 +263,53 @@ test('throws if the `searchParams` value is invalid', async t => {
 	});
 });
 
-test('`userData` option is not enumerable', withServer, async (t, server, got) => {
+test('`context` option is not enumerable', withServer, async (t, server, got) => {
 	server.get('/', echoUrl);
 
+	const context = {
+		foo: 'bar'
+	};
+
 	await got({
-		userData: 123,
+		context,
 		hooks: {
 			beforeRequest: [
 				options => {
-					t.is(options.userData, 123);
-					t.false({}.propertyIsEnumerable.call(options, 'userData'));
+					t.is(options.context, context);
+					t.false({}.propertyIsEnumerable.call(options, 'context'));
 				}
 			]
 		}
 	});
 });
 
-test('`userData` option is accessible when using hooks', withServer, async (t, server, got) => {
+test('`context` option is accessible when using hooks', withServer, async (t, server, got) => {
 	server.get('/', echoUrl);
 
+	const context = {
+		foo: 'bar'
+	};
+
 	await got({
-		userData: 123,
+		context,
 		hooks: {
 			init: [
 				options => {
-					t.is(options.userData, 123);
-					t.false({}.propertyIsEnumerable.call(options, 'userData'));
+					t.is(options.context, context);
+					t.false({}.propertyIsEnumerable.call(options, 'context'));
 				}
 			]
 		}
 	});
 });
 
-test('`userData` option is accessible when extending instances', t => {
-	const instance = got.extend({
-		userData: 123
-	});
+test('`context` option is accessible when extending instances', t => {
+	const context = {
+		foo: 'bar'
+	};
+
+	const instance = got.extend({context});
 
-	t.is(instance.defaults.options.userData, 123);
-	t.false({}.propertyIsEnumerable.call(instance.defaults.options, 'userData'));
+	t.is(instance.defaults.options.context, context);
+	t.false({}.propertyIsEnumerable.call(instance.defaults.options, 'context'));
 });