From 455162feae4d9f37d431c4e23ff8bd9957c12307 Mon Sep 17 00:00:00 2001
From: Evyatar Alush <ealush@meta.com>
Date: Mon, 25 Nov 2024 12:21:09 +0200
Subject: [PATCH] docs: suite serialization

---
 .DS_Store                               | Bin 0 -> 6148 bytes
 website/docs/server_side_validations.md |  27 +-----
 website/docs/suite_serialization.md     | 112 ++++++++++++++++++++++++
 3 files changed, 114 insertions(+), 25 deletions(-)
 create mode 100644 .DS_Store
 create mode 100644 website/docs/suite_serialization.md

diff --git a/.DS_Store b/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..5008ddfcf53c02e82d7eee2e57c38e5672ef89f6
GIT binary patch
literal 6148
zcmeH~Jr2S!425mzP>H1@V-^m;4Wg<&0T*E43hX&L&p$$qDprKhvt+--jT7}7np#A3
zem<@ulZcFPQ@L2!n>{z**<q8>++&mCkOWA81W14cNZ<zv;LbK1Poaz?KmsK2CSc!(
z0ynLxE!0092;Krf2c+FF_Fe*7ECH>lEfg7;MkzE(HCqgga^y>{tEnwC%0;vJ&^%eQ
zLs35+`xjp>T0<F0fCPF1$Cyrb|F7^5{eNG?83~ZUUlGt@xh*qZDeu<Z%US-OSsOPv
j)R!Z4KLME7ReXlK;d!wEw5GODWMKRea10D2@KpjYNUI8I

literal 0
HcmV?d00001

diff --git a/website/docs/server_side_validations.md b/website/docs/server_side_validations.md
index 74c00a6a5..2a6515e20 100644
--- a/website/docs/server_side_validations.md
+++ b/website/docs/server_side_validations.md
@@ -66,29 +66,6 @@ function serversideCheck(data) {
 }
 ```
 
-## require vs import
+## Full stack validations
 
-Depending on your node version and the module system you support you can use different syntax to include Vest.
-
-### Most compatible: commonjs
-
-To be on the safe side and compatible with all node versions, use a `require` statement.
-
-```js
-const vest = require('vest');
-const { test, enforce } = vest;
-```
-
-### Node 14
-
-With node 14's support of [package entry points](https://nodejs.org/api/esm.html#esm_package_entry_points), node should be able to detect on its own which import style you use and load the correct bundle.
-
-Both of the following should work:
-
-```js
-import { create, test } from 'vest';
-```
-
-```js
-const vest = require('vest');
-```
+Vest allows serializing and resuming validations across client and server. Read more in [suite serialization and resumption](./suite_serialization.md).
diff --git a/website/docs/suite_serialization.md b/website/docs/suite_serialization.md
new file mode 100644
index 000000000..d20fd350d
--- /dev/null
+++ b/website/docs/suite_serialization.md
@@ -0,0 +1,112 @@
+---
+sidebar_position: 12
+title: Suite Serialization and Resumption
+description: Serialize and resume Vest suites across different environments, such as client-side and server-side.
+keywords:
+  [Vest, serialize, resume, client, server, validation, full stack validation]
+---
+
+# Suite Serialization and Resumption
+
+Vest provides the ability to serialize and resume validation suites, allowing you to transfer the state of validations between different environments, such as from the server to the client. This feature enhances the user experience by providing immediate feedback on the client-side based on server-side validations.
+
+## Use Cases
+
+- **Client-Server Validation:** Perform validations on the server and seamlessly resume them on the client, providing immediate feedback to the user without re-running all validations.
+- **Persistence:** Store the validation state and resume it later, for example, if the user navigates away from a form and returns.
+- **Debugging:** Serialize the state of a suite for debugging purposes, making it easier to reproduce and analyze validation issues.
+
+## How it Works
+
+The `SuiteSerializer` object provides two static methods: `serialize` and `resume`.
+
+### `SuiteSerializer.serialize()`
+
+This method takes a Vest suite instance and returns a string representation of the suite's current state. This string can be transferred to another environment, such as the client.
+
+```javascript
+import { SuiteSerializer } from 'vest';
+
+const suite = create(data => {
+  // ... your validation tests ...
+});
+
+suite(formData); // Run the suite with some data
+
+const serializedSuite = SuiteSerializer.serialize(suite);
+```
+
+## SuiteSerializer.resume()
+
+This method takes a Vest suite instance and a serialized suite string. It applies the serialized state to the provided suite instance, effectively resuming the validation state from the serialized data.
+
+```js
+import { SuiteSerializer } from 'vest';
+
+const suite = create(data => {
+  // ... your validation tests ...
+});
+
+SuiteSerializer.resume(suite, serializedSuite);
+
+// The suite now has the state from the serializedSuite string
+```
+
+## Example: Client-Server Validation
+
+```js
+// suite.js
+import { create } from 'vest';
+import { SuiteSerializer } from 'vest';
+
+const suite = create(data => {
+  test('username', 'Username is required', () => {
+    enforce(data.username).isNotBlank();
+  });
+
+  test('email', 'Email is invalid', () => {
+    enforce(data.email).isEmail();
+  });
+});
+```
+
+```js
+// server.js
+
+app.post('/submit', (req, res) => {
+  const formData = req.body;
+
+  suite(formData);
+
+  const serializedSuite = SuiteSerializer.serialize(suite);
+
+  res.json({ serializedSuite });
+});
+```
+
+```js
+// client.js
+import suite from './suite';
+import { SuiteSerializer } from 'vest';
+
+const form = document.getElementById('myForm');
+
+form.addEventListener('submit', (event) => {
+  event.preventDefault();
+
+  const formData = new FormData(form);  
+
+
+  fetch('/submit', {
+    method: 'POST',
+    body: formData,
+  })
+    .then((response) => response.json())
+    .then((data)  
+ => {
+      SuiteSerializer.resume(suite, data.serializedSuite);
+    });
+});
+```
+
+In this example, the server performs the initial validation and sends the serialized suite state to the client. The client then resumes the suite with the received state, allowing for immediate feedback and a consistent validation experience across both environments.