wasm-memory-js

Manual memory management for JavaScript powered by WebAssembly.

wasm-memory-js brings a familiar C-style memory model to JavaScript. Allocate raw memory blocks, work directly with bytes through TypedArrays, and explicitly free memory when you're done.

Why?

JavaScript normally relies on garbage collection.

Sometimes, especially when working with:

• WebAssembly
• Large binary files
• Video processing
• Audio processing
• Custom runtimes
• Binary protocols
• Low-level systems experiments

it can be useful to manage memory manually.

wasm-memory-js provides a simple API inspired by C's malloc() and free() while remaining fully usable from JavaScript.

Installation

npm install wasm-memory-js

Basic Usage

import {
  allocMemory,
  freeMemory
} from "wasm-memory-js";

const block = allocMemory(100);

block.memory[0] = 65;
block.memory[1] = 66;
block.memory[2] = 67;

freeMemory(block);

Memory Block

Calling:

const block = allocMemory(100);

returns:

{
  ptr: 1024,
  size: 100,
  memory: Uint8Array(...)
}

Properties

| Property | Description | | -------- | ----------------------------------------- | | ptr | Pointer/address inside WebAssembly memory | | size | Allocated size in bytes | | memory | Uint8Array view over the allocated memory |

Large Memory Allocations

wasm-memory-js is configured with 1 GB of WebAssembly memory, allowing applications to work with large binary datasets and memory-intensive workloads.

Examples:

const block = allocMemory(
  1024 * 1024 * 100
); // 100 MB

const block = allocMemory(
  1024 * 1024 * 1024
); // 1 GB

Check the current WebAssembly memory size:

console.log(
  block.memory.buffer.byteLength
);

Typical use cases:

• Large file processing
• Video and audio pipelines
• WebAssembly runtimes
• Binary protocols
• Custom allocators
• Systems programming experiments

Notes

• Actual usable memory depends on available system resources.
• WebAssembly memory is backed by virtual memory and may not immediately consume physical RAM.
• Extremely large allocations may still fail if insufficient memory is available.
• Always free memory when finished.

Writing Data

const block = allocMemory(4);

block.memory[0] = 10;
block.memory[1] = 20;
block.memory[2] = 30;
block.memory[3] = 40;

Reading Data

console.log(block.memory[0]);
console.log(block.memory[1]);

Working With Strings

const block = allocMemory(100);

const bytes =
  new TextEncoder().encode(
    "hello"
  );

block.memory.set(bytes);

const text =
  new TextDecoder().decode(
    block.memory.subarray(
      0,
      bytes.length
    )
  );

console.log(text);

Output:

hello

Freeing Memory

freeMemory(block);

After freeing:

block.ptr === null;
block.memory === null;
block.size === 0;

This helps prevent accidental use-after-free bugs.

Important Notes

Memory Is Not Erased

Calling:

freeMemory(block);

does not immediately erase bytes.

It marks the memory as available for future allocations.

Do Not Use Freed Blocks

Bad:

freeMemory(block);

block.memory[0] = 123;

Good:

block.memory[0] = 123;

freeMemory(block);

Ownership vs Data

When memory is freed:

freeMemory(block);

ownership of the memory is released, but the old bytes may still remain in memory until they are overwritten by a future allocation.

This behavior is similar to C's:

free(ptr);

and is one of the most important concepts in manual memory management.

TypeScript Support

wasm-memory-js ships with built-in TypeScript definitions.

import {
  allocMemory,
  freeMemory
} from "wasm-memory-js";

const block = allocMemory(100);

block.memory[0] = 123;

freeMemory(block);

Inspiration

wasm-memory-js is inspired by:

void* ptr = malloc(size);

/* use memory */

free(ptr);

and brings a similar workflow to JavaScript through WebAssembly.

Educational Purpose

This project was created to help JavaScript developers better understand:

• Memory allocation
• Pointers
• Heaps
• WebAssembly memory
• Manual memory management
• Systems programming concepts

through a simple JavaScript API.

License

MIT