FieldValue

FieldValue

new FieldValue()

Sentinel values that can be used when writing documents with set(), create() or update().

Methods

isEqual(other) → {boolean}

Returns true if this FieldValue is equal to the provided value.

Parameters:
Name Type Description
other *

The value to compare against.
Returns:
Type Description
boolean

true if this FieldValue is equal to the provided value.
Example
```
let fieldValues = [
  Firestore.FieldValue.increment(-1.0),
  Firestore.FieldValue.increment(-1),
  Firestore.FieldValue.increment(-0.0),
  Firestore.FieldValue.increment(-0),
  Firestore.FieldValue.increment(0),
  Firestore.FieldValue.increment(0.0),
  Firestore.FieldValue.increment(1),
  Firestore.FieldValue.increment(1.0)
];

let equal = 0;
for (let i = 0; i < fieldValues.length; ++i) {
  for (let j = i + 1; j < fieldValues.length; ++j) {
    if (fieldValues[i].isEqual(fieldValues[j])) {
      ++equal;
    }
  }
}
console.log(`Found ${equal} equalities.`);
```

(static) arrayRemove(…elements) → {FieldValue}

Returns a special value that can be used with set(), create() or update() that tells the server to remove the given elements from any array value that already exists on the server. All instances of each element specified will be removed from the array. If the field being modified is not already an array it will be overwritten with an empty array.

Parameters:
Name Type Attributes Description
elements * <repeatable>

The elements to remove from the array.
Returns:
Type Description
FieldValue

The FieldValue sentinel for use in a call to set(), create() or update().
Example
```
let documentRef = firestore.doc('col/doc');

documentRef.update(
  'array', Firestore.FieldValue.arrayRemove('foo')
).then(() => {
  return documentRef.get();
}).then(doc => {
  // doc.get('array') no longer contains field 'foo'
});
```

(static) arrayUnion(…elements) → {FieldValue}

Returns a special value that can be used with set(), create() or update() that tells the server to union the given elements with any array value that already exists on the server. Each specified element that doesn't already exist in the array will be added to the end. If the field being modified is not already an array it will be overwritten with an array containing exactly the specified elements.

Parameters:
Name Type Attributes Description
elements * <repeatable>

The elements to union into the array.
Returns:
Type Description
FieldValue

The FieldValue sentinel for use in a call to set(), create() or update().
Example
```
let documentRef = firestore.doc('col/doc');

documentRef.update(
  'array', Firestore.FieldValue.arrayUnion('foo')
).then(() => {
  return documentRef.get();
}).then(doc => {
  // doc.get('array') contains field 'foo'
});
```

(static) delete() → {FieldValue}

Returns a sentinel for use with update() or set() with {merge:true} to mark a field for deletion.

Returns:
Type Description
FieldValue

The sentinel value to use in your objects.
Example
```
let documentRef = firestore.doc('col/doc');
let data = { a: 'b', c: 'd' };

documentRef.set(data).then(() => {
  return documentRef.update({a: Firestore.FieldValue.delete()});
}).then(() => {
  // Document now only contains { c: 'd' }
});
```

(static) increment(n) → {FieldValue}

Returns a special value that can be used with set(), create() or update() that tells the server to increment the field's current value by the given value.

If either current field value or the operand uses floating point precision, both values will be interpreted as floating point numbers and all arithmetic will follow IEEE 754 semantics. Otherwise, integer precision is kept and the result is capped between -2^63 and 2^63-1.

If the current field value is not of type 'number', or if the field does not yet exist, the transformation will set the field to the given value.

Parameters:
Name Type Description
n number

The value to increment by.
Returns:
Type Description
FieldValue

The FieldValue sentinel for use in a call to set(), create() or update().
Example
```
let documentRef = firestore.doc('col/doc');

documentRef.update(
  'counter', Firestore.FieldValue.increment(1)
).then(() => {
  return documentRef.get();
}).then(doc => {
  // doc.get('counter') was incremented
});
```

(static) maximum(n) → {FieldValue}

Returns a special value that can be used with set(), create() or update() that tells the server to set the field to the numeric maximum of the field's current and the given value.

If the current field value is not of type 'number', or if the field does not yet exist, the transformation will set the field to the given value.

If the existing value and the operand are equivalent, then the field does not change. For example, 0, 0.0, and -0.0 are all equivalent. If the operand is NaN then the result is always NaN.

Parameters:
Name Type Description
n number

The value to compare to the exiting field value.
Returns:
Type Description
FieldValue

The FieldValue for use in a call to set(), create() or update().
Example
```typescript
let documentRef = firestore.doc('col/doc');

documentRef.update(
  'counter', Firestore.FieldValue.maximum(1)
).then(() => {
  return documentRef.get();
}).then(doc => {
  // doc.get('counter') is the maximum of either the existing value or 1
});
```

(static) minimum(n) → {FieldValue}

Returns a special value that can be used with set(), create() or update() that tells the server to set the field to the numeric minimum of the field's current and the given value.

If the current field value is not of type 'number', or if the field does not yet exist, the transformation will set the field to the given value.

If the existing value and the operand are equivalent, then the field does not change. For example, 0, 0.0, and -0.0 are all equivalent. If the operand is NaN then the result is always NaN.

Parameters:
Name Type Description
n number

The value to compare to the exiting field value.
Returns:
Type Description
FieldValue

The FieldValue for use in a call to set(), create() or update().
Example
```typescript
let documentRef = firestore.doc('col/doc');

documentRef.update(
  'counter', Firestore.FieldValue.minimum(1)
).then(() => {
  return documentRef.get();
}).then(doc => {
  // doc.get('counter') is the minimum of either the existing value or 1
});
```

(static) serverTimestamp() → {FieldValue}

Returns a sentinel used with set(), create() or update() to include a server-generated timestamp in the written data.

Returns:
Type Description
FieldValue

The FieldValue sentinel for use in a call to set(), create() or update().
Example
```
let documentRef = firestore.doc('col/doc');

documentRef.set({
  time: Firestore.FieldValue.serverTimestamp()
}).then(() => {
  return documentRef.get();
}).then(doc => {
  console.log(`Server time set to ${doc.get('time')}`);
});
```

(static) vector(values)

Creates a new VectorValue constructed with a copy of the given array of numbers.

Parameters:
Name Type Description
values

Create a VectorValue instance with a copy of this array of numbers.
Returns:
Type Description

A new VectorValue constructed with a copy of the given array of numbers.