<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>README</title>
<style>
html {
line-height: 1.5;
font-family: Georgia, serif;
font-size: 20px;
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
overflow-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 1em;
}
h1 {
font-size: 1.8em;
}
}
@media print {
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
font-size: 85%;
margin: 0;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
overflow-wrap: normal;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC ul {
padding-left: 1.3em;
}
#TOC > ul {
padding-left: 0;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
</head>
<body>
<h1 id="serialize-javascript">Serialize JavaScript</h1>
<p>Serialize JavaScript to a <em>superset</em> of JSON that includes
regular expressions, dates and functions.</p>
<h2 id="overview">Overview</h2>
<p>The code in this package began its life as an internal module to <a
href="https://github.com/yahoo/express-state">express-state</a>. To
expand its usefulness, it now lives as <code>serialize-javascript</code>
— an independent package on npm.</p>
<p>You're probably wondering: <strong>What about
<code>JSON.stringify()</code>!?</strong> We've found that sometimes we
need to serialize JavaScript <strong>functions</strong>,
<strong>regexps</strong>, <strong>dates</strong>, <strong>sets</strong>
or <strong>maps</strong>. A great example is a web app that uses
client-side URL routing where the route definitions are regexps that
need to be shared from the server to the client. But this module is also
great for communicating between node processes.</p>
<p>The string returned from this package's single export function is
literal JavaScript which can be saved to a <code>.js</code> file, or be
embedded into an HTML document by making the content of a
<code><script></code> element.</p>
<blockquote>
<p><strong>HTML characters and JavaScript line terminators are escaped
automatically.</strong></p>
</blockquote>
<p>Please note that serialization for ES6 Sets & Maps requires
support for <code>Array.from</code> (not available in IE or Node <
0.12), or an <code>Array.from</code> polyfill.</p>
<h2 id="installation">Installation</h2>
<p>Install using npm:</p>
<pre class="shell"><code>$ npm install serialize-javascript</code></pre>
<h2 id="usage">Usage</h2>
<div class="sourceCode" id="cb2"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> serialize <span class="op">=</span> <span class="pp">require</span>(<span class="st">'serialize-javascript'</span>)<span class="op">;</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="fu">serialize</span>({</span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">str</span> <span class="op">:</span> <span class="st">'string'</span><span class="op">,</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">num</span> <span class="op">:</span> <span class="dv">0</span><span class="op">,</span></span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">obj</span> <span class="op">:</span> {<span class="dt">foo</span><span class="op">:</span> <span class="st">'foo'</span>}<span class="op">,</span></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">arr</span> <span class="op">:</span> [<span class="dv">1</span><span class="op">,</span> <span class="dv">2</span><span class="op">,</span> <span class="dv">3</span>]<span class="op">,</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">bool</span> <span class="op">:</span> <span class="kw">true</span><span class="op">,</span></span>
<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">nil</span> <span class="op">:</span> <span class="kw">null</span><span class="op">,</span></span>
<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">undef</span><span class="op">:</span> <span class="kw">undefined</span><span class="op">,</span></span>
<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">inf</span> <span class="op">:</span> <span class="kw">Infinity</span><span class="op">,</span></span>
<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">date</span> <span class="op">:</span> <span class="kw">new</span> <span class="bu">Date</span>(<span class="st">"Thu, 28 Apr 2016 22:02:17 GMT"</span>)<span class="op">,</span></span>
<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">map</span> <span class="op">:</span> <span class="kw">new</span> <span class="bu">Map</span>([[<span class="st">'hello'</span><span class="op">,</span> <span class="st">'world'</span>]])<span class="op">,</span></span>
<span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">set</span> <span class="op">:</span> <span class="kw">new</span> <span class="bu">Set</span>([<span class="dv">123</span><span class="op">,</span> <span class="dv">456</span>])<span class="op">,</span></span>
<span id="cb2-15"><a href="#cb2-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">fn</span> <span class="op">:</span> <span class="kw">function</span> <span class="fu">echo</span>(arg) { <span class="cf">return</span> arg<span class="op">;</span> }<span class="op">,</span></span>
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">re</span> <span class="op">:</span> <span class="ss">/</span><span class="sc">([^\s]+)</span><span class="ss">/g</span><span class="op">,</span></span>
<span id="cb2-17"><a href="#cb2-17" aria-hidden="true" tabindex="-1"></a> <span class="dt">big</span> <span class="op">:</span> <span class="bu">BigInt</span>(<span class="dv">10</span>)<span class="op">,</span></span>
<span id="cb2-18"><a href="#cb2-18" aria-hidden="true" tabindex="-1"></a>})<span class="op">;</span></span></code></pre></div>
<p>The above will produce the following string output:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="st">'{"str":"string","num":0,"obj":{"foo":"foo"},"arr":[1,2,3],"bool":true,"nil":null,"undef":undefined,"inf":Infinity,"date":new Date("2016-04-28T22:02:17.000Z"),"map":new Map([["hello","world"]]),"set":new Set([123,456]),"fn":function echo(arg) { return arg; },"re":new RegExp("([^</span><span class="sc">\\\\</span><span class="st">s]+)", "g"),"big":BigInt("10")}'</span></span></code></pre></div>
<p>Note: to produced a beautified string, you can pass an optional
second argument to <code>serialize()</code> to define the number of
spaces to be used for the indentation.</p>
<h3 id="automatic-escaping-of-html-characters">Automatic Escaping of
HTML Characters</h3>
<p>A primary feature of this package is to serialize code to a string of
literal JavaScript which can be embedded in an HTML document by adding
it as the contents of the <code><script></code> element. In order
to make this safe, HTML characters and JavaScript line terminators are
escaped automatically.</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="fu">serialize</span>({</span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">haxorXSS</span><span class="op">:</span> <span class="st">'</script>'</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a>})<span class="op">;</span></span></code></pre></div>
<p>The above will produce the following string, HTML-escaped output
which is safe to put into an HTML document as it will not cause the
inline script element to terminate:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="st">'{"haxorXSS":"</span><span class="sc">\\</span><span class="st">u003C</span><span class="sc">\\</span><span class="st">u002Fscript</span><span class="sc">\\</span><span class="st">u003E"}'</span></span></code></pre></div>
<blockquote>
<p>You can pass an optional <code>unsafe</code> argument to
<code>serialize()</code> for straight serialization.</p>
</blockquote>
<h3 id="options">Options</h3>
<p>The <code>serialize()</code> function accepts an <code>options</code>
object as its second argument. All options are being defaulted to
<code>undefined</code>:</p>
<h4 id="optionsspace"><code>options.space</code></h4>
<p>This option is the same as the <code>space</code> argument that can
be passed to <a
href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify"><code>JSON.stringify</code></a>.
It can be used to add whitespace and indentation to the serialized
output to make it more readable.</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="fu">serialize</span>(obj<span class="op">,</span> {<span class="dt">space</span><span class="op">:</span> <span class="dv">2</span>})<span class="op">;</span></span></code></pre></div>
<h4 id="optionsisjson"><code>options.isJSON</code></h4>
<p>This option is a signal to <code>serialize()</code> that the object
being serialized does not contain any function or regexps values. This
enables a hot-path that allows serialization to be over 3x faster. If
you're serializing a lot of data, and know its pure JSON, then you can
enable this option for a speed-up.</p>
<p><strong>Note:</strong> That when using this option, the output will
still be escaped to protect against XSS.</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="fu">serialize</span>(obj<span class="op">,</span> {<span class="dt">isJSON</span><span class="op">:</span> <span class="kw">true</span>})<span class="op">;</span></span></code></pre></div>
<h4 id="optionsunsafe"><code>options.unsafe</code></h4>
<p>This option is to signal <code>serialize()</code> that we want to do
a straight conversion, without the XSS protection. This options needs to
be explicitly set to <code>true</code>. HTML characters and JavaScript
line terminators will not be escaped. You will have to roll your
own.</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">serialize</span>(obj<span class="op">,</span> {<span class="dt">unsafe</span><span class="op">:</span> <span class="kw">true</span>})<span class="op">;</span></span></code></pre></div>
<h4 id="optionsignorefunction"><code>options.ignoreFunction</code></h4>
<p>This option is to signal <code>serialize()</code> that we do not want
serialize JavaScript function. Just treat function like
<code>JSON.stringify</code> do, but other features will work as
expected.</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode js"><code class="sourceCode javascript"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="fu">serialize</span>(obj<span class="op">,</span> {<span class="dt">ignoreFunction</span><span class="op">:</span> <span class="kw">true</span>})<span class="op">;</span></span></code></pre></div>
<h2 id="deserializing">Deserializing</h2>
<p>For some use cases you might also need to deserialize the string.
This is explicitly not part of this module. However, you can easily
write it yourself:</p>
<div class="sourceCode" id="cb10"><pre
class="sourceCode js"><code class="sourceCode javascript"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="kw">function</span> <span class="fu">deserialize</span>(serializedJavascript){</span>
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span> <span class="pp">eval</span>(<span class="st">'('</span> <span class="op">+</span> serializedJavascript <span class="op">+</span> <span class="st">')'</span>)<span class="op">;</span></span>
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>}</span></code></pre></div>
<p><strong>Note:</strong> Don't forget the parentheses around the
serialized javascript, as the opening bracket <code>{</code> will be
considered to be the start of a body.</p>
<h2 id="license">License</h2>
<p>This software is free to use under the Yahoo! Inc. BSD license. See
the <a
href="https://github.com/yahoo/serialize-javascript/blob/main/LICENSE">LICENSE
file</a> for license text and copyright information.</p>
</body>
</html>
|