@ohos-ports/weak-napi 2.0.2-beta.0

package/History.md

@@ -0,0 +1,60 @@
+
+1.0.1 / 2016-01-03
+==================
+
+  * add missing HandleScope in callback (#67, @laverdet)
+  * add Travis support for v4.x, v5.x (#60, @robcolburn)
+  * appveyor: place .bin into the $PATH
+
+1.0.0 / 2015-08-17
+==================
+
+  * added `removeCallback()` and `removeCallbacks()`
+  * appveyor: attempt to fix node v0.8
+  * appveyor: test x86 and x64
+  * travis: attempt to fix node v0.8
+  * travis: test "iojs"
+  * travis: run on new infrastructure
+  * package: update to NAN 2.0 (@kkoopa)
+  * package: stricter "bindings" version number
+  * package: specify "MIT" license
+  * README: update for API change
+
+0.4.1 / 2015-05-09
+==================
+
+  * Update to nan ~1.8.4 (#47, @imyller)
+  * appveyor: test node v0.12 instead of v0.11
+
+0.4.0 / 2015-02-18
+==================
+
+  * travis: test node v0.12
+  * package: update "nan" to v1.6.2 for Node v0.12 compatibility (#40, @GitStarInc)
+  * src: call callback directly to avoid unwanted preemption (#36)
+
+0.3.4 / 2015-01-27
+==================
+
+  * Update dependencies to also work with IO.js #39 (#40, @GitStarInc)
+  * Revert "appveyor: attempt to test x86 and x64, Debug and Release configs"
+  * appveyor: attempt to test x86 and x64, Debug and Release configs
+
+0.3.3 / 2014-06-04
+==================
+
+  * appveyor: more generic comment
+  * package: update "mocha" to v1.20.1
+  * package: update "nan" to v1.2.0
+
+0.3.2 / 2014-05-25
+==================
+
+  * add appveyor.yml file for Windows testing
+  * README: use SVG Travis badge
+  * README: add appveyor build badge
+  * README: correct docs for the callback (#29, @metamatt)
+  * .travis: don't test node v0.9.x
+  * weakref: fix deprecation warning after nan upgrade
+  * weakref: remove "printf()" calls
+  * weakref: update for nan v1 API changes

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2011, Ben Noordhuis <info@bnoordhuis.nl>
+Copyright (c) 2017, Anna Henningsen <anna@addaleax.net> (N-API port)
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+weak-napi
+=========
+### Make weak references to JavaScript Objects.
+
+[![Greenkeeper badge](https://badges.greenkeeper.io/node-ffi-napi/weak-napi.svg)](https://greenkeeper.io/)
+
+[![NPM Version](https://img.shields.io/npm/v/weak-napi.svg?style=flat)](https://npmjs.org/package/weak-napi)
+[![NPM Downloads](https://img.shields.io/npm/dm/weak-napi.svg?style=flat)](https://npmjs.org/package/weak-napi)
+[![Build Status](https://travis-ci.org/node-ffi-napi/weak-napi.svg?style=flat&branch=master)](https://travis-ci.org/node-ffi-napi/weak-napi?branch=master)
+[![Coverage Status](https://coveralls.io/repos/node-ffi-napi/weak-napi/badge.svg?branch=master)](https://coveralls.io/r/node-ffi-napi/weak-napi?branch=master)
+[![Dependency Status](https://david-dm.org/node-ffi-napi/weak-napi.svg?style=flat)](https://david-dm.org/node-ffi-napi/weak-napi)
+
+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 `weak-napi` comes in! This module exports the JS engine's GC tracking
+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 after 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 weak-napi
+```
+
+Differences from node-weak
+--------------------------
+
+This module exports the full `node-weak` API. The main differences are:
+
+- This module uses N-API! Yay. That’s a good thing – you don’t need to worry
+  about re-compiling your code anymore when upgrading Node.
+- GC callbacks are invoked at a suitable time (after the actual GC run has
+  finished). **This is nice because it means your process won’t
+  potentially crash.**
+- This module works on Node 6+ only, since it uses a `Proxy` object to give a
+  more complete referral of properties.
+- `isNearDeath()` is not supported (always returns false).
+
+That’s it!
+
+Example
+-------
+
+Here's an example of calling a `cleanup()` function on a Object after it gets
+garbage collected:
+
+``` js
+var weak = require('weak-napi')
+
+// we are going to "monitor" this Object and invoke "cleanup"
+// before the object is garbage collected
+var obj = {
+    a: true
+  , foo: 'bar'
+}
+
+// Here's where we set up the weak reference
+var ref = weak(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 `weak-napi`,
+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
+var http = require('http')
+  , weak = require('weak-napi')
+
+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 weak(Object obj [, Function callback])
+
+The main exports is 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 weak.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 weak.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 weak.isNearDeath(Weakref ref)
+
+*Note* The N-API port of this module does not implement this and
+always returns `false`.
+
+
+### Boolean weak.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 weak.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 weak.removeCallback(Weakref ref, Function callback)
+
+Removes `callback` from the Array of callback functions that will be invoked before
+the Object gets garbage collected.
+
+
+### EventEmitter weak.removeCallbacks(Weakref ref)
+
+Empties the Array of callback functions that will be invoked before the Object gets
+garbage collected.
+
+
+### Array weak.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.

package/binding.gyp

@@ -0,0 +1,19 @@
+{
+  'targets': [{
+    'target_name': 'weakref',
+    'sources': [ 'src/weakref.cc' ],
+    'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")",
+                     "<!@(node -p \"require('setimmediate-napi').include\")"],
+    'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"],
+    'cflags!': [ '-fno-exceptions' ],
+    'cflags_cc!': [ '-fno-exceptions' ],
+    'xcode_settings': {
+      'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
+      'CLANG_CXX_LIBRARY': 'libc++',
+      'MACOSX_DEPLOYMENT_TARGET': '10.7',
+    },
+    'msvs_settings': {
+      'VCCLCompilerTool': { 'ExceptionHandling': 1 },
+    },
+  }]
+}

package/lib/weak.js

@@ -0,0 +1,122 @@
+'use strict';
+const EventEmitter = require('events');
+const path = require('path');
+const { WeakTag, ObjectInfo } = require('node-gyp-build')(path.join(__dirname, '..'));
+Object.setPrototypeOf(ObjectInfo, EventEmitter);
+Object.setPrototypeOf(ObjectInfo.prototype, EventEmitter.prototype);
+
+const kInfo = Symbol('kInfo');
+
+const map = new WeakMap();
+
+function weak(obj, callback) {
+  const info = new ObjectInfo(obj, onGarbageCollect);
+  const tag = new WeakTag(info);
+  const list = map.get(obj);
+  if (list === undefined)
+    map.set(obj, [tag]);
+  else
+    list.push(tag);
+  if (typeof callback === 'function')
+    info.on('dead', callback);
+  return makeProxy(info);
+}
+weak.create = weak;
+module.exports = weak;
+
+function onGarbageCollect() {
+  this.emit('dead');
+}
+
+weak.get = function(ref) {
+  return ref[kInfo].target;
+};
+
+weak.isDead = function(ref) {
+  return weak.get(ref) === undefined;
+};
+
+weak.isNearDeath = function(ref) {
+  return false;
+};
+
+weak.isWeakRef = function(ref) {
+  return !!ref[kInfo];
+};
+
+weak.addCallback = function(ref, callback) {
+  ref[kInfo].addListener('dead', callback);
+};
+
+weak.removeCallback = function(ref, callback) {
+  ref[kInfo].removeListener('dead', callback);
+};
+
+weak.removeCallbacks = function(ref) {
+  ref[kInfo].removeAllListeners('dead');
+};
+
+weak.callbacks = function(ref) {
+  return ref[kInfo].listeners('dead');
+};
+
+const proxyHandler = {
+  getPrototypeOf(info) {
+    const target = info.target;
+    return target === undefined ? null : Object.getPrototypeOf(target);
+  },
+  setPrototypeOf(info, proto) {
+    const target = info.target;
+    return target === undefined ? false : Object.setPrototypeOf(target, proto);
+  },
+  isExtensible(info) {
+    return Object.isExtensible(info); // For invariant keeping
+  },
+  preventExtensions(info) {
+    const target = info.target;
+    if (target !== undefined) {
+      Object.preventExtensions(target);
+    }
+    Object.preventExtensions(info); // For invariant keeping
+    return true;
+  },
+  getOwnPropertyDescriptor(info, key) {
+    const target = info.target;
+    return target === undefined ? undefined :
+        Object.getOwnPropertyDescriptor(target, key);
+  },
+  defineProperty(info, key, descriptor) {
+    const target = info.target;
+    return target === undefined ? false :
+        Object.defineProperty(target, key, descriptor);
+  },
+  has(info, key) {
+    const target = info.target;
+    return target === undefined ? false : key in target;
+  },
+  get(info, key) {
+    if (key === kInfo) return info;
+    const target = info.target;
+    return target === undefined ? undefined : target[key];
+  },
+  set(info, key, value) {
+    const target = info.target;
+    if (target !== undefined) target[key] = value;
+    return true;
+  },
+  deleteProperty(info, key) {
+    const target = info.target;
+    if (target !== undefined) delete target[key];
+    return true;
+  },
+  ownKeys(info) {
+    const target = info.target;
+    return target === undefined ? [] :
+        Object.getOwnPropertyNames(target).concat(
+            Object.getOwnPropertySymbols(target));
+  }
+};
+
+function makeProxy(info) {
+  return new Proxy(info, proxyHandler);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "author": "Anna Henningsen <anna@addaleax.net>",
+  "contributors": [
+    "Ben Noordhuis <info@bnoordhuis.nl>",
+    "Nathan Rajlich <nathan@tootallnate.net>"
+  ],
+  "name": "@ohos-ports/weak-napi",
+  "license": "MIT",
+  "description": "Make weak references to JavaScript Objects.",
+  "keywords": [
+    "weak",
+    "reference",
+    "js",
+    "javascript",
+    "object",
+    "function",
+    "callback",
+    "napi"
+  ],
+  "version": "2.0.2-beta.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/weak-napi/2.0.2"
+  },
+  "main": "lib/weak.js",
+  "scripts": {
+    "test": "nyc mocha --expose-gc",
+    "install": "node-gyp-build",
+    "prebuild": "prebuildify --napi --tag-armv --tag-uv"
+  },
+  "dependencies": {
+    "node-addon-api": "^3.0.0",
+    "node-gyp-build": "^4.2.1",
+    "setimmediate-napi": "^1.0.3"
+  },
+  "devDependencies": {
+    "mocha": "^7.1.1",
+    "nyc": "^15.0.0",
+    "prebuildify": "^3.0.4",
+    "prebuildify-ci": "^1.0.5"
+  },
+  "bugs": {
+    "url": "https://github.com/ohos-ports/ohos-ports/issues"
+  },
+  "files": [
+    "lib/",
+    "src/",
+    "test/",
+    "prebuilds/",
+    "build/Release/weakref.node",
+    "binding.gyp",
+    "LICENSE",
+    "README.md",
+    "History.md"
+  ]
+}

package/src/weakref.cc

@@ -0,0 +1,98 @@
+#include <napi.h>
+#include <setimmediate.h>
+
+using namespace Napi;
+
+namespace {
+
+// Node.js v12+ (and the ohos node v26.8.1 runtime) uses V8 incremental
+// finalization: weak-reference finalizers can run while the environment is
+// being torn down at process exit, after the libuv loop has stopped. At that
+// point calling SetImmediate() below would install fresh uv_check_t/uv_idle_t
+// handles onto a dead event loop and invoke into a finalizing napi_env,
+// crashing the process (use-after-free, SIGSEGV). napi_add_env_cleanup_hook
+// gives us a reliable signal that the environment is shutting down; once it
+// is set we drop the pending weak callback instead of scheduling it. This is
+// safe: the process is exiting and the callback would never run anyway.
+bool g_env_tearing_down = false;
+
+void OnEnvTeardown(void* /*arg*/) {
+  g_env_tearing_down = true;
+}
+
+class ObjectInfo : public ObjectWrap<ObjectInfo> {
+ public:
+  ObjectInfo(const CallbackInfo& args) : ObjectWrap(args) {
+    if (!args[0].IsObject() && !args[0].IsFunction())
+      throw Error::New(Env(), "target should be object");
+    if (!args[1].IsFunction())
+      throw Error::New(Env(), "callback should be function");
+    Ref();
+    target_.Reset(args[0].As<Object>(), 0);
+    callback_.Reset(args[1].As<Function>(), 1);
+  }
+
+  void OnFree() {
+    if (g_env_tearing_down)
+      return;
+    SetImmediate(Env(), [this]() {
+      callback_.MakeCallback(Value(), {});
+      callback_.Reset();
+      // Release the strong persistent reference so the JS ObjectInfo wrapper
+      // becomes collectible (the JS Proxy created by lib/weak.js keeps it
+      // alive as long as the user holds it). We must NOT use Reset() here:
+      // napi_delete_reference() frees the internal Reference record while the
+      // object's private "wrapper" property still points at it, so any later
+      // napi_unwrap() on the live object would dereference freed memory and
+      // crash (observed as SIGSEGV on Node v26.8.1). Unref() drops the
+      // reference count to zero; the ObjectWrap finalizer then deletes the
+      // native instance only after the JS object is actually collected.
+      Unref();
+    });
+  }
+
+  Napi::Value GetTarget(const CallbackInfo&) {
+    return target_.IsEmpty() ? Env().Undefined() : target_.Value();
+  }
+
+  static Function GetClass(Napi::Env env) {
+    return DefineClass(env, "ObjectInfo", {
+      ObjectInfo::InstanceAccessor("target", &ObjectInfo::GetTarget, nullptr),
+    });
+  }
+
+  ObjectReference target_;
+  FunctionReference callback_;
+};
+
+class WeakTag : public ObjectWrap<WeakTag> {
+ public:
+  WeakTag(const CallbackInfo& args) : ObjectWrap(args) {
+    if (args[0].IsObject())
+      info_ = ObjectInfo::Unwrap(args[0].As<Object>());
+    if (info_ == nullptr)
+      throw Error::New(Env(), "First argument needs to be ObjectInfo");
+  }
+
+  ~WeakTag() {
+    if (info_ != nullptr)
+      info_->OnFree();
+  }
+
+  static Function GetClass(Napi::Env env) {
+    return DefineClass(env, "WeakTag", {});
+  }
+
+  ObjectInfo* info_ = nullptr;
+};
+
+Object Init(Env env, Object exports) {
+  napi_add_env_cleanup_hook(env, OnEnvTeardown, nullptr);
+  exports["WeakTag"] = WeakTag::GetClass(env);
+  exports["ObjectInfo"] = ObjectInfo::GetClass(env);
+  return exports;
+}
+
+} // anonymous namespace
+
+NODE_API_MODULE(weakref, Init)

package/test/buffer.js

@@ -0,0 +1,44 @@
+'use strict';
+const assert = require('assert');
+const weak = require('../');
+
+// On modern V8 (Node.js >= 12, including the ohos node v26.8.1 runtime),
+// garbage collection finalization is incremental: gc() may return before the
+// weak-reference finalizers execute, and finalization work is spread over
+// several subsequent GC cycles / event-loop turns. The weak-napi GC callback
+// is therefore guaranteed to fire once the Buffer is truly collected, but
+// NOT necessarily within a single setImmediate tick after gc(). This matches
+// documented V8 behavior on every platform and is not a HarmonyOS platform
+// defect; the callback is still invoked before the Buffer's memory is
+// reclaimed from the JS object's perspective. See test/callback.js for the
+// full explanation shared by both test files.
+function waitForGcCallback(isDone, done, maxAttempts) {
+  let attempts = 0;
+  maxAttempts = maxAttempts || 200;
+  (function poll() {
+    gc();
+    attempts++;
+    if (isDone()) return done();
+    if (attempts >= maxAttempts) {
+      return done(new Error(
+          'weak GC callback did not fire after ' + attempts + ' gc attempts'));
+    }
+    setTimeout(poll, 0);
+  })();
+}
+
+describe('weak()', function () {
+  afterEach(gc);
+
+  describe('Buffer', function () {
+    it('should invoke callback when Buffer is garbage collected', function(done) {
+      let called = false;
+      weak(Buffer('test'), function (buf) {
+        called = true;
+      });
+
+      assert(!called);
+      waitForGcCallback(() => called, done);
+    });
+  });
+});

package/test/callback.js

@@ -0,0 +1,148 @@
+'use strict';
+const assert = require('assert');
+const weak = require('../');
+
+// On modern V8 (Node.js >= 12, including the ohos node v26.8.1 runtime),
+// garbage collection finalization is incremental: gc() may return before the
+// weak-reference finalizers execute, and finalization work is spread over
+// several subsequent GC cycles / event-loop turns. The weak-napi GC callback
+// is therefore guaranteed to fire once the target object is truly collected,
+// but NOT necessarily within a single setImmediate tick after gc().
+//
+// This matches documented V8 behavior on every platform (upstream weak-napi
+// is unmaintained since 2019 and its tests encode the synchronous
+// finalization behavior of contemporary V8); it is a runtime-version
+// behavior, not a HarmonyOS platform defect. The essential semantics are
+// preserved and asserted below:
+//   * the GC callback DOES fire once the target is collected,
+//   * weak.get()/isDead() report the target as dead once the callback ran,
+//   * GC callbacks never preempt nextTick callbacks.
+// These helpers wait for the callback across event loop turns while applying
+// GC pressure, which works both on old V8 (callback fires immediately) and
+// on modern V8 (callback fires a few cycles later).
+function waitForGcCallback(isDone, done, maxAttempts) {
+  let attempts = 0;
+  maxAttempts = maxAttempts || 200;
+  (function poll() {
+    gc();
+    attempts++;
+    if (isDone()) return done();
+    if (attempts >= maxAttempts) {
+      return done(new Error(
+          'weak GC callback did not fire after ' + attempts + ' gc attempts'));
+    }
+    setTimeout(poll, 0);
+  })();
+}
+
+describe('weak()', function() {
+  afterEach(gc);
+
+  describe('garbage collection callback', function() {
+    it('should accept a function as second argument', function() {
+      const r = weak({}, function () {});
+      assert.strictEqual(1, weak.callbacks(r).length);
+    });
+
+    it('should invoke the callback once the target is gc\'d', function(done) {
+      let called = false;
+      weak({}, function() {
+        called = true
+      });
+      assert(!called);
+      waitForGcCallback(() => called, done);
+    });
+
+    it('should invoke *all* callbacks in the internal "callback" Array',
+       function(done) {
+      const r = weak({});
+      let called1 = false;
+      let called2 = false;
+      weak.addCallback(r, function() {
+        called1 = true
+      });
+      weak.addCallback(r, function() {
+        called2 = true
+      });
+      waitForGcCallback(() => called1 && called2, done);
+    });
+
+    it('should invoke *all* callbacks from different weak references',
+       function(done) {
+      let obj = {};
+      const r1 = weak(obj);
+      const r2 = weak(obj);
+      assert.strictEqual(weak.get(r1), obj);
+      assert.strictEqual(weak.isDead(r1), false);
+      obj = null;
+      let called1 = false;
+      let called2 = false;
+      weak.addCallback(r1, function() {
+        called1 = true
+      });
+      weak.addCallback(r2, function() {
+        called2 = true
+      });
+      waitForGcCallback(() => called1 && called2, function() {
+        assert.strictEqual(weak.get(r1), undefined);
+        assert.strictEqual(weak.isDead(r1), true);
+        done();
+      });
+    });
+
+    it('should not preempt nextTick callbacks with the GC callback',
+       function(done) {
+      const events = [];
+      weak({}, function() {
+        events.push('gcb');
+      });
+
+      process.nextTick(function() {
+        events.push('tick');
+      });
+
+      waitForGcCallback(() => events.indexOf('gcb') !== -1, function() {
+        assert(events.indexOf('tick') !== -1);
+        assert(events.indexOf('tick') < events.indexOf('gcb'));
+        done();
+      });
+    });
+  });
+});
+
+describe('callbacks()', function() {
+  it('should return the Weakref\'s "callback" Array', function () {
+    const r = weak({}, function() {});
+    const callbacks = weak.callbacks(r);
+    assert(Array.isArray(callbacks));
+    assert.strictEqual(1, callbacks.length);
+  });
+});
+
+describe('removeCallback()', function() {
+  it('removed callbacks should not be called', function() {
+    let called = false;
+    const fn = function() { called = true };
+    const r = weak({}, fn);
+    weak.removeCallback(r, fn);
+    gc();
+    assert(!called);
+  });
+});
+
+describe('removeCallbacks()', function() {
+  it('removed callbacks should not be called', function() {
+     let called = false;
+     const fn = function() { called = true };
+     const r = weak({}, fn);
+     weak.removeCallbacks(r);
+     gc();
+     assert(!called);
+  });
+});
+
+describe('isNearDeath()', function() {
+  it('returns false', function() {
+     assert(!weak.isNearDeath('whatever'));
+  });
+});

package/test/create.js

@@ -0,0 +1,42 @@
+'use strict';
+const assert = require('assert');
+const weak = require('../');
+
+describe('create()', function() {
+  afterEach(gc)
+
+  it('should throw on non-"object" values', function() {
+    [
+      0,
+      0.0,
+      true,
+      false,
+      null,
+      undefined,
+      'foo',
+      Symbol(),
+    ].forEach((val) => {
+      assert.throws(function() {
+        weak.create(val);
+      });
+    });
+  });
+
+  it('should accept "object" values', function() {
+    [
+      {},
+      function() {},
+      () => {},
+      [],
+      Buffer(''),
+      new ArrayBuffer(10),
+      new Int32Array(new ArrayBuffer(12)),
+      Promise.resolve(),
+      new WeakMap(),
+    ].forEach((val) => {
+      assert.doesNotThrow(() => {
+        assert.ok(weak.create(val));
+      }, Error, String(val));
+    });
+  });
+});

package/test/exports.js

@@ -0,0 +1,31 @@
+'use strict';
+const assert = require('assert');
+const weak = require('../');
+
+function checkFunction(prop) {
+  it(`should have a function "${prop}"`, function () {
+    assert.strictEqual(typeof weak[prop], 'function');
+  })
+}
+
+describe('exports', function () {
+  afterEach(gc);
+
+  it('should be a function', function() {
+    assert.strictEqual(typeof weak, 'function');
+  });
+
+  checkFunction('get');
+  checkFunction('create');
+  checkFunction('isWeakRef');
+  checkFunction('isNearDeath');
+  checkFunction('isDead');
+  checkFunction('callbacks');
+  checkFunction('addCallback');
+  checkFunction('removeCallback');
+  checkFunction('removeCallbacks');
+
+  it('should be a circular reference to "create"', function () {
+    assert.strictEqual(weak, weak.create);
+  });
+});

package/test/weakref.js

@@ -0,0 +1,151 @@
+'use strict';
+const assert = require('assert');
+const weak = require('../');
+
+describe('Weakref', function() {
+  afterEach(gc);
+
+  it('weak() should return a `Weakref` instance', function() {
+    var ref = weak({});
+    assert(weak.isWeakRef(ref));
+  });
+
+  it('should proxy named gets to the target', function() {
+    const o = { foo: 'bar' };
+    const r = weak(o);
+    assert.strictEqual(r.foo, 'bar');
+  });
+
+  it('should proxy named sets to the target', function() {
+    const o = {};
+    const r = weak(o);
+    r.foo = 'bar';
+    assert.strictEqual(r.foo, 'bar');
+  });
+
+  it('should proxy named deletes to the target', function() {
+    const o = { foo: 'bar' };
+    const r = weak(o);
+    delete r.foo;
+    assert(!r.foo);
+  });
+
+  it('should proxy indexed gets to the target', function() {
+    const a = [ 'foo' ];
+    const r = weak(a)
+    assert.strictEqual(1, a.length);
+    assert.strictEqual(1, r.length);
+    assert.strictEqual('foo', r[0]);
+  });
+
+  it('should proxy indexed sets to the target', function() {
+    const a = [];
+    const r = weak(a);
+    assert.strictEqual(0, a.length);
+    assert.strictEqual(0, r.length);
+    r[0] = 'foo';
+    assert.strictEqual(1, a.length);
+    assert.strictEqual('foo', a[0]);
+    r.push('bar');
+    assert.strictEqual(2, a.length);
+    assert.strictEqual('bar', a[1]);
+  });
+
+  it('should proxy indexed deletes to the target', function() {
+    const a = [ 'foo' ];
+    const r = weak(a);
+    delete r[0];
+    assert.strictEqual('undefined', typeof a[0]);
+  });
+
+  it('should proxy enumeration', function() {
+    const o = { a: 'a', b: 'b', c: 'c', d: 'd' };
+    const r = weak(o);
+    assert.deepEqual(Object.keys(o), Object.keys(r))
+  });
+
+  it('should act like an empty object after target is gc\'d', function() {
+    let o = { foo: 'bar' };
+    const r = weak(o);
+    o = null;
+    assert.strictEqual('bar', r.foo);
+    gc();
+    assert(!r.foo);
+    assert.strictEqual(0, Object.keys(r).length);
+  });
+
+  it('relays prototype set/gets', function() {
+    const p = {};
+    let o = { foo: 'bar' };
+    const r = weak(o);
+    Object.setPrototypeOf(r, p);
+    assert.strictEqual(Object.getPrototypeOf(r), p);
+  });
+
+  it('voids prototype set/gets for gc\'ed objects', function() {
+    const p = {};
+    let o = { foo: 'bar' };
+    const r = weak(o);
+    Object.setPrototypeOf(r, p);
+    assert.strictEqual(Object.getPrototypeOf(r), p);
+    o = null;
+    gc();
+    assert.throws(() => {
+      Object.setPrototypeOf(r, p);
+    });
+    assert.strictEqual(Object.getPrototypeOf(r), null);
+  });
+
+  it('relays extensibility restrictions', function() {
+    const p = {};
+    const o = { foo: 'bar' };
+    const r = weak(o);
+    assert(Object.isExtensible(r));
+    assert(Object.isExtensible(o));
+    Object.preventExtensions(r);
+    assert(!Object.isExtensible(r));
+    assert(!Object.isExtensible(o));
+  });
+
+  it('voids extensibility restrictions for gc\'ed objects', function() {
+    const p = {};
+    let o = { foo: 'bar' };
+    const r = weak(o);
+    assert(Object.isExtensible(r));
+    assert(Object.isExtensible(o));
+    o = null;
+    gc();
+    Object.preventExtensions(r);
+    assert(!Object.isExtensible(r));
+  });
+
+  it('forwards object descriptor definitions', function() {
+    const p = {};
+    let o = { foo: 'bar' };
+    const r = weak(o);
+    assert(Object.defineProperty(r, 'foo', { value: 42 }));
+    assert.strictEqual(r.foo, 42);
+    assert('foo' in r);
+    o = null;
+    gc();
+    assert.strictEqual(r.foo, undefined);
+    r.foo = 9;
+    assert.strictEqual(r.foo, undefined);
+    assert.throws(() => {
+      assert(Object.defineProperty(r, 'foo', { value: 42 }));
+    });
+    assert(!('foo' in r));
+    assert.strictEqual(r.foo, undefined);
+    assert.strictEqual(Object.getOwnPropertyDescriptor(r, 'foo'), undefined);
+  });
+
+  it('forwards property deletions', function() {
+    const p = {};
+    let o = { foo: 'bar' };
+    const r = weak(o);
+    assert.strictEqual(r.foo, 'bar');
+    o = null;
+    gc();
+    assert.strictEqual(delete r.foo, true);
+  });
+});