@squiz/dx-common-lib 1.72.0 → 1.72.3

package/src/stream/StreamUtils.spec.ts

@@ -0,0 +1,113 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+import { extractTenantIdFromArn, getDynamoValue, getActionType } from './StreamUtils';
+
+describe('StreamUtils', () => {
+  describe('extractTenantIdFromArn', () => {
+    it('should extract tenant ID from valid CMP table ARN', () => {
+      const arn =
+        'arn:aws:dynamodb:us-east-1:123456789012:table/dev.cmp-service.tenant123/stream/2024-01-01T00:00:00.000';
+      const tenantId = extractTenantIdFromArn(arn, 'cmp');
+      expect(tenantId).toBe('tenant123');
+    });
+
+    it('should extract tenant ID from valid content table ARN', () => {
+      const arn =
+        'arn:aws:dynamodb:us-east-1:123456789012:table/prod.content-service.acme/stream/2024-01-01T00:00:00.000';
+      const tenantId = extractTenantIdFromArn(arn, 'content');
+      expect(tenantId).toBe('acme');
+    });
+
+    it('should extract only the last segment as tenant ID', () => {
+      const arn =
+        'arn:aws:dynamodb:us-east-1:123456789012:table/dev.cmp-service.tenant123/stream/2024-01-01T00:00:00.000';
+      const tenantId = extractTenantIdFromArn(arn, 'cmp');
+      expect(tenantId).toBe('tenant123');
+    });
+
+    it('should throw error for invalid ARN format', () => {
+      const invalidArn = 'not-a-valid-arn';
+      expect(() => extractTenantIdFromArn(invalidArn, 'cmp')).toThrow('Invalid ARN format');
+    });
+
+    it('should throw error for invalid table name format', () => {
+      const arn = 'arn:aws:dynamodb:us-east-1:123456789012:table/invalid-table-name/stream/2024-01-01T00:00:00.000';
+      expect(() => extractTenantIdFromArn(arn, 'cmp')).toThrow('Invalid cmp table name format');
+    });
+
+    it('should throw error when service identifier does not match', () => {
+      const arn =
+        'arn:aws:dynamodb:us-east-1:123456789012:table/dev.content-service.tenant123/stream/2024-01-01T00:00:00.000';
+      expect(() => extractTenantIdFromArn(arn, 'cmp')).toThrow('Invalid cmp table name format');
+    });
+
+    it('should throw error for ARN with missing table name segment', () => {
+      const arn = 'arn:aws:dynamodb:us-east-1:123456789012:table//stream/2024-01-01T00:00:00.000';
+      expect(() => extractTenantIdFromArn(arn, 'cmp')).toThrow('Invalid ARN format');
+    });
+  });
+
+  describe('getDynamoValue', () => {
+    it('should extract string value from DynamoDB attribute', () => {
+      const attr = { S: 'test-value' };
+      expect(getDynamoValue(attr)).toBe('test-value');
+    });
+
+    it('should extract number value from DynamoDB attribute', () => {
+      const attr = { N: '123' };
+      expect(getDynamoValue(attr)).toBe('123');
+    });
+
+    it('should prefer string value over number value', () => {
+      const attr = { S: 'string-value', N: '123' };
+      expect(getDynamoValue(attr)).toBe('string-value');
+    });
+
+    it('should return undefined when attribute is undefined', () => {
+      expect(getDynamoValue(undefined)).toBeUndefined();
+    });
+
+    it('should return undefined when both S and N are undefined', () => {
+      const attr = {};
+      expect(getDynamoValue(attr as any)).toBeUndefined();
+    });
+
+    it('should return undefined when attribute has no S or N property', () => {
+      const attr = { M: {} };
+      expect(getDynamoValue(attr as any)).toBeUndefined();
+    });
+
+    it('should handle empty string values by returning undefined', () => {
+      const attr = { S: '' };
+      expect(getDynamoValue(attr)).toBeUndefined();
+    });
+  });
+
+  describe('getActionType', () => {
+    it('should return create for INSERT events', () => {
+      expect(getActionType('INSERT')).toBe('create');
+    });
+
+    it('should return delete for REMOVE events', () => {
+      expect(getActionType('REMOVE')).toBe('delete');
+    });
+
+    it('should return update for MODIFY events', () => {
+      expect(getActionType('MODIFY')).toBe('update');
+    });
+
+    it('should return update for unknown event types', () => {
+      expect(getActionType('UNKNOWN')).toBe('update');
+    });
+
+    it('should return update when event name is undefined', () => {
+      expect(getActionType(undefined)).toBe('update');
+    });
+
+    it('should return update when event name is empty string', () => {
+      expect(getActionType('')).toBe('update');
+    });
+  });
+});

package/src/stream/StreamUtils.ts

@@ -0,0 +1,58 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+/**
+ * Extracts tenant ID from a DynamoDB stream ARN
+ *
+ * ARN format: arn:aws:dynamodb:region:account:table/tableName/stream/timestamp
+ * Table name format: {stackPrefix}.{tableServiceName}-service.{tenantId}
+ *
+ * @param arn - The event source ARN from the DynamoDB stream record
+ * @param tableServiceIdentifier - The service identifier (e.g., 'cmp', 'content') to validate in table name
+ * @returns The tenant ID extracted from the table name
+ * @throws Error if ARN or table name format is invalid
+ */
+export function extractTenantIdFromArn(arn: string, tableServiceIdentifier: string): string {
+  const tableName = arn.split('/')[1];
+  if (!tableName) {
+    throw new Error(`Invalid ARN format: ${arn}`);
+  }
+
+  const parts = tableName.split('.');
+  if (parts.length < 3 || parts[1] !== `${tableServiceIdentifier}-service`) {
+    throw new Error(
+      `Invalid ${tableServiceIdentifier} table name format: ${tableName}. Expected format: {prefix}.${tableServiceIdentifier}-service.{tenantId}`,
+    );
+  }
+
+  return parts[parts.length - 1];
+}
+
+/**
+ * Extracts string or number value from DynamoDB attribute format
+ *
+ * DynamoDB represents attributes as objects with type keys (e.g., { S: "value" }, { N: "123" })
+ * This helper extracts the actual value.
+ *
+ * @param value - The DynamoDB attribute value object
+ * @returns The extracted string value, or undefined if the attribute is empty
+ */
+export function getDynamoValue(value?: { S?: string; N?: string }): string | undefined {
+  return value?.S || value?.N;
+}
+
+/**
+ * Determines the action type based on DynamoDB event name
+ *
+ * Maps DynamoDB stream event types to semantic action types suitable for event publishing.
+ *
+ * @param eventName - The DynamoDB stream event name (INSERT, MODIFY, REMOVE)
+ * @returns The corresponding action: 'create', 'update', or 'delete'
+ */
+export function getActionType(eventName?: string): 'create' | 'update' | 'delete' {
+  if (eventName === 'INSERT') return 'create';
+  if (eventName === 'REMOVE') return 'delete';
+  return 'update';
+}