@jzhuo3/dynamodb-lib 0.1.0 → 0.1.1

package/doc/service.md

@@ -192,3 +192,39 @@ db.destroy();
 ```
 
 In Lambda, keep the service outside the handler and reuse it across invocations. Calling `destroy` at the end of every handler invocation prevents connection reuse.
+
+## Logging
+
+Pass a logger implementing `debug(message, ...meta)`, `warn(message, ...meta)`, and `error(message, ...meta)`. Logging is silent when no logger is supplied. Messages use a readable string followed by a structured metadata object; Winston does not need interpolation formatting to display them.
+
+- **Debug:** individual requests and their outcomes, batch sizes and completion counts, query pages and whether more pages exist, transaction start/completion, and expected conditional write skips. Batch read completion counts exclude missing and expired items; query page counts describe the DynamoDB response before local TTL filtering.
+- **Warn:** retrying unprocessed batch items or transaction conflicts, including attempt and delay in milliseconds; LSI projections that may incur additional reads.
+- **Error:** failed requests, invalid GSI projections, and exhausted batch or transaction retries. SDK errors retain their original cause for the caller; logs include the error name instead of the raw error message.
+
+Logs omit primary key values, item contents, expression text and bindings, cursors, credentials, and raw request options. Metadata can include your configured table alias (`tableKey`) and index names, so choose aliases appropriate for your logging environment. Expected missing/expired records and unmet write conditions are not warnings.
+
+For example, an unprocessed batch produces:
+
+```ts
+logger.warn('DynamoDB retrying unprocessed batch items', {
+  operation: 'getMany',
+  tableKey: 'items',
+  itemCount: 2,
+  attempt: 1,
+  delayMs: 50, // Actual delay includes backoff jitter.
+});
+```
+
+Retry warnings describe retries performed by this library, not retries internal to the AWS SDK. Debug messages are diagnostic output, not a stable audit-event API.
+
+### Testing with Winston
+
+The integration suite injects a real Winston logger with a JSON console transport. Winston is a development dependency only; consumers still choose their own logger. Debug output is enabled by default so you can see requests, pagination, and outcomes while testing:
+
+```sh
+npm run test:integration
+npm run test:integration -- --log-level warn
+DYNAMODB_TEST_LOG_LEVEL=error npm run test:integration
+```
+
+`--log-level` overrides `DYNAMODB_TEST_LOG_LEVEL`. Supported levels are Winston's standard npm levels: `error`, `warn`, `info`, `http`, `verbose`, `debug`, and `silly`. The unit suite also sends library events through a real Winston JSON stream transport and checks debug/warn/error metadata and payload omission; other unit tests retain spies for precise assertions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jzhuo3/dynamodb-lib",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-independent DynamoDB document service and expression builders",
   "license": "MIT",
   "author": "jzhuo3",
@@ -55,7 +55,8 @@
     "@types/node": "^22.19.0",
     "@vitest/coverage-v8": "4.1.11",
     "typescript": "~5.9.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.11",
+    "winston": "3.19.0"
   },
   "overrides": {
     "fast-xml-parser": "5.7.1",
@@ -73,4 +74,4 @@
   "bugs": {
     "url": "https://github.com/maczhuo/dynamodb-lib/issues"
   }
-}
+}