docs(examples): refresh cdk example

Author: dreamorosi

examples/cdk/functions/common/clients/dynamodb.ts

@@ -0,0 +1,15 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { tracer } from '#powertools';
+
+// Create DynamoDB Client and patch it for tracing
+const ddbClient = tracer.captureAWSv3Client(new DynamoDBClient({}));
+
+// Create the DynamoDB Document client.
+const docClient = DynamoDBDocumentClient.from(ddbClient, {
+  marshallOptions: {
+    removeUndefinedValues: true,
+  },
+});
+
+export { ddbClient, docClient };

examples/cdk/functions/common/constants.ts

@@ -0,0 +1,7 @@
+import { getStringFromEnv } from '#helpers/utils';
+
+// Get the DynamoDB table name from environment variables
+const itemsTableName = getStringFromEnv('TABLE_NAME');
+const ssmParameterName = getStringFromEnv('SSM_PARAMETER_NAME');
+
+export { itemsTableName, ssmParameterName };

examples/cdk/functions/common/powertools.ts

@@ -0,0 +1,8 @@
+class ItemNotFound extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = 'ItemNotFound';
+  }
+}
+
+export { ItemNotFound };

examples/cdk/functions/commons/clients/dynamodb.ts

@@ -0,0 +1,32 @@
+import { docClient } from '#clients/dynamodb';
+import { itemsTableName } from '#constants';
+import type { DebugLogger } from '#types';
+import { GetCommand, type GetCommandOutput } from '@aws-sdk/lib-dynamodb';
+
+/**
+ * Fetch an item from the DynamoDB table.
+ *
+ * @param id The ID of the item to fetch from the DynamoDB table
+ * @param logger A logger instance
+ */
+const getItemDynamoDB = async (
+  id: string,
+  logger: DebugLogger
+): Promise<GetCommandOutput['Item']> => {
+  const response = await docClient.send(
+    new GetCommand({
+      TableName: itemsTableName,
+      Key: {
+        id,
+      },
+    })
+  );
+
+  logger.debug(`ddb response`, {
+    response,
+  });
+
+  return response.Item;
+};
+
+export { getItemDynamoDB };

examples/cdk/functions/commons/constants.ts

@@ -0,0 +1,20 @@
+import { getParameter } from '@aws-lambda-powertools/parameters/ssm';
+
+/**
+ * Fetch a string from an SSM parameter.
+ *
+ * Throws an error if the parameter is not found.
+ *
+ * @param name The name of the parameter
+ */
+const getSSMStringParameter = async (name: string): Promise<string> => {
+  const parameter = await getParameter(name, { maxAge: 600 });
+
+  if (!parameter) {
+    throw new Error(`Parameter ${name} not found`);
+  }
+
+  return parameter;
+};
+
+export { getSSMStringParameter };

examples/cdk/functions/commons/errors.ts

@@ -0,0 +1,38 @@
+import { docClient } from '#clients/dynamodb';
+import { itemsTableName } from '#constants';
+import type { DebugLogger } from '#types';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Put an item in the DynamoDB table.
+ *
+ * When the item is put in the table, the item's ID and name are returned.
+ *
+ * @param name The name of the item to put in the DynamoDB table
+ * @param logger A logger instance
+ */
+const putItemInDynamoDB = async (
+  name: string,
+  logger: DebugLogger
+): Promise<{ id: string; name: string }> => {
+  const item = {
+    id: randomUUID(),
+    name,
+  };
+
+  const response = await docClient.send(
+    new PutCommand({
+      TableName: itemsTableName,
+      Item: item,
+    })
+  );
+
+  logger.debug(`ddb response`, {
+    response,
+  });
+
+  return item;
+};
+
+export { putItemInDynamoDB };

examples/cdk/functions/commons/helpers/get-item.ts

@@ -0,0 +1,29 @@
+import { docClient } from '#clients/dynamodb';
+import { itemsTableName } from '#constants';
+import type { DebugLogger } from '#types';
+import { ScanCommand, type ScanCommandOutput } from '@aws-sdk/lib-dynamodb';
+
+/**
+ * Scan the DynamoDB table and return all items.
+ *
+ * @note this function is purposefully not paginated to keep the example simple
+ *
+ * @param logger A logger instance
+ */
+const scanItemsDynamoDB = async (
+  logger: DebugLogger
+): Promise<ScanCommandOutput['Items']> => {
+  const response = await docClient.send(
+    new ScanCommand({
+      TableName: itemsTableName,
+    })
+  );
+
+  logger.debug(`ddb response`, {
+    response,
+  });
+
+  return response.Items;
+};
+
+export { scanItemsDynamoDB };

examples/cdk/functions/commons/helpers/get-string-param.ts

@@ -0,0 +1,35 @@
+/**
+ * Assert that the given value is an error.
+ *
+ * TypeScript treats errors as `unknown` when caught,
+ * so we need to assert that the value is an error.
+ *
+ * We need this because in JavaScript, any value can be thrown
+ * using the `throw` keyword i.e. `throw 1` is valid.
+ *
+ * @param error The value to assert is an error
+ */
+// eslint-disable-next-line func-style -- type assertions cannot use arrow functions microsoft/TypeScript#34523
+function assertIsError(error: unknown): asserts error is Error {
+  if (!(error instanceof Error)) {
+    throw error;
+  }
+}
+
+/**
+ * Fetch a string from an environment variable.
+ *
+ * Throws an error if the environment variable is not set.
+ *
+ * @param name The name of the environment variable
+ */
+const getStringFromEnv = (name: string): string => {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`${name} environment variable is not set`);
+  }
+
+  return value;
+};
+
+export { assertIsError, getStringFromEnv };

examples/cdk/functions/commons/helpers/put-item.ts

@@ -0,0 +1,20 @@
+/**
+ * Service name for the application to use in logs, metrics, and traces.
+ *
+ * Can also be configured via POWERTOOLS_SERVICE_NAME environment variable.
+ */
+const serviceName = 'items-store';
+/**
+ * Namespace for metrics to use in metrics.
+ *
+ * Can also be configured via POWERTOOLS_METRICS_NAMESPACE environment variable.
+ */
+const metricsNamespace = 'pwwertools-example';
+/**
+ * Key-value pairs to include in all metrics and logs.
+ */
+const defaultValues = {
+  executionEnv: process.env.AWS_EXECUTION_ENV || 'N/A',
+};
+
+export { serviceName, metricsNamespace, defaultValues };

examples/cdk/functions/commons/helpers/scan-items.ts

@@ -0,0 +1,10 @@
+/**
+ * We have single entry point for all the powertools modules so that functions that need only one
+ * can bundle only that one that they need and keep the bundle size small.
+ */
+import { logger } from './logger.js';
+import { metrics } from './metrics.js';
+import { tracer } from './tracer.js';
+
+// We export all three modules for those functions who need to use all of them
+export { logger, metrics, tracer };

examples/cdk/functions/commons/helpers/utils.ts

@@ -0,0 +1,22 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+import { PT_VERSION as version } from '@aws-lambda-powertools/commons';
+import { serviceName, defaultValues } from './constants.js';
+
+/**
+ * Create logger instance with centralized configuration so that
+ * all functions have consistent logging behavior.
+ */
+const logger = new Logger({
+  logLevel: 'debug',
+  serviceName,
+  persistentLogAttributes: {
+    ...defaultValues,
+    region: process.env.AWS_REGION || 'N/A',
+    logger: {
+      name: '@aws-lambda-powertools/logger',
+      version,
+    },
+  },
+});
+
+export { logger };

examples/cdk/functions/commons/powertools/constants.ts

@@ -0,0 +1,14 @@
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { serviceName, metricsNamespace, defaultValues } from './constants.js';
+
+/**
+ * Create metrics instance with centralized configuration so that
+ * all functions have the same dimensions and namespace.
+ */
+const metrics = new Metrics({
+  serviceName,
+  namespace: metricsNamespace,
+  defaultDimensions: defaultValues,
+});
+
+export { metrics };

examples/cdk/functions/commons/powertools/index.ts

@@ -0,0 +1,12 @@
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { serviceName } from './constants.js';
+
+/**
+ * Create tracer instance with centralized configuration so that
+ * all traces have the same service name as an annotation.
+ */
+const tracer = new Tracer({
+  serviceName,
+});
+
+export { tracer };

examples/cdk/functions/commons/powertools/logger.ts

@@ -0,0 +1,7 @@
+import type { LogItemExtraInput } from '@aws-lambda-powertools/logger/types';
+
+type DebugLogger = {
+  debug: (message: string, ...extraInput: LogItemExtraInput) => void;
+};
+
+export type { DebugLogger };