{"_id":"@bm8/aws-dynamodb-streams","_rev":"2-66a27a6dfdf279a1951de3f2dbcdefea","name":"@bm8/aws-dynamodb-streams","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@bm8/aws-dynamodb-streams","version":"0.0.1","author":{"name":"Paul Carter"},"license":"MIT","_id":"@bm8/aws-dynamodb-streams@0.0.1","maintainers":[{"name":"bewdym8","email":"bewdym85176@gmail.com"}],"homepage":"https://github.com/pgcarter/aws-utils#readme","bugs":{"url":"https://github.com/pgcarter/aws-utils/issues"},"dist":{"shasum":"5c6ff7e222eed9c85f3719e4ca79111440a89e4d","tarball":"https://registry.npmjs.org/@bm8/aws-dynamodb-streams/-/aws-dynamodb-streams-0.0.1.tgz","fileCount":5,"integrity":"sha512-y6uQ+8F0iCVaqyo0Lne8acS3fzm3l0m7DI+Cvo5nC19Ctrk+v9OFn5H5ndwhxhs0TiK2UsiN+i17J8AR3bJAVQ==","signatures":[{"sig":"MEYCIQDcdxA4lxiiUjzGC/dSdnVTPsRiIWZRVsWIibMM9ORlXgIhAPjJngkxWkULZNDi9Dm7aiq3PzG8HXSecGGFQy4N2vF2","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27525},"main":"./dist/index.js","type":"module","_from":"file:bm8-aws-dynamodb-streams-0.0.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist *.tsbuildinfo","typecheck":"tsc --noEmit && pnpm typecheck:tests","typecheck:tests":"tsc --noEmit -p tsconfig.test.json"},"_npmUser":{"name":"bewdym8","email":"bewdym85176@gmail.com"},"_resolved":"/private/var/folders/5v/_kwm0fcx53l5447mf1l54sp80000gn/T/c7b74db129a7fa91456950621bcec961/bm8-aws-dynamodb-streams-0.0.1.tgz","_integrity":"sha512-y6uQ+8F0iCVaqyo0Lne8acS3fzm3l0m7DI+Cvo5nC19Ctrk+v9OFn5H5ndwhxhs0TiK2UsiN+i17J8AR3bJAVQ==","repository":{"url":"git+https://github.com/pgcarter/aws-utils.git","type":"git","directory":"packages/aws-dynamodb-streams"},"_npmVersion":"11.9.0","description":"A typed DynamoDB Streams record processor for entities defined with [`@bm8/aws-dynamodb`](../aws-dynamodb). Register handlers per `(eventName, entityName)`; the processor unmarshalls images, dispatches to the right handler with a typed entity, preserves p","directories":{},"_nodeVersion":"24.14.0","dependencies":{"@bm8/aws-dynamodb":"0.0.1","@aws-sdk/util-dynamodb":"^3.693.0","@aws-sdk/client-dynamodb-streams":"^3.693.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"@types/aws-lambda":"^8.10.161"},"peerDependencies":{"@types/aws-lambda":"^8.10.0"},"peerDependenciesMeta":{"@types/aws-lambda":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/aws-dynamodb-streams_0.0.1_1779523555475_0.9601108508975167","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@bm8/aws-dynamodb-streams","version":"0.1.0","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"@aws-sdk/client-dynamodb-streams":"^3.693.0","@aws-sdk/util-dynamodb":"^3.693.0","@bm8/aws-dynamodb":"0.1.0"},"peerDependencies":{"@types/aws-lambda":"^8.10.0"},"peerDependenciesMeta":{"@types/aws-lambda":{"optional":true}},"devDependencies":{"@types/aws-lambda":"^8.10.161"},"publishConfig":{"access":"public","provenance":true},"repository":{"type":"git","url":"git+https://github.com/pgcarter/aws-utils.git","directory":"packages/aws-dynamodb-streams"},"license":"MIT","author":{"name":"Paul Carter"},"scripts":{"build":"tsup","test":"vitest run","typecheck":"tsc --noEmit && pnpm typecheck:tests","typecheck:tests":"tsc --noEmit -p tsconfig.test.json","clean":"rm -rf dist *.tsbuildinfo"},"_id":"@bm8/aws-dynamodb-streams@0.1.0","description":"A typed DynamoDB Streams record processor for entities defined with [`@bm8/aws-dynamodb`](../aws-dynamodb). Register handlers per `(eventName, entityName)`; the processor unmarshalls images, dispatches to the right handler with a typed entity, preserves p","bugs":{"url":"https://github.com/pgcarter/aws-utils/issues"},"homepage":"https://github.com/pgcarter/aws-utils#readme","_integrity":"sha512-6AhnPa8AUZCXQ6z4QR82h/l+31ZBcyxvO02tnUfYeJoiebUbe0Dv11fBltK9JYXp0R3DvPqEDweowmpDhA2ryg==","_resolved":"/tmp/f9f437f43eca7478c4d1955c91623405/bm8-aws-dynamodb-streams-0.1.0.tgz","_from":"file:bm8-aws-dynamodb-streams-0.1.0.tgz","_nodeVersion":"24.16.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-6AhnPa8AUZCXQ6z4QR82h/l+31ZBcyxvO02tnUfYeJoiebUbe0Dv11fBltK9JYXp0R3DvPqEDweowmpDhA2ryg==","shasum":"904661828b31edc27e1fb54f5ff99a36fa19c1a1","tarball":"https://registry.npmjs.org/@bm8/aws-dynamodb-streams/-/aws-dynamodb-streams-0.1.0.tgz","fileCount":5,"unpackedSize":27525,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bm8%2faws-dynamodb-streams@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICug5nlLusjn1hu7tHSVQxHjTNTExboVf2AeLc1JrN5MAiEA1U7t85N2qYkqBwvHhFgu/js3KUz9U+p+EKQhqs7EbYo="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:81f17764-60bb-4768-b3ec-685a47f47c84"}},"directories":{},"maintainers":[{"name":"bewdym8","email":"bewdym85176@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aws-dynamodb-streams_0.1.0_1780111550750_0.14743687149473672"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-23T08:05:55.264Z","modified":"2026-05-30T03:25:51.530Z","0.0.1":"2026-05-23T08:05:55.651Z","0.1.0":"2026-05-30T03:25:50.895Z"},"bugs":{"url":"https://github.com/pgcarter/aws-utils/issues"},"author":{"name":"Paul Carter"},"license":"MIT","homepage":"https://github.com/pgcarter/aws-utils#readme","repository":{"type":"git","url":"git+https://github.com/pgcarter/aws-utils.git","directory":"packages/aws-dynamodb-streams"},"description":"A typed DynamoDB Streams record processor for entities defined with [`@bm8/aws-dynamodb`](../aws-dynamodb). Register handlers per `(eventName, entityName)`; the processor unmarshalls images, dispatches to the right handler with a typed entity, preserves p","maintainers":[{"name":"bewdym8","email":"bewdym85176@gmail.com"}],"readme":"# @bm8/aws-dynamodb-streams\n\nA typed DynamoDB Streams record processor for entities defined with [`@bm8/aws-dynamodb`](../aws-dynamodb). Register handlers per `(eventName, entityName)`; the processor unmarshalls images, dispatches to the right handler with a typed entity, preserves per-shard ordering, and reports per-record failures via `batchItemFailures`.\n\n## Install\n\n```sh\npnpm add @bm8/aws-dynamodb-streams\n```\n\n## Quickstart\n\n```ts\nimport { createStreamProcessor } from '@bm8/aws-dynamodb-streams';\nimport { entities } from './entities'; // same map you pass to createDynamoClient\n\nconst processor = createStreamProcessor({ entities })\n  .on('INSERT', 'user', async ({ entity, key, eventID }) => {\n    // entity is fully typed against the user EntityDefinition\n  })\n  .on('MODIFY', 'user', async ({ oldEntity, newEntity }) => {})\n  .on('REMOVE', 'user', async ({ entity }) => {});\n\n// Share one handler across events — arg is typed as the union of per-event args.\ncreateStreamProcessor({ entities }).on(['INSERT', 'MODIFY'], 'user', async (arg) => {\n  if ('oldEntity' in arg) {\n    /* MODIFY */\n  } else {\n    /* INSERT */\n  }\n});\n\n// Pass the records straight off your stream batch.\nconst { batchItemFailures } = await processor.process(records);\n```\n\n## Lambda\n\nWrap a processor with `toLambdaHandler` to get a Lambda-shaped function. Configure your event source mapping with `ReportBatchItemFailures` so DynamoDB Streams retries only the failed records.\n\n```ts\nimport { createStreamProcessor, toLambdaHandler } from '@bm8/aws-dynamodb-streams';\nimport { entities } from './entities';\n\nconst processor = createStreamProcessor({ entities }).on(\n  'INSERT',\n  'user',\n  async ({ entity }) => {},\n);\n\nexport const handler = toLambdaHandler(processor);\n```\n\nThe adapter is the only place this package touches Lambda types — install `@types/aws-lambda` if you use it; non-Lambda consumers can skip it (it's an optional peer dependency).\n\n## Required table configuration\n\nThe processor assumes the table's stream is configured with `StreamViewType: NEW_AND_OLD_IMAGES`. Any other view type causes `.process()` to throw with a directly actionable message — `INSERT` needs `NewImage`, `REMOVE` needs `OldImage`, and `MODIFY` needs both.\n\n## Delivery semantics and idempotency\n\nDynamoDB Streams is **at-least-once**: a given record can be delivered to your handler more than once (after a Lambda retry, a shard re-read, etc.). This package does not deduplicate. Handlers must be idempotent — for example, by writing with conditional expressions, by upserting on a stable key derived from the record, or by gating on a downstream version number.\n\n## Error contract\n\n| Situation                                               | Behavior                                                                 |\n| ------------------------------------------------------- | ------------------------------------------------------------------------ |\n| Record has no `type` attribute                          | Silently skipped (treated as a legacy or non-entity row).                |\n| Record's `type` is not in the `entities` map            | `.process()` throws — treated as deploy skew, retry will not help.       |\n| Required image is missing (wrong `StreamViewType`)      | `.process()` throws with a `NEW_AND_OLD_IMAGES` hint.                    |\n| Duplicate `.on(event, entityName, ...)` registration    | Throws synchronously at registration time, naming the conflicting cell.  |\n| `(event, entityName)` has no registered handler         | Silently skipped — opt into the events you care about.                   |\n| Handler rejects                                         | Recorded in `batchItemFailures` by `SequenceNumber`; remainder continues.|\n\nWhen a handler rejects, return the result from your Lambda configured with `ReportBatchItemFailures` so DynamoDB Streams retries only the failed records.\n\n## See also\n\n- [`@bm8/aws-dynamodb`](../aws-dynamodb) — the source of `EntityDefinition` and the shared `entities` map.\n","readmeFilename":"README.md"}