There are two equivalent formats for queries: strings and arrays.
Query strings are friendlier to CLI usage, more expressive,
and easier to serialize.
Query arrays are friendlier to programmatic usage, and
faster. Also, they do not require escaping, so they should be used when the
input is dynamic or user-provided to prevent injection attacks.
Query strings
⛏️ Deep properties
# Deep properties of objects or arrays.# Dots are used for array indices, not brackets.# Symbol properties are always ignored.user.colors.0
🚂 Unions
# Unions ("or") of queries are space-delimited.# The string must not be empty.colors name age
⭐ Wildcards
# Shallow wildcards target all properties/items of a single object/arrayuser.*# Deep wildcards target all properties/items of 0, 1 or many objects/arraysuser.****.colors
🗺️ Regexps
# Regexps match property namesuser./name/# Flags can be used, e.g. to make it case-insensitiveuser./name/i# ^ $ must be used to match from the beginning or until the enduser./^name$/i
🌵 Arrays indices
# Array indices are integersuser.colors.0# Array indices can be negative.# -1 is the last item.# -0 is the item after it, which can be used to append.user.colors.-1
🏜️ Array slices
# Array slices. Goes from the start (included) to the end index (excluded).user.colors.0:2# The start index defaults to 0, i.e. the beginninguser.colors.:2# The end index defaults to -0, i.e. the enduser.colors.0:user.colors.:
🪨 Escaping
# Dots, spaces and backslashes in property names must be escapedname\\ with\\ spacesname\\.with\\.dotsname\\\\with\\\\backslashes# Ambiguous property names must be escaped with a backslash at the beginning.# This includes properties that:# - Are integers but are not array elements# - Have multiple slashes and start with onename.\\0name.\\/not_a_regexp/
🏨 Root and empty strings
# A leading dot can optionally be used. It is ignored.user.colors.user.colors# Root value.# Empty string propertiesuser..colors
Query arrays
⛏️ Deep properties
// Deep properties of objects or arrays.// Symbol properties are always ignored.['user', 'colors', 0]
🚂 Unions
// Unions ("or") of queries are arrays of arrays.// There must be at least one item.[['colors'], ['name'], ['age']]
⭐ Wildcards
// Shallow wildcards target all properties/items of a single object/array['user', { type: 'any' }]// Deep wildcards target all properties/items of 0, 1 or many objects/arrays['user', { type: 'anyDeep' }][{ type: 'anyDeep' }, 'colors']
🤠 Regexps
// Regexps match property names['user', /name/]// Flags can be used, e.g. to make it case-insensitive['user', /name/i]// ^ $ must be used to match from the beginning or until the end['user', /^name$/i]
🌵 Arrays indices
// Array indices are integers, not strings['user', 'colors', 0]// Array indices can be negative.// -1 is the last item.// -0 is the item after it, which can be used to append.['user', 'colors', -1]
🏜️ Array slices
// Array slices. Goes from the start (included) to the end index (excluded).['user', 'colors', { type: 'slice', from: 0, to: 2 }]// The start index defaults to 0, i.e. the beginning['user', 'colors', { type: 'slice', to: 2 }]// The end index defaults to -0, i.e. the end['user', 'colors', { type: 'slice', from: 0 }]['user', 'colors', { type: 'slice' }]
🪨 Escaping
// Escaping is not necessary with query arrays['name with spaces']['name.with.dots']['name\\with\\backslashes']['name', '0']['name', '/not_a_regexp/']
wild-wild-parser can be used to
convert between both formats, or to compare queries.
Undefined values
Object properties with a defined key but an undefined value are not ignored.
However, object properties without any defined key are ignored. The
has() method, missing option and
entries option can be used to distinguish those.
Unless true, wildcards and regexps ignore
properties of objects that are not plain objects (like class instances, errors
or functions). Those can still be matched by using their
property name.