> ## Documentation Index
> Fetch the complete documentation index at: https://numpyts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# NPY & NPZ Files

> Read and write NumPy's binary .npy and .npz file formats in the browser and Node.js.

numpy-ts provides full support for NumPy's `.npy` (single array) and `.npz` (multiple arrays, ZIP archive) binary formats. The API is split into two layers:

* **Buffer functions** -- Work with `ArrayBuffer` / `Uint8Array` / strings. Imported from `numpy-ts`.
* **File I/O functions** -- Add file system I/O on top. Also imported from `numpy-ts`. Works on Node.js, Bun, and Deno. Throws in browser environments.

<Warning>
  The `numpy-ts/node` entry point is deprecated. Imports from it still work but you should migrate to `numpy-ts`.
</Warning>

## Browser API

These functions work in any JavaScript environment (browser, Deno, Bun, Node.js) since they operate on bytes, not files.

### parseNpy

Parse a `.npy` buffer into an NDArray.

```typescript theme={null}
function parseNpy(buffer: ArrayBuffer | Uint8Array): NDArray
```

| Name     | Type                        | Default | Description                 |
| -------- | --------------------------- | ------- | --------------------------- |
| `buffer` | `ArrayBuffer \| Uint8Array` | --      | Raw bytes of a `.npy` file. |

**Returns:** `NDArray` -- The parsed array with correct shape, dtype, and data.

```typescript theme={null}
import { parseNpy } from 'numpy-ts';

const response = await fetch('/data/weights.npy');
const buffer = await response.arrayBuffer();
const arr = parseNpy(buffer);
console.log(arr.shape, arr.dtype);
```

***

### parseNpyHeader

Parse only the header of a `.npy` file without reading the data. Useful for inspecting file metadata.

```typescript theme={null}
function parseNpyHeader(bytes: Uint8Array): NpyMetadata
```

| Name    | Type         | Default | Description                 |
| ------- | ------------ | ------- | --------------------------- |
| `bytes` | `Uint8Array` | --      | Raw bytes of a `.npy` file. |

**Returns:** `NpyHeader` -- Object with `{ descr, fortran_order, shape, version, headerLength }`.

```typescript theme={null}
import { parseNpyHeader } from 'numpy-ts';

const header = parseNpyHeader(buffer);
console.log(header.shape);  // e.g. [100, 200]
console.log(header.descr);  // e.g. '<f8'
```

***

### parseNpyData

Parse the data portion of a `.npy` file given pre-parsed metadata. Advanced use for custom streaming workflows.

```typescript theme={null}
function parseNpyData(bytes: Uint8Array, metadata: NpyMetadataType): NDArray
```

| Name       | Type          | Default | Description                        |
| ---------- | ------------- | ------- | ---------------------------------- |
| `bytes`    | `Uint8Array`  | --      | Raw data bytes (after the header). |
| `metadata` | `NpyMetadata` | --      | Metadata from header parsing.      |

**Returns:** `NDArray` -- The parsed array.

***

### serializeNpy

Serialize an NDArray to `.npy` format bytes.

```typescript theme={null}
function serializeNpy(arr: NDArray): Uint8Array
```

| Name  | Type      | Default | Description             |
| ----- | --------- | ------- | ----------------------- |
| `arr` | `NDArray` | --      | The array to serialize. |

**Returns:** `Uint8Array` -- The `.npy` file as bytes, ready to be written or downloaded.

```typescript theme={null}
import * as np from 'numpy-ts';
import { serializeNpy } from 'numpy-ts';

const arr = np.array([[1, 2, 3], [4, 5, 6]]);
const bytes = serializeNpy(arr);

// Download in browser
const blob = new Blob([bytes], { type: 'application/octet-stream' });
```

***

### parseNpz / parseNpzSync

Parse a `.npz` buffer into a collection of named arrays. The async version supports DEFLATE-compressed files.

```typescript theme={null}
function parseNpz(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): Promise<NpzParseResult>

function parseNpzSync(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): NpzParseResult
```

| Name      | Type                        | Default | Description                 |
| --------- | --------------------------- | ------- | --------------------------- |
| `buffer`  | `ArrayBuffer \| Uint8Array` | --      | Raw bytes of a `.npz` file. |
| `options` | `NpzParseOptions`           | `{}`    | Parse options.              |

**NpzParseOptions:**

| Name    | Type      | Default | Description                                                         |
| ------- | --------- | ------- | ------------------------------------------------------------------- |
| `force` | `boolean` | `false` | If `true`, skip arrays with unsupported dtypes instead of throwing. |

**Returns:** `NpzParseResult` -- `{ arrays: Map<string, NDArray>, skipped: string[], errors: Map<string, string> }`.

```typescript theme={null}
import { parseNpz } from 'numpy-ts';

const response = await fetch('/data/model.npz');
const buffer = await response.arrayBuffer();
const result = await parseNpz(buffer);

for (const [name, arr] of result.arrays) {
  console.log(name, arr.shape);
}
```

***

### serializeNpz / serializeNpzSync

Serialize multiple arrays to `.npz` format. The async version supports DEFLATE compression.

```typescript theme={null}
function serializeNpz(
  arrays: NpzArraysInput,
  options?: NpzSerializeOptions
): Promise<Uint8Array>

function serializeNpzSync(
  arrays: NpzArraysInput
): Uint8Array
```

| Name      | Type                  | Default | Description                                                                                                                   |
| --------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `arrays`  | `NpzArraysInput`      | --      | Arrays to serialize. Accepts `NDArray[]` (named `arr_0`, `arr_1`, ...), `Map<string, NDArray>`, or `Record<string, NDArray>`. |
| `options` | `NpzSerializeOptions` | `{}`    | Serialization options.                                                                                                        |

**NpzSerializeOptions:**

| Name       | Type      | Default | Description                                           |
| ---------- | --------- | ------- | ----------------------------------------------------- |
| `compress` | `boolean` | `false` | Use DEFLATE compression (like `np.savez_compressed`). |

**Returns:** `Uint8Array` (or `Promise<Uint8Array>`) -- The `.npz` file as bytes.

```typescript theme={null}
import * as np from 'numpy-ts';
import { serializeNpz } from 'numpy-ts';

const x = np.array([1, 2, 3]);
const y = np.array([4, 5, 6]);
const bytes = await serializeNpz({ x, y });
```

***

### loadNpz / loadNpzSync

Convenience wrappers that parse an `.npz` buffer and return a simple `Record<string, NDArray>` (discarding error/skip metadata).

```typescript theme={null}
function loadNpz(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): Promise<Record<string, NDArray>>

function loadNpzSync(
  buffer: ArrayBuffer | Uint8Array,
  options?: NpzParseOptions
): Record<string, NDArray>
```

| Name      | Type                        | Default | Description                 |
| --------- | --------------------------- | ------- | --------------------------- |
| `buffer`  | `ArrayBuffer \| Uint8Array` | --      | Raw bytes of a `.npz` file. |
| `options` | `NpzParseOptions`           | `{}`    | Parse options.              |

**Returns:** `Record<string, NDArray>` -- Object mapping array names to NDArrays.

***

## File I/O API

<Tabs>
  <Tab title="Async">
    ### load

    Auto-detect file format (`.npy` or `.npz`) and load arrays from disk.

    ```typescript theme={null}
    function load(path: string, options?: LoadOptions): Promise<NDArray | NpzParseResultNDArray>
    ```

    | Name      | Type          | Default     | Description                      |
    | --------- | ------------- | ----------- | -------------------------------- |
    | `path`    | `string`      | --          | Path to a `.npy` or `.npz` file. |
    | `options` | `LoadOptions` | `undefined` | Loading options.                 |

    **Returns:** `Promise<NDArray>` for `.npy` files, `Promise<NpzParseResult>` for `.npz` files.

    ```typescript theme={null}
    import * as np from 'numpy-ts';

    const arr = await np.load('weights.npy');
    const data = await np.load('dataset.npz');
    ```

    ***

    ### save

    Save a single NDArray to a `.npy` file.

    ```typescript theme={null}
    function save(path: string, arr: NDArray): Promise<void>
    ```

    | Name   | Type      | Default | Description                           |
    | ------ | --------- | ------- | ------------------------------------- |
    | `path` | `string`  | --      | Output path (should end with `.npy`). |
    | `arr`  | `NDArray` | --      | Array to save.                        |

    **Returns:** `Promise<void>`

    ```typescript theme={null}
    import * as np from 'numpy-ts';

    const arr = np.array([[1, 2], [3, 4]]);
    await np.save('matrix.npy', arr);
    ```

    ***

    ### loadNpy

    Load a single `.npy` file from disk. Explicit alternative to the auto-detect `load`.

    ```typescript theme={null}
    function loadNpy(path: string): Promise<NDArray>
    ```

    | Name   | Type     | Default | Description              |
    | ------ | -------- | ------- | ------------------------ |
    | `path` | `string` | --      | Path to the `.npy` file. |

    **Returns:** `Promise<NDArray>`

    ```typescript theme={null}
    import * as np from 'numpy-ts';

    const arr = await np.loadNpy('weights.npy');
    ```

    ***

    ### saveNpy

    Save a single NDArray to a `.npy` file. Explicit alternative to `save`.

    ```typescript theme={null}
    function saveNpy(path: string, arr: NDArray): Promise<void>
    ```

    | Name   | Type      | Default | Description                           |
    | ------ | --------- | ------- | ------------------------------------- |
    | `path` | `string`  | --      | Output path (should end with `.npy`). |
    | `arr`  | `NDArray` | --      | Array to save.                        |

    **Returns:** `Promise<void>`

    ***

    ### loadNpzFile

    Load a `.npz` file from disk and return parsed arrays.

    ```typescript theme={null}
    function loadNpzFile(path: string, options?: LoadOptions): Promise<NpzParseResult>
    ```

    | Name      | Type          | Default     | Description              |
    | --------- | ------------- | ----------- | ------------------------ |
    | `path`    | `string`      | --          | Path to the `.npz` file. |
    | `options` | `LoadOptions` | `undefined` | Loading options.         |

    **Returns:** `Promise<NpzParseResult>`

    ```typescript theme={null}
    import * as np from 'numpy-ts';

    const result = await np.loadNpzFile('dataset.npz');
    ```

    ***

    ### saveNpzFile

    Save multiple arrays to a `.npz` file on disk.

    ```typescript theme={null}
    function saveNpzFile(path: string, arrays: NpzArraysInput, options?: SaveNpzOptions): Promise<void>
    ```

    | Name      | Type             | Default     | Description                                              |
    | --------- | ---------------- | ----------- | -------------------------------------------------------- |
    | `path`    | `string`         | --          | Output path. `.npz` extension is appended if missing.    |
    | `arrays`  | `NpzArraysInput` | --          | Named arrays to save. Also accepts `NDArray[]` or `Map`. |
    | `options` | `SaveNpzOptions` | `undefined` | Save options (e.g. compression).                         |

    **Returns:** `Promise<void>`

    ***

    ### savez

    Save multiple arrays to an uncompressed `.npz` file.

    ```typescript theme={null}
    function savez(path: string, arrays: NpzArraysInput): Promise<void>
    ```

    | Name     | Type                      | Default | Description                                              |
    | -------- | ------------------------- | ------- | -------------------------------------------------------- |
    | `path`   | `string`                  | --      | Output path. `.npz` extension is appended if missing.    |
    | `arrays` | `Record<string, NDArray>` | --      | Named arrays to save. Also accepts `NDArray[]` or `Map`. |

    **Returns:** `Promise<void>`

    ```typescript theme={null}
    import * as np from 'numpy-ts';

    await np.savez('data.npz', { x: xArr, y: yArr });
    ```

    ***

    ### savez\_compressed

    Save multiple arrays to a DEFLATE-compressed `.npz` file.

    ```typescript theme={null}
    function savez_compressed(path: string, arrays: NpzArraysInput): Promise<void>
    ```

    | Name     | Type                      | Default | Description                                           |
    | -------- | ------------------------- | ------- | ----------------------------------------------------- |
    | `path`   | `string`                  | --      | Output path. `.npz` extension is appended if missing. |
    | `arrays` | `Record<string, NDArray>` | --      | Named arrays to save.                                 |

    **Returns:** `Promise<void>`

    ```typescript theme={null}
    import * as np from 'numpy-ts';

    await np.savez_compressed('data.npz', { weights: w, biases: b });
    ```
  </Tab>

  <Tab title="Sync">
    Synchronous versions are also available:

    ```typescript theme={null}
    import * as np from 'numpy-ts';

    // Load
    const arr = np.loadSync('weights.npy');
    const data = np.loadNpzFileSync('dataset.npz');

    // Explicit .npy load/save
    const weights = np.loadNpySync('weights.npy');
    np.saveNpySync('output.npy', weights);

    // Save
    np.saveSync('output.npy', arr);
    np.saveNpzSync('output.npz', { x: xArr });
    np.saveNpzFileSync('output.npz', { x: xArr });
    ```

    <Tip>
      `parseNpzSync` / `loadNpzSync` only work with uncompressed `.npz` files. Use the async versions for compressed files. This is a limitation of the [`CompressionStream API`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) which is async-only.
    </Tip>
  </Tab>
</Tabs>

***

## Types

### LoadOptions

| Name    | Type      | Default | Description                                                         |
| ------- | --------- | ------- | ------------------------------------------------------------------- |
| `force` | `boolean` | `false` | If `true`, skip arrays with unsupported dtypes instead of throwing. |

### SaveNpzOptions

| Name       | Type      | Default | Description              |
| ---------- | --------- | ------- | ------------------------ |
| `compress` | `boolean` | `false` | Use DEFLATE compression. |

***

<Warning>
  Only the following dtypes are supported: `float16`, `float32`, `float64`, `int8`, `int16`, `int32`, `uint8`, `uint16`, `uint32`, `bool`, and `int64`/`uint64` (as BigInt).
  Structured arrays and object dtypes are not supported.
</Warning>