clamp-it

clamp-it

Clamps numbers to given bounds.

Install

npm install clamp-it --save

Motivation

You may find yourself needing a number to be at least a certain value. So you used Math.max():

value = Math.max(0, value); // make sure value is at least 0

You may find yourself needing a number to be at most a certain value. So you used Math.min():

value = Math.min(100, value); // value cannot exceed 100

You may find yourself needing a number to be within a closed range. So you used both Math.min() and Math.max():

value = Math.min(100, Math.min(0, value)); // value must be in [0, 100]

And you may ask yourself: How did we get here? Why am I using max to specify a minimum. Why am I using min to specify a maximum. This isn't my beautiful house! This isn't my beautiful wife!

Usage

Introducing clamp-it — clamps values using easy-to-understand language!

Need a number to be at least a certain value?

const { atLeast } = require("clamp-it");

// later:
value = atLeast(0).clamp(value);

Need a number to be at most a certain value?

const { atMost } = require("clamp-it");

// later:
value = atMost(100).clamp(value);

Need a number to be within a closed range?

const { within } = require("clamp-it");

// later:
value = within(0, 100).clamp(value);

Or even spicier: 🌶

const { atLeast } = require("clamp-it");

// later:
value = atLeast(0).atMost(100).clamp(value);

Do I really need this library?

No. You can clamp values the old-fashioned way with min() or max(). Or you could write helper functions that delegate to min() and max() like so (go ahead and copy-paste this):

function atLeast(bound, value) {
  return Math.max(bound, value);
}

function atMost(bound, value) {
  return Math.min(bound, value);
}

function within(lower, upper, value) {
  return Math.min(upper, Math.max(lower, value));
}

So why does this library exist?

I created this repo mostly as an exercise in API design and because I wanted to try property-based testing in TypeScript.

I wanted an API in which mistakes in its usage would be obvious. Hence the names atLeast(), atMost(), and within(). I wanted to be able to chain the atLeast() with atMost() to create a self-documenting way to specify a closed range.

I also tested a whole bunch of properties and had to decided whether using NaNs as a bound made any sense (spoilers: no).

I don't intend clamp-it to be used in production, but you absolutely can.