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

``bash
npm install @k13engineering/po6-mmap
`

Usage

`typescript
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

$3

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.

$3

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.

$3

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:

`typescript
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.