Update | dynamodb-datamodel

Set of helper methods used to build UpdateExpression for use in DynamoDB update method.

example

examples/Update.Model.ts (imports: examples/Table.ts)

import { Fields, Model, Table, Update } from 'dynamodb-datamodel';
import { table } from './Table';

interface ModelKey {
  id: string;
}
interface ModelItem extends ModelKey {
  name: Update.String;
  revision: Update.Number;
  nickName: Update.String;
}

const model = Model.createModel<ModelKey, ModelItem>({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    name: Fields.string(),
    nickName: Fields.string(),
    revision: Fields.number(),
  },
  table: table as Table,
});

// update will: set name attribute to 'new name', delete nickName attribute and increment revision attribute by 2.
const params = model.updateParams({
  id: 'P-1.S-1',
  name: 'new name',
  nickName: Update.del(),
  revision: Update.inc(2),
});

// (jest) output of updateParams
expect(params).toEqual({
  ExpressionAttributeNames: { '#n0': 'name', '#n1': 'nickName', '#n2': 'revision' },
  ExpressionAttributeValues: { ':v0': 'new name', ':v1': 2 },
  Key: { P: 'P-1', S: 'S-1' },
  ReturnValues: 'ALL_NEW',
  TableName: 'ExampleTable',
  UpdateExpression: 'SET #n0 = :v0, #n2 = #n2 + :v1 REMOVE #n1',
});

Using Table (though in most cases you'll use Model):

example

examples/Update.Table.ts (imports: examples/Table.ts)

import { Update } from 'dynamodb-datamodel';
import { table } from './Table';

// update will: set name attribute to 'new name', delete nickName attribute and increment revision attribute by 2.
const params = table.updateParams(
  { P: 'P-1', S: 'S-1' },
  { name: 'new name', nickName: Update.del(), revision: Update.inc(2) },
);

// (jest) output of updateParams
expect(params).toEqual({
  ExpressionAttributeNames: { '#n0': 'name', '#n1': 'nickName', '#n2': 'revision' },
  ExpressionAttributeValues: { ':v0': 'new name', ':v1': 2 },
  Key: { P: 'P-1', S: 'S-1' },
  ReturnValues: 'ALL_NEW',
  TableName: 'ExampleTable',
  UpdateExpression: 'SET #n0 = :v0, #n2 = #n2 + :v1 REMOVE #n1',
});

Hierarchy

Update

Index

Constructors

constructor

Methods

Constructors

constructor

new Update(): Update

Returns Update

Methods

Static add

add(left: OperandNumber, right: OperandNumber): Update.Resolver<"N">

Sets an attribute to the result of adding two values. Note: The reference attributes must exists for the update to succeed. Supported types: number.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    base: Fields.number(),
    count: Fields.number(),
  },
  // ...additional properties like table
});

// Sets count attribute to the result of adding 3 to the 'base' attribute
// Example: If base = 5, then after this update count will be 8
model.update({
  id: 'P-GUID.S-0',
  count: Update.add('base', 3),
});

Parameters

left: OperandNumber

A value (or reference attribute) to using in add operation.
right: OperandNumber

A value (or reference attribute) to using in add operation.

Returns Update.Resolver<"N">

Update resolver function to set a number attribute to the result of adding two values.

Static addToSet

addToSet(value: AttributeSetValues): Update.Resolver<"BS" | "NS" | "SS">

Adds an array of values to a set based attribute (sets are ordered). Supported types: StringSet, NumberSet or BinarySet.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    colors: Fields.stringSet(),
  },
  // ...additional properties like table
});

// Adds 'yellow' and 'red' to the colors attribute
// Example: If colors = ['blue', 'yellow'], then after this update colors will be ['blue', 'red', 'yellow']
model.update({
  id: 'P-GUID.S-0',
  colors: Update.addToSet(model.table.createStringSet(['yellow', 'red']));
});

Parameters

value: AttributeSetValues

Array of values to add.

Returns Update.Resolver<"BS" | "NS" | "SS">

Update resolver function to add an array of values to a set based attribute.

Static append

append(value: OperandList<Table.AttributeValues>): Update.Resolver<"L">

Appends items to the end of an existing list attribute. Supported types: list.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    groups: Fields.list(),
  },
  // ...additional properties like table
});

// Appends 'soccer' and 'tennis' to the end of the list in groups attribute
// Example: If groups = ['baseball', 'swimming'], then after this update it would be ['baseball', 'swimming', 'soccer', 'tennis']
model.update({
  id: 'P-GUID.S-0',
  groups: Update.append(['soccer', 'tennis']),
});

Parameters

value: OperandList<Table.AttributeValues>

A list (or reference attribute) to append.

Returns Update.Resolver<"L">

Update resolver function to append a list to an attribute.

Static arithmetic

arithmetic(left: undefined | OperandNumber, op: "+" | "-", right: OperandNumber): Update.Resolver<"N">

- Defined in Update.ts:172
Sets an attribute to the result of an arithmetic expression. Note: The reference attributes must exists for the update to succeed. Helper method used by inc, dec, add and sub.

Parameters
- left: undefined | OperandNumber
  
  A value (or reference attribute) used on the left side of the arithmetic expression.
- op: "+" | "-"
  
  Operation to use for expression.
- right: OperandNumber
  
  A value (or reference attribute) used on the left side of the arithmetic expression.
Returns Update.Resolver<"N">
Update resolver function to set a number attribute to the result of the arithmetic expression.

Static dec

dec(value: OperandNumber): Update.Resolver<"N">

Decrements a number based attribute by a certain amount. Note: The attribute that is being decremented must exist in the table item for this update to succeed. Supported types: number.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    count: Fields.number(),
  },
  // ...additional properties like table
});

// Decrements the count attribute by 2
// Example: if count = 5, then after this update it would be 3
model.update({
  id: 'P-GUID.S-0',
  count: Update.dec(2),
});

Parameters

value: OperandNumber

A value (or reference attribute) to decrement the number attribute by.

Returns Update.Resolver<"N">

Update resolver function to decrement the attribute.

Static default

default<T>(value: T): Update.Resolver<Table.AttributeTypes>

Sets the default value for an attribute that does not exist in on the table item.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    name: Fields.string(),
  },
  // ...additional properties like table
});

// Set name attribute to 'Default Name' only if it doesn't exists
model.update({
  id: 'P-GUID.S-0',
  name: Update.default('Default Name'),
});

Type parameters

T: Table.AttributeValues

Parameters

value: T

Default value to set if attribute value does not exist.

Returns Update.Resolver<Table.AttributeTypes>

Update resolver function to set default value.

Static del

del(path?: string): Update.Resolver<Table.AttributeTypes>

Delete the attribute from the table item. Setting an model property to null also deletes the attribute.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    name: Fields.string(),
  },
  // ...additional properties like table
});

// Deletes name attribute from item.  Could also use "name: null" to do the same thing.
model.update({
  id: 'P-GUID.S-0',
  name: Update.del(),
});

Parameters

Optional path: string

Returns Update.Resolver<Table.AttributeTypes>

Update resolver function to delete attribute.

Static delIndexes

delIndexes(indexes: number[]): Update.Resolver<"L">

Deletes an array of indices from an list based attribute (the lists are 0 based). Supported types: list.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    children: Fields.list(),
  },
  // ...additional properties like table
});

// Removes the values at the 1st and 2nd index in the children attribute.
// Example: If children = ['john', 'jill', 'bob', 'betty'], then after this update children will be ['john', 'betty']
model.update({
  id: 'P-GUID.S-0',
  children: Update.delIndexes([1, 2]);
});

Parameters

indexes: number[]

Array of indices (numbered indexes into the list) to delete from the list.

Returns Update.Resolver<"L">

Update resolver function to delete indices in a list based attribute.

Static inc

inc(value: OperandNumber): Update.Resolver<"N">

Increments a number based attribute by a certain amount. Note: The attribute that is being incremented must exist in the table item for this update to succeed. Supported types: number.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    count: Fields.number(),
  },
  // ...additional properties like table
});

// Increments the count attribute by 1
// Example: If count = 3, then after this update it would be 4
model.update({
  id: 'P-GUID.S-0',
  count: Update.inc(1),
});

Parameters

value: OperandNumber

A value (or reference attribute) to increment the number attribute by.

Returns Update.Resolver<"N">

Update resolver function to increment the attribute.

Static join

join(left?: OperandList<Table.AttributeValues>, right?: OperandList<Table.AttributeValues>): Update.Resolver<"L">

Sets an attribute to the result of joining two lists. Supported types: list.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    parents: Fields.list(),
    ancestors: Fields.list(),
  },
  // ...additional properties like table
});

// Sets ancestors attribute to the result of joining the list from the parents attribute with ['grandpa, 'grandma']
// Example: if parents = ['mom', 'dad'], then after this update ancestors will be ['mom', 'dad', 'grandpa', 'grandma']
model.update({
  id: 'P-GUID.S-0',
  ancestors: Update.join('parents', ['grandpa', 'grandma']),
});

Parameters

Optional left: OperandList<Table.AttributeValues>

A list (or reference attribute) to add to the start.
Optional right: OperandList<Table.AttributeValues>

A list (or reference attribute) to add at the end.

Returns Update.Resolver<"L">

Update resolver function to set an attribute to the joining of two lists.

Static map

map(map: ResolverMap): Update.Resolver<"M">

- Defined in Update.ts:557
Updates the inner attributes of a map based attribute. set is used to overwrite the entire map attribute, while map updates the attributes inside of table attribute. Example if an address attribute is set to { street: 'One Infinite Loop', city: 'Cupertino', state: 'CA, zip: '95014' } then using Update.map({street: '1 Apple Park Way'}) will result in { street: '1 Apple Park Way', city: 'Cupertino', state: 'CA, zip: '95014' }, while using Update.set({street: '1 Apple Park Way'}) will result in { street: '1 Apple Park Way' }. Supported types: map.
example
```
import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    address: Fields.map(),
  },
  // ...additional properties like table
});

// Update only the street property inside of the address attribute
// Example: If address = { street: 'One Infinite Loop', city: 'Cupertino', state: 'CA, zip: '95014' } then
// after this update address will be { street: '1 Apple Park Way', city: 'Cupertino', state: 'CA, zip: '95014' }
model.update({
  id: 'P-GUID.S-0',
  address: Update.map({
    street: '1 Apple Park Way'
  });
});
```
Parameters
- map: ResolverMap
  
  Map of update values and resolvers to evaluate.
Returns Update.Resolver<"M">
Update resolver function to recursively set the inner attributes of a map based attribute.

Static model

model<T>(map: ResolverModel<T>): Update.Resolver<"M">

- Defined in Update.ts:569
Typed based version of Update.map.

Type parameters
- T
Parameters
- map: ResolverModel<T>
  
  The model or resolver to create resolver for.
Returns Update.Resolver<"M">
Update resolver function to remove an array of values from a set based attribute.

Static modelMap

modelMap<T>(map: ResolverModelMap<T>): Update.Resolver<"M">

- Defined in Update.ts:579
Map that contains string keys with a Model T for each value.

Type parameters
- T
Parameters
- map: ResolverModelMap<T>
  
  Map containing the models to change for each key.
Returns Update.Resolver<"M">
Update resolver function to remove an array of values from a set based attribute.

Static path

path(path: string): OperandFunction

Used to reference other attributes for the value argument in Update.* methods.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    fullName: Fields.string(),
    name: Fields.string(),
  },
  // ...additional properties like table
});

// Sets name attribute to the value of the fullName attribute
// Example: If fullName = 'John Smith', then name would be set to 'John Smith'
model.update({
  id: 'P-GUID.S-0',
  name: Update.path('fullName'),
});

Parameters

path: string

Attribute path to resolve and get alias for.

Returns OperandFunction

Update function that returns the alias for the path.

Static pathWithDefault

pathWithDefault<T>(path: string, value: T): OperandFunction

Used to reference other attributes for the value argument in Update.* methods.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    fullName: Fields.string(),
    name: Fields.string(),
  },
  // ...additional properties like table
});

// Sets name attribute to the value of the fullName attribute, if fullName
// attribute doesn't exists then set name attribute to 'User Name'.
model.update({
  id: 'P-GUID.S-0',
  name: Update.pathWithDefault('fullName', 'User Name'),
});

Type parameters

T: Table.AttributeValues

Parameters

path: string

Attribute path to resolve and get alias for.
value: T

The default value to set if the path attribute value does not exist.

Returns OperandFunction

Update function that returns the alias for the path.

Static prepend

prepend(value: OperandList<Table.AttributeValues>): Update.Resolver<"L">

Prepends items to the beginning of an existing list attribute. Supported types: list.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    groups: Fields.list(),
  },
  // ...additional properties like table
});

// Prepends 'soccer', 'tennis' to the beginning of the list in groups attribute
// Example: If groups = ['baseball', 'swimming'], then after this update it would be ['soccer', 'tennis', 'baseball', 'swimming']
model.update({
  id: 'P-GUID.S-0',
  groups: Update.prepend(['soccer', 'tennis']),
});

Parameters

value: OperandList<Table.AttributeValues>

A list (or reference attribute) to prepend.

Returns Update.Resolver<"L">

Update resolver function to prepend a list to an attribute.

Static removeFromSet

removeFromSet(value: AttributeSetValues): Update.Resolver<"BS" | "NS" | "SS">

Removes an array of values from a set based attribute (sets are ordered). Supported types: StringSet, NumberSet or BinarySet.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    colors: Fields.stringSet(),
  },
  // ...additional properties like table
});

// Remove 'yellow' and 'red' from the colors attribute
// Example: If colors = ['blue', 'yellow'], then after this update colors will be ['blue']
model.update({
  id: 'P-GUID.S-0',
  colors: Update.removeFromSet(model.table.createStringSet(['yellow', 'red']));
});

Parameters

value: AttributeSetValues

Array of values to remove.

Returns Update.Resolver<"BS" | "NS" | "SS">

Update resolver function to remove an array of values from a set based attribute.

Static set

set<T>(value: OperandValue<T>): Update.Resolver<Table.AttributeTypes>

- Defined in Update.ts:160
Sets the attribute to a new value. Set is the default action for model property not set to a Update.Resolver or null.
example
```
import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    name: Fields.string(),
  },
  // ...additional properties like table
});

// Sets name attribute from item.  Could also use "name: 'new name'" to do the same thing.
model.update({
  id: 'P-GUID.S-0',
  name: Update.set('new name'),
});
```
Type parameters
- T: Table.AttributeValues
Parameters
- value: OperandValue<T>
  
  The value (or attribute reference) to update the item attribute to, will add attribute if not present.
Returns Update.Resolver<Table.AttributeTypes>
Update resolver function to set attribute to a value.

Static setIndexes

setIndexes(values: {}): Update.Resolver<"L">

Sets the values of select indices for list based attribute. Supported types: list.

example

import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    children: Fields.list(),
  },
  // ...additional properties like table
});

// Sets the values at the 1st and 2nd index in the children attribute to be 'margret' and 'mathew' respectively
// Example: If children = ['john', 'jill', 'bob', 'betty'], then after this update children will be ['john', 'margret', 'mathew', 'betty']
model.update({
  id: 'P-GUID.S-0',
  children: Update.setIndexes({1: 'margret', 2: 'mathew'});
});

Parameters

values: {}
- [key: number]: OperandValue | undefined

Returns Update.Resolver<"L">

Update resolver function to set values for select indices in a list based attribute.

Static sub

sub(left: OperandNumber, right: OperandNumber): Update.Resolver<"N">

- Defined in Update.ts:304
Sets an attribute to the result of subtracting two values. Note: The reference attributes must exists for the update to succeed. Supported types: number.
example
```
import { Fields, Model, Update } from 'dynamodb-datamodel';

const model = new Model({
  schema: {
    id: Fields.split({ aliases: ['P', 'S'] }),
    base: Fields.number(),
    count: Fields.number(),
  },
  // ...additional properties like table
});

// Sets count attribute to the result of subtracting 2 from the 'base' attribute
// Example: If base = 9, then after this update count would be 7
model.update({
  id: 'P-GUID.S-0',
  count: Update.sub('base', 2),
});
```
Parameters
- left: OperandNumber
  
  A value (or reference attribute) to use on the left side of a subtract operation.
- right: OperandNumber
  
  A value (or reference attribute) to use on the right side of a subtract operation.
Returns Update.Resolver<"N">
Update resolver function to set a number attribute to the result of subtracting two values.

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Returns Update

Methods

Static add

Parameters

left: OperandNumber

right: OperandNumber

Returns Update.Resolver<"N">

Static addToSet

Parameters

value: AttributeSetValues

Returns Update.Resolver<"BS" | "NS" | "SS">

Static append

Parameters

value: OperandList<Table.AttributeValues>

Returns Update.Resolver<"L">

Static arithmetic

Parameters

left: undefined | OperandNumber

op: "+" | "-"

right: OperandNumber

Returns Update.Resolver<"N">

Static dec

Parameters

value: OperandNumber

Returns Update.Resolver<"N">

Static default

Type parameters

T: Table.AttributeValues

Parameters

value: T

Returns Update.Resolver<Table.AttributeTypes>

Static del

Parameters

Optional path: string

Returns Update.Resolver<Table.AttributeTypes>

Static delIndexes

Parameters

indexes: number[]

Returns Update.Resolver<"L">

Static inc

Parameters

value: OperandNumber

Returns Update.Resolver<"N">

Static join

Parameters

Optional left: OperandList<Table.AttributeValues>

Optional right: OperandList<Table.AttributeValues>

Returns Update.Resolver<"L">

Static map

Parameters

map: ResolverMap

Returns Update.Resolver<"M">

Static model

Type parameters

T

Parameters

map: ResolverModel<T>

Returns Update.Resolver<"M">

Static modelMap

Type parameters

T

Parameters

map: ResolverModelMap<T>

Returns Update.Resolver<"M">

Static path

Parameters

path: string

Returns OperandFunction

Static pathWithDefault

Type parameters

T: Table.AttributeValues

Parameters

path: string

value: T