Merge pull request #39 from Rich-Harris/devalue-json

add a non-JavaScript mode

Author: Rich-Harris

README.md

@@ -25,32 +25,58 @@ Try it out [here](https://svelte.dev/repl/138d70def7a748ce9eda736ef1c71239?versi
 
 ## Usage
 
+There are two ways to use `devalue`:
+
+### `uneval`
+
+This function takes a JavaScript value and returns the JavaScript code to create an equivalent value — sort of like `eval` in reverse:
+
+```js
+import * as devalue from 'devalue';
+
+let obj = { message: 'hello' };
+devalue.uneval(obj); // '{message:"hello"}'
+
+obj.self = obj;
+devalue.uneval(obj); // '(function(a){a.message="hello";a.self=a;return a}({}))'
+```
+
+Use `uneval` when you want the most compact possible output and don't want to include any code for parsing the serialized value.
+
+### `stringify` and `parse`
+
+These two functions are analogous to `JSON.stringify` and `JSON.parse`:
+
 ```js
-import { devalue } from 'devalue';
+import * as devalue from 'devalue';
 
-let obj = { a: 1, b: 2 };
-obj.c = 3;
+let obj = { message: 'hello' };
 
-devalue(obj); // '{a:1,b:2,c:3}'
+let stringified = devalue.stringify(obj); // '[{"message":1},"hello"]'
+devalue.parse(stringified); // { message: 'hello' }
 
 obj.self = obj;
-devalue(obj); // '(function(a){a.a=1;a.b=2;a.c=3;a.self=a;return a}({}))'
+
+stringified = devalue.stringify(obj); // '[{"message":1,"self":0},"hello"]'
+devalue.parse(stringified); // { message: 'hello', self: [Circular] }
 ```
 
+Use `stringify` and `parse` when evaluating JavaScript isn't an option.
+
 ## Error handling
 
-If `devalue` encounters a function or a non-POJO, it will throw an error. You can find where in the input data the offending value lives by inspecting `error.path`:
+If `uneval` or `stringify` encounters a function or a non-POJO, it will throw an error. You can find where in the input data the offending value lives by inspecting `error.path`:
 
 ```js
 try {
   const map = new Map();
   map.set('key', function invalid() {});
 
-  devalue({
+  uneval({
     object: {
       array: [map]
     }
-  })
+  });
 } catch (e) {
   console.log(e.path); // '.object.array[0].get("key")'
 }
@@ -84,12 +110,12 @@ Which would result in this:
 </script>
 ```
 
-Using `devalue`, we're protected against that attack:
+Using `uneval` or `stringify`, we're protected against that attack:
 
 ```js
 const template = `
 <script>
-  var preloaded = ${devalue(state)};
+  var preloaded = ${uneval(state)};
 </script>`;
 ```
 
@@ -102,15 +128,15 @@ const template = `
 </script>
 ```
 
-This, along with the fact that `devalue` bails on functions and non-POJOs, stops attackers from executing arbitrary code. Strings generated by `devalue` can be safely deserialized with `eval` or `new Function`:
+This, 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`:
 
 ```js
 const value = (0, eval)('(' + str + ')');
 ```
 
 ## Other security considerations
 
-While `devalue` 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 `devalue` would have access to your system.
+While `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.
 
 When using `eval`, ensure that you call it _indirectly_ so that the evaluated code doesn't have access to the surrounding scope:
 
@@ -127,7 +153,7 @@ Using `new Function(code)` is akin to using indirect eval.
 ## See also
 
 - [lave](https://github.com/jed/lave) by Jed Schmidt
-- [arson](https://github.com/benjamn/arson) by Ben Newman
+- [arson](https://github.com/benjamn/arson) by Ben Newman. The `stringify`/`parse` approach in `devalue` was inspired by `arson`
 - [tosource](https://github.com/marcello3d/node-tosource) by Marcello Bastéa-Forte
 - [serialize-javascript](https://github.com/yahoo/serialize-javascript) by Eric Ferraiuolo
 - [jsesc](https://github.com/mathiasbynens/jsesc) by Mathias Bynens

devalue.test.js

@@ -0,0 +1,9 @@
+export { uneval } from './src/uneval.js';
+export { parse } from './src/parse.js';
+export { stringify } from './src/stringify.js';
+
+export function devalue() {
+	throw new Error(
+		'The `devalue` export has been removed. Use `uneval` instead'
+	);
+}

index.js

@@ -5,23 +5,24 @@
 	"repository": "Rich-Harris/devalue",
 	"exports": {
 		".": {
-			"import": "./devalue.js",
-			"types": "./types/devalue.d.ts"
+			"import": "./index.js",
+			"types": "./types/index.d.ts"
 		}
 	},
-	"main": "devalue.js",
+	"main": "index.js",
 	"files": [
-		"devalue.js",
+		"index.js",
+		"src",
 		"types"
 	],
-	"types": "./types/devalue.d.ts",
+	"types": "./types/index.d.ts",
 	"devDependencies": {
 		"typescript": "^3.1.3",
 		"uvu": "^0.5.6"
 	},
 	"scripts": {
 		"build": "tsc",
-		"test": "node devalue.test.js",
+		"test": "uvu test",
 		"prepublishOnly": "npm test && npm run build"
 	},
 	"license": "MIT",

package.json

@@ -0,0 +1,6 @@
+export const UNDEFINED = -1;
+export const HOLE = -2;
+export const NAN = -3;
+export const POSITIVE_INFINITY = -4;
+export const NEGATIVE_INFINITY = -5;
+export const NEGATIVE_ZERO = -6;