@kravc/dos-dynamodb 1.0.0-alpha.0

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

@@ -0,0 +1,14 @@
+import getTableOptions from '../getTableOptions';
+import buildQueryCommandInput from '../buildQueryCommandInput';
+
+describe('buildQueryCommandInput(tableOptions, query, options)', () => {
+  it('throws an exception if the index is not defined in the table config', () => {
+    const tableOptions = getTableOptions('partition', 'id');
+
+    const query = {};
+    const options = { sort: 'asc', limit: 10, indexName: 'customGSI' };
+
+    expect(() => buildQueryCommandInput(tableOptions, query, options))
+      .toThrow('Index "customGSI" is not defined');
+  });
+});

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

@@ -0,0 +1,19 @@
+import getTableOptions from '../getTableOptions';
+import buildTableSchema from '../buildTableSchema';
+
+describe('buildTableSchema(tableOptions)', () => {
+  it('supports global secondary indexes without a sort key', () => {
+    const tableOptions = getTableOptions('partition', 'id');
+
+    tableOptions.globalSecondaryIndexes = [
+      {
+        name: 'gsiTest',
+        partitionKey: 'gsiPartitionKey',
+      }
+    ];
+
+    const tableSchema = buildTableSchema(tableOptions);
+
+    expect(tableSchema.GlobalSecondaryIndexes).toHaveLength(1);
+  });
+});

package/src/Table/helpers/buildConditionExpression.ts

@@ -0,0 +1,151 @@
+import type { QueryMap } from '@kravc/dos';
+
+export enum ExpressionKey {
+  LT = 'lt',
+  LE = 'le',
+  GT = 'gt',
+  GE = 'ge',
+  NOT = 'not',
+  CONTAIN = 'contains',
+  EXCLUDE = 'not_contains',
+  // TODO: Add support for:
+  // - between: lt and gt
+  // - begins with
+}
+
+/** Builds condition expression from a query for a table query, update and delete methods. */
+const buildConditionExpression = (query: QueryMap) => {
+  // NOTE: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html
+  const ConditionExpressions = [] as string[];
+  const ExpressionAttributeNames = {} as Record<string, string>;
+  const ExpressionAttributeValues = {} as Record<string, unknown>;
+
+  for (let key in query) {
+    let path = '#Q_' + key.replace(/\./g, '.#Q_');
+
+    const valueKey = key.replace(/\.|:/g, '_');
+    const filterValue = query[key];
+
+    const isNot = key.endsWith(`:${ExpressionKey.NOT}`);
+    const isLessThan = key.endsWith(`:${ExpressionKey.LT}`);
+    const isLessThanOrEqual = key.endsWith(`:${ExpressionKey.LE}`);
+    const isGreaterThan = key.endsWith(`:${ExpressionKey.GT}`);
+    const isGreaterThanOrEqual = key.endsWith(`:${ExpressionKey.GE}`);
+    const isContains = key.endsWith(`:${ExpressionKey.CONTAIN}`);
+    const isNotContains = key.endsWith(`:${ExpressionKey.EXCLUDE}`);
+
+    const isFilterValueNull = filterValue === null;
+
+    if (isNot) {
+      key = key.replace(/:not/g, '');
+    }
+
+    if (isContains) {
+      key = key.replace(/:contains/g, '');
+    }
+
+    if (isNotContains) {
+      key = key.replace(/:not_contains/g, '');
+    }
+
+    if (isLessThan) {
+      key = key.replace(/:lt/g, '');
+    }
+
+    if (isLessThanOrEqual) {
+      key = key.replace(/:le/g, '');
+    }
+
+    if (isGreaterThan) {
+      key = key.replace(/:gt/g, '');
+    }
+
+    if (isGreaterThanOrEqual) {
+      key = key.replace(/:ge/g, '');
+    }
+
+    const pathKeys = key.split('.');
+
+    for (const pathKey of pathKeys) {
+      ExpressionAttributeNames[`#Q_${pathKey}`] = pathKey;
+    }
+
+    const isFilterValueArray = Array.isArray(filterValue);
+
+    if (isFilterValueArray) {
+      const filterValues = filterValue.entries();
+      const valueKeys = [];
+
+      for (const [ index, value ] of filterValues) {
+        ExpressionAttributeValues[`:Q_${valueKey}${index + 1}`] = value;
+        valueKeys.push(`:Q_${valueKey}${index + 1}`);
+      }
+
+      ConditionExpressions.push(`${path} in (${valueKeys})`);
+
+    } else {
+      ExpressionAttributeValues[`:Q_${valueKey}`] = filterValue;
+
+      if (isNot) {
+        path = path.replace(/:not/, '');
+        ConditionExpressions.push(`${path} <> :Q_${valueKey}`);
+
+        if (isFilterValueNull) {
+          ConditionExpressions.push(`attribute_exists(${path})`);
+        }
+
+      } else if (isContains) {
+        path = path.replace(/:contains/, '');
+        ConditionExpressions.push(`contains(${path}, :Q_${valueKey})`);
+
+      } else if (isNotContains) {
+        path = path.replace(/:not_contains/, '');
+        ConditionExpressions.push(`not contains(${path}, :Q_${valueKey})`);
+
+      } else if (isLessThan) {
+        path = path.replace(/:lt/, '');
+        ConditionExpressions.push(`${path} < :Q_${valueKey}`);
+
+      } else if (isLessThanOrEqual) {
+        path = path.replace(/:le/, '');
+        ConditionExpressions.push(`${path} <= :Q_${valueKey}`);
+
+      } else if (isGreaterThan) {
+        path = path.replace(/:gt/, '');
+        ConditionExpressions.push(`${path} > :Q_${valueKey}`);
+
+      } else if (isGreaterThanOrEqual) {
+        path = path.replace(/:ge/, '');
+        ConditionExpressions.push(`${path} >= :Q_${valueKey}`);
+
+      } else {
+        if (isFilterValueNull) {
+          ConditionExpressions.push(`(${path} = :Q_${valueKey} OR attribute_not_exists(${path}))`);
+
+        } else {
+          ConditionExpressions.push(`${path} = :Q_${valueKey}`);
+
+        }
+
+      }
+    }
+  }
+
+  const ConditionExpression = ConditionExpressions.join(' AND ');
+  const hasConditionExpression = ConditionExpression !== '';
+
+  if (!hasConditionExpression) {
+    return {
+      ExpressionAttributeNames,
+      ExpressionAttributeValues
+    };
+  }
+
+  return {
+    ConditionExpression,
+    ExpressionAttributeNames,
+    ExpressionAttributeValues,
+  };
+};
+
+export default buildConditionExpression;

package/src/Table/helpers/buildQueryCommandInput.ts

@@ -0,0 +1,113 @@
+import { TableOptions } from './getTableOptions';
+import { got, type QueryMap } from '@kravc/dos';
+import { type QueryCommandInput } from '@aws-sdk/lib-dynamodb';
+import buildQueryConditionExpression from './buildQueryConditionExpression';
+
+const QUERY_ERROR_TEMPLATE = 'Query parameter "$PATH" is required';
+
+const SORT_ASC = 'asc';
+
+/** Returns partitionKey and sortKey for a query. */
+const getKeys = (
+  tableOptions: TableOptions,
+  indexName?: string
+): {
+  isGlobalSecondaryIndex: boolean;
+  partitionKey: string;
+  sortKey: string
+} => {
+  const {
+    primaryKey,
+    localSecondaryIndexes,
+    globalSecondaryIndexes
+  } = tableOptions;
+
+  if (!indexName) {
+    return { ...primaryKey, isGlobalSecondaryIndex: false };
+  }
+
+  const lsi = localSecondaryIndexes.find(({ name }) => name === indexName);
+
+  if (lsi) {
+    const { sortKey } = lsi;
+
+    return { ...primaryKey, sortKey, isGlobalSecondaryIndex: false };
+  }
+
+  const gsi = globalSecondaryIndexes.find(({ name }) => name === indexName);
+
+  if (gsi) {
+    const { partitionKey, sortKey } = gsi;
+
+    return { partitionKey, sortKey, isGlobalSecondaryIndex: true };
+  }
+
+  const indexesJson = JSON.stringify({ localSecondaryIndexes, globalSecondaryIndexes }, null, 2);
+  throw new Error(`Index "${indexName}" is not defined, indexes: ${indexesJson}`);
+};
+
+/** Builds query command input. */
+const buildQueryCommandInput = (
+  tableOptions: TableOptions,
+  query: QueryMap,
+  options: {
+    sort: string,
+    limit: number,
+    indexName?: string,
+    exclusiveStartKey?: string
+  }
+) => {
+  const { name: TableName } = tableOptions;
+
+  const {
+    sort,
+    limit,
+    indexName,
+    exclusiveStartKey
+  } = options;
+
+  const {
+    sortKey,
+    partitionKey,
+    isGlobalSecondaryIndex
+  } = getKeys(tableOptions, indexName);
+
+  got(query, partitionKey, QUERY_ERROR_TEMPLATE);
+
+  const {
+    ConditionExpression,
+    KeyConditionExpression,
+    ExpressionAttributeNames,
+    ExpressionAttributeValues
+  } = buildQueryConditionExpression(query, partitionKey, sortKey);
+
+  const Limit = limit;
+  const ConsistentRead = !isGlobalSecondaryIndex;
+  const ScanIndexForward = sort === SORT_ASC;
+
+  const input = {
+    TableName,
+    Limit,
+    ConsistentRead,
+    ScanIndexForward,
+    KeyConditionExpression,
+    ExpressionAttributeNames,
+    ExpressionAttributeValues
+  } as QueryCommandInput;
+
+  if (indexName) {
+    input.IndexName = indexName;
+  }
+
+  if (ConditionExpression) {
+    input.FilterExpression = ConditionExpression;
+  }
+
+  if (exclusiveStartKey) {
+    input.ExclusiveStartKey = JSON.parse(decodeURIComponent(exclusiveStartKey));
+  }
+
+  return input;
+};
+
+export default buildQueryCommandInput;

package/src/Table/helpers/buildQueryConditionExpression.ts

@@ -0,0 +1,109 @@
+import type { QueryMap } from '@kravc/dos';
+import buildConditionExpression from './buildConditionExpression';
+
+export enum SortExpressionKey {
+  BW = 'bw',
+  LT = 'lt',
+  LE = 'le',
+  GT = 'gt',
+  GE = 'ge',
+};
+
+/** Builds condition expression for a table query. */
+const buildQueryConditionExpression = (
+  query: QueryMap,
+  partitionKey: string,
+  sortKey: string,
+) => {
+  const {
+    [partitionKey]: partitionKeyValue,
+    [sortKey]: sortKeyValue,
+    [`${sortKey}:${SortExpressionKey.BW}`]: sortKeyBeginsWithValue,
+    [`${sortKey}:${SortExpressionKey.LT}`]: sortKeyLowerThanValue,
+    [`${sortKey}:${SortExpressionKey.LE}`]: sortKeyLowerThanOrEqualValue,
+    [`${sortKey}:${SortExpressionKey.GT}`]: sortKeyGreaterThanValue,
+    [`${sortKey}:${SortExpressionKey.GE}`]: sortKeyGreaterThanOrEqualValue,
+    ...conditionQuery
+  } = query;
+
+  const {
+    ConditionExpression,
+    ExpressionAttributeNames,
+    ExpressionAttributeValues,
+  } = buildConditionExpression(conditionQuery);
+
+  ExpressionAttributeNames[`#${partitionKey}`] = partitionKey;
+  ExpressionAttributeValues[`:${partitionKey}`] = partitionKeyValue;
+
+  const KeyConditionExpression = `#${partitionKey} = :${partitionKey}`;
+
+  const result = {
+    ConditionExpression,
+    KeyConditionExpression,
+    ExpressionAttributeNames,
+    ExpressionAttributeValues
+  };
+
+  const isBetweenValues = !!sortKeyLowerThanValue && !!sortKeyGreaterThanValue;
+
+  if (isBetweenValues) {
+    result.KeyConditionExpression += ` AND #${sortKey} BETWEEN :${sortKey}_gt AND :${sortKey}_lt`;
+    result.ExpressionAttributeNames[`#${sortKey}`] = sortKey;
+    result.ExpressionAttributeValues[`:${sortKey}_lt`] = sortKeyLowerThanValue;
+    result.ExpressionAttributeValues[`:${sortKey}_gt`] = sortKeyGreaterThanValue;
+
+    return result;
+  }
+
+  if (sortKeyLowerThanValue) {
+    result.KeyConditionExpression += ` AND #${sortKey} < :${sortKey}_lt`;
+    result.ExpressionAttributeNames[`#${sortKey}`] = sortKey;
+    result.ExpressionAttributeValues[`:${sortKey}_lt`] = sortKeyLowerThanValue;
+
+    return result;
+  }
+
+  if (sortKeyLowerThanOrEqualValue) {
+    result.KeyConditionExpression += ` AND #${sortKey} <= :${sortKey}_le`;
+    result.ExpressionAttributeNames[`#${sortKey}`] = sortKey;
+    result.ExpressionAttributeValues[`:${sortKey}_le`] = sortKeyLowerThanOrEqualValue;
+
+    return result;
+  }
+
+  if (sortKeyGreaterThanValue) {
+    result.KeyConditionExpression += ` AND #${sortKey} > :${sortKey}_gt`;
+    result.ExpressionAttributeNames[`#${sortKey}`] = sortKey;
+    result.ExpressionAttributeValues[`:${sortKey}_gt`] = sortKeyGreaterThanValue;
+
+    return result;
+  }
+
+  if (sortKeyGreaterThanOrEqualValue) {
+    result.KeyConditionExpression += ` AND #${sortKey} >= :${sortKey}_ge`;
+    result.ExpressionAttributeNames[`#${sortKey}`] = sortKey;
+    result.ExpressionAttributeValues[`:${sortKey}_ge`] = sortKeyGreaterThanOrEqualValue;
+
+    return result;
+  }
+
+  if (sortKeyBeginsWithValue) {
+    result.KeyConditionExpression += ` AND begins_with(#${sortKey}, :${sortKey})`;
+    result.ExpressionAttributeNames[`#${sortKey}`] = sortKey;
+    result.ExpressionAttributeValues[`:${sortKey}`] = sortKeyBeginsWithValue;
+
+    return result;
+  }
+
+  if (sortKeyValue) {
+    result.KeyConditionExpression += ` AND #${sortKey} = :${sortKey}`;
+    result.ExpressionAttributeNames[`#${sortKey}`] = sortKey;
+    result.ExpressionAttributeValues[`:${sortKey}`] = sortKeyValue;
+
+    return result;
+  }
+
+  return result;
+};
+
+export default buildQueryConditionExpression;

package/src/Table/helpers/buildTableSchema.ts

@@ -0,0 +1,151 @@
+import { uniq } from 'lodash';
+import type { TableOptions, PrimaryKey, LSI, GSI } from './getTableOptions';
+import {
+  type CreateTableInput,
+  type LocalSecondaryIndex,
+  type GlobalSecondaryIndex
+} from '@aws-sdk/client-dynamodb';
+
+const ProvisionedThroughput = {
+  ReadCapacityUnits: 1,
+  WriteCapacityUnits: 1,
+};
+
+const Projection = {
+  ProjectionType: 'ALL'
+};
+
+/** Returns attribute definitions for table schema. */
+const getAttributeDefinitions = (
+  primaryKey: PrimaryKey,
+  localSecondaryIndexes: LSI[],
+  globalSecondaryIndexes: GSI[]
+) => {
+  const { partitionKey, sortKey } = primaryKey;
+
+  let attributes = [ partitionKey, sortKey ];
+
+  for (const localIndexKey in localSecondaryIndexes) {
+    const { sortKey } = localSecondaryIndexes[localIndexKey];
+
+    attributes.push(sortKey);
+  }
+
+  for (const globalIndexKey in globalSecondaryIndexes) {
+    const { partitionKey, sortKey } = globalSecondaryIndexes[globalIndexKey];
+
+    attributes.push(partitionKey);
+
+    if (sortKey) {
+      attributes.push(sortKey);
+    }
+  }
+
+  attributes = uniq(attributes);
+
+  const AttributeDefinitions = attributes
+    .map(AttributeName => ({
+      // NOTE: Only composite keys are supported, no numbers.
+      AttributeType: 'S',
+      AttributeName,
+    }));
+
+  return AttributeDefinitions;
+};
+
+/** Returns secondary index. */
+const getSecondaryIndex = (
+  IndexName: string,
+  partitionKey: string,
+  sortKey?: string
+) => {
+  const KeySchema = [
+    {
+      KeyType: 'HASH',
+      AttributeName: partitionKey
+    },
+  ];
+
+  if (sortKey) {
+    KeySchema.push({
+      KeyType: 'RANGE',
+      AttributeName: sortKey
+    });
+  }
+
+  const index = {
+    IndexName,
+    KeySchema,
+    Projection,
+  } as LocalSecondaryIndex | GlobalSecondaryIndex;
+
+  return index;
+};
+
+/** Returns schemas for local secondary indexes. */
+const getLocalSecondaryIndexes = (
+  partitionKey: string,
+  localSecondaryIndexes: LSI[]
+): LocalSecondaryIndex[] => {
+  const indexes = localSecondaryIndexes
+    .map(({ name, sortKey }) => getSecondaryIndex(name, partitionKey, sortKey));
+
+  return indexes;
+};
+
+/** Returns schemas for global secondary indexes. */
+const getGlobalSecondaryIndexes = (globalSecondaryIndexes: GSI[], isLocalhost: boolean) => {
+  const indexes = globalSecondaryIndexes
+    .map(({ name, partitionKey, sortKey }) =>
+      getSecondaryIndex(name, partitionKey, sortKey)
+    ) as GlobalSecondaryIndex[];
+
+  /* istanbul ignore next */
+  if (!isLocalhost) {
+    return indexes;
+  }
+
+  indexes.forEach(index => index.ProvisionedThroughput = ProvisionedThroughput);
+  return indexes;
+};
+
+/** Returns schema for a table from table options. */
+const buildTableSchema = ({
+  name: TableName,
+  primaryKey,
+  isLocalhost,
+  localSecondaryIndexes,
+  globalSecondaryIndexes,
+}: TableOptions): CreateTableInput => {
+  const { partitionKey, sortKey } = primaryKey;
+
+  const AttributeDefinitions = getAttributeDefinitions(primaryKey, localSecondaryIndexes, globalSecondaryIndexes);
+  const LocalSecondaryIndexes = getLocalSecondaryIndexes(partitionKey, localSecondaryIndexes);
+  const GlobalSecondaryIndexes = getGlobalSecondaryIndexes(globalSecondaryIndexes, isLocalhost);
+
+  const KeySchema = [
+    { KeyType: 'HASH', AttributeName: partitionKey },
+    { KeyType: 'RANGE', AttributeName: sortKey }
+  ];
+
+  const schema = {
+    TableName,
+    KeySchema,
+    AttributeDefinitions,
+    LocalSecondaryIndexes,
+    GlobalSecondaryIndexes,
+  } as CreateTableInput;
+
+  /* istanbul ignore else */
+  if (isLocalhost) {
+    schema.ProvisionedThroughput = ProvisionedThroughput;
+
+  } else {
+    schema.BillingMode = 'PAY_PER_REQUEST';
+
+  }
+
+  return schema;
+};
+
+export default buildTableSchema;

package/src/Table/helpers/buildUpdateExpression.ts

@@ -0,0 +1,95 @@
+import type { QueryMap, MutationMap } from '@kravc/dos';
+import buildConditionExpression from './buildConditionExpression';
+
+/** Builds update expression from a query for a table item update method. */
+const buildUpdateExpression = (query: QueryMap, mutation: MutationMap) => {
+  const UpdateExpressions = [] as string[];
+  const RemoveExpressions = [] as string[];
+
+  const {
+    ConditionExpression: _ConditionExpression,
+    ExpressionAttributeNames,
+    ExpressionAttributeValues,
+  } = buildConditionExpression(query);
+
+  let ConditionExpression = _ConditionExpression;
+
+  for (let name in mutation) {
+    const expressionValue = mutation[name];
+
+    const arrayItemIndex = name.match(/\[\d+\]/g);
+    name = name.replace(/\[\d+\]/g, '');
+
+    let path = '#' + name.replace(/\./g, '.#');
+
+    const valueKey = name.replace(/\.|:/g, '_');
+
+    const isAppend = name.endsWith(':append');
+    const isPrepend = name.endsWith(':prepend');
+
+    name = name.replace(/:append/, '');
+    name = name.replace(/:prepend/, '');
+
+    const pathKeys = name.split('.');
+
+    for (const pathKey of pathKeys) {
+      ExpressionAttributeNames[`#${pathKey}`] = pathKey;
+    }
+
+    const shouldRemoveAttribute = expressionValue === null;
+
+    if (shouldRemoveAttribute) {
+      RemoveExpressions.push(`${path}`);
+      continue;
+    }
+
+    if (isAppend || isPrepend) {
+      path = path.replace(/:append/, '');
+      path = path.replace(/:prepend/, '');
+
+      ExpressionAttributeValues[`:${valueKey}`] = [ expressionValue ];
+      ExpressionAttributeValues[`:${valueKey}_item`] = expressionValue;
+
+      ConditionExpression += ` AND not contains (${path}, :${valueKey}_item)`;
+
+      if (isAppend) {
+        UpdateExpressions.push(`${path} = list_append(#${name}, :${valueKey})`);
+
+      } else {
+        UpdateExpressions.push(`${path} = list_append(:${valueKey}, #${name})`);
+
+      }
+
+    } else {
+      ExpressionAttributeValues[`:${valueKey}`] = expressionValue;
+      path = `${path}${arrayItemIndex ? arrayItemIndex : ''}`;
+
+      UpdateExpressions.push(`${path} = :${valueKey}`);
+    }
+  }
+
+  const UpdatedExpressions = [];
+
+  const hasUpdateExpressions = UpdateExpressions.length > 0;
+
+  if (hasUpdateExpressions) {
+    UpdatedExpressions.push(`SET ${UpdateExpressions.join(', ')}`);
+  }
+
+  const hasRemoveAttributes = RemoveExpressions.length > 0;
+
+  if (hasRemoveAttributes) {
+    UpdatedExpressions.push(`REMOVE ${RemoveExpressions.join(', ')}`);
+  }
+
+  const UpdateExpression = UpdatedExpressions.join(' ');
+
+  return {
+    UpdateExpression,
+    ConditionExpression,
+    ExpressionAttributeNames,
+    ExpressionAttributeValues,
+  };
+};
+
+export default buildUpdateExpression;