@jzhuo3/dynamodb-lib 0.1.0 → 0.1.1

package/PUBLISHING.md

@@ -34,7 +34,15 @@ npm publish --access public
 
 `prepublishOnly` runs the source, unit, build and package checks. Integration tests are explicit because they require an available database; CI runs them against DynamoDB Local. The AWS SDK dependency tree is deliberately bundled with the archive, alongside `npm-shrinkwrap.json`, to preserve the tested Node 18-compatible, patched dependencies. After updating dependencies, refresh the shrinkwrap and run the clean consumer installation check as well as the Node runtime matrix.
 
-This repository contains a verification workflow, but no automatic publishing trigger; the actual release identity and credentials still need to be configured.
+## Automated publishing
+
+Commit and push the workflows and both Release Please configuration files before creating the next release. `release-please.yml` uses the repository variable `RELEASE_APP_CLIENT_ID` and secret `RELEASE_APP_PRIVATE_KEY` to prepare release PRs and create GitHub releases after those PRs are merged.
+
+When a non-prerelease GitHub release is published, `.github/workflows/publish.yml` checks that its tag is `vX.Y.Z` and matches `package.json`. It runs the reusable CI workflow against that exact commit, including unit, package, coverage, clean installation, and DynamoDB Local integration checks across Node 18, 20, 22, and 24. Only after verification passes does its `publish` job enter the `npm` environment and publish using Node 24 and npm 11. Draft releases and prereleases do not publish to npm.
+
+Configure the npm package's GitHub Actions trusted publisher with owner `maczhuo`, repository `dynamodb-lib`, workflow filename `publish.yml`, environment `npm`, and permission for direct `npm publish`. The GitHub environment `npm` must allow release tags such as `v*`. No `NPM_TOKEN` is required. Any environment approval rules will pause the publish job until satisfied.
+
+The workflow does not retroactively publish existing GitHub releases. If a run fails before publication, fix the external configuration and rerun the failed jobs from GitHub Actions. An already published npm version cannot be published again; code or workflow fixes require a new release containing those changes. Initial package creation may still require the manual bootstrap described above.
 
 Official references (checked September 2026):
 

package/dist/cjs/index.js

@@ -421,6 +421,7 @@ class DynamoDBTransaction {
                     if (i === retries - 1) {
                         throw error;
                     }
+                    this.logger.warn('DynamoDB retrying transaction conflict', { mode: this.mode, attempt: i + 1, maxAttempts: retries, delayMs: delay * (i + 1) });
                     await new Promise(resolve => setTimeout(resolve, delay * (i + 1)));
                 }
                 else {
@@ -669,10 +670,6 @@ class DynamoDBTransaction {
             }
             ExpressionAttributeValues[attributeValueVariable] = value;
         });
-        this.logger.debug('Update Expression: %s', UpdateExpression);
-        this.logger.debug('Condition Expression: %s', ConditionExpression);
-        this.logger.debug('Expression Attribute Names: %o', ExpressionAttributeNames);
-        this.logger.debug('Expression Attribute Values: %o', ExpressionAttributeValues);
         this.transactWriteItems.push({
             Update: {
                 TableName: table.name,
@@ -748,6 +745,7 @@ class DynamoDBTransaction {
         const result = {
             numberOfTransactItems: 0,
         };
+        this.logger.debug('DynamoDB transaction started', { mode: this.mode, itemCount: this.mode === DynamoDBTransactionMode.READ ? this.transactGetItems.length : this.transactWriteItems.length });
         switch (this.mode) {
             case DynamoDBTransactionMode.READ:
                 command = new lib_dynamodb_1.TransactGetCommand({
@@ -759,21 +757,21 @@ class DynamoDBTransaction {
                 const { Responses } = (await this.txConflictRetryWrapper(command, this.txRetryLimit, this.txRetryDelay).catch((e) => {
                     this._cleanup();
                     if (isTransactionConflictError(e)) {
-                        this.logger.error('Transaction conflict due to TransactionConflict');
+                        this.logger.error('DynamoDB transaction conflict retry limit reached', { errorName: e.name });
                         throw new DynamoDBError(409, {
                             message: e.message,
                             cause: e,
                         });
                     }
                     else if (e.name === 'TransactionCanceledException') {
-                        this.logger.error(e.message);
+                        this.logger.error('DynamoDB transaction canceled', { errorName: e.name });
                         throw new DynamoDBError(400, {
                             message: e.message,
                             cause: e,
                         });
                     }
                     else {
-                        this.logger.error('Transaction failed due to %s', e.message);
+                        this.logger.error('Transaction failed', { errorName: e.name });
                         throw new DynamoDBError(500, {
                             message: e.message,
                             cause: e,
@@ -822,28 +820,28 @@ class DynamoDBTransaction {
                 await this.txConflictRetryWrapper(command, this.txRetryLimit, this.txRetryDelay).catch((e) => {
                     this._cleanup();
                     if (isTransactionConflictError(e)) {
-                        this.logger.error('Transaction conflict due to TransactionConflict');
+                        this.logger.error('DynamoDB transaction conflict retry limit reached', { errorName: e.name });
                         throw new DynamoDBError(409, {
                             message: e.message,
                             cause: e,
                         });
                     }
                     else if (e.name === 'TransactionCanceledException') {
-                        this.logger.error(e.message);
+                        this.logger.error('DynamoDB transaction canceled', { errorName: e.name });
                         throw new DynamoDBError(400, {
                             message: e.message,
                             cause: e,
                         });
                     }
                     else if (e.name === 'ValidationException') {
-                        this.logger.error('The request parameters are invalid with error: %s', e.message);
+                        this.logger.error('The request parameters are invalid', { errorName: e.name });
                         throw new DynamoDBError(400, {
                             message: 'Invalid request parameters',
                             cause: e,
                         });
                     }
                     else {
-                        this.logger.error('Transaction failed due to %s', e.message);
+                        this.logger.error('Transaction failed', { errorName: e.name });
                         throw new DynamoDBError(500, {
                             message: e.message,
                             cause: e,
@@ -856,6 +854,7 @@ class DynamoDBTransaction {
             default:
                 throw new Error('Invalid transaction mode');
         }
+        this.logger.debug('DynamoDB transaction completed', { mode: this.mode, itemCount: result.numberOfTransactItems });
         return result;
     }
 }
@@ -925,8 +924,7 @@ class DynamoDBService {
                 ExpressionAttributeNames[attributeNameVariable] = attributeName;
             });
         }
-        this.logger.debug('Projection Expression: %s', ProjectionExpression);
-        this.logger.debug('Expression Attribute Names: %o', ExpressionAttributeNames);
+        this.logger.debug('DynamoDB request started', { operation: 'getOne', tableKey });
         const getCommand = new lib_dynamodb_1.GetCommand({
             TableName: table.name,
             Key: keys,
@@ -941,22 +939,14 @@ class DynamoDBService {
             .send(getCommand)
             .catch((e) => {
             if (e.name === 'ValidationException') {
-                this.logger.error('The request parameters are invalid with error: %s', e.message, {
-                    tableKey,
-                    primaryKey,
-                    opts,
-                });
+                this.logger.error('The request parameters are invalid', { errorName: e.name, tableKey });
                 throw new DynamoDBError(400, {
                     message: 'Invalid request parameters',
                     cause: e,
                 });
             }
             else {
-                this.logger.error('Failed to get item with error: %s', e.message, {
-                    tableKey,
-                    primaryKey,
-                    opts,
-                });
+                this.logger.error('Failed to get item', { errorName: e.name, tableKey });
                 throw new DynamoDBError(500, {
                     message: 'Failed to get item',
                     cause: e,
@@ -967,6 +957,7 @@ class DynamoDBService {
         if (item && table.timeToLiveAttribute && item[table.timeToLiveAttribute] !== undefined) {
             const now = getUnixTime(new Date());
             if (item[table.timeToLiveAttribute] <= now) {
+                this.logger.debug('DynamoDB getOne completed', { tableKey, outcome: 'expired' });
                 return null;
             }
             // Delete the time to live attribute from the item if not requested
@@ -974,6 +965,7 @@ class DynamoDBService {
                 delete item[table.timeToLiveAttribute];
             }
         }
+        this.logger.debug('DynamoDB getOne completed', { tableKey, outcome: item ? 'found' : 'not-found' });
         // Item will be undefined if not found
         // Convert keys back to camelCase if camelOrSnake is 'camel' or to snake_case if camelOrSnake is 'snake'
         if (item) {
@@ -1007,7 +999,6 @@ class DynamoDBService {
         const keys = primaryKeys.map((primaryKey, indx) => {
             const isArrayOfKeys = Array.isArray(primaryKey);
             const pkStr = serializeKey(primaryKey);
-            this.logger.debug('Primary Key: %s', pkStr);
             if (pkIndexMap.has(pkStr)) {
                 throw new Error(`Duplicate primary key: ${pkStr}`);
             }
@@ -1056,13 +1047,12 @@ class DynamoDBService {
                 ExpressionAttributeNames[attributeNameVariable] = attributeName;
             });
         }
-        this.logger.debug('Projection Expression: %s', ProjectionExpression);
-        this.logger.debug('Expression Attribute Names: %o', ExpressionAttributeNames);
         const results = new Array(primaryKeys.length).fill(null);
         const now = getUnixTime(new Date());
         let unprocessedAttempt = 0;
         while (keys.length > 0) {
             const batch = keys.splice(0, 100);
+            this.logger.debug('DynamoDB batch request started', { operation: 'getMany', tableKey, itemCount: batch.length });
             const batchGetCommand = new lib_dynamodb_1.BatchGetCommand({
                 RequestItems: {
                     [table.name]: {
@@ -1076,19 +1066,23 @@ class DynamoDBService {
                 },
                 ReturnConsumedCapacity: opts.returnConsumedCapacity ?? client_dynamodb_1.ReturnConsumedCapacity.NONE,
             });
-            const { Responses: responses, UnprocessedKeys: rawUnprocessedKeys } = await this.ddbDocClient.send(batchGetCommand);
+            const { Responses: responses, UnprocessedKeys: rawUnprocessedKeys } = await this.ddbDocClient.send(batchGetCommand).catch((error) => {
+                this.logger.error('Failed to get items', { tableKey, errorName: error.name });
+                throw error;
+            });
             const items = responses && responses[table.name] ? responses[table.name] : [];
             const unprocessedKeys = (rawUnprocessedKeys && rawUnprocessedKeys[table.name]?.Keys) || [];
-            this.logger.debug(`GetMany Responsed Items: %o`, items);
-            this.logger.debug('Now: %d', now);
             if (unprocessedKeys.length > 0) {
                 if (unprocessedAttempt >= MAX_UNPROCESSED_ATTEMPTS) {
+                    this.logger.error('DynamoDB batch retry limit reached', { operation: 'getMany', tableKey, retryCount: unprocessedAttempt });
                     throw new DynamoDBError(500, {
                         message: 'Failed to retrieve items after multiple attempts',
                         cause: new Error('Too many unprocessed items'),
                     });
                 }
-                await sleep(backoffDelayMs(unprocessedAttempt));
+                const delayMs = backoffDelayMs(unprocessedAttempt);
+                this.logger.warn('DynamoDB retrying unprocessed batch items', { operation: 'getMany', tableKey, itemCount: unprocessedKeys.length, attempt: unprocessedAttempt + 1, delayMs });
+                await sleep(delayMs);
                 unprocessedAttempt += 1;
             }
             else {
@@ -1111,7 +1105,6 @@ class DynamoDBService {
                 const pkStr = serializeKey(table.sortKey
                     ? [item[table.partitionKey], item[table.sortKey]]
                     : item[table.partitionKey]);
-                this.logger.debug('Primary Key: %s', pkStr);
                 //  Delete the primary key values from the item if not requested
                 if (optIncludePartitionKey === false) {
                     delete item[table.partitionKey];
@@ -1138,6 +1131,7 @@ class DynamoDBService {
                 }
             });
         }
+        this.logger.debug('DynamoDB getMany completed', { tableKey, requestedCount: primaryKeys.length, returnedCount: results.filter(item => item !== null).length });
         return results;
     }
     async find(tableKey, keyCondition, filter = null, opts = {}, camelOrSnake = 'camel') {
@@ -1300,7 +1294,6 @@ class DynamoDBService {
                             indexName: indexToScan.indexName,
                             projectionType: indexToScan
                                 .projectionType,
-                            projectionFields,
                         });
                     }
                     break;
@@ -1330,12 +1323,11 @@ class DynamoDBService {
                             ]).length > 0;
                     }
                     if (hasFieldNotInsideGSIProjection) {
-                        this.logger.error('Some of the projection fields are not included in the GSI projection, which may cause additional read cost', {
+                        this.logger.error('Some of the projection fields are not included in the GSI projection, so the query cannot be executed', {
                             tableKey,
                             indexName: indexToScan.indexName,
                             projectionType: indexToScan
                                 .projectionType,
-                            projectionFields,
                         });
                         throw new Error('All projection fields must be included in the GSI projection');
                     }
@@ -1392,11 +1384,6 @@ class DynamoDBService {
             }
             ExpressionAttributeValues[attributeValueVariable] = value;
         });
-        this.logger.debug('Projection Expression: %s', ProjectionExpression);
-        this.logger.debug('Expression Attribute Names: %o', ExpressionAttributeNames);
-        this.logger.debug('Expression Attribute Values: %o', ExpressionAttributeValues);
-        this.logger.debug('Key Condition Expression: %s', KeyConditionExpression);
-        this.logger.debug('Filter Expression: %s', FilterExpression);
         const numOfNeededItems = opts.limit; // May be undefined then no limit
         const result = {
             items: [],
@@ -1458,32 +1445,24 @@ class DynamoDBService {
                 : {}),
         };
         while (true) {
+            this.logger.debug('DynamoDB query page requested', { tableKey, hasCursor: !!params.ExclusiveStartKey, hasFilter: !!params.FilterExpression });
             const { Items, LastEvaluatedKey } = await this.ddbDocClient
                 .send(new lib_dynamodb_1.QueryCommand(params))
                 .catch((e) => {
                 if (e.name === 'ValidationException') {
-                    this.logger.error('The request parameters are invalid with error: %s', e.message, {
-                        tableKey,
-                        keyCondition,
-                        filter,
-                        opts,
-                    });
+                    this.logger.error('The request parameters are invalid', { errorName: e.name, tableKey });
                     throw new DynamoDBError(400, {
                         message: 'Invalid request parameters',
                         cause: e,
                     });
                 }
-                this.logger.error('Failed to query items with error: %s', e.message, {
-                    tableKey,
-                    keyCondition,
-                    filter,
-                    opts,
-                });
+                this.logger.error('Failed to query items', { errorName: e.name, tableKey });
                 throw new DynamoDBError(500, {
                     message: 'Failed to query items',
                     cause: e,
                 });
             });
+            this.logger.debug('DynamoDB query page received', { tableKey, itemCount: Items?.length ?? 0, hasMore: !!LastEvaluatedKey });
             if (LastEvaluatedKey) {
                 params.ExclusiveStartKey = LastEvaluatedKey;
             }
@@ -1628,6 +1607,7 @@ class DynamoDBService {
                 ExpressionAttributeNames[key] = value;
             });
         }
+        this.logger.debug('DynamoDB request started', { operation: 'createOne', tableKey });
         const putCommand = new lib_dynamodb_1.PutCommand({
             TableName: table.name,
             Item: normalizedItem,
@@ -1680,22 +1660,18 @@ class DynamoDBService {
             const error = e;
             if (error.name === 'ConditionalCheckFailedException' &&
                 opts.onConflict === 'ignore') {
-                this.logger.debug('Item %s already exists', normalizedItem[table.partitionKey] +
-                    (table.sortKey ? `:${normalizedItem[table.sortKey]}` : ''));
+                this.logger.debug('DynamoDB create skipped: item already exists', { tableKey });
                 result.created = false;
             }
             else {
-                this.logger.error('Failed to create item with error: %s', error.message, {
-                    tableKey,
-                    item: normalizedItem,
-                    opts,
-                });
+                this.logger.error('Failed to create item', { errorName: error.name, tableKey });
                 throw new DynamoDBError(500, {
                     message: 'Failed to create item',
                     cause: error,
                 });
             }
         }
+        this.logger.debug('DynamoDB createOne completed', { tableKey, created: result.created });
         return result;
     }
     async createMany(tableKey, primaryKeys, items, opts = {}) {
@@ -1740,6 +1716,7 @@ class DynamoDBService {
         let unprocessedAttempt = 0;
         while (normalizedItems.length > 0) {
             const batch = normalizedItems.splice(0, 25);
+            this.logger.debug('DynamoDB batch request started', { operation: 'createMany', tableKey, itemCount: batch.length });
             const batchWriteCommand = new lib_dynamodb_1.BatchWriteCommand({
                 RequestItems: {
                     [table.name]: batch.map(item => ({
@@ -1753,11 +1730,7 @@ class DynamoDBService {
             const { UnprocessedItems } = await this.ddbDocClient
                 .send(batchWriteCommand)
                 .catch((e) => {
-                this.logger.error('Failed to create items with error: %s', e.message, {
-                    tableKey,
-                    items: batch,
-                    opts,
-                });
+                this.logger.error('Failed to create items', { errorName: e.name, tableKey });
                 throw new DynamoDBError(500, {
                     message: 'Failed to create items',
                     cause: e,
@@ -1766,12 +1739,15 @@ class DynamoDBService {
             const unprocessedItems = UnprocessedItems?.[table.name];
             if (unprocessedItems !== undefined && unprocessedItems.length > 0) {
                 if (unprocessedAttempt >= MAX_UNPROCESSED_ATTEMPTS) {
+                    this.logger.error('DynamoDB batch retry limit reached', { operation: 'createMany', tableKey, retryCount: unprocessedAttempt });
                     throw new DynamoDBError(500, {
                         message: 'Failed to create items after multiple attempts',
                         cause: new Error('Too many unprocessed items'),
                     });
                 }
-                await sleep(backoffDelayMs(unprocessedAttempt));
+                const delayMs = backoffDelayMs(unprocessedAttempt);
+                this.logger.warn('DynamoDB retrying unprocessed batch items', { operation: 'createMany', tableKey, itemCount: unprocessedItems.length, attempt: unprocessedAttempt + 1, delayMs });
+                await sleep(delayMs);
                 unprocessedAttempt += 1;
                 normalizedItems.push(...unprocessedItems
                     .map(item => item.PutRequest?.Item)
@@ -1781,6 +1757,7 @@ class DynamoDBService {
                 unprocessedAttempt = 0;
             }
         }
+        this.logger.debug('DynamoDB createMany completed', { tableKey, itemCount: result.numberOfItems });
         return result;
     }
     async update(tableKey, primaryKey, commands, condition = null, opts = {}, camelOrSnake = 'camel') {
@@ -1856,10 +1833,7 @@ class DynamoDBService {
             }
             ExpressionAttributeValues[attributeValueVariable] = value;
         });
-        this.logger.debug('Update Expression: %s', UpdateExpression);
-        this.logger.debug('Condition Expression: %s', ConditionExpression);
-        this.logger.debug('Expression Attribute Names: %o', ExpressionAttributeNames);
-        this.logger.debug('Expression Attribute Values: %o', ExpressionAttributeValues);
+        this.logger.debug('DynamoDB request started', { operation: 'update', tableKey });
         const updateCommand = new lib_dynamodb_1.UpdateCommand({
             TableName: table.name,
             Key: keys,
@@ -1893,29 +1867,17 @@ class DynamoDBService {
         catch (e) {
             const error = e;
             if (error.name === 'ValidationException') {
-                this.logger.error('The request parameters are invalid with error: %s', error.message, {
-                    tableKey,
-                    primaryKey,
-                    commands,
-                    condition,
-                    opts,
-                });
+                this.logger.error('The request parameters are invalid', { errorName: error.name, tableKey });
                 throw new DynamoDBError(400, {
                     message: 'Invalid request parameters',
                     cause: e,
                 });
             }
             else if (error.name === 'ConditionalCheckFailedException') {
-                this.logger.debug('Condition failed to update item %s', primaryKey.toString());
+                this.logger.debug('DynamoDB update skipped: condition not met', { tableKey });
             }
             else {
-                this.logger.error('Failed to update item with error: %s', error.message, {
-                    tableKey,
-                    primaryKey,
-                    commands,
-                    condition,
-                    opts,
-                });
+                this.logger.error('Failed to update item', { errorName: error.name, tableKey });
                 throw new DynamoDBError(500, {
                     message: 'Failed to update item',
                     cause: e,
@@ -1941,6 +1903,7 @@ class DynamoDBService {
                 result.item = newItem;
             }
         }
+        this.logger.debug('DynamoDB update completed', { tableKey, updatedOrCreated: result.updatedOrCreated });
         return result;
     }
     async deleteOne(tableKey, primaryKey, condition = null, opts = {}, camelOrSnake = 'camel') {
@@ -1976,6 +1939,7 @@ class DynamoDBService {
             }
             ConditionExpression = condition.expression;
         }
+        this.logger.debug('DynamoDB request started', { operation: 'deleteOne', tableKey });
         const deleteCommand = new lib_dynamodb_1.DeleteCommand({
             TableName: table.name,
             Key: keys,
@@ -2003,27 +1967,17 @@ class DynamoDBService {
         catch (e) {
             const error = e;
             if (error.name === 'ValidationException') {
-                this.logger.error('The request parameters are invalid with error: %s', error.message, {
-                    tableKey,
-                    primaryKey,
-                    condition,
-                    opts,
-                });
+                this.logger.error('The request parameters are invalid', { errorName: error.name, tableKey });
                 throw new DynamoDBError(400, {
                     message: 'Invalid request parameters',
                     cause: e,
                 });
             }
             else if (error.name === 'ConditionalCheckFailedException') {
-                this.logger.debug('Condition failed to delete item %s', primaryKey.toString());
+                this.logger.debug('DynamoDB delete skipped: condition not met', { tableKey });
             }
             else {
-                this.logger.error('Failed to delete item with error: %s', error.message, {
-                    tableKey,
-                    primaryKey,
-                    condition,
-                    opts,
-                });
+                this.logger.error('Failed to delete item', { errorName: error.name, tableKey });
                 throw new DynamoDBError(500, {
                     message: 'Failed to delete item',
                     cause: e,
@@ -2049,6 +2003,7 @@ class DynamoDBService {
                 result.item = newItem;
             }
         }
+        this.logger.debug('DynamoDB deleteOne completed', { tableKey, deleted: result.deleted });
         return result;
     }
     async deleteMany(tableKey, primaryKeys, opts = {}) {
@@ -2073,6 +2028,7 @@ class DynamoDBService {
         let unprocessedAttempt = 0;
         while (keys.length > 0) {
             const batch = keys.splice(0, 25);
+            this.logger.debug('DynamoDB batch request started', { operation: 'deleteMany', tableKey, itemCount: batch.length });
             const batchWriteCommand = new lib_dynamodb_1.BatchWriteCommand({
                 RequestItems: {
                     [table.name]: batch.map(key => ({
@@ -2086,11 +2042,7 @@ class DynamoDBService {
             const { UnprocessedItems } = await this.ddbDocClient
                 .send(batchWriteCommand)
                 .catch((e) => {
-                this.logger.error('Failed to delete items with error: %s', e.message, {
-                    tableKey,
-                    keys: batch,
-                    opts,
-                });
+                this.logger.error('Failed to delete items', { errorName: e.name, tableKey });
                 throw new DynamoDBError(500, {
                     message: 'Failed to delete items',
                     cause: e,
@@ -2099,12 +2051,15 @@ class DynamoDBService {
             const unprocessedItems = UnprocessedItems?.[table.name];
             if (unprocessedItems !== undefined && unprocessedItems.length > 0) {
                 if (unprocessedAttempt >= MAX_UNPROCESSED_ATTEMPTS) {
+                    this.logger.error('DynamoDB batch retry limit reached', { operation: 'deleteMany', tableKey, retryCount: unprocessedAttempt });
                     throw new DynamoDBError(500, {
                         message: 'Failed to delete items after multiple attempts',
                         cause: new Error('Too many unprocessed items'),
                     });
                 }
-                await sleep(backoffDelayMs(unprocessedAttempt));
+                const delayMs = backoffDelayMs(unprocessedAttempt);
+                this.logger.warn('DynamoDB retrying unprocessed batch items', { operation: 'deleteMany', tableKey, itemCount: unprocessedItems.length, attempt: unprocessedAttempt + 1, delayMs });
+                await sleep(delayMs);
                 unprocessedAttempt += 1;
                 keys.push(...unprocessedItems
                     .map(item => item.DeleteRequest?.Key)
@@ -2114,6 +2069,7 @@ class DynamoDBService {
                 unprocessedAttempt = 0;
             }
         }
+        this.logger.debug('DynamoDB deleteMany completed', { tableKey, itemCount: result.numberOfItems });
         return result;
     }
     transaction(opts) {