{"id":19080673,"url":"https://github.com/valeriansaliou/node-bloom-control","last_synced_at":"2025-04-30T06:11:54.836Z","repository":{"id":55131967,"uuid":"95000290","full_name":"valeriansaliou/node-bloom-control","owner":"valeriansaliou","description":":bouquet: Bloom Control integration for Node. Used in pair with Bloom, the HTTP REST API caching middleware.","archived":false,"fork":false,"pushed_at":"2025-01-06T21:18:46.000Z","size":141,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-30T06:11:45.330Z","etag":null,"topics":["bloom","cache","ddos","dos","http","nodejs","npm","npm-package","performance","rest","scale","speed"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/bloom-control","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/valeriansaliou.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-06-21T12:14:07.000Z","updated_at":"2025-03-15T13:09:32.000Z","dependencies_parsed_at":"2023-11-06T09:45:54.509Z","dependency_job_id":"769a1beb-a624-4d68-bcb3-b75931188d50","html_url":"https://github.com/valeriansaliou/node-bloom-control","commit_stats":{"total_commits":86,"total_committers":1,"mean_commits":86.0,"dds":0.0,"last_synced_commit":"15ab60e3e807cdccf7282884259fcecbd3ebee66"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valeriansaliou%2Fnode-bloom-control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valeriansaliou%2Fnode-bloom-control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valeriansaliou%2Fnode-bloom-control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valeriansaliou%2Fnode-bloom-control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valeriansaliou","download_url":"https://codeload.github.com/valeriansaliou/node-bloom-control/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251651231,"owners_count":21621716,"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":["bloom","cache","ddos","dos","http","nodejs","npm","npm-package","performance","rest","scale","speed"],"created_at":"2024-11-09T02:24:56.990Z","updated_at":"2025-04-30T06:11:54.817Z","avatar_url":"https://github.com/valeriansaliou.png","language":"JavaScript","funding_links":["https://www.buymeacoffee.com/valeriansaliou"],"categories":[],"sub_categories":[],"readme":"# node-bloom-control\n\n[![Test and Build](https://github.com/valeriansaliou/node-bloom-control/workflows/Test%20and%20Build/badge.svg?branch=master)](https://github.com/valeriansaliou/node-bloom-control/actions?query=workflow%3A%22Test+and+Build%22) [![Build and Release](https://github.com/valeriansaliou/node-bloom-control/workflows/Build%20and%20Release/badge.svg)](https://github.com/valeriansaliou/node-bloom-control/actions?query=workflow%3A%22Build+and+Release%22) [![NPM](https://img.shields.io/npm/v/bloom-control.svg)](https://www.npmjs.com/package/bloom-control) [![Downloads](https://img.shields.io/npm/dt/bloom-control.svg)](https://www.npmjs.com/package/bloom-control) [![Buy Me A Coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg)](https://www.buymeacoffee.com/valeriansaliou)\n\n**Bloom Control integration for Node. Used in pair with Bloom, the HTTP REST API caching middleware.**\n\nBloom Control lets you control your Bloom cache, from your NodeJS code. Purge API cache on-demand, whenever your API worker updates a database model or performs some action that require cached data to be invalidated.\n\n**🇫🇷 Crafted in Brest, France.**\n\n## Who uses it?\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003ca href=\"https://crisp.chat/\"\u003e\u003cimg src=\"https://valeriansaliou.github.io/node-bloom-control/images/crisp.png\" width=\"64\" /\u003e\u003c/a\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003eCrisp\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n_👋 You use bloom-control and you want to be listed there? [Contact me](https://valeriansaliou.name/)._\n\n## How to install?\n\nInclude `bloom-control` in your `package.json` dependencies.\n\nAlternatively, you can run `npm install bloom-control --save`.\n\n## How to use?\n\n### 1. Create the connection\n\n`node-bloom-control` can be instanciated as such:\n\n```javascript\nvar BloomControl = require(\"bloom-control\").BloomControl;\n\nvar bloomControl = new BloomControl({\n  host  : \"::1\",  // Or '127.0.0.1' if you are still using IPv4\n  port  : 8811,   // Default port is '8811'\n  shard : 0       // Specify the Bloom shard to use, as \\\n                  //   a Bloom instance can host multiple cache shards, eg. for different API workers\n}).connect({\n  connected : function() {\n    // Connected handler\n    console.info(\"Bloom Control succeeded to connect to host.\");\n  },\n\n  disconnected : function() {\n    // Disconnected handler\n    console.error(\"Bloom Control is now disconnected.\");\n  },\n\n  timeout : function() {\n    // Timeout handler\n    console.error(\"Bloom Control connection timed out.\");\n  },\n\n  retrying : function() {\n    // Retry handler\n    console.error(\"Trying to reconnect to Bloom Control...\");\n  },\n\n  error : function(error) {\n    // Failure handler\n    console.error(\"Bloom Control failed to connect to host.\", error);\n  }\n});\n```\n\n### 2. Purge cache collections\n\nUse the same `bloomControl` instance to purge cache collections:\n\n```javascript\n// Notice: all methods return 'true' if executed immediately, 'false' if deferred (ie. TCP socket disconnected)\n\n// Purge cache for a given bucket (all authenticated users)\nbloomControl.purgeBucket(`cache_bucket_id`, function(error) {\n  // Handle purge errors here\n});\n\n// Purge cache for a multiple buckets at once (all authenticated users)\nbloomControl.purgeBucket([\n  `cache_bucket_id_1`,\n  `cache_bucket_id_2`\n], function(error) {\n  // Handle purge errors here\n});\n\n// Purge all cache for a given authenticated user\n// Notice: identifier and token can usually be found in your Basic Auth headers\nbloomControl.purgeAuth(`auth_identifier`, `auth_token`, function(error) {\n  // Handle purge errors here\n});\n\n// Purge all cache for multiple authenticated users at once\nbloomControl.purgeAuth([\n  [`auth_identifier_1`, `auth_token_1`],\n  [`auth_identifier_2`, `auth_token_2`]\n], function(error) {\n  // Handle purge errors here\n});\n```\n\n### 3. Listen for processed commands\n\nIn the event you need to debug the commands being executed (given the result, either `NIL`, `OK`, `ERR` or `PONG`), you can register a listener as:\n\n```javascript\n// Listen for OK commands (ie. executed commands)\nbloomControl.on(\"OK\", function(command) {\n  console.log(\"Command OK:\", command);\n});\n\n// Listen for ERR commands (ie. failed commands)\nbloomControl.on(\"ERR\", function(command) {\n  console.log(\"Command ERR:\", command);\n});\n\n// Listen for NIL commands (ie. unknown commands, you won't need this)\nbloomControl.on(\"NIL\", function(command) {\n  console.log(\"Command NIL:\", command);\n});\n\n// Listen for PONG commands (ie. replies to pings)\nbloomControl.on(\"PONG\", function(command) {\n  console.log(\"Command PONG:\", command);\n});\n```\n\nYou can stop listening to events as such:\n\n```javascript\nbloomControl.off(\"OK\");\nbloomControl.off(\"ERR\");\nbloomControl.off(\"NIL\");\nbloomControl.off(\"PONG\");\n```\n\n**Notice: only 1 handler can be registered at the same time for a given command result.**\n\n### 4. Test connection\n\nYou can test your connection to Bloom anytime by sending a ping:\n\n```javascript\nbloomControl.ping(function(error) {\n  // Handle ping errors here\n});\n```\n\nThe response to your ping will come on the event channel (register a listener for the `PONG` event).\n\n**Notice: pings are automatically sent to maintain the connection. You will get pong events periodically on the event channel, even if you never sent a ping.**\n\n### 5. Teardown connection\n\nIf you need to teardown an ongoing connection to Bloom, use:\n\n```javascript\n// Returns: true if proceeding close, false if already closed\nbloomControl.close(function(error) {\n  // Handle close errors here\n});\n```\n\n## What is Bloom?\n\nℹ️ **Wondering what Bloom is?** Check out **[valeriansaliou/bloom](https://github.com/valeriansaliou/bloom)**.\n\n## How is it linked to Bloom?\n\n`node-bloom-control` maintains a persistent TCP connection to the Bloom Control interface that's listening on your running Bloom instance. In case `node-bloom-control` gets disconnected from Bloom, it will retry to connect once the connection is established again. Pending cache purge requests that could not be transmitted to Bloom are stacked, up to a certain limit where further cache purge requests will be dropped and not stacked. Once the connection to Bloom Control is established again, stacked cache purge requests are transmitted to Bloom for processing.\n\nYou can configure the connection details of your Bloom instance when initializing `node-bloom-control` from your code; via the Bloom host and port.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaleriansaliou%2Fnode-bloom-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaleriansaliou%2Fnode-bloom-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaleriansaliou%2Fnode-bloom-control/lists"}