@ebowwa/bun-native-page 0.2.0

package/dist/index.ts

@@ -0,0 +1,433 @@
+/**
+ * @ebowwa/bun-native-page
+ *
+ * Cross-platform page-size aware memory operations for Bun
+ */
+
+export * from './errors.js';
+export * from './oom.js';
+export * from './allocator.js';
+
+import { ffi, ptr, toArrayBuffer } from './ffi.js';
+import { PageSizeError, MapError, ProtectionError, LockError } from './errors.js';
+import { handleOOM, OOMOptions } from './oom.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PageSizeInfo {
+  /** System page size in bytes */
+  readonly size: number;
+  /** true if page size is 4096 bytes */
+  readonly is4k: boolean;
+  /** true if page size is 16384 bytes */
+  readonly is16k: boolean;
+  /** true if page size is 65536 bytes */
+  readonly is64k: boolean;
+  /** Huge page size in bytes (Linux only, 0 if unavailable) */
+  readonly hugePageSize: number;
+  /** Platform identifier */
+  readonly platform: PlatformName;
+}
+
+export type PlatformName =
+  | 'darwin-arm64'
+  | 'darwin-x64'
+  | 'linux-x64'
+  | 'linux-x86'
+  | 'linux-arm64'
+  | 'linux-arm'
+  | 'windows-x64'
+  | 'windows-x86'
+  | 'windows-arm64'
+  | 'unknown';
+
+export type MemoryProtection =
+  | 'none'
+  | 'read'
+  | 'write'
+  | 'exec'
+  | 'read-write'
+  | 'read-exec'
+  | 'write-exec'
+  | 'all';
+
+export type MemoryAdvice =
+  | 'normal'
+  | 'random'
+  | 'sequential'
+  | 'willneed'
+  | 'dontneed'
+  | 'free'
+  | 'hugepage'
+  | 'nohugepage';
+
+export interface AllocatedBuffer {
+  /** Pointer to allocated memory */
+  readonly ptr: bigint;
+  /** Requested size */
+  readonly size: number;
+  /** Actual allocated size (may be larger due to alignment) */
+  readonly allocatedSize: number;
+  /** ArrayBuffer view of the memory */
+  readonly buffer: ArrayBuffer;
+  /** Free the allocation */
+  free(): void;
+}
+
+export interface MappedRegion {
+  /** Pointer to mapped memory */
+  readonly ptr: bigint;
+  /** Mapped size */
+  readonly size: number;
+  /** ArrayBuffer view */
+  readonly buffer: ArrayBuffer;
+  /** Unmap the region */
+  unmap(): void;
+  /** Change memory protection */
+  protect(prot: MemoryProtection): void;
+  /** Advise kernel about usage pattern */
+  advise(advice: MemoryAdvice): void;
+  /** Lock pages in memory (prevent swap) */
+  lock(): void;
+  /** Unlock pages */
+  unlock(): void;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const PROTECTION_MAP: Record<MemoryProtection, number> = {
+  'none': 0,
+  'read': 1,
+  'write': 2,
+  'exec': 4,
+  'read-write': 3,
+  'read-exec': 5,
+  'write-exec': 6,
+  'all': 7,
+};
+
+const ADVICE_MAP: Record<MemoryAdvice, number> = {
+  'normal': 0,
+  'random': 1,
+  'sequential': 2,
+  'willneed': 3,
+  'dontneed': 4,
+  'free': 5,
+  'hugepage': 6,
+  'nohugepage': 7,
+};
+
+const PLATFORM_NAMES: Record<number, PlatformName> = {
+  0: 'darwin-arm64',
+  1: 'darwin-x64',
+  2: 'linux-x64',
+  3: 'linux-x86',
+  4: 'linux-arm64',
+  5: 'linux-arm',
+  6: 'windows-x64',
+  7: 'windows-x86',
+  8: 'windows-arm64',
+  99: 'unknown',
+};
+
+// Cached page size info
+let cachedPageSizeInfo: PageSizeInfo | null = null;
+
+// ============================================================================
+// Page Size API
+// ============================================================================
+
+/**
+ * Get system page size information
+ */
+export function getPageSize(): PageSizeInfo {
+  if (cachedPageSizeInfo) {
+    return cachedPageSizeInfo;
+  }
+
+  const size = Number(ffi.getSize());
+  const hugePageSize = Number(ffi.getHugePageSize());
+  const platformId = Number(ffi.getPlatform());
+
+  cachedPageSizeInfo = {
+    size,
+    is4k: size === 4096,
+    is16k: size === 16384,
+    is64k: size === 65536,
+    hugePageSize,
+    platform: PLATFORM_NAMES[platformId] ?? 'unknown',
+  };
+
+  return cachedPageSizeInfo;
+}
+
+/**
+ * Round size up to nearest page boundary
+ */
+export function alignToPage(size: number): number {
+  return Number(ffi.alignSize(BigInt(size)));
+}
+
+/**
+ * Round size down to nearest page boundary
+ */
+export function truncateToPage(size: number): number {
+  return Number(ffi.truncateSize(BigInt(size)));
+}
+
+/**
+ * Check if a pointer is page-aligned
+ */
+export function isPageAligned(ptr: bigint | number): boolean {
+  const result = ffi.isAligned(BigInt(ptr));
+  return result !== 0;
+}
+
+// ============================================================================
+// Allocation API
+// ============================================================================
+
+/**
+ * Allocate page-aligned memory
+ */
+export function allocPageAligned(
+  size: number,
+  options?: OOMOptions
+): AllocatedBuffer | null {
+  if (size <= 0) {
+    throw new PageSizeError('Size must be positive');
+  }
+
+  if (size > Number.MAX_SAFE_INTEGER) {
+    throw new PageSizeError('Size exceeds safe integer range');
+  }
+
+  const allocHandle = ffi.alloc(BigInt(size));
+
+  if (allocHandle === null || allocHandle === 0n) {
+    return handleOOM(size, options) as never;
+  }
+
+  const actualPtr = ffi.allocPtr(allocHandle);
+  const actualSize = Number(ffi.allocSize(allocHandle));
+
+  if (actualPtr === null || actualPtr === 0n) {
+    ffi.free(allocHandle);
+    return handleOOM(size, options) as never;
+  }
+
+  let freed = false;
+
+  return {
+    ptr: BigInt(actualPtr as unknown as number),
+    size,
+    allocatedSize: actualSize,
+    get buffer() {
+      if (freed) {
+        throw new PageSizeError('Cannot access freed buffer');
+      }
+      return toArrayBuffer(actualPtr as unknown as number, 0, actualSize);
+    },
+    free() {
+      if (!freed) {
+        freed = true;
+        ffi.free(allocHandle);
+      }
+    },
+  };
+}
+
+// ============================================================================
+// mmap API
+// ============================================================================
+
+/**
+ * Map anonymous memory (no file backing)
+ */
+export function mmapAnonymous(
+  size: number,
+  prot: MemoryProtection = 'read-write'
+): MappedRegion {
+  if (size <= 0) {
+    throw new PageSizeError('Size must be positive');
+  }
+
+  const protValue = PROTECTION_MAP[prot];
+  const regionHandle = ffi.mmapAnonymous(BigInt(size), protValue);
+
+  if (regionHandle === null || regionHandle === 0n) {
+    throw new MapError(size, 'mmap failed');
+  }
+
+  const actualPtr = ffi.mmapPtr(regionHandle);
+  const actualSize = Number(ffi.mmapSize(regionHandle));
+
+  if (actualPtr === null || actualPtr === 0n) {
+    throw new MapError(size, 'mmap returned null pointer');
+  }
+
+  let unmapped = false;
+
+  return {
+    ptr: BigInt(actualPtr as unknown as number),
+    size: actualSize,
+    get buffer() {
+      if (unmapped) {
+        throw new PageSizeError('Cannot access unmapped region');
+      }
+      return toArrayBuffer(actualPtr as unknown as number, 0, actualSize);
+    },
+    unmap() {
+      if (!unmapped) {
+        unmapped = true;
+        const result = ffi.munmap(regionHandle);
+        if (result !== 0) {
+          throw new PageSizeError('munmap failed');
+        }
+      }
+    },
+    protect(prot: MemoryProtection) {
+      const protValue = PROTECTION_MAP[prot];
+      const result = ffi.mprotect(actualPtr as unknown as number, BigInt(actualSize), protValue);
+      if (result !== 0) {
+        throw new ProtectionError(`mprotect failed with code ${result}`);
+      }
+    },
+    advise(advice: MemoryAdvice) {
+      const adviceValue = ADVICE_MAP[advice];
+      ffi.madvise(actualPtr as unknown as number, BigInt(actualSize), adviceValue);
+    },
+    lock() {
+      const result = ffi.mlock(actualPtr as unknown as number, BigInt(actualSize));
+      if (result !== 0) {
+        throw new LockError(`mlock failed with code ${result}`);
+      }
+    },
+    unlock() {
+      const result = ffi.munlock(actualPtr as unknown as number, BigInt(actualSize));
+      if (result !== 0) {
+        throw new LockError(`munlock failed with code ${result}`);
+      }
+    },
+  };
+}
+
+/**
+ * Map a file into memory
+ */
+export function mmapFile(
+  fd: number,
+  size: number,
+  offset: number = 0,
+  prot: MemoryProtection = 'read-write'
+): MappedRegion {
+  if (size <= 0) {
+    throw new PageSizeError('Size must be positive');
+  }
+
+  const protValue = PROTECTION_MAP[prot];
+  const regionHandle = ffi.mmapFile(fd, BigInt(size), BigInt(offset), protValue);
+
+  if (regionHandle === null || regionHandle === 0n) {
+    throw new MapError(size, 'mmap file failed');
+  }
+
+  const actualPtr = ffi.mmapPtr(regionHandle);
+  const actualSize = Number(ffi.mmapSize(regionHandle));
+
+  if (actualPtr === null || actualPtr === 0n) {
+    throw new MapError(size, 'mmap file returned null pointer');
+  }
+
+  let unmapped = false;
+
+  return {
+    ptr: BigInt(actualPtr as unknown as number),
+    size: actualSize,
+    get buffer() {
+      if (unmapped) {
+        throw new PageSizeError('Cannot access unmapped region');
+      }
+      return toArrayBuffer(actualPtr as unknown as number, 0, actualSize);
+    },
+    unmap() {
+      if (!unmapped) {
+        unmapped = true;
+        ffi.munmap(regionHandle);
+      }
+    },
+    protect(prot: MemoryProtection) {
+      const protValue = PROTECTION_MAP[prot];
+      ffi.mprotect(actualPtr as unknown as number, BigInt(actualSize), protValue);
+    },
+    advise(advice: MemoryAdvice) {
+      const adviceValue = ADVICE_MAP[advice];
+      ffi.madvise(actualPtr as unknown as number, BigInt(actualSize), adviceValue);
+    },
+    lock() {
+      ffi.mlock(actualPtr as unknown as number, BigInt(actualSize));
+    },
+    unlock() {
+      ffi.munlock(actualPtr as unknown as number, BigInt(actualSize));
+    },
+  };
+}
+
+/**
+ * Map huge pages (Linux only, falls back to regular pages on other platforms)
+ */
+export function mmapHuge(size: number): MappedRegion | null {
+  if (size <= 0) {
+    throw new PageSizeError('Size must be positive');
+  }
+
+  const regionHandle = ffi.mmapHuge(BigInt(size));
+
+  if (regionHandle === null || regionHandle === 0n) {
+    return null;
+  }
+
+  const actualPtr = ffi.mmapPtr(regionHandle);
+  const actualSize = Number(ffi.mmapSize(regionHandle));
+
+  if (actualPtr === null || actualPtr === 0n) {
+    return null;
+  }
+
+  let unmapped = false;
+
+  return {
+    ptr: BigInt(actualPtr as unknown as number),
+    size: actualSize,
+    get buffer() {
+      if (unmapped) {
+        throw new PageSizeError('Cannot access unmapped region');
+      }
+      return toArrayBuffer(actualPtr as unknown as number, 0, actualSize);
+    },
+    unmap() {
+      if (!unmapped) {
+        unmapped = true;
+        ffi.munmap(regionHandle);
+      }
+    },
+    protect(prot: MemoryProtection) {
+      const protValue = PROTECTION_MAP[prot];
+      ffi.mprotect(actualPtr as unknown as number, BigInt(actualSize), protValue);
+    },
+    advise(advice: MemoryAdvice) {
+      const adviceValue = ADVICE_MAP[advice];
+      ffi.madvise(actualPtr as unknown as number, BigInt(actualSize), adviceValue);
+    },
+    lock() {
+      ffi.mlock(actualPtr as unknown as number, BigInt(actualSize));
+    },
+    unlock() {
+      ffi.munlock(actualPtr as unknown as number, BigInt(actualSize));
+    },
+  };
+}

package/dist/oom.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OOM (Out of Memory) handling strategies
+ */
+export type OOMStrategy = 'throw' | 'null' | 'callback' | 'fallback';
+export interface OOMOptions {
+    strategy?: OOMStrategy;
+    onOOM?: (requestedSize: number) => number | null;
+    fallbackSize?: number;
+}
+/**
+ * Set global OOM strategy
+ */
+export declare function setOOMStrategy(strategy: OOMStrategy): void;
+/**
+ * Get current global OOM strategy
+ */
+export declare function getOOMStrategy(): OOMStrategy;
+/**
+ * Set global OOM callback (for 'callback' strategy)
+ */
+export declare function setOOMCallback(callback: (size: number) => number | null): void;
+/**
+ * Set global fallback size (for 'fallback' strategy)
+ */
+export declare function setFallbackSize(size: number): void;
+/**
+ * Handle OOM according to strategy
+ * Returns null if strategy allows, otherwise throws
+ */
+export declare function handleOOM(requestedSize: number, options?: OOMOptions): number | null;
+/**
+ * Check if allocation would succeed (probe)
+ * Useful for 'fallback' strategy
+ */
+export declare function wouldAllocSucceed(size: number): boolean;
+//# sourceMappingURL=oom.d.ts.map

package/dist/oom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oom.d.ts","sourceRoot":"","sources":["oom.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAErE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,KAAK,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAOD;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,IAAI,CAE9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,UAAU,GACnB,MAAM,GAAG,IAAI,CAyBf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYvD"}

package/dist/oom.js

@@ -0,0 +1,73 @@
+/**
+ * OOM (Out of Memory) handling strategies
+ */
+// Global OOM strategy
+let globalOOMStrategy = 'throw';
+let globalOOMCallback = null;
+let globalFallbackSize = 4096;
+/**
+ * Set global OOM strategy
+ */
+export function setOOMStrategy(strategy) {
+    globalOOMStrategy = strategy;
+}
+/**
+ * Get current global OOM strategy
+ */
+export function getOOMStrategy() {
+    return globalOOMStrategy;
+}
+/**
+ * Set global OOM callback (for 'callback' strategy)
+ */
+export function setOOMCallback(callback) {
+    globalOOMCallback = callback;
+}
+/**
+ * Set global fallback size (for 'fallback' strategy)
+ */
+export function setFallbackSize(size) {
+    globalFallbackSize = size;
+}
+/**
+ * Handle OOM according to strategy
+ * Returns null if strategy allows, otherwise throws
+ */
+export function handleOOM(requestedSize, options) {
+    const strategy = options?.strategy ?? globalOOMStrategy;
+    switch (strategy) {
+        case 'null':
+            return null;
+        case 'callback': {
+            const callback = options?.onOOM ?? globalOOMCallback;
+            if (callback) {
+                return callback(requestedSize);
+            }
+            return null;
+        }
+        case 'fallback': {
+            return options?.fallbackSize ?? globalFallbackSize;
+        }
+        case 'throw':
+        default:
+            throw new Error(`Out of memory: failed to allocate ${requestedSize} bytes`);
+    }
+}
+/**
+ * Check if allocation would succeed (probe)
+ * Useful for 'fallback' strategy
+ */
+export function wouldAllocSucceed(size) {
+    try {
+        // This is a heuristic - actual allocation may still fail
+        const totalMem = process.memoryUsage().heapTotal;
+        const usedMem = process.memoryUsage().heapUsed;
+        const available = totalMem - usedMem;
+        // Be conservative - require 2x the requested size
+        return available >= size * 2;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=oom.js.map

package/dist/oom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oom.js","sourceRoot":"","sources":["oom.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,sBAAsB;AACtB,IAAI,iBAAiB,GAAgB,OAAO,CAAC;AAC7C,IAAI,iBAAiB,GAA6C,IAAI,CAAC;AACvE,IAAI,kBAAkB,GAAW,IAAI,CAAC;AAEtC;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAqB;IAClD,iBAAiB,GAAG,QAAQ,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAyC;IACtE,iBAAiB,GAAG,QAAQ,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,kBAAkB,GAAG,IAAI,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,aAAqB,EACrB,OAAoB;IAEpB,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,iBAAiB,CAAC;IAExD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;QAEd,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,QAAQ,GAAG,OAAO,EAAE,KAAK,IAAI,iBAAiB,CAAC;YACrD,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC;YACjC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,OAAO,OAAO,EAAE,YAAY,IAAI,kBAAkB,CAAC;QACrD,CAAC;QAED,KAAK,OAAO,CAAC;QACb;YACE,MAAM,IAAI,KAAK,CACb,qCAAqC,aAAa,QAAQ,CAC3D,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,CAAC;QACH,yDAAyD;QACzD,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC;QACjD,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC;QAC/C,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;QAErC,kDAAkD;QAClD,OAAO,SAAS,IAAI,IAAI,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/oom.ts

@@ -0,0 +1,96 @@
+/**
+ * OOM (Out of Memory) handling strategies
+ */
+
+export type OOMStrategy = 'throw' | 'null' | 'callback' | 'fallback';
+
+export interface OOMOptions {
+  strategy?: OOMStrategy;
+  onOOM?: (requestedSize: number) => number | null;
+  fallbackSize?: number;
+}
+
+// Global OOM strategy
+let globalOOMStrategy: OOMStrategy = 'throw';
+let globalOOMCallback: ((size: number) => number | null) | null = null;
+let globalFallbackSize: number = 4096;
+
+/**
+ * Set global OOM strategy
+ */
+export function setOOMStrategy(strategy: OOMStrategy): void {
+  globalOOMStrategy = strategy;
+}
+
+/**
+ * Get current global OOM strategy
+ */
+export function getOOMStrategy(): OOMStrategy {
+  return globalOOMStrategy;
+}
+
+/**
+ * Set global OOM callback (for 'callback' strategy)
+ */
+export function setOOMCallback(callback: (size: number) => number | null): void {
+  globalOOMCallback = callback;
+}
+
+/**
+ * Set global fallback size (for 'fallback' strategy)
+ */
+export function setFallbackSize(size: number): void {
+  globalFallbackSize = size;
+}
+
+/**
+ * Handle OOM according to strategy
+ * Returns null if strategy allows, otherwise throws
+ */
+export function handleOOM(
+  requestedSize: number,
+  options?: OOMOptions
+): number | null {
+  const strategy = options?.strategy ?? globalOOMStrategy;
+
+  switch (strategy) {
+    case 'null':
+      return null;
+
+    case 'callback': {
+      const callback = options?.onOOM ?? globalOOMCallback;
+      if (callback) {
+        return callback(requestedSize);
+      }
+      return null;
+    }
+
+    case 'fallback': {
+      return options?.fallbackSize ?? globalFallbackSize;
+    }
+
+    case 'throw':
+    default:
+      throw new Error(
+        `Out of memory: failed to allocate ${requestedSize} bytes`
+      );
+  }
+}
+
+/**
+ * Check if allocation would succeed (probe)
+ * Useful for 'fallback' strategy
+ */
+export function wouldAllocSucceed(size: number): boolean {
+  try {
+    // This is a heuristic - actual allocation may still fail
+    const totalMem = process.memoryUsage().heapTotal;
+    const usedMem = process.memoryUsage().heapUsed;
+    const available = totalMem - usedMem;
+
+    // Be conservative - require 2x the requested size
+    return available >= size * 2;
+  } catch {
+    return false;
+  }
+}