{"id":13687,"library":"numpy-parser","title":"NumPy .npy File Parser","description":"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.","status":"maintenance","version":"1.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/ludwigschubert/js-numpy-parser","tags":["javascript","numpy","npy","parser"],"install":[{"cmd":"npm install numpy-parser","lang":"bash","label":"npm"},{"cmd":"yarn add numpy-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add numpy-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary parsing function is a named export, not a default export.","wrong":"import numpyParser from 'numpy-parser';","symbol":"fromArrayBuffer","correct":"import { fromArrayBuffer } from 'numpy-parser';"},{"note":"While CommonJS `require` might work in some environments, the library's examples typically use ESM `import`. Use ESM for modern applications.","wrong":"const { fromArrayBuffer } = require('numpy-parser');","symbol":"fromArrayBuffer","correct":"import { fromArrayBuffer } from 'numpy-parser';"},{"note":"For TypeScript users, import the `NpyArray` type to correctly type the return value of `fromArrayBuffer`.","wrong":null,"symbol":"NpyArray","correct":"import type { NpyArray } from 'numpy-parser';"}],"quickstart":{"code":"import { fromArrayBuffer } from 'numpy-parser';\n\ninterface NpyArray {\n  data: TypedArray; // e.g., Float32Array, Int32Array\n  dtype: string;\n  shape: number[];\n  fortranOrder: boolean;\n}\n\n// This example demonstrates parsing an ArrayBuffer obtained from a .npy file.\n// You would typically load this buffer from a file system (Node.js) or network (browser).\n\n// --- Node.js Example (requires a 'data.npy' file) ---\n// import { readFileSync } from 'node:fs';\n// try {\n//   const filePath = './data.npy'; // Path to your .npy file\n//   const fileBuffer = readFileSync(filePath);\n//   const arrayBufferNode = fileBuffer.buffer; // Get the underlying ArrayBuffer\n//   const parsedDataNode = fromArrayBuffer(arrayBufferNode) as NpyArray;\n//   console.log('Node.js Parsed Data:', parsedDataNode.data.slice(0, 5));\n//   console.log('Node.js Data Type:', parsedDataNode.dtype);\n//   console.log('Node.js Shape:', parsedDataNode.shape);\n// } catch (error) {\n//   console.error('Error reading/parsing .npy in Node.js:', error);\n// }\n\n// --- Browser Example (requires an accessible .npy URL) ---\nasync function loadAndParseNpy(url: string) {\n  try {\n    console.log(`Fetching .npy file from: ${url}`);\n    const response = await fetch(url);\n    if (!response.ok) {\n      throw new Error(`HTTP error! Status: ${response.status}`);\n    }\n    const arrayBuffer = await response.arrayBuffer();\n    \n    const parsedData = fromArrayBuffer(arrayBuffer) as NpyArray;\n    \n    console.log('Successfully parsed .npy file:');\n    console.log('Data Type:', parsedData.dtype); // e.g., 'float32', 'int8'\n    console.log('Shape:', parsedData.shape);     // e.g., [100, 200]\n    console.log('First 10 data elements:', parsedData.data.slice(0, 10));\n    return parsedData;\n  } catch (error) {\n    console.error('Failed to load or parse .npy file:', error);\n    return null;\n  }\n}\n\n// Replace with a URL to an actual .npy file for a live example.\n// For instance, you could serve a small .npy file locally or use a public one if available.\n// Example using a placeholder URL:\nloadAndParseNpy('https://example.com/path/to/your/data.npy');\n\n// To run this in a real browser, create an HTML file:\n/*\n<script type=\"module\">\n  import { fromArrayBuffer } from 'https://cdn.jsdelivr.net/npm/numpy-parser@1.2.3/dist/index.mjs';\n  // ... rest of the loadAndParseNpy function ...\n  loadAndParseNpy('https://example.com/path/to/your/data.npy');\n</script>\n*/","lang":"typescript","description":"Demonstrates how to parse an ArrayBuffer using `fromArrayBuffer`, with examples for obtaining the buffer in both Node.js and browser environments."},"warnings":[{"fix":"Consider testing with newer NumPy files, or evaluate alternative parsing libraries if active maintenance and latest format compatibility are critical.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Parsing 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"The library primarily processes the core NPY binary format. It does not support compressed `.npz` files or NPY files containing Python pickled objects.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.2.3':46 '16':99 '2019':55 'activ':64 'allow':82 'applic':84 'array':25,91 'binari':16,90 'bit':100 'comput':79 'current':42 'data':73 'design':13 'develop':65 'direct':72 'ecosystem':80 'enabl':71 'exchang':74 'featur':108 'file':3,18,92 'float':101 'float32':32 'float64':33 'format':21 'futur':96 'high':88 'howev':47 'includ':31 'indic':56 'int16':35 'int32':36 'int8':34 'januari':54 'javascript':10,83,109 'last':51 'librari':11 'lie':69 'mainten':60 'mention':95 'mode':61 'npi':2,17,111 'numpi':1,6,24,110 'numpy-pars':5 'optim':89 'packag':49 'pars':15 'parser':4,7,112 'primari':67 'publish':52 'python':76 'rather':62 'read':86 'readm':94 'remain':105 'scientif':78 'specif':12 'stabl':43 'standard':20 'store':23 'subclass':30 'support':27,102 'typedarray':29 'uint16':38 'uint32':40 'uint8':37 'unimpl':107 'util':68 'various':28 'version':44 'work':97","created_at":"2026-04-20T01:55:47.627687+00:00","updated_at":"2026-04-20T01:55:47.627687+00:00","problems":[{"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.","cause":"The provided ArrayBuffer is either corrupted, not a valid .npy file, or does not conform to the expected NPY format specification.","error":"Error: Invalid NPY file header"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'buffer')"},{"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.","cause":"The `fetch` API is a Web API (browser-native) and is not globally available in a standard Node.js environment without a polyfill.","error":"ReferenceError: fetch is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ludwigschubert/js-numpy-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/numpy-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}