## SipaSerializer Serializer to serialize data of primitive types or even complex Objects, to ensure to be stored as valid JSON and can be deserialized back without data loss. Includes support for - Boolean, Number, String, Array, Object, null (native JS[SON] support) And includes special type handling to support the following types: - Functions - RegExp, Date - NaN, Infinity, -Infinity, undefined - empty (special type when deleting an item of an array) The special types are escaped by an internal escaping when serialized. See SipaSerializer.STORAGE_PLACEHOLDERS for the escapes. * [SipaSerializer](#SipaSerializer) * [.STORAGE_PLACEHOLDERS](#SipaSerializer.STORAGE_PLACEHOLDERS) : Object * [.serialize(value)](#SipaSerializer.serialize) → string \| null * [.deserialize(value)](#SipaSerializer.deserialize) → Boolean \| String \| Number \| Array \| Object \| RegExp \| Date \| undefined \| NaN \| Infinity \| null \| \* * [.isFunctionString(value)](#SipaSerializer.isFunctionString) → boolean * [.isArrayString(value)](#SipaSerializer.isArrayString) → boolean * [.isObjectString(value)](#SipaSerializer.isObjectString) → boolean * [.deserializeFunctionString(value)](#SipaSerializer.deserializeFunctionString) → function * [.deepSerializeSpecialTypes(obj)](#SipaSerializer.deepSerializeSpecialTypes) → Array \| Object * [.deepDeserializeSpecialTypes(obj)](#SipaSerializer.deepDeserializeSpecialTypes) → Array \| Object ### SipaSerializer.STORAGE\_PLACEHOLDERS : Object Placeholders for special types when serialized. These placeholders are used to identify and restore the special types during deserialization. ### SipaSerializer.serialize(value) → string \| null Serialize given value to be stored in JSON without loosing its original value. **Returns**: string \| null - returns string or null if value is null | Param | Type | | --- | --- | | value | any | **Example** ```js const my_example_object = { name: "My Object", created: new Date(), pattern: /abc/i, doSomething: function(a, b) { return a + b; }, nothing: null, not_defined: undefined, not_a_number: NaN, infinite: Infinity, items: [1, 2, 3, 4] }; delete my_example_object.items[2]; // create an empty entry in the array console.log(my_example_object.items); // [1, 2, empty, 4] const serialized = SipaSerializer.serialize(my_example_object); console.log(serialized); // Example output (formatted for readability): /*{ "name": "My Object", "created": "::Date::2023-10-05T12:34:56.789Z", "pattern": "::RegExp::/abc/i", "doSomething": "function(a, b) { return a + b; }", "nothing": null, "not_defined": "::undefined::", "not_a_number": "::NaN::", "infinite": "::Infinity::", "items": [1, 2, "::empty::", 4] }* / // serialized is now a valid JSON string that can be stored without data loss const deserialized = SipaSerializer.deserialize(serialized); // deserialized is now a clone of my_example_object with all original values and types console.log(deserialized.name); // "My Object" console.log(deserialized.created instanceof Date); // true console.log(deserialized.pattern instanceof RegExp); // true console.log(typeof deserialized.doSomething === 'function'); // true console.log(deserialized.nothing === null); // true console.log(typeof deserialized.not_defined === 'undefined'); // true console.log(typeof deserialized.not_a_number === 'number' && isNaN(deserialized.not_a_number)); // true console.log(deserialized.infinite === Infinity); // true console.log(Array.isArray(deserialized.items) && deserialized.items.length === 4 && !(2 in deserialized.items)); // true, note the empty entry at index 2 ``` ### SipaSerializer.deserialize(value) → Boolean \| String \| Number \| Array \| Object \| RegExp \| Date \| undefined \| NaN \| Infinity \| null \| \* Serialize given value to be stored in JSON without loosing its original value. | Param | Type | | --- | --- | | value | String \| null | **Example** ```js const serialized = `{ "name": "My Object", "created": "::Date::2023-10-05T12:34:56.789Z", "pattern": "::RegExp::/abc/i", "doSomething": "function(a, b) { return a + b; }", "nothing": null, "not_defined": "::undefined::", "not_a_number": "::NaN::", "infinite": "::Infinity::", "items": [1, 2, "::empty::", 4] }`; const deserialized = SipaSerializer.deserialize(serialized); // deserialized is now a clone of my_example_object with all original values and types console.log(deserialized); // show the full object { name: "My Object", created: Date, // actual Date object pattern: RegExp, // actual RegExp object doSomething: function(a, b) { return a + b; }, // nothing: null, not_defined: undefined, not_a_number: NaN, infinite: Infinity, items: [1, 2, empty, 4] } ``` ### SipaSerializer.isFunctionString(value) → boolean Check if given string is a valid javascript function. Note: This method does not check if the function makes sense, only if the syntax is valid. | Param | Type | | --- | --- | | value | String | **Example** ```js SipaSerializer.isFunctionString("function(a, b) { return a + b; }"); // true SipaSerializer.isFunctionString("(a, b) => { return a + b; }"); // true SipaSerializer.isFunctionString("a => a * 2"); // true SipaSerializer.isFunctionString("function myFunc(a, b) { return a + b; }"); // true SipaSerializer.isFunctionString("myFunc(a, b) { return a + b; }"); // true, function name without prefix 'function' ``` ### SipaSerializer.isArrayString(value) → boolean Check if given string is a valid javascript array. | Param | Type | | --- | --- | | value | String | **Example** ```js SipaSerializer.isArrayString("[1, 2, 3]"); // true SipaSerializer.isArrayString("['a', 'b', 'c']"); // true SipaSerializer.isArrayString("[true, false, null]"); // true SipaSerializer.isArrayString("[1, [2, 3], {a: 4}]"); // true SipaSerializer.isArrayString("{a: 1, b: 2}"); // false SipaSerializer.isArrayString("function() {}"); // false SipaSerializer.isArrayString("not an array"); // false ``` ### SipaSerializer.isObjectString(value) → boolean Check if given string is a valid javascript object. | Param | Type | | --- | --- | | value | String | **Example** ```js SipaSerializer.isObjectString("{a: 1, b: 2}"); // true SipaSerializer.isObjectString("{'a': 1, 'b': 2}"); // true SipaSerializer.isObjectString('{"a": 1, "b": 2}'); // true SipaSerializer.isObjectString("{a: 1, b: {c: 3}}"); // true SipaSerializer.isObjectString("[1, 2, 3]"); // false SipaSerializer.isObjectString("function() {}"); // false SipaSerializer.isObjectString("not an object"); // false ``` ### SipaSerializer.deserializeFunctionString(value) → function Deserialize a valid javascript string into a callable function. | Param | Type | | --- | --- | | value | String | **Example** ```js const fn1 = SipaSerializer.deserializeFunctionString("function(a, b) { return a + b; }"); console.log(fn1(2, 3)); // 5 ``` ### SipaSerializer.deepSerializeSpecialTypes(obj) → Array \| Object Serializes (escapes) all special types within an Array or Object to be stored in JSON without data loss. Original Array or Object is cloned and will not be manipulated. | Param | Type | | --- | --- | | obj | Array \| Object | **Example** ```js const my_example_object = { name: "My Object", created: new Date(), pattern: /abc/i, doSomething: function(a, b) { return a + b; }, nothing: null, not_defined: undefined, not_a_number: NaN, infinite: Infinity, items: [1, 2, 3, 4] }; delete my_example_object.items[2]; // create an empty entry in the array console.log(my_example_object.items); // [1, 2, empty, 4] const escaped = SipaSerializer.deepSerializeSpecialTypes(my_example_object); console.log(escaped); { name: "My Object", created: "::Date::2023-10-05T12:34:56.789Z", pattern: "::RegExp::/abc/i", doSomething: "function(a, b) { return a + b; }", nothing: null, not_defined: "::undefined::", not_a_number: "::NaN::", infinite: "::Infinity::", items: [1, 2, "::empty::", 4] } ``` ### SipaSerializer.deepDeserializeSpecialTypes(obj) → Array \| Object Deserializes (unescapes) all special types of the given Array or Object. Original Array or Object is cloned and will not be manipulated. | Param | Type | | --- | --- | | obj | Array \| Object | **Example** ```js const escaped = { name: "My Object", created: "::Date::2023-10-05T12:34:56.789Z", pattern: "::RegExp::/abc/i", doSomething: "function(a, b) { return a + b; }", nothing: null, not_defined: "::undefined::", not_a_number: "::NaN::", infinite: "::Infinity::", items: [1, 2, "::empty::", 4] }; const deserialized = SipaSerializer.deepDeserializeSpecialTypes(escaped); console.log(deserialized); { name: "My Object", created: Date, // actual Date object pattern: RegExp, // actual RegExp object doSomething: function(a, b) { return a + b; }, // actual function nothing: null, not_defined: undefined, not_a_number: NaN, infinite: Infinity, items: [1, 2, empty, 4] // note the empty entry at index 2 } ```