node-weak-ref/README.md

Make weak references to JavaScript Objects.

node-weak-ref
=========
### Make weak references to JavaScript Objects.
[![Build Status](https://github.com/Vinccool96/node-weak/workflows/Node%20CI/badge.svg)](https://github.com/TooTallNate/node-weak/actions?workflow=Node+CI)

On certain rarer occasions, you run into the need to be notified when a JavaScript
object is going to be garbage collected. This feature is exposed to V8's C++ API,
but not to JavaScript.

That's where `node-weak-ref` comes in! This module exports V8's `Persistent<Object>`
functionality to JavaScript. This allows you to create weak references, and
optionally attach a callback function to any arbitrary JS object. The callback
function will be invoked right before the Object is garbage collected (i.e. after
there are no more remaining references to the Object in JS-land).

This module can, for example, be used for debugging; to determine whether or not
an Object is being garbage collected as it should.
Take a look at the example below for commented walkthrough scenario.

Installation
------------

Install with `npm`:

``` bash
$ npm install node-weak-ref
```

Install with `yarn`:

``` bash
$ yarn add node-weak-ref
```

Example
-------

Here's an example of calling a `cleanup()` function on a Object before it gets
garbage collected:

``` js
import { create } from "weak"

// we are going to "monitor" this Object and invoke "cleanup"
// before the object is garbage collected
let obj = {
  a: true,
  foo: "bar",
}

// Here's where we set up the weak reference
const ref = create(obj, function () {
  // `this` inside the callback is the EventEmitter.
  console.log('"obj" has been garbage collected!')
})

// While `obj` is alive, `ref` proxies everything to it, so:
ref.a === obj.a
ref.foo === obj.foo

// Clear out any references to the object, so that it will be GC'd at some point...
obj = null

// Time passes, and the garbage collector is run

// `callback()` above is called, and `ref` now acts like an empty object.
typeof ref.foo === 'undefined'
```

Weak Callback Function "Best Practices"
---------------------------------------

It's important to be careful when using the "callbacks" feature of `node-weak`,
otherwise you can end up in a situation where the watched object will never
be garbage collected.

You _should **not**_ define the callback function in the same scope as the
object that is being watched. It's often best to define the callback function
at the highest scope possible (top-level being the best). Named functions
work really well for this:

``` js
const http = require("http")
const { create } = require("weak")

http.createServer(function (req, res) {
  weak(req, gcReq)
  weak(res, gcRes)
  res.end("Hello World\n")
}).listen(3000)

function gcReq () {
  console.log("GC'd `req` object")
}

function gcRes () {
  console.log("GC'd `res` object")
}
```

API
---

### Weakref create(Object obj [, Function callback])

The function that creates the weak reference.
The first argument is the Object that should be monitored.
The Object can be a regular Object, an Array, a Function, a RegExp, or any of
the primitive types or constructor function created with `new`.

Optionally, you can set a callback function to be invoked
before the object is garbage collected.

### Object get(Weakref ref)

`get()` returns the actual reference to the Object that this weak reference was
created with. If this is called with a dead reference, `undefined` is returned.

### Boolean isDead(Weakref ref)

Checks to see if `ref` is a dead reference. Returns `true` if the original Object
has already been GC'd, `false` otherwise.

### Boolean isWeakRef(Object obj)

Checks to see if `obj` is "weak reference" instance. Returns `true` if the
passed in object is a "weak reference", `false` otherwise.

### EventEmitter addCallback(Weakref ref, Function callback)

Adds `callback` to the Array of callback functions that will be invoked before the
Object gets garbage collected. The callbacks get executed in the order that they
are added.

### EventEmitter removeCallback(Weakref ref, Function callback)

Removes `callback` from the Array of callback functions that will be invoked before
the Object gets garbage collected.

### EventEmitter removeCallbacks(Weakref ref)

Empties the Array of callback functions that will be invoked before the Object gets
garbage collected.

### Array callbacks(Weakref ref)

Returns an Array that `ref` iterates through to invoke the GC callbacks. This
utilizes node's `EventEmitter#listeners()` function and therefore returns a copy
in node 0.10 and newer.