Proof-of-concept for #113 (ensureGlobalSecondaryIndexExists method) (#114)

aregier · jeskew · commit 7da6b782a0e0 · 2018-10-31T14:49:47.000-04:00
* Proof-of-concept for #113 (ensureGlobalSecondaryIndexExists method) * Defensive programming; waitFor('tableExists') already polls for ACTIVE table status, but returns before the new GSI finishes backfilling * Move indexName argument before options bag in GlobalSecondaryIndex decls * const correctness from PR feedback * Add unit tests for createGlobalSecondaryIndex / ensureGlobalSecondaryIndexExists * ignore vscode generated debugging launch configs, etc
diff --git a/.gitignore b/.gitignore
@@ -11,6 +11,7 @@ pids
 *.pid
 *.seed
 *.pid.lock
+.vscode
 lib-cov
 coverage
 build
diff --git a/packages/dynamodb-data-mapper/src/DataMapper.spec.ts b/packages/dynamodb-data-mapper/src/DataMapper.spec.ts
@@ -13,7 +13,7 @@ import {
     UpdateExpression,
 } from "@aws/dynamodb-expressions";
 import {ItemNotFoundException} from "./ItemNotFoundException";
-import {BatchGetOptions, ParallelScanState} from './index';
+import {BatchGetOptions, ParallelScanState, GlobalSecondaryIndexOptions} from './index';
 
 type BinaryValue = ArrayBuffer|ArrayBufferView;
 
@@ -664,6 +664,105 @@ describe('DataMapper', () => {
         }
     });
 
+    describe('#createGlobalSecondaryIndex', () => {
+        const waitPromiseFunc = jest.fn(() => Promise.resolve());
+        const updateTablePromiseFunc = jest.fn(() => Promise.resolve({}));
+        const mockDynamoDbClient = {
+            config: {},
+            updateTable: jest.fn(() => ({promise: updateTablePromiseFunc})),
+            waitFor: jest.fn(() => ({promise: waitPromiseFunc})),
+        };
+
+        beforeEach(() => {
+            updateTablePromiseFunc.mockClear();
+            mockDynamoDbClient.updateTable.mockClear();
+            waitPromiseFunc.mockClear();
+            mockDynamoDbClient.waitFor.mockClear();
+        });
+
+        const mapper = new DataMapper({
+            client: mockDynamoDbClient as any,
+        });    
+
+        class Item {
+            get [DynamoDbTable]() { return 'foo' }
+
+            get [DynamoDbSchema]() {
+                return {
+                    id: {
+                        type: 'String',
+                        keyType: 'HASH'
+                    },
+                    description: {
+                        type: 'String',
+                        indexKeyConfigurations: {
+                            DescriptionIndex: 'HASH'
+                        }
+                    }
+                };
+            }
+        }
+
+        const DescriptionIndex: GlobalSecondaryIndexOptions = {
+            projection: 'all',
+            readCapacityUnits: 1,
+            type: 'global',
+            writeCapacityUnits: 1
+        };
+
+        it('should make and send an UpdateTable request', async () => {
+            await mapper.createGlobalSecondaryIndex(Item, 'DescriptionIndex', {
+                indexOptions: {
+                    DescriptionIndex
+                },
+                readCapacityUnits: 5,
+                writeCapacityUnits: 5,
+            });
+
+            expect(mockDynamoDbClient.updateTable.mock.calls).toEqual([
+                [
+                    {
+                        TableName: 'foo',
+                        AttributeDefinitions: [
+                            {
+                                AttributeName: 'id',
+                                AttributeType: 'S'
+                            },
+                            {
+                                AttributeName: 'description',
+                                AttributeType: 'S'
+                            }
+                        ],
+                        GlobalSecondaryIndexUpdates: [
+                            {
+                                Create: {
+                                    IndexName: 'DescriptionIndex',
+                                    KeySchema: [
+                                        {
+                                            AttributeName: 'description',
+                                            KeyType: 'HASH'
+                                        }
+                                    ],
+                                    Projection: {
+                                        ProjectionType: 'ALL'
+                                    },
+                                    ProvisionedThroughput: {
+                                        ReadCapacityUnits: 1,
+                                        WriteCapacityUnits: 1
+                                    }
+                                }
+                            }
+                        ],
+                    },
+                ]
+            ]);
+
+            expect(mockDynamoDbClient.waitFor.mock.calls).toEqual([
+                [ 'tableExists', { TableName: 'foo' } ],
+            ]);
+        });
+    })
+
     describe('#createTable', () => {
         const waitPromiseFunc = jest.fn(() => Promise.resolve());
         const createTablePromiseFunc = jest.fn(() => Promise.resolve({}));
@@ -1487,6 +1586,135 @@ describe('DataMapper', () => {
         });
     });
 
+
+    describe('#ensureGlobalSecondaryIndexExists', () => {
+        const waitPromiseFunc = jest.fn(() => Promise.resolve());
+        const describeTablePromiseFunc = jest.fn(() => Promise.resolve({
+            Table: {
+                TableStatus: 'ACTIVE',
+                GlobalSecondaryIndexes: [ 
+                    {
+                        IndexName: 'DescriptionIndex'
+                    }
+                ],
+            }
+        }));
+        const mockDynamoDbClient = {
+            config: {},
+            describeTable: jest.fn(() => ({promise: describeTablePromiseFunc})),
+            waitFor: jest.fn(() => ({promise: waitPromiseFunc})),
+        };
+
+        const mapper = new DataMapper({
+            client: mockDynamoDbClient as any,
+        });
+        mapper.createGlobalSecondaryIndex = jest.fn(() => Promise.resolve());
+
+        beforeEach(() => {
+            (mapper.createGlobalSecondaryIndex as any).mockClear();
+            mockDynamoDbClient.describeTable.mockClear();
+            waitPromiseFunc.mockClear();
+            mockDynamoDbClient.waitFor.mockClear();
+        });
+
+        let tableName = 'foo';
+        let schema = {
+            id: {
+                type: 'String',
+                keyType: 'HASH'
+            },
+            description: {
+                type: 'String',
+                indexKeyConfigurations: {
+                    DescriptionIndex: 'HASH'
+                }
+            }
+        };
+
+        class Item {
+            get [DynamoDbTable]() { return tableName }
+
+            get [DynamoDbSchema]() { return schema; }
+        }
+
+        const DescriptionIndex: GlobalSecondaryIndexOptions = {
+            projection: 'all',
+            readCapacityUnits: 1,
+            type: 'global',
+            writeCapacityUnits: 1
+        };
+
+        it(
+            'should resolve immediately if the table exists, is active, and the GSI already exists',
+            async () => {
+                await mapper.ensureGlobalSecondaryIndexExists(Item, 'DescriptionIndex', {
+                    indexOptions: {
+                        DescriptionIndex
+                    },
+                    readCapacityUnits: 5,
+                    writeCapacityUnits: 5,
+                });
+
+                expect(mockDynamoDbClient.describeTable.mock.calls).toEqual([
+                    [{ TableName: tableName }]
+                ]);
+
+                expect(mockDynamoDbClient.waitFor.mock.calls.length).toBe(0);
+                expect((mapper.createGlobalSecondaryIndex as any).mock.calls.length).toBe(0);
+            }
+        );
+
+        it(
+            'should attempt to create the index if the table exists in the ACTIVE state but the specified index does not exist',
+            async () => {
+                describeTablePromiseFunc.mockImplementationOnce(() => Promise.resolve({
+                    Table: { TableStatus: 'ACTIVE' }
+                }))
+                await mapper.ensureGlobalSecondaryIndexExists(Item, 'DescriptionIndex', {
+                    indexOptions: {
+                        DescriptionIndex
+                    },
+                    readCapacityUnits: 5,
+                    writeCapacityUnits: 5,
+                });
+
+                expect(mockDynamoDbClient.describeTable.mock.calls).toEqual([
+                    [{ TableName: tableName }]
+                ]);
+
+                expect((mapper.createGlobalSecondaryIndex as any).mock.calls.length).toBe(1);
+                expect(mockDynamoDbClient.waitFor.mock.calls.length).toBe(0);
+            }
+        );
+
+        it(
+            'should rethrow if "describeTable" throws a "ResourceNotFoundException"',
+            async () => {
+                const expectedError = new Error('No such table!');
+                expectedError.name = 'ResourceNotFoundException';
+                describeTablePromiseFunc.mockImplementationOnce(async () => {
+                    throw expectedError;
+                });
+
+                await expect(mapper.ensureGlobalSecondaryIndexExists(Item, 'DescriptionIndex', {
+                    indexOptions: {
+                        DescriptionIndex
+                    },
+                    readCapacityUnits: 5,
+                    writeCapacityUnits: 5,
+                }))
+                .rejects
+                .toMatchObject(expectedError);
+
+                expect(mockDynamoDbClient.describeTable.mock.calls).toEqual([
+                    [{ TableName: tableName }]
+                ]);
+
+                expect(mockDynamoDbClient.waitFor.mock.calls.length).toBe(0);
+            }
+        );
+    });
+
     describe('#ensureTableExists', () => {
         const waitPromiseFunc = jest.fn(() => Promise.resolve());
         const describeTablePromiseFunc = jest.fn(() => Promise.resolve({
diff --git a/packages/dynamodb-data-mapper/src/DataMapper.ts b/packages/dynamodb-data-mapper/src/DataMapper.ts
@@ -76,6 +76,7 @@ import {
 import {
     AttributeDefinition,
     AttributeMap,
+    CreateGlobalSecondaryIndexAction,
     DeleteItemInput,
     GetItemInput,
     GlobalSecondaryIndexList,
@@ -306,6 +307,86 @@ export class DataMapper {
         }
     }
 
+    /**
+     * Perform a UpdateTable operation using the schema accessible via the
+     * {DynamoDbSchema} property, the table name accessible via the
+     * {DynamoDbTable} property on the prototype of the constructor supplied,
+     * and the specified global secondary index name.
+     *
+     * The promise returned by this method will not resolve until the table is
+     * active and ready for use.
+     *
+     * @param valueConstructor  The constructor used for values in the table.
+     * @param options           Options to configure the UpdateTable operation
+     */
+    async createGlobalSecondaryIndex(
+        valueConstructor: ZeroArgumentsConstructor<any>,
+        indexName: string,
+        {
+            indexOptions = {},
+        }: CreateTableOptions
+    ) {
+        const schema = getSchema(valueConstructor.prototype);
+        const { attributes, indexKeys } = keysFromSchema(schema);
+        const TableName = this.getTableName(valueConstructor.prototype);
+
+        const globalSecondaryIndexes = indexDefinitions(indexKeys, indexOptions, schema).GlobalSecondaryIndexes;
+        const indexSearch = globalSecondaryIndexes === undefined ? [] : globalSecondaryIndexes.filter(function(index) {
+            return index.IndexName === indexName;
+        });
+        const indexDefinition: CreateGlobalSecondaryIndexAction = indexSearch[0];
+
+        const {
+            TableDescription: {TableStatus} = {TableStatus: 'UPDATING'}
+        } = await this.client.updateTable({
+            GlobalSecondaryIndexUpdates: [{
+                Create: {
+                    ...indexDefinition
+                }
+            }],
+            TableName,
+            AttributeDefinitions: attributeDefinitionList(attributes),
+        }).promise();
+
+        if (TableStatus !== 'ACTIVE') {
+            await this.client.waitFor('tableExists', {TableName}).promise();
+        }
+    }
+
+    /**
+     * If the index does not already exist, perform a UpdateTable operation
+     * using the schema accessible via the {DynamoDbSchema} property, the
+     * table name accessible via the {DynamoDbTable} property on the prototype
+     * of the constructor supplied, and the index name.
+     *
+     * The promise returned by this method will not resolve until the table is
+     * active and ready for use. Note that the index will not be usable for queries
+     * until it has finished backfilling
+     *
+     * @param valueConstructor  The constructor used for values in the table.
+     * @param options           Options to configure the UpdateTable operation
+     */
+    async ensureGlobalSecondaryIndexExists(
+        valueConstructor: ZeroArgumentsConstructor<any>,
+        indexName: string,
+        options: CreateTableOptions
+    ) {
+        const TableName = this.getTableName(valueConstructor.prototype);
+        try {
+            const {
+                Table: {GlobalSecondaryIndexes } = {GlobalSecondaryIndexes: []}
+            } = await this.client.describeTable({TableName}).promise();
+            const indexSearch = GlobalSecondaryIndexes === undefined ? [] : GlobalSecondaryIndexes.filter(function(index) {
+                return index.IndexName === indexName;
+            });
+            if (indexSearch.length === 0) {
+                await this.createGlobalSecondaryIndex(valueConstructor, indexName, options);
+            }
+        } catch (err) {
+            throw err;
+        }
+    }
+
     /**
      * Perform a DeleteItem operation using the schema accessible via the
      * {DynamoDbSchema} property and the table name accessible via the
