Angles.js is a small, dependency-free TypeScript library for normalized angles,
wrapped ranges, shortest-path interpolation, circular means, unit conversion,
compass labels, and directions derived from points.
Angles are expressed in a configurable number of units per full turn. The
default is 360, but 2 * Math.PI supports radians and 400 supports gradians.
All operations are exposed as static methods on the Angles class.
Installation
npm install angles
ES modules:
import Angles, { type CompassDirection, type PointTuple, type RotationDirection, type ShortestDirection,} from 'angles';Angles.SCALE = 360;console.log(Angles.normalize(-10)); // 350
SCALE is shared mutable state. Do not switch it between unit systems while
independent operations are running concurrently. Convert values explicitly
when an application uses multiple units at the same time.
Assigning zero, a negative value, NaN, or infinity throws a RangeError.
Normalization and comparison
Angles.normalize(angle)
Normalizes angle to the half-open interval [0, SCALE).
Exactly opposite angles use the normalized negative half-turn and therefore
return 1.
Angles.lerp(a, b, amount, direction?)
Interpolates from a to b. Without direction, the normalized shortest path
is used. Pass -1 to force clockwise movement or 1 to force
counter-clockwise movement.
Divides the full turn into equal regions and returns a one-based region index.
Points exactly on a region boundary return 0. Set regions to 4 for
quadrants or 8 for octants. shift rotates the region boundaries in current
angle units and may be positive or negative.
Angles.SCALE = 360;Angles.quadrant(1, 1); // 1Angles.quadrant(-1, 1); // 2Angles.quadrant(1, 0); // 0, on a boundaryAngles.quadrant(1, 0, 4, -45); // 4Angles.quadrant(1, 1, 8); // 0, on an octant boundary
The origin has no geometric direction, but follows Math.atan2(0, 0) and is
reported as boundary 0.
Angles.compass(course)
Returns the nearest eight-point compass label. Compass courses use north at
zero and increase through east, south, and west.
The result is one of "N", "NE", "E", "SE", "S", "SW", "W",
or "NW". Non-finite input returns undefined.
Circular mean
Angles.average(angles)
Returns the circular mean of an array or readonly array of angles. Unlike an
ordinary arithmetic mean, values on either side of the wrap boundary remain
close to each other.
npm test performs strict type checking, builds every distribution, validates
ESM and CommonJS type consumers, and runs the runtime and browser-format tests.
Build without running the tests:
npm run build
Copyright and licensing
Copyright (c) 2026, Robert Eisele
Licensed under the MIT license.