weak-napi: N-API Weak References

Common errors

• Error: The module 'weak-napi.node' was compiled against a different Node.js version. This version of Node.js cannot load this module.

  cause The native addon was compiled for a different Node.js major version than the one currently running the application.
  fix Run `npm rebuild weak-napi` in your project directory to recompile the native module against your current Node.js version.

• TypeError: Object.getOwnPropertyDescriptors called on non-object

  cause This error or similar Proxy-related errors occur when `weak-napi` is run on a Node.js version older than 6, which lacks full support for JavaScript Proxy objects.
  fix Upgrade your Node.js environment to version 6 or newer. Using a recent LTS version is highly recommended.

• GC callback function not firing, or objects never appear to be garbage collected.

  cause A strong reference to the weakly-referenced object still exists somewhere in the application's memory, preventing the garbage collector from reclaiming it. A common culprit is defining the callback in a closure that captures the object.
  fix Review your code to ensure no strong references remain to the object after `obj = null;`. Pay close attention to the scope where your GC callback is defined, ensuring it doesn't close over the `obj` variable itself.

• Error: Cannot find module 'weak-napi' or Error: The specified module could not be found.

  cause The `weak-napi` native addon failed to compile during installation, or its compiled binary (`.node` file) is missing or corrupted.
  fix Check the `npm install` logs for any compilation errors. Ensure you have required build tools (like `node-gyp` and a C++ compiler) installed. Then run `npm rebuild weak-napi` to attempt recompilation.

Warnings

• breaking The `isNearDeath()` method is explicitly not supported and will always return `false`. Code relying on this method's prior functionality in `node-weak` will break or behave unexpectedly.
  Fix: Remove or refactor code that uses `isNearDeath()`. `weak-napi` does not provide an equivalent API.
• gotcha Defining the GC callback function within the same scope as the object being weakly referenced can unintentionally create a strong reference to the object, preventing it from ever being garbage collected. This leads to memory leaks.
  Fix: Always define GC callback functions in the highest possible scope (e.g., top-level or a module-level named function) to ensure they do not capture a strong reference to the target object. Refer to 'Weak Callback Function "Best Practices"' in the documentation.
• breaking `weak-napi` requires Node.js version 6 or higher due to its internal use of JavaScript `Proxy` objects. Running on older Node.js versions will result in runtime errors related to unsupported language features.
  Fix: Upgrade your Node.js runtime environment to version 6 or newer. The latest LTS version is recommended for stability and security.
• gotcha Although `weak-napi` uses N-API (which reduces recompilation issues), it is still a native Node.js addon. Compilation can fail if your system lacks necessary build tools (e.g., C++ compilers, Python, `node-gyp`).
  Fix: Ensure you have the appropriate build tools installed for your operating system (e.g., `windows-build-tools` for Windows, `build-essential` for Linux, Xcode Command Line Tools for macOS). If issues persist, try `npm rebuild weak-napi`.

Install

• npm install weak-napi npm
• yarn add weak-napi yarn
• pnpm add weak-napi pnpm

Imports

• weak (CJS)

  const weak = require('weak-napi')

  CommonJS import pattern for Node.js environments. The module exports a single function.
• weak (ESM)
  wrong:

  import { weak } from 'weak-napi'

  correct:

  import weak from 'weak-napi'

  ES Module import pattern. 'weak-napi' exports a default function, not a named export. Node.js 6+ is required for full functionality.

Quickstart

This example demonstrates how to create a weak reference to an object and register a callback function to be executed when the object is garbage collected. It highlights best practices for callback placement and the process of dereferencing the original object. Due to the non-deterministic nature of garbage collection, the callback's execution time is not guaranteed without explicitly exposing V8's GC via Node.js `--expose-gc` flag.

var weak = require('weak-napi');

// We will monitor this object and invoke 'cleanup' after it's garbage collected
let obj = {
    id: 'my-object',
    data: Array(1000).fill('some data string') // Make it large enough to be GC'd
};

// Define the cleanup callback at a high scope to avoid strong references
function cleanupCallback() {
  console.log('"obj" with ID ' + this.id + ' has been garbage collected!');
}

// Create a weak reference to obj with the cleanup callback
// Note: `this` inside the callback refers to the EventEmitter instance returned by `weak()`.
const ref = weak(obj, cleanupCallback);
ref.id = obj.id; // Store ID on the ref for logging in callback

console.log('Weak reference created. Initial obj.id:', obj.id);

// Dereference the object to allow it to be garbage collected
obj = null;

console.log('Original object reference cleared. Waiting for GC...');

// In a real scenario, you'd let your application run.
// For demonstration, we might try to force GC, but it's not reliable or recommended.
// Global.gc is usually not available unless explicitly enabled with --expose-gc.
// If process.env.EXPOSE_GC is set, you can try to call it:
if (typeof global.gc === 'function') {
  console.log('Attempting to force garbage collection...');
  global.gc();
  global.gc(); // Call twice for better chances
} else {
  console.log('Run Node.js with --expose-gc flag to see immediate callback execution via global.gc().');
  console.log('Otherwise, the callback will eventually fire when V8 decides to run GC naturally.');
}

// Keep the process alive for a bit to allow GC to run naturally
setTimeout(() => {
  console.log('Process ending. If GC ran, you should have seen the callback message.');
}, 500);