rename devalue function to uneval, update README

Author: Rich-Harris

README.md

@@ -25,32 +25,58 @@ Try it out on [runkit.com](https://npm.runkit.com/devalue).
 
 ## 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 { uneval } from 'devalue';
+
+let obj = { message: 'hello' };
+uneval(obj); // '{message:"hello"}'
+
+obj.self = obj;
+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 { stringify, parse } 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 = stringify(obj); // '[{"message":1},"hello"]'
+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 = stringify(obj); // '[{"message":1,"self":0},"hello"]'
+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:
 

index.js

@@ -1,3 +1,9 @@
-export { devalue } from './src/devalue.js';
+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'
+	);
+}

src/devalue.js renamed to src/uneval.js

@@ -18,7 +18,7 @@ const object_proto_names = Object.getOwnPropertyNames(Object.prototype)
  * Turn a value into the JavaScript that creates an equivalent value
  * @param {any} value
  */
-export function devalue(value) {
+export function uneval(value) {
 	const counts = new Map();
 
 	/** @type {string[]} */

test/test.js

@@ -1,7 +1,7 @@
 import * as vm from 'vm';
 import * as assert from 'uvu/assert';
 import * as uvu from 'uvu';
-import { devalue, parse, stringify } from '../index.js';
+import { uneval, parse, stringify } from '../index.js';
 
 const fixtures = {
 	basics: [
@@ -350,10 +350,10 @@ const fixtures = {
 };
 
 for (const [name, tests] of Object.entries(fixtures)) {
-	const test = uvu.suite(`devalue: ${name}`);
+	const test = uvu.suite(`uneval: ${name}`);
 	for (const t of tests) {
 		test(t.name, () => {
-			const actual = devalue(t.value);
+			const actual = uneval(t.value);
 			const expected = t.js;
 			assert.equal(actual, expected);
 		});
@@ -390,7 +390,7 @@ for (const [name, tests] of Object.entries(fixtures)) {
 	test.run();
 }
 
-for (const fn of [devalue, stringify]) {
+for (const fn of [uneval, stringify]) {
 	uvu.test(`${fn.name} throws for non-POJOs`, () => {
 		class Foo {}
 		const foo = new Foo();
@@ -432,7 +432,7 @@ for (const fn of [devalue, stringify]) {
 uvu.test('does not create duplicate parameter names', () => {
 	const foo = new Array(20000).fill(0).map((_, i) => i);
 	const bar = foo.map((_, i) => ({ [i]: foo[i] }));
-	const serialized = devalue([foo, ...bar]);
+	const serialized = uneval([foo, ...bar]);
 
 	eval(serialized);
 });