feat: version field to prevent overwrite instead of updated_at (#131)

Signed-off-by: David Dal Busco <[email protected]>

docs/build/datastore.md

@@ -170,25 +170,38 @@ const docs = await getManyDocs({ docs: [docPair1, docPair2] });
 
 ## Update a document
 
-To update a document, use the `setDoc` function with a timestamp to validate that the most recent entry is being updated:
+To update a document, use the `setDoc` function with its current version to validate that the most recent entry is being updated:
 
 ```typescript
 import { setDoc } from "@junobuild/core";
 
 await setDoc<Example>({
   collection: "my_collection_key",
   doc: {
-    ...myDoc, // includes 'key' and 'updated_at'
-    data: myNewData
+    key: myId,
+    data: myExample,
+    version: 3n
   }
 });
 ```
 
-The `updated_at` timestamp must match the timestamp of the last document update on the satellite, otherwise the call will fail. This prevents unexpected concurrent updates.
+The `version` must match the current version of the last document within the satellite; otherwise, the call will fail. This prevents unexpected concurrent overwrites, which is useful, for example, if your users use your projects simultaneously on multiple devices.
 
 :::tip
 
-It is common to retrieve the document with `getDoc` before updating it to ensure that you have the most recent timestamp.
+You can spread the document you have previously retrieved, for example with `getDoc`, to populate the `version` and `key` fields.
+
+```typescript
+import { setDoc } from "@junobuild/core";
+
+await setDoc<Example>({
+  collection: "my_collection_key",
+  doc: {
+    ...myDoc, // includes 'key' and 'version'
+    data: myNewData
+  }
+});
+```
 
 :::
 

docs/guides/rust.md

@@ -145,7 +145,7 @@ async fn on_set_doc(context: OnSetDocContext) -> Result<(), String> {
     let doc: SetDoc = SetDoc {
         data: encode_data,
         description: context.data.data.after.description,
-        updated_at: Some(context.data.data.after.updated_at),
+        version: context.data.data.after.version,
     };
 
     // We save the document for the same caller as the one who triggered the original on_set_doc, in the same collection with the same key as well.
@@ -273,7 +273,7 @@ async fn on_set_doc(context: OnSetDocContext) -> Result<(), String> {
             let doc: SetDoc = SetDoc {
                 data: encode_data,
                 description: context.data.data.after.description,
-                updated_at: Some(context.data.data.after.updated_at),
+                version: context.data.data.after.version,
             };
 
             // 7. We store the data in the Datastore for the same caller as the one who triggered the original on_set_doc, in the same collection with the same key as well.