meminfo For Node.js
=================================

[![CI](https://github.com/magiclen/node-meminfo/actions/workflows/ci.yml/badge.svg)](https://github.com/magiclen/node-meminfo/actions/workflows/ci.yml)

Get memory information on Linux.

## Requirements and Installation

Linux, Node.js 24 or later and Rust 1.88 or later are required. Install Rust with [rustup](https://rustup.rs/) and a C compiler for linking.

```sh
npm install node-meminfo
```

Installation compiles the native module from source using the included `Cargo.lock`. There are no prebuilt platform packages. Package managers that block dependency build scripts must allow the `node-meminfo` install script; for pnpm, approve `node-meminfo` with `pnpm approve-builds` and rebuild it with `pnpm rebuild node-meminfo`. If npm requires script approval, use `npm install-scripts approve node-meminfo` followed by `npm rebuild node-meminfo`.

## Usage

### meminfo

The `meminfo` function gets all fields and values from `/proc/meminfo`. The values are in bytes, except the `HugePages_*` fields, which are page counts.

```typescript
import { meminfo } from "node-meminfo";

console.log(meminfo());
/*
{
    MemTotal: 66645020672,
    MemFree: 914055168,
    MemAvailable: 45735542784,
    Buffers: 2629632,
    Cached: 42922389504,
    SwapCached: 8396800,
    Active: 11555053568,
    Inactive: 46985338880,
    'Active(anon)': 8459821056,
    'Inactive(anon)': 8526344192,
    'Active(file)': 3095232512,
    'Inactive(file)': 38458994688,
    Unevictable: 93741056,
    Mlocked: 114688,
    SwapTotal: 8192520192,
    SwapFree: 6442967040,
    Zswap: 0,
    Zswapped: 0,
    Dirty: 1622016,
    Writeback: 0,
    AnonPages: 15701975040,
    Mapped: 2233372672,
    Shmem: 1370796032,
    KReclaimable: 4012236800,
    Slab: 5578682368,
    SReclaimable: 4012236800,
    SUnreclaim: 1566445568,
    KernelStack: 59473920,
    PageTables: 204087296,
    SecPageTables: 8339456,
    NFS_Unstable: 0,
    Bounce: 0,
    WritebackTmp: 0,
    CommitLimit: 41515028480,
    Committed_AS: 89246199808,
    VmallocTotal: 35184372087808,
    VmallocUsed: 193331200,
    VmallocChunk: 0,
    Percpu: 26640384,
    HardwareCorrupted: 0,
    AnonHugePages: 79691776,
    ShmemHugePages: 25165824,
    ShmemPmdMapped: 0,
    FileHugePages: 0,
    FilePmdMapped: 0,
    CmaTotal: 0,
    CmaFree: 0,
    Unaccepted: 0,
    Balloon: 0,
    HugePages_Total: 0,
    HugePages_Free: 0,
    HugePages_Rsvd: 0,
    HugePages_Surp: 0,
    Hugepagesize: 2097152,
    Hugetlb: 0,
    DirectMap4k: 12566372352,
    DirectMap2M: 54299459584,
    DirectMap1G: 3221225472
}
*/
```

### free

If you like to use the `free` command on Linux, you probably prefer to use the `free` function. It returns the same values as `free -b -w` of procps-ng 4.

```typescript
import { free } from "node-meminfo";

console.log(free());
/*
{
    mem: {
        total: 66645020672,
        used: 20909477888,
        free: 914055168,
        shared: 1370796032,
        buffers: 2629632,
        cache: 46934626304,
        available: 45735542784
    },
    swap: {
        total: 8192520192,
        used: 1749553152,
        free: 6442967040,
        cache: 8396800
    }
}
*/
```

All values are in bytes and are calculated from the fields of `/proc/meminfo` as follows.

| Field           | Calculation               |
| --------------- | ------------------------- |
| `mem.total`     | `MemTotal`                |
| `mem.used`      | `MemTotal - MemAvailable` |
| `mem.free`      | `MemFree`                 |
| `mem.shared`    | `Shmem`                   |
| `mem.buffers`   | `Buffers`                 |
| `mem.cache`     | `Cached + SReclaimable`   |
| `mem.available` | `MemAvailable`            |
| `swap.total`    | `SwapTotal`               |
| `swap.used`     | `SwapTotal - SwapFree`    |
| `swap.free`     | `SwapFree`                |
| `swap.cache`    | `SwapCached`              |

Like procps-ng, `MemFree` is used as `MemAvailable` if `MemAvailable` is missing or larger than `MemTotal` (for example, in some LXC containers).

## License

[MIT](LICENSE)
