numpy-ts

Complete NumPy for TypeScript and JavaScript — npm install numpy-ts

1 — 概要
何か

numpy-ts は NumPy 2.0+ の API を TypeScript / JavaScript で再実装したライブラリ。476 の関数と全 NDArray メソッドを実装し、Zig-WASM カーネルによる高速演算を提供する。Node.js・Deno・Bun・ブラウザすべてで動作し、numpy-ts/core エントリポイント経由でツリーシェイキングにも対応している。

93.9%NumPy API Coverage
476実装済み関数
10K+Python NumPy 比較テスト
47/47NDArray メソッド

Python NumPy と同じ関数名・引数順序で動作し、既存の NumPy コードを TypeScript に移植する際の学習コストを最小化している。

01 / TYPE-SAFE
完全な型定義
すべての関数・メソッドに TypeScript 型定義を提供。dtype パラメータも型安全。
02 / UNIVERSAL
クロスランタイム
Node.js・Deno・Bun・ブラウザで動作。ESM + CJS 両形式を同梱。
03 / TREE-SHAKEABLE
~10 KB から始まる
numpy-ts/core なら使った関数だけがバンドルに含まれる。最小 ~11 KB。
04 / FAST
Zig-WASM カーネル
一部の演算は Python NumPy より速い。WASM バイナリはバンドルに同梱。
2 — アーキテクチャ
2 層構造

numpy-ts は core 層 と full 層 の 2 層設計を採用している。core 層は軽量な NDArrayCore を返し、full 層は NDArray（メソッドチェーン対応）を返す。すべての演算実装は common/ops/ に一元化されており、full 層はコアの薄いラッパーにすぎない。

flowchart TD
  UC["User Code"]:::user
  FI["full/index.ts
(NDArray)"]:::full
  CI["core/index.ts
(NDArrayCore)"]:::core
  OPS["common/ops/
Arithmetic / Shape / Reduction
LinAlg / FFT / Random ..."]:::ops
  ST["common/storage.ts
ArrayStorage
(TypedArray + shape + strides)"]:::storage
  WA["Zig-WASM Kernels
(高速演算)"]:::wasm

  UC --> FI
  UC --> CI
  FI --> CI
  CI --> OPS
  OPS --> ST
  OPS --> WA

  classDef user fill:#f0f4f7,stroke:#0d7fa3,color:#181b2e
  classDef full fill:#d8eef5,stroke:#0d7fa3,color:#181b2e
  classDef core fill:#fdf3d8,stroke:#c4981a,color:#181b2e
  classDef ops fill:#ddf0ea,stroke:#46997a,color:#181b2e
  classDef storage fill:#f9e5db,stroke:#b55c3a,color:#181b2e
  classDef wasm fill:#e0e4f0,stroke:#3a4a8c,color:#181b2e
ディレクトリ構造
src/
src/
├── common/                # 共有内部実装（直接エクスポートされない）
│   ├── ndarray-core.ts    # NDArrayCore クラス（データのみ）
│   ├── storage.ts         # ArrayStorage（TypedArray + shape + strides）
│   ├── dtype.ts           # DType ユーティリティ・昇格ルール
│   ├── broadcasting.ts    # ブロードキャスト演算
│   ├── slicing.ts         # スライス文字列のパース
│   └── ops/               # 低レベル演算（ArrayStorage を直接操作）
│       ├── arithmetic.ts  # add, subtract, multiply ...
│       ├── shape.ts       # reshape, transpose ...
│       ├── reduction.ts   # sum, mean, max ...
│       └── linalg.ts      # dot, matmul ...
│
├── core/                  # ツリーシェイカブルエントリ（NDArrayCore を返す）
│   ├── creation.ts        # zeros, ones, array ...
│   └── index.ts           # すべてを再エクスポート
│
├── full/                  # フルライブラリ（NDArray を返す）
│   ├── ndarray.ts         # NDArray（NDArrayCore を継承 + ~150 メソッド）
│   └── index.ts           # NDArrayCore → NDArray へのアップグレードラッパー
│
├── index.ts               # メインエントリ: export * from './full'
├── core.ts                # コアエントリ: export * from './core'
└── node.ts                # Node.js ファイル I/O 関数
NDArray vs NDArrayCore

NDArrayCore はデータと基本プロパティのみを保持する最小クラス。NDArray は NDArrayCore を継承し、約 150 の演算メソッド（.add(), .reshape() 等）を付与する。

ゼロコピー アップグレード: NDArray.from(core) は同じ ArrayStorage 参照を共有するため、データコピーが発生しない。core._storage === full._storage が常に成立する。
full/index.ts — アップグレードパターン
const up = (x: NDArrayCore): NDArray => NDArray.from(x);

export const zeros = (shape: number[], dtype?: DType): NDArray =>
  up(core.zeros(shape, dtype));

export const add = (a: ArrayLike, b: ArrayLike): NDArray =>
  up(core.add(a, b));
3 — エントリポイント
3 種類のインポートパス
インポートパス返却型バンドルサイズ用途
numpy-ts NDArray ~180 KB メソッドチェーン・NumPy ライクな構文。アプリケーションコード向け。
numpy-ts/core NDArrayCore ~11–40 KB ツリーシェイキング。ライブラリ内部実装向け。使った関数だけがバンドルされる。
numpy-ts/node NDArray ~180 KB + fs Node.js ファイル I/O（.npy / .npz 読み書き）を含む完全版。
使い分け例
// アプリ: メソッドチェーンが使える完全版
import * as np from 'numpy-ts';
const a = np.zeros([3, 3]);
a.add(1).multiply(2).sum();   // OK

// ライブラリ: ツリーシェイキング最優先
import { zeros, add } from 'numpy-ts/core';
const a = zeros([3, 3]);      // NDArrayCore（メソッドなし）
const b = add(a, 1);          // 関数スタイル

// Node.js: .npy ファイル I/O
import { loadNpy, saveNpy } from 'numpy-ts/node';
const arr = await loadNpy('./data.npy');
4 — 機能詳細
データ型（DType）

NumPy 互換の 11 種類の DType をサポート。自動型昇格ルールは NumPy に準拠する。

float64 float32 int64 int32 int16 int8 uint64 uint32 uint16 uint8 bool
型昇格ヒエラルキー: float64 > float32 > int64 > int32 > int16 > int8 > uint64 > uint32 > uint16 > uint8 > bool。比較演算は常に bool、mean() は整数配列でも float64 を返す。
dtype 指定と型昇格
const a = np.ones([3], 'int32');
const b = np.ones([3], 'float32');
const c = a.add(b);   // float32 に昇格

// int64 / uint64 は BigInt で表現
const d = np.array([1n, 2n, 3n], 'int64');

// 整数 dtype はオーバーフローで折り返す（NumPy 準拠）
const e = np.array([127], 'int8').add(1);
console.log(e.get([0]));  // -128
ブロードキャスト

NumPy 完全互換のブロードキャスト。形状が異なる配列同士の演算をゼロコピーで実現する。

形状互換ルール

  1. 配列の次元数が異なる場合、小さい方の先頭に 1 を詰める
  2. 各次元が等しいか、どちらかが 1 の場合に互換
  3. 出力形状は各次元の最大値

ブロードキャスト例

(3, 4) + (4,) → (3, 4)
(3, 1) × (1, 4) → (3, 4) 外積
(3, 1, 4) + (2, 1) → (3, 2, 4)
ビューセマンティクス

NumPy 準拠のビュー（別名配列）を実装。ビューを変更すると元配列のデータが書き換わる。

操作ビュー / コピー備考
slice()ビュー（可能な場合）ストライドで表現できない場合はコピー
transpose()常にビューstrides を逆順にするだけ
reshape()C-contiguous ならビュー転置後などは非連続でコピーになる
broadcast_to()常にビューstride = 0 で仮想的に拡張
flatten()常にコピー平坦な新配列を返す
ビューの確認
const arr = np.ones([4, 4]);
const view = arr.slice('0:2', '0:2');

console.log(view.base === arr);    // true — ビュー
console.log(view.flags.OWNDATA);   // false
console.log(arr.flags.OWNDATA);    // true

// ビューへの書き込みが元配列に反映される
view.set([0, 0], 99);
console.log(arr.get([0, 0]));      // 99
スライス構文

TypeScript は Python の arr[0:5, :] 構文をサポートしないため、numpy-ts は文字列でスライスを表現する。

スライス記法
// 単一次元
arr.slice(':')        // arr[:]
arr.slice('0:5')      // arr[0:5]
arr.slice('::2')      // arr[::2]（1 つ飛ばし）
arr.slice('::-1')     // arr[::-1]（逆順）
arr.slice('-1')       // arr[-1]（末尾）

// 多次元
arr.slice('0:5', ':')           // arr[0:5, :]
arr.slice(':', '1:3')           // arr[:, 1:3]
arr.slice('0:10:2', '5:10:1')   // arr[0:10:2, 5:10:1]

// ショートカット
arr.row(0)            // arr[0, :]
arr.col(2)            // arr[:, 2]
arr.rows(0, 5)        // arr[0:5, :]
arr.cols(1, 3)        // arr[:, 1:3]
5 — クイックスタート
インストール
shell
npm install numpy-ts
基本的な使い方
TypeScript
import * as np from 'numpy-ts';

// 配列生成（dtype 指定可）
const A = np.array([[1, 2], [3, 4]], 'float32');
const B = np.ones([2, 2], 'int32');
const C = np.arange(0, 10, 1, 'float32');  // [0, 1, 2, ..., 9]

// ブロードキャスト・メソッドチェーン
const result = A.add(5).multiply(2);      // [[12,14],[16,18]]

// 線形代数
const D = A.matmul(B);   // 行列積
const trace = A.trace(); // 対角和

// 軸を指定した集約
const colMeans = A.mean(0);  // [2.0, 3.0]（列平均）
const rowSums  = A.sum(1);   // [3, 7]  （行合計）

// スライス
const row = A.slice('0', ':');           // A[0, :] → [1, 2]
const sub  = A.slice('0:2', '1:');       // A[0:2, 1:] → [[2],[4]]
コアエントリでのツリーシェイキング
TypeScript — numpy-ts/core
// ~11 KB: zeros と add だけバンドルされる
import { zeros, add } from 'numpy-ts/core';

const a = zeros([1000, 1000]);  // NDArrayCore
const b = add(a, 1);            // 関数スタイル（メソッドチェーン不可）

// NDArrayCore のプロパティ
console.log(a.shape);    // [1000, 1000]
console.log(a.dtype);    // 'float64'
console.log(a.ndim);     // 2
console.log(a.size);     // 1000000
6 — API カバレッジ
全体サマリ
476/507トップレベル関数
47/47NDArray メソッド
29完了カテゴリ
31未実装（Unplanned）

最終更新: 2026-02-16。未実装の 31 関数は Unplanned カテゴリとして分類されており、コア演算への影響は軽微。

100% 完了カテゴリ
✓ Arithmetic (29/29)
✓ Array Creation (35/35)
✓ Array Manipulation (46/46)
✓ Bit Operations (13/13)
✓ Broadcasting (3/3)
✓ Comparison (10/10)
✓ Exponential (9/9)
✓ FFT (18/18)
✓ Gradient (4/4)
✓ Hyperbolic (9/9)
✓ I/O (8/8)
✓ Indexing (21/21)
✓ Linear Algebra (16/16)
✓ linalg (31/31)
✓ Logic (24/24)
✓ NDArray Methods (47/47)
✓ Other Math (15/15)
✓ Polynomials (10/10)
✓ Printing (10/10)
✓ Random (53/53)
✓ Reductions (36/36)
✓ Rounding (7/7)
✓ Searching (7/7)
✓ Set Operations (12/12)
✓ Sorting (6/6)
✓ Statistics (11/11)
✓ Trigonometric (16/16)
✓ Type Checking (7/7)
✓ Utilities (10/10)
参考リンク