@ebowwa/bun-native-page

Cross-platform page-size aware memory operations for Bun.

Why?

Different systems have different memory page sizes:

• macOS Apple Silicon (M1/M2/M3/M4): 16 KB
• macOS Intel: 4 KB
• Linux x86_64: 4 KB
• Linux ARM64 (Asahi, future): 16 KB
• Windows: 4 KB

Hardcoding 4096 wastes memory on 16 KB systems and can cause alignment issues with mmap, Direct I/O, and GPU interop.

Features

• Runtime page size detection
• Page-aligned memory allocation
• mmap/munmap/madvise wrappers
• Huge page support (Linux)
• PageArena bump allocator
• BufferPool fixed-size buffer pool
• Full TypeScript types

Installation

bun add @ebowwa/bun-native-page

Quick Start

import { getPageSize, allocPageAligned, mmapAnonymous } from '@ebowwa/bun-native-page';

// Get system page size
const info = getPageSize();
console.log(`Page size: ${info.size} bytes`); // 4096 or 16384
console.log(`Platform: ${info.platform}`);    // darwin-arm64, linux-x64, etc.

// Allocate page-aligned memory
const buf = allocPageAligned(1024);
console.log(`Aligned to: ${buf.size} bytes`); // Rounded to page boundary
buf.free();

// Memory-mapped anonymous region
const region = mmapAnonymous(1024 * 1024); // 1MB
const view = new Uint8Array(region.buffer);
view[0] = 0x42;
region.unmap();

API

See SPEC.md for full API documentation.

Status

Specification Phase - See SPEC.md for design review.

License

MIT