Brunobkr/llama.cpp_AlgMor24_github

1Serialize JavaScript2====================3 4Serialize JavaScript to a _superset_ of JSON that includes regular expressions, dates and functions.5 6[![npm Version][npm-badge]][npm]7![Test](https://github.com/yahoo/serialize-javascript/workflows/Test/badge.svg)8 9## Overview10 11The code in this package began its life as an internal module to [express-state][]. To expand its usefulness, it now lives as `serialize-javascript` — an independent package on npm.12 13You're probably wondering: **What about `JSON.stringify()`!?** We've found that sometimes we need to serialize JavaScript **functions**, **regexps**, **dates**, **sets** or **maps**. 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.14 15The string returned from this package's single export function is literal JavaScript which can be saved to a `.js` file, or be embedded into an HTML document by making the content of a `<script>` element.16 17> **HTML characters and JavaScript line terminators are escaped automatically.**18 19Please note that serialization for ES6 Sets & Maps requires support for `Array.from` (not available in IE or Node < 0.12), or an `Array.from` polyfill.20 21> [!WARNING]22> It may be tempting to use this package as a way to pass arbitrary functions into [worker threads][], since you cannot pass them directly via `postMessage()`. However, passing functions between worker threads is not possible in the general case. This package lets you serialize *some* functions, but it has limitations.23>24> For instance, if a function references something from outside the function body, it will not run properly if serialized and deserialized. This could include [closed-over variables][] or imports from other packages. For a serialized function to run properly, it must be entirely self-contained.25>26> In general, it is not possible to send arbitrary JavaScript to a worker thread, and pretend it's running the same way it would run on the main thread. This package doesn't let you do that.27 28## Installation29 30Install using npm:31 32```shell33$ npm install serialize-javascript34```35 36## Usage37 38```js39var serialize = require('serialize-javascript');40 41serialize({42    str  : 'string',43    num  : 0,44    obj  : {foo: 'foo'},45    arr  : [1, 2, 3],46    bool : true,47    nil  : null,48    undef: undefined,49    inf  : Infinity,50    date : new Date("Thu, 28 Apr 2016 22:02:17 GMT"),51    map  : new Map([['hello', 'world']]),52    set  : new Set([123, 456]),53    fn   : function echo(arg) { return arg; },54    re   : /([^\s]+)/g,55    big  : BigInt(10),56    url  : new URL('https://example.com/'),57});58```59 60The above will produce the following string output:61 62```js63'{"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("([^\\\\s]+)", "g"),"big":BigInt("10"),"url":new URL("https://example.com/")}'64```65 66Note: to produce a beautified string, you can pass an optional second argument to `serialize()` to define the number of spaces to be used for the indentation.67 68### Automatic Escaping of HTML Characters69 70A 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 `<script>` element. In order to make this safe, HTML characters and JavaScript line terminators are escaped automatically.71 72```js73serialize({74    haxorXSS: '</script>'75});76```77 78The 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:79 80```js81'{"haxorXSS":"\\u003C\\u002Fscript\\u003E"}'82```83 84> You can pass an optional `unsafe` argument to `serialize()` for straight serialization.85 86### Options87 88The `serialize()` function accepts an `options` object as its second argument. All options are being defaulted to `undefined`:89 90#### `options.space`91 92This option is the same as the `space` argument that can be passed to [`JSON.stringify`][JSON.stringify]. It can be used to add whitespace and indentation to the serialized output to make it more readable.93 94```js95serialize(obj, {space: 2});96```97 98#### `options.isJSON`99 100This option is a signal to `serialize()` 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.101 102**Note:** That when using this option, the output will still be escaped to protect against XSS.103 104```js105serialize(obj, {isJSON: true});106```107 108#### `options.unsafe`109 110This option is to signal `serialize()` that we want to do a straight conversion, without the XSS protection. This options needs to be explicitly set to `true`. HTML characters and JavaScript line terminators will not be escaped. You will have to roll your own.111 112```js113serialize(obj, {unsafe: true});114```115 116#### `options.ignoreFunction`117 118This option is to signal `serialize()` that we do not want serialize JavaScript function. 119Just treat function like `JSON.stringify` do, but other features will work as expected.120 121```js122serialize(obj, {ignoreFunction: true});123```124 125## Deserializing126 127For 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:128 129```js130function deserialize(serializedJavascript){131  return eval('(' + serializedJavascript + ')');132}133```134 135**Note:** Don't forget the parentheses around the serialized javascript, as the opening bracket `{` will be considered to be the start of a body.136 137## License138 139This software is free to use under the Yahoo! Inc. BSD license.140See the [LICENSE file][LICENSE] for license text and copyright information.141 142 143[npm]: https://www.npmjs.org/package/serialize-javascript144[npm-badge]: https://img.shields.io/npm/v/serialize-javascript.svg?style=flat-square145[express-state]: https://github.com/yahoo/express-state146[JSON.stringify]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify147[LICENSE]: https://github.com/yahoo/serialize-javascript/blob/main/LICENSE148[worker threads]: https://nodejs.org/api/worker_threads.html149[closed-over variables]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Closures150