package
A simplified FinalizationRegistry utility that works
npm install gc-hookGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
21.1 kB
Includes dependencies.
Social Media Photo by Steve Johnson on Unsplash
A simplified FinalizationRegistry utility that works:
// available as commonjs too
import { create, drop } from 'gc-hook';
// keep a count of all passed references created here
let references = 0;
// notify how many references are still around
const onGarbageCollected = myUtility => {
console.log(--references, 'references still used');
};
export default options => {
const myUtility = { ...options, do: 'something' };
console.log(++references, 'references provided');
// return a proxy to avoid holding directly myUtility
// while keeping the utility in memory until such proxy
In case you'd like to be notified when an object not meant to leak has been collected,
you can use the create function in its most simple way:
import { create } from 'gc-hook';
const privateObject = {};
const onGC = privateObject => {
console.log(privateObject, 'not used anymore');
};
export create(privateObject, onGC);If you are handling FFI related references, you can hold on internal values and yet return whatever artifact you like in the wild.
import { create } from 'gc-hook';
export const createWrap = reference => {
const onGC = reference => {
ffi.gc.decreaseRefCounting(reference);
};
const wrap = function (...args) {
return ffi.apply(reference, args);
};
wrap.destroy = onGC;
// will return the wrap as it is without holding
// the reference in the wild
return create(reference, onGC, { return: wrap });
};In case you need to relate a specific object to a unique id (coincident use case) and you don't need to ever unregister the held reference / id internally:
import { create } from 'gc-hook';
const onGC = id => {
console.log(id.valueOf(), 'not needed anymore');
};
// id can be any primitive in here and ref must be used as return
export const relate = (id, ref) => {
return create(
typeof id === 'string' ? new String
In case you need to relate a specific object to a unique id but you still would like to drop the reference from the FinalizationRegistry later on:
import { create, drop } from 'gc-hook';
const onGC = ({ id, time }) => {
console.log(id, 'created at', time, 'not needed anymore');
};
// id can be any primitive in here
export const relate = (id, wrap) => {
const token = { id, time: Date.now() };
const hold = typeof id === 'string' ? new String(id) : new Number(id);
return {
One does not need to pass to the GC callback just a specific kind of value so that it's possible to combine various operations at once:
import { create, drop } from 'gc-hook';
export const createComplexHeld = ref => {
const onGC = ({ ref, destroy, time }) => {
destroy();
console.log(ref, 'created at', time, 'not needed');
};
const wrap = function (...args) {
return ffi.apply(ref, args);
};
wrap.destroy = () => {
drop(held);
If you'd like to track one or more reference you can use gc-hook/track helper.
All it does is to notify in console, via console.debug, that such reference has eventually be collected.
// or use https://esm.run/gc-hook/track live
import BUG_GC from 'gc-hook/track';
// HINT: use a constant so that rollup or bundlers
// can eventually remove all the dead code in production
const D = true;
// create any reference
let test = { any: 'value' };
// when debugging, pass an object literal to simplify
// naming -> references convention
D&&BUG_GC({ test });
setTimeout(() => { test = null; });
// now press the Collect Garbage button in devtools
// and see the lovely message: **test** collected// returns a ProxyHandler<hold> or whatever
// the `return` option wants to return.
// The returned reference is the one that
// notifies the GC handler once destroyed
// or not referenced anymore in the consumer code.
create(
// the reference or primitive to keep in memory
// until the returned value is used. It can be
// a primitive, but it requires `token = false`,
// or any reference to hold in memory.
hold,
// a callback that will receive the held value
// whenever its Proxy or wrapper is not referenced
// anymore in the program using it.
onGarbageCollected,
// optional properties:
{
// if passed along, it will be used automatically
// to create the ProxyHandler<hold>.
handler = Object.create(null),
// override the otherwise automatically created Proxy
// for the `held` reference.
return = new Proxy(hold, handler),
This use case was designed after pyodide Proxy and GC dance around passed references to the JS world.
The only and most important thing is to never return something part of the held logic otherwise that returned value cannot possibly ever be Garbage Collected.