Vue-data-object-path NPM

vue-data-object-path

This Vue plugin allows you to retrieve and modify observable data properties in deeply nested structures using paths encoded in strings ("form.attachments[1]") or arrays (["form", "attachments", 1]). Intermediate objects are automatically created for you.

$op.set('a.b.c.d.e.f', 'gun');

// Creates this:
{
  a: {
    b: {
      c: {
        d: {
          e: {
            f: 'gun'
          }
        }
      }
    }
  }
}

$op.get('a.b.c.d.e.f'); // returns 'gun'.

Tested with the latest release of every minor version of Vue.js 2 (from 2.0 to 2.6).

Install

npm install vue-data-object-path

Usage

Require the module vue-data-object-path and pass it to Vue.use.

const VueDataObjectPath = require('vue-data-object-path')

Vue.use(VueDataObjectPath)

You will then have access to $objectPath and $op in every Vue component.

Documentation

$op and its long version $objectPath are available in every Vue component. You can use them after the data method has run. They have the following methods:

Method	Short description
set(path)	Stores a value
get(path)	Retrieves a value
has(path)	Checks if value exists
insert(path, start, ...items)	Inserts elements into array
remove(path, start, deleteCount)	Removes elements from array
empty(path)	Empties objects and arrays
delete(path)	Works like the delete operator
push(path, ...value)	Inserts elements to the end of array
pop(path)	Removes and returns last element of array
shift(path)	Removes and returns first element of array
unshift(path, ...value)	Inserts elements to the beginning of array
splice(path, start, deleteCount, ...items)	Removes and inserts elements into array
coalesce(...path)	Returns first non-null and non-undefined value

For examples and more detailed descriptions, please read on.

Methods

`get(path)`

Retrieves an object's property or an array's element.

Returns undefined if path does not lead to a value.

{
  data() {
    return {
      a: {
        b: {
          c: {
            d: {
              e: {
                f: 'gun'
              }
            }
          }
        }
        'dot.dot': 'value'
        array: ['first', 'second']
      }
    };
  }
}

// Retrieves value from nested property.
$op.get('a.b.c.d.e.f'); // returns 'gun'.

// Accesses a property using an array to prevent disambiguation.
$op.get(['a', 'dot.dot']); // returns 'value'.

// Retrieves element of array.
$op.get('a.array[1]'); // returns 'second'.

// Accessing same element but with an array path. Note that the index
// of the element must be passed as a number.
$op.get(['a', 'array', 1]); // returns 'second'.

// Does not crash if intermediate paths do not exist.
$op.get('a.doesNotExist.alsoDoesNotExist'); // returns undefined.

`set(path, value)`

Changes the value of a property of an object or the element of an array.

If the property does not exist it will be created and it will be reactive.

Intermediate objects and arrays will automatically be created.

{
  data() {
    return {
      a: {
        b: 'd',
        c: ['e', 'f', 'g'],
      }
    };
  }
}

// Changes an existing property.
$op.set('a.b', 'm'); // this.a.b is now 'm'.

// Changes the element of an array
$op.set('a.c[1]', 'm'); // this.a.c is now ['e', 'm', 'g']

// Will create intermediate objects and arrays depending on the type of the key. If
// you pass a string, an object is created, if you pass a number an array is
// created.
$op.set(['a', 'd', 'c'], 'm'); // this.a.d.c is 'd'.
                               // this.a.d is { c: 'm' }.
$op.set(['a', 'e', 1], 'm'); // this.a.e[1] is 'm'.
                             // this.a.e is [undefined, 'm'].

`has(path)`

Checks if path leads to a meaningful value.

Null and undefined are values that are not considered meaningful.

{
  data() {
    return {
      a: {
        b: 'd',
        c: ['e', 'f', 'g'],
        d: undefined,
        e: null
      }
    };
  }
}

$op.has('a'); // returns true.
$op.has('a.b'); // returns true.
$op.has('a.b.c[0]'); // returns true.

$op.has('b'); // returns false.
$op.has('a.c'); // returns false.
$op.has('a.b.c[3]'); // returns false.
$op.has('a.b.d'); // returns false.
$op.has('a.b.e'); // returns false.

`insert(path, start, ...items)`

Adds elements to an array.

If the array does not exist it will be created.

Fails if the path leads to a value that is not an array.

{
  data() {
    return {
      a: {
        b: ['c', 'e', 'f'],
      }
    };
  }
}

// Inserting a single element.
$op.insert('a.b', 1, 'd'); // this.a.b is now ['c', 'd', 'e', 'f']

// Creating a new array and inserting an element.
$op.insert('a.c', 0, 'd'); // this.a.c is now ['d']

// Inserting multiple elements.
$op.insert('a.c', 1, 'e', 'f'); // this.a.c is now ['d', 'e', 'f']

`remove(path, start, deleteCount)`

Removes elements from an array.

The deleteCount parameter is optional. When omitted, only a single element will be removed. So it is equivalent to passing 1.

It returns the elements that were removed.

The method does nothing if path leads to no value but fails if path leads to a value that is not an array.

{
  data() {
    return {
      a: {
        b: ['c', 'd', 'e', 'f', 'g'],
      }
    };
  }
}

// Removes element at index 1
$op.remove('a.b', 1); // this.a.b is now ['c', 'e', 'f', 'g']

// Removes 2 elements starting at index 1.
$op.remove('a.b', 1, 2); // this.a.b is now ['c', 'g']

// Does nothing when a path leads to no value.
$op.remove('a.c', 1); // this.a.c is undefined

`delete(path)`

Acts very much like the delete operator.

{
  data() {
    return {
      a: {
        b: 'd',
        c: ['e', 'f', 'g'],
      }
    };
  }
}

$op.delete('a.b'); // this.a.b is now undefined.
$op.delete('a.c[1]'); // this.a.c is now ['e', undefined, 'g'].

`empty(path)`

Empties objects, arrays and strings.

{
  data() {
    return {
      a: {
        b: 'd',
        c: ['e', 'f', 'g'],
      }
    };
  }
}

$op.empty('a.b'); // this.a.b is now ''.
$op.empty('a.c'); // this.a.c is now [].
$op.empty('a'); // this.a is now {}.

`push(path, ...value)`

Works just like JavaScript's push method. Only works on Arrays.

{
  data() {
    return {
      a: {}
    };
  }
}

// Pushes an element into an array. Note that push can also create
// intermediate objects and arrays.
$op.push('a.b', 'o'); // this.a.b is now ['o']

// You can push multiple elements with a single function call.
$op.push('a.b', 'p', 'q'); // this.a.b is now ['o', 'p', 'q']

`pop(path)`

Works just like JavaScript's pop method. Only works on Arrays.

{
  data() {
    return {
      a: {
        b: ['e', 'f', 'g'],
      }
    };
  }
}

// Removes the last element of the array.
$op.pop('a.b'); // Returns 'g' and this.a.b is now ['e', 'f'].

`shift(path)`

Works just like JavaScript's shift method. Only works on Arrays.

{
  data() {
    return {
      a: {
        b: ['e', 'f', 'g'],
      }
    };
  }
}

// Removes the first element of the array.
$op.shift('a.b'); // Returns 'e' and this.a.b is now ['f', 'g']

`unshift(path, ...value)`

Works just like JavaScript's unshift method. Only works on Arrays.

{
  data() {
    return {
      a: {}
    };
  }
}

// Adds an element to the beginning. Note that unshift can also create
// intermediate objects and arrays.
$op.push('a.b', 'o'); // this.a.b is now ['o']

// You can add multiple elements with a single function call.
$op.push('a.b', 'p', 'q'); // this.a.b is now ['p', 'q', 'o']

`splice(path, start, deleteCount, ...items)`

Works just like JavaScript's splice method. Only works on Arrays.

{
  data() {
    return {
      a: {
        b: ['e', 'f', 'g'],
      }
    };
  }
}

// Removes 1 element from the array.
$op.splice('a.b', 0, 1); // Returns ['e'] and this.a.b is now ['f', 'g']

// Removes 1 element and inserts 2 elements.
$op.splice('a.b', 0, 1, 'h', 'i'); // Returns ['f'] and this.a.b is now ['h', 'i', 'g']

// Removes all elements starting from the given index.
$op.splice('a.b', 1); // Returns ['i', 'g'] and this.a.b is now ['h']

`coalesce(...path)`

Inspired by the COALESCE function present in SQL based databases. Retrieves the first non-undefined and non-null value.

{
  data() {
    return {
      a: {
        b: undefined,
        c: null,
        e: 'first',
        f: 'second'
      }
    };
  }
}

// Retrieves first non-undefined and non-null value.
$op.coalesce('a.b', 'a.c', 'a.d', 'a.e', 'a.f'); // returns 'first'.

Caveats

You cannot create new properties directly on the data object. This is a limitation imposed by Vue.js

{
  data() {
    return {
      existingProperty: 1,
      object: {
        property: 'value'
      }
    };
  }
}

// Throws error. Not allowed to create properties at the root level.
$op.set('newProperty', 'no');

// Allowed to change existing properties.
$op.set('existingProperty', 2);

// Allowed to create new nested properties.
$op.set('object.newProperty', 'yes');