.extract() - DarthJDG/Mangler.js GitHub Wiki

Extracts parts of items with path filters and returns a new mangler object with the result.

.extract(filter[, options])

Returns a new mangler object with the results.

The .extract() method extracts parts of your data by their path. It recursively traverses all iterable objects in the .items[ ] array looking for items that matches the filter. List of results will be returned in a new mangler object for method chaining. Call the .end() method to return to the previous mangler object in the chain, or the .endAll() method to return the mangler object at the top of the chain.

Apart from object literals and arrays, other typed objects may be made iterable and could be traversed. See Mangler.registerType() for details.

data = {
	mobile_os: [
		{ id: '001', name: 'Android' },
		{ id: '002', name: 'iOS' }
	],
	desktop_os: [
		{ id: '003', name: 'Windows' },
		{ id: '004', name: 'Linux', sub_os: [
			{ id: '005', name: 'CentOS' },
			{ id: '006', name: 'Ubuntu' }
		]}
	]
}

os = Mangler(data).extract('mobile_os');

/*
	os.items = [
		{ id: '001', name: 'Android' },
		{ id: '002', name: 'iOS' }
	]
*/

Filters can be as vague or as specific as you want them to be and can match anything anywhere in the object, not just top-level properties:

// Extract all name properties from all levels
os = Mangler(data).extract('name');
// os.items = ['Android', 'iOS', 'Windows', 'Linux', 'CentOS', 'Ubuntu']

// Extract all mobile OS names
os = Mangler(data).extract('mobile_os[].name');
// os.items = ['Android', 'iOS']

// Extract all linux distro names
os = Mangler(data).extract('desktop_os[1].sub_os[].name');
// os.items = ['CentOS', 'Ubuntu']

Filters also support wildcard characters, use * to substitute zero or more levels of references:

// Extract all desktop OS names, including distros
os = Mangler(data).extract('desktop_os.*.name');
// os.items = ['Windows', 'Linux', 'CentOS', 'Ubuntu']

You can also use ? anywhere to match partial property names. The filter ?_os collects top-level objects from both the mobile_os and desktop_os arrays, yielding the following:

[
	{ id: '001', name: 'Android' },
	{ id: '002', name: 'iOS' },
	{ id: '003', name: 'Windows' },
	{ id: '004', name: 'Linux', sub_os: [
		{ id: '005', name: 'CentOS' },
		{ id: '006', name: 'Ubuntu' }
	]}
]

Use and array of strings or the | character to pass multiple filters. In this example the filter 'mobile_os|desktop_os' or ['mobile_os', 'desktop_os'] would match the same items as above.

You can even use a custom RegExp for more complex filters. For a complete reference on the filter parameter's format and how it matches against the object path, see Path filter format.

By default .extract() will not go deeper into objects that match the filter. In the example above, even though ?_os would have matched it, sub_os items were not extracted, because desktop_os has already matched the filter further up the hierarchy. To override this behaviour, set the drilldown option to true:

os = Mangler(data).extract('?_os', { drilldown: true });

/*
	os.items = [
		{ id: '001', name: 'Android' },
		{ id: '002', name: 'iOS' },
		{ id: '003', name: 'Windows' },
		{ id: '004', name: 'Linux', sub_os: [
			{ id: '005', name: 'CentOS' },
			{ id: '006', name: 'Ubuntu' }
		]},
		{ id: '005', name: 'CentOS' },
		{ id: '006', name: 'Ubuntu' }
	]
*/

Note that because references are not destroyed, objects might be referenced multiple times in the resulting array. They are not cloned, all references point to the same original objects.

The key option adds a property to matched objects recording their key in their parent. If the parent is an object, it will be a string containing the propery name. If the parent is an array, it will be the array index of the object.

The prop option is similar, but it only passes property names. If the matched object is part of an array, it looks further up in the parent tree until it finds a property name. If no property name is found, an empty string is used.

data = {
	manager: { name: 'John' },
	employees: [
		{ name: 'Fred' },
		{ name: 'Bill' }
	]
};

m = Mangler(data).extract('manager|employees', { key: true, prop: true });

/*
	m.items = [
		{ name: 'John', key: 'manager', prop: 'manager' },
		{ name: 'Fred', key: 0, prop: 'employees' },
		{ name: 'Bill', key: 1, prop: 'employees' }
	]
*/

You can also set the key and prop options to strings to change the name of the added properties:

m = Mangler(data).extract('manager|employees', { key: 'id', prop: 'type' });

/*
	m.items = [
		{ name: 'John', id: 'manager', type: 'manager' },
		{ name: 'Fred', id: 0, type: 'employees' },
		{ name: 'Bill', id: 1, type: 'employees' }
	]
*/