ALS

Class: Serializable

.ALS. Serializable

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:

  1. 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.
  2. 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:

  1. Assign serialized.constructorArguments to the array.
  2. For each custom object argument: create skipDeserialization property and set it to true.
  3. Put your custom arguments to serialized.constructorArguments in such order that constructor requires.
  4. 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() or deserialize(). Should not be called in the middle of serialization or deserialization, for example, at serialize().

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 to seenObjects.

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