FAQ
Does It Mutate My Object?
Section titled “Does It Mutate My Object?”Yes — every method except filter() mutates the
source. Call clone() first to work on a copy.
Can I Use It with CommonJS / require()?
Section titled “Can I Use It with CommonJS / require()?”No. v3 is ESM only — use import { Notation } from 'notation'. See
What’s New in v3 and the
ESM note.
What’s the Difference between !x and !x.*?
Section titled “What’s the Difference between !x and !x.*?”!x removes x. !x.* empties x’s contents but keeps x (as {} or
[]). They’re not interchangeable — see Object, Bracket & Array Syntax.
Why Does My Glob Throw?
Section titled “Why Does My Glob Throw?”Almost always a data-integrity issue: a list
mixing object and array root notations, or a !x.* negation against a value
that isn’t a container. Use !x to remove a non-object instead.
get() Returns undefined for a Property I Set to undefined — Bug?
Section titled “get() Returns undefined for a Property I Set to undefined — Bug?”No. A property that exists with value undefined has a value, so the default
isn’t applied. Use has() vs hasDefined()
to tell the two apart.
How Do I Combine Two Glob Lists?
Section titled “How Do I Combine Two Glob Lists?”NotationGlob.union(a, b) — it merges and
normalizes, resolving duplicates and contradictions. Don’t concatenate arrays by
hand.
Does clone() Copy Class Instances and Functions?
Section titled “Does clone() Copy Class Instances and Functions?”No. It deep-copies plain objects, arrays, primitives, Date, and RegExp.
Everything else is copied by reference. For a full clone, use a library like
lodash first — see Mutation & Cloning.
How Do I Validate a Notation from User Input?
Section titled “How Do I Validate a Notation from User Input?”Notation.isValid() for regular
notation, or NotationGlob.isValid() if wildcards/negation are allowed.
Does It Preserve the Prototype Chain?
Section titled “Does It Preserve the Prototype Chain?”No. Notation works on enumerable data properties only — it’s for data objects,
not class instances.