{"id":18374554,"url":"https://github.com/jupiterone/dynamodb-dao","last_synced_at":"2025-04-06T19:32:42.100Z","repository":{"id":38442661,"uuid":"268776280","full_name":"JupiterOne/dynamodb-dao","owner":"JupiterOne","description":"Creating, querying, updating, and deleting from a DynamoDB table.","archived":false,"fork":false,"pushed_at":"2024-07-02T16:04:42.000Z","size":722,"stargazers_count":3,"open_issues_count":2,"forks_count":2,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-03-22T06:12:52.182Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JupiterOne.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-02T10:56:25.000Z","updated_at":"2024-07-02T16:04:44.000Z","dependencies_parsed_at":"2024-05-15T15:54:57.642Z","dependency_job_id":"33f158e3-47d6-409b-9002-59780aabfded","html_url":"https://github.com/JupiterOne/dynamodb-dao","commit_stats":{"total_commits":80,"total_committers":11,"mean_commits":"7.2727272727272725","dds":0.625,"last_synced_commit":"cd256ec52e3f368a2c86d8ff90cb76142a2afcb6"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fdynamodb-dao","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fdynamodb-dao/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fdynamodb-dao/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fdynamodb-dao/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JupiterOne","download_url":"https://codeload.github.com/JupiterOne/dynamodb-dao/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247539519,"owners_count":20955319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T00:15:02.967Z","updated_at":"2025-04-06T19:32:41.438Z","avatar_url":"https://github.com/JupiterOne.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dynamodb-dao\n\nThis project contains code for a `DynamoDbDao` class that can be used for\ncreating, querying, updating, and deleting from DynamoDB table. Unlike tools\nlike `dynamoose`, `DynamoDbDao` is a lower level wrapper and aims not to\nabstract away too many of the DynamoDB implementation details.\n\nAlso, this module leverages TypeScript type declarations so that, when possible,\nmethods arguments and return values are strictly typed.\n\n## Examples\n\n**Constructor:**\n\n```javascript\nimport { DynamoDBClient } from '@aws-sdk/client-dynamodb';\nimport { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';\n\nconst ddb = new DynamoDBClient({\n  apiVersion: '2012-08-10'\n})\n\nconst documentClient = DynamoDBDocumentClient.from(ddb, {\n  marshallOptions: {\n    removeUndefinedValues: true\n  }\n});\n\n// The type declaration of for the documents that we are storing\ninterface MyDocument {\n  id: string;\n  accountId: string;\n  name: string;\n  total?: number;\n}\n\n// Key schema should have one or two properties which correspond to\n// hash key and range key.\n//\n// NOTE: a range key is optional and depends\n// on how your DynamoDB table is configured.\ninterface MyDocumentKeySchema {\n  // hash key\n  accountId: string;\n\n  // range key\n  id: string;\n}\n\nconst myDocumentDao = new DynamoDbDao\u003cMyDocument, MyDocumentKeySchema\u003e({\n  tableName: 'my-documents',\n  documentClient\n});\n```\n\n**Get query:**\n\n```javascript\nconst myDocument = await myDocumentDao.get({ id, accountId });\n```\n\n**Paginated query:**\n\n```javascript\nconst { items, lastKey } = await myDocumentDao.query({\n  index: 'NameIndex',\n  keyConditionExpression: 'accountId = :accountId',\n  startAt: cursor /* `cursor` is a previously returned `lastKey` */,\n  scanIndexForward: true,\n  attributeValues: {\n    ':accountId': accountId,\n  },\n});\n```\n\n**Count query:**\n\n```javascript\nconst count = await myDocumentDao.count({\n  index: 'NameIndex',\n  keyConditionExpression: 'accountId = :accountId',\n  attributeValues: {\n    ':accountId': input.accountId,\n  },\n});\n```\n\n**Put:**\n\n```javascript\nawait myDocumentDao.put({\n  id: 'something',\n  accountId: 'abc'\n  name: 'blah'\n});\n```\n\n**Delete:**\n\n```javascript\nawait myDocumentDao.delete({ id, accountId });\n```\n\n**Incrementing/Decrementing**\n\nNOTE: This should only be used where overcounting and undercounting can be\ntolerated. See\n[the DynamoDB atomic counter documentation](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.AtomicCounters)\nfor more information.\n\nIf a property does not already exist, the initial value is assigned `0` and\nincremented/decremented from `0`.\n\n```ts\n// `total` will have the value `5`\nconst { total } = await myDocumentDao.incr(\n  // The key\n  {\n    id: 'abc',\n    accountId: 'def',\n  },\n  // The `number` property to increment\n  'total',\n  // The number to increment by. Defaults to 1.\n  5\n);\n\n// `total` will have the value `-5`\nconst { total } = await myDocumentDao.decr(\n  // The key\n  {\n    id: '123',\n    accountId: 'def',\n  },\n  // The `number` property to increment\n  'total',\n  // The number to decrement by. Defaults to 1.\n  5\n);\n```\n\nWhen multiple values must be incremented and/or decremented in the same call:\n\n```ts\n// `total` will have the value `5` and `extra` will have the value -1.\nconst { extra, total } = await myDocumentDao.multiIncr(\n  {\n    id: 'abc',\n    accountId: 'def',\n  },\n  {\n    total: 5,\n    extra: -1,\n  }\n);\n```\n\n**Optimistic Locking with Version Numbers**\n\nFor callers who wish to enable an optimistic locking strategy there are two\navailable toggles:\n\n1. Provide the attribute you wish to be used to store the version number. This\n   will enable optimistic locking on the following operations: `put`, `update`,\n   and `delete`.\n\n   Writes for documents that do not have a version number attribute will\n   initialize the version number to 1. All subsequent writes will need to\n   provide the current version number. If an out-of-date version number is\n   supplied, an error will be thrown.\n\n   Example of Dao constructed with optimistic locking enabled.\n\n   ```typescript\n   const dao = new DynamoDbDao\u003cDataModel, KeySchema\u003e({\n     tableName,\n     documentClient,\n     {\n        optimisticLockingAttribute: 'version',\n        // If true, the first put or update will create and initialize\n        // the 'version' attribute, otherwise it will not create it\n        // This allows adopters to choose to adopt at the item level\n        // or at the dao level\n        autoInitiateLockingAttribute: true, // default: true\n     }\n   });\n   ```\n\n2. If you wish to ignore optimistic locking for a save operation, specify\n   `ignoreOptimisticLocking: true` in the options on your `put`, `update`, or\n   `delete`.\n\nNOTE: Optimistic locking is NOT supported for `batchWrite` or `batchPut`\noperations. Consuming those APIs for data models that do have optimistic locking\nenabled may clobber your version data and could produce undesirable effects for\nother callers.\n\nThis was modeled after the\n[Java Dynamo client](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.OptimisticLocking.html)\nimplementation.\n\n## Developing\n\nThe test setup requires that [docker-compose]() be installed. To run the tests,\nfirst open one terminal and start the local DynamoDB docker container by\nrunning:\n\n```\nyarn start:containers\n```\n\nIn a second terminal run:\n\n```\nyarn test\n```\n\nTo stop containers:\n\n```\nyarn stop:containers\n```\n\n## Releasing\n\nOnce you are ready to publish a new version, make sure all of your changes have\nbeen pushed and merged to the remote repository.\n\nNext, create a new branch and run the following command:\n\n```\nnpm version minor (or major or patch)\n```\n\nThis will add a commit with an updated `package.json`, and create a new tag\nlocally.\n\nThen, push your branch and new tag to the remote.\n\n```\ngit push \u0026\u0026 git push --tags\n```\n\nCreate a pull request with the branch. Once that is merged, your new version\nwill be published.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupiterone%2Fdynamodb-dao","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjupiterone%2Fdynamodb-dao","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupiterone%2Fdynamodb-dao/lists"}