Table | dynamodb-datamodel

Object that represents the DynamoDB table.

In most single table designs secondary indexes will be used like in the following example:

example

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

import { DocumentClient } from 'aws-sdk/clients/dynamodb';
import { Table } from 'dynamodb-datamodel';
import { GSI0Key, gsi0, LSI0Key, lsi0 } from './Index';
export { GSI0Key, gsi0, LSI0Key, lsi0 }; // export from here to consolidate imports

// Good practice to covert empty values to null
export const client = new DocumentClient({ convertEmptyValues: true });

// Define the table primary key interface.
export interface TableKey {
  P: Table.PrimaryKey.PartitionString;
  S?: Table.PrimaryKey.SortString;
}

// Define the combined primary keys across the table and secondary indexes.
interface KeyAttributes extends TableKey, GSI0Key, LSI0Key {}

// Create the table object with global and local secondary indexes.
// name, keyAttributes and keySchema should match the DynamoDB's table CloudFormation resource.
export const table = Table.createTable<TableKey, KeyAttributes>({
  client,
  name: 'ExampleTable',
  // Defines the attribute type ('S', 'N', 'B') for all primary keys, table and indexes.
  keyAttributes: {
    P: Table.PrimaryKey.StringType,
    S: Table.PrimaryKey.StringType,
    G0P: Table.PrimaryKey.StringType,
    G0S: Table.PrimaryKey.StringType,
    L0S: Table.PrimaryKey.NumberType,
  },
  // Defines the key type ('HASH' or 'RANGE') for the table primary keys.
  keySchema: {
    P: Table.PrimaryKey.PartitionKeyType,
    S: Table.PrimaryKey.SortKeyType,
  },
});

Hierarchy

Table
- TableT

Constructors

constructor

new Table(params: TableParams): Table

- Defined in Table.ts:53
Parameters
- params: TableParams
  
  Initialize the Table's name, attributes, keySchema and index properties.
Returns Table

Properties

keyAttributes

keyAttributes: AttributeTypesMap

Definition of the attribute types required for table and index primary key and for index projected attributes. These need to be defined at the table level since the attributes are table wide concept.

keySchema

keySchema: KeyTypesMap

Schema map for the Table's primary key, in the form of { <partition key name>: { keyType: 'HASH' } }.

name

name: string

Name of the DynamoDB table, used to set the TableName when calling DynamoDB methods.

onError

onError: (msg: string) => void = ...

Type declaration

- (msg: string): void
- Determines how errors should be handled. The default is to throw on any errors.
  
  Parameters
  - msg: string
  Returns void

Accessors

client

get client(): DocumentClient

- Defined in Table.ts:65
Gets the DocumentClient associated with this Table, which may mean creating one.

Returns DocumentClient
The DocumentClient used for all Table operations.

Methods

createBinarySet

createBinarySet(list: binaryType[], options?: CreateSetOptions): BinarySet

- Defined in Table.ts:123
Create a binary set from a binary array.

Parameters
- list: binaryType[]
  
  Binary array to create set from.
- Optional options: CreateSetOptions
  
  Options to pass DocumentClient createSet.
Returns BinarySet

createNumberSet

createNumberSet(list: number[], options?: CreateSetOptions): NumberSet

- Defined in Table.ts:114
Create a number set from a number array.

Parameters
- list: number[]
  
  Number array to create set from.
- Optional options: CreateSetOptions
  
  Options to pass DocumentClient createSet.
Returns NumberSet

createSet

createSet(list: string[] | number[] | binaryType[], options?: CreateSetOptions): AttributeSetValues

- Defined in Table.ts:93
Wrapper around the DocumentClient.createSet used by the below create*Set methods to create type safe sets. Choose to leverage DocumentClient implementation of set to allow DocumentClient to correctly auto convert to DynamoDB's native types.

Parameters
- list: string[] | number[] | binaryType[]
  
  Array of items to create the set from.
- Optional options: CreateSetOptions
  
  Options to pass DocumentClient createSet.
Returns AttributeSetValues

createStringSet

createStringSet(list: string[], options?: CreateSetOptions): StringSet

- Defined in Table.ts:105
Create a string set from a string array.

Parameters
- list: string[]
  
  String array to create set from.
- Optional options: CreateSetOptions
  
  Options to pass DocumentClient createSet.
Returns StringSet

delete

delete(key: Table.PrimaryKey.AttributeValuesMap, options?: DeleteOptions): Promise<DeleteItemOutput>

- Defined in Table.ts:239
Wrapper method for DocumentClient.delete method.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of item to delete.
- Optional options: DeleteOptions
  
  Additional optional options to use for delete.
Returns Promise<DeleteItemOutput>
Async promise returned by DocumentClient.delete method.

deleteParams

deleteParams(key: Table.PrimaryKey.AttributeValuesMap, options?: DeleteOptions): DeleteItemInput

- Defined in Table.ts:143
Creates the params that can be used when calling DocumentClient.delete.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of the item to delete.
- options: DeleteOptions = {}
  
  Additional optional options to use for delete.
Returns DeleteItemInput
Input params for DocumentClient.delete.

get

get(key: Table.PrimaryKey.AttributeValuesMap, options?: GetOptions): Promise<GetItemOutput>

- Defined in Table.ts:229
Wrapper method for DocumentClient.get method.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of item to get.
- Optional options: GetOptions
  
  Additional optional options to use for get.
Returns Promise<GetItemOutput>
Async promise returned by DocumentClient.get method.

getParams

getParams(key: Table.PrimaryKey.AttributeValuesMap, options?: GetOptions): GetInput

- Defined in Table.ts:133
Creates the params that can be used when calling DocumentClient.get.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of the item to get.
- options: GetOptions = {}
  
  Additional optional options to use for get.
Returns GetInput
Input params for DocumentClient.get.

getPartitionKey

getPartitionKey(): string

- Defined in Table.ts:74
Gets the partition key name for the Table.

Returns string
The name of the primary (or HASH) key attribute.

getPutCondition

getPutCondition(options: undefined | PutWriteOptions): void | Condition.Resolver

- Defined in Table.ts:155
Get the condition that is needed to support a specific PutWriteOptions.

Parameters
- options: undefined | PutWriteOptions
  
  Type of put to get the condition for.
Returns void | Condition.Resolver
Condition resolver that maps to the PutWriteOptions.

getSortKey

getSortKey(): string

- Defined in Table.ts:82
Gets the sort key name for the Table.

Returns string
The name of the sort (or RANGE) key attribute.

put

put(key: Table.PrimaryKey.AttributeValuesMap, items?: Table.AttributeValuesMap, options?: PutOptions): Promise<PutItemOutput>

- Defined in Table.ts:253
Wrapper method for DocumentClient.put method.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of item to put.
- Optional items: Table.AttributeValuesMap
- Optional options: PutOptions
  
  Additional optional options to use for put.
Returns Promise<PutItemOutput>
Async promise returned by DocumentClient.put method.

putParams

putParams(key: Table.PrimaryKey.AttributeValuesMap, item?: Table.AttributeValuesMap, options?: PutOptions): PutItemInput

- Defined in Table.ts:167
Creates the params that can be used when calling DocumentClient.put.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of item to put.
- Optional item: Table.AttributeValuesMap
  
  Attributes of the item to put.
- options: PutOptions = {}
  
  Additional optional options to use for put.
Returns PutItemInput
Input params for DocumentClient.put.

query

query(key: KeyQueryMap, options?: QueryOptions): Promise<QueryOutput>

- Defined in Table.ts:283
Wrapper around DocumentClient.query. method that uses the index and table properties with the key and options params.

Parameters
- key: KeyQueryMap
  
  Primary key with optional KeyCondition to query the secondary index with.
- Optional options: QueryOptions
  
  Used in building the query params.
Returns Promise<QueryOutput>
Promise with the query results, including items fetched.

queryParams

queryParams(key: KeyQueryMap, options?: QueryOptions): QueryInput

- Defined in Table.ts:208
Creates the params that can be used when calling DocumentClient.query method.

Parameters
- key: KeyQueryMap
  
  Primary key with optional KeyCondition to query the table with.
- options: QueryOptions = {}
  
  Used in building the query params.
Returns QueryInput
Input params for DocumentClient.query.

scan

scan(options?: ScanOptions): Promise<ScanOutput>

- Defined in Table.ts:293
Wrapper around DocumentClient.scan. method that uses the index and table properties with the options param.

Parameters
- Optional options: ScanOptions
  
  Used in building the scan params.
Returns Promise<ScanOutput>
Promise with the scan results, including items fetched.

scanParams

scanParams(options?: ScanOptions): ScanInput

- Defined in Table.ts:219
Creates the params that can be used when calling DocumentClient.scan method.

Parameters
- options: ScanOptions = {}
  
  Used in building the scan params.
Returns ScanInput
Input params for DocumentClient.scan method.

setBatchGet

setBatchGet(batchGet: BatchGet, keys: Table.PrimaryKey.AttributeValuesMap[], options?: BatchGetTableOptions): BatchGet

- Defined in Table.ts:304
Creates the params that can be used when calling DocumentClient.batchGet method.

Parameters
- batchGet: BatchGet
  
  Batch get object to set the table get on.
- keys: Table.PrimaryKey.AttributeValuesMap[]
  
  Keys of items to get.
- Optional options: BatchGetTableOptions
  
  Set of get options for table.
Returns BatchGet
BatchGet object passed in, to support calling execute on same line.

setBatchWrite

setBatchWrite(batchWrite: BatchWrite, putItems?: PutItem[], delKeys?: Table.PrimaryKey.AttributeValuesMap[]): BatchWrite

- Defined in Table.ts:320
Creates the params that can be used when calling DocumentClient.batchWrite method.

Parameters
- batchWrite: BatchWrite
  
  Batch write object to set the table write on.
- Optional putItems: PutItem[]
  
  Items to put in the table.
- Optional delKeys: Table.PrimaryKey.AttributeValuesMap[]
  
  Keys of items to delete from the table.
Returns BatchWrite
BatchWrite object passed in, to support calling execute on same line.

setTransactGet

setTransactGet(transactGet: TransactGet, getItems: TransactGetItem[]): TransactGet

- Defined in Table.ts:336
Creates the params that can be used when calling DocumentClient.transactGet method.

Parameters
- transactGet: TransactGet
- getItems: TransactGetItem[]
  
  Keys of items and associated attributes to get.
Returns TransactGet
TransactGet object passed in, to support calling execute on same line.

setTransactWrite

setTransactWrite(transactWrite: TransactWrite, write: TransactWriteData): TransactWrite

- Defined in Table.ts:347
Creates the params that can be used when calling DocumentClient.transactWrite method.

Parameters
- transactWrite: TransactWrite
- write: TransactWriteData
  
  Set of operations to write in the transaction.
Returns TransactWrite
TransactWrite object passed in, to support calling execute on same line.

update

update(key: Table.PrimaryKey.AttributeValuesMap, item?: ResolverMap, options?: UpdateOptions): Promise<UpdateItemOutput>

- Defined in Table.ts:268
Wrapper method for DocumentClient.update method.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of item to update.
- Optional item: ResolverMap
  
  Attributes of the item to update.
- Optional options: UpdateOptions
  
  Additional optional options to use for update.
Returns Promise<UpdateItemOutput>
Async promise returned by DocumentClient.update method.

updateParams

updateParams(key: Table.PrimaryKey.AttributeValuesMap, item?: ResolverMap, options?: UpdateOptions): UpdateItemInput

- Defined in Table.ts:190
Creates the params that can be used when calling DocumentClient.update. By default this method uses ReturnValues: 'ALL_NEW' to return all of the properties for an item, since many APIs or server code use the updated values in some way.

Parameters
- key: Table.PrimaryKey.AttributeValuesMap
  
  Primary key of item to update.
- Optional item: ResolverMap
  
  Attributes of the item to update.
- options: UpdateOptions = {}
  
  Additional optional options to use for update.
Returns UpdateItemInput
Input params for DocumentClient.update.

Static addBatchParams

addBatchParams(options: { consumed?: string; metrics?: string; token?: string }, params: { ClientRequestToken?: string; ReturnConsumedCapacity?: string; ReturnItemCollectionMetrics?: string }): void

- Defined in Table.ts:450
Translates options into batch or transact based input params.

Parameters
- options: { consumed?: string; metrics?: string; token?: string }
  
  Common batch or transact options to set on params.
  - Optional consumed?: string
  - Optional metrics?: string
  - Optional token?: string
- params: { ClientRequestToken?: string; ReturnConsumedCapacity?: string; ReturnItemCollectionMetrics?: string }
  
  Input params to set based on options.
  - Optional ClientRequestToken?: string
  - Optional ReturnConsumedCapacity?: string
  - Optional ReturnItemCollectionMetrics?: string
Returns void

Static addItemAttributes

addItemAttributes<T>(params: T, attributes: Table.ExpressionAttributes, itemAttributes?: string[]): void

- Defined in Table.ts:383
Appends attributes names to the ProjectionExpression for input params.

Type parameters
- T: ExpressionParams
Parameters
- params: T
  
  Params to add ProjectionExpression on.
- attributes: Table.ExpressionAttributes
  
  Definition of the attribute types required for table and index primary key and for index projected attributes.
- Optional itemAttributes: string[]
  
  List of attribute names to return.
Returns void
Params that have ProjectionExpression added to.

Static addParams

addParams<T>(params: T, options: AddParamsOptions, addParams?: AddExpressionParams, getAttributes?: () => Table.ExpressionAttributes): T & { ConditionExpression?: string; FilterExpression?: string; KeyConditionExpression?: string; ProjectionExpression?: string; UpdateExpression?: string } & ExpressionAttributeParams

- Defined in Table.ts:402
Add expressions properties to the params object.

Type parameters
- T: ExpressionParams
Parameters
- params: T
  
  The params object to add expression properties to.
- options: AddParamsOptions
  
  Options used to build params.
- Optional addParams: AddExpressionParams
- Optional getAttributes: () => Table.ExpressionAttributes
  - - (): Table.ExpressionAttributes
    - Returns Table.ExpressionAttributes
Returns T & { ConditionExpression?: string; FilterExpression?: string; KeyConditionExpression?: string; ProjectionExpression?: string; UpdateExpression?: string } & ExpressionAttributeParams
Params object that was passed in with expression added.

Static addWriteParams

addWriteParams<T>(params: T, item: { conditions?: Condition.Resolver[]; returnFailure?: string }, addParams?: AddExpressionParams): T & { ConditionExpression?: string; FilterExpression?: string; KeyConditionExpression?: string; ProjectionExpression?: string; UpdateExpression?: string } & ExpressionAttributeParams

- Defined in Table.ts:429
Add expressions properties to the params object.

Type parameters
- T: { ConditionExpression?: string; FilterExpression?: string; KeyConditionExpression?: string; ProjectionExpression?: string; UpdateExpression?: string } & ExpressionAttributeParams & { ReturnValuesOnConditionCheckFailure?: string }
Parameters
- params: T
  
  The params object to add expression properties to.
- item: { conditions?: Condition.Resolver[]; returnFailure?: string }
  
  Transact write item used to build params.
  - Optional conditions?: Condition.Resolver[]
  - Optional returnFailure?: string
- Optional addParams: AddExpressionParams
Returns T & { ConditionExpression?: string; FilterExpression?: string; KeyConditionExpression?: string; ProjectionExpression?: string; UpdateExpression?: string } & ExpressionAttributeParams
Params object that was passed in with expression added.

Static getKeyName

getKeyName(keySchema: KeyTypesMap, type: KeyTypes): string

- Defined in Table.ts:473
Finds the partition or sort key name for a table or index key schema.

Parameters
- keySchema: KeyTypesMap
  
  Table key schema to find the primary key in.
- type: KeyTypes
  
  Primary key type to look for, either HASH or RANGE.
Returns string
Name of the key if it exists otherwise an empty string.

Static getPutAction

getPutAction(options?: PutWriteOptions): PutItemActions

- Defined in Table.ts:361
Maps PutWriteOptions to one of the put based ItemActions used by Fields to tell the type of put operation.

Parameters
- Optional options: PutWriteOptions
  
  Put write option to map into a put item action.
Returns PutItemActions

Static isPutAction

isPutAction(action: ItemActions): boolean

- Defined in Table.ts:372
Checks if item action is a put based action.

Parameters
- action: ItemActions
  
  Item actions to check if put.
Returns boolean
True if item action is a put action.

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

params: TableParams

Returns Table

Properties

keyAttributes

keySchema

name

onError

Type declaration

Parameters

msg: string

Returns void

Accessors

client

Returns DocumentClient

Methods

createBinarySet

Parameters

list: binaryType[]

Optional options: CreateSetOptions

Returns BinarySet

createNumberSet

Parameters

list: number[]

Optional options: CreateSetOptions

Returns NumberSet

createSet

Parameters

list: string[] | number[] | binaryType[]

Optional options: CreateSetOptions

Returns AttributeSetValues

createStringSet

Parameters

list: string[]

Optional options: CreateSetOptions

Returns StringSet

delete

Parameters

key: Table.PrimaryKey.AttributeValuesMap

Optional options: DeleteOptions

Returns Promise<DeleteItemOutput>

deleteParams

Parameters

key: Table.PrimaryKey.AttributeValuesMap

options: DeleteOptions = {}

Returns DeleteItemInput

get

Parameters

key: Table.PrimaryKey.AttributeValuesMap

Optional options: GetOptions

Returns Promise<GetItemOutput>

getParams

Parameters

key: Table.PrimaryKey.AttributeValuesMap

options: GetOptions = {}

Returns GetInput

getPartitionKey

Returns string

getPutCondition

Parameters

options: undefined | PutWriteOptions

Returns void | Condition.Resolver

getSortKey

Returns string

put

Parameters

key: Table.PrimaryKey.AttributeValuesMap

Optional items: Table.AttributeValuesMap

Optional options: PutOptions

Returns Promise<PutItemOutput>

putParams

Parameters