@cutticat/math-extras

Numeric utilities and pagination library.

Table of Contents

• Overview
• Installation
• Quick Start
• API
• Documentation
• Requirements

Overview

The library provides:

• Numbers — clamp / clamp2d, inRange / inRange2d, mod, wrap, roundToStep / floorToStep / ceilToStep, lerp / inverseLerp / remap, percentage; types Range, Range2d, Point2d
• Pagination — three contexts (page + limit + optional totalPages / totalCount), normalization, page window, "showing X–Y" range

Installation

pnpm i @cutticat/math-extras

Quick Start

import {
  clamp,
  normalizePaginationContext,
  normalizeWindowPaginationContext,
  calculatePaginationWindow,
  calculateItemRange,
  defaultPaginationWindowLimit,
} from "@cutticat/math-extras"

normalizePaginationContext({ page: -1, limit: 0 }) // { page: 0, limit: 1 }

const windowContext = normalizeWindowPaginationContext({
  page: 4,
  totalPages: 9,
  limit: defaultPaginationWindowLimit,
})
calculatePaginationWindow(windowContext).indices // [2, 3, 4, 5, 6]

calculateItemRange({ page: 1, limit: 20, totalCount: 100 }) // { start: 21, end: 40 }

API

Numbers

• clamp(value, range?) — clamp by Range
• clamp2d(point, range?) — clamp by Range2d
• inRange(value, range) / inRange2d(point, range)
• mod(dividend, divisor) / wrap(index, length)
• roundToStep / floorToStep / ceilToStep
• lerp / inverseLerp / remap / percentage
• Types: Range, Range2d, Point2d

Pagination

Common fields: page (0-based), limit.

| Type | Fields | Purpose | | :-: | :-: | :-: | | PaginationContext | page, limit | DB / offset (page * limit) | | WindowPaginationContext | page, limit, totalPages | sliding window of page indices | | RangePaginationContext | page, limit, totalCount | "showing 21–40 of 100" |

Functions:

• normalizePaginationContext — page ≥ 0, limit ≥ 1
• normalizeWindowPaginationContext — for WindowPaginationContext
• normalizeRangePaginationContext — for RangePaginationContext
• calculatePaginationWindow(context, noNormalization?) — page indices in window
• calculateItemRange(context, noNormalization?) — 1-based { start, end }
• defaultPaginationWindowLimit — default limit for page window (5)

Aligns with PaginationSchema from @cutticat/zod-extras (limit, page); normalization lives here.

Documentation

• Project structure
• Scripts
• Style guide
• Contributing

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0