numpy-ts supports the same file formats as NumPy: .npy (single array), .npz (multiple arrays), and delimited text files. All functions are available from the main numpy-ts entry point.
| Category | File-based (Node / Bun / Deno) | Buffer-based (all environments) |
|---|
.npy | loadNpy / loadNpySync / saveNpy / saveNpySync | serializeNpy / parseNpy |
.npz | loadNpzFile / loadNpzFileSync / saveNpzFile / saveNpzFileSync / savez / savez_compressed | serializeNpz / parseNpz |
| Auto-detect | load / loadSync / save / saveSync | — |
| Text (CSV, TSV) | loadtxt / loadtxtSync / savetxt / savetxtSync | serializeTxt / parseTxt |
| Text (flexible) | genfromtxtFile / genfromtxtFileSync / fromregexFile / fromregexFileSync | genfromtxt / fromregex |
File-based functions read and write files on disk and require a server runtime (Node.js, Bun, or Deno). In the browser, they throw: “File IO requires Node.js, Bun, or Deno. In the browser, use parseNpy(buffer) / parseTxt(text) with fetch() instead.” Buffer-based functions work with ArrayBuffer, Uint8Array, and strings in all environments.
numpy-ts/node still works but is a deprecated alias for numpy-ts. Update your imports to from 'numpy-ts'.
NPY files (single array)
The .npy format stores a single array with its dtype and shape metadata.
import { array, save, load } from 'numpy-ts';
const a = array([[1, 2, 3], [4, 5, 6]]);
// Save to disk
await save('matrix.npy', a);
// Load from disk
const loaded = await load('matrix.npy');
console.log(loaded.shape); // [2, 3]
import { array, saveSync, loadSync } from 'numpy-ts';
const a = array([1, 2, 3]);
saveSync('data.npy', a);
const loaded = loadSync('data.npy');
import { array, serializeNpy, parseNpy } from 'numpy-ts';
const a = array([[1, 2, 3], [4, 5, 6]]);
// Serialize to Uint8Array
const bytes = serializeNpy(a);
// Parse from ArrayBuffer (e.g., from fetch)
const response = await fetch('https://example.com/matrix.npy');
const buffer = await response.arrayBuffer();
const loaded = parseNpy(buffer);
console.log(loaded.shape); // [2, 3]
import { array, serializeNpy, parseNpy } from 'numpy-ts/core';
NPZ archives (multiple arrays)
The .npz format stores multiple named arrays in a single ZIP archive. savez_compressed applies deflate compression.
import { array, zeros, savez, savez_compressed, load } from 'numpy-ts';
const weights = array([[0.1, 0.2], [0.3, 0.4]]);
const biases = zeros([2]);
// Save multiple arrays (uncompressed)
await savez('model.npz', { weights, biases });
// Save with compression
await savez_compressed('model_compressed.npz', { weights, biases });
// Load returns an object with a Map of arrays
const result = await load('model.npz');
const w = result.arrays.get('weights');
const b = result.arrays.get('biases');
import { array, zeros, serializeNpz, parseNpz } from 'numpy-ts';
const weights = array([[0.1, 0.2], [0.3, 0.4]]);
const biases = zeros([2]);
// Serialize to Uint8Array
const bytes = await serializeNpz({ weights, biases });
// Parse from ArrayBuffer (e.g., from fetch)
const response = await fetch('https://example.com/model.npz');
const buffer = await response.arrayBuffer();
const result = await parseNpz(buffer);
const w = result.arrays.get('weights');
const b = result.arrays.get('biases');
Text files
Load and save delimited text files such as CSV and TSV.
import { array, loadtxt, savetxt } from 'numpy-ts';
// Load a CSV file
const data = await loadtxt('data.csv', { delimiter: ',' });
// Load with options
const filtered = await loadtxt('data.csv', {
delimiter: ',',
skiprows: 1, // Skip header row
usecols: [0, 2], // Only columns 0 and 2
});
// Save as CSV
const a = array([[1.1, 2.2], [3.3, 4.4]]);
await savetxt('output.csv', a, {
delimiter: ',',
header: 'x,y',
fmt: '%.2f',
});
import { array, parseTxt, serializeTxt } from 'numpy-ts';
// Parse from a string (e.g., from fetch or FileReader)
const csv = `1.0,2.0,3.0
4.0,5.0,6.0`;
const data = parseTxt(csv, { delimiter: ',' });
console.log(data.shape); // [2, 3]
// Serialize to a string
const a = array([[1.1, 2.2], [3.3, 4.4]]);
const text = serializeTxt(a, {
delimiter: ',',
header: 'x,y',
fmt: '%.2f',
});
console.log(text);
// # x,y
// 1.10,2.20
// 3.30,4.40
Flexible text loading
genfromtxt
Like loadtxt, but handles missing values more gracefully.
import { genfromtxtFile } from 'numpy-ts';
const data = await genfromtxtFile('messy_data.csv', {
delimiter: ',',
missing_values: ['NA', '', '-'],
filling_values: 0,
});
import { genfromtxt } from 'numpy-ts';
const csv = `1.0,2.0,3.0
4.0,NA,6.0
7.0,8.0,`;
const data = genfromtxt(csv, {
delimiter: ',',
missing_values: ['NA', ''],
filling_values: 0,
});
// [[1, 2, 3], [4, 0, 6], [7, 8, 0]]
fromregex
Extract numeric data from unstructured text using regular expressions.
import { fromregexFile } from 'numpy-ts';
// File contents: "Point: x=1.5, y=2.3\nPoint: x=4.0, y=5.1"
const points = await fromregexFile('points.txt', /x=([\d.]+), y=([\d.]+)/);
console.log(points.shape); // [2, 2]
console.log(points.toArray()); // [[1.5, 2.3], [4.0, 5.1]]
import { fromregex } from 'numpy-ts';
const text = `Point: x=1.5, y=2.3
Point: x=4.0, y=5.1`;
const points = fromregex(text, /x=([\d.]+), y=([\d.]+)/);
console.log(points.toArray()); // [[1.5, 2.3], [4.0, 5.1]]
Types
File I/O functions accept typed options objects:
import type {
LoadOptions,
SaveNpzOptions,
LoadTxtOptions,
SaveTxtOptions,
} from 'numpy-ts';
Sync I/O internals
Sync file I/O functions (loadSync, saveSync, loadNpySync, etc.) use an async self-warming cache that resolves node:fs at module load time. This is transparent in practice. In the extremely unlikely case that you call a sync function before the microtask queue has flushed, call any async I/O function first to ensure the cache is ready.
NumPy compatibility
Files saved by numpy-ts can be loaded by Python NumPy, and vice versa:
# Python
import numpy as np
# Load a file saved by numpy-ts
arr = np.load('matrix.npy')
# Save a file for numpy-ts to load
np.save('from_python.npy', np.array([[1, 2], [3, 4]]))
// TypeScript
import { load } from 'numpy-ts';
const arr = await load('from_python.npy');
console.log(arr.toArray()); // [[1, 2], [3, 4]]
numpy-ts does not support NumPy object arrays, structured arrays, or pickle-based .npy files. Only numeric dtypes (float16, float64, float32, int32, int16, int8, uint32, uint16, uint8, bool, complex128, complex64) are supported.
