A collection of functions for working with points in a 2D coordinate system, along with additional utility functions.

Live demos →

Table of contents

• What's new
• How to use — install, imports, develops, publishes
• Examples
• Point class
• Function reference
• Changelog

---

What's new (2.3.0)

• scale and rotate argument order — points array comes first: scale(points, factorX, factorY) and rotate(points, center, angle).
• Source maps — published builds include .map files for easier debugging.

Upgrading from 2.2.x? Swap argument order for scale and rotate (see CHANGELOG).

See CHANGELOG.md for full notes.

---

How to use

Use Node 18+. The repo pins Node 20 for development (.nvmrc — nvm use recommended).

Install

npm:

npm install pointscape

pnpm / Yarn:

pnpm add pointscape
# or
yarn add pointscape

What ships on npm

The published tarball contains only dist/ (ESM + CJS + types), README, CHANGELOG, and LICENSE—see package.json → files. Import ESM with import or CommonJS with require per your bundler; types are exposed through exports for both.

1. Default import — one object with every export (larger surface; fine for scripts).

import pointscape from "pointscape";

2. Named imports (preferred for tree-shaking) — see Types and imports below.

Types and imports (TypeScript)

Use named imports so bundlers can tree-shake unused functions:

import { distance, collision, nearest, Point } from "pointscape";
import type { Bounds, Line, PointType } from "pointscape";

Functions take any { x: number; y: number }; you do not have to allocate a Point class instance. PointType matches instances of Point (the class exported from this package).

Developing

Open a PR against the default branch; CI runs npm ci, tests, and npm run build on every push/PR (see .github/workflows/ci.yml).

git clone https://github.com/Arman2409/pointscape.git
cd pointscape
nvm use   # optional: picks Node from .nvmrc
npm ci
npm test
npm run build

Publishing on npm

1. Bump version in package.json and update CHANGELOG.md.
2. npm login with an account that [maintains pointscape\*\*](https://www.npmjs.com/package/pointscape) on the public registry (https://registry.npmjs.org/`).
3. npm publish — the prepack script rebuilds dist/ first.

Preview tarball contents locally: npm run publish:dry-run.

See also npm files publish guide — only dist/, readme, changelog, and license are published.

Examples

Most functions work with plain { x, y } objects — no class allocation needed.

Collision detection

import { collision, collisionInArray } from "pointscape";

const player = { x: 0, y: 0 };
const enemy  = { x: 3, y: 4 };  // exactly 5 units away

collision(player, enemy, 5);  // true  — within radius
collision(player, enemy, 4);  // false — outside radius

// Optional callback fires on hit
collision(player, enemy, 5, () => console.log("hit!"));

// Batch: all targets within radius 3 of origin
const targets = [{ x: 1, y: 0 }, { x: 5, y: 0 }, { x: 3, y: 0 }];
collisionInArray({ x: 0, y: 0 }, targets, 3);
// [{ x: 1, y: 0 }, { x: 3, y: 0 }]

Nearest & farthest

import { nearest, farthest } from "pointscape";

const origin = { x: 0, y: 0 };
const pts    = [{ x: 5, y: 0 }, { x: 1, y: 0 }, { x: 10, y: 0 }];

nearest(origin, pts);   // { x: 1, y: 0 }
farthest(origin, pts);  // { x: 10, y: 0 }
nearest(origin, []);    // null

Movement & interpolation

import { move, lerp } from "pointscape";

move({ x: 5, y: 5 }, 3, -2);
// { x: 8, y: 3 }

// 25 % of the way from A to B — useful for smooth animation
lerp({ x: 0, y: 0 }, { x: 20, y: 40 }, 0.25);
// { x: 5, y: 10 }

// Midpoint (equivalent to middle())
lerp({ x: 0, y: 0 }, { x: 20, y: 40 }, 0.5);
// { x: 10, y: 20 }

Point geometry

import { distance, middle, angle, center, perimeter } from "pointscape";

const a = { x: 0, y: 0 };
const b = { x: 10, y: 10 };

distance(a, b);   // 14.142135623730951
middle(a, b);     // { x: 5, y: 5 }
angle(a, b);      // 0.7853981633974483  (π/4 radians)

const points = [a, b, { x: 0, y: 10 }, { x: 10, y: 0 }];
center(points);    // { x: 5, y: 5 }
perimeter(points); // 48.2842712474619

Rotation & scaling

Argument order changed in 2.3.0 — points array is always first.

import { rotate, scale, degreesToRadians } from "pointscape";

const box = [{ x: 10, y: 0 }, { x: 10, y: 10 }, { x: 0, y: 10 }, { x: 0, y: 0 }];

// Rotate 90 ° around the origin
rotate(box, { x: 0, y: 0 }, degreesToRadians(90));
// Each vertex rotated — e.g. { x: 10, y: 0 } becomes { x: 0, y: 10 }

// Double width, halve height
scale(box, 2, 0.5);
// [{ x: 20, y: 0 }, { x: 20, y: 5 }, { x: 0, y: 5 }, { x: 0, y: 0 }]

Area calculations

import { area, triangleArea, circleArea } from "pointscape";

// Polygon area — rectangle 4 × 3
area([{ x: 0, y: 0 }, { x: 4, y: 0 }, { x: 4, y: 3 }, { x: 0, y: 3 }]);
// 12

triangleArea({ x: 0, y: 0 }, { x: 6, y: 0 }, { x: 3, y: 4 });
// 12

circleArea(5);
// 78.53981633974483

Shape generators

import { square, rectangle, triangle, pentagon } from "pointscape";

// 4 vertices of a 10-unit square (clockwise from origin)
square({ x: 0, y: 0 }, 10);
// [{ x:0,y:0 }, { x:10,y:0 }, { x:10,y:-10 }, { x:0,y:-10 }]

// Rectangle 10 wide × 5 tall
rectangle({ x: 0, y: 0 }, 10, 5);
// [{ x:0,y:0 }, { x:10,y:0 }, { x:10,y:-5 }, { x:0,y:-5 }]

// Triangle vertices, size 10, default direction "left"
triangle({ x: 0, y: 0 }, 10);

// Pentagon centred at (50, 50) with radius 30
pentagon({ x: 50, y: 50 }, 30);  // 5 evenly-spaced vertices

Point class

The Point class wraps any { x, y } and exposes all geometric operations as chainable methods. Every method that returns a point returns a Point instance, so calls can be chained.

import { Point } from "pointscape";

const a = new Point(10, 20);
const b = new Point(50, 80);

// Basic methods
a.distanceTo(b);  // 72.11...
a.angleTo(b);     // number in radians
a.equals(b);      // false
a.clone();        // Point(10, 20)
a.toString();     // "Point(10, 20)"

// Factory — convert a plain { x, y } to a Point instance
const c = Point.from({ x: 0, y: 0 });

// Chainable — move() and lerp() return Point instances
a.move(5, -5)       // Point(15, 15)
    .lerp(b, 0.5)   // Point(32.5, 47.5)
    .distanceTo(b); // number

// Rotate a point around a center
a.rotateAround({ x: 0, y: 0 }, Math.PI); // Point(-10, -20)

// Array-based methods — return Point or Point | null
a.nearestFromPoints([b, c]);  // Point | null
a.farthestFromPoints([b, c]); // Point | null

Plain { x: number; y: number } objects work for every function — you don't need to allocate a Point instance unless you want the method API.

Lines & circular positioning

import { inLine, cross, positionInCircle } from "pointscape";

// Is (5, 5) on the line from (0, 0) to (10, 10)?
inLine({ x: 5, y: 5 }, { start: { x: 0, y: 0 }, end: { x: 10, y: 10 } });
// true

// Do two diagonals intersect?
cross(
    { start: { x: 0, y: 0 },  end: { x: 10, y: 10 } },
    { start: { x: 0, y: 10 }, end: { x: 10, y: 0 } }
);
// true

// Point on a circle of radius 10 at angle 0 (rightmost)
positionInCircle({ x: 0, y: 0 }, 10, 0);
// { x: 10, y: 0 }

Sorting points

import { sort } from "pointscape";

const pts = [{ x: 3, y: 1 }, { x: 1, y: 3 }, { x: 2, y: 2 }];

sort([...pts]);        // by x → [{ x:1,y:3 }, { x:2,y:2 }, { x:3,y:1 }]
sort([...pts], "y");   // by y → [{ x:3,y:1 }, { x:2,y:2 }, { x:1,y:3 }]
// Note: sort mutates the array in place.

Math utilities

import { degreesToRadians, radiansToDegrees, roundToPrecision, average, inRange } from "pointscape";

degreesToRadians(180);      // 3.141592653589793
radiansToDegrees(Math.PI);  // 180

roundToPrecision(3.14159, 2);  // 3.14
roundToPrecision(3.14159, 0);  // 3

average([10, 20, 30, 40]);  // 25

inRange(5, 0, 10);   // true
inRange(15, 0, 10);  // false

Array utilities

import { intersection, difference, removeDuplicates, chunk, sample } from "pointscape";

intersection([1, 2, 3, 4], [3, 4, 5, 6]);  // [3, 4]
difference([1, 2, 3, 4], [3, 4, 5, 6]);    // [1, 2]
removeDuplicates([1, 1, 2, 3, 3, 4]);      // [1, 2, 3, 4]
chunk([1, 2, 3, 4, 5, 6], 2);              // [[1, 2], [3, 4], [5, 6]]

sample([10, 20, 30, 40, 50]);     // one random element, e.g. 30
sample([10, 20, 30, 40, 50], 3);  // 3 consecutive elements, e.g. [20, 30, 40]

Randomization

import { randomNumber, randomBoolean, uniqueId } from "pointscape";

randomNumber(1, 10);   // random integer in [1, 10], e.g. 7
randomBoolean();       // true or false

uniqueId();                       // e.g. "110e8400-e29b-41d4-a716-446655440000"
uniqueId(["id-1", "id-2"]);       // UUID guaranteed not to collide with the provided ids

The list of available functions

Function Categories

• Points
  • Geometry
  • Positioning
  • Relationships
• Math
• Arrays
• Randomization

Points

Geometry

area

triangleArea

perimeter

center

square

rectangle

pentagon

triangle

circleArea

middle

Positioning

distance

positionInCircle

angle

nearest

randomPoint

randomPointInDistance

randomPoints

farthest

rotate

inLine

cross

move

lerp

Relationships

collision

collisionInArray

possibleConnections

sort

scale

pointWithoutCollision

Math

degreesToRadians

radiansToDegrees

inRange

roundToPrecision

average

Arrays

intersection

difference

chunk

removeDuplicate

sample

Randomization

randomNumber

randomBoolean

uniqueId

Function documentation

Points

• distance

interface Point {
    x: number;
    y: number;
}

(point1: Point, point2: Point) => number;

Returns the distance beetween two points, each point is an object with x and y properties.

• area

(points: Point[]) => number;

Returns the area enclosed by the given points. Takes an array of points as argument, where each point is an object with x and y properties.

• triangleArea

(point1: Point, point2: Point, point3: Point) => number;

Returns the area of the triangle formed by three points.

• collision

(
    point1: Point,
    point2: Point,
    collisionDistance: number,
    [callback]?: () => void
) => boolean;

Returns true if the Euclidean distance between the two points is less than or equal to collisionDistance (treat collisionDistance as a non-negative radius for a circle around each position). Optionally invokes callback when a collision is detected.

• collisionInArray

  (initialPoint: Point, points: Point[], radius: number) => Point[]

Returns every point in points whose distance to initialPoint is within radius, using the same circular rule as collision.

• positionInCircle

(point: Point, radius: number, angleInRadians: number) => Point;

Returns the x and y coordinates for the current point in the circle, given its center point, radius, and angle.

• angle

(point1: Point, point2: Point) => number;

Returns the angle formed by the connection of two points.

• middle

(point1: Point, point2: Point) => Point;

Returns the midpoint between two points.

• nearest

(point: Point, points: Point[]) => Point | null;

Returns the nearest point to the given point from the array, or null if points is empty.

• perimeter

(points: Point[]) => number;

Returns the perimeter of the figure formed by the given points.

• pointWithoutCollision(minX, maxX, minY, maxY, distance, points)

interface Bounds {
    min: number;
    max: number;
}

(xBounds: Bounds, yBounds: Bounds, distance: number, points: Point[]) =>
    Point | string;

Returns a point that doesn't collide with any of the given points within the specified distance, if such a point exists, otherwise returns error string.

• randomPoint

([xBounds]: Bounds, [yBounds]: Bounds) => Point;

Returns a random point within the given dimensions, if provided, otherwise in 100 units on both axes.

• randomPointInDistance

(point: Point, distance: number) => Point;

Returns a random point within the given distance from the specified point.

• randomPoints

   ([xBounds]: Bounds, [yBounds]: Bounds, quantity: number,) => Point[]

Returns a specified quantity of random points within the given dimensions, if dimensions are provided, otherwise in the range of 100.

• possibleConnections

(pointsCount: number) => number;

Returns the quantity of possible connections among given quantity of points.

• circleArea

(radius: number) => number;

Returns the area of the circle given its radius.

• center

(points: Point[]) => Point;

Returns the center of given points.

• farthest

(point: Point, points: Point[]) => Point | null;

Returns the farthest point from the given point among the given array; null if the array is empty.

• rotate

  (points: Point[], centerPoint: Point, angleInRadians: number) => Point[]

Returns the points rotated around the given center point.

• sort

  (points: Point[], coordinate?: "x" | "y") => Point[]

Mutates points in place (Array.sort) and returns the same array reference. Omit coordinate to sort primarily by x; "y" sorts by y.

• scale

  (points: Point[], scaleFactorX: number, scaleFactorY: number) => Point[]

Returns the scaled points.

• inLine

interface Line {
    start: Point;
    end: Point;
}

(point: Point, line: Line) => boolean;

Returns boolean value indicating whether or not the given coordinates are on line defined by two other points.

• cross

(line1: Line, line2: Line) => boolean;

Returns boolean value indicating if two lines each defined by two points intersect.

• move

(point: Point, xStep: number, yStep: number) => Point;

Returns a point of with the new coordinates.

• lerp

(point1: Point, point2: Point, t: number) => Point;

Returns the linearly interpolated point between point1 and point2 at parameter t (0 = point1, 1 = point2, 0.5 = midpoint). Values of t outside [0, 1] extrapolate beyond the two points.

• square

 (point: Point, size: number, [direction]: "left" | "right" | "down" | "up" ) => Point[]

Returns an array of points representing a shape of square.Takes four parameters: starting coordinates (x and y), size of square side, and direction which should be one of the values "left", "right", "up", "down".

• rectangle(point, width, height, [direction])

 (point: Point, width: number, height: number, [direction]: "left" | "right" | "down" | "up" ) => Point[]

Returns vertices of a rectangle starting at point, advancing width then height along the directional path (same directional convention as square).

• triangle(point, size, [direction])

 (point: Point, size: number, [direction]: "left" | "right" | "down" | "up" ) => Point[]

Returns an array of points representing a shape of triangle.Takes same parameters as square function.

• pentagon(center, radius, [angle])

 (centerPoint: Point, radius: number, angle?: number) => Point[]

Returns vertices of a pentagon around centerPoint with radius and rotation angle (degrees, default 0).

Math

• degreesToRadians

(degrees: number) => number;

Converts degrees to radians.

• radiansToDegrees

(radians: number) => number;

Converts radians to degrees.

• inRange

(number: number, min: number, max: number) => boolean;

Returns true if the given number is within the specified range.

• roundToPrecision

(number: number, precision: -100 | -10 | 0 | 10 | 100 | number) => number;

Rounds the number to the given precision.

• average

(numbers: number[]) => number;

Returns the average of all numbers in an array.

Arrays

• intersection

 (arr1: any[], arr2: any[]) => any[]

Returns the array of intersection of two arrays.

• difference

 (arr1: any[], arr2: any[]) => any[]

Returns the array of difference of two arrays.

• chunk

 (arr: any[], perArr: number) => any[][]

Returns an array splited into chunks based on elements count per chunk.

• removeDuplicates(arr)

 (arr: any[]) => any[]

Returns the array without duplicates.

• sample

  (arr: any[], [size]: number[]) => any[]

Returns a random sample from an array with optional size argument for sampling length. If not specified, it returns only one element.

Randomization

• randomNumber

(min: number, max: number) => number;

Returns a random number within the given range.

• randomBoolean

() => boolean;

Returns a random boolean value.

• uniqueId

  ([other ids]: string[]) => string

Returns a unique ID that's different from the provided IDs, or a random ID if no other IDs are given.