Registry / data / numpy-parser

numpy-parser

library1.2.3jsnpmunverified

numpy-parser is a JavaScript library specifically designed for parsing binary `.npy` files, the standard format for storing NumPy arrays. It supports various TypedArray subclasses including `float32`, `float64`, `int8`, `int16`, `int32`, `uint8`, `uint16`, and `uint32`. The current stable version is 1.2.3; however, the package was last published in January 2019, indicating it is in maintenance mode rather than active development. Its primary utility lies in enabling direct data exchange with Python's scientific computing ecosystem by allowing JavaScript applications to read these highly optimized binary array files. The README mentions future work for 16-bit float support, but this remains an unimplemented feature.

data serialization

npm install numpy-parser

github ↗package ↗

INSTALL

IMPORT

SIG · NUMPY-PARSER

numpy-parser

datajavascriptv1.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fromArrayBuffer

✓ import { fromArrayBuffer } from 'numpy-parser';

✗ import numpyParser from 'numpy-parser';

The primary parsing function is a named export, not a default export.

fromArrayBuffer

✓ import { fromArrayBuffer } from 'numpy-parser';

✗ const { fromArrayBuffer } = require('numpy-parser');

While CommonJS `require` might work in some environments, the library's examples typically use ESM `import`. Use ESM for modern applications.

NpyArray

✓ import type { NpyArray } from 'numpy-parser';

For TypeScript users, import the `NpyArray` type to correctly type the return value of `fromArrayBuffer`.

Demonstrates how to parse an ArrayBuffer using `fromArrayBuffer`, with examples for obtaining the buffer in both Node.js and browser environments.

import { fromArrayBuffer } from 'numpy-parser'; interface NpyArray { data: TypedArray; // e.g., Float32Array, Int32Array dtype: string; shape: number[]; fortranOrder: boolean; } // This example demonstrates parsing an ArrayBuffer obtained from a .npy file. // You would typically load this buffer from a file system (Node.js) or network (browser). // --- Node.js Example (requires a 'data.npy' file) --- // import { readFileSync } from 'node:fs'; // try { // const filePath = './data.npy'; // Path to your .npy file // const fileBuffer = readFileSync(filePath); // const arrayBufferNode = fileBuffer.buffer; // Get the underlying ArrayBuffer // const parsedDataNode = fromArrayBuffer(arrayBufferNode) as NpyArray; // console.log('Node.js Parsed Data:', parsedDataNode.data.slice(0, 5)); // console.log('Node.js Data Type:', parsedDataNode.dtype); // console.log('Node.js Shape:', parsedDataNode.shape); // } catch (error) { // console.error('Error reading/parsing .npy in Node.js:', error); // } // --- Browser Example (requires an accessible .npy URL) --- async function loadAndParseNpy(url: string) { try { console.log(`Fetching .npy file from: ${url}`); const response = await fetch(url); if (!response.ok) { throw new Error(`HTTP error! Status: ${response.status}`); } const arrayBuffer = await response.arrayBuffer(); const parsedData = fromArrayBuffer(arrayBuffer) as NpyArray; console.log('Successfully parsed .npy file:'); console.log('Data Type:', parsedData.dtype); // e.g., 'float32', 'int8' console.log('Shape:', parsedData.shape); // e.g., [100, 200] console.log('First 10 data elements:', parsedData.data.slice(0, 10)); return parsedData; } catch (error) { console.error('Failed to load or parse .npy file:', error); return null; } } // Replace with a URL to an actual .npy file for a live example. // For instance, you could serve a small .npy file locally or use a public one if available. // Example using a placeholder URL: loadAndParseNpy('https://example.com/path/to/your/data.npy'); // To run this in a real browser, create an HTML file: /* <script type="module"> import { fromArrayBuffer } from 'https://cdn.jsdelivr.net/npm/numpy-parser@1.2.3/dist/index.mjs'; // ... rest of the loadAndParseNpy function ... loadAndParseNpy('https://example.com/path/to/your/data.npy'); </script> */

Debug

Known issues

gotchaThe `numpy-parser` library was last published in January 2019. While functional for its stated purpose, it is not actively maintained. Users should be aware of potential compatibility issues with very recent NumPy `.npy` format versions or a lack of security updates.

fix

Consider testing with newer NumPy files, or evaluate alternative parsing libraries if active maintenance and latest format compatibility are critical.

affects: >=1.0.0

gotchaThe library does not natively support `float16` data types, which `.npy` files can encode. While the README mentions this as future work, it's not implemented. `float16` arrays will likely not parse correctly or may require pre-conversion.

fix

Ensure that `.npy` files containing `float16` data are converted to a supported float type (e.g., `float32` or `float64`) using NumPy before being processed by `numpy-parser`.

affects: >=1.0.0

gotchaParsing large `.npy` files in JavaScript environments (especially browsers) can lead to significant memory consumption and performance issues, as the entire ArrayBuffer needs to be loaded into memory before parsing.

fix

For very large datasets, consider pre-processing the data into smaller chunks or alternative streaming formats in Python, or use Node.js with sufficient memory allocation. Implement client-side memory management if parsing large files in a browser.

affects: >=1.0.0

gotchaThe library primarily processes the core NPY binary format. It does not support compressed `.npz` files or NPY files containing Python pickled objects.

fix

Decompress `.npz` archives beforehand (e.g., using a JS zip library or Python) to extract individual `.npy` files. Convert Python pickled objects to primitive types before saving to `.npy`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Invalid NPY file header

The provided ArrayBuffer is either corrupted, not a valid .npy file, or does not conform to the expected NPY format specification.

fix

Verify the integrity of the .npy file and ensure it was generated correctly by NumPy. Check for partial downloads or file corruption. This parser might also not support very new .npy format versions.

TypeError: Cannot read properties of undefined (reading 'buffer')

This error often occurs in a Node.js context when trying to access `.buffer` on a value that is not a `Buffer` or is `undefined`, typically when `readFileSync` fails or is not correctly used.

fix

Ensure `fs.readFileSync` successfully reads the file and returns a `Buffer` object before attempting to access its `.buffer` property. Check the file path for correctness and read permissions.

ReferenceError: fetch is not defined

The `fetch` API is a Web API (browser-native) and is not globally available in a standard Node.js environment without a polyfill.

fix

If running in Node.js, either install a `node-fetch` polyfill (e.g., `npm install node-fetch` and `import fetch from 'node-fetch';`) or use Node.js's native `node:fs` module to read local files, as shown in the quickstart comments.

Upgrade

Version history

1.2.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ludwigschubert/js-numpy-parser ↗

packagehttps://www.npmjs.com/package/numpy-parser ↗