node-po6-mmap

A Node.js library for memory-mapped file I/O using the mmap system call. This package provides a TypeScript-first interface for mapping files into memory with automatic resource management and garbage collection safety.

Features

• 🗺️ Map files into memory using the mmap syscall
• 🔒 Support for shared and private mappings
• ⚡ Zero-copy access to file data via Uint8Array
• 🛡️ Automatic detection of unmapped buffers during garbage collection
• 📦 TypeScript-first with full type definitions
• 🔧 Flexible memory protection flags (read, write, execute)

Installation

npm install @k13engineering/po6-mmap

Usage

import { mmapFd, determinePageSize } from "@k13engineering/po6-mmap";
import nodeFs from "node:fs";

const fd = nodeFs.openSync("/dev/zero", "r+");

const length = determinePageSize();

const { errno, mapping } = mmapFd({
  fd,
  mappingVisibility: "MAP_PRIVATE",
  memoryProtectionFlags: {
    PROT_READ: true,
    PROT_WRITE: false,
    PROT_EXEC: false,
  },
  genericFlags: {},
  offsetInFd: 0,
  length,
});

nodeFs.closeSync(fd);

if (errno !== undefined) {
  throw Error(`mmapFd failed with errno ${errno}`);
}

console.log(`mapped buffer of length ${mapping.length} at address 0x${mapping.address.toString(16)}`);
console.log(`buffer:`, mapping.createArrayBuffer());

mapping.unmap();

API

mmapFd(options)

Maps a file descriptor into memory.

Parameters:

• fd (number): File descriptor to map
• mappingVisibility ("MAP_SHARED" | "MAP_PRIVATE"): Mapping visibility
  • MAP_SHARED: Changes are shared with other processes
  • MAP_PRIVATE: Changes are private (copy-on-write)
• memoryProtectionFlags (object): Memory protection flags
  • PROT_READ (boolean): Allow read access
  • PROT_WRITE (boolean): Allow write access
  • PROT_EXEC (boolean): Allow execution
• genericFlags (object): Additional flags
  • MAP_32BIT (boolean): Map into 32-bit address space
  • MAP_LOCKED (boolean): Lock pages in memory
  • MAP_NORESERVE (boolean): Don't reserve swap space
• offsetInFd (number): Offset in file (must be page-aligned)
• length (number): Length of mapping in bytes

Returns: Object with either:

• { errno: number, mapping: undefined } on error
• { errno: undefined, mapping: TMemoryMapping } on success

Note: Not all mmap options are currently exposed. Additional flags and options may be added in future versions.

TMemoryMapping

An object representing a memory mapping with the following properties:

• address (bigint): Memory address of the mapping
• length (number): Length of the mapping in bytes
• createArrayBuffer() (function): Returns an ArrayBuffer for the mapped memory region
• unmap() (function): Unmaps the memory region

Important: Always call unmap() when done to avoid memory leaks. If a buffer is garbage collected without being unmapped, the library will throw an uncaught exception.

determinePageSize()

Returns the system page size (currently hardcoded to 4096).

Memory Safety

This library includes a finalization registry that detects if a memory-mapped buffer is garbage collected without calling unmap(). If this happens, a MemoryMappedBufferGarbageCollectedWithoutUnmapError is thrown to prevent silent memory leaks.

Always ensure you call unmap() on buffers when you're done with them:

const result = mmapFd({ /* ... */ });
if (result.errno === undefined) {
  try {
    // Use result.mapping
    const buffer = result.mapping.createArrayBuffer();
  } finally {
    result.mapping.unmap(); // Always unmap in finally block
  }
}

Development Notes

The main code in this library is primarily hand-crafted, while the test suite has been mostly generated by AI. This approach combines careful manual implementation with comprehensive AI-assisted testing coverage.

License

See LICENSE file.