Add 'path' parameter to the mapper function

index.d.ts

@@ -22,7 +22,20 @@ export type Mapper<
 > = (
 	sourceKey: keyof SourceObjectType,
 	sourceValue: SourceObjectType[keyof SourceObjectType],
-	source: SourceObjectType
+	source: SourceObjectType,
+	/**
+	When using `deep: true`, this is the sequence of keys to reach the current value from the `source`, otherwise it is an empty array.
+	For arrays, the key is the index of the element being mapped.
+	@example
+	import mapObject from 'map-obj';
+	const object = {foo: {bar: [2], baz: [1, 2, 3]}}
+	const mapper = (key, value, source, path) => path.join(".") === "foo.baz" ? [key, 3] : [key, value];
+	const result = mapObject(object, mapper, {deep: true});
+
+	console.log(result);
+	//=> {foo: {bar:[2], baz: [3, 3, 3]}}
+	 */
+	path: string[],
 ) => [
 	targetKey: MappedObjectKeyType,
 	targetValue: MappedObjectValueType,

index.js

@@ -10,7 +10,7 @@ const isObjectCustom = value =>
 
 export const mapObjectSkip = Symbol('mapObjectSkip');
 
-const _mapObject = (object, mapper, options, isSeen = new WeakMap()) => {
+const _mapObject = (object, mapper, options, {isSeen = new WeakMap(), path = []} = {}) => {
 	options = {
 		deep: false,
 		target: {},
@@ -26,13 +26,18 @@ const _mapObject = (object, mapper, options, isSeen = new WeakMap()) => {
 	const {target} = options;
 	delete options.target;
 
-	const mapArray = array => array.map(element => isObjectCustom(element) ? _mapObject(element, mapper, options, isSeen) : element);
+	const mapArray = (array, arrayPath) => array.map((element, index) =>
+		isObjectCustom(element)
+			? _mapObject(element, mapper, options, {isSeen, path: [...arrayPath, index]})
+			: element,
+	);
+
 	if (Array.isArray(object)) {
-		return mapArray(object);
+		return mapArray(object, path);
 	}
 
 	for (const [key, value] of Object.entries(object)) {
-		const mapResult = mapper(key, value, object);
+		const mapResult = mapper(key, value, object, options.deep ? [...path, key] : []);
 
 		if (mapResult === mapObjectSkip) {
 			continue;
@@ -47,8 +52,8 @@ const _mapObject = (object, mapper, options, isSeen = new WeakMap()) => {
 
 		if (options.deep && shouldRecurse && isObjectCustom(newValue)) {
 			newValue = Array.isArray(newValue)
-				? mapArray(newValue)
-				: _mapObject(newValue, mapper, options, isSeen);
+				? mapArray(newValue, [...path, key])
+				: _mapObject(newValue, mapper, options, {isSeen, path: [...path, key]});
 		}
 
 		target[newKey] = newValue;

readme.md

@@ -38,10 +38,29 @@ The source object to copy properties from.
 
 #### mapper
 
-Type: `(sourceKey, sourceValue, source) => [targetKey, targetValue, mapperOptions?] | mapObjectSkip`
+Type: `(sourceKey, sourceValue, source, path) => [targetKey, targetValue, mapperOptions?] | mapObjectSkip`
 
 A mapping function.
 
+##### path
+
+Type: `string[]`
+
+When using `deep: true`, this is the sequence of keys to reach the current value from the `source`, otherwise it is an empty array.
+
+For arrays, the key is the index of the element being mapped.
+
+```js
+import mapObject from 'map-obj';
+
+const object = {foo: {bar: [2], baz: [1, 2, 3]}}
+const mapper = (key, value, source, path) => path.join(".") === "foo.baz" ? [key, 3] : [key, value];
+const result = mapObject(object, mapper, {deep: true});
+
+console.log(result);
+//=> {foo: {bar:[2], baz: [3, 3, 3]}}
+```
+
 ##### mapperOptions
 
 Type: `object`

test.js

@@ -186,3 +186,76 @@ test('remove keys (#36)', t => {
 	const actual = mapObject(object, mapper, {deep: true});
 	t.deepEqual(actual, expected);
 });
+
+test('mapper `path` argument', t => {
+	t.plan(10);
+
+	const subject = {
+		one: 1,
+		nested: {
+			two: 2,
+			deep: {
+				three: 3,
+			},
+
+			array: [4, 5, 6],
+		},
+	};
+
+	mapObject(
+		subject,
+		(key, value, source, path) => {
+			t.true(Array.isArray(path));
+			t.is(path.length, 0);
+			return [key, value];
+		},
+	);
+
+	mapObject(
+		subject,
+		(key, value, source, path) => {
+			t.true(Array.isArray(path));
+			return [key, value];
+		},
+		{deep: true},
+	);
+});
+
+test('mapper argument `path` contains the sequence of keys to reach the current value from the source', t => {
+	const subject = {
+		one: 1,
+		nested: {
+			two: 2,
+			deep: {
+				three: 3,
+			},
+			simpleArray: [4, 5, 6],
+			complexArray: [
+				{seven: 7},
+				{eight: 8},
+			],
+		},
+	};
+
+	const expectations = {
+		one: 1,
+		nested: subject.nested,
+		'nested.two': 2,
+		'nested.deep': subject.nested.deep,
+		'nested.deep.three': 3,
+		'nested.simpleArray': subject.nested.simpleArray,
+		'nested.complexArray': subject.nested.complexArray,
+		'nested.complexArray.0.seven': 7,
+		'nested.complexArray.1.eight': 8,
+	};
+
+	const mapper = (key, value, source, path) => {
+		t.true(Array.isArray(path));
+		t.is(path.at(-1), key);
+		const expectedValue = expectations[path.join('.')];
+		t.is(value, expectedValue);
+		return [key, value];
+	};
+
+	mapObject(subject, mapper, {deep: true});
+});