{"_id":"@conveyant/promise-transactions","_rev":"6-de41555503799cfa30f710e3cea08d96","name":"@conveyant/promise-transactions","description":"Transactions engine for Promise-based asynchronous operations","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@conveyant/promise-transactions","version":"0.1.0","description":"Transactions engine for Promise-based asynchronous operations","main":"dist/index.js","files":["dist/index.js","dist/index.d.ts"],"scripts":{"test":"jasmine-ts spec/**/*.spec.ts","build":"tsc","prepare":"tsc"},"repository":{"type":"git","url":"git+https://github.com/Conveyant/promise-transactions.git"},"keywords":["transaction","promise","rollback"],"author":{"name":"Ben Callaghan"},"license":"MIT","bugs":{"url":"https://github.com/Conveyant/promise-transactions/issues"},"homepage":"https://github.com/Conveyant/promise-transactions#readme","devDependencies":{"@types/jasmine":"^2.8.6","jasmine-ts":"^0.2.1","typescript":"^2.7.1"},"gitHead":"3ad15045c9fa42b14fa9408dc5e57cca19531b37","_id":"@conveyant/promise-transactions@0.1.0","_shasum":"0e304d421b2a341311a246b9dab57b1358e1478e","_from":".","_npmVersion":"3.10.10","_nodeVersion":"6.11.4","_npmUser":{"name":"bcallaghan","email":"bcallaghan@conveyant.com"},"dist":{"shasum":"0e304d421b2a341311a246b9dab57b1358e1478e","tarball":"https://registry.npmjs.org/@conveyant/promise-transactions/-/promise-transactions-0.1.0.tgz","integrity":"sha512-S99xyQIJf4HpN3TxbsD+1dOh+j6hUDVZtvOcO8QO3CNlN6k2J3OwhJm4H7z2Vc/A5zs1R2CxbUdRBRd0f+8JLA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICSAp8YuIgArapFpzMrWCiJoyfrfg7BYUVO5p46EDn+MAiApEg05bejW2dS+Kqx5did4XG32cmW+/O5HSAj3/9lvOA=="}]},"maintainers":[{"name":"bcallaghan","email":"bcallaghan@conveyant.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/promise-transactions-0.1.0.tgz_1517890485002_0.698186322581023"},"directories":{}},"0.1.1":{"name":"@conveyant/promise-transactions","version":"0.1.1","description":"Transactions engine for Promise-based asynchronous operations","main":"dist/index.js","files":["dist/index.js","dist/index.d.ts"],"scripts":{"test":"jasmine-ts spec/**/*.spec.ts","build":"tsc","prepare":"tsc"},"repository":{"type":"git","url":"git+https://github.com/Conveyant/promise-transactions.git"},"keywords":["transaction","promise","rollback"],"author":{"name":"Ben Callaghan"},"license":"MIT","bugs":{"url":"https://github.com/Conveyant/promise-transactions/issues"},"homepage":"https://github.com/Conveyant/promise-transactions#readme","devDependencies":{"@types/jasmine":"^2.8.6","jasmine-ts":"^0.2.1","typescript":"^2.7.1"},"gitHead":"45bd476b3da43006c7813e5594e58a03e683944f","_id":"@conveyant/promise-transactions@0.1.1","_shasum":"3256c7e9451852789ee26cd0eb9dcecb9cf6dd1d","_from":".","_npmVersion":"3.10.10","_nodeVersion":"6.11.4","_npmUser":{"name":"bcallaghan","email":"bcallaghan@conveyant.com"},"dist":{"shasum":"3256c7e9451852789ee26cd0eb9dcecb9cf6dd1d","tarball":"https://registry.npmjs.org/@conveyant/promise-transactions/-/promise-transactions-0.1.1.tgz","integrity":"sha512-QUflY30oxL+6P68HU9o6B86PjTAo/uVt+DGm4dt2Dow2kvC5X4q/yu9xA12an84Q6ySqBmohVTlicXZFHY+GUA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCx67RB/eOLQCtHRB/V4c55zw/j3gS3S8MjMPOgh99ojwIgaP5PmI9bxHfDnZY2hOi6TBng6EsGB+dwYSHb1G6SA0g="}]},"maintainers":[{"name":"bcallaghan","email":"bcallaghan@conveyant.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/promise-transactions-0.1.1.tgz_1517890580450_0.5477005424909294"},"directories":{}},"0.2.0":{"name":"@conveyant/promise-transactions","version":"0.2.0","description":"Transactions engine for Promise-based asynchronous operations","main":"dist/index.js","files":["dist/index.js","dist/index.d.ts"],"scripts":{"test":"jasmine-ts spec/**/*.spec.ts","build":"tsc --inlineSources false -p .","prepare":"npm run build"},"repository":{"type":"git","url":"git+https://github.com/Conveyant/promise-transactions.git"},"keywords":["transaction","promise","rollback"],"author":{"name":"Ben Callaghan"},"license":"MIT","bugs":{"url":"https://github.com/Conveyant/promise-transactions/issues"},"homepage":"https://github.com/Conveyant/promise-transactions#readme","devDependencies":{"@types/jasmine":"^2.8.6","jasmine-ts":"^0.2.1","typescript":"^2.7.1"},"gitHead":"743a7d2063df9b3b334e0ac40defe5d31fa66f66","_id":"@conveyant/promise-transactions@0.2.0","_shasum":"2614e17e8215f312418af96dc5a2d41a0ab11ef8","_from":".","_npmVersion":"3.10.10","_nodeVersion":"6.11.4","_npmUser":{"name":"bcallaghan","email":"bcallaghan@conveyant.com"},"dist":{"shasum":"2614e17e8215f312418af96dc5a2d41a0ab11ef8","tarball":"https://registry.npmjs.org/@conveyant/promise-transactions/-/promise-transactions-0.2.0.tgz","fileCount":5,"unpackedSize":8056,"integrity":"sha512-cpywP4RjvIw4dZ++Alv5EiL2NAOwLDOmnRiC4M9GS9VyF3E8OjuGaT0K2EJ+v7eqBwDIn8td8P5/cK/fFucJqw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDXBXd1pu83vjO1whYaJMs8t3EhqSPOMLjzIlxBGM4L4AIhAKD8lZc4KHB1ZygaBvRbw/aU/f4SfSml5uET5zWx3jjK"}]},"maintainers":[{"name":"bcallaghan","email":"bcallaghan@conveyant.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/promise-transactions_0.2.0_1518301793114_0.4176526263513263"},"_hasShrinkwrap":false},"0.2.1":{"name":"@conveyant/promise-transactions","version":"0.2.1","description":"Transactions engine for Promise-based asynchronous operations","main":"dist/index.js","files":["dist/*.js","dist/*.d.ts"],"scripts":{"test":"jasmine-ts spec/**/*.spec.ts","build":"tsc --inlineSources false -p .","prepare":"npm run build"},"repository":{"type":"git","url":"git+https://github.com/Conveyant/promise-transactions.git"},"keywords":["transaction","promise","rollback"],"author":{"name":"Ben Callaghan"},"license":"MIT","bugs":{"url":"https://github.com/Conveyant/promise-transactions/issues"},"homepage":"https://github.com/Conveyant/promise-transactions#readme","devDependencies":{"@types/jasmine":"^2.8.6","jasmine-ts":"^0.2.1","typescript":"^2.7.1"},"gitHead":"75d5f3d3e4d190368f55c049754f981c3d760b1a","_id":"@conveyant/promise-transactions@0.2.1","_shasum":"398cfe51d0216d0b2416bbf2a3e266bc0d6203c5","_from":".","_npmVersion":"3.10.10","_nodeVersion":"6.11.4","_npmUser":{"name":"bcallaghan","email":"bcallaghan@conveyant.com"},"dist":{"shasum":"398cfe51d0216d0b2416bbf2a3e266bc0d6203c5","tarball":"https://registry.npmjs.org/@conveyant/promise-transactions/-/promise-transactions-0.2.1.tgz","fileCount":11,"unpackedSize":26383,"integrity":"sha512-d89btH49Ub09YBkelstsl86hwU7KhX5obf4wI/UMyAJfOSxSvc6qh2m37jxWgz786ZJju8SGnw5ZwmeJJTbwgg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDTCrCfqaXCupfphxulBsg0978nPtAWM8oEauVmSzbzNwIgTjYlFv61edzvfkJtG5GgJ6aiGRJTmUpmuil/m7mKiT0="}]},"maintainers":[{"name":"bcallaghan","email":"bcallaghan@conveyant.com"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/promise-transactions_0.2.1_1518301866036_0.7314967355240853"},"_hasShrinkwrap":false}},"readme":"# Promise Transactions\nTransactions engine for Promise-based asynchronous operations\n\n## Install\n\nThis package can be installed using npm with the following command:\n```bash\nnpm install --save @conveyant/promise-transactions\n```\n\nYarn may also be used to install this package.\n```bash\nyarn add @conveyant/promise-transactions\n```\n\n## Usage\n\n### Import\n\nFor ES5/JavaScript, the package can be `require`d as normal.\n```javascript\nvar Transaction = require('@conveyant/promise-transactions').Transaction;\n```\n\nFor ES6/TypeScript, the package can also be `import`ed.\n```typescript\nimport { Transaction } from '@conveyant/promise-transactions';\n```\n\n### Tasks\n\nThe fundamental unit of a `Transaction` is a `Task` that can be executed and (if necessary) rolled back. Each `Task` must have a unique name. This name can be used to retrieve intermediate results during and after execution. Intermediate results are stored in a context object that is passed to the `execute` and `rollback` functions of the `Task`.\n\nFor example:\n```javascript\nvar task = {\n    name: 'myTask',\n    execute: function(context) {\n        return 7;\n    },\n    rollback: function(context) {\n        console.log(context.myTask); // 7\n    }\n};\n```\n\nES6/TypeScript arrow functions may also be used.\n```typescript\nimport { Task } from '@conveyant/promise-transactions';\n\nconst task: Task = {\n    name: 'myTask',\n    execute: (context) => 7,\n    rollback: (context) => console.log(context.myTask) // 7\n};\n```\n\nNote that the execute and rollback functions of a `Task` may return a direct value (synchronous) or return a `Promise` (asynchronous). For traditional callback-style asynchronous functions, the functions [util.promisify](https://nodejs.org/dist/latest-v8.x/docs/api/util.html#util_util_promisify_original) or [Bluebird.promisify](http://bluebirdjs.com/docs/api/promise.promisify.html) may be useful.\n\n### Defining a Transaction\n\nA `Transaction` object must be created before `Task`s may be added to it.\n```javascript\nvar transaction = new Transaction();\n```\n\n`Task`s may be added one at a time or in a params-style list. Note that `Task`s will be executed in the order they were added and will be rolled back in the reverse order.\n```javascript\ntransaction.add(task1);\ntransaction.add(task2, task3, task4);\n```\n\nUsing the ES6/TypeScript spread operator, an entire array can be added at once.\n```typescript\nlet tasks: Task[];\n...\ntransaction.add(...tasks);\n```\n\n#### Nesting Transactions\n\nThe `Transaction` class implements the `Task` interface, making it possible to nest `Transaction`s and mix-and-match `Transaction`s with normal functions. This is particularly useful if you have another function that returns a `Transaction` object that represents a single step in a larger method chain.\n```javascript\nvar inner = getTransaction();\nvar transaction = new Transaction();\ntransaction.add(inner);\ntransaction.add(genericTask);\n```\n\n### Executing the Transaction\n\nOnce all necessary `Task`s have been added, the `Transaction` can be started with the `execute` function. This function returns a `Promise` which resolves when all `Task`s have been completed successfully. The returned object will contain the result of each `Task` which can be accessed by name or index. If one `Task` fails, all `Task`s that succeeded will be rolled back, and the `Promise` will be rejected. The error returned by the rejected `Promise` will contain the original error that caused the failure as well as any errors that occurred during rollback.\n```javascript\ntransaction.execute().then(function (results) {\n    console.log(results[0]); // The first result\n    console.log(result.myTask); // The result of 'myTask'\n}).catch(function (error) {\n    console.error(error.cause); // The original failure\n    console.error(error.rollbackErrors); // Array of errors during rollback\n});\n```\n\nSimilar results can be achieved with TypeScript's `async` and `await` features.\n```typescript\nimport { Transaction, TransactionResults, TransactionError } from '@conveyant/promise-transactions';\n...\ntry {\n    const results: TransactionResults = await transaction.execute();\n    console.log(results[0]); // The first result\n    console.log(result.myTask); // The result of 'myTask'\n} catch (e) {\n    const error: TransactionError = e;\n    console.error(error.cause); // The original failure\n    console.error(error.rollbackErrors); // Array of errors during rollback.\n}\n```\n\nThe final result of the transaction is also available in the `final` property of the `results` object.\n```javascript\nconsole.log(results.final); // Result of the final task\n```\n\n### TypeScript definitions\n\nA TypeScript definition file is included as part of the package.\n\n## Building\n\nThis package is written in TypeScript and can be executed using `ts-node`. To \"transpile\" the code into regular JavaScript, execute the `build` task.\n```bash\nnpm run build\n```\n\n## Testing\n\nTests are found in the `spec` folder and use the `jasmine` framework. Tests can be run through the `test` task.\n```bash\nnpm test\n```\n\n## Issues\n\nAny bugs or improvements are appreciated and could be posted at https://github.com/Conveyant/promise-transactions/issues.\n\n## Credits\n\nThis package was inspired by [node-transactions](https://github.com/ceoworks/node-transactions). Much of the logic and API were taken from that package. The primary difference is that `node-transactions` uses generator functions while `promise-transactions` uses native `Promise`s.\n","maintainers":[{"name":"bcallaghan","email":"bcallaghan@conveyant.com"}],"time":{"modified":"2022-06-12T16:38:59.257Z","created":"2018-02-06T04:14:45.856Z","0.1.0":"2018-02-06T04:14:45.856Z","0.1.1":"2018-02-06T04:16:21.426Z","0.2.0":"2018-02-10T22:29:53.859Z","0.2.1":"2018-02-10T22:31:06.749Z"},"homepage":"https://github.com/Conveyant/promise-transactions#readme","keywords":["transaction","promise","rollback"],"repository":{"type":"git","url":"git+https://github.com/Conveyant/promise-transactions.git"},"author":{"name":"Ben Callaghan"},"bugs":{"url":"https://github.com/Conveyant/promise-transactions/issues"},"license":"MIT","readmeFilename":"README.md"}