├── .gitignore
├── LICENSE
├── README.md
├── babel.config.js
├── examples
└── react
│ ├── .gitignore
│ ├── index.html
│ ├── index.js
│ ├── package.json
│ └── yarn.lock
├── package.json
├── src
├── index.ts
├── store.ts
├── sync-queue.ts
├── transaction.ts
├── transactions-manager.ts
└── types.ts
├── tsconfig.json
└── yarn.lock
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | dist
3 | .DS_Store
4 | .env
5 | yarn-error.log
6 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2022 Webstudio
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | The core idea is to use [patches](https://immerjs.github.io/immer/patches) to keep the UI in sync between client and server, multiple clients, or multiple windows.
6 |
7 | It uses [Immer](https://immerjs.github.io/immer/) as an interface for state mutations and provides a convenient way to group mutations into a single transaction, and enables undo/redo out of the box.
8 |
9 | [Play with it on Codesandbox](https://codesandbox.io/s/github/webstudio-is/immerhin/tree/main/examples/react)
10 |
11 | [Read the article](https://dev.to/oleg008/synchronized-immutable-state-with-time-travel-2c6o)
12 |
13 | ## Features
14 |
15 | 1. Sync application state using [patches](https://immerjs.github.io/immer/patches)
16 | 1. Get undo/redo for free
17 | 1. Sync to the server
18 | 1. Server agnostic
19 | 1. State management libraries agnostic (a container interface)
20 | 1. Small bundle size
21 | 1. Sync between iframes (not implemented yet)
22 | 1. Sync between tabs (not implemented yet)
23 | 1. Resolve conflicts (not implemented yet)
24 | 1. Provide server handler (not implemented yet)
25 |
26 | ## Example
27 |
28 | ```js
29 | import store, { sync } from "immerhin";
30 |
31 | // Create containers for each state. Sync engine only cares that the result has a "get()" and a "set(newValue)"
32 | const container1 = atom(initialValue);
33 | const container2 = atom(initialValue);
34 |
35 | // - Explicitely enable containers for transactions
36 | // - Define a namespace for each container, so that server knows which object it has to patch.
37 | store.register("container1", container1);
38 | store.register("container2", container2);
39 |
40 | // Creating the actual transaction that will:
41 | // - generate patches
42 | // - update states
43 | // - inform all subscribers
44 | // - register a transaction for potential undo/redo and sync calls
45 | store.createTransaction(
46 | [container1, container2, ...rest],
47 | (value1, value2, ...rest) => {
48 | mutateValue(value1);
49 | mutateValue(value2);
50 | // ...
51 | }
52 | );
53 |
54 | // Setup periodic sync with a fetch, or do this with Websocket
55 | setInterval(async () => {
56 | const entries = sync();
57 | await fetch("/patch", { method: "POST", payload: JSON.stringify(entries) });
58 | }, 1000);
59 |
60 | // Undo/redo
61 |
62 | store.undo();
63 | store.redo();
64 | ```
65 |
66 | ## How it works
67 |
68 | ### Containers
69 |
70 | A container is an interface that implements `.get()` and `.set(value)` methods so that a value can be updated and propagated to all consumers.
71 |
72 | You can use anything to create containers, it could be a Redux store, could be an observable, a [nano state](https://github.com/kof/react-nano-state) or [nanostores](https://github.com/nanostores/nanostores).
73 |
74 | You can use the same container instance to subscribe to the changes across the entire application.
75 |
76 | Example using nano state:
77 |
78 | ```js
79 | import { atom } from "nanostores";
80 | import { useStore } from "@nanostores/react";
81 | const myContainer = atom(initialValue);
82 |
83 | // I can call a set from anywhere
84 | myContainer.set(newValue);
85 |
86 | // I can subscribe to updates in React
87 | const Component = () => {
88 | const value = useStore(myContainer);
89 | };
90 | ```
91 |
92 | ### Container registration
93 |
94 | We register containers for two reasons:
95 |
96 | 1. To define a namespace for each container so that whoever consumes the changes knows which object to apply the patches to.
97 | 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.
98 |
99 | Example
100 |
101 | ```js
102 | store.register("myName", myContainer);
103 | ```
104 |
105 | ### Creating a transaction
106 |
107 | A transaction is a set of changes applied to a set of states. When you apply changes to the states inside a transaction, you are essentially telling the engine which changes are associated with the same user action so that undo/redo can use that as a single step to work with.
108 |
109 | A call into `store.createTransaction()`does all of this:
110 |
111 | - generate patches (using Immer)
112 | - update states and inform all subscribers (by calling `container.set(newValue)`)
113 | - register a transaction for potential undo/redo and calls
114 |
115 | Example
116 |
117 | ```js
118 | store.createTransaction(
119 | [container1, container2, ...rest],
120 | (value1, value2, ...rest) => {
121 | mutateValue(value1);
122 | mutateValue(value2);
123 | // ...
124 | }
125 | );
126 | ```
127 |
128 | ### Undo/redo
129 |
130 | Calling undo() and redo() functions will essentially apply the right patch for the value and dispatch the update.
131 |
132 | ### Sync
133 |
134 | The `sync(`) function returns you all changes queued up for a sync since the last call.
135 | With the return from `sync(),` you can do anything you want, for example, send it to your server.
136 |
137 | Example
138 |
139 | ```js
140 | // Setup periodic sync with a fetch, or do this with Websocket
141 | setInterval(async () => {
142 | const entries = sync();
143 | await fetch("/patch", { method: "POST", payload: JSON.stringify(entries) });
144 | }, 1000);
145 | ```
146 |
147 | Example entries:
148 |
149 | ```json
150 | [
151 | {
152 | "transactionId": "6243062b469f516835327f65",
153 | "changes": [
154 | {
155 | "namespace": "root",
156 | "patches": [
157 | {
158 | "op": "replace",
159 | "path": ["children", 1],
160 | "value": {
161 | "component": "Box",
162 | "id": "6241f55791596f2467df9c2a",
163 | "style": {},
164 | "children": []
165 | }
166 | },
167 | {
168 | "op": "replace",
169 | "path": ["children", 2],
170 | "value": {
171 | "component": "Box",
172 | "id": "6241f55a91596f2467df9c36",
173 | "style": {},
174 | "children": []
175 | }
176 | },
177 | {
178 | "op": "replace",
179 | "path": ["children", "length"],
180 | "value": 3
181 | }
182 | ]
183 | }
184 | ]
185 | }
186 | ]
187 | ```
188 |
189 | ## Create a new store
190 |
191 | If you want to have multiple separate undoable states, create a separate store for each. They add to the same sync queue in the end.
192 |
193 | ```js
194 | import { Store } from "immerhin";
195 |
196 | const store = new Store();
197 | ```
198 |
--------------------------------------------------------------------------------
/babel.config.js:
--------------------------------------------------------------------------------
1 | module.exports = {
2 | presets: ["@babel/preset-typescript"],
3 | };
4 |
--------------------------------------------------------------------------------
/examples/react/.gitignore:
--------------------------------------------------------------------------------
1 | .parcel-cache
--------------------------------------------------------------------------------
/examples/react/index.html:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/examples/react/index.js:
--------------------------------------------------------------------------------
1 | import React, { Fragment } from "react";
2 | import { createRoot } from "react-dom/client";
3 | import { atom } from 'nanostores';
4 | import { useStore } from '@nanostores/react'
5 | import store, { sync } from "immerhin";
6 |
7 | const itemsContainer = atom([]);
8 |
9 | store.register("items", itemsContainer);
10 |
11 | const List = () => {
12 | const items = useStore(itemsContainer);
13 | return (
14 |
3 |