Table Manager

TableManager is used to perform operations on DynamoDB table. It also initializes Entity Managers that act as repositories for your models.

new TableManager(tableEntity, tableMetadata)

This constructor initializes TableManager class that acts as a repository that is used to perform operations on a DynamoDB table.

Arguments

tableEntity - Table class that inherits from Entity class. It has to define all primary and secondary indexes defined on the DynamoDB table. To learn more check out Modeling page.

tableMetadata - Metadata that describes table name, primary key, secondary index keys and createdAt/updatedAt timestamps. Dynamode uses metadata in all underlying methods so be cautious when setting it up.

Name	Description	Type	Default
tableName	Name of the table in DynamoDB	string	N/A
partitionKey	Name of the partition key	string	N/A
sortKey	Name of the sort key	string	N/A
indexes	Object that defines secondary indexes	{ [indexName: string], {partitionKey?: string; sortKey?:string } }	N/A
createdAt	Name of the createdAt timestamp	string	undefined
updatedAt	Name of the updatedAt timestamp	string	undefined

Examples

AllPossibleProperties model is defined here. To initialize its table manager, use TableManager constructor.

import TableManager from 'dynamode/table';

const AllPossiblePropertiesTableManager = new TableManager(AllPossibleProperties, {
  tableName: TABLE_NAME,
  partitionKey: 'partitionKey',
  sortKey: 'sortKey',
  indexes: {
    GSI_1_NAME: {
      partitionKey: 'GSI_1_PK',
      sortKey: 'GSI_1_SK',
    },
    LSI_1_NAME: {
      sortKey: 'LSI_1_SK',
    },
  },
  createdAt: 'createdAt',
  updatedAt: 'updatedAt',
});

TableManager.entityManager(entity?)

This method initializes EntityManager class that acts as a repository that is used to perform operations on a given model. To learn more check out Entity Manager page.

Arguments

You can add optional entity parameter which is a model that inherits from tableEntity class.

Name	Description	Type	Default
entity	Entity	Entity class that inherits from tableEntity	tableEntity (argument passed in TableManager constructor)

Examples

BaseTable is an example class that extends Entity.

import TableManager from 'dynamode/table';

const BaseTableManager = new TableManager(...);

// BaseTable entity manager
const BaseTableEntityManager = BaseTableManager.entityManager();

// EntityOne entity manager
const EntityOneManager = BaseTableManager.entityManager(EntityOne);

// EntityTwo entity manager
const EntityTwoManager = BaseTableManager.entityManager(EntityTwo);

// EntityThree entity manager
const EntityThreeManager = BaseTableManager.entityManager(EntityThree);

TableManager.createTable(options?)

Description

This method is used to create a new DynamoDB table. It uses the CreateTable DynamoDB operation.

Arguments

You can add optional options parameter that is an object. The table below represents options that you can pass in:

Name	Description	Type	Default
return	What the method should return. For 'default', method returns TableData. For 'input', method returns CreateTableCommandInput and no request is made to DynamoDB. For 'output', method returns the output from the CreateTable DynamoDB operation.	'default' | 'input' | 'output'	'default'
extraInput	Extra input that is sent to CreateTable DynamoDB operation. Use only if you know what you are doing, as it may override other standard properties.	CreateTableCommandInput	undefined
throughput	Provisioned throughput settings for the table. Defines the number of read and write capacity units.	{ read: number; write: number }	undefined
tags	Metadata to assign to the table.	Record<string, string>	undefined
deletionProtection	Protection from deletion. If this is enabled, the table cannot be deleted.	boolean	false

Examples

return: 'default'

const table = await TableManager.createTable({
  throughput: { read: 5, write: 5 }
});
const table = await TableManager.createTable({
  throughput: { read: 5, write: 5 },
  return: 'default'
});

Output:

TableData {
  tableName: 'users',
  tableStatus: 'ACTIVE',
  creationDateTime: '2021-08-23T10:00:00Z',
  provisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 },
  tableSizeBytes: 0,
  itemCount: 0,
  tableArn: 'arn:aws:dynamodb:us-west-2:1234567890:table/users',
  tableId: 'abcde12345',
  billingModeSummary: { BillingMode: 'PROVISIONED' }
}

return: 'input'

const input = TableManager.createTable({
  throughput: { read: 5, write: 5 },
  return: 'input'
});

Output:

{
  TableName: 'users',
  KeySchema: [...],
  AttributeDefinitions: [...],
  ProvisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 },
  DeletionProtectionEnabled: false,
  BillingMode: 'PROVISIONED'
}

return: 'output'

const output = await TableManager.createTable({
  throughput: { read: 5, write: 5 },
  return: 'output'
});

Output:

{
  '$metadata': {
    ...
  },
  TableDescription: {
    ...
  }
}

TableManager.deleteTable(tableName, options?)

Description

This method deletes a DynamoDB table. It uses the DeleteTable DynamoDB operation.

Arguments

tableName: string - The name of the table to delete.

You can add optional options parameter that is an object. The table below represents options that you can pass in:

Name	Description	Type	Default
return	What the method should return. For 'default', method returns TableData. For 'input', method returns DeleteTableCommandInput and no request is made to DynamoDB (method no longer returns a promise). For 'output', method returns the output from the DeleteTable DynamoDB operation.	'default' | 'input' | 'output'	'default'
extraInput	Extra input that is sent to CreateTable DynamoDB operation. Use only if you know what you are doing, as it may override other standard properties.	DeleteTableCommandInput	undefined

Examples

return: 'default'

const deletedTable = await TableManager.deleteTable('users');
const deletedTable = await TableManager.deleteTable('users', { return: "default" });

Output:

TableData {
  tableName: 'users',
  tableStatus: 'DELETING',
  ...
}

return: 'input'

const input = TableManager.deleteTable('users', { return: 'input' });

Output:

{
  TableName: 'users'
}

return: 'output'

const output = await TableManager.deleteTable('users', { return: 'output' });

Output:

{
  '$metadata': {
    ...
  },
  TableDescription: {
    ...
  }
}

TableManager.createTableIndex(indexName, options?)

Description

This method creates a new secondary index in a DynamoDB table. It uses the UpdateTable DynamoDB operation.

Arguments

indexName: string - The name of the global secondary index to create.

You can add optional options parameter that is an object. The table below represents options that you can pass in:

Name	Description	Type	Default
return	What the method should return. For 'default', it returns TableData. For 'input', it returns UpdateTableCommandInput and no request is made to DynamoDB (method no longer returns a promise). For 'output', it returns the output from the UpdateTable DynamoDB operation.	'default' | 'input' | 'output'	'default'
extraInput	Extra input that is sent to UpdateTable DynamoDB operation. Use only in case that you know what you are doing as it may override other properties passed to DynamoDB operation.	UpdateTableCommandInput	undefined
throughput	Provisioned throughput settings for the table index. Defines the number of read and write capacity units.	{ read: number; write: number }	undefined

Examples

return: 'default'

const table = await TableManager.createTableIndex('MyIndex', {
  throughput: { read: 5, write: 5 }
});
const table = await TableManager.createTableIndex('MyIndex', {
  throughput: { read: 5, write: 5 }
  return: 'default'
});

Output:

TableData {
  tableName: 'users',
  tableStatus: 'UPDATING',
  ...
}

return: 'input'

const input = TableManager.createTableIndex('MyIndex', {
  throughput: { read: 5, write: 5 },
  return: 'input'
});

Output:

{
  TableName: 'users',
  AttributeDefinitions: [...],
  GlobalSecondaryIndexUpdates: [...],
  ...
}

return: 'output'

const output = await TableManager.createTableIndex('MyIndex', {
  throughput: { read: 5, write: 5 },
  return: 'output'
});

Output:

{
  '$metadata': {
    ...
  },
  TableDescription: {
    ...
  }
}

TableManager.deleteTableIndex(indexName, options?)

Description

This method deletes an existing global secondary index in a DynamoDB table. It uses the UpdateTable DynamoDB operation.

Arguments

indexName: string - The name of the table global secondary index to delete.

You can add optional options parameter that is an object. The table below represents options that you can pass in:

Name	Description	Type	Default
return	What the method should return. For 'default', it returns TableData. For 'input', it returns UpdateTableCommandInput and no request is made to DynamoDB (method no longer returns a promise). For 'output', it returns the output from the UpdateTable DynamoDB operation.	'default' | 'input' | 'output'	'default'
extraInput	Extra input that is sent to UpdateTable DynamoDB operation. Use only in case that you know what you are doing as it may override other properties passed to DynamoDB operation.	UpdateTableCommandInput	undefined

Examples

return: 'default'

const table = await TableManager.deleteTableIndex('MyIndex');
const table = await TableManager.deleteTableIndex('MyIndex', { return: 'default' });

Output:

TableData {
  tableName: 'users',
  tableStatus: 'UPDATING',
  ...
}

return: 'input'

const input = TableManager.deleteTableIndex('MyIndex', { return: 'input' });

Output:

{
  TableName: 'users',
  GlobalSecondaryIndexUpdates: [...],
  ...
}

return: 'output'

const output = await TableManager.deleteTableIndex('MyIndex', { return: 'output' });

Output:

{
  '$metadata': {
    ...
  },
  TableDescription: {
    ...
  }
}

TableManager.validateTable(options?)

Description

This method validates the structure of a DynamoDB table against a known table structure. It uses the DescribeTable DynamoDB operation to retrieve the current table's structure and validates it with Dynamode table metadata.

Arguments

You can add an optional options parameter that is an object. The table below represents options that you can pass in:

Name	Description	Type	Default
return	What the method should return. For 'default', it returns TableData. For 'input', it returns DescribeTableCommandInput and no request is made to DynamoDB (method no longer returns a promise). For 'output', it returns the output from the DescribeTable DynamoDB operation.	'default' | 'input' | 'output'	'default'
extraInput	Extra input that is sent to DescribeTable DynamoDB operation. Use only in case that you know what you are doing as it may override other properties passed to DynamoDB operation.	DescribeTableCommandInput	undefined

Examples

return: 'default'

const tableData = await TableManager.validateTable();
const tableData = await TableManager.validateTable({ return: 'default' });

Output:

TableData {
  tableName: 'users',
  tableStatus: 'ACTIVE',
  creationDateTime: '2021-08-23T10:00:00Z',
  provisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 },
  tableSizeBytes: 0,
  itemCount: 0,
  tableArn: 'arn:aws:dynamodb:us-west-2:1234567890:table/users',
  tableId: 'abcde12345',
  billingModeSummary: { BillingMode: 'PROVISIONED' }
}

return: 'input'

const input = TableManager.validateTable({ return: 'input' });

Output:

{
  TableName: 'users',
  ...
}

return: 'output'

const output = await TableManager.validateTable({ return: 'output' });

Output:

{
  '$metadata': {
    ...
  },
  Table: {
    ...
  }
}