@simpo/private

Private

ES6 classes provide no native way to implement private methods and classes. This module provides a simple mechanism for achieving this.

Install

npm install --save

with yarn:

yarn add

with pnpm :

pnpm install --save

Example

const Private = require('@simpo/private');
const $private = new Private();


class My_Class() {
	doSomething() {
		// Get private value linked to this class instance.
		const value = $private.get(this, 'value'); 
		// ... do something with value
	}
}

API

Private exports an extension to the native WeakMap class (this ensures data is garbage-collected after class instance goes out of scope).

Static properties

NB: Changing these static properties will change the default on future created Private instances, so you might change behaviour in someone else's modules - beware! Better to change the instance version of this property.

Constructor

The default Map object used to store values against a given object / class instance. Normally, this would not be changed but you might wish to supply a special extended Map or other class. The class should expose the methods normally expected on a Map() object.

constructorParams

The default parameters to use when creating a new Map object for your private values. This defaults to an empty an array and should remain as-such unless you have a special reason for changing it.

Static methods

getInstance()

Get a new instance of Private, the same as new Private(). This is just a convenience method so you can:

const $private = require('@simpo/private').getInstance();

This is neater than and easier to understand than:

const $private = new (require('@simpo/private'))();

Instance properties

Constructor

Map constructor used to create your internal values map. Defaults to the static Constructor property of Private and is normally just Map.

constructorParams

The default parameters to use when creating a new Map object for your private values. This defaults to an empty an array and should remain as-such unless you have a special reason for changing it.

Instance methods

clear()

Clear all private values set against a given reference object or class instance.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on. Will throw if not supplied.
returns	undefined	-

delete()

Delete a private value set against a given class instance.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on.
key	String | Number | String[] | Number[]	undefined	The value you wish to delete. If a key is not supplied the entire Map relating to reference is deleted.
returns	Boolean | *	-	The return value of delete() method on your private map. Will normally be a boolean, true when the value existed and was deleted and false if it did not exist.

entries()

Return an iterator for all the entries set against a given reference.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on. Will throw if not supplied.
returns	iterator | *	-	The return value of entries() method on your private map. Will normally a new Map iterator object.

get()

Get a private value set against a given class instance.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on.
key	String | Number | String[] | Number[]	undefined	The value you wish to get. If a key is not supplied the entire Map relating to reference is returned. If an array is given, get all the keys in the array and return an array.
default	*	undefined	The default value to return if value to set. Will set the value to this default if not found. Method will internally do an arguments count to see if this parameter is set, hence setting this value to undefined, explicitly sets the value to undefined (where-as not supplying a default does not). If an array key was given, an array is expected here if it is supplied.
returns	*	undefined	The value set for given key against given reference.

NB: You can also get private static values by supplying the constructor as the reference object. Eg.

$private.get(My_Class, 'value');

Memory Leaks Warning: Be careful when not supplying a key as this will return the Map object containing all private values. If you hold onto this object it cannot be garbage collected when your class instance or object go out of scope.

has()

Test for the existence of a given value set against the reference object.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on.
key	string	undefined	The key you wish to test, if not set then then test for just the reference object.
returns	Boolean	false	The a value set for given key against given reference.

invoke()

Invoke a given private method, binding to the supplied reference object.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on.
methodName	string	undefined	The method, you wish to invoke.
...params	*	undefined	The parameters to use.
returns	Boolean	false	The result of invoking the given method with supplied parameters.

Example:

return $private(this, 'somePrivateMethod', value1, value2);

keys()

Return an iterator for all the keys set against a given reference.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on. Will throw if not supplied.
returns	iterator | *	-	The return value of keys() method on your private map. Will normally a new Map iterator object.

Example:

[...$private.keys(this)].forEach(key=>{
	// Do something
});

link()

Link two objects together so they share all their private values. This cannot be reversed.

Parameter	Type	Default	Description
reference1	Object	-	The first object to link to.
reference2	Object	-	The second object to link to.

NB: Will internally use the entries() method of your Map object to combine these.

set()

Set a private value against a given reference.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on.
key	string	undefined	The key you wish to set. Will throw if not given.
value	string	undefined	The value to set it to.
returns	Map | *	Map	The return value of set() method on your private map. Will normally be the Map object if that is what you are using.

toObject()

Get an object containing all the key/values. This is useful ass you can use destructing to get values, eg:

const {value1, value2} = $private.toObject(this);

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on.
returns	Object	-	An object containing your key/value pairs.

NB: Will internally use the Keys() method of your Map object.

values()

Return an iterator for all the values set against a given reference.

Parameter	Type	Default	Description
reference	Object	-	Should be your class instance. This could be any JavaScript object that you wish to set private data on. Will throw if not supplied.
returns	iterator | *	-	The return value of values() method on your private map. Will normally a new Map iterator object.