@squiz/db-lib 1.65.0 → 1.66.0

package/src/dynamodb/AbstractDynamoDbRepository.ts

@@ -0,0 +1,445 @@
+import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';
+
+import {
+  DynamoDBDocument,
+  QueryCommandInput,
+  UpdateCommandOutput,
+  PutCommandInput,
+  DeleteCommandInput,
+} from '@aws-sdk/lib-dynamodb';
+
+import { Transaction, DynamoDbManager, MissingKeyValuesError, DuplicateItemError, InvalidDbSchemaError } from '..';
+
+interface Reader<T> {
+  queryItems(partialItem: Partial<T>, useSortKey?: boolean, index?: keyof TableIndexes): Promise<T[]>;
+  getItem(id: string | Partial<T>): Promise<T | undefined>;
+}
+
+interface Writer<T> {
+  createItem(item: Partial<T>): Promise<T>;
+  updateItem(partialItem: Partial<T>, newValue: Partial<T>): Promise<T | undefined>;
+  deleteItem(partialItem: Partial<T>): Promise<number>;
+}
+
+type Repository<T> = Reader<T> & Writer<T>;
+
+type Repositories = Record<string, Repository<any>>;
+
+export type TableKeys = {
+  pk: {
+    attributeName: string;
+    format: string;
+  };
+  sk: {
+    attributeName: string;
+    format: string;
+  };
+};
+
+export type TableIndexes = Record<string, TableKeys>;
+
+export type KeysFormat = Record<keyof TableKeys | keyof TableIndexes, string>;
+
+export type EntityDefinition = {
+  keys: TableKeys;
+  indexes: TableIndexes;
+};
+
+export abstract class AbstractDynamoDbRepository<SHAPE extends object, DATA_CLASS extends SHAPE>
+  implements Reader<SHAPE>, Writer<SHAPE>
+{
+  protected client: DynamoDBDocument;
+
+  protected keys: TableKeys;
+  protected indexes: TableIndexes;
+  protected keysFormat: KeysFormat;
+
+  constructor(
+    protected tableName: string,
+    protected dbManager: DynamoDbManager<Repositories>,
+    protected entityName: string,
+    protected entityDefinition: EntityDefinition,
+    protected classRef: { new (data?: Record<string, unknown>): DATA_CLASS },
+  ) {
+    this.client = dbManager.client;
+
+    this.keys = entityDefinition.keys;
+    this.indexes = entityDefinition.indexes;
+
+    this.keysFormat = {
+      [this.keys.pk.attributeName]: this.keys.pk.format,
+      [this.keys.sk.attributeName]: this.keys.sk.format,
+    };
+    Object.keys(this.indexes).forEach((key) => {
+      const index = this.indexes[key];
+      this.keysFormat[index.pk.attributeName] = index.pk.format;
+      this.keysFormat[index.sk.attributeName] = index.sk.format;
+    });
+  }
+
+  /**
+   * Get the single item matching the key fields value in the given
+   * partial item. Will throw MissingKeyValuesError if key field values
+   * are missing
+   *
+   * @param item
+   *
+   * @throws MissingKeyValuesError
+   */
+  public async getItem(item: Partial<SHAPE>): Promise<DATA_CLASS | undefined> {
+    const output = await this.client.get({
+      TableName: this.tableName,
+      Key: {
+        [this.keys.pk.attributeName]: this.getPk(item),
+        [this.keys.sk.attributeName]: this.getSk(item),
+      },
+    });
+    if (output.Item === undefined) {
+      return undefined;
+    }
+    return this.hydrateItem(output.Item);
+  }
+
+  /**
+   * Finds all the items matching the partition key or
+   * the gsi key (when gsi index name is specified)
+   *
+   * @param item
+   * @param useSortKey
+   * @param index
+   * @throws MissingKeyValuesError
+   */
+  public async queryItems(
+    item: Partial<SHAPE>,
+    useSortKey: boolean = false,
+    index?: keyof TableIndexes,
+  ): Promise<DATA_CLASS[]> {
+    let pkName = this.keys.pk.attributeName;
+    let skName = this.keys.sk.attributeName;
+    let indexName = null;
+
+    if (index) {
+      if (this.indexes[index] === undefined) {
+        throw new MissingKeyValuesError(`Table index '${index}' not defined on entity ${this.entityName}`);
+      }
+      indexName = index;
+      pkName = this.indexes[index].pk.attributeName;
+      skName = this.indexes[index].sk.attributeName;
+    }
+
+    const pk = this.getKey(item, pkName);
+    const keyConditionExpression = ['#pkName = :pkValue'];
+    const expressionAttributeNames: Record<string, string> = { '#pkName': pkName };
+    const expressionAttributeValues: Record<string, unknown> = { ':pkValue': pk };
+    if (useSortKey) {
+      const sk = this.getKey(item, skName);
+      keyConditionExpression.push('#skName = :skValue');
+      expressionAttributeNames['#skName'] = skName;
+      expressionAttributeValues[':skValue'] = sk;
+    }
+
+    const queryCommandInput: QueryCommandInput = {
+      TableName: this.tableName,
+      KeyConditionExpression: keyConditionExpression.join(' AND '),
+      ExpressionAttributeNames: expressionAttributeNames,
+      ExpressionAttributeValues: expressionAttributeValues,
+    };
+    if (indexName) {
+      queryCommandInput['IndexName'] = String(indexName);
+    }
+    const output = await this.client.query(queryCommandInput);
+
+    return !output.Items ? [] : output.Items.map((item) => this.hydrateItem(item));
+  }
+
+  /**
+   * Update the existing item matching the key fields value
+   * in the passed in partialItem
+   * @param partialItem
+   * @param newValue
+   * @param transaction
+   *
+   * @returns Promise<SHAPE | undefined>
+   * @throws MissingKeyValuesError
+   */
+  public async updateItem(
+    partialItem: Partial<SHAPE>,
+    newValue: Exclude<Partial<SHAPE>, Record<string, never>>,
+    transaction: Transaction = {},
+  ): Promise<DATA_CLASS | undefined> {
+    const oldValue = await this.getItem(partialItem);
+    if (oldValue === undefined) {
+      return undefined;
+    }
+
+    this.assertValueMatchesModel({ ...oldValue, ...newValue });
+
+    const updateExpression = [];
+    const expressionAttributeNames: Record<string, string> = {};
+    const expressionAttributeValues: Record<string, unknown> = {};
+    for (const modelProperty of Object.keys(newValue)) {
+      const propName = `#${modelProperty}`;
+      const propValue = `:${modelProperty}`;
+
+      updateExpression.push(`${propName} = ${propValue}`);
+      expressionAttributeNames[propName] = modelProperty;
+
+      expressionAttributeValues[propValue] = newValue[modelProperty as keyof SHAPE];
+    }
+
+    const updateCommandInput = {
+      TableName: this.tableName,
+      Key: {
+        [this.keys.pk.attributeName]: this.getPk(partialItem),
+        [this.keys.sk.attributeName]: this.getSk(partialItem),
+      },
+      UpdateExpression: 'SET ' + updateExpression.join(','),
+      ExpressionAttributeValues: expressionAttributeValues,
+      ExpressionAttributeNames: expressionAttributeNames,
+      ConditionExpression: `attribute_exists(${this.keys.pk.attributeName})`,
+    };
+
+    if (transaction.id?.length) {
+      // this command will be executed together with
+      // other db write commands in the "transaction" block
+      this.dbManager.addWriteTransactionItem(transaction.id, {
+        Update: updateCommandInput,
+      });
+      return new this.classRef({ ...oldValue, ...newValue });
+    }
+
+    let output: UpdateCommandOutput;
+    try {
+      output = await this.client.update({
+        ...updateCommandInput,
+        ReturnValues: 'ALL_NEW',
+      });
+    } catch (e) {
+      if (e instanceof ConditionalCheckFailedException) {
+        return undefined;
+      }
+      throw e;
+    }
+
+    let item: DATA_CLASS | undefined = undefined;
+    if (output.Attributes) {
+      item = this.hydrateItem(output.Attributes);
+    }
+    return item ? item : undefined;
+  }
+
+  /**
+   * Adds new item to the table
+   *
+   * @param value
+   * @param transaction
+   *
+   * @returns Promise<SHAPE>
+   * @throws DuplicateItemError
+   * @throws MissingKeyValuesError
+   */
+  public async createItem(value: DATA_CLASS, transaction: Transaction = {}): Promise<DATA_CLASS> {
+    this.assertValueMatchesModel(value);
+
+    const columns: any = {};
+    for (const modelProperty of Object.keys(value)) {
+      columns[modelProperty] = value[modelProperty as keyof DATA_CLASS];
+    }
+
+    const keyFields: Record<string, unknown> = {
+      [this.keys.pk.attributeName]: this.getPk(value),
+      [this.keys.sk.attributeName]: this.getSk(value),
+    };
+
+    Object.keys(this.indexes).forEach((key) => {
+      const index = this.indexes[key];
+      keyFields[index.pk.attributeName] = this.getKey(value, index.pk.attributeName);
+      keyFields[index.sk.attributeName] = this.getKey(value, index.sk.attributeName);
+    });
+
+    const putCommandInput: PutCommandInput = {
+      TableName: this.tableName,
+      Item: {
+        ...keyFields,
+        ...columns,
+      },
+      ConditionExpression: `attribute_not_exists(${this.keys.pk.attributeName})`,
+    };
+
+    if (transaction.id?.length) {
+      // this command will be executed together with
+      // other db write commands in the "transaction block"
+      this.dbManager.addWriteTransactionItem(transaction.id, {
+        Put: putCommandInput,
+      });
+      return value;
+    }
+
+    try {
+      await this.client.put(putCommandInput);
+    } catch (e) {
+      if (e instanceof ConditionalCheckFailedException) {
+        throw new DuplicateItemError(`Item already exists`);
+      }
+      throw e;
+    }
+    return value;
+  }
+
+  /**
+   * Deletes an item from the table
+   *
+   * @param partialItem
+   * @param transaction
+   * @returns number
+   * @throw MissingKeyValuesError
+   */
+  public async deleteItem(partialItem: Partial<SHAPE>, transaction: Transaction = {}): Promise<number> {
+    const deleteCommandInput: DeleteCommandInput = {
+      TableName: this.tableName,
+      Key: {
+        [this.keys.pk.attributeName]: this.getPk(partialItem),
+        [this.keys.sk.attributeName]: this.getSk(partialItem),
+      },
+      ConditionExpression: `attribute_exists(${this.keys.pk.attributeName})`,
+    };
+
+    if (transaction.id?.length) {
+      // this command will be executed together with
+      // other db write commands in the "transaction block"
+      this.dbManager.addWriteTransactionItem(transaction.id, {
+        Delete: deleteCommandInput,
+      });
+      return 1;
+    }
+
+    try {
+      await this.client.delete(deleteCommandInput);
+    } catch (e) {
+      if (e instanceof ConditionalCheckFailedException) {
+        return 0;
+      }
+      throw e;
+    }
+    return 1;
+  }
+
+  /**
+   * Return repo model object from the db value
+   * @param item
+   * @returns
+   */
+  protected hydrateItem(item: Record<string, unknown>): DATA_CLASS {
+    return new this.classRef(item);
+  }
+
+  /**
+   * Evaluate the partition key value from the partial item
+   * @param item
+   * @returns string
+   * @throw MissingKeyValuesError
+   */
+  protected getPk(item: Partial<SHAPE>): string {
+    return this.getKey(item, this.keys.pk.attributeName);
+  }
+
+  /**
+   * Evaluate the sort key value from the partial item
+   * @param item
+   * @returns string
+   *
+   * @throw MissingKeyValuesError
+   */
+  protected getSk(item: Partial<SHAPE>): string {
+    return this.getKey(item, this.keys.sk.attributeName);
+  }
+
+  /**
+   * Evaluate the key value from the
+   *
+   * Example 1:
+   * Input:
+   *  - item: {id: foo, name: 'some-name' }
+   *  - attributeName: pk
+   *  - this.keysFormat = { pk: 'item#{id}', 'sk': '#meta', ... }
+   * Output:
+   *  - 'item#foo'
+   *
+   * Example 2:
+   * Input:
+   *  - item: {id: foo, name: 'some-name', itemType: 'A' }
+   *  - attributeName: sk
+   *  - this.keysFormat = { pk: 'item#{id}', 'sk': 'type#{itemType}', ... }
+   * Output:
+   *  - 'type#A'
+   *
+   * Example 3:
+   * Input:
+   *  - item: {id: foo, name: 'some-name' }
+   *  - attributeName: sk
+   *  - this.keysFormat = { pk: 'item#{id}', 'sk': 'name-type#{itemType}{name}', ... }
+   * Output:
+   *  - Error: "Key field "itemType" must be specified in the input item"
+   *
+   * @param item
+   * @param attributeName
+   *
+   * @returns string
+   * @throw MissingKeyValuesError
+   */
+  protected getKey(item: Partial<SHAPE>, attributeName: keyof KeysFormat): string {
+    let keyFormat = this.keysFormat[attributeName];
+    if (keyFormat == undefined || !keyFormat.length) {
+      throw new MissingKeyValuesError(
+        `Key format not defined or empty for key attribute '${attributeName}' in entity ${this.entityName}`,
+      );
+    }
+
+    const matches = keyFormat.match(/{[a-zA-Z]+?}/g);
+    const replacements: { property: keyof SHAPE; placeholder: string }[] = !matches
+      ? []
+      : matches.map((match) => {
+          return {
+            property: match.slice(1, -1) as keyof SHAPE,
+            placeholder: match,
+          };
+        });
+
+    for (let i = 0; i < replacements.length; i++) {
+      const field = replacements[i].property;
+      if (item[field] === undefined) {
+        throw new MissingKeyValuesError(
+          `Key field "${String(field)}" must be specified in the input item in entity ${this.entityName}`,
+        );
+      }
+      keyFormat = keyFormat.replace(replacements[i].placeholder, String(item[field] ?? ''));
+    }
+
+    const moreMatches = keyFormat.match(/{[a-zA-Z]+?}/g);
+    if (moreMatches?.length) {
+      throw new MissingKeyValuesError(
+        `Cannot resolve key placeholder(s) for key attribute format '${this.keysFormat[attributeName]} in entity ${
+          this.entityName
+        }: '${moreMatches.join("','")}'`,
+      );
+    }
+    return keyFormat;
+  }
+
+  /**
+   * Validate the data matches with "DATA_MODEL"
+   * @param value
+   * @return void
+   */
+  private assertValueMatchesModel(value: unknown) {
+    // Trigger AssertionError if model instantiation fails
+    // see the DATA_CLASS model class
+    const obj = new this.classRef(value as Record<string, any>);
+    const inputProperties = Object.keys(value as object);
+    const modelProperties = Object.keys(obj);
+    const excessProperties = inputProperties.filter((prop) => !modelProperties.includes(prop));
+    if (excessProperties.length > 0) {
+      throw new InvalidDbSchemaError(`Excess properties in entity ${this.entityName}: ${excessProperties.join(', ')}`);
+    }
+  }
+}

package/src/dynamodb/DynamoDbManager.ts

@@ -0,0 +1,66 @@
+import { DynamoDBDocument, TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
+import { randomUUID } from 'crypto';
+import { TransactionError } from '../error/TransactionError';
+
+export type Transaction = {
+  id?: string;
+};
+
+type TransactionItems = TransactWriteCommandInput['TransactItems'];
+export type TransactionItem = NonNullable<TransactionItems>[number];
+
+export class DynamoDbManager<TRepositories> {
+  private transactionItems: Record<string, TransactionItem[]>;
+  public repositories: TRepositories;
+
+  constructor(
+    public client: DynamoDBDocument,
+    repositoryCreator: (dbManager: DynamoDbManager<TRepositories>) => TRepositories,
+  ) {
+    this.transactionItems = {};
+    this.repositories = repositoryCreator(this);
+  }
+
+  public async executeInTransaction<T>(func: (transaction: Transaction) => Promise<T>): Promise<T> {
+    const transactionId = randomUUID();
+
+    try {
+      this.startTransaction(transactionId);
+      const value = await func({ id: transactionId });
+      await this.executeTransaction(transactionId);
+      return value;
+    } finally {
+      this.closeTransaction(transactionId);
+    }
+  }
+
+  public addWriteTransactionItem(transactionId: string, item: TransactionItem) {
+    if (this.transactionItems[transactionId] === undefined) {
+      throw new TransactionError(`No items in transaction '${transactionId}' to add transaction item to`);
+    }
+
+    this.transactionItems[transactionId].push(item);
+  }
+
+  private async executeTransaction(transactionId: string) {
+    if (this.transactionItems[transactionId] === undefined) {
+      throw new TransactionError(`No items in transaction '${transactionId}' to execute`);
+    }
+
+    return await this.client.transactWrite({
+      ClientRequestToken: transactionId,
+      TransactItems: this.transactionItems[transactionId],
+    });
+  }
+
+  private startTransaction(transactionId: string) {
+    if (this.transactionItems[transactionId] !== undefined) {
+      throw new TransactionError(`Transaction '${transactionId}' already started`);
+    }
+    this.transactionItems[transactionId] = [];
+  }
+
+  private closeTransaction(transactionId: string) {
+    delete this.transactionItems[transactionId];
+  }
+}

package/src/error/DuplicateItemError.ts

@@ -0,0 +1,8 @@
+import { InternalServerError } from '@squiz/dx-common-lib';
+
+export class DuplicateItemError extends InternalServerError {
+  name = 'DuplicateItemError';
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/error/InvalidDbSchemaError.ts

@@ -0,0 +1,8 @@
+import { BadRequestError } from '@squiz/dx-common-lib';
+
+export class InvalidDbSchemaError extends BadRequestError {
+  name = 'InvalidDbSchemaError';
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/error/MissingKeyValuesError.ts

@@ -0,0 +1,8 @@
+import { InternalServerError } from '@squiz/dx-common-lib';
+
+export class MissingKeyValuesError extends InternalServerError {
+  name = 'MissingKeyValuesError';
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/error/TransactionError.ts

@@ -0,0 +1,8 @@
+import { InternalServerError } from '@squiz/dx-common-lib';
+
+export class TransactionError extends InternalServerError {
+  name = 'TransactionError';
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/index.ts

@@ -1,8 +1,14 @@
 export * from './AbstractRepository';
 export * from './ConnectionManager';
+export * from './dynamodb/DynamoDbManager';
+export * from './dynamodb/AbstractDynamoDbRepository';
 export * from './Migrator';
 export * from './Repositories';
 export * from './getConnectionInfo';
+export * from './error/DuplicateItemError';
+export * from './error/TransactionError';
+export * from './error/MissingKeyValuesError';
+export * from './error/InvalidDbSchemaError';
 
 // Postgres
 export * from './PostgresErrorCodes';