🤠 Parser for object property paths with wildcards and regexps. 🌵

wild-wild-path is a library which gets/sets object properties using dot-delimited paths, wildcards, regexps, slices and unions. wild-wild-parser allows manipulating its query format:

• 🚂 Parse/serialize, i.e. convert between query strings and query arrays
• ⭐ Normalize queries
• 🗺️ Compare queries

Install

npm install wild-wild-parser

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

parseQuery(queryString)

queryString QueryString
Return value: QueryArray

Convert a query string into a query array.

parseQuery('users.0.*') // [['users', 0, { type: 'any' }]]
parseQuery('users admins') // [['users'], ['admins']]
parseQuery('users./[/') // Throws: invalid RegExp

serializeQuery(queryArray)

queryArray QueryArray
Return value: QueryString

Convert a query array into a query string.

serializeQuery(['users', 0, { type: 'any' }]) // 'users.0.*'
serializeQuery([['users'], ['admins']]) // 'users admins'
serializeQuery([true]) // Throws: `true` is not a valid query

normalizeQuery(query)

query Query
Return value: QueryArray

If the query is a query string, convert it into a query array. If it is already a query array, normalize it to a canonical form.

normalizeQuery('users.0.*') // [['users', 0, { type: 'any' }]]
normalizeQuery(['users']) // [['users']]
normalizeQuery([['users'], ['admins']]) // [['users'], ['admins']]
normalizeQuery([{ type: 'slice' }]) // [[{ type: 'slice', from: 0 }]]
normalizeQuery('users./[/') // Throws: invalid RegExp
normalizeQuery([true]) // Throws: `true` is not a valid query

parsePath(pathString)

pathString PathString
Return value: PathArray

Same as parseQuery() but only for a path query.

parsePath('users.0') // ['users', 0]
parsePath('*') // Throws: this is a valid query but not a path
parsePath('users./[/') // Throws: invalid RegExp

serializePath(pathArray)

pathArray PathArray
Return value: PathString

Same as serializeQuery() but only for a path query.

serializePath(['users', 0]) // 'users.0'
serializePath([{ type: 'any' }]) // Throws: this is a valid query but not a path
serializePath([true]) // Throws: `true` is not a valid query

normalizePath(path)

path Path
Return value: PathArray

Same as normalizeQuery() but only for a path query.

normalizePath('users.0') // ['users', 0]
normalizePath(['users', 0]) // ['users', 0]
normalizePath('*') // Throws: `*` is a valid query but not a path
normalizePath([true]) // Throws: `true` is not a valid query

isSameQuery(firstQuery, secondQuery)

firstQuery Query
secondQuery Query
Return value: boolean

Return true if both queries are the same, even if they use different formats (string or array) or if they are syntactically different but semantically identical.

isSameQuery('users.0.*', 'users.0.*') // true
isSameQuery('users.0.*', ['users', 0, { type: 'any' }]) // true
isSameQuery(['users', 0, { type: 'any' }], ['users', 0, { type: 'any' }]) // true
isSameQuery('users.0.*', 'users.1.*') // false
isSameQuery('0:2', ':2') // true
isSameQuery([['user']], ['user']) // true
isSameQuery([true], 'user') // Throws: `true` is not a valid query

isSamePath(firstPath, secondPath)

firstPath Path
secondPath Path
Return value: boolean

Same as isSameQuery() but only for a path query.

isSamePath('user.name', 'user.name') // true
isSamePath('user.name', ['user', 'name']) // true
isSamePath(['user', 'name'], ['user', 'name']) // true
isSamePath('user.name', 'user.lastName') // false
isSamePath('*', 'user.name') // Throws: `*` is a valid query but not a path
isSamePath([true], 'user.name') // Throws: `true` is not a valid query

isParentPath(parentPath, childPath)

parentPath Path
childPath Path
Return value: boolean

Return true if the first argument is a parent path to the second. Queries that are not paths cannot be used.

isParentPath('user', 'user.name') // true
isParentPath('user', 'user.settings.name') // true
isParentPath('user', ['user', 'settings', 'name']) // true
isParentPath(['user'], ['user', 'settings', 'name']) // true
isParentPath('user', 'user') // false
isParentPath('user.name', 'user') // false
isParentPath('user.name', 'user.settings') // false
isParentPath('*', 'user.name') // Throws: `*` is valid query but not a path
isParentPath([true], 'user.name') // Throws: `true` is not a valid query

isSameToken(firstToken, secondToken)

firstToken Token
secondToken Token
Return value: boolean

Same as isSameQuery() but only for query array individual tokens.

isSameToken('user', 'user') // true
isSameToken('user', 'users') // false
isSameToken(2, 2) // true
isSameToken(0, -0) // false
isSameToken(/Name/, /Name/) // true
isSameToken(/Name/, /name/i) // false
isSameToken({ type: 'slice' }, { type: 'slice', from: 0 }) // true
isSameToken('user', true) // Throws: invalid token `true`

getTokenType(token)

token Token
Return value: string

Retrieve the type of a query array individual token among: "prop", "index", "slice", "regExp", "any" or "anyDeep". "unknown" is returned if the token is invalid.

getTokenType('user') // "prop"
getTokenType(0) // "index"
getTokenType(/Name/) // "regExp"
getTokenType({ type: 'slice', from: 0, to: 2 }) // "slice"
getTokenType({ type: 'any' }) // "any"
getTokenType({ type: 'anyDeep' }) // "anyDeep"
getTokenType(true) // "unknown"

Related projects

• wild-wild-path: get/set object properties using wild-wild-parser's paths
• wild-wild-utils: functional utilities using wild-wild-parser's paths

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!