@kravc/dos-dynamodb 1.0.0-alpha.0

package/src/Document/__tests__/__helpers.ts

@@ -0,0 +1,115 @@
+import { Schema, Validator } from '@kravc/schema';
+import { Asset, Activity, Organization } from '../../../example';
+import { Context, type Identity, type Request, type LambdaRequest, type ExtraContext } from '@kravc/dos';
+
+const operationId = 'CreateAsset';
+
+const DEFAULT_LAMBDA_REQUEST = {
+  headers: {},
+  operationId,
+} as LambdaRequest;
+
+type Props = {
+  request?: Request;
+  schemas?: Schema[];
+  identity?: Identity;
+  extraContext?: ExtraContext;
+};
+
+/** Deletes and recreates the table. */
+export const resetTable = async () => await Asset.table.reset();
+
+/** Creates an instance of an operation context. */
+export const createContext = (props: Props = {}): Context => {
+  const {
+    request = DEFAULT_LAMBDA_REQUEST,
+    schemas = [ Asset.schema, Activity.schema, Organization.schema ],
+    identity = {
+      sub: 'USR_1',
+      organizationId: 'ORG_1',
+      email: 'john.doe@example.com',
+      lastName: 'Doe',
+      firstName: 'John',
+    },
+    extraContext = {},
+  } = props;
+
+  const validator = new Validator(schemas);
+
+  const spec = {
+    basePath: '/api',
+    paths: {
+      [`/${operationId}`]: {
+        post: {
+          operationId,
+        },
+      }
+    }
+  };
+
+  const context = new Context({ spec, validator }, request, extraContext);
+  context.identity = identity;
+
+  return context;
+};
+
+/** Creates an asset. */
+export const createAsset = async (extraAttributes: Record<string, unknown> = {}) => {
+  const context = createContext();
+
+  const attributes = {
+    name: 'Text Document',
+    tags: [ 'Tag A', 'Tag B' ],
+    type: 'CONTENT',
+    status: 'ACTIVE',
+    content: 'Text document content.',
+    ...extraAttributes,
+  };
+
+  const asset = await Asset.create(context, attributes);
+
+  return asset;
+};
+
+/** Creates an activity. */
+export const createActivity = async (extraAttributes: Record<string, unknown> = {}) => {
+  const context = createContext();
+
+  const attributes = {
+    operationId: 'CreateAsset',
+    summaryTemplate: 'Asset "Text Document" has been created by {user:createdBy}',
+    parametersJson: '{ "mutation": { "name": "Text Document" } }',
+    resultDocumentJson: '{ "name": "Text Document", "createdBy": "USR_1" }',
+    userId: 'USR_1',
+    traceId: 'TRACE_ID',
+    userAgent: 'USER_AGENT',
+    ipAddress: '127.0.0.1',
+    identity: {
+      sub: 'USR_1',
+      email: 'john.doe@example.com',
+      firstName: 'John',
+      lastName: 'Doe',
+      permissions: [ 'assets-write' ],
+    },
+    ...extraAttributes,
+  };
+
+  const activity = await Activity.create(context, attributes);
+
+  return activity;
+};
+
+/** Creates an organization. */
+export const createOrganization = async (extraAttributes: Record<string, unknown> = {}) => {
+  const context = createContext();
+
+  const attributes = {
+    name: 'Organization 1',
+    status: 'ACTIVE',
+    ...extraAttributes,
+  };
+
+  const organization = await Organization.create(context, attributes);
+
+  return organization;
+};

package/src/Document/helpers/__tests__/composeIndexKeys.test.ts

@@ -0,0 +1,40 @@
+import getTableOptions from '../../../Table/helpers/getTableOptions';
+import composeIndexKeys from '../composeIndexKeys';
+
+describe('composeIndexKeys(props)', () => {
+  it('returns empty object if no composers are defined for the document', () => {
+    const tableOptions = getTableOptions('partition', 'id');
+
+    const props = {
+      idPrefix: 'FIL',
+      attributes: {},
+      documentName: 'File',
+      tableOptions
+    };
+
+    const composedKeys = composeIndexKeys(props);
+
+    expect(composedKeys).toEqual({});
+  });
+
+  it('throws an exception if the index is not defined in the table config', () => {
+    const tableOptions = getTableOptions('partition', 'id');
+
+    tableOptions.indexKeys = {
+      lsi4: {
+        documentName: 'Activity',
+        sk: '#updatedAt',
+      }
+    };
+
+    const props = {
+      idPrefix: 'ACT',
+      attributes: {},
+      documentName: 'Activity',
+      tableOptions
+    };
+
+    expect(() => composeIndexKeys(props))
+      .toThrow('Index "lsi4" is not defined');
+  });
+});

package/src/Document/helpers/composeIndexKeys.ts

@@ -0,0 +1,137 @@
+import { get } from 'lodash';
+import { got } from '@kravc/dos';
+import type { TableOptions, LocalIndexKeyComposer, GlobalIndexKeyComposer } from '../../Table';
+
+type Attributes = Record<string, unknown>;
+
+const PLACEHOLDER_REGEX = /#(\w+)/g;
+
+/** Replaces each #name in the template with the value from attributes. */
+const composeValue = (
+  attributes: Attributes,
+  template: string
+): string | undefined => {
+  const names = [...template.matchAll(PLACEHOLDER_REGEX)].map(([ , name ]) => name);
+
+  for (const name of names) {
+    const value = get(attributes, name);
+
+    if (!value) {
+      return;
+    }
+  }
+
+  const composedValue = template.replace(PLACEHOLDER_REGEX, (_, name) =>
+    `#${attributes[name]}`
+  );
+
+  return composedValue;
+};
+
+/** Returns sort key value using ID prefix and template. */
+const composeSortKeyValue = (
+  attributes: Attributes,
+  template: string
+): string | undefined => {
+  return composeValue(attributes, template);
+};
+
+/** Returns partition key value using template. */
+const composePartitionKeyValue = (
+  idPrefix: string,
+  attributes: Attributes,
+  template: string
+): string | undefined => {
+  const composedValue = composeValue(attributes, template);
+
+  if (!composedValue) {
+    return;
+  }
+
+  return `${idPrefix}#${composedValue}`.replace('##', '#');
+};
+
+/** Returns index keys composed from item attributes. */
+const composeIndexKeys = ({
+  idPrefix,
+  attributes,
+  documentName,
+  tableOptions,
+}: {
+  idPrefix: string,
+  attributes: Attributes
+  documentName: string,
+  tableOptions: TableOptions,
+}): Attributes => {
+  const {
+    indexKeys,
+    isLocalSecondaryIndex,
+    getLocalIndexSortKeyName,
+    getGlobalIndexSortKeyName,
+    getGlobalIndexPartitionKeyName,
+  } = tableOptions;
+
+  const indexNames = Object.keys(indexKeys);
+
+  const localKeyComposers = indexNames
+    .filter(indexName => isLocalSecondaryIndex(indexName))
+    .filter(indexName => got(indexKeys[indexName] as LocalIndexKeyComposer, 'documentName') === documentName)
+    .map(indexName => ({
+      localIndexComposer: indexKeys[indexName] as LocalIndexKeyComposer,
+      indexName,
+    }));
+
+  const globalKeyComposers = indexNames
+    .filter(indexName => !isLocalSecondaryIndex(indexName))
+    .filter(indexName => !!get((indexKeys[indexName] as Record<string, GlobalIndexKeyComposer>), documentName))
+    .map(indexName => ({
+      globalIndexComposer: got(indexKeys[indexName], documentName) as GlobalIndexKeyComposer,
+      indexName,
+    }));
+
+  const composedKeys = {} as Attributes;
+  const indexKeysJson = JSON.stringify(indexKeys, null, 2);
+
+  for (const { indexName, localIndexComposer } of localKeyComposers) {
+    const sortKey = getLocalIndexSortKeyName(indexName);
+
+    const errorTemplate = `Sort key composer should be defined by "${indexName}.$PATH", index keys: ${indexKeysJson}`;
+    const skTemplate = got(localIndexComposer, 'sk', errorTemplate);
+    const skValue = composeSortKeyValue(attributes, skTemplate);
+
+    if (!skValue) {
+      continue;
+    }
+
+    composedKeys[sortKey] = skValue;
+  }
+
+  for (const { indexName, globalIndexComposer } of globalKeyComposers) {
+    const sortKey = getGlobalIndexSortKeyName(indexName);
+    const partitionKey = getGlobalIndexPartitionKeyName(indexName);
+
+    const skErrorTemplate = `Partition key composer should be defined by "${indexName}.${documentName}.$PATH", index keys: ${indexKeysJson}`;
+    const pkTemplate = got(globalIndexComposer, 'pk', skErrorTemplate) as string;
+    const pkValue = composePartitionKeyValue(idPrefix, attributes, pkTemplate);
+
+    if (!pkValue) {
+      continue;
+    }
+
+    composedKeys[partitionKey] = pkValue;
+
+    const pkErrorTemplate = `Sort key composer should be defined by "${indexName}.${documentName}.$PATH", index keys: ${indexKeysJson}`;
+    const skTemplate = got(globalIndexComposer, 'sk', pkErrorTemplate) as string;
+    const skValue = composeSortKeyValue(attributes, skTemplate);
+
+    if (!skValue) {
+      continue;
+    }
+
+    composedKeys[sortKey] = skValue;
+  }
+
+  return composedKeys;
+};
+
+export default composeIndexKeys;

package/src/Document/helpers/index.ts

@@ -0,0 +1,5 @@
+import composeIndexKeys from './composeIndexKeys';
+
+export {
+  composeIndexKeys,
+};

package/src/Table/Table.ts

@@ -0,0 +1,354 @@
+import type { MutationMap, QueryMap } from '@kravc/dos';
+import { DynamoDBClient, DeleteTableCommand, CreateTableCommand } from '@aws-sdk/client-dynamodb';
+
+import {
+  type PutCommandInput,
+  type GetCommandInput,
+  type QueryCommandInput,
+  type QueryCommandOutput,
+  type DeleteCommandInput,
+  DynamoDBDocument,
+  UpdateCommandInput,
+} from '@aws-sdk/lib-dynamodb';
+
+import {
+  type TableOptions,
+  getTableOptions,
+  buildTableSchema,
+  getRawClientConfig,
+  buildUpdateExpression,
+  buildQueryCommandInput,
+  buildConditionExpression,
+  filterConditionExpression,
+} from './helpers';
+
+type Options = {
+  partitionKey: string;
+  sortKey: string;
+}
+
+export type ItemAttributes = Record<string, unknown>;
+
+/** DynamoDB table class. */
+class Table {
+  private _client: DynamoDBDocument;
+  private _rawClient: DynamoDBClient;
+  private _tableOptions: TableOptions;
+
+  /** Creates an instance of a table. */
+  constructor(options: Options) {
+    const { sortKey, partitionKey } = options;
+
+    const tableOptions = getTableOptions(partitionKey, sortKey);
+
+    const { region, profile } = tableOptions;
+    const config = getRawClientConfig(region, profile);
+
+    this._rawClient = new DynamoDBClient(config);
+    this._client = DynamoDBDocument.from(this._rawClient);
+
+    this._tableOptions = tableOptions;
+  }
+
+  /** Returns table options. */
+  get options() {
+    return this._tableOptions;
+  }
+
+  /** Creates a DynamoDB table. */
+  async create(): Promise<void> {
+    const tableSchema = buildTableSchema(this._tableOptions);
+    const command = new CreateTableCommand(tableSchema);
+
+    await this._rawClient.send(command);
+  }
+
+  /** Deletes a DynamoDB table. */
+  async delete(): Promise<void> {
+    const { name: TableName } = this._tableOptions;
+    const deleteTableCommand = new DeleteTableCommand({ TableName });
+
+    await this._client.send(deleteTableCommand);
+  }
+
+  /** Resets a DynamoDB table. */
+  async reset(): Promise<void> {
+    try {
+      await this.delete();
+
+    } catch (dynamoError: unknown) {
+      const { name: errorName } = dynamoError as { name: string };
+
+      /* istanbul ignore next */
+      if (errorName !== 'ResourceNotFoundException') {
+        throw dynamoError;
+      }
+    }
+
+    await this.create();
+  }
+
+  /** Returns key and conditionQuery from query. */
+  _parseItemQuery(query: QueryMap) {
+    const { primaryKey } = this._tableOptions;
+    const { sortKey, partitionKey } = primaryKey;
+
+    const {
+      [sortKey]: sortKeyValue,
+      [partitionKey]: partitionKeyValue,
+      ...conditionQuery
+    } = query;
+
+    const Key = {
+      [sortKey]: sortKeyValue,
+      [partitionKey]: partitionKeyValue,
+    };
+
+    return { Key, conditionQuery };
+  }
+
+  /** Creates a table item; returns false if item already exists. */
+  async createItem(attributes: ItemAttributes): Promise<boolean> {
+    const { name: TableName, primaryKey } = this._tableOptions;
+
+    const { sortKey } = primaryKey;
+
+    const ConditionExpression = `#${sortKey} <> :${sortKey}`;
+
+    const ExpressionAttributeNames = {
+      [`#${sortKey}`]: sortKey,
+    };
+
+    const ExpressionAttributeValues = {
+      [`:${sortKey}`]: attributes[sortKey],
+    };
+
+    const putCommandInput = {
+      TableName,
+      ConditionExpression,
+      ExpressionAttributeNames,
+      ExpressionAttributeValues,
+      Item: attributes,
+    } as PutCommandInput;
+
+    try {
+      await this._client.put(putCommandInput);
+
+    } catch (dynamoError: unknown) {
+      const { name: errorName } = dynamoError as { name: string };
+
+      if (errorName === 'ConditionalCheckFailedException') {
+        return false;
+      }
+
+      /* istanbul ignore next */
+      if (errorName !== 'ResourceNotFoundException') {
+        throw dynamoError;
+      }
+
+      throw new Error(`Table "${TableName}" does not exist`);
+    }
+
+    return true;
+  }
+
+  /** Returns a table item, or undefined if not found. */
+  async getItem(query: QueryMap): Promise<ItemAttributes | undefined> {
+    const { name: TableName } = this._tableOptions;
+    const { Key, conditionQuery } = this._parseItemQuery(query);
+
+    const getCommandInput = {
+      ConsistentRead: true,
+      TableName,
+      Key,
+    } as GetCommandInput;
+
+    let result;
+
+    try {
+      result = await this._client.get(getCommandInput);
+
+    } catch (dynamoError: unknown) {
+      const { name: errorName } = dynamoError as { name: string };
+
+      /* istanbul ignore next */
+      if (errorName !== 'ResourceNotFoundException') {
+        throw dynamoError;
+      }
+
+      throw new Error(`Table "${TableName}" does not exist`);
+    }
+
+    const { Item: itemAttributes } = result;
+
+    return filterConditionExpression(itemAttributes, conditionQuery);
+  }
+
+  /** Updates a table item with attributes. */
+  async updateItem(query: QueryMap, mutation: MutationMap): Promise<ItemAttributes | undefined> {
+    const { name: TableName, primaryKey } = this._tableOptions;
+    const { Key } = this._parseItemQuery(query);
+
+    const { partitionKey, sortKey } = primaryKey;
+
+    delete mutation[sortKey];
+    delete mutation[partitionKey];
+
+    const {
+      UpdateExpression,
+      ConditionExpression,
+      ExpressionAttributeNames,
+      ExpressionAttributeValues,
+    } = buildUpdateExpression(query, mutation);
+
+    const updateCommandInput = {
+      ReturnValues: 'ALL_NEW',
+      Key,
+      TableName,
+      UpdateExpression,
+      ConditionExpression,
+      ExpressionAttributeNames,
+      ExpressionAttributeValues,
+    } as UpdateCommandInput;
+
+    let result;
+
+    try {
+      result = await this._client.update(updateCommandInput);
+
+    } catch (dynamoError: unknown) {
+      const { name: errorName } = dynamoError as { name: string };
+
+      if (errorName === 'ConditionalCheckFailedException') {
+        return;
+      }
+
+      /* istanbul ignore next */
+      if (errorName !== 'ResourceNotFoundException') {
+        throw dynamoError;
+      }
+
+      throw new Error(`Table "${TableName}" does not exist`);
+    }
+
+    const { Attributes: attributes } = result;
+
+    return attributes;
+  }
+
+  /** Deletes a table item; returns false if item not found. */
+  async deleteItem(query: QueryMap): Promise<boolean> {
+    const { name: TableName } = this._tableOptions;
+    const { Key } = this._parseItemQuery(query);
+
+    const {
+      ConditionExpression,
+      ExpressionAttributeNames,
+      ExpressionAttributeValues,
+    } = buildConditionExpression(query);
+
+    const deleteCommandInput = {
+      TableName,
+      Key,
+      ConditionExpression,
+      ExpressionAttributeNames,
+      ExpressionAttributeValues
+    } as DeleteCommandInput;
+
+    try {
+      await this._client.delete(deleteCommandInput);
+
+    } catch (dynamoError: unknown) {
+      const { name: errorName } = dynamoError as { name: string };
+
+      if (errorName === 'ConditionalCheckFailedException') {
+        return false;
+      }
+
+      /* istanbul ignore next */
+      if (errorName !== 'ResourceNotFoundException') {
+        throw dynamoError;
+      }
+
+      throw new Error(`Table "${TableName}" does not exist`);
+    }
+
+    return true;
+  }
+
+  /** Returns item from the table using a query. */
+  async _queryItems(input: QueryCommandInput): Promise<QueryCommandOutput> {
+    let result: QueryCommandOutput;
+
+    try {
+      result = await this._client.query(input);
+
+    } catch (dynamoError: unknown) {
+      const { name: errorName } = dynamoError as { name: string };
+
+      /* istanbul ignore next */
+      if (errorName !== 'ResourceNotFoundException') {
+        throw dynamoError;
+      }
+
+      const { TableName } = input;
+
+      throw new Error(`Table "${TableName}" does not exist`);
+    }
+
+    return result;
+  }
+
+  /** Lists table items. */
+  async listItems(
+    query: QueryMap,
+    options: {
+      sort: string,
+      limit: number,
+      indexName?: string,
+      exclusiveStartKey?: string
+    }
+  ): Promise<{
+    count: number;
+    items: ItemAttributes[];
+    lastEvaluatedKey?: string;
+  }> {
+    const queryCommandInput = buildQueryCommandInput(this._tableOptions, query, options);
+
+    const { limit } = options;
+
+    let count = 0;
+    let items = [] as Record<string, unknown>[];
+    let lastEvaluatedKey;
+    let isNextChunkRequired = true;
+
+    do {
+      const {
+        Items: chunk,
+        LastEvaluatedKey
+      } = await this._queryItems(queryCommandInput);
+
+      const hasMoreItems = !!LastEvaluatedKey;
+
+      items = [ ...items, ...(chunk as ItemAttributes[]) ];
+      count = items.length;
+      lastEvaluatedKey = LastEvaluatedKey;
+      isNextChunkRequired = hasMoreItems && count < limit;
+
+      queryCommandInput.ExclusiveStartKey = LastEvaluatedKey;
+
+    } while (isNextChunkRequired);
+
+    if (lastEvaluatedKey) {
+      lastEvaluatedKey = encodeURIComponent(JSON.stringify(lastEvaluatedKey));
+    }
+
+    return {
+      count,
+      items,
+      lastEvaluatedKey
+    };
+  }
+}
+
+export default Table;

package/src/Table/__tests__/Table.test.ts

@@ -0,0 +1,64 @@
+import Table from '../Table';
+
+describe('Table', () => {
+  const table = new Table({
+    sortKey: 'id',
+    partitionKey: 'partition',
+  });
+
+  beforeAll(async () => {
+    try {
+      await table.delete();
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    } catch (_error) {
+      ;
+    }
+  });
+
+  describe('Table.createItem(attributes)', () => {
+    it('throws an exception if the table does not exist', async () => {
+      const attributes = {};
+      await expect(table.createItem(attributes))
+        .rejects
+        .toThrow('Table "kravc-dos-dynamodb" does not exist');
+    });
+  });
+
+  describe('Table.getItem(query)', () => {
+    it('throws an exception if the table does not exist', async () => {
+      const query = { partition: 'ORG_1', id: 'AST_BAD_ID' };
+      await expect(table.getItem(query))
+        .rejects
+        .toThrow('Table "kravc-dos-dynamodb" does not exist');
+    });
+  });
+
+  describe('Table.updateItem(query, mutation)', () => {
+    it('throws an exception if the table does not exist', async () => {
+      const query = { partition: 'ORG_1', id: 'AST_BAD_ID' };
+      const mutation = { name: 'Text Document' };
+      await expect(table.updateItem(query, mutation))
+        .rejects
+        .toThrow('Table "kravc-dos-dynamodb" does not exist');
+    });
+  });
+
+  describe('Table.deleteItem(query)', () => {
+    it('throws an exception if the table does not exist', async () => {
+      const query = { partition: 'ORG_1', id: 'AST_BAD_ID' };
+      await expect(table.deleteItem(query))
+        .rejects
+        .toThrow('Table "kravc-dos-dynamodb" does not exist');
+    });
+  });
+
+  describe('Table.listItems(query, options)', () => {
+    it('throws an exception if the table does not exist', async () => {
+      const query = { partition: 'ORG_1' };
+      await expect(table.listItems(query, { limit: 100, sort: 'desc' }))
+        .rejects
+        .toThrow('Table "kravc-dos-dynamodb" does not exist');
+    });
+  });
+});