bun-memory 1.1.19 → 1.1.21

package/README.md

@@ -42,19 +42,28 @@ const modules = memory.modules;
 
 const client = modules['client.dll'];
 
-console.log(`Base address: 0x${client.base.toString(16)}`);
-console.log(`Size: ${client.size} bytes`);
+console.log(`Base: 0x%s — Size: %d bytes…`, client.base.toString(16), client.size);
+
+const address = memory.follow(client.base + 0x12345678n, [0x10n, 0x20n, 0x30n]);
 
 // Read a 32-bit integer…
-const value = memory.i32(client.base + 0x12345678n);
+const value = memory.i32(address);
 
 // Write a float…
-memory.f32(client.base + 0x12345678n, 3.14159);
+memory.f32(address, 3.14159);
 
 // Clean up…
 memory.close();
 ```
 
+### API — Follow / Read / Write
+
+Low-level helpers for pointer resolution and raw, allocation-free memory transfers. Use these when you need maximum control or want to reuse your own scratches.
+
+- follow
+- read
+- write
+
 ### API — Typed Reads / Writes
 
 A `Memory` instance exposes typed helpers for reading and writing process memory. Pairs indicate

package/package.json

@@ -22,7 +22,7 @@
     "url": "git://github.com/obscuritysrl/bun-memory.git"
   },
   "type": "module",
-  "version": "1.1.19",
+  "version": "1.1.21",
   "main": "./index.ts",
   "keywords": [
     "bun",

package/structs/Memory.ts

@@ -260,6 +260,63 @@ class Memory {
 
   // Core memory operations
 
+  /**
+   * Follows a multi-level pointer chain and returns the resolved absolute address.
+   *
+   * This helper walks a sequence of offsets starting at `address`, repeatedly
+   * dereferencing intermediate pointers as 64-bit unsigned integers, and finally
+   * adding the last offset without dereferencing.
+   *
+   * Semantics:
+   * - If `offsets` is empty, the original `address` is returned unchanged.
+   * - For each offset except the last, the method adds the offset to the current
+   *   address and dereferences a `uint64` at that location to get the next base.
+   * - If any intermediate dereference yields `0n`:
+   *   - when `throw_` is `true`, an error is thrown;
+   *   - otherwise, `-1n` is returned to indicate a null chain.
+   * - After all intermediate dereferences succeed, the final offset is **added**
+   *   (no dereference) and the resulting absolute address is returned.
+   *
+   * @param address - Starting absolute memory address (BigInt).
+   * @param offsets - Readonly list of `bigint` offsets that define the pointer path.
+   * @param throw_ - When `true`, throw on a null pointer encounter (default: `false`).
+   * @returns The resolved absolute address, or `-1n` if a null pointer was encountered and `throw_` is `false`.
+   * @throws {Error} When a null pointer is encountered and `throw_` is `true`.
+   *
+   * @example
+   * ```typescript
+   * // Typical multi-level pointer chain (moduleBase + 0x123456 → [0x10, 0x20] → +0x30 final)
+   * const client = memory.modules['client.dll'];
+   * const resolved = memory.follow(client.base, [0x10n, 0x20n, 0x30n]);
+   *
+   * if (resolved !== -1n) {
+   *   const health = memory.f32(resolved);
+   *   console.log('Health:', health);
+   * }
+   * ```
+   */
+  public follow(address: bigint, offsets: readonly bigint[], throw_ = false): bigint {
+    const last = offsets.length - 1;
+
+    if (last === -1) {
+      return address;
+    }
+
+    for (let i = 0; i < last; i++) {
+      address = this.u64((address += offsets[i]));
+
+      if (address === 0n) {
+        if (throw_) {
+          throw new Error('address must not be 0n.');
+        }
+
+        return -1n;
+      }
+    }
+
+    return address + offsets[last];
+  }
+
   /**
    * Reads data from the target process memory into the provided scratch buffer and returns that
    * same scratch object (strongly typed). This is a low-level, zero-copy helper used internally by