weak-set-5 v1.0.1

weak-set-5

Introduction

WeakSet5 is an ES6 WeakSet-alike library that doesn't expose entries and supports WeakSet5.prototype.clear. It also provides non-ES6 spec methods which make manipulating weak set become easier, such as adding and deleting multiple objects all-at-once.

Browser Compatibility

Installation

NPM:

npm install weak-set-5

<script> tag:

<!-- Uncompressed version, emit error on invalid action -->
<script src="https://unpkg.com/weak-set-5/dist/weak-set-5.js"></script>

<!-- Compressed version, silently failed on invalid action -->
<script src="https://unpkg.com/weak-set-5/dist/weak-set-5.min.js"></script>

Note that WeakSet5 sees itself as a library, not a polyfill. You need to access WeakSet5 identifier explicitly to use WeakSet5.

new WeakSet5;

Highlight

Weak sets hold the entries

In other weak set libraries, objects are carrying weak set registry. To verify if an object is registered on the weak set, the weak set just needs to check if its ID exists in the object's weak set registry.

In WeakSet5, it reverts. Weak sets hold the entries, while the objects hold the ID. To ease of garbage collection, weak set entries are just carrying the object's ID.

Each time a fresh new object is assigned into a weak set, it will be assigned an ID. The ID will be reused in every weak set. To verify if an object is registered to a weak set, the weak set just needs to retrieve the object's ID, and check if the ID exists in its entries.

Note that the object's ID need to be assigned as a property onto the object. Therefore, non-extensible cannot be registered to WeakSet5.

Entries and ID are private

It is dangerous to expose weak set entries and object IDs to external environment, since they will be easily manipulated and glitches may happen.

Therefore, weak set entries and object IDs are private to internal. When retrieving weak set entries and object ID, they are actually passed to an internal site. WeakSet5 methods will then retrieve them from the internal site.

Add and delete multiple objects on the fly

In ES6 WeakSet spec, there is no methods provided to add and delete multiple objects all-at-once after the weak set is constructed. It will be a pain when you need to add and delete multiple objects from the weak set in some cases.

In WeakSet5, WeakSet5.prototype.addMultiple and WeakSet5.prototype.deleteMultiple is introduced. You can now add and delete multiple objects with just one method.

WeakSet5.prototype.clear

Since weak set itself holds the entries, it is possible to implement WeakSet5.prototype.clear again. This will clear all the object ID in the entries. All registered objects will be unrecognised unless they are re-registered.

API

WeakSet5 follows ES6 WeakSet behaviour. Therefore, it is easily to use WeakSet5 if you are familiar with ES6 WeakSet.

Note that in WeakSet5, the recognised iterable object are array, array-like object, Iterator object, and object that provides next() method. WeakSet5 doesn't invoke [Symbol.iterator], you need to invoke it manually:

new WeakSet5( obj[Symbol.iterator]() );

Also, WeakSet5 provides non-ES6 methods, which are listed below.

WeakSet5.prototype.addMultiple( itrObj )

Description

Add multiple objects into the weak set.

Arguments

• itrObj <Array> | <ArrayLike> | <Iterator>

An array, array-like object, Iterator object, or iterator-like object that contains objects to be added.

Return value

<WeakSet5> The weak set object.

WeakSet5.prototype.deleteMultiple( itrObj )

Description

Delete multiple objects from the weak set.

Arguments

• itrObj <Array> | <ArrayLike> | <Iterator>

  An array, array-like object, Iterator object, or iterator-like object that contains object to be deleted.

Return value

<Boolean> true if at least one of the objects has been removed from the weak set, false if none of the objects has been removed from the weak set.

WeakSet5.prototype.clear()

Description

Clear the entries of the weak set. All previously registered objects need to be re-registered again.

Arguments

None.

Return value

undefined

License

MIT License