tensorfile

read and write safetensors. zero deps. pulls one tensor out of a remote model with a range request instead of downloading the file.

npm i tensorfile

why

the format is deliberately simple — eight bytes of little endian header length, a json header, then the tensor data packed end to end. that simplicity is the whole point: you can read the header of a 10gb model with two small http requests, then fetch only the tensor you want.

nothing on npm does that. @huggingface/gguf is a different format, and the safetensors name on npm is an empty 0.0.1 placeholder from 2023. the rust crate has millions of downloads and no javascript counterpart.

local

import { read, write } from 'tensorfile'
import { readFileSync } from 'node:fs'

const model = read(readFileSync('model.safetensors'))

model.names                     // ['weight', 'bias']
model.metadata.get('format')    // 'pt'

const w = model.get('weight')
w.dtype      // 'F32'
w.shape      // [2, 2]
w.view       // Float32Array(4) [1, 2, 3, 4]
w.bytes      // the raw slice, no copy when aligned

writing takes the same shape:

const bytes = write({
  weight: { dtype: 'F32', shape: [2, 2], data: floats },
  bias: { dtype: 'F32', shape: [2], data: moreFloats }
}, { format: 'pt' })

over http, without downloading the model

import { RemoteTensors } from 'tensorfile'

const model = await RemoteTensors.open('https://host/model.safetensors')

model.names                        // two small requests so far
const embed = await model.get('embeddings')   // one request, only those bytes

two range requests read the length and the header. every get after that fetches exactly the tensor's byte span and nothing else. that works from a cloudflare worker, where downloading a multi-gigabyte model is not an option.

private models take a token:

RemoteTensors.open(url, { headers: { authorization: `Bearer ${hfToken}` } })

a server that ignores Range and returns the whole body is detected and sliced locally rather than handing back the wrong bytes.

dtypes

BOOL U8 I8 U16 I16 U32 I32 U64 I64 F16 F32 F64 BF16 F8_E4M3 F8_E5M2

view gives the matching typed array where javascript has one. BF16 and the two float8 types have no native array, so those come back as raw bytes — fromBF16() converts when you need floats.

a header from the internet is not trusted

offsets and shapes come out of the file, so all of these throw a typed TensorError rather than being followed:

| header says | result | |---|---| | a length larger than the file | TRUNCATED | | a length of several exabytes | HEADER_TOO_LARGE, refused before allocating | | offsets ending past the data | BAD_OFFSETS | | offsets running backwards, or negative | BAD_OFFSETS | | a shape needing more bytes than the range holds | BAD_SHAPE | | a shape whose product overflows | BAD_SHAPE | | two tensors covering the same bytes | OVERLAP | | a dtype that does not exist | BAD_DTYPE |

the shape and the byte range have to agree, because a caller reading by shape would otherwise walk straight past the end of the tensor.

tensor names are file content, so they are held in a Map throughout — a tensor called __proto__ is an ordinary name and never becomes an object key.

limits are yours to set:

read(bytes, { maxHeaderBytes: 100 << 20, maxTensors: 100_000, allowOverlap: false })

correctness

37 tests. the ones that matter are the interop tests: we read what python's safetensors writes, and python reads what we write — checked across f32, f16, i64, u8, multi dimensional shapes, metadata and a 50,000 element tensor.

license

MIT