Numsy

Numsy validates, sanitizes, extracts and de-duplicates Indian mobile numbers from text, CSV and Excel. One engine powers four ways to use it, so they always agree.

Surface	Use it for	Start with
Library	A typed API inside your Node.js app	npm install numsy
CLI	Cleaning files from the terminal or CI	npx numsy@latest --help
Local dashboard	A browser UI on localhost:6789	numsy dashboard --open
Playground	The dashboard, entirely in your browser	Playground

Contents

#	Section	What's inside
1	Features	What Numsy checks, reads and writes
2	Install	Package, global CLI or npx
3	Quick start	First commands and first lines of code
4	Local dashboard	The browser UI and its options
5	Performance	Benchmarks at real-world volumes
6	Privacy	Where your data goes
7	Documentation	Guides on the website and in this repo
8	Community	Contributing, conduct and security
9	Built with Claude	How Numsy 2.x was made
10	License	MIT

Features

Turn messy contact data into clean, unique, valid Indian mobile numbers.

Capability	What it does
Validate	Accepts 10-digit numbers starting with 6, 7, 8 or 9; rejects repeats, sequences and dummies
Sanitize	Strips spaces, punctuation and the +91 / 0 prefix
Extract	Finds every number in free text
De-duplicate	Keeps all, the first or the last occurrence of each number
Read	CSV, Excel, plain text or stdin, with phone and name columns detected for you
Export	CSV, Excel, JSON, Markdown and Text

Install

One package gives you the library, the numsy CLI and the local dashboard. Works with npm, pnpm and Yarn.

Use	Command
Library	npm install numsy
Global CLI	npm install -g numsy
One-off run	npx numsy@latest --help

[!NOTE] Numsy moved from @numsy/numsy to numsy in 2.1.0. The API is the same; swap the package name and reinstall.

Quick start

Validate a few numbers, clean a whole sheet, or call the engine from code.

CLI

Command	Does
numsy validate <numbers…>	Validates each value
numsy extract <text…>	Finds every number in free text
numsy process <file>	Cleans a .csv or .xlsx file and exports the results
numsy dashboard	Starts the local dashboard and REST API
numsy formats	Lists the output formats

numsy validate 9876501234 "+91 98765 43210"
numsy process contacts.xlsx --dedupe --only valid -f csv,xlsx -d reports

Library

import { Numsy } from 'numsy';

const numsy = new Numsy({ enableLogging: false });
numsy.validate('+91 98765 01234'); // → { sanitized: '9876501234', isValid: true, … }

const report = await numsy.analyzeFile('contacts.xlsx', { dedupe: 'first' });
report.analytics; // → { totalValidNumbers, uniqueValidNumbers, duplicatesRemoved, … }

[!TIP] Every flag, method and exit code is in the CLI guide and the Library guide.

Local dashboard

numsy dashboard opens a browser UI on localhost:6789: drop in a file of up to 50 MB, filter it and export the rows you need.

Area	Options	CLI flags
Filters	Duplicates, dummy numbers, empty cells	--dedupe --loose --skip-empty
Columns	Detected or chosen phone and name columns	--column --name-column
Rows	All, valid, invalid, unique or duplicates	--only
Output	Number style, columns, header and row limit	--number-style --columns --max-rows
Export	CSV, Excel, JSON, Markdown, Text	-f

[!NOTE] The dashboard listens on 127.0.0.1 only, keeps uploads in memory and makes no requests to the internet. It also serves a REST API for scripts.

Performance

About 1.1 million validations per second.

Workload	Time
Validate 100,000 numbers	89 ms
Validate 1,000,000 numbers	0.82 s
Analyse and de-duplicate 500,000 rows	1.8 s
Real 11.7 MB Excel file, 505,277 rows	8.7 s to read, 2.2 s to analyse

[!NOTE] Measured on an AMD Ryzen 7 laptop with Node.js 24. The Performance guide has the method and shows how to run node scripts/benchmark.js yourself.

Privacy

Numsy never receives your data. Every surface runs on your computer or in your browser.

Surface	Runs on	Your data
Library	Your Node.js process	Stays in your process
CLI	Your terminal	Read from and written to your disk
Local dashboard	127.0.0.1:6789	Kept in memory, never sent out
Playground	A Web Worker in your browser	Never uploaded

[!IMPORTANT] Numsy does not store file contents, never sells or shares them, and never uses them for AI training. Read the privacy & data disclaimer.

Documentation

Every guide lives on the website and in this repository. Try things first in the Playground.

This is the beginning of the README. Read the rest at the original. Read the full README ↗