{"id":26067119,"url":"https://github.com/ambassify/throttle","last_synced_at":"2025-04-11T16:39:12.648Z","repository":{"id":20244908,"uuid":"81435880","full_name":"ambassify/throttle","owner":"ambassify","description":"Throttle depending on function arguments.","archived":false,"fork":false,"pushed_at":"2025-04-01T13:47:15.000Z","size":74,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T14:39:01.440Z","etag":null,"topics":["cache","javascript","throttle","timeout"],"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/ambassify.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-09T09:58:24.000Z","updated_at":"2025-04-01T13:47:17.000Z","dependencies_parsed_at":"2024-07-30T17:19:28.289Z","dependency_job_id":"83585b89-b04c-4996-812d-6513070c0d6e","html_url":"https://github.com/ambassify/throttle","commit_stats":{"total_commits":40,"total_committers":4,"mean_commits":10.0,"dds":"0.19999999999999996","last_synced_commit":"722a06d47d76ccc77005d8ad15ac1f768698af0f"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambassify%2Fthrottle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambassify%2Fthrottle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambassify%2Fthrottle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambassify%2Fthrottle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ambassify","download_url":"https://codeload.github.com/ambassify/throttle/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248441899,"owners_count":21104096,"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":["cache","javascript","throttle","timeout"],"created_at":"2025-03-08T21:08:47.994Z","updated_at":"2025-04-11T16:39:12.626Z","avatar_url":"https://github.com/ambassify.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Throttle\n\n[![CircleCI](https://circleci.com/gh/ambassify/throttle.svg?style=svg\u0026circle-token=8907f8b5ae62aab17b3ee1a1077bd1528c0cecb6)](https://circleci.com/gh/ambassify/throttle)\n\nCreate a throttled version of a function.\n\n## Installation\n\n```shell\nnpm install --save @ambassify/throttle\n```\n\n## Usage\n\nCreates a throttled version of `func`. `func` will only be invoked when its\nresult is not in the throttled function's cache or the time between the\ncurrent and last invocation is larger than what's specified by `delay`.\n\nIf `func` is async, the throttled function will immediately return a value\nfrom cache (if available) while `func` is executing.\n\n**Returns**: \u003ccode\u003eThrottledFunction\u003c/code\u003e - The throttled version of \"func\"\n\n| Param | Type | Description |\n| --- | --- | --- |\n| func | \u003ccode\u003efunction\u003c/code\u003e | The function to throttle |\n| options | \u003ccode\u003eThrottleOptions\u003c/code\u003e |  |\n\n**Example**\n```js\nconst throttle = require('@ambassify/throttle');\n\nconst throttled = throttle(\u003cfunction-to-throttle\u003e, \u003coptions\u003e);\n\nthrottled('hello');\nthrottled.clear(\u003c...args\u003e);\n```\n\n### ThrottleOptions : \u003ccode\u003eObject\u003c/code\u003e\n\n| Name | Type | Description |\n| --- | --- | --- |\n| delay | \u003ccode\u003enumber\u003c/code\u003e | How much time must have been elapsed for `func` to be invoked again when there's a chached result available. Defaults to `Infinity`. |\n| maxAge | \u003ccode\u003enumber\u003c/code\u003e | How long are items allowed to remain in cache. Unlimited by default. |\n| maxSize | \u003ccode\u003enumber\u003c/code\u003e | How long are items allowed to remain in cache. Unlimited by default. |\n| cache | \u003ccode\u003eMap\u003c/code\u003e | Specify a custom cache for throttle to use. Must provide methods that match Map's equivalent: has, get, set, delete, clear |\n| resolver | \u003ccode\u003efunction\u003c/code\u003e | Given the same arguments used to invoke `func` return only what's important to build the cache key. |\n| onUpdated | \u003ccode\u003efunction\u003c/code\u003e | Invoked with the `cacheItem` whenever the item is updated. |\n| onError | \u003ccode\u003e\u0026#x27;clear\u0026#x27;\u003c/code\u003e \\| \u003ccode\u003e\u0026#x27;cached\u0026#x27;\u003c/code\u003e \\| \u003ccode\u003e\u0026#x27;persist\u0026#x27;\u003c/code\u003e \\| \u003ccode\u003efunction\u003c/code\u003e | Error handler      to use when \"func\" throws or rejects.      - `clear`: The cache is cleared and the error is thrown      - `persist`: The error is saved into cache and thrown      - `cached`: If a previous value is in cache, it will be returned, if not the error will be thrown      - a custom function that receives the error as first param and cacheItem as the second, when specified        the throttled function won't touch the cache when an error occurs, it's up to this handler        to interact with cacheItem. |\n\n\u003ca name=\"module_@ambassify/throttle--throttle..ThrottledFunction\"\u003e\u003c/a\u003e\n\n### ThrottledFunction : \u003ccode\u003efunction\u003c/code\u003e\nThe throttled function.\n\n**Properties**\n\n| Name | Type | Description |\n| --- | --- | --- |\n| clear | \u003ccode\u003efunction\u003c/code\u003e | When invoked without any arguments the entire cache      is cleared, when **are** supplied they are passed, the item for those      arguments is removed from cache. |\n\n\n### CacheItem\n\nCacheItems are exposed through the `onUpdated` callback that can be specified in the throttle options.\n\n- **cacheItem.initialized**: Whether or not the item has its initial value\n- **cacheItem.pending**: The pending promise when throttle is currently running but already has\na previous value\n- **cacheItem.key**: The key for this cache item\n- **cacheItem.stale**: Whether or not the cache item\u0026#x27;s value is considered stale based on the\nlast time it was updated and its \u0026quot;delay\u0026quot; option.\n- **cacheItem.value**: Current value of the cache item. When this is set, all timers and the like\nfor the item are also reset\n- **cacheItem.error**: Same as \u0026quot;value\u0026quot; but used to indicate the result of throttled is an error\n- **cacheItem.clear()**: Clear the item from throttled\u0026#x27;s cache\n- **cacheItem.delay(delay)**: Update this specific item\u0026#x27;s \u0026quot;delay\u0026quot;\n- **cacheItem.maxAge(maxAge)**: Update this specific item\u0026#x27;s \u0026quot;maxAge\u0026quot;\n\n## Example\n\n```javascript\nconst throttle = require('@ambassify/throttle');\n\nlet example = 0;\n\nasync function myFunction(input) {\n    // Delay 500 ms to fake a slow operation\n    await new Promise(resolve =\u003e setTimeout(resolve, 500));\n\n    example += input;\n    return example;\n}\n\n// Allow `myFunction` to be called once every 2 seconds for each different\n//`input` and cache the value for max 5 seconds.\nconst throttled = throttle(myFunction, { delay: 2000, maxAge: 5000 });\n\nthrottled(1); // 1\nthrottled(1); // 1\nthrottled(1); // 1\n\n// Wait for 2 seconds\n// \"myFunction\" is called, but the old cached result is returned immediately\n\nthrottled(1); // 1\n\n// Wait 500ms (the fake delay)\n// \"myFunction\" isn't called (as delay hasn't been reached) but we do get the\n// latest result\n\nthrottled(1); // 2\n\n// Wait for 5 seconds\n// \"myFunction\" is called but the old cached value has expired so it resolves\n// with the new value once the function has run\n\nthrottled(1); // 3\n\nconst conditional = throttle(myFunction, {\n    delay: 2000,\n    maxAge: 5000\n    onCached: function(item) {\n        // Only cache results for large values of input\n        if (item.key \u003c 10)\n            item.clear();\n    }\n}\n\nconditional(1); // 1\nconditional(1); // 2\nconditional(1); // 3\n\nconditional(20); // 23\nconditional(20); // 23\n```\n\n## Contributing\n\nIf you have some issue or code you would like to add, feel free to open a Pull Request or Issue and we will look into it as soon as we can.\n\n## License\n\nWe are releasing this under a MIT License.\n\n## About us\n\nIf you would like to know more about us, be sure to have a look at [our website](https://www.ambassify.com), or our Twitter accounts [@Ambassify](https://twitter.com/Ambassify), [Sitebase](https://twitter.com/Sitebase), [JorgenEvens](https://twitter.com/JorgenEvens).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambassify%2Fthrottle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fambassify%2Fthrottle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambassify%2Fthrottle/lists"}