diff --git a/README.md b/README.md index 5bfc793..66e23b6 100644 --- a/README.md +++ b/README.md @@ -21,3 +21,153 @@ with Python. [V8 serialization format]: https://h4l.github.io/v8serialize/en/latest/explanation/v8_serialization_format.html + +## Examples + +These examples demonstrate serializing and deserializing the same selection of +JavaScript values in Python and JavaScript. JavaScript types supported by +JavaScript's [`structuredClone()` algorithm] can be serialized. + +[`structuredClone()` algorithm]: + https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm + +### Serialize with Python + +```python +from base64 import b64encode +from datetime import datetime, UTC +import re + +from v8serialize import dumps +from v8serialize.jstypes import JSObject, JSArray, JSUndefined + +serialized = dumps( + [ + "strings 🧵🧶🪡", + 123, + None, + JSUndefined, + JSArray({0: 'a', 1: 'b', 123456789: 'sparse'}), + JSObject({"msg": "Hi"}), + b"\xc0\xff\xee", + 2**128, + {"maps": True}, + {"sets", "yes"}, + re.compile(r"^\w+$"), + datetime(2024, 1, 1, tzinfo=UTC), + ] +) + +print(b64encode(serialized).decode()) +``` + +**Output** + +``` +/w9BDFMUc3RyaW5ncyDwn6e18J+ntvCfqqFVezBfYZaa7zpVAFMBYVUBUwFiVZWa7zpTBnNwYXJzZUADlprvOm9TA21zZ1MCSGl7AUIDwP/uWiIAAAAAAAAAAAAAAAAAAAAAATtTBG1hcHNUOgInUwRzZXRzUwN5ZXMsAlJTBV5cdyskgAJEAABAHyXMeEIkAAw= +``` + +### Deserialize with Python + +```python +from base64 import b64decode +from v8serialize import loads + +# The output of the JavaScript example +serialized = b64decode( + "/w9BDGMccwB0AHIAaQBuAGcAcwAgAD7Y9d0+2PbdPtih3kn2ATBfYZaa7zpJACIBYUkCIgFiSaq03nUiBnNwYXJzZUADlprvOm8iA21zZyICSGl7AUIDwP/uWjAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAA7IgRtYXBzVDoCJyIDeWVzIgRzZXRzLAJSIgVeXHcrJIACRAAAQB8lzHhCJAAM" +) +print(loads(serialized)) +``` + +**Output** + +```python +JSArray([ + 'strings 🧵🧶🪡', + 123, + None, + JSUndefined, + JSArray({ + 0: 'a', + 1: 'b', + 123456789: 'sparse', + }), + JSObject(msg='Hi'), + JSArrayBuffer(b'\xc0\xff\xee'), + 340282366920938463463374607431768211456, + JSMap({ + 'maps': True, + }), + JSSet([ + 'yes', + 'sets', + ]), + JSRegExp(source='^\\w+$', flags=), + datetime.datetime(2024, 1, 1, 0, 0), +]) +``` + +### Serialize with Node.js / Deno + +```javascript +import * as v8 from "node:v8"; + +const sparseArray = ["a", "b"]; +sparseArray[123456789] = "sparse"; + +const buffer = v8.serialize([ + "strings 🧵🧶🪡", + 123, + null, + undefined, + sparseArray, + { msg: "Hi" }, + Uint8Array.from([0xc0, 0xff, 0xee]).buffer, + 2n ** 128n, + new Map([["maps", true]]), + new Set(["yes", "sets"]), + /^\w+$/v, + new Date(Date.UTC(2024, 0, 1)), +]); + +console.log(buffer.toString("base64")); +``` + +**Output** + +``` +/w9BDGMccwB0AHIAaQBuAGcAcwAgAD7Y9d0+2PbdPtih3kn2ATBfYZaa7zpJACIBYUkCIgFiSaq03nUiBnNwYXJzZUADlprvOm8iA21zZyICSGl7AUIDwP/uWjAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAA7IgRtYXBzVDoCJyIDeWVzIgRzZXRzLAJSIgVeXHcrJIACRAAAQB8lzHhCJAAM +``` + +## Deserialize with Node.js / Deno + +```javascript +import * as v8 from "node:v8"; + +// The output of the Python example +const buffer = Buffer.from( + "/w9BDFMUc3RyaW5ncyDwn6e18J+ntvCfqqFVezBfYZaa7zpVAFMBYVUBUwFiVZWa7zpTBnNwYXJzZUADlprvOm9TA21zZ1MCSGl7AUIDwP/uWiIAAAAAAAAAAAAAAAAAAAAAATtTBG1hcHNUOgInUwN5ZXNTBHNldHMsAlJTBV5cdyskgAJEAABAHyXMeEIkAAw=", + "base64" +); +console.log(v8.deserialize(buffer)); +``` + +**Output** + +```javascript +[ + 'strings 🧵🧶🪡', + 123, + null, + undefined, + [ 'a', 'b', <123456787 empty items>, 'sparse' ], + { msg: 'Hi' }, + ArrayBuffer { [Uint8Contents]: , byteLength: 3 }, + 340282366920938463463374607431768211456n, + Map(1) { 'maps' => true }, + Set(2) { 'yes', 'sets' }, + /^\w+$/v, + 2024-01-01T00:00:00.000Z +] +```