serialism

Version:

Serialize complex JavaScript objects and ESM classes with circular dependencies, natively.

83 lines (74 loc) • 37.3 kB

HTML

<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>serialism</title><meta name="description" content="Documentation for serialism"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="index.html" class="title">serialism</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>serialism</h1></div><div class="tsd-panel tsd-typography"><h1 id="serialism" class="tsd-anchor-link">serialism<a href="#serialism" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1>Serialize complex JavaScript objects and ES classes with circular dependencies natively. <a href="https://www.npmjs.com/package/serialism"><img src="https://img.shields.io/npm/v/serialism.svg" alt="npm"></a> <a href="https://github.com/voodooattack/serialism/blob/master/LICENSE"><img src="https://img.shields.io/github/license/voodooattack/serialism.svg" alt="GitHub license"></a> <a href="https://github.com/voodooattack/serialism/issues"><img src="https://img.shields.io/github/issues/voodooattack/serialism.svg" alt="GitHub issues"></a> <a href="https://travis-ci.org/voodooattack/serialism"><img src="https://travis-ci.org/voodooattack/serialism.svg?branch=master" alt="Build Status"></a> <a href="https://coveralls.io/github/voodooattack/serialism"><img src="https://coveralls.io/repos/github/voodooattack/serialism/badge.svg" alt="Coverage Status"></a> <img src="https://img.shields.io/npm/types/serialism.svg" alt="npm type definitions"> <h2 id="important-warning" class="tsd-anchor-link">Important Warning<a href="#important-warning" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>The underlying v8 API used by this native addon is still experimental, and binary compatibility may not be guaranteed between data output by the same application running in two different node versions. If you plan to use this over a wire, please bear that in mind. <h2 id="compatibility" class="tsd-anchor-link">Compatibility<a href="#compatibility" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ul> <li>node.js >= v20.19.3 (LTS/Jod)</li> </ul> <h2 id="installation" class="tsd-anchor-link">Installation<a href="#installation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="prerequisites" class="tsd-anchor-link">Prerequisites<a href="#prerequisites" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>Please make sure you have the following installed: <ul> <li>Python</li> <li>Make</li> <li>C++ compiler</li> </ul> Use one of the following commands depending on your platform. <h4 id="linux" class="tsd-anchor-link">Linux<a href="#linux" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>You need <code>g++</code>, <code>make</code> and <code>python</code> installed. <h5 id="ubuntudebian" class="tsd-anchor-link">Ubuntu/Debian<a href="#ubuntudebian" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h5><code>sudo apt-get install -y build-essential python</code> <h5 id="fedora" class="tsd-anchor-link">Fedora<a href="#fedora" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h5><code>dnf install gcc-c++ make</code> <h5 id="rhel-and-centos" class="tsd-anchor-link">RHEL and CentOS<a href="#rhel-and-centos" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h5><code>yum install -y gcc-c++ make</code> <h4 id="windows" class="tsd-anchor-link">Windows<a href="#windows" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><code>npm install -g --production windows-build-tools</code> <h2 id="usage" class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>Use <code>npm install serialism</code> to install the npm package. <h3 id="simple-example" class="tsd-anchor-link">Simple Example<a href="#simple-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript">const buffer = new Serialism().serialize([1,2,3]) const deserialized = new Serialism().deserialize(buffer); console.log(deserialized) // [1, 2, 3] </code><button type="button">Copy</button></pre> <h4 id="so-why-would-i-use-this-over-jsonstringify" class="tsd-anchor-link">So, why would I use this over <code>JSON.stringify</code>?<a href="#so-why-would-i-use-this-over-jsonstringify" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>The biggest difference about serialism-aside from extended type support—is that it preserves an object's graph, i.e if you do this: <pre><code class="js">const array = [1, 2, 3] const buffer = serialism.serialize({arr1: array, arr2: array}) </code><button type="button">Copy</button></pre> If you save the buffer and deserialize it later on, then—unlike <code>JSON</code>—the following holds true: <pre><code class="js">const {arr1, arr2} = serialism.deserialize(buffer) // Check for strict equality console.log(arr1 === arr2); // true </code><button type="button">Copy</button></pre> Another tangential benefit is compactness. Serialism returns a node <code>Buffer</code> object, containing the object graph in a compact binary format. Duplicate objects (i.e objects that exhibit strict equality) are stored using references, so no single value is ever stored twice. The binary format is also useful if you wish to send it to a Worker or over an IPC mechanism while preserving its structure. <h3 id="more-complex-example" class="tsd-anchor-link">More Complex Example<a href="#more-complex-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript">import { assert } from 'chai'; import { Serialism } from 'serialism'; import { Class1 } from './Class1'; const serialism = new Serialism(); // Register a class. serialism.register(Class1); const sharedArray = ['value']; const target = { undef: undefined, nullVal: null, negativeZero: -0, test: 'hello world', array: [1, 2, 3, 'test', Math.PI, new Date()], buffer: new Uint8Array([1, 2, 3]), arrayBuffer: new ArrayBuffer(8), arrayBufferView: new Uint8Array([1, 2, 3]), map: new Map<any, any>([['hi', 3], [Infinity, 'test'], [NaN, null]]), set: new Set<any>([1, 2, 3, +0, null, undefined]), regexp: /hello-world/g, instance: new Class1(), str: new String('string object instance'), num: new Number(100), object: { 'test long key': 'value', emptyString: '', sharedArray, }, sharedArray, myClass: new Class1() }; // create some basic and deeply nested cyclic dependencies target.cyclic = target; target.map.set(target, target.set); target.set.add(target); target.map.set(target.array, target.instance); const data = serialism.serialize(target); const result = serialism.deserialize<typeof target>(result); assert.deepEqual(target, result); // true assert.strictEquals(result.cyclic, result.map.get(result.cyclic)) // true assert.strictEquals(result.cyclic, result.map.get(result.cyclic)) // true assert.strictEquals(result.cyclic, result.map.get(result.array)) // true assert.strictEquals(result.sharedArray, result.object.sharedArray) // true </code><button type="button">Copy</button></pre> <h4 id="javascript" class="tsd-anchor-link">JavaScript<a href="#javascript" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><pre><code class="js">const Serialism = require('serialism').Serialism; const Class1 = require('./Class1'); const serialism = new Serialism().register(Class1); // serialize an object, an array, a regex, a set, a map, a primitive value, anything works except local symbols const data = serialism.serialize([ 1, 2, NaN, new Map(), new Set(), /my-regex-here/g, new Class1() ]); console.log(Buffer.isBuffer(data)); // true; const deserialized = serialism.deserialize(data); // deserialize the data assert.deepEqual(data, deserialized); // true </code><button type="button">Copy</button></pre> <h3 id="error-handling" class="tsd-anchor-link">Error Handling<a href="#error-handling" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul> <li>All classes must be registered to be proccessed. Serialism will throw if you attempt to serialize an unknown class.</li> </ul> <pre><code class="typescript">import {assert} from 'chai'; import {Serialism} from 'serialism'; const serializer = new Serialism(); assert.throws(() => serializer.serialize( new class MyUnregisteredClass {} ), "No registered class found for MyUnregisteredClass" ); </code><button type="button">Copy</button></pre> <ul> <li>Serialism will throw if you attempt to deserialize an unknown class.</li> </ul> <pre><code class="typescript">import {assert} from 'chai'; import {Serialism} from 'serialism'; class RegisteredClass {} serializer.register(RegisteredClass); const result = serializer.serialize(new RegisteredClass()); assert.throws( // A new deserializer instance does not know the class. () => new Serialism().deserialize(result), "No registered class found for: RegisteredClass" ); </code><button type="button">Copy</button></pre> <h5 id="registering-classes" class="tsd-anchor-link">Registering Classes<a href="#registering-classes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h5><ul> <li>You can't register two different classes with the same name.</li> </ul> <pre><code class="typescript">import {assert} from 'chai'; import {Serialism} from 'serialism'; assert.throws(() => { const serializer2 = new Serialism(); serializer2.register(class RegisteredClass {}); serializer2.register(class RegisteredClass {}); }, "A different class with the name 'RegisteredClass' is already registered."); </code><button type="button">Copy</button></pre> <h3 id="contributions" class="tsd-anchor-link">Contributions<a href="#contributions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>All contributions and pull requests are welcome. If you have something to suggest or an idea you'd like to discuss, then please submit an issue or a pull request. Note: Please commit your changes using <code>npm run commit</code> to trigger <code>conventional-changelog</code>. <h3 id="license-mit" class="tsd-anchor-link">License (MIT)<a href="#license-mit" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>Copyright (c) 2018 Abdullah A. Hassan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility">Member Visibility<ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Inherited</label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#serialism">serialism</a><ul><li><a href="#important-warning">Important Warning</a></li><li><a href="#compatibility">Compatibility</a></li><li><a href="#installation">Installation</a></li><li><ul><li><a href="#prerequisites">Prerequisites</a></li><li><ul><li><a href="#linux">Linux</a></li><li><ul><li><a href="#ubuntudebian">Ubuntu/Debian</a></li><li><a href="#fedora">Fedora</a></li><li><a href="#rhel-and-centos">RHEL and CentOS</a></li></ul></li><li><a href="#windows">Windows</a></li></ul></li></ul></li><li><a href="#usage">Usage</a></li><li><ul><li><a href="#simple-example">Simple Example</a></li><li><ul><li><a href="#so-why-would-i-use-this-over-jsonstringify">So, why would I use this over JSON.stringify?</a></li></ul></li><li><a href="#more-complex-example">More Complex Example</a></li><li><ul><li><a href="#javascript">JavaScript</a></li></ul></li><li><a href="#error-handling">Error Handling</a></li><li><ul><li><ul><li><a href="#registering-classes">Registering Classes</a></li></ul></li></ul></li><li><a href="#contributions">Contributions</a></li><li><a href="#license-mit">License (MIT)</a></li></ul></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">serialism</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></footer><div class="overlay"></div></body></html>