Skip to content

ehmicky/wild-wild-path

BranchesTags

Repository files navigation

wild-wild-path logo

Node Browsers TypeScript Codecov Minified size Mastodon Medium

🤠 Object property paths with wildcards and regexps. 🌵

Get/set object properties using:

Install

npm install wild-wild-path

This package works in both Node.js >=18.18.0 and browsers.

This is an ES module. It must be loaded using an import or import() statement, not require(). If TypeScript is used, it must be configured to output ES modules, not CommonJS.

API

Methods

get(target, query, options?)

target: Target
query: Query
options: Options?
Return value: any | undefined

Return the first property matching the query.

const target = { settings: { colors: ['red', 'blue'] } }

get(target, 'settings.colors.0') // 'red'
get(target, ['settings', 'colors', 0]) // 'red'

has(target, query, options?)

target: Target
query: Query
options: Options?
Return value: boolean

Return whether the query matches any property.

const target = { settings: { lastName: undefined, colors: ['red', 'blue'] } }

has(target, 'settings.firstName') // false
has(target, ['settings', 'firstName']) // false
has(target, 'settings.lastName') // true

list(target, query, options?)

target: Target
query: Query
options: Options?
Return value: any[]

Return all properties matching the query, as an array.

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 },
// ]

iterate(target, query, options?)

target: Target
query: Query
options: Options?
Return value: Iterable<any>

Return all properties matching the query, as an iterable. This is slower than list() but uses less memory.

const target = { settings: { colors: ['red', 'blue'] } }

for (const color of iterate(target, 'settings.colors.*')) {
  console.log(color) // 'red', 'blue'
}

set(target, query, value, options?)

target: Target
query: Query
value: any
options: Options?
Return value: Target

Sets all properties matching the query. The return value is a deep clone unless the mutate option is true.

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', 'blue', 'yellow']
set(target, 'colors.*', 'yellow') // ['yellow', 'yellow']
set({}, 'user.0.color', 'red') // { user: [{ color: 'red' }] }
set({}, 'user.0.color', 'red', { missing: false }) // {}

remove(target, query, options?)

target: Target
query: Query
options: Options?
Return value: Target

Delete all properties matching the query. The return value is a deep clone unless the mutate option is true.

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 } }

Functional utilities

wild-wild-utils is a separate library which provides with additional, higher-level methods: map(), merge(), push(), unshift(), find(),