Brunobkr/llama.cpp_AlgMor24_github

1# devalue2 3Like `JSON.stringify`, but handles4 5- cyclical references (`obj.self = obj`)6- repeated references (`[value, value]`)7- `undefined`, `Infinity`, `NaN`, `-0`8- regular expressions9- dates10- `Map` and `Set`11- `BigInt`12- `ArrayBuffer` and Typed Arrays13- `URL` and `URLSearchParams`14- `Temporal`15- custom types via replacers, reducers and revivers16- promises (via `stringifyAsync`)17 18Try it out [here](https://svelte.dev/repl/138d70def7a748ce9eda736ef1c71239?version=3.49.0).19 20## Goals:21 22- Performance23- Security (see [XSS mitigation](#xss-mitigation))24- Compact output25 26## Non-goals:27 28- Human-readable output29- Stringifying functions30- Stability of serialization mechanisms between versions (i.e. if you `devalue.stringify` with one version and `devalue.parse` with another, things may break)31 32## Usage33 34There are two ways to use `devalue`:35 36### `uneval`37 38This function takes a JavaScript value and returns the JavaScript code to create an equivalent value — sort of like `eval` in reverse:39 40```js41import * as devalue from 'devalue';42 43let obj = { message: 'hello' };44devalue.uneval(obj); // '{message:"hello"}'45 46obj.self = obj;47devalue.uneval(obj); // '(function(a){a.message="hello";a.self=a;return a}({}))'48```49 50Use `uneval` when you want the most compact possible output and don't want to include any code for parsing the serialized value.51 52### `stringify` and `parse`53 54These two functions are analogous to `JSON.stringify` and `JSON.parse`:55 56```js57import * as devalue from 'devalue';58 59let obj = { message: 'hello' };60 61let stringified = devalue.stringify(obj); // '[{"message":1},"hello"]'62devalue.parse(stringified); // { message: 'hello' }63 64obj.self = obj;65 66stringified = devalue.stringify(obj); // '[{"message":1,"self":0},"hello"]'67devalue.parse(stringified); // { message: 'hello', self: [Circular] }68```69 70Use `stringify` and `parse` when evaluating JavaScript isn't an option.71 72### `stringifyAsync`73 74`stringifyAsync` is an async version of `stringify` that can handle promises:75 76```js77import * as devalue from 'devalue';78 79let obj = {80	quick: 'data',81	slow: fetch('/api/slow').then((r) => r.json())82};83 84let stringified = await devalue.stringifyAsync(obj);85devalue.parse(stringified); // { quick: 'data', slow: { ... } }86```87 88Promises are awaited and their resolved values are serialized. The output format is identical to `stringify`, so `parse` and `unflatten` work unchanged.89 90### `unflatten`91 92In the case where devalued data is one part of a larger JSON string, `unflatten` allows you to revive just the bit you need:93 94```js95import * as devalue from 'devalue';96 97const json = `{98  "type": "data",99  "data": ${devalue.stringify(data)}100}`;101 102const data = devalue.unflatten(JSON.parse(json).data);103```104 105## Custom types106 107You can serialize and deserialize custom types by passing a second argument to `stringify` containing an object of types and their _reducers_, and a second argument to `parse` or `unflatten` containing an object of types and their _revivers_:108 109```js110class Vector {111	constructor(x, y) {112		this.x = x;113		this.y = y;114	}115 116	magnitude() {117		return Math.sqrt(this.x * this.x + this.y * this.y);118	}119}120 121const stringified = devalue.stringify(new Vector(30, 40), {122	Vector: (value) => value instanceof Vector && [value.x, value.y]123});124 125console.log(stringified); // [["Vector",1],[2,3],30,40]126 127const vector = devalue.parse(stringified, {128	Vector: ([x, y]) => new Vector(x, y)129});130 131console.log(vector.magnitude()); // 50132```133 134If a function passed to `stringify` returns a truthy value, it's treated as a match.135 136You can also use custom types with `uneval` by specifying a custom replacer:137 138```js139devalue.uneval(vector, (value, uneval) => {140	if (value instanceof Vector) {141		return `new Vector(${value.x},${value.y})`;142	}143}); // `new Vector(30,40)`144```145 146Note that any variables referenced in the resulting JavaScript (like `Vector` in the example above) must be in scope when it runs.147 148## Error handling149 150If `uneval` or `stringify` encounters a function or a non-POJO that isn't handled by a custom replacer/reducer, it will throw an error. You can find where in the input data the offending value lives by inspecting `error.path`:151 152```js153try {154	const map = new Map();155	map.set('key', function invalid() {});156 157	uneval({158		object: {159			array: [map]160		}161	});162} catch (e) {163	console.log(e.path); // '.object.array[0].get("key")'164}165```166 167## XSS mitigation168 169Say you're server-rendering a page and want to serialize some state, which could include user input. `JSON.stringify` doesn't protect against XSS attacks:170 171```js172const state = {173	userinput: `</script><script src='https://evil.com/mwahaha.js'>`174};175 176const template = `177<script>178  // NEVER DO THIS179  var preloaded = ${JSON.stringify(state)};180</script>`;181```182 183Which would result in this:184 185```html186<script>187	// NEVER DO THIS188	var preloaded = {"userinput":"189</script>190<script src="https://evil.com/mwahaha.js">191	"};192</script>193```194 195Using `uneval` or `stringify`, we're protected against that attack:196 197```js198const template = `199<script>200  var preloaded = ${uneval(state)};201</script>`;202```203 204```html205<script>206	var preloaded = {207		userinput:208			"\\u003C\\u002Fscript\\u003E\\u003Cscript src='https:\\u002F\\u002Fevil.com\\u002Fmwahaha.js'\\u003E"209	};210</script>211```212 213This, along with the fact that `uneval` and `stringify` bail on functions and non-POJOs, stops attackers from executing arbitrary code. Strings generated by `uneval` can be safely deserialized with `eval` or `new Function`:214 215```js216const value = (0, eval)('(' + str + ')');217```218 219## Other security considerations220 221While `uneval` prevents the XSS vulnerability shown above, meaning you can use it to send data from server to client, **you should not send user data from client to server** using the same method. Since it has to be evaluated, an attacker that successfully submitted data that bypassed `uneval` would have access to your system.222 223When using `eval`, ensure that you call it _indirectly_ so that the evaluated code doesn't have access to the surrounding scope:224 225```js226{227	const sensitiveData = 'Setec Astronomy';228	eval('sendToEvilServer(sensitiveData)'); // pwned :(229	(0, eval)('sendToEvilServer(sensitiveData)'); // nice try, evildoer!230}231```232 233Using `new Function(code)` is akin to using indirect eval.234 235## See also236 237- [lave](https://github.com/jed/lave) by Jed Schmidt238- [arson](https://github.com/benjamn/arson) by Ben Newman. The `stringify`/`parse` approach in `devalue` was inspired by `arson`239- [oson](https://github.com/KnorpelSenf/oson) by Steffen Trog240- [tosource](https://github.com/marcello3d/node-tosource) by Marcello Bastéa-Forte241- [serialize-javascript](https://github.com/yahoo/serialize-javascript) by Eric Ferraiuolo242- [jsesc](https://github.com/mathiasbynens/jsesc) by Mathias Bynens243- [superjson](https://github.com/blitz-js/superjson) by Blitz244- [next-json](https://github.com/iccicci/next-json) by Daniele Ricci245 246## License247 248[MIT](LICENSE)249