🤠 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
.
allows manipulating
:
Install
npm install wild-wild-parser copy
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 copy
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 copy
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 copy
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 copy
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 copy
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 copy
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 copy
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 copy
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'
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` copy
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" copy
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!