iKeyed
Enhances JavaScript constructors to automatically provide unique keys for all generated instances and automatically provides JSON restore capability based on the key.
Compatibility
Compatible with Chrome, Firefox, and Node.js. Due to lack of built-in standards support IE, Edge, and Safari are not currently supported. Compatibility tests sponsored by https://www.browserstack.com/automate.
Usage
npm install iKeyed
Properties
.scope - A lookup object using constructor names as properties and constructors as values, i.e. {constructorName1: constructor1,...}.
Enhancing Classes: iKeyed(constructor,keyProperty="@key")
Constructors for classes enhanced with iKeyed will produce instances that have a unique key of the form:
@<uuid 4>, e.g. TestClass@049093f0-7111-4a9e-af3c-ae58116ec25f
Enhancing a class will add a constructor to iKeyed.scope. It will also add a virtual property, .instances, to the Proxy for the constructor. This is a lookup object using object unique keys as properties and instances of the iKey enhanced class as values, i.e. {: ,...}.
Syntax
constructor = iKeyed(constructor);
var instance = new constructor();
or
var myvar = iKeyed(constructor);
var instance = new myvar();
In the above examples, the instance will be added to constructor.instances or myvar.instances respectively.
Parameters
constructor - A named class constructor. Anonymous constructors are not supported.
keyProperty - The property to add to all instances.
Return Value
Returns a Proxy.
Restoring Instances .fromJSON(object,scope[,keyProperty])
iKeyed enhanced classes can restore plain Objects to instances of the appropriate class. If there is no key in the object at the root level, then it is assumed an instance of the restoring class is needed and a key will be generated. For nested classes, objects lacking keys remain direct instances of Object. If there is a key in the root object or nested object, then the key will be analyzed and if the appropriate class constructor is in scope that constructor will be called. This allows nested objects to be restored with a single call. If no constructor is available, a direct instance of Object will be restored.
Note: To be restorable an object MUST support a zero argument constructor or its own restore method. This is because the ECMA spec provides no means to intercept Object.create and iKeyed must use a constructor internally in case the class being restored has also been proxied. As far as we know, there is no way to intercept Object.create on an function rather than the function's prototype.
scope is of the form: {<constructor name>:<constructor>,...}
keyProperty is optional and defualts to the value provided when iKeyed(<constructor>,<keyProperty>) was called.
Restoring a class will add it to .instances.
Syntax
Person = iKeyed(Person);
Pet = iKeyed(Pet);
var person = iKeyed(constructor).restore({name: "joe",pet:{"@key":"Pet@@049093f0-7111-4a9e-af3c-ae58116ec25f"}});
Parameters
object - An object to restore.
scope - An optional scope object of the form {constructorName1: constructor1,...}
Return Value
Returns an object than is an instance of the restorer, unless the object to restore was keyed as a different class, in which case an instance of that class if the constructor was in scope, otherwise a plain Object.
Release History
2016-07-29 v0.0.7 - Reworked object creation for classes that do not have their own toJSON method. Existing code created two objects in some situations.
2016-07-21 v0.0.6 - Renamed restore to fromJSON.
2016-07-21 v0.0.5 - Made so keyProperty argument to constructor can be a function.
2016-07-08 v0.0.4 - Updated dependencies.
2016-07-08 v0.0.3 - More documentation.
2016-07-07 v0.0.2 - Added documentation, build automation and quality controls.
2016-06-23 v0.0.1 - Initial public release.