From adaa95ebb84860b809ece199197349b69b7ecd43 Mon Sep 17 00:00:00 2001
From: Kevin Jahns <kevin.jahns@protonmail.com>
Date: Thu, 27 Apr 2023 18:08:10 +0200
Subject: [PATCH] add example to createDocFromSnapshot - #159

---
 src/utils/Snapshot.js   | 10 +++++++++-
 tests/snapshot.tests.js | 12 ++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/utils/Snapshot.js b/src/utils/Snapshot.js
index c9aa19e9..a13bb559 100644
--- a/src/utils/Snapshot.js
+++ b/src/utils/Snapshot.js
@@ -153,6 +153,14 @@ export const splitSnapshotAffectedStructs = (transaction, snapshot) => {
 }
 
 /**
+ * @example
+ *  const ydoc = new Y.Doc({ gc: false })
+ *  ydoc.getText().insert(0, 'world!')
+ *  const snapshot = Y.snapshot(ydoc)
+ *  ydoc.getText().insert(0, 'hello ')
+ *  const restored = Y.createDocFromSnapshot(ydoc, snapshot)
+ *  assert(restored.getText().toString() === 'world!')
+ *
  * @param {Doc} originDoc
  * @param {Snapshot} snapshot
  * @param {Doc} [newDoc] Optionally, you may define the Yjs document that receives the data from originDoc
@@ -161,7 +169,7 @@ export const splitSnapshotAffectedStructs = (transaction, snapshot) => {
 export const createDocFromSnapshot = (originDoc, snapshot, newDoc = new Doc()) => {
   if (originDoc.gc) {
     // we should not try to restore a GC-ed document, because some of the restored items might have their content deleted
-    throw new Error('originDoc must not be garbage collected')
+    throw new Error('Garbage-collection must be disabled in `originDoc`!')
   }
   const { sv, ds } = snapshot
 
diff --git a/tests/snapshot.tests.js b/tests/snapshot.tests.js
index 7f26718d..cd3e4773 100644
--- a/tests/snapshot.tests.js
+++ b/tests/snapshot.tests.js
@@ -2,6 +2,18 @@ import * as Y from '../src/index.js'
 import * as t from 'lib0/testing'
 import { init } from './testHelper.js'
 
+/**
+ * @param {t.TestCase} tc
+ */
+export const testBasic = tc => {
+  const ydoc = new Y.Doc({ gc: false })
+  ydoc.getText().insert(0, 'world!')
+  const snapshot = Y.snapshot(ydoc)
+  ydoc.getText().insert(0, 'hello ')
+  const restored = Y.createDocFromSnapshot(ydoc, snapshot)
+  t.assert(restored.getText().toString() === 'world!')
+}
+
 /**
  * @param {t.TestCase} tc
  */