numpy-ts

███╗   ██╗██╗   ██╗███╗   ███╗██████╗ ██╗   ██╗  ████████╗███████╗
████╗  ██║██║   ██║████╗ ████║██╔══██╗╚██╗ ██╔╝  ╚══██╔══╝██╔════╝
██╔██╗ ██║██║   ██║██╔████╔██║██████╔╝ ╚████╔╝█████╗██║   ███████╗
██║╚██╗██║██║   ██║██║╚██╔╝██║██╔═══╝   ╚██╔╝ ╚════╝██║   ╚════██║
██║ ╚████║╚██████╔╝██║ ╚═╝ ██║██║        ██║        ██║   ███████║
╚═╝  ╚═══╝ ╚═════╝ ╚═╝     ╚═╝╚═╝        ╚═╝        ╚═╝   ╚══════╝

Complete NumPy implementation for TypeScript and JavaScript

⚠️ Under active development — API may change before v1.0

npm install numpy-ts

Why numpy-ts?

• 📊 Extensive API — 336 of 507 NumPy functions (66.3% coverage)
• ✅ NumPy-validated — 3000+ test cases cross-validated against Python NumPy
• 🔒 Type-safe — Full TypeScript support with shape and dtype inference
• 🌐 Universal — Works in Node.js and browsers with .npy/.npz file support
• 🎯 Zero dependencies — Pure TypeScript, no heavy external libraries

Quick Start

import * as np from 'numpy-ts';

// Array creation with dtype support
const A = np.array([[1, 2], [3, 4]], 'float32');
const B = np.ones([2, 2], 'int32');

// Broadcasting and chained operations
const result = A.add(5).multiply(2);

// Linear algebra
const C = A.matmul(B);
const trace = A.trace();

// Reductions with axis support
const colMeans = A.mean(0);  // [2.0, 3.0]

// NumPy-style slicing with strings
const row = A.slice('0', ':');    // A[0, :]
const submatrix = A.slice('0:2', '1:');  // A[0:2, 1:]

Features

API Coverage

Progress toward complete NumPy API compatibility:

Category	Complete	Total	Status
Arithmetic	29/29	100%	✅
Broadcasting	3/3	100%	✅
Comparison	10/10	100%	✅
Exponential	9/9	100%	✅
Gradient	4/4	100%	✅
Hyperbolic	9/9	100%	✅
I/O	8/8	100%	✅
Indexing	21/21	100%	✅
Logic	24/24	100%	✅
Rounding	7/7	100%	✅
Searching	7/7	100%	✅
Sorting	6/6	100%	✅
Trigonometric	16/16	100%	✅
Reductions	34/36	94%	🟡
Array Creation	33/35	94%	🟡
Array Manipulation	37/46	80%	🟡
Statistics	9/12	75%	🟡
Bit Operations	9/13	69%	🟡
NDArray Methods	34/53	64%	🟡
Linear Algebra (linalg)	19/31	61%	🟡
Linear Algebra	9/15	60%	🟡
Set Operations	7/12	58%	🟡
Other Math	5/15	33%	🔴
Random	17/53	32%	🔴
Utilities	4/16	25%	🔴
FFT	0/18	0%	🔴
Polynomials	0/10	0%	🔴
String/Formatting	0/10	0%	🔴
Type Checking	0/7	0%	🔴
Unplanned	0/25	0%	🔴

Overall: 336/507 functions (66.3% complete)

See the complete API Reference for detailed function list.

Data Types (dtypes)

NumPy-compatible type system with automatic promotion:

DType	NumPy	numpy-ts	Notes
Floating Point
float64	✅	✅	Default dtype
float32	✅	✅
float16	✅	⚠️	Planned (waiting for this)
Signed Integers
int64	✅	✅	Uses BigInt
int32	✅	✅
int16	✅	✅
int8	✅	✅
Unsigned Integers
uint64	✅	✅	Uses BigInt
uint32	✅	✅
uint16	✅	✅
uint8	✅	✅
Other Numeric
bool	✅	✅	Stored as uint8
complex64	✅	✅
complex128	✅	✅
Non-Numeric
str_	✅	❌	Not planned
bytes_	✅	❌	Not planned
object_	✅	❌	Not planned
datetime64	✅	❌	Not planned
timedelta64	✅	❌	Not planned

Supported: 13/20 numeric dtypes

Intentional Divergences from NumPy

numpy-ts focuses on numeric array computing. The following NumPy features are not planned:

Feature	Why Not Included
Datetime/Timedelta (datetime64, timedelta64)	JS has native Date; libraries like date-fns handle time math better
F-order memory layout	Exists in NumPy for Fortran/BLAS interop, which doesn't exist in JS
Object dtype (object_)	Defeats the purpose of typed arrays; use regular JS arrays instead
String/Bytes dtypes (str_, bytes_, U, S)	JS strings are first-class; no need for fixed-width string arrays

These omissions keep the library focused and the bundle small. For string manipulation, datetime math, or heterogeneous data, use native JS/TS constructs alongside numpy-ts.

NumPy Memory Model

• View tracking — base attribute and OWNDATA flag
• Strided arrays — C/F contiguous flags for memory layout
• Zero-copy ops — Views for slicing, transpose, reshape (when possible)

const arr = np.ones([4, 4]);
const view = arr.slice('0:2', '0:2');

console.log(view.base === arr);      // true - view tracks base
console.log(view.flags.OWNDATA);     // false - doesn't own data
console.log(arr.flags.C_CONTIGUOUS); // true - row-major layout

Architecture

┌─────────────────────────────────┐
│  NumPy-Compatible API           │
│  Broadcasting, DType Promotion  │
└───────────────┬─────────────────┘
                │
┌───────────────┴─────────────────┐
│  NDArray (Views & Memory Mgmt)  │
│  Strided Arrays, Base Tracking  │
└───────────────┬─────────────────┘
                │- - - - - - - - - - - - - - - - - - ┐  
┌───────────────┴─────────────────┐  ┌ ─ ─ ─ ─ ─ ─ ─ ┴ ─ ─ ─ ─ ─ ─ ─ ─┐
│  TypeScript / JavaScript Core   │  │  WASM Compute Engine (Future)  │
│  Computational Engine           │  │  Optimized BLAS / arithmetic   │
└─────────────────────────────────┘  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┘

Pure TypeScript implementation built from scratch for correctness and NumPy compatibility.

Performance

See benchmarks/README.md for detailed performance analysis.

File I/O

Read and write .npy and .npz files with Node.js or browsers.

Node.js

import { load, save, savez, savez_compressed } from 'numpy-ts/node';

save('array.npy', arr);
const arr = load('array.npy');

savez('arrays.npz', { a: arr1, b: arr2 });
const { a, b } = load('arrays.npz');

Browser

import * as np from 'numpy-ts';

// Parse fetched .npy file
const response = await fetch('array.npy');
const arr = np.parseNpy(await response.arrayBuffer());

// Serialize for download
const bytes = np.serializeNpy(arr);

Why separate imports? The /node entry includes Node.js fs usage. Keeping it separate ensures browser bundles stay clean.

Examples

Broadcasting

const matrix = np.ones([3, 4]);     // (3, 4)
const row = np.arange(4);           // (4,)
const result = matrix.add(row);     // (3, 4) - row broadcast to each row

const col = np.array([[1], [2], [3]]);  // (3, 1)
const grid = col.multiply(row);         // (3, 4) - outer product via broadcasting

Slicing

TypeScript doesn't support Python's arr[0:5, :], so we use strings:

arr.slice('0:5', '1:3');     // arr[0:5, 1:3]
arr.slice(':', '-1');        // arr[:, -1]
arr.slice('::2');            // arr[::2]

// Convenience helpers
arr.row(0);                  // arr[0, :]
arr.col(2);                  // arr[:, 2]

Type Safety

const arr = np.zeros([3, 4]);  // Type: NDArray<Float64>
arr.shape;  // Type: readonly [3, 4]
arr.sum();  // Type: number

Comparison with Alternatives

Feature	numpy-ts	numjs	ndarray	TensorFlow.js
NumPy API Coverage	336/507 (66%)	~20%	Different	ML-focused
TypeScript Native	✅ Full	Partial	❌ No	✅ Yes
NumPy Validated	✅ 1365+ tests	Mostly	❌ No	❌ No
.npy/.npz Files	✅ v1/v2/v3	❌ No	❌ No	❌ No
Broadcasting	✅ Full	Limited	Limited	✅ Full
Bundle Size	<50kb	~60kb	~5kb	>100kb

Contributing

Contributions welcome! See CONTRIBUTING.md for detailed instructions on:

• Setting up the development environment
• Adding new functions with tests
• Running benchmarks
• Submitting pull requests

Documentation

• API Reference — Complete function checklist (120+ functions)
• Feature Details — Broadcasting, dtypes, views, slicing
• Contributing Guide — How to contribute
• Testing Guide — Testing strategy and examples
• Architecture — System design and internals

License

MIT License — Copyright (c) 2025 Nicolas Dupont

---

Bring NumPy to TypeScript! ⭐ GitHub • Issues • NumPy Docs