repository·main·Indexed 20 days ago
https://github.com/ehmicky/wild-wild-pathA utility for accessing, setting, and removing object properties using a powerful query syntax that supports wildcards, regexps, slices, and unions. Version 5.0.1 provides functions such as get(), set(), has(), list(), remove(), and a memory-efficient iterate() generator for traversing complex object structures.
Install the package using npm. This project is an ES module and requires Node.js >=18.18.0 or a modern browser.
Important Requirements:
import or import() statements; require() is not supported.npm install wild-wild-pathWhen performing path operations like set(), the library may encounter missing values. The library distinguishes between 'known' missing properties (e.g., those identified by prop, index, or slice tokens) and 'unknown' missing properties (e.g., those identified by any or regexp tokens).
set(): Automatically creates missing entries deeply by default.list(), get(), has(): Do not create missing entries. Instead, they use a missing property to signal whether a value was found or if a default was used.To control this behavior, the getMissingValue function can be used to determine if a value should be replaced with a default based on the provided missing flag and classes configuration.
Use iterate(target, query, options?) to return an Iterable<any> of all properties matching the query.
Note: This is more memory-efficient than list() but is slower for small datasets.
const target = { settings: { colors: ['red', 'blue'] } }
for (const color of iterate(target, 'settings.colors.*')) {
console.log(color) // 'red', 'blue'
}Use get(target, query, options?) to return the first property matching the query.
target: The object or array to search.query: A string path, array of path segments, or regex.options: Optional configuration.Returns any | undefined.
const target = { settings: { colors: ['red', 'blue'] } }
get(target, 'settings.colors.0') // 'red'
get(target, ['settings', 'colors', 0]) // 'red'Use list(target, query, options?) to return all properties matching the query as an array.
Supported query types include:
'path.one path.two').[['path', 'one'], ['path', 'two']].'user./Name/').* or **.0:2.If { entries: true } is passed in options, it returns an array of objects containing { value, path, missing } instead of just values.
const target = {
userOne: { firstName: 'John', lastName: 'Doe', age: 72 },
userTwo: { firstName: 'Alice', colors: ['red', 'blue', 'yellow'] },
}
list(target, 'userOne.firstName userTwo.colors.0') // ['John', 'red']
list(target, [['userOne', 'firstName'], ['userTwo', 'colors', 0]]) // ['John', 'red']
list(target, 'userOne./Name/') // ['John', 'Doe']
list(target, ['userOne', /Name/]) // ['John', 'Doe']
list(target, 'userTwo.colors.*') // ['red', 'blue', 'yellow']
list(target, 'userTwo.colors.0:2') // ['red', 'blue']
list(target, '**.firstName') // ['John', 'Alice']
list(target, 'userOne.*', { entries: true })
// [
// { value: 'John', path: ['userOne', 'firstName'], missing: false },
// { value: 'Doe', path: ['userOne', 'lastName'], missing: false },
// { value: 72, path: ['userOne', 'age'], missing: false },
// ]Use remove(target, query, options?) to delete all properties matching the query.
Target. By default, it returns a deep clone. To modify the original object, set { mutate: true } in options.const target = { user: { firstName: 'John', lastName: 'Doe', age: 72 } }
remove(target, 'user.lastName') // { user: { firstName: 'John', age: 72 } }
remove(target, 'user./Name/') // { user: { age: 72 } }
remove(target, ['user', /Name/]) // { user: { age: 72 } }Use set(target, query, value, options?) to set all properties matching the query to the provided value.
Target. By default, it returns a deep clone. To modify the original object, set { mutate: true } in options.set({}, 'user.0.color', 'red') creates the nested structure).{ missing: false } is passed, it will not create new paths if they don't exist.const target = { colors: ['red', 'blue'] }
set(target, 'colors.0', 'yellow') // ['yellow', 'blue']
set(target, ['colors', 0], 'yellow') // ['yellow', 'blue']
set(target, 'colors.-1', 'yellow') // ['red', 'yellow']
set(target, 'colors.-0', 'yellow') // ['red', 'yellow', 'blue']
set(target, 'colors.*', 'yellow') // ['yellow', 'yellow']
set({}, 'user.0.color', 'red') // { user: [{ color: 'red' }] }
set({}, 'user.0.color', 'red', { missing: false }) // {}Use has(target, query, options?) to return a boolean indicating whether the query matches any property in the target.
Returns boolean.
const target = { settings: { lastName: undefined, colors: ['red', 'blue'] } }
has(target, 'settings.firstName') // false
has(target, ['settings', 'firstName']) // false
has(target, 'settings.lastName') // trueThe Options object allows you to fine-tune how queries match and how results are returned.
childFirst: (boolean) When using unions/deep wildcards, sorts results from children to parents. Default: false.roots: (boolean) When true, only matches the highest level of a match (ignores children if a parent matches). Default: false.leaves: (boolean) When true, only matches the lowest level of a match (ignores parents if a child matches). Default: false.shallowArrays: (boolean) If true, wildcards do not recurse into arrays. Default: false.classes: (boolean) If true, wildcards/regexps include non-plain objects like class instances or errors. Default: false.inherited: (boolean) If true, includes inherited properties (but not non-enumerable ones). Default: false.sort: (boolean) Sorts sibling object properties lexicographically by name. Default: false.entries: (boolean) If true, returns Entry objects ({ value, path, missing }) instead of raw values. Default: false.missing: (boolean) If true, includes properties not defined in the target. Default: false for list|iterate, true for set.mutate: (boolean) If true, set() and remove() mutate the target directly instead of returning a deep clone. Default: false.// Example: childFirst
const target = { user: { name: 'Alice' } }
list(target, 'user.**', { childFirst: true }) // ['Alice', { name: 'Alice' }]
// Example: roots
list(target, 'user.**', { roots: true }) // [{ name: 'Alice' }]
// Example: leaves
list(target, 'user.**', { leaves: true }) // ['Alice']Query strings are ideal for CLI usage and serialization. They support several advanced features:
user.colors.0).For more advanced functional operations, use the companion library wild-wild-utils. It provides the following methods:
map()merge()push()unshift()find()pick()include()exclude()flatten()Use remove(target, query, options?) to delete data from a target at the location specified by the query.
import { remove } from 'wild-wild-path';
remove(target, query);