{"id":21153892,"url":"https://github.com/dolsem/dynamoose-plugin-optimistic-locking","last_synced_at":"2025-04-13T12:07:29.120Z","repository":{"id":35029278,"uuid":"198322041","full_name":"dolsem/dynamoose-plugin-optimistic-locking","owner":"dolsem","description":null,"archived":false,"fork":false,"pushed_at":"2023-01-04T05:06:49.000Z","size":2521,"stargazers_count":2,"open_issues_count":17,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T12:07:19.272Z","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/dolsem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-23T00:36:01.000Z","updated_at":"2020-10-16T02:34:49.000Z","dependencies_parsed_at":"2023-01-15T12:21:20.208Z","dependency_job_id":null,"html_url":"https://github.com/dolsem/dynamoose-plugin-optimistic-locking","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolsem%2Fdynamoose-plugin-optimistic-locking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolsem%2Fdynamoose-plugin-optimistic-locking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolsem%2Fdynamoose-plugin-optimistic-locking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolsem%2Fdynamoose-plugin-optimistic-locking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dolsem","download_url":"https://codeload.github.com/dolsem/dynamoose-plugin-optimistic-locking/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248710433,"owners_count":21149190,"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-20T11:00:19.664Z","updated_at":"2025-04-13T12:07:29.092Z","avatar_url":"https://github.com/dolsem.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dynamoose Plugin - Optimistic Locking\n\n[![NPM Version][npm-image]][npm-url]\n[![NPM Downloads][downloads-image]][downloads-url]\n[![Build Status][travis-image]][travis-url]\n[![Coverage Status][coverage-image]][coverage-url]\n[![License: MIT][license-image]][license-url]\n\nDynamoose is a modeling tool for Amazon's DynamoDB ([https://github.com/dynamoosejs/dynamoose](https://github.com/dynamoosejs/dynamoose)).\nOptimistic Locking is a technique that protects data integrity in a concurrent enviroment, ensuring multiple write operations on the same data do not overwrite each other (by default last operation wins)\n\n\n## Getting Started\n\n### Installation\n\n    $ npm i dynamoose-plugin-optimistic-locking\n\n### Example\n\n```js\nconst {\n  OptimisticLockingPlugin,\n  OptimisticLockException,\n} = require('dynamoose-plugin-optimistic-locking');\n\nconst BookCollectionSchema = new dynamoose.Schema({\n  author: {\n    type: String,\n    hashKey: true,\n  },\n  books: [String],\n  derivedWorks: [String],\n});\nconst BookCollection = dynamo.model(\"BookCollection\", BookCollectionSchema)\nBookCollection.plugin(OptimisticLockingPlugin, { fetchItemOnWriteError: true });\n\nconst asoiaf = await BookCollection.create({\n  author: 'George R. R. Martin',\n  books: ['A Game of Thrones', 'A Clash of Kings', 'A Storm of Swords'],\n  derivedWorks: ['Game of Thrones (TV Series)'],\n});\nasoiaf.getVersion(); // Returns 1.\n...\nlet updatedCollection;\nwhile (!updatedCollection) {\n  asoiaf.push('A Feast For Crows');\n  try {\n    updatedCollection = await BookCollection.put(asoiaf);\n  } catch (err) {\n    if (!(err instanceof OptimisticLockException)) throw err;\n    asoiaf = err.itemInDb;\n  }\n}\n```\n\n## API\n\n### Plugin Options\n\n```js\nBookCollection.plugin(OptimisticLockingPlugin, {/* Plugin Options */});\n```\n\n**fetchItemOnWriteError**: boolean (default: `false`)\n\nIf set to `true`, Optimistic Locking Plugin will perform a database read automatically if conditional update fails. If the version of the item in the database is newer than the one being saved, it will throw an instance of `OptimisticLockException`. The item from the database is stored as `itemInDb` property on the exception object. If set to `false`, the original `ConditionalCheckFailedException` is thrown, and there is no guarantee that optimistic locking is the cause of the received exception. Setting to `true` is recommended to get the most out of the plugin.\n\n**attributeName**: string (default: `'__version'`)\n\nDynamoDB attribute name for storing version number.\n\n**attributeSymbol**: symbol\n\nCan be used to override default symbol for accessing version prop on an item. Using `getVersion()` and `setVersion()` methods is recommended instead.\n\n### Static methods\n\n**Model.putNextVersion(item, updateFunction[, options])**\nSends put request in a loop fetching newest item version every iteration, until request succeeds or max attempts reached (if specified). Requires `fetchItemOnWriteError` plugin option to be set to `true`.\n```js\nBookCollection.plugin(OptimisticLockingPlugin, { fetchItemOnWriteError: true });\n\nconst updatedAsoiaf = await BookCollection.putNextVersion(\n  asoiaf,\n  (item) =\u003e { item.derivedWorks.push('Game of Thrones: A Telltale Games Series'); },\n  { maxAttempts: 3 }\n);\n```\n| Parameter Name | Type | Description | |\n| ---- | ---- | ----------- | -------- |\n| item | `object` | item to update and save to the database | required |\n| updateFunction | `function`  | applies updates to the item, will be called every iteration | required |\n| options | `object`  | extra options | \u0026nbsp; |\n| options.maxAttempts | `number`  | by default operation will run until the item is saved, but will fail after max attempts have been reached if this option is specified | \u0026nbsp; |\n\n### Instance methods\n\n**item.getVersion()**\nReturns current item version\n```js\nasoiaf.getVersion();\n```\n\n**item.setVersion(number)**\nOverwrites item version with custom value. Note that this value will be incremented before the item is saved.\n\n## Roadmap\n\n- Better TypeScript support\n- Provide option to disable optimistic locking for invidual put/batchPut/update calls\n\n## License\n\nMIT\n\n[npm-image]: https://img.shields.io/npm/v/dynamoose-plugin-optimistic-locking.svg\n[npm-url]: https://npmjs.org/package/dynamoose-plugin-optimistic-locking\n[downloads-image]: https://img.shields.io/npm/dm/dynamoose-plugin-optimistic-locking.svg\n[downloads-url]: https://npmjs.org/package/dynamoose-plugin-optimistic-locking\n[travis-image]: https://travis-ci.org/dolsem/dynamoose-plugin-optimistic-locking.svg?branch=master\n[travis-url]: https://travis-ci.org/dolsem/dynamoose-plugin-optimistic-locking\n[coverage-image]: https://coveralls.io/repos/github/dolsem/dynamoose-plugin-optimistic-locking/badge.svg?branch=master\n[coverage-url]: https://coveralls.io/github/dolsem/dynamoose-plugin-optimistic-locking?branch=master\n[license-image]: https://img.shields.io/badge/License-MIT-blue.svg\n[license-url]: https://opensource.org/licenses/MIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdolsem%2Fdynamoose-plugin-optimistic-locking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdolsem%2Fdynamoose-plugin-optimistic-locking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdolsem%2Fdynamoose-plugin-optimistic-locking/lists"}