Use cases

The guides use university timetabling as their running example, because its constraints are easy to say out loud. This section does the opposite: real problems from Node.js codebases and the teams around them.

Each page states the problem, links to the primary source describing it, shows the code, and gives the measured result. Every number came from running the package, including the ones where aequitas falls short of the theoretical best. A worked example that only flatters the library is not much use when you are deciding whether to depend on it.

Case	Bins	Items	Weight is
Monorepo CI tasks	CI agents	Package tasks	Recorded duration
Test sharding	Shards	Spec files	Recorded duration
Database shards	Shards	SaaS tenants	Gigabytes stored
Support backlog	Agents	Queued tickets	Estimated minutes

The one rule that spans all four

When you already have a working assignment and the inputs change, both suggest and rebalance will give you a valid answer. Which one is right depends entirely on a question aequitas cannot answer for you:

Does moving an item cost anything?

• No. Moving a package between CI agents is free, so take the better layout. suggest wins there: on the monorepo example it beats rebalance by 30 seconds of pipeline.
• Yes. Moving a tenant means copying its data and taking a maintenance window. rebalance wins there, and not marginally: on the database example it reaches an equally good layout while migrating 430 GB instead of 625 GB.

Same library, opposite advice, and the deciding factor is in your domain rather than in the solver.

What none of them do

Three limits recur, so they are worth knowing before you read any of the pages:

• No dependencies or ordering. Nothing expresses "this after that". A monorepo build graph and an SLA deadline are both out of reach.
• One weight per item. Real bins run out of several things at once: a database shard has disk, connections and CPU. You pick the dimension that binds, or build a composite and accept it is a heuristic.
• No item-to-bin rules. You cannot forbid a pairing. Filter the bin list per item instead, which the support backlog page works through.