Patches allow you to modify a particular entity, such as user profiles or session attributes, without knowing its current state.
Most operations require specifying the path to the target attribute. The path format is similar to the way you are already used to access nested structures in JavaScript.
For objects and maps, you should use the object.property notation:
patch.set('custom.pet', 'crocodile');For lists, you should use the list[index] notation:
patch.set('custom.pets[0]', 'crocodile');Notice that the processing performed by a patch is atomic to prevent entities from ending up in an inconsistent state. So either all operations are applied, or none of them are.
This reference documents all methods available in the Patch API and explains in detail how these methods work.
This method sets a value at a given path.
This operation will overwrite the value in the specified path. Note that this operation will fail if the
parent path does not exist or is not a list or map. For example, given the path foo.bar, if the value at foo
does not exist or is not a map, the operation will fail.
The set method has the following signature:
patch.set(path: string, value: JsonValue): PatchThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to set a value:
patch.set('custom.pet', 'crocodile');This method adds a value to a collection.
The following table shows how the operation behaves in different scenarios:
| Current Value | Given Value | Result |
|---|---|---|
null |
'a' |
['a'] |
'a' |
null |
['a'] |
'a' |
'b' |
['a', 'b'] |
['a'] |
null |
['a'] |
[] |
'a' |
['a'] |
['a', 'b'] |
'a' |
['a', 'b', 'a'] |
The add method has the following signature:
patch.add(path: string, element: JsonValue): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to add a value to a collection:
patch.add('custom.pets', 'crocodile');This method combines two set of values.
The following table shows how the operation behaves in different scenarios:
| Current Value | Given Value | Result |
|---|---|---|
[] |
[] |
[] |
[] |
['a', 'a'] |
['a'] |
['a'] |
null |
['a'] |
['a'] |
'b' |
['a', 'b'] |
['a'] |
['b', null] |
['a', 'b'] |
[null] |
['a'] |
['a'] |
null |
null |
[] |
null |
['a'] |
['a'] |
null |
'a' |
['a'] |
'a' |
'b' |
['a', 'b'] |
'a' |
['b'] |
['a', 'b'] |
'a' |
['a'] |
['a'] |
The combine method has the following signature:
patch.combine(path: string, value: JsonValue): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to combine sets:
patch.combine('custom.pets', ['crocodile', 'iguana']);This method merges two maps or lists.
The following table shows how the operation behaves in different scenarios:
| Current Value | Given Value | Result |
|---|---|---|
{} |
{} |
{} |
{} |
{a: 1} |
{a: 1} |
{a: 1} |
{b: 2} |
{a: 1, b: 2} |
{a: 1} |
{a: 2} |
{a: 2} |
null |
{a: 1} |
{a: 1} |
null |
[1] |
[1] |
1 |
[2] |
[1, 2] |
[] |
[1] |
[1] |
[1] |
[2] |
[1, 2] |
['a', 'b'] |
['b', 'c'] |
['a', 'b', 'b', 'c'] |
The merge method has the following signature:
patch.merge(path: string, value: JsonArray | JsonMap): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to merge maps:
patch.merge('preferences', {color: 'green'});This method increments a value by a given amount.
The following table shows how the operation behaves in different scenarios:
| Current Value | Amount | Result |
|---|---|---|
null |
10 | 10 |
0 |
10 | 10 |
-1 |
10 | 9 |
The increment method has the following signature:
patch.increment(path: string, value: number = 1): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to increment a value:
patch.increment('custom.score', 10);This method decrements a value by a given amount.
The following table shows how the operation behaves in different scenarios:
| Current Value | Amount | Result |
|---|---|---|
null |
10 | -10 |
0 |
10 | -10 |
1 |
10 | -9 |
The decrement method has the following signature:
patch.decrement(path: string, value: number = 1): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to decrement a value:
patch.decrement('custom.score', 10);This method removes values from a collection.
The following table shows how the operation behaves in different scenarios:
| Current Value | Given Value | Result |
|---|---|---|
['a', 'b', 'c'] |
'a' |
['b', 'c'] |
['a', 'b', 'c', 'c'] |
'c' |
['a', 'b'] |
['a', 'b', 'c'] |
'd' |
['a', 'b', 'c'] |
['a', {b: 1}, 'c'] |
{b: 1} |
['a', 'c'] |
The remove method has the following signature:
patch.remove(path: string, value: JsonValue): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to remove a value from a collection:
patch.remove('custom.pets', 'crocodile');This method clears the value at given path.
The following table shows how the operation behaves in different scenarios:
| Current Value | Result |
|---|---|
null |
null |
[] |
[] |
['a'] |
[] |
'foo' |
null |
Note that the operation will not fail if the path does not exist.
The clear method has the following signature:
patch.clear(path: string): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to clear a given path:
patch.clear('custom.pets');This method deletes a given path.
The difference between unset and clear is that unset deletes the path,
while clear removes the value by setting it to null or removing all its elements.
Note that the operation will not fail if the path does not exist.
The unset method has the following signature:
patch.unset(path: string): thisThe return is the Patch instance itself to allow operation chaining.
Here's a minimal example showing how to unset a value:
patch.unset('custom.pets');This method builds the patch and emits an event to record the specified changes.
Notice that the processing performed by a patch is atomic to prevent entities from ending up in an inconsistent state. So either all operations are applied, or none of them are.
The save method has the following signature:
patch.save(): Promise<Event>The return is a Promise that resolves to the tracked event after successful transmission.
Here's a minimal example showing how save the specified changes:
patch.save();