{"_id":"@austinbreslin/pledge","_rev":"1-be04bd6fb0e801f46a70602fa1dcbd9b","name":"@austinbreslin/pledge","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@austinbreslin/pledge","version":"1.0.0","keywords":[],"license":"MIT","_id":"@austinbreslin/pledge@1.0.0","maintainers":[{"name":"austinbreslindev","email":"buckyaustin@gmail.com"}],"homepage":"https://github.com/AustinBreslinDev/libs/","dist":{"shasum":"f6756262bb78cf7b5365cc6350c832929983f330","tarball":"https://registry.npmjs.org/@austinbreslin/pledge/-/pledge-1.0.0.tgz","fileCount":6,"integrity":"sha512-CrPMM1bZmP3zO5aAAv+THVUiRCu4hKFC+6WVMP6pJGSzlbOL/3vrCxyhZO+ssymgieI9RdF32hyZdPJu8ooHxw==","signatures":[{"sig":"MEQCIGreyWCF3UmhJl7mEGtIwJhf1gwFWGw0d7MaDV+UHR5tAiAKEF2XxgqG2wlXe9Y2kkWnkwHx0E3YZSv77ywTYS9NtA==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":17664},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","$schema":"https://json.schemastore.org/package.json","engines":{"node":">=18","pnpm":">=9.12.1"},"exports":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"gitHead":"0572f25f259eaa51526bb5232b73f5babe064d07","scripts":{"dev":"NODE_ENV=development vite build --mode development --watch","lint":"tsc --noEmit && biome check ./src --config-path ../../biome.json","test":"vitest","build":"NODE_ENV=production rimraf ./dist && vite build && jampack ./dist","dev:lib":"NODE_ENV=development vite build --watch","build:dev":"NODE_ENV=development vite build --mode development","test:bench":"vitest bench","test:debug":"npm run test -- --inspect --no-file-parallelism --ui"},"_npmUser":{"name":"austinbreslindev","email":"buckyaustin@gmail.com"},"repository":{"url":"git+https://github.com/AustinBreslinDev/libs/.git","type":"git"},"_npmVersion":"10.9.0","description":"- [**Pledge**: A Promise Wrapper for Error Handling and Timed Functions](#pledge-a-promise-wrapper-for-error-handling-and-timed-functions)   - [Installation](#installation)   - [API](#api)     - [newPledge](#newpledge)     - [pledge](#pledge)     - [pledg","directories":{},"_nodeVersion":"20.18.0","dependencies":{},"_hasShrinkwrap":false,"packageManager":"pnpm@9.12.1","_npmOperationalInternal":{"tmp":"tmp/pledge_1.0.0_1735675553924_0.3801028857742308","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"$schema":"https://json.schemastore.org/package.json","name":"@austinbreslin/pledge","version":"1.0.1","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"scripts":{"build":"NODE_ENV=production rimraf ./dist && vite build && jampack ./dist","build:dev":"NODE_ENV=development vite build --mode development","dev":"NODE_ENV=development vite build --mode development --watch","lint":"tsc --noEmit && biome check ./src --config-path ../../biome.json","dev:lib":"NODE_ENV=development vite build --watch","test":"vitest","test:bench":"vitest bench","test:debug":"npm run test -- --inspect --no-file-parallelism --ui"},"dependencies":{},"license":"MIT","keywords":[],"repository":{"url":"git+https://github.com/AustinBreslinDev/libs/.git","type":"git"},"homepage":"https://github.com/AustinBreslinDev/libs/","packageManager":"pnpm@9.15.2","engines":{"pnpm":">=9.15.2","node":">=20"},"_id":"@austinbreslin/pledge@1.0.1","gitHead":"3dc7b31666e22d66ccf4127bd34c4d7cfe2b01ca","description":"- [**Pledge**: A Promise Wrapper for Error Handling and Timed Functions](#pledge-a-promise-wrapper-for-error-handling-and-timed-functions)   - [Installation](#installation)   - [API](#api)     - [newPledge](#newpledge)     - [pledge](#pledge)     - [pledg","_nodeVersion":"22.12.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-mjyP42Rx9y7NCCbYfg8SM78RF4LGwhc/dbk3Iq+4kRKJaSLLZ4ncNvi6Jl+TlAR/As5ITBoCb+VHhCWjRw4EsA==","shasum":"968f09b8914440f54d0f4daa651ea35f52da9258","tarball":"https://registry.npmjs.org/@austinbreslin/pledge/-/pledge-1.0.1.tgz","fileCount":6,"unpackedSize":17703,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFUVAoeNOfqPoUS0BeijUc+xoWLY7je6UtOxPVZa3ZtHAiBVxotUUtSKHa9L510LNC7nnil2C8yQ9Y5gWX9pWWt9Cw=="}]},"_npmUser":{"name":"austinbreslindev","email":"buckyaustin@gmail.com"},"directories":{},"maintainers":[{"name":"austinbreslindev","email":"buckyaustin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pledge_1.0.1_1736714318652_0.9517378812876753"},"_hasShrinkwrap":false}},"time":{"created":"2024-12-31T20:05:53.811Z","modified":"2025-01-12T20:38:39.020Z","1.0.0":"2024-12-31T20:05:54.132Z","1.0.1":"2025-01-12T20:38:38.806Z"},"license":"MIT","homepage":"https://github.com/AustinBreslinDev/libs/","keywords":[],"repository":{"url":"git+https://github.com/AustinBreslinDev/libs/.git","type":"git"},"description":"- [**Pledge**: A Promise Wrapper for Error Handling and Timed Functions](#pledge-a-promise-wrapper-for-error-handling-and-timed-functions)   - [Installation](#installation)   - [API](#api)     - [newPledge](#newpledge)     - [pledge](#pledge)     - [pledg","maintainers":[{"name":"austinbreslindev","email":"buckyaustin@gmail.com"}],"readme":"# Pledge: A Promise Wrapper for Error Handling and Timed Functions\n\n- [**Pledge**: A Promise Wrapper for Error Handling and Timed Functions](#pledge-a-promise-wrapper-for-error-handling-and-timed-functions)\n  - [Installation](#installation)\n  - [API](#api)\n    - [newPledge](#newpledge)\n    - [pledge](#pledge)\n    - [pledgeTryCatch](#pledgetrycatch)\n    - [pledgify](#pledgify)\n    - [pledgeAll](#pledgeall)\n    - [pledgeAllSettled](#pledgeallsettled)\n    - [pledgeRace](#pledgerace)\n    - [pledgeAny](#pledgeany)\n    - [pledgeTimed](#pledgetimed)\n    - [pledgeAllTimed](#pledgealltimed)\n    - [pledgeAllSettledTimed](#pledgeallsettledtimed)\n    - [pledgeWait](#pledgewait)\n\n**Pledge** is a utility library designed to simplify error handling in JavaScript applications using Promises.\nIt provides functions that wrap promises, try-catch blocks, callback-based functions, and timed operations,\nreturning tuples instead of throwing errors.\n\n- All pledge items return a tuple/array with the first item in the tuple being an Error | undefined and the second\n  item in the tuple being of type `T | undefined`.\n- Pledge has a type for this tuple called `PledgeResult<T> `\n- All pledge functions take an optional parameter object that allows you to supply an abort controller, giving\n  you the ability to cancel the execution of the promise at any time.\n- **Pledge** has full Typescript support\n\n## Installation\n\nYou can install **Pledge** via npm or pnpm:\n\n**npm**\n\n```bash\nnpm install @austinbreslin/pledge\n```\n\n**pnpm**\n\n```bash\npnpm add @austinbreslin/pledge\n```\n\n## API\n\n### newPledge\n\nAllows you to reduce your boilerplate code for using pledge, by using the exact same constructor\nused in new Promise.\n\n***Signature***\n\n```typescript\nnewPledge<T>(cb: (resolve: (value: T) => void, reject: (reason?: unknown) => void) => void): PledgeResult<T>\n```\n\n***Usage***\n\n```javascript\nimport { newPledge } from \"@austinbreslin/pledge\";\n\nconst example = newPledge((resolve, reject) => {\n  // do something as if your in a promise\n  resolve({ example: 'data' });\n});\n\nconst result = await example();\nconsole.log(result); // [undefined, { example: 'data' }]\n```\n\n### pledge\n\nWraps an already constructed promise object and ensures it returns a tuple.\n\n***Signature***\n\n```typescript\nasync pledge<T>(Promise<T>, options?: { abortController: AbortController }): PledgeResult<T>\n```\n\n***Usage***\n\n```javascript\nimport { pledge } from '@austinbreslin/pledge';\n\nconst result = await pledge(Promise.resolve({ example: 'data' }));\nconsole.log(result); // [undefined, { example: 'data' }]\n```\n\n### pledgeTryCatch\n\nReduces the boilerplate code when you want to run code that could throw an error.\n\n***Signature***\n\n```typescript\n<T>(fn: () => T) => void\n```\n\n***Usage***\n\n```javascript\nimport { pledgeTryCatch } from \"@austinbreslin/pledge\";\n\nconst result = pledgeTryCatch<object>(() => {\n    return JSON.parse('abc{}invalid');\n});\nconsole.log(result); // [SyntaxError: Unexpected token 'a', \"abc{}invalid\" is not valid JSON, undefined]\n```\n\n### pledgify\n\nConverts a callback function into pledge wrapped promise.\nThis does not accept options as a second parameter.\n\n***Signature***\n\n```typescript\nasync <T>(fn: (...arguments: unknown[], callback: (err: Error | undefined, data: T | undefined) => void)) => void;\n```\n\n***Usage***\n\n```javascript\nimport { pledgify } from \"@austinbreslin/pledge\";\n\nconst example = (toWhom, cb) => {\n  // You shouldn't create callbacks anymore, but some old libraries will still\n  // use this format.\n  try {\n    const parsed = JSON.parse(`abc{ hello: '${toWhom}'}invalid`);\n    cb(undefined, parsed);\n  } catch (error) {\n    cb(error, undefined);\n  }\n};\n\nconst wrapped = pledgify(example);\nconst result = await wrapped(\"John Smith\");\nconsole.log(result); // [SyntaxError: Unexpected token, undefined]\n```\n\n### pledgeAll\n\nAn alternative to Promise.all that returns a tuple\n\n***Signature***\n\n```typescript\nasync <T>(promise: Promise[], options?: { abortController: AbortController }): PledgeResult<T>\n```\n\n***Usage***\n\n```javascript\nimport { pledgeAll } from \"@austinbreslin/pledge\";\n\nconst promises = [\n  fetch('https://example.com'),\n  fetch('https://example.com')\n];\n\nconst pledged = await pledgeAll(promises);\nconsole.log(pledged); // [undefined, [fetch1:Response, fetch2:Response]]\n```\n\n### pledgeAllSettled\n\nAn alternative to Promise.allSettled, but returns an array of errors and an array of results\nin the order you specified, unlike Promise.all which forces you to check each result to discover\nif that promise failed or not.\n\n***Signature***\n\n```typescript\nasync <T>(promise: Promise[], options?: { abortController: AbortController }): [Error[], T[]]\n```\n\n***Usage***\n\n```javascript\nimport { pledgeAllSettled } from \"@austinbreslin/pledge\";\n\nconst promises = [\n  fetch('https://example.com'),\n  fetch('invalidhttps://example.com'),\n];\n\nconst pledged = await pledgeAllSettled(promises);\nconsole.log(pledge); // [[undefined, net::ERR_NAME_NOT_RESOLVED], [Response, undefined]]\n```\n\n### pledgeRace\n\nAn alternative to Promise.race\n\n**Signature**\n\n```typescript\nasync <T>(promises: Promise[], options?: { abortController: AbortController }): PledgeResult<T>\n```\n\n**Usage**\n\n```javascript\nimport { pledgeRace } from \"@austinbreslin/pledge\"\n\nconst promises = [\n  fetch('https://example.com'),\n  fetch('https://example.com'),\n];\n\nconst pledged = await pledgeRace(promises);\nconsole.log(pledged); // [undefined, Response]\n```\n\n### pledgeAny\n\nAn alternative to Promise.any\n\n**Signature**\n\n```typescript\nasync <T>(promises: Promise[], options?: { abortController: AbortController }): PledgeResult<T>\n```\n\n**Usage**\n\n```javascript\nimport { pledgeAny } from \"@austinbreslin/pledge\";\n\nconst promises = [\n  fetch('https://example.com'),\n  fetch('invalidhttps://example.com')\n];\n\nconst pledged = await pledgeAny(promises);\nconsole.log(pledged); // [undefined, [Response]]\n// Doesn't error out, because 1 passed\n```\n\n### pledgeTimed\n\nAn alternative to pledge, but with time options. It will cancel the promise if it\nexceeds the set time. The time unit is milliseconds, and the default is 0ms.\n\n**Signature**\n\n```typescript\nasync <T>(promise: Promise<T>, timeoutMs: number, options?: { abortController: AbortController }): PledgeResult<T>\n```\n\n**Usage**\n\n```javascript\nimport { pledgeTimed } from \"@austinbreslin/pledge\";\n\nconst pledged = await pledgeTimed(fetch('https://example.com'), 20);\nconsole.log(pledged); // [Error('Pledge time out occurred at set time:'), undefined] \n```\n\n### pledgeAllTimed\n\nAn alternative to pledgeAll, but with time options. It will cancel all the promises if any of them\nexceed the set time. The time unit is milliseconds, and the default is 0ms.\n\n**Signature**\n\n```typescript\nasync <T>(promises: Promise[], timeoutMs: number, options?: { abortController: AbortController }): PledgeResult<T>\n```\n\n**Usage**\n\n```javascript\nimport { pledgeAllTimed } from \"@austinbreslin/pledge\";\n\nconst promises = [\n  fetch('https://example.com'),\n  fetch('https://example.com')\n];\n\nconst pledged = await pledgeAllTimed(promises, 20);\nconsole.log(pledged); // [Error('Pledge time out occurred at set time:'), undefined]\n\nconst success = await pledgeAllTimed(promises, 2000);\nconsole.log(success); // [undefined, [Response1, Response1]]\n```\n\n### pledgeAllSettledTimed\n\nAn alternative to pledgeAllSettled, but with time options. It will cancel all the promises if any of them\nexceed the set time. The unit is milliseconds, and the default is 0ms.\n\n**Signature**\n\n```typescript\nasync <T>(promises: Promise[], timeoutMs: Number, options?: { abortController: AbortController }): [(Error | undefined)[], (T | undefined)[]]\n```\n\n**Usage**\n\n```javascript\nimport { pledgeAllSettledTimed } from \"@austinbreslin/pledge\";\n\nconst promises = [\n  fetch('https://example.com'),\n  fetch('https://example.com')\n];\n\nconst pledged = await pledgeAllSettledTimed(promises, 20);\n\nconsole.log(pledged); // [[Error(\"Pledge time out occurred at set time: \")], undefined]\n```\n\n### pledgeWait\n\nThis is a helper function that will execute your promise function after a set period of time.\nThe time unit is milliseconds. The default wait time is 0ms.\n\n**Signature**\n\n```typescript\nasync <T>(promiseFn: () => Promise<T>) => PledgeResult<T>\n```\n\n**Usage**\n\n```javascript\nimport { pledgeWait } from \"@austinbreslin/pledge\";\n\nconst promiseFn = fetch.bind(null, 'https://example.com');\nconst pledged = await pledgeWait(promiseFn);\n\nconsole.log(pledged); // [undefined, Response] \n```\n","readmeFilename":"readme.md"}