Complete NumPy implementation for TypeScript and JavaScript (81% API coverage)
npm install numpy-ts!License: MIT
!bundle size
!numpy api coverage
``
███╗ ██╗██╗ ██╗███╗ ███╗██████╗ ██╗ ██╗ ████████╗███████╗
████╗ ██║██║ ██║████╗ ████║██╔══██╗╚██╗ ██╔╝ ╚══██╔══╝██╔════╝
██╔██╗ ██║██║ ██║██╔████╔██║██████╔╝ ╚████╔╝█████╗██║ ███████╗
██║╚██╗██║██║ ██║██║╚██╔╝██║██╔═══╝ ╚██╔╝ ╚════╝██║ ╚════██║
██║ ╚████║╚██████╔╝██║ ╚═╝ ██║██║ ██║ ██║ ███████║
╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚══════╝
Complete NumPy implementation for TypeScript and JavaScript
⚠️ Under active development — API may change before v1.0
`bash`
npm install numpy-ts
- 📊 Extensive API — 411 of 507 NumPy functions (81.1% 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
`typescript
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:]
`
Progress toward complete NumPy API compatibility:
| Category | Complete | Total | Status |
|----------|----------|-------|--------|
| Arithmetic | 29/29 | 100% | ✅ |
| Array Creation | 35/35 | 100% | ✅ |
| Array Manipulation | 46/46 | 100% | ✅ |
| Bit Operations | 13/13 | 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% | ✅ |
| Linear Algebra | 15/15 | 100% | ✅ |
| Linear Algebra (linalg) | 31/31 | 100% | ✅ |
| Logic | 24/24 | 100% | ✅ |
| Other Math | 15/15 | 100% | ✅ |
| Polynomials | 10/10 | 100% | ✅ |
| Reductions | 36/36 | 100% | ✅ |
| Rounding | 7/7 | 100% | ✅ |
| Searching | 7/7 | 100% | ✅ |
| Set Operations | 12/12 | 100% | ✅ |
| Sorting | 6/6 | 100% | ✅ |
| Statistics | 11/11 | 100% | ✅ |
| Trigonometric | 16/16 | 100% | ✅ |
| Type Checking | 7/7 | 100% | ✅ |
| NDArray Methods | 40/53 | 75% | 🟡 |
| Utilities | 10/16 | 62% | 🟡 |
| Random | 17/53 | 32% | 🔴 |
| FFT | 0/18 | 0% | 🔴 |
| String/Formatting | 0/10 | 0% | 🔴 |
| Unplanned | 0/26 | 0% | 🔴 |
Overall: 411/507 functions (81.1% complete)
See the complete API Reference for detailed function list.
NumPy-compatible type system with automatic promotion:
| DType | NumPy | numpy-ts | Notes |
|-------|-------|----------|-------|
| Floating Point ||||
| float64 | ✅ | ✅ | Default dtype |float32
| | ✅ | ✅ | |float16
| | ✅ | ⚠️ | Planned (waiting for this) |int64
| Signed Integers ||||
| | ✅ | ✅ | Uses BigInt |int32
| | ✅ | ✅ | |int16
| | ✅ | ✅ | |int8
| | ✅ | ✅ | |uint64
| Unsigned Integers ||||
| | ✅ | ✅ | Uses BigInt |uint32
| | ✅ | ✅ | |uint16
| | ✅ | ✅ | |uint8
| | ✅ | ✅ | |bool
| Other Numeric ||||
| | ✅ | ✅ | Stored as uint8 |complex64
| | ✅ | ✅ | |complex128
| | ✅ | ✅ | |str_
| Non-Numeric ||||
| | ✅ | ❌ | Not planned |bytes_
| | ✅ | ❌ | Not planned |object_
| | ✅ | ❌ | Not planned |datetime64
| | ✅ | ❌ | Not planned |timedelta64
| | ✅ | ❌ | Not planned |
Supported: 13/20 numeric dtypes
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 |object_
| F-order memory layout | Exists in NumPy for Fortran/BLAS interop, which doesn't exist in JS |
| Object dtype () | Defeats the purpose of typed arrays; use regular JS arrays instead |str_
| String/Bytes dtypes (, 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.
- 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)
`typescript
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
`
`
┌─────────────────────────────────┐
│ 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.
See benchmarks/README.md for detailed performance analysis.
Read and write .npy and .npz files with Node.js or browsers.
`typescript
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');
`
`typescript
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.
`typescript
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
`
TypeScript doesn't support Python's arr[0:5, :], so we use strings:
`typescript
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]
`
`typescript``
const arr = np.zeros([3, 4]); // Type: NDArray
arr.shape; // Type: readonly [3, 4]
arr.sum(); // Type: number
| Feature | numpy-ts | numjs | ndarray | TensorFlow.js |
|---------|----------|-------|---------|---------------|
| NumPy API Coverage | 411/507 (81%) | ~20% | Different | ML-focused |
| TypeScript Native | ✅ Full | Partial | ❌ No | ✅ Yes |
| NumPy Validated | ✅ 4500+ tests | Mostly | ❌ No | ❌ No |
| .npy/.npz Files | ✅ v1/v2/v3 | ❌ No | ❌ No | ❌ No |
| Broadcasting | ✅ Full | Limited | Limited | ✅ Full |
| Bundle Size | <50kb | ~60kb | ~5kb | >100kb |
Contributions welcome! See CONTRIBUTING.md for detailed instructions on:
- Setting up the development environment
- Adding new functions with tests
- Running benchmarks
- Submitting pull requests
- 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
MIT License — Copyright (c) 2025 Nicolas Dupont
---
Bring NumPy to TypeScript! ⭐
GitHub • Issues • NumPy Docs