@aligent/aws-wrappers 0.0.1

package/src/dynamodb/dynamodb.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBService = void 0;
+const logger_1 = require("@aws-lambda-powertools/logger");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const aws_xray_sdk_core_1 = require("aws-xray-sdk-core");
+const redact_1 = require("../util/redact");
+const BATCH_WRITE_MAX_ATTEMPTS = 5;
+const BATCH_WRITE_BASE_DELAY_MS = 200;
+/**
+ * Fields safe to log at INFO. Omits `Key` (may carry customer IDs / tenant IDs).
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const GET_ITEM_SAFE_FIELDS = [
+    'TableName',
+    'ConsistentRead',
+    'ProjectionExpression',
+    'ReturnConsumedCapacity',
+    'ExpressionAttributeNames',
+];
+/**
+ * Fields safe to log at INFO. Omits `Item` (the payload itself) and
+ * `ExpressionAttributeValues` (values bound to ConditionExpression, often PII).
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const PUT_ITEM_SAFE_FIELDS = [
+    'TableName',
+    'ConditionExpression',
+    'ExpressionAttributeNames',
+    'ReturnValues',
+    'ReturnConsumedCapacity',
+    'ReturnItemCollectionMetrics',
+    'ReturnValuesOnConditionCheckFailure',
+];
+/**
+ * Fields safe to log at INFO. Omits `Key` and `ExpressionAttributeValues`.
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const UPDATE_ITEM_SAFE_FIELDS = [
+    'TableName',
+    'UpdateExpression',
+    'ConditionExpression',
+    'ExpressionAttributeNames',
+    'ReturnValues',
+    'ReturnConsumedCapacity',
+    'ReturnItemCollectionMetrics',
+    'ReturnValuesOnConditionCheckFailure',
+];
+/**
+ * Fields safe to log at INFO. Omits `Key` and `ExpressionAttributeValues`
+ * (the latter binds to ConditionExpression and may carry PII).
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const DELETE_ITEM_SAFE_FIELDS = [
+    'TableName',
+    'ConditionExpression',
+    'ExpressionAttributeNames',
+    'ReturnValues',
+    'ReturnConsumedCapacity',
+    'ReturnItemCollectionMetrics',
+    'ReturnValuesOnConditionCheckFailure',
+];
+/**
+ * Fields safe to log at INFO for `query` and `paginateItems`. Omits
+ * `ExpressionAttributeValues` (values often carry PII) and `ExclusiveStartKey`
+ * (pagination cursor includes Key shape). `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks
+ * the full input.
+ */
+const QUERY_SAFE_FIELDS = [
+    'TableName',
+    'IndexName',
+    'KeyConditionExpression',
+    'FilterExpression',
+    'ProjectionExpression',
+    'ExpressionAttributeNames',
+    'ConsistentRead',
+    'ScanIndexForward',
+    'Select',
+    'Limit',
+    'ReturnConsumedCapacity',
+];
+/**
+ * Fields safe to log at INFO for `scan` and `paginateScan`. Omits
+ * `ExpressionAttributeValues` and `ExclusiveStartKey`.
+ * `POWERTOOLS_LOG_LEVEL=DEBUG` unlocks the full input.
+ */
+const SCAN_SAFE_FIELDS = [
+    'TableName',
+    'IndexName',
+    'FilterExpression',
+    'ProjectionExpression',
+    'ExpressionAttributeNames',
+    'ConsistentRead',
+    'Select',
+    'Limit',
+    'Segment',
+    'TotalSegments',
+    'ReturnConsumedCapacity',
+];
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const backoffDelay = (attempt) => {
+    const exp = BATCH_WRITE_BASE_DELAY_MS * 2 ** attempt;
+    return exp + Math.random() * exp;
+};
+/**
+ * Wrapper around the AWS DynamoDB Document client providing structured
+ * Powertools logging and X-Ray tracing by default.
+ *
+ * Items are automatically marshalled / unmarshalled via the document client —
+ * callers work with plain TypeScript objects in both directions.
+ */
+class DynamoDBService {
+    client;
+    logger;
+    /**
+     * @param opts.logger - Optional Powertools logger. Defaults to `new Logger()`,
+     * which picks up `POWERTOOLS_SERVICE_NAME` from the environment.
+     * @param opts.client - Optional pre-configured `DynamoDBDocumentClient`.
+     * When supplied, the wrapper does not apply X-Ray instrumentation. When
+     * omitted, a default `DynamoDBClient` is wrapped with `captureAWSv3Client`
+     * *before* being passed to `DynamoDBDocumentClient.from`, so X-Ray
+     * tracing captures every DynamoDB call.
+     */
+    constructor(opts) {
+        this.client =
+            opts?.client ??
+                lib_dynamodb_1.DynamoDBDocumentClient.from((0, aws_xray_sdk_core_1.captureAWSv3Client)(new client_dynamodb_1.DynamoDBClient({})), {
+                    marshallOptions: { removeUndefinedValues: true },
+                });
+        this.logger = opts?.logger ?? new logger_1.Logger();
+    }
+    /**
+     * Get an item from DynamoDB.
+     * @template K - Shape of the partition / sort key.
+     * @template R - Expected unmarshalled item shape.
+     * @returns The item, or `undefined` if not found.
+     */
+    async getItem(input) {
+        this.logger.info('Getting DynamoDB item', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, GET_ITEM_SAFE_FIELDS),
+        });
+        const response = await this.client.send(new lib_dynamodb_1.GetCommand(input));
+        return response.Item;
+    }
+    /**
+     * Put an item into DynamoDB. The caller's `Item` is typed as `T`, which
+     * the document client marshalls automatically.
+     * @template T - Type of the item being stored.
+     */
+    async putItem(input) {
+        this.logger.info('Putting DynamoDB item', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, PUT_ITEM_SAFE_FIELDS),
+        });
+        return this.client.send(new lib_dynamodb_1.PutCommand(input));
+    }
+    /**
+     * Update an item in DynamoDB. The `Attributes` field on the response is
+     * typed as `R` — the caller should choose `R` to match their
+     * `ReturnValues` setting:
+     * - `NONE` (default): no `Attributes` returned.
+     * - `ALL_OLD` / `ALL_NEW`: full item.
+     * - `UPDATED_OLD` / `UPDATED_NEW`: only updated attributes (partial).
+     * @template K - Shape of the partition / sort key.
+     * @template R - Expected shape of the returned `Attributes`.
+     */
+    async updateItem(input) {
+        this.logger.info('Updating DynamoDB item', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, UPDATE_ITEM_SAFE_FIELDS),
+        });
+        const response = await this.client.send(new lib_dynamodb_1.UpdateCommand(input));
+        return response;
+    }
+    /**
+     * Delete an item from DynamoDB. The `Attributes` field on the response is
+     * typed as `R` — relevant when `ReturnValues: 'ALL_OLD'` is set.
+     * @template K - Shape of the partition / sort key.
+     * @template R - Expected shape of the returned `Attributes`.
+     */
+    async deleteItem(input) {
+        this.logger.info('Deleting DynamoDB item', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, DELETE_ITEM_SAFE_FIELDS),
+        });
+        const response = await this.client.send(new lib_dynamodb_1.DeleteCommand(input));
+        return response;
+    }
+    /**
+     * Execute a DynamoDB Query. The full `QueryCommandOutput` is returned with
+     * `Items` typed as `T[]` so callers retain pagination metadata
+     * (`LastEvaluatedKey`, `Count`, etc.).
+     * @template T - Expected shape of each unmarshalled item.
+     */
+    async query(input) {
+        this.logger.info('Querying DynamoDB', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, QUERY_SAFE_FIELDS),
+        });
+        const response = await this.client.send(new lib_dynamodb_1.QueryCommand(input));
+        return response;
+    }
+    /**
+     * Scan a DynamoDB table. The full `ScanCommandOutput` is returned with
+     * `Items` typed as `T[]` so callers retain pagination metadata.
+     *
+     * Scan reads every item in the table, so cost and latency grow linearly
+     * with table size; it is rarely the right tool in a runtime service.
+     * Prefer, in order:
+     *
+     *   1. `query` with the table's partition key.
+     *   2. `query` against a GSI or LSI whose key matches your access pattern.
+     *   3. A sparse GSI populated only for the items you need to enumerate.
+     *   4. A denormalised lookup item or table maintained on write.
+     *
+     * Legitimate scan use cases are mostly one-off admin work (export,
+     * migration, audit). For those, prefer the AWS CLI or Console rather than
+     * embedding a scan in a Lambda.
+     *
+     * @template T - Expected shape of each unmarshalled item.
+     */
+    async scan(input) {
+        this.logger.info('Scanning DynamoDB', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, SCAN_SAFE_FIELDS),
+        });
+        const response = await this.client.send(new lib_dynamodb_1.ScanCommand(input));
+        return response;
+    }
+    /**
+     * Batch-get items from one or more DynamoDB tables.
+     *
+     * Note: this method is intentionally **not** generic. `BatchGet`'s
+     * `Responses` field is a multi-table `Record<string, item[]>` whose item
+     * shapes can differ per table — no single `T` can soundly describe it.
+     * Callers should narrow the result type at the call site.
+     */
+    async batchGet(input) {
+        // Inline DEBUG check rather than `filterFieldsForLogLevel` because
+        // `RequestItems` is a `Record<tableName, KeysAndAttributes>` — the
+        // payload (`Keys[]`) lives inside the value, not as a top-level key
+        // the helper could pick or drop.
+        const isDebug = this.logger.getLevelName() === 'DEBUG';
+        this.logger.info('Batch getting DynamoDB items', {
+            input: isDebug ? input : { tables: Object.keys(input.RequestItems ?? {}) },
+        });
+        return this.client.send(new lib_dynamodb_1.BatchGetCommand(input));
+    }
+    /**
+     * Batch-write items to DynamoDB, retrying `UnprocessedItems` with jittered
+     * exponential backoff. Up to 5 attempts (200ms base delay). Throws when
+     * items remain unprocessed after the final attempt.
+     */
+    async batchWrite(input) {
+        // Inline DEBUG check rather than `filterFieldsForLogLevel` because
+        // `RequestItems` is a `Record<tableName, WriteRequest[]>` — the
+        // payload (`PutRequest.Item` / `DeleteRequest.Key`) lives inside the
+        // value, not as a top-level key the helper could pick or drop.
+        const isDebug = this.logger.getLevelName() === 'DEBUG';
+        this.logger.info('Batch writing DynamoDB items', {
+            input: isDebug ? input : { tables: Object.keys(input.RequestItems ?? {}) },
+        });
+        let current = input;
+        for (let attempt = 0; attempt < BATCH_WRITE_MAX_ATTEMPTS; attempt++) {
+            const response = await this.client.send(new lib_dynamodb_1.BatchWriteCommand(current));
+            const unprocessed = response.UnprocessedItems;
+            if (!unprocessed || Object.keys(unprocessed).length === 0)
+                return response;
+            this.logger.warn('Retrying unprocessed DynamoDB items', {
+                attempt: attempt + 1,
+                tables: Object.keys(unprocessed),
+            });
+            if (attempt < BATCH_WRITE_MAX_ATTEMPTS - 1)
+                await sleep(backoffDelay(attempt));
+            current = { ...input, RequestItems: unprocessed };
+        }
+        throw new Error(`batchWrite failed after ${BATCH_WRITE_MAX_ATTEMPTS} attempts`);
+    }
+    /**
+     * Paginate over Query results, yielding one unmarshalled item at a time.
+     * @template T - Expected shape of each yielded item.
+     */
+    async *paginateItems(input) {
+        this.logger.info('Paginating DynamoDB query', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, QUERY_SAFE_FIELDS),
+        });
+        const paginator = (0, lib_dynamodb_1.paginateQuery)({ client: this.client }, input);
+        for await (const page of paginator) {
+            if (!page.Items)
+                continue;
+            for (const item of page.Items)
+                yield item;
+        }
+    }
+    /**
+     * Paginate over Scan results, yielding one unmarshalled item at a time.
+     * @template T - Expected shape of each yielded item.
+     */
+    async *paginateScan(input) {
+        this.logger.info('Paginating DynamoDB scan', {
+            input: (0, redact_1.filterFieldsForLogLevel)(this.logger, input, SCAN_SAFE_FIELDS),
+        });
+        const paginator = (0, lib_dynamodb_1.paginateScan)({ client: this.client }, input);
+        for await (const page of paginator) {
+            if (!page.Items)
+                continue;
+            for (const item of page.Items)
+                yield item;
+        }
+    }
+}
+exports.DynamoDBService = DynamoDBService;

package/src/index.d.ts

@@ -0,0 +1,7 @@
+export { DynamoDBService } from './dynamodb/dynamodb';
+export { S3Service } from './s3/s3';
+export { SecretsManagerService } from './secrets-manager/secrets-manager';
+export { StepFunctionsService } from './sfn/sfn';
+export { SNSService } from './sns/sns';
+export { SQSService } from './sqs/sqs';
+export { SSMService } from './ssm/ssm';

package/src/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSMService = exports.SQSService = exports.SNSService = exports.StepFunctionsService = exports.SecretsManagerService = exports.S3Service = exports.DynamoDBService = void 0;
+var dynamodb_1 = require("./dynamodb/dynamodb");
+Object.defineProperty(exports, "DynamoDBService", { enumerable: true, get: function () { return dynamodb_1.DynamoDBService; } });
+var s3_1 = require("./s3/s3");
+Object.defineProperty(exports, "S3Service", { enumerable: true, get: function () { return s3_1.S3Service; } });
+var secrets_manager_1 = require("./secrets-manager/secrets-manager");
+Object.defineProperty(exports, "SecretsManagerService", { enumerable: true, get: function () { return secrets_manager_1.SecretsManagerService; } });
+var sfn_1 = require("./sfn/sfn");
+Object.defineProperty(exports, "StepFunctionsService", { enumerable: true, get: function () { return sfn_1.StepFunctionsService; } });
+var sns_1 = require("./sns/sns");
+Object.defineProperty(exports, "SNSService", { enumerable: true, get: function () { return sns_1.SNSService; } });
+var sqs_1 = require("./sqs/sqs");
+Object.defineProperty(exports, "SQSService", { enumerable: true, get: function () { return sqs_1.SQSService; } });
+var ssm_1 = require("./ssm/ssm");
+Object.defineProperty(exports, "SSMService", { enumerable: true, get: function () { return ssm_1.SSMService; } });

package/src/s3/s3.d.ts

@@ -0,0 +1,131 @@
+import { Logger } from '@aws-lambda-powertools/logger';
+import { CopyObjectCommandInput, CopyObjectCommandOutput, DeleteObjectCommandInput, DeleteObjectCommandOutput, DeleteObjectsCommandOutput, GetObjectCommandInput, GetObjectCommandOutput, HeadObjectCommandInput, HeadObjectCommandOutput, PutObjectCommandInput, PutObjectCommandOutput, S3Client } from '@aws-sdk/client-s3';
+/** Tight wrapper input type for `putObject`. */
+type PutObjectInput = Required<Pick<PutObjectCommandInput, 'Bucket' | 'Key' | 'Body'>>;
+/** Tight wrapper input type for `putJsonObject`. */
+type PutJsonObjectInput<T> = {
+    Bucket: string;
+    Key: string;
+    Body: T;
+    Metadata?: Record<string, string>;
+};
+/**
+ * Wrapper around the AWS S3 client providing structured Powertools logging
+ * and X-Ray tracing by default.
+ *
+ * Input shapes are intentionally tight (Bucket/Key/Body only). Callers
+ * needing SDK-level options not exposed here (server-side encryption,
+ * tagging, version IDs) should use `S3Client` directly.
+ */
+export declare class S3Service {
+    private readonly client;
+    private readonly logger;
+    /**
+     * @param opts.logger - Optional Powertools logger. Defaults to `new Logger()`,
+     * which picks up `POWERTOOLS_SERVICE_NAME` from the environment.
+     * @param opts.client - Optional pre-configured `S3Client`. When supplied,
+     * the wrapper does not apply X-Ray instrumentation.
+     */
+    constructor(opts?: {
+        logger?: Logger;
+        client?: S3Client;
+    });
+    /**
+     * Put an object into S3.
+     *
+     * Note: the structured log line only includes `Bucket` and `Key` —
+     * `Body` is omitted to avoid spilling large payloads or sensitive
+     * content into CloudWatch.
+     *
+     * @param input - Bucket, Key, and Body of the object to store.
+     */
+    putObject(input: PutObjectInput): Promise<PutObjectCommandOutput>;
+    /**
+     * Serialise a value to JSON and store it as an S3 object.
+     *
+     * Note: the structured log line only includes `Bucket` and `Key` —
+     * the JSON-encoded body is omitted to avoid spilling potentially
+     * large or sensitive content into CloudWatch.
+     *
+     * @template T - Type of the value being stored.
+     */
+    putJsonObject<T>(input: PutJsonObjectInput<T>): Promise<PutObjectCommandOutput>;
+    /**
+     * Get an object from S3.
+     */
+    getObject(input: Required<Pick<GetObjectCommandInput, 'Bucket' | 'Key'>>): Promise<GetObjectCommandOutput>;
+    /**
+     * Get an object from S3 and return its body as a string.
+     * @returns The object body as a string, or `undefined` if the response
+     * has no body.
+     */
+    getObjectBody(input: Required<Pick<GetObjectCommandInput, 'Bucket' | 'Key'>>): Promise<string | undefined>;
+    /**
+     * Get an object from S3 and parse it as JSON.
+     * @template T - Expected type of the parsed value.
+     * @returns The parsed value, or `undefined` if the response has no body.
+     * @throws If the body is non-empty and not valid JSON.
+     */
+    getJsonObject<T>(input: Required<Pick<GetObjectCommandInput, 'Bucket' | 'Key'>>): Promise<T | undefined>;
+    /**
+     * Fetch the metadata for an S3 object without downloading its body.
+     */
+    headObject(input: Required<Pick<HeadObjectCommandInput, 'Bucket' | 'Key'>>): Promise<HeadObjectCommandOutput>;
+    /**
+     * Copy an object within S3.
+     */
+    copyObject(input: Required<Pick<CopyObjectCommandInput, 'Bucket' | 'Key' | 'CopySource'>>): Promise<CopyObjectCommandOutput>;
+    /**
+     * List object keys under a bucket and optional prefix, auto-paginating
+     * across all pages.
+     */
+    listObjects(bucket: string, prefix?: string): Promise<string[]>;
+    /**
+     * List and JSON-parse every object under a bucket and optional prefix.
+     * Auto-paginated. Objects without a body are skipped.
+     * @template T - Expected type of each parsed object.
+     */
+    getAllObjects<T>(bucket: string, prefix?: string): Promise<T[]>;
+    /**
+     * Generate a presigned URL that callers can use to GET or PUT an S3 object
+     * directly, without going through the wrapper. The signing happens against
+     * the wrapper's `S3Client`, so callers do not need their own client.
+     *
+     * GET URLs are signed with `ResponseContentDisposition: 'attachment'` so
+     * browsers download the object rather than rendering it in-place.
+     *
+     * The input shape is an inline object (rather than the `Required<Pick<...>>`
+     * pattern used by other S3 methods) because this method wraps two SDK
+     * commands rather than one, and `action` / `expiresIn` are wrapper-level
+     * concerns with no SDK-input equivalent.
+     *
+     * @param input.Bucket - The S3 bucket name.
+     * @param input.Key - The S3 object key.
+     * @param input.action - `'get'` to download, `'put'` to upload.
+     * @param input.expiresIn - URL lifetime in seconds. Defaults to 3600 (1 hour).
+     */
+    getPresignedUrl(input: {
+        Bucket: string;
+        Key: string;
+        action: 'get' | 'put';
+        expiresIn?: number;
+    }): Promise<string>;
+    /**
+     * Delete a single object from S3.
+     */
+    deleteObject(input: Required<Pick<DeleteObjectCommandInput, 'Bucket' | 'Key'>>): Promise<DeleteObjectCommandOutput>;
+    /**
+     * Delete multiple objects from S3, auto-chunking the request into batches
+     * of 1000 keys (the S3-enforced DeleteObjects limit). Returns one output
+     * per chunk.
+     */
+    deleteObjects(bucket: string, keys: string[]): Promise<DeleteObjectsCommandOutput[]>;
+    /**
+     * Delete every object in a bucket. Streams the listing page-by-page and
+     * delegates each page's deletion to `deleteObjects`, so peak memory stays
+     * bounded by one page (~1000 keys) regardless of bucket size.
+     * @returns The keys of every deleted object.
+     */
+    emptyBucket(bucket: string): Promise<string[]>;
+}
+export {};