@openstax/ts-utils 1.33.1 → 1.34.0

package/packages/utils/src/services/documentStore/unversioned/dynamodb.ts

@@ -0,0 +1,243 @@
+import {
+  AttributeValue, BatchGetItemCommand, DynamoDB,
+  GetItemCommand, KeysAndAttributes, PutItemCommand,
+  QueryCommand, ScanCommand, UpdateItemCommand
+} from '@aws-sdk/client-dynamodb';
+import asyncPool from 'tiny-async-pool';
+import { Config, TDocument } from '..';
+import { once } from '../../..';
+import { ConfigProviderForConfig, resolveConfigValue } from '../../../config';
+import { ConflictError, NotFoundError } from '../../../errors';
+import { ifDefined } from '../../../guards';
+import { decodeDynamoDocument, encodeDynamoAttribute, encodeDynamoDocument } from '../dynamoEncoding';
+
+interface Initializer<C> {
+  configSpace?: C;
+  dynamoClient?: DynamoDB;
+}
+
+export const dynamoUnversionedDocumentStore = <C extends string = 'dynamodb'>(initializer?: Initializer<C>) => {
+  const init = ifDefined(initializer, {} as NonNullable<typeof initializer>);
+  const dynamodb = once(() => init.dynamoClient ?? new DynamoDB({apiVersion: '2012-08-10'}));
+
+  return <T extends TDocument<T>>() => (configProvider: {[_key in C]: ConfigProviderForConfig<Config>}) => <K extends keyof T>(_: {}, hashKey: K, options?: {afterWrite?: (item: T) => void | Promise<void>; batchAfterWrite?: (items: T[]) => void | Promise<void>}) => {
+    const tableName = once(() => resolveConfigValue(configProvider[ifDefined(init.configSpace, 'dynamodb' as C)].tableName));
+
+    return {
+      loadAllDocumentsTheBadWay: async() => {
+        const loadAllResults = async(ExclusiveStartKey?: {[key: string]: AttributeValue}): Promise<T[]> => {
+          const cmd = new ScanCommand({TableName: await tableName(), ExclusiveStartKey});
+          const result = await dynamodb().send(cmd);
+          const resultItems = result.Items?.map((item) => decodeDynamoDocument<T>(item)) ?? [];
+
+          if (result.LastEvaluatedKey) {
+            return [...resultItems, ...await loadAllResults(result.LastEvaluatedKey)];
+          }
+
+          return resultItems;
+        };
+
+        return loadAllResults();
+      },
+      /*
+       * requires that a global secondary index exist on the table
+       */
+      getItemsByField: async(key: keyof T, value: T[K], pageKey?: string) => {
+        const ExclusiveStartKey = pageKey
+          ? JSON.parse(Buffer.from(pageKey, 'base64').toString('utf-8'))
+          : undefined;
+
+        const table = await tableName();
+        const cmd = new QueryCommand({
+          TableName: table,
+          IndexName: key.toString(),
+          ExclusiveStartKey,
+          KeyConditionExpression: '#hk = :hkv',
+          ExpressionAttributeValues: {
+            ':hkv': encodeDynamoAttribute(value),
+          },
+          ExpressionAttributeNames: {
+            '#hk': key.toString(),
+          },
+        });
+        const response = await dynamodb().send(cmd);
+        const items = response.Items?.map((item) => decodeDynamoDocument<T>(item)) ?? [];
+        const nextPageToken = response.LastEvaluatedKey;
+        return {
+          items,
+          nextPageToken: nextPageToken
+            ? Buffer.from(JSON.stringify(nextPageToken)).toString('base64')
+            : undefined,
+        };
+      },
+      batchGetItem: async(ids: T[K][]) => {
+        const table = await tableName();
+        const key = hashKey.toString();
+
+        const getBatches = async(
+          requestItems?: Record<string, KeysAndAttributes>
+        ): Promise<T[]> => {
+          const cmd = new BatchGetItemCommand({
+            RequestItems: requestItems ?? { [table]: { Keys: ids.map((id) => ({ [key]: encodeDynamoAttribute(id) })) } },
+          });
+
+          const response = await dynamodb().send(cmd);
+          const currentResponses = response.Responses ?
+            response.Responses[table].map(response => decodeDynamoDocument<T>(response)) : [];
+
+          return currentResponses.concat(response.UnprocessedKeys ? await getBatches(response.UnprocessedKeys) : []);
+        };
+
+        return getBatches();
+      },
+      getItem: async(id: T[K]) => {
+        const cmd = new GetItemCommand({
+          Key: { [hashKey.toString()]: encodeDynamoAttribute(id) },
+          TableName: await tableName(),
+        });
+
+        return dynamodb().send(cmd).then(result => result.Item ? decodeDynamoDocument<T>(result.Item) : undefined);
+      },
+      /* atomically increments the given item attribute by 1 */
+      incrementItemAttribute: async(id: T[K], attribute: keyof T) => {
+        const key = hashKey.toString();
+        const field = attribute.toString();
+        const cmd = new UpdateItemCommand({
+          Key: { [key]: encodeDynamoAttribute(id) },
+          TableName: await tableName(),
+          UpdateExpression: 'ADD #f :one',
+          ConditionExpression: 'attribute_exists(#k)',
+          ExpressionAttributeNames: { '#k': hashKey.toString(), '#f': field },
+          ExpressionAttributeValues: { ':one': { N: '1' } },
+          ReturnValues: 'ALL_NEW',
+        });
+
+        return dynamodb().send(cmd).then(async (item) => {
+          const result = item.Attributes?.[field]?.['N'];
+          if (!item.Attributes) { throw new NotFoundError(`Item with ${key} "${id}" does not exist`); }
+          if (!result) { throw new NotFoundError(`Item with ${key} "${id}" did not produce field "${field}"`); }
+          const updatedDoc = decodeDynamoDocument<T>(item.Attributes);
+          await options?.afterWrite?.(updatedDoc);
+          return parseFloat(result);
+        }).catch((error) => {
+          throw error.name === 'ConditionalCheckFailedException' ?
+            new NotFoundError(`Item with ${key} "${id}" does not exist`) : error;
+        });
+      },
+      /* replaces only specified attributes with the given data */
+      patchItem: async(item: Partial<T>) => {
+        const id = item[hashKey];
+        const key = hashKey.toString();
+        if (!id) { throw new Error(`Key attribute "${key}" is required for patchItem`); }
+
+        const entries = Object.entries(item).filter(([field]) => field !== key) as [string, T[keyof T]][];
+        if (entries.length === 0) { throw new Error('No attributes to update'); }
+
+        const updates: string[] = [];
+        const expressionAttributeNames: Record<string, string> = { '#k': key };
+        const expressionAttributeValues: Record<string, AttributeValue> = {};
+        entries.forEach(([field, value], index) => {
+          updates.push(`#f${index} = :f${index}`);
+          expressionAttributeNames[`#f${index}`] = field;
+          expressionAttributeValues[`:f${index}`] = encodeDynamoAttribute(value);
+        });
+
+        const cmd = new UpdateItemCommand({
+          Key: { [key]: encodeDynamoAttribute(id) },
+          TableName: await tableName(),
+          UpdateExpression: `SET ${updates.join(', ')}`,
+          ConditionExpression: 'attribute_exists(#k)',
+          ExpressionAttributeNames: expressionAttributeNames,
+          ExpressionAttributeValues: expressionAttributeValues,
+          ReturnValues: 'ALL_NEW',
+        });
+
+        return dynamodb().send(cmd).then(async(item) => {
+          if (!item.Attributes) { throw new NotFoundError(`Item with ${key} "${id}" does not exist`); }
+          const updatedDoc = decodeDynamoDocument<T>(item.Attributes);
+          await options?.afterWrite?.(updatedDoc);
+          return updatedDoc;
+        }).catch((error) => {
+          throw error.name === 'ConditionalCheckFailedException' ?
+            new NotFoundError(`Item with ${key} "${id}" does not exist`) : error;
+        });
+      },
+      /* replaces the entire document with the given data */
+      putItem: async(item: T) => {
+        const cmd = new PutItemCommand({
+          TableName: await tableName(),
+          Item: encodeDynamoDocument(item),
+        });
+
+        const updatedDoc = await dynamodb().send(cmd).then(() => item);
+        await options?.afterWrite?.(updatedDoc);
+        return updatedDoc;
+      },
+      /* creates a new document, fails if the primary key already exists */
+      createItem: async(item: T) => {
+        const cmd = new PutItemCommand({
+          TableName: await tableName(),
+          Item: encodeDynamoDocument(item),
+          ConditionExpression: 'attribute_not_exists(#k)',
+          ExpressionAttributeNames: {
+            '#k': hashKey.toString(),
+          },
+        });
+
+        return await dynamodb().send(cmd).then(() => item).catch((error) => {
+          throw error.name === 'ConditionalCheckFailedException' ?
+            new ConflictError(`Item with ${String(hashKey)} "${item[hashKey]}" already exists`) : error;
+        }).then(async (createdDoc) => {
+          await options?.afterWrite?.(createdDoc);
+          return createdDoc;
+        });
+      },
+      /* creates multiple new documents, returns successful and failed items separately */
+      batchCreateItem: async(items: T[], concurrency = 10): Promise<{successful: T[]; failed: Array<{item: T; error: Error}>}> => {
+        if (items.length === 0) return { successful: [], failed: [] };
+        const successful: T[] = [];
+        const failed: Array<{item: T; error: Error}> = [];
+
+        // Process using async iterator (tiny-async-pool v2)
+        for await (const result of asyncPool(concurrency, items, async (item: T) => {
+          try {
+            const cmd = new PutItemCommand({
+              TableName: await tableName(),
+              Item: encodeDynamoDocument(item),
+              ConditionExpression: 'attribute_not_exists(#k)',
+              ExpressionAttributeNames: {
+                '#k': hashKey.toString(),
+              },
+            });
+
+            await dynamodb().send(cmd);
+
+            // Only call individual afterWrite if batchAfterWrite is not defined
+            if (!options?.batchAfterWrite) {
+              await options?.afterWrite?.(item);
+            }
+
+            return { success: true, item };
+          } catch (error: any) {
+            const processedError = error.name === 'ConditionalCheckFailedException' ?
+              new ConflictError(`Item with ${String(hashKey)} "${item[hashKey]}" already exists`) : error;
+            return { success: false, item, error: processedError };
+          }
+        })) {
+          if (result.success) {
+            successful.push(result.item);
+          } else {
+            failed.push({ item: result.item, error: result.error });
+          }
+        }
+
+        // Call batchAfterWrite with all successful items if defined
+        if (options?.batchAfterWrite && successful.length > 0) {
+          await options.batchAfterWrite(successful);
+        }
+
+        return { successful, failed };
+      },
+    };
+  };
+};