first version

Author: kof

.gitignore

@@ -0,0 +1,5 @@
+node_modules
+/dist
+.DS_Store
+.env
+yarn-error.log

README.md

@@ -1,51 +1,55 @@
-# Sync Engine
+# Immerhin
+
 The core idea is to use [Immer](https://immerjs.github.io/immer/) as an interface for state mutations and provide a convenient way to group mutations into a single transaction.
-As an end-result, we get patches that can be used to sync the app state across the application and to sync the changes to the server. This also gives us a way to undo/redo a transaction automatically.
+
+Using Immer's patches we sync the state across the application and to the server. This also gives us a way to undo/redo a transaction automatically.
 
 ## Features
 
 1. Update application state using [patches](https://immerjs.github.io/immer/patches)
-2. Synchronize with the server
+2. Synchronize to the server
 3. Get undo/redo on the client that does both updating the client state and syncing to the server
 4. Server agnostic
 5. State management agnostic (mostly)
 
 ## Example
 
 ```js
-import {createTransaction, register, sync, undo, redo} from 'sync-engine'
+import { createTransaction, register, sync, undo, redo } from "sync-engine";
 
 // Create containers for each state. Sync engine only cares that the result has a "value" and a "dispatch(newValue)"
 const container1 = createContainer(initialValue);
 const container2 = createContainer(initialValue);
 
 // - Explicitely enable containers for transactions
 // - Define a namespace for each container, so that server knows which object it has to patch.
-register('some-name1', container1);
-register('some-name2', container2);
+register("some-name1", container1);
+register("some-name2", container2);
 
 // Creating the actual transaction that will:
 // - generate patches
 // - update states
 // - inform all subscribers
 // - register a transaction for potential undo/redo and sync calls
-createTransaction([container1, container2, ...rest], (value1, value2, ...rest) => {
+createTransaction(
+  [container1, container2, ...rest],
+  (value1, value2, ...rest) => {
     mutateValue(value1);
     mutateValue(value2);
     // ...
-});
+  }
+);
 
 // Setup periodic sync with a fetch, or do this with Websocket
 setInterval(async () => {
-  const entries = sync()
-  await fetch('/patch', {method: 'POST', payload: JSON.stringify(entries)})
-}, 1000)
+  const entries = sync();
+  await fetch("/patch", { method: "POST", payload: JSON.stringify(entries) });
+}, 1000);
 
 // Undo/redo
 
-undo()
-redo()
-
+undo();
+redo();
 ```
 
 ## How it works
@@ -63,28 +67,29 @@ You can use the same container instance to subscribe to the changes across the e
 Example using nano state:
 
 ```js
-import {createContainer, useValue} from 'react-nano-state'
-const myContainer = createContainer(initialValue)
+import { createContainer, useValue } from "react-nano-state";
+const myContainer = createContainer(initialValue);
 
 // I can call a dispatch from anywhere
-myContainer.dispatch(newValue)
+myContainer.dispatch(newValue);
 
 // I can subscribe to updates in React
 const Component = () => {
-  const [value, setValue] = useValue(myContainer)
-}
+  const [value, setValue] = useValue(myContainer);
+};
 ```
 
 ### Container registration
 
-We register containers for two reasons: 
+We register containers for two reasons:
+
 1. To define a namespace for each container so that whoever consumes the changes knows which object to apply the patches to.
 2. Ensure that the container was intentionally registered to be synced to the server and be part of undo/redo transactions. You may not want this for every container since you can use them for ephemeral states.
 
 Example
 
 ```js
-register('myName', myContainer)
+register("myName", myContainer);
 ```
 
 ### Creating a transaction
@@ -100,11 +105,14 @@ A call into `createTransaction()`does all of this:
 Example
 
 ```js
-createTransaction([container1, container2, ...rest], (value1, value2, ...rest) => {
+createTransaction(
+  [container1, container2, ...rest],
+  (value1, value2, ...rest) => {
     mutateValue(value1);
     mutateValue(value2);
     // ...
-});
+  }
+);
 ```
 
 ### Undo/redo
@@ -121,58 +129,49 @@ Example
 ```js
 // Setup periodic sync with a fetch, or do this with Websocket
 setInterval(async () => {
-  const entries = sync()
-  await fetch('/patch', {method: 'POST', payload: JSON.stringify(entries)})
-}, 1000)
+  const entries = sync();
+  await fetch("/patch", { method: "POST", payload: JSON.stringify(entries) });
+}, 1000);
 ```
 
 Example entries:
 
 ```json
 [
-    {
-        "transactionId": "6243062b469f516835327f65",
-        "changes": [
-            {
-                "namespace": "root",
-                "patches": [
-                    {
-                        "op": "replace",
-                        "path": [
-                            "children",
-                            1
-                        ],
-                        "value": {
-                            "component": "Box",
-                            "id": "6241f55791596f2467df9c2a",
-                            "style": {},
-                            "children": []
-                        }
-                    },
-                    {
-                        "op": "replace",
-                        "path": [
-                            "children",
-                            2
-                        ],
-                        "value": {
-                            "component": "Box",
-                            "id": "6241f55a91596f2467df9c36",
-                            "style": {},
-                            "children": []
-                        }
-                    },
-                    {
-                        "op": "replace",
-                        "path": [
-                            "children",
-                            "length"
-                        ],
-                        "value": 3
-                    }
-                ]
+  {
+    "transactionId": "6243062b469f516835327f65",
+    "changes": [
+      {
+        "namespace": "root",
+        "patches": [
+          {
+            "op": "replace",
+            "path": ["children", 1],
+            "value": {
+              "component": "Box",
+              "id": "6241f55791596f2467df9c2a",
+              "style": {},
+              "children": []
+            }
+          },
+          {
+            "op": "replace",
+            "path": ["children", 2],
+            "value": {
+              "component": "Box",
+              "id": "6241f55a91596f2467df9c36",
+              "style": {},
+              "children": []
             }
+          },
+          {
+            "op": "replace",
+            "path": ["children", "length"],
+            "value": 3
+          }
         ]
-    }
+      }
+    ]
+  }
 ]
 ```

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: ["@babel/preset-typescript"],
+};

package.json

@@ -1,14 +1,17 @@
 {
-  "name": "sync-engine",
+  "name": "immerhin",
   "version": "0.1.0",
   "description": "Send patches to your server, update the UI state, get undo-redo for free",
-  "main": "lib/index.js",
+  "main": "dist/immerhin.cjs.js",
+  "module": "dist/immerhin.esm.js",
   "scripts": {
-    "test": "jest"
+    "build": "preconstruct build",
+    "dev": "preconstruct dev",
+    "prepublishOnly": "yarn build"
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://[email protected]/webstudio-is/sync-engine.git"
+    "url": "git+ssh://[email protected]/webstudio-is/immerhin.git"
   },
   "keywords": [
     "Immer",
@@ -21,7 +24,19 @@
   "author": "Oleg Isonen",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/webstudio-is/sync-engine/issues"
+    "url": "https://github.com/webstudio-is/immerhin/issues"
   },
-  "homepage": "https://github.com/webstudio-is/sync-engine#readme"
+  "homepage": "https://github.com/webstudio-is/immerhin#readme",
+  "devDependencies": {
+    "@babel/preset-typescript": "^7.16.7",
+    "@preconstruct/cli": "^2.1.5",
+    "typescript": "^4.6.3"
+  },
+  "dependencies": {
+    "bson-objectid": "^2.0.3",
+    "immer": "^9.0.12"
+  },
+  "files": [
+    "dist"
+  ]
 }

src/index.ts

@@ -0,0 +1,3 @@
+export { register, createTransaction } from "./store";
+export { sync, type SyncItem } from "./sync-queue";
+export { undo, redo } from "./transactions-manager";

src/store.ts

@@ -0,0 +1,64 @@
+import { createDraft, finishDraft, enablePatches, type Patch } from "immer";
+import { type ValueContainer } from "./types";
+import { Transaction } from "./transaction";
+import { add } from "./transactions-manager";
+
+enablePatches();
+
+// eslint-disable-next-line  @typescript-eslint/no-explicit-any
+type Any = any;
+
+const registry: Map<ValueContainer<Any>, string> = new Map();
+
+export const register = <Value>(
+  namespace: string,
+  container: ValueContainer<Value>
+) => {
+  registry.set(container, namespace);
+};
+
+type UnwrapContainers<Containers extends Array<ValueContainer<unknown>>> = {
+  [Index in keyof Containers]: Containers[Index] extends ValueContainer<
+    infer Value
+  >
+    ? Value
+    : never;
+};
+
+export const createTransaction = <
+  Containers extends Array<ValueContainer<Any>>
+>(
+  containers: [...Containers],
+  recipe: (...values: UnwrapContainers<Containers>) => void
+): UnwrapContainers<Containers> => {
+  type Values = UnwrapContainers<Containers>;
+  const drafts = [] as unknown as Values;
+  for (const container of containers) {
+    drafts.push(createDraft(container.value));
+  }
+  recipe(...drafts);
+  const transaction = new Transaction();
+  const values = [] as unknown as Values;
+  drafts.forEach((draft, index) => {
+    const namespace = registry.get(containers[index]);
+    if (namespace === undefined) {
+      throw new Error(
+        "Container used for transaction is not registered in sync engine"
+      );
+    }
+    const value = finishDraft(
+      draft,
+      (patches: Array<Patch>, revisePatches: Array<Patch>) => {
+        transaction.add({
+          namespace,
+          patches,
+          revisePatches,
+          container: containers[index],
+        });
+      }
+    );
+    values.push(value);
+  });
+  add(transaction);
+  return values;
+};

src/sync-queue.ts

@@ -0,0 +1,35 @@
+import { type Change } from "./transaction";
+
+export type SyncItem = {
+  transactionId: string;
+  changes: Array<Change>;
+};
+
+const queue: Array<SyncItem> = [];
+
+const dequeue = (transactionId: string) => {
+  const index = queue.findIndex(
+    (entry) => entry.transactionId === transactionId
+  );
+  if (index === -1) return false;
+  queue.splice(index, 1);
+  return true;
+};
+
+export const enqueue = (transactionId: string, changes: Array<Change>) => {
+  // We are trying to delete that transaction from the queue,
+  // if it was not found - we are adding the patches, because they are new
+  // if it was found - we don't add it because it is technically an undo operation.
+  // This can happen if user runs undo before sync happened, so we we are avoiding
+  // sending it to the server unnecessarily.
+  if (dequeue(transactionId) === false) {
+    queue.push({ transactionId, changes });
+  }
+};
+
+export const sync = () => {
+  if (queue.length === 0) return [];
+  const queueCopy = [...queue];
+  queue.splice(0);
+  return queueCopy;
+};