bun-memory 1.1.18 → 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/example/trigger-bot.ts

@@ -45,22 +45,17 @@ if (ClientPtr === undefined) {
 }
 // !
 
-const dec = new TextDecoder('utf-8');
-
-const buffer = Buffer.allocUnsafe(32);
-const pointers = [4749947025128n, 4749937696488n, 4749757372648n, 4745786211048n, 4745800086248n, 4748263960808n, 4748274490088n, 4748287459048n, 4747096900328n, 4747107757288n];
-
 console.time('test');
 
-while (true) {
-  for (const pointer of pointers) {
-    const cString = cs2.cString(pointer, 32).toString();
+// while (true) {
+//   for (const pointer of pointers) {
+//     const cString = cs2.cString(pointer, 32).toString();
 
-    if (cString.length > 32) {
-      console.log(cString);
-    }
-  }
-}
+//     if (cString.length > 32) {
+//       console.log(cString);
+//     }
+//   }
+// }
 
 console.timeEnd('test');
 

package/package.json

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

package/structs/Memory.ts

@@ -261,23 +261,91 @@ class Memory {
   // Core memory operations
 
   /**
-   * Reads data from the target process memory into a scratch buffer.
-   * This is a low-level method used internally by the typed read methods.
+   * 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`.
    *
-   * @param address - Memory address to read from
-   * @param scratch - Buffer to store the read data
-   * @returns This Memory instance for method chaining
-   * @throws {Win32Error} When the read operation fails
+   * @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
+   * typed readers.
+   *
+   * @typeParam T - Concrete scratch type extending {@link Scratch} (for example, `Scratch16`,
+   * `Scratch32`, a CString scratch, etc.).
+   *
+   * @param address - Absolute memory address to read from (BigInt).
+   * @param scratch - Destination scratch instance to receive the bytes.
+   * @returns The same scratch instance you passed in, typed as `T`.
+   * @throws {Win32Error} When the underlying `ReadProcessMemory` call fails.
    *
    * @todo Research what it will take to add CString to the Scratch type.
    *
    * @example
-   * ```typescript
-   * const buffer = new Uint8Array(4);
-   * memory.read(0x12345678n, buffer);
+   * ```ts
+   * // Strongly typed result based on the scratch you pass in:
+   * const s16 = memory.Scratch16;
+   * const out16 = memory.read(0x12345678n, s16);
+   * ```
+   *
+   * @example
+   * ```ts
+   * const myScratch = Buffer.allocUnsafe(64);
+   * const out = memory.read(0x1000_2000n, myScratch);
    * ```
    */
-  public read(address: bigint, scratch: Scratch): this {
+  public read<T extends Scratch>(address: bigint, scratch: T): T {
     const lpBaseAddress = address;
     const lpBuffer = scratch.ptr;
     const nSize = scratch.byteLength;
@@ -289,7 +357,7 @@ class Memory {
       throw new Win32Error('ReadProcessMemory', Kernel32.GetLastError());
     }
 
-    return this;
+    return scratch;
   }
 
   /**
@@ -306,7 +374,7 @@ class Memory {
    * memory.write(0x12345678n, buffer);
    * ```
    */
-  private write(address: bigint, scratch: Scratch): void {
+  private write(address: bigint, scratch: Scratch): this {
     const lpBaseAddress = address;
     const lpBuffer = scratch.ptr;
     const nSize = scratch.byteLength;
@@ -318,7 +386,7 @@ class Memory {
       throw new Win32Error('WriteProcessMemory', Kernel32.GetLastError());
     }
 
-    return;
+    return this;
   }
 
   // Public read / write methods…