NotationGlob

Defined in: src/core/NotationGlob.ts:68

NotationGlob is a utility for validating, comparing and sorting dot-notation globs.

You can use http://www.linfo.org/wildcard.html|wildcard stars * and negate the notation by prepending a bang !. A star will include all the properties at that level and a negated notation will be excluded.

Examples

// for the following object;
{ name: 'John', billing: { account: { id: 1, active: true } } };

'billing.account.*'  // represents value `{ id: 1, active: true }`
'billing.account.id' // represents value `1`
'!billing.account.*' // represents value `{ name: 'John' }`
'name' // represents `'John'`
'*' // represents the whole object

const glob = new NotationGlob('billing.account.*');
glob.test('billing.account.id'); // true

Constructor

new NotationGlob(glob): NotationGlob

Defined in: src/core/NotationGlob.ts:84

Constructs a NotationGlob object with the given glob string.

Parameters

glob

string

Notation string with globs.

Returns

NotationGlob

Throws

• If given notation glob is invalid.

Accessors

glob

Get Signature

get glob(): string

Defined in: src/core/NotationGlob.ts:103

Gets the normalized glob notation string.

Returns

string

---

absGlob

Get Signature

get absGlob(): string

Defined in: src/core/NotationGlob.ts:111

Gets the absolute glob notation without the negation prefix ! and redundant trailing wildcards.

Returns

string

---

isNegated

Get Signature

get isNegated(): boolean

Defined in: src/core/NotationGlob.ts:118

Specifies whether this glob is negated with a ! prefix.

Returns

boolean

---

regexp

Get Signature

get regexp(): RegExp

Defined in: src/core/NotationGlob.ts:126

Represents this glob in regular expressions. Note that the negation prefix (!) is ignored, if any.

Returns

RegExp

---

notes

Get Signature

get notes(): string[]

Defined in: src/core/NotationGlob.ts:137

List of notes (levels) of this glob notation. Note that trailing, redundant wildcards are removed from the original glob notation.

Returns

string[]

---

first

Get Signature

get first(): string

Defined in: src/core/NotationGlob.ts:144

Gets the first note of this glob notation.

Returns

string

---

last

Get Signature

get last(): string

Defined in: src/core/NotationGlob.ts:151

Gets the last note of this glob notation.

Returns

string

---

parent

Get Signature

get parent(): string | null

Defined in: src/core/NotationGlob.ts:166

Gets the parent notation (up to but excluding the last note) from the glob notation string. Note that initially, trailing/redundant wildcards are removed.

Example

const glob = NotationGlob.create;
glob('first.second.*').parent;   // "first.second"
glob('*.x.*').parent;            // "*" ("*.x.*" normalizes to "*.x")
glob('*').parent;                // null (no parent)

Returns

string | null

Methods

test()

test(notation): boolean

Defined in: src/core/NotationGlob.ts:195

Checks whether the given notation value matches the source notation glob.

Parameters

notation

string

The notation string to be tested. Cannot have any globs.

Returns

boolean

Throws

• If given notation is not valid or contains any globs.

Example

const glob = new NotationGlob('!prop.*.name');
glob.test("prop.account.name"); // true

---

covers()

covers(glob): boolean

Defined in: src/core/NotationGlob.ts:215

Specifies whether this glob notation can represent (or cover) the given glob notation. Note that negation prefix is ignored, if any.

Parameters

glob

string | string[] | NotationGlob

Glob notation string, glob notes array or a NotationGlob instance.

Returns

boolean

Example

const glob = NotationGlob.create;
glob('*.y').covers('x.y')      // true
glob('x[*].y').covers('x[*]')  // false

---

intersect()

intersect(glob, restrictive?): string | null

Defined in: src/core/NotationGlob.ts:236

Gets the intersection of this and the given glob notations. When restrictive, if any one of them is negated, the outcome is negated. Otherwise, only if both of them are negated, the outcome is negated.

Parameters

glob

string

Second glob to be used.

restrictive?

boolean = false

Whether the intersection should be negated when one of the globs is negated.

Returns

string | null

• Intersection notation if any; otherwise null.

Example

const glob = NotationGlob.create;
glob('x.*').intersect('!*.y')         // 'x.y'
glob('x.*').intersect('!*.y', true)   // '!x.y'

---

create()

static create(glob): NotationGlob

Defined in: src/core/NotationGlob.ts:255

Basically constructs a new NotationGlob instance with the given glob string.

Parameters

glob

string

The source notation glob.

Returns

NotationGlob

Example

const glob = NotationGlob.create(strGlob);
// equivalent to:
const glob = new NotationGlob(strGlob);

---

isValid()

static isValid(glob): boolean

Defined in: src/core/NotationGlob.ts:265

Validates the given notation glob.

Parameters

glob

string

Notation glob to be validated.

Returns

boolean

---

isValidNote()

static isValidNote(note): boolean

Defined in: src/core/NotationGlob.ts:274

Validates the given glob note.

Parameters

note

string

Note to be validated.

Returns

boolean

---

hasMagic()

static hasMagic(glob): boolean

Defined in: src/core/NotationGlob.ts:284

Specifies whether the given glob notation includes any valid wildcards (*) or negation bang prefix (!).

Parameters

glob

string

Glob notation to be checked.

Returns

boolean

---

toRegExp()

static toRegExp(glob): RegExp

Defined in: src/core/NotationGlob.ts:298

Gets a regular expressions instance from the given glob notation. Note that the bang ! prefix will be ignored if the given glob is negated.

Parameters

glob

string

Glob notation to be converted.

Returns

RegExp

• A RegExp instance from the glob.

Throws

• If given notation glob is invalid.

---

split()

static split(glob, normalize?): string[]

Defined in: src/core/NotationGlob.ts:339

Splits the given glob notation string into its notes (levels). Note that this will exclude the ! negation prefix, if it exists.

Parameters

glob

string

Glob notation string to be splitted.

normalize?

boolean = false

Whether to remove trailing, redundant wildcards.

Returns

string[]

• A string array of glob notes (levels).

Throws

• If given glob notation is invalid.

Example

NotationGlob.split('*.list[2].prop')  // ['*', 'list', '[2]', 'prop']
// you can get the same result from the .notes property of a NotationGlob instance.

---

join()

static join(notes, normalize?): string

Defined in: src/core/NotationGlob.ts:362

Joins the given notes into a glob notation.

No negation is allowed in notes array.

Parameters

notes

string[]

Array of notes.

normalize?

boolean = false

Whether to remove trailing wildcards.

Returns

string

• A string of glob notation.

Throws

• If given notes are invalid.

---

compare()

static compare(globA, globB): number

Defined in: src/core/NotationGlob.ts:408

Compares two given notation globs and returns an integer value as a result. This is generally used to sort glob arrays. Loose globs (with stars especially closer to beginning of the glob string) and globs representing the parent/root of the compared property glob come first. Verbose/detailed/exact globs come last. (* < *.abc < abc).

For instance; store.address comes before store.address.street. So this works both for *, store.address.street, !store.address and *, store.address, !store.address.street. For cases such as prop.id vs !prop.id which represent the same property; the negated glob comes last.

Parameters

globA

string

First notation glob to be compared.

globB

string

Second notation glob to be compared.

Returns

number

• Returns -1 if globA comes first, 1 if globB comes first and 0 if equivalent priority.

Throws

• If either globA or globB is invalid glob notation.

Example

const { compare } = NotationGlob;
compare('*', 'info.user')               // -1
compare('*', '[*]')                     // 0
compare('info.*.name', 'info.user')     // 1

---

sort()

static sort(globList): string[]

Defined in: src/core/NotationGlob.ts:457

Sorts the notation globs in the given array by their priorities. Loose globs (with stars especially closer to beginning of the glob string); globs representing the parent/root of the compared property glob come first. Verbose/detailed/exact globs come last. (* < *.y < x.y).

For instance; store.address comes before store.address.street. For cases such as prop.id vs !prop.id which represent the same property; the negated glob wins (comes last).

Parameters

globList

string[]

The notation globs array to be sorted. The passed array reference is modified.

Returns

string[]

• Logically sorted globs array.

Example

NotationGlob.sort(['!prop.*.name', 'prop.*', 'prop.id']) // ['prop.*', 'prop.id', '!prop.*.name'];

---

normalize()

static normalize(globList, restrictive?): string[]

Defined in: src/core/NotationGlob.ts:499

Normalizes the given notation globs array by removing duplicate or redundant items, eliminating extra verbosity (also with intersection globs) and returns a priority-sorted globs array.

• If any exact duplicates found, all except first is removed.
  example: `['car', 'dog', 'car']` normalizes to `['car', 'dog']`.
• If both normal and negated versions of a glob are found, negated wins.
  example: `['*', 'id', '!id']` normalizes to `['*', '!id']`.
• If a glob is covered by another, it's removed.
  example: `['car.*', 'car.model']` normalizes to `['car']`.
• If a negated glob is covered by another glob, it's kept.
  example: `['*', 'car', '!car.model']` normalizes as is.
• If a negated glob is not covered by another or it does not cover any other; then we check for for intersection glob. If found, adds them to list; removes the original negated.
  example: `['car.*', '!*.model']` normalizes as to `['car', '!car.model']`.
• In restrictive mode; if a glob is covered by another negated glob, it's removed. Otherwise, it's kept.
  example: `['*', '!car.*', 'car.model']` normalizes to `['*', '!car']` if restrictive.

Parameters

globList

string | string[]

Notation globs array to be normalized.

restrictive?

boolean = false

Whether negated items strictly remove every match. Note that, regardless of this option, if any item has an exact negated version; non-negated is always removed.

Returns

string[]

Throws

• If any item in globs list is invalid.

Example

const { normalize } = NotationGlob;
normalize(['*', '!id', 'name', '!car.model', 'car.*', 'id', 'name']); // ['*', '!id', '!car.model']
normalize(['!*.id', 'user.*', 'company']); // ['company', 'user', '!company.id', '!user.id']
normalize(['*', 'car.model', '!car.*']); // ["*", "!car.*", "car.model"]
// restrictive normalize:
normalize(['*', 'car.model', '!car.*'], true); // ["*", "!car.*"]

---

union()

static union(globsA, globsB, restrictive?): string[]

Defined in: src/core/NotationGlob.ts:719

Gets the union from the given couple of glob arrays and returns a new array of globs.

• If the exact same element is found in both arrays, one of them is removed to prevent duplicates.
  example: `['!id', 'name'] ∪ ['!id']` unites to `['!id', 'name']`
• If any non-negated item is covered by a glob in the same or other array, the redundant item is removed.
  example: `['*', 'name'] ∪ ['email']` unites to `['*']`
• If one of the arrays contains a negated equivalent of an item in the other array, the negated item is removed.
  example: `['!id'] ∪ ['id']` unites to `['id']`
• If any item covers/matches a negated item in the other array, the negated item is removed.
  example #1: `['!user.id'] ∪ ['user.*']` unites to `['user']`
  example #2: `['*'] ∪ ['!password']` unites to `['*']`

Parameters

globsA

string[]

First array of glob strings.

globsB

string[]

Second array of glob strings.

restrictive?

boolean = false

Whether negated items in each of the lists, strictly remove every match in themselves (not the cross list). This option is used when pre-normalizing each glob list and normalizing the final union list.

Returns

string[]

Example

const a = ['user.*', '!user.email', 'car.model', '!*.id'];
const b = ['!*.date', 'user.email', 'car', '*.age'];
const { union } = NotationGlob;
union(a, b)     // ['car', 'user', '*.age', '!car.date', '!user.id']