{"id":18924628,"url":"https://github.com/dash-os/promise-map-es6","last_synced_at":"2025-11-05T03:04:01.516Z","repository":{"id":57331427,"uuid":"92349067","full_name":"Dash-OS/promise-map-es6","owner":"Dash-OS","description":"Hybrid \"Map\" / \"Array\" / \"Promise\" object for composing asynchronously resolved objects.","archived":false,"fork":false,"pushed_at":"2017-10-23T06:56:53.000Z","size":58,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-25T05:16:38.911Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/Dash-OS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-25T00:44:30.000Z","updated_at":"2018-01-23T16:51:16.000Z","dependencies_parsed_at":"2022-09-14T18:40:35.745Z","dependency_job_id":null,"html_url":"https://github.com/Dash-OS/promise-map-es6","commit_stats":null,"previous_names":["dash-os/promisemap"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Dash-OS/promise-map-es6","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dash-OS%2Fpromise-map-es6","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dash-OS%2Fpromise-map-es6/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dash-OS%2Fpromise-map-es6/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dash-OS%2Fpromise-map-es6/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dash-OS","download_url":"https://codeload.github.com/Dash-OS/promise-map-es6/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dash-OS%2Fpromise-map-es6/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267780270,"owners_count":24143202,"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","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-08T11:07:38.935Z","updated_at":"2025-11-05T03:04:01.413Z","avatar_url":"https://github.com/Dash-OS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PromiseMap\n\n## Overview\n\nPromiseMap attempts to take the ideas of `Map` and `Promise` and combine them\ninto a useful tool for handling situations where you may be working with multiple\npromises simultaneously.\n\nIt does behave differently in a few aspects from `Map`.\n\n  - Consuming (getting) values removes them from the Map once resolved.\n  - Due to the above, we accept an array of keys to resolve / get\n  - Values are resolved deeply if possible.\n  - Values resolve until there are not any more promises.  This means that if the promises continue to add to the same promise map it will never resolve itself since it will continually attempt to resolve the new promises until none remain (think of it like a short-lived event loop resolving to a value).\n\n### Installation\n\n```\nyarn add promise-map-es6\n```\n\n***OR***\n\n```\nnpm install --save promise-map-es6\n```\n\n## Simple Example\n\n```javascript\n// assuming timeoutPromised() is:\nconst timeoutPromised = (fn, delay) =\u003e\n  new Promise((resolve, reject) =\u003e {\n    setTimeout(() =\u003e {\n      try {\n        resolve(fn());\n      } catch (e) {\n        reject(e);\n      }\n    }, delay);\n  });\nexport default timeoutPromised\n```\n\n```javascript\nimport PromiseMap from 'promise-map-es6'\nimport timeoutPromised from './timeoutPromised'\n\nconst P = new PromiseMap()\n\nP.set('foo', timeoutPromised(() =\u003e 1, 1000))\nP.set('bar', timeoutPromised(() =\u003e 2, 2000))\nP.set('baz', timeoutPromised(() =\u003e 3, 3000))\n\nP.then(result =\u003e console.log(result))\n// after 3 seconds: { foo: 1, bar: 2, baz: 3 }\n```\n\n\n## PromiseMap Syntax\n\n\u003e **Note:** All examples extend the example above by replacing the final function call.\n\n - [PromiseMap.prototype.size](#PromiseMap.prototype.size)\n - [PromiseMap.prototype.length](#PromiseMap.prototype.size)\n - PromiseMap.prototype.forEach()\n - PromiseMap.prototype.keys()\n - PromiseMap.prototype.get(...keys)\n - PromiseMap.prototype.set(key, promise)\n - PromiseMap.prototype.merge(promises)\n - PromiseMap.prototype.push(...promises)\n - PromiseMap.prototype.clear()\n - PromiseMap.prototype.has(...keys)\n - PromiseMap.prototype.entries(_?...keys?_)\n - PromiseMap.prototype.then(function (resolve, reject))\n - PromiseMap.prototype.catch()\n - PromiseMap[Symbol.iterator]\n\n---\n\n### Prototype Properties\n\n---\n\n#### PromiseMap.prototype.size\n\nReturns the number of key/value pairs in the PromiseMap object.\n\n```js\nP.size; // 3\n```\n\n---\n\n#### PromiseMap.prototype.length\n\nSynonymous with PromiseMap.prototype.size\n\n```js\nP.length; // 3\n```\n\n**returns** ***Number*** *Map.size*\n\n---\n\n### Methods\n\n---\n\n#### PromiseMap.prototype.clear()\n\nRemoves all key/value pairs from the PromiseMap object.  All promises are simply\nignored without resolution since Promises are not cancellable by design.\n\n```js\nP.size; // 3\nP.clear();\nP.size; // 0\n```\n\n**returns** _undefined_\n\n---\n\n#### PromiseMap.prototype.delete(...keys)\n\nDeletes the given key(s) and returns the result for each.  Each result is the\nresult of running the [`delete`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/delete)\nmethod on the underlying `Map`.\n\n```js\nP.size; // 3\nP.delete('foo', 'baz'); // [true, true]\nP.size; // 1\n```\n\n**returns** ***Array*** *keys.map(k =\u003e Map.delete(k))*\n\n---\n\n#### PromiseMap.prototype.entries(?...keys?)\n\nReturns a Promise which resolves to a standard `entries()` result where each value\nis resolved.  If *keys* is provided then only the given keys will be resolved.  All\nresolved values are removed from the `PromiseMap` once consumed.\n\n```js\nP.entries().then(entries =\u003e {\n  console.log(entries); // [ ['foo', 1], ['bar', 2], ['baz', 3] ]\n})\nP.size; // 0\n```\n\n```js\nP.entries('foo', 'baz').then(entries =\u003e {\n  console.log(entries); // [ ['foo', 1], ['baz', 3] ]\n})\nP.size; // 1\n```\n\n**returns** ***Promise*** *.then(entries)*\n\n---\n\n#### PromiseMap.prototype.get(...keys)\n\nReturns a Promise which resolves with an object that represents the resolved key/value pairs\nthat were requested.  All resolved values are removed from the `PromiseMap` once consumed.\n\n```js\nP.get('foo').then(result =\u003e console.log(result)); // { foo: 1 }\nP.size; // 2\n```\n\n**returns** ***Promise*** *.then(result)*\n\n---\n\n#### PromiseMap.prototype.set(key, promise)\n\nSets a key on the PromiseMap.  When the PromiseMap resolves, the resolved value of the\npromise will be available on that key of the object.\n\n```js\nP.set('qux', timeoutPromised(() =\u003e 4, 3000)); // { foo: 1, bar: 2, baz: 3, qux: 4 }\n```\n\n**returns** ***PromiseMap***\n\n---\n\n#### PromiseMap.prototype.merge(promises)\n\nTakes a plain object of key/promise pairs and runs PromiseMap.set(key, promise) on each.\nNote that it is an error to set a key which already exists on the PromiseMap.\n\n```js\nP.merge({\n  qux: timeoutPromised(() =\u003e 4, 3000)\n}).then(result =\u003e console.log(result)); // { foo: 1, bar: 2, baz: 3, qux: 4 }\n```\n\n**returns** ***PromiseMap***\n\n---\n\n#### PromiseMap.prototype.has(...keys)\n\nReturns _Boolean_ whether all given keys are within the `PromiseMap`.\n\n```js\nP.has('foo'); // true\nP.has('foo', 'bar'); // true\nP.has('foo', 'bar', 'blah'); // false\n```\n\n**returns** ***Boolean*** *keys.every(k =\u003e Map.has(k))*\n\n---\n\n#### PromiseMap.prototype.push(...promises)\n\nPushes new promises into the map.  These promises will be resolved with the `PromiseMap` but\ntheir responses will not be added to the final object.  This is useful if you want to make\nsure a given task is complete before resolving your final object, but don't want its resolved\nvalue to be included in the resulting object.\n\n```js\nP.push(timeoutPromised(() =\u003e 4, 10000))\n\nP.then(result =\u003e console.log(result))\n// after 10 seconds: { foo: 1, bar: 2, baz: 3 }\n```\n\n**returns** ***undefined***\n\n---\n\n#### PromiseMap.prototype.then(onResolve, onReject)\n\nResolves the entire PromiseMap and returns the result.  PromiseMap will be empty once completed. Note that the second argument (onReject) is better handled by chaining a .catch().\n\n\u003e In addition to resolving the promises within the PromiseMap, this will also resolve any Promises which are added to the PromiseMap during the resolution itself.\n\n```js\nP.then(result =\u003e console.log(result)); // { foo: 1, bar: 2, baz: 3 }\nP.size; // 0\n```\n**returns** ***Promise*** *.then(result, error)*\n\n---\n\n#### PromiseMap.prototype.catch(fn)\n\nResolves the entire PromiseMap and only registers a callback to occur should an error be\ncaught while resolving the values.  Note that since this consumes the values you will not\nbe able to retrieve them when using this method.\n\n```js\nP.add('errorExample', timeoutPromised(() =\u003e { throw new Error('Fail') }))\nP.catch(e =\u003e console.log(e.name, e.message)); //  errorExample Fail\nP.size; // 0\n```\n\n**returns** ***Promise***\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdash-os%2Fpromise-map-es6","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdash-os%2Fpromise-map-es6","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdash-os%2Fpromise-map-es6/lists"}