new Serializable()
Introduction
Provides serialization capabilities, used to serialize different kinds of objects to JSON and deserialize them back.
Deals with cyclic references.
Serializes following types: Array, RegExp, BigInt, Symbol. Serializes custom properties in all of those types.
Tries to deal with any types of objects, but you may want to provide your own serialization and deserialization mechanisms. To do so, override serialize() and static deserialize() methods.
Caveats:
- Objects' ownership (where object has been created) changes after deserialization. The way it changes depends on how user's browser handles
for ... in
loop. The first place object will appear at would be the owner of that object after deserialization. - If user's browser doesn't support BigInt or Symbol, those types will be deserialized as number and string respectively.
How to implement custom mechanisms
You'll have to override L.ALS.Serializable#serialize
and L.ALS.Serializable.deserialize
methods.
L.ALS.Serializable#serialize
should return an object that can be serialized by JSON.stringify()
. You may want to create plain objects containing your data or use static L.ALS.Serializable.serializeAnyObject
method to serialize complex objects. Though it won't work with custom classes, it may be still useful.
Static L.ALS.Serializable.deserialize
method accepts your serialized object as an argument and must return a deserialized instance of your class. You can use static L.ALS.Serializable.getObjectFromSerialized
method to do so and perform your deserialization on returned object. You may also find default deserialization mechanism useful for deserializing complex objects such as described above.
There are also plenty of helpers methods to accomplish your goal. L.ALS.Layer
has additional methods to help you.
Hints
Every L.ALS.Serializable
instance has public L.ALS.Serializable#serializationIgnoreList
property which contains properties' names to ignore while serializing. You may want to use it if you want to stick to default serialization mechanisms. Just append your properties' and methods' names to serializationIgnoreList
.
Both L.ALS.Serializable#serialize
and L.ALS.Serializable.deserialize
methods accepts two additional arguments: seenObjects
and seenObjectsForCleanUp
. Those are used internally by serialization mechanism. If you're making layer, just don't pass anything to the default mechanism. If your class serializes some other L.ALS.Serializable
that uses default mechanism, please, pass those parameters to its serialize()
and deserialize()
methods.
You can prevent constructor arguments from being serialized or deserialized by creating custom skipSerialization
and skipDeserialization
properties respectively and setting them to true
. If you choose to prevent serialization, you'll need to set skipped arguments at deserialization yourself. For this, see the next tip.
You can put custom objects as arguments to the constructor while deserializing using default mechanisms. To do so:
- Assign
serialized.constructorArguments
to the array. - For each custom object argument: create
skipDeserialization
property and set it totrue
. - Put your custom arguments to
serialized.constructorArguments
in such order that constructor requires. - Pass your
serialized
object to the default mechanism:L.ALS.Serializable.deserialize(serialized);
Extends
- L.Class
Members
-
<protected> constructorArguments :Array.<any>
-
Contains arguments passed to this constructor
Type:
- Array.<any>
-
<protected> serializationIgnoreList :Array.<string>
-
Contains properties that won't be serialized. Append your properties at the constructor.
Type:
- Array.<string>
Methods
-
<static> cleanUp(seenObjects)
-
Cleans up seen objects. Must be called after first call of
serialize()
,serializeAnyObjects()
ordeserialize()
. Should not be called in the middle of serialization or deserialization, for example, atserialize()
.Parameters:
Name Type Description seenObjects
Object seenObjects
argument that you've passed to serialization and deserialization methods -
<static> deserialize(serialized, seenObjects)
-
Generic deserialization method, can be used to deserialize any object or primitive anywhere by calling
L.ALS.Serializable.deserialize
.Parameters:
Name Type Description serialized
Object Serialized object or primitive
seenObjects
Object Already seen objects' ids. Intended only for internal use.
Returns:
Deserialized object or primitive
-
<static> deserializePrimitive(primitive)
-
Deserializes primitives including types unsupported by JSON
Parameters:
Name Type Description primitive
Primitive to deserialize
Returns:
Deserialized primitive
- Type
- bigint | number | *
-
<static> findGetter(property, object)
-
Finds getter name for given property in a given object
Parameters:
Name Type Description property
string Property name
object
Object Object to find getter in
Returns:
Either getter name or undefined if nothing has been found
- Type
- string | undefined
-
<static> findSetter(property, object)
-
Finds setter name for given property in a given object
Parameters:
Name Type Description property
string Property name
object
Object Object to find setter in
Returns:
Either setter name or undefined if nothing has been found
- Type
- string | undefined
-
<static> getObjectFromSerialized(serialized, seenObjects)
-
Constructs new instance of Serializable and passes serialized arguments to the constructor. Assigns
serializationID
to the object and adds it toseenObjects
.Parameters:
Name Type Description serialized
Object Serialized Serializable object
seenObjects
Already seen objects' ids. Intended only for internal use.
Returns:
Instance of given object or
serialized
argument if constructor hasn't been found- Type
- L.ALS.Serializable | Object
-
<static> getSerializableConstructor(className)
-
Finds a constructor by given class name
Parameters:
Name Type Description className
string Full class name. Just pass serialized.serializableClassName.
Returns:
Found constructor or undefined
- Type
- function | undefined
-
<static> serializeAnyObject(object, seenObjects)
-
Generic serialization mechanism. Tries to serialize everything possible
Parameters:
Name Type Description object
Any object or primitive to serialize
seenObjects
Object Already seen objects' ids. Intended only for internal use.
Returns:
Serialized object or primitive
- Type
- Object
-
<static> serializePrimitive(primitive)
-
Serializes primitives including types unsupported by JSON
Parameters:
Name Type Description primitive
Primitive to serialize
Returns:
Serialized primitive
-
<static> shouldIgnoreProperty(property, object, isGetter, checkOnlyIgnoreList)
-
Checks if property should be ignored when serializing or deserializing.
If you're deserializing, call it for both serialized object and new instance like this:
if (this.shouldIgnoreProperty(property, serialized) || this.shouldIgnoreProperty(property, newObject, false, true)) // Ignore this property
Parameters:
Name Type Description property
string Name of the property
object
L.ALS.Serializable | Object Object containing ignore lists
isGetter
boolean Indicates whether given property is getter or not
checkOnlyIgnoreList
boolean If true, will only check if property is in the ignore lists
Returns:
True, if property is in ignore lists. False otherwise.
- Type
- boolean
-
getObjectToSerializeTo(newObject, seenObjects)
-
Registers this object for serialization and deserialization. Returns an object to serialize custom properties to.
Call it first, if you implement your own algrorithm, and serialize to the returned object!
Parameters:
Name Type Description newObject
Object Object to where you'll serialize
seenObjects
Object Already seen objects
Returns:
Object to serialize to.
- Type
- Object
-
serialize(seenObjects)
-
Serializes this object to JSON. If overridden, you MUST perform following operations before returning JSON:
let json = {} // Your JSON ... // Perform serialization json.constructorArguments = this.serializeConstrutorArguments(); // Serialize constructor arguments json.serializableClassName = this.serializableClassName; // Add class name to JSON return json; // Finally return JSON
Parameters:
Name Type Description seenObjects
Object Already seen objects
Returns:
This serialized object
- Type
- Object
-
serializeConstructorArguments()
-
Serializes constructor arguments. If your constructor is not empty, result of this method MUST be added to json at
L.ALS.Serializable#serialize
as "_construtorArgs" property.Deprecated in favor of
L.ALS.Serializable#getObjectFromSerialized
which uses this function under-the-hood.- Deprecated:
-
- Yes
Returns:
Serialized constructor arguments
- Type
- Array
-
setConstructorArguments(args)
-
Sets constructor arguments for serialization
Parameters:
Name Type Description args
Arguments to set