wild-wild-parser

🤠 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 is an ES module and must be loaded using an import or import() statement, not require().

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"

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!