pointscape

**A collection of functions for working with points in a 2D coordinate system, along with additional utility functions.** [![CI](https://github.com/Arman2409/pointscape/actions/workflows/ci.yml/badge.svg)](https://github.com/Arman2409/pointscape/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/pointscape.svg)](https://www.npmjs.com/package/pointscape) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) **[Live demos →](https://arman2409.github.io/pointscape/)** ## Table of contents - [What's new](#whats-new-23x) - [How to use](#how-to-use) — install, imports, develops, publishes - [Examples](#examples) - [Point class](#point-class) - [Function reference](#the-list-of-available-functions) - [Changelog](./CHANGELOG.md) --- ## 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](./CHANGELOG.md#230--2026-05-29)). See **[CHANGELOG.md](./CHANGELOG.md)** for full notes. --- ## How to use Use **Node 18+**. The repo pins **Node 20** for development (**[`.nvmrc`](./.nvmrc)** — `nvm use` recommended). ### Install npm: ```bash npm install pointscape ``` pnpm / Yarn: ```bash 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`](./package.json). Import ESM with `import` or CommonJS with `require` per your bundler; types are exposed through [`exports`](./package.json) for both. 1. **Default import** — one object with every export (larger surface; fine for scripts). ```typescript import pointscape from "pointscape"; ``` 2. **Named imports** (preferred for tree-shaking) — see [Types and imports](#types-and-imports-typescript) below. ### Types and imports (TypeScript) Use **named imports** so bundlers can tree-shake unused functions: ```typescript 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`](./.github/workflows/ci.yml)**). ```bash 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](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files) — only `dist/`, readme, changelog, and license are published. ## Examples Most of the functions are designed for working with points in a 2D coordinate system. ```typescript import { distance, middle, angle, center, perimeter } from "pointscape"; const point1 = { x: 0, y: 0 }; const point2 = { x: 10, y: 10 }; // Plain { x, y } objects work for all point APIs const distanceBetweenPoints = distance(point1, point2); // result: 14.142135623730951 const middlePoint = middle(point1, point2); // result: {x: 5, y: 5} const angleBetweenPoints = angle(point1, point2); // result: 0.7853981633974483 const point3 = { x: 0, y: 10 }, point4 = { x: 10, y: 0 }; const perimeterOfPoints = perimeter([point1, point2, point3, point4]); // result: 48.2842712474619 ``` ### 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. ```typescript 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 — also 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. There are other utility functions as well. ```typescript import { inRange, chunk, randomBoolean } from "pointscape"; // Helper functions for math const isInTheRange = inRange(1, 0, 10); // result: true // Helper functions for arrays const chunks = chunk([1, 1, 1, 1], 2); // result: [[1, 1], [1, 1]] // Helper functions for randomization const randomBool = randomBoolean(); // result: true or false ``` ## The list of available functions ### Function Categories - [Points](#points) - [Geometry](#geometry) - [Positioning](#positioning) - [Relationships](#relationships) - [Math](#math) - [Arrays](#arrays) - [Randomization](#randomization) #### Points ##### Geometry [area](#geometry) [triangleArea](#geometry) [perimeter](#geometry) [center](#geometry) [square](#geometry) [rectangle](#geometry) [pentagon](#geometry) [triangle](#geometry) [circleArea](#geometry) [middle](#geometry) ##### Positioning [distance](#positioning) [positionInCircle](#positioning) [angle](#positioning) [nearest](#positioning) [randomPoint](#positioning) [randomPointInDistance](#positioning) [randomPoints](#positioning) [farthest](#positioning) [rotate](#positioning) [inLine](#positioning) [cross](#positioning) [move](#positioning) [lerp](#positioning) ##### Relationships [collision](#relationships) [collisionInArray](#relationships) [possibleConnections](#relationships) [sort](#relationships) [scale](#relationships) [pointWithoutCollision](#relationships) #### Math [degreesToRadians](#math) [radiansToDegrees](#math) [inRange](#math) [roundToPrecision](#math) [average](#math) #### Arrays [intersection](#arrays) [difference](#arrays) [chunk](#arrays) [removeDuplicate](#arrays) [sample](#arrays) #### Randomization [randomNumber](#randomization) [randomBoolean](#randomization) [uniqueId](#randomization) ## Function documentation ### Points - distance ```typescript 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 ```typescript (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 ```typescript (point1: Point, point2: Point, point3: Point) => number; ``` Returns the area of the triangle formed by three points. - collision ```typescript ( 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 ```typescript (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`](#collision). - positionInCircle ```typescript (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 ```typescript (point1: Point, point2: Point) => number; ``` Returns the angle formed by the connection of two points. - middle ```typescript (point1: Point, point2: Point) => Point; ``` Returns the midpoint between two points. - nearest ```typescript (point: Point, points: Point[]) => Point | null; ``` Returns the nearest point to the given point from the array, or **`null`** if **`points`** is empty. - perimeter ```typescript (points: Point[]) => number; ``` Returns the perimeter of the figure formed by the given points. - pointWithoutCollision(minX, maxX, minY, maxY, distance, points) ```typescript 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 ```typescript ([xBounds]: Bounds, [yBounds]: Bounds) => Point; ``` Returns a random point within the given dimensions, if provided, otherwise in 100 units on both axes. - randomPointInDistance ```typescript (point: Point, distance: number) => Point; ``` Returns a random point within the given distance from the specified point. - randomPoints ```typescript ([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 ```typescript (pointsCount: number) => number; ``` Returns the quantity of possible connections among given quantity of points. - circleArea ```typescript (radius: number) => number; ``` Returns the area of the circle given its radius. - center ```typescript (points: Point[]) => Point; ``` Returns the center of given points. - farthest ```typescript (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 ```typescript (points: Point[], centerPoint: Point, angleInRadians: number) => Point[] ``` Returns the points rotated around the given center point. - sort ```typescript (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 ```typescript (points: Point[], scaleFactorX: number, scaleFactorY: number) => Point[] ``` Returns the scaled points. - inLine ```typescript 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 ```typescript (line1: Line, line2: Line) => boolean; ``` Returns boolean value indicating if two lines each defined by two points intersect. - move ```typescript (point: Point, xStep: number, yStep: number) => Point; ``` Returns a point of with the new coordinates. - lerp ```typescript (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 ```typescript (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]) ```typescript (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](#square)). - triangle(point, size, [direction]) ```typescript (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](#square) function. - pentagon(center, radius, [angle]) ```typescript (centerPoint: Point, radius: number, angle?: number) => Point[] ``` Returns vertices of a pentagon around **`centerPoint`** with **`radius`** and rotation **`angle`** (degrees, default **`0`**). ### Math - degreesToRadians ```typescript (degrees: number) => number; ``` Converts degrees to radians. - radiansToDegrees ```typescript (radians: number) => number; ``` Converts radians to degrees. - inRange ```typescript (number: number, min: number, max: number) => boolean; ``` Returns true if the given number is within the specified range. - roundToPrecision ```typescript (number: number, precision: -100 | -10 | 0 | 10 | 100 | number) => number; ``` Rounds the number to the given precision. - average ```typescript (numbers: number[]) => number; ``` Returns the average of all numbers in an array. ### Arrays - intersection ```typescript (arr1: any[], arr2: any[]) => any[] ``` Returns the array of intersection of two arrays. - difference ```typescript (arr1: any[], arr2: any[]) => any[] ``` Returns the array of difference of two arrays. - chunk ```typescript (arr: any[], perArr: number) => any[][] ``` Returns an array splited into chunks based on elements count per chunk. - removeDuplicates(arr) ```typescript (arr: any[]) => any[] ``` Returns the array without duplicates. - sample ```typescript (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 ```typescript (min: number, max: number) => number; ``` Returns a random number within the given range. - randomBoolean ```typescript () => boolean; ``` Returns a random boolean value. - uniqueId ```typescript ([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.