{"id":13464173,"url":"https://github.com/kessler/node-loadbalance","last_synced_at":"2025-07-24T08:39:08.429Z","repository":{"id":1964555,"uuid":"45424233","full_name":"kessler/node-loadbalance","owner":"kessler","description":"A collection of distilled load balancing engines","archived":false,"fork":false,"pushed_at":"2022-12-12T12:02:19.000Z","size":42,"stargazers_count":81,"open_issues_count":4,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-20T07:07:21.564Z","etag":null,"topics":["engine","javascript","load-balancer","node-js","node-module","nodejs","npm-module","npm-package"],"latest_commit_sha":null,"homepage":"","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/kessler.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":"2015-11-02T21:45:48.000Z","updated_at":"2023-02-02T21:55:47.000Z","dependencies_parsed_at":"2023-01-11T16:07:00.452Z","dependency_job_id":null,"html_url":"https://github.com/kessler/node-loadbalance","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/kessler/node-loadbalance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-loadbalance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-loadbalance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-loadbalance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-loadbalance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kessler","download_url":"https://codeload.github.com/kessler/node-loadbalance/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fnode-loadbalance/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266815235,"owners_count":23988563,"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-24T02:00:09.469Z","response_time":99,"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":["engine","javascript","load-balancer","node-js","node-module","nodejs","npm-module","npm-package"],"created_at":"2024-07-31T14:00:36.004Z","updated_at":"2025-07-24T08:39:07.364Z","avatar_url":"https://github.com/kessler.png","language":"JavaScript","funding_links":[],"categories":["misc"],"sub_categories":["Extensibility"],"readme":"# loadbalance\n\n[![npm status](http://img.shields.io/npm/v/loadbalance.svg?style=flat-square)](https://www.npmjs.org/package/loadbalance)\n\nThis is a collection of load balancing engines in (what is hopefully) their most distilled form. \n\nThe goal was to create a highly reusable implementation that imposes as little as possible on the user.\n\n## Install\n\nWith [npm](https://npmjs.org) do:\n\n`npm i loadbalance`\n\n```js\nconst loadbalance = require('loadbalance')\n```\n\n## Usage\nTo use, instantiate an engine or call a factory method with a pool. Then call pick(), which will return the selected object, calling pick() repeatedly will yield the same or a different object from the pool, depending on the algorithm which powers that engine.\n\n```javascript\nconst loadbalance = require('loadbalance')\nconst engine = loadbalance.random(['a', 'b', 'c'])\nconst pick = engine.pick()\n```\n\n### pick()\n`pick()` is called without any arguments and will always return an object which is a member of the pool according to the pool's selection strategy\n\n## Engines\n\n### Random Engine\nThe random engine picks an object from the pool at random, each time pick() is called.\n\n```javascript\nconst loadbalance = require('loadbalance')\nconst engine = loadbalance.random(['a', 'b', 'c'])\nconst pick = engine.pick()\n```\n\n#### new RandomEngine(pool, seed)\n```javascript\nconst engine = new loadbalance.RandomEngine(pool)\n```\nPool - an objects to pick from, eg ```[1,2,3]```\nSeed - an optional seed that will be used to recreate a random sequence of selections\n\n### Weighted Random Engine\nThe random engine picks an object from the pool at random **but with bias** (probably should have called it BiasedRandomEngine), each time pick() is called.\n\n```javascript\nconst loadbalance = require('loadbalance')\nconst engine = loadbalance.random([\n    { object: 'a', weight: 2 }, \n    { object: 'b', weight: 3 }, \n    { object: 'c', weight: 5 }\n])\nconst pick = engine.pick()\n```\nWith this engine, calling pick() repeatedly will roughly return `'a'` 20% of the time, `'b'` 30% of the time and `'c'` 50% of the time\n\n#### new WeightedRandomEngine(pool, seed)\n```javascript\nconst engine = new loadbalance.WeightedRandomEngine(pool)\n```\n\nPool - objects to pick from. Each object is of the form:\n```javascript\nconst object1 = {\n    object: 'something',\n    weight: 2\n}\n```\n\nSeed - an optional seed that will be used to recreate a random sequence of selections\n\n### RoundRobinEngine\nAn engine that picks objects from its pool using Round Robin algorithm (doh!)\n\n```javascript\nconst loadbalance = require('loadbalance')\nconst engine = loadbalance.roundRobin(['a', 'b', 'c'])\nconst pick = engine.pick()\n```\n\nThe roundRobin() factory method can be used to obtain both RoundRobinEngine and WeightedRoundRobinEngine. The decision is based on the contents of the pool.\n\n#### new RoundRobinEngine(pool)\n```javascript\nconst engine = new loadbalance.RoundRobinEngine(pool)\n```\nPool - objects to pick from, eg ```[1,2,3]```\n\n### WeightedRoundRobinEngine\nSame as round robin engine, only members of the pool can have weights. \n\n```javascript\nconst loadbalance = require('loadbalance')\nconst engine = loadbalance.roundRobin([{ object: 'a', weight: 2 }, {object: 'b', weight: 1 }])\nconst pick = engine.pick()\n```\n\ncall pick six times using the above engine will yield: 'a', 'a', 'b', 'a', 'a', 'b'\n\n#### new WeightedRoundRobinEngine(pool)\n```javascript\nconst engine = new loadbalance.WeightedRoundRobinEngine(pool)\n```\nPool - objects to pick from. Each object is of the form:\n```javascript\nconst object1 = {\n    object: 'something',\n    weight: 2\n}\n```\n\nWeight should always be an integer which is greater than zero. \nObject (you can also use value, its an alias property) can be anything you want, just like other pools. It cannot, however, be null or undefined at the time the pool is created.\n\n### PriorityEngine\nNot yet implemented\n\n### Extensibility\nHere is an example of a custom engine:\n```javascript\nconst AbstractEngine = require('loadbalance').AbstractEngine\n\nclass MyEngine extends AbstractEngine {\n    constructor(pool) {\n        super(pool)\n    }\n\n    _pick(pool) {\n        // pick something from the pool somehow and return it\n    }\n}\n\n```\n\n## misc\n\nThis module shares some functinality with [pool](https://github.com/coopernurse/node-pool) module. It is worth taking a look at it if you are looking for something more high level.\n\nThis module is heavily inspired by this [article about load balance algorithms](https://devcentral.f5.com/articles/intro-to-load-balancing-for-developers-ndash-the-algorithms)\n\n\n## license\n\n[MIT](http://opensource.org/licenses/MIT) © [yaniv kessler](blog.yanivkessler.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkessler%2Fnode-loadbalance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkessler%2Fnode-loadbalance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkessler%2Fnode-loadbalance/lists"}