hammy2899 / dot-notation-tokenizer

Dot notation tokenizer

dot-notation-tokenizer

Convert a dot notation string into a tokenized array.

---

Installation

yarn

yarn add dot-notation-tokenizer

npm

npm i dot-notation-tokenizer

Usage

JavaScript ES / TypeScript

import { tokenize } from 'dot-notation-tokenizer'

tokenize('dot.notation')

Browser

<script src="path/to/script/index.min.js"></script>

<script>
  dotNotationTokenizer.tokenize('dot.notation')
</script>

NodeJS

const { tokenize } = require('dot-notation-tokenizer')

tokenize('dot.notation')

Extra exported functions and types

import {
  notationFromTokens,     // convert tokens array (returned from tokenize) into a dot notation string
  isNotationToken,        // check if a value is a valid token
  tokensFromPropertyKeys, // convert an array of property keys into an array of tokens
  escapeProperty,         // escape token characters
  unescapeProperty,       // remove \ from escaped token characters
  Tokens                  // this is actually a class which extends Array and contains the _notation property
} from 'dot-notation-tokenizer'
// Most of these functions are used internally however they can also prove useful

import type {
  TokenKind,        // either 'PROPERTY' or 'ARRAY_INDEX'
  PropertyToken,    // interface with properties for a property token
  ArrayIndexToken,  // interface with properties for an array index token
  Token             // either PropertyToken or ArrayIndexToken
} from 'dot-notation-tokenizer'

Explanation

Dot notation can consist of basic property keys seperated by a . and also array indexes within [x] like the following.

path.to.array[1]

The above notation would return the following token array.

[
  {
    "kind": "PROPERTY",
    "value": "path",
    "index": {
      "start": 0,
      "end": 4
    },
    "escaped": "path"
  },
  {
    "kind": "PROPERTY",
    "value": "to",
    "index": {
      "start": 5,
      "end": 7
    },
    "escaped": "to"
  },
  {
    "kind": "PROPERTY",
    "value": "array",
    "index": {
      "start": 8,
      "end": 13
    },
    "escaped": "array"
  },
  {
    "kind": "ARRAY_INDEX",
    "value": 1,
    "index": {
      "start": 14,
      "end": 16
    },
    "text": "[1]"
  }
]

The notation used above would be used to access the second array value in the following object.

The value returned would be 2.

{
  "path": {
    "to": {
      "array": [
        1,
        2,
        3
      ]
    }
  }
}

You can also chain array indexes for nested arrays like the following notation.

path.to.deep.array[1][0][4]

Escaping characters

If you need to include ., [ or ] in your array key you can simply escape it by putting a slash \ in front of the character.

escaped\\.property\\[0\\].withindex

The above notation would return the following tokens.

[
  {
    "kind": "PROPERTY",
    "value": "escaped.property[0]",
    "index": {
      "start": 0,
      "end": 22
    },
    "escaped": "escaped\\.property\\[0\\]"
  },
  {
    "kind": "PROPERTY",
    "value": "withindex",
    "index": {
      "start": 23,
      "end": 32
    },
    "escaped": "withindex"
  }
]