docs: add docs for replication

docs/.vitepress/config.mts

@@ -36,9 +36,10 @@ export default defineConfig({
  text: 'Examples',
  collapsed: false,
  items: [
- { text: 'RxDB', link: 'https://signaldb.js.org/examples/rxdb/' },
- { text: 'Firebase', link: 'https://signaldb.js.org/examples/firebase/' },
+ { text: 'HTTP Replication', link: 'https://signaldb.js.org/examples/replication-http/' },
  { text: 'Appwrite', link: 'https://signaldb.js.org/examples/appwrite/' },
+ { text: 'Firebase', link: 'https://signaldb.js.org/examples/firebase/' },
+ { text: 'RxDB', link: 'https://signaldb.js.org/examples/rxdb/' },
  { text: 'Supabase', link: 'https://signaldb.js.org/examples/supabase/' },
  ],
  },
@@ -79,6 +80,18 @@ export default defineConfig({
  { text: 'Other libraries', link: '/reactivity/other/' },
  ],
  },
+ {
+ text: 'Replication',
+ collapsed: false,
+ items: [
+ { text: 'Overview', link: '/replication/' },
+ { text: 'HTTP', link: '/replication/http/' },
+ { text: 'Appwrite', link: '/replication/appwrite/' },
+ { text: 'Firebase', link: '/replication/firebase/' },
+ { text: 'Supabase', link: '/replication/supabase/' },
+ { text: 'Other Replication Options', link: '/replication/other/' },
+ ],
+ },
  {
  text: 'Data Persistence',
  collapsed: false,
@@ -87,19 +100,9 @@ export default defineConfig({
  { text: 'localStorage', link: '/data-persistence/local-storage/' },
  { text: 'Filesystem', link: '/data-persistence/file-system/' },
  { text: 'RxDB', link: '/data-persistence/rxdb/' },
- { text: 'Firebase', link: '/data-persistence/firebase/' },
- { text: 'Appwrite', link: '/data-persistence/appwrite/' },
- { text: 'Supabase', link: '/data-persistence/supabase/' },
  { text: 'Other Persistence Options', link: '/data-persistence/other/' },
  ],
  },
- {
- text: 'Replication (coming soon)',
- collapsed: false,
- items: [
- { text: 'Overview', link: '/replication/' },
- ],
- },
  {
  text: 'Help',
  collapsed: false,

docs/replication/appwrite/index.md

@@ -0,0 +1,15 @@
+---
+head:
+- - link
+ - rel: canonical
+ href: https://signaldb.js.org/replication/appwrite/
+---
+# Integrate SignalDB with [Appwrite](https://appwrite.io/)
+
+Appwrite is a secure end-to-end backend server for Web, Mobile, and Flutter developers that is packaged as a set of Docker containers for easy deployment. Appwrite provides a set of REST APIs that allow you to build complex applications and workflows. It also offers a cloud service that you can use to host your Appwrite server.
+
+SignalDB can be integrated with Appwrite to provide real-time data synchronization across multiple clients.
+
+Checkout our example to learn how to integrate SignalDB with Appwrite: [SignalDB Appwrite Example](/examples/appwrite/)
+
+If you have any questions or need help, feel free to ask a question on [Github](https://github.com/maxnowack/signaldb/discussions).

docs/replication/firebase/index.md

@@ -0,0 +1,15 @@
+---
+head:
+- - link
+ - rel: canonical
+ href: https://signaldb.js.org/replication/firebase/
+---
+# Integrate SignalDB with [Firebase](https://firebase.google.com/)
+
+Firebase is a platform developed by Google for creating mobile and web applications. It provides a variety of services, including a real-time database, cloud storage, authentication, and more.
+
+SignalDB can be integrated with Firebase to provide real-time data synchronization across multiple clients.
+
+Checkout our example to learn how to integrate SignalDB with Firebase: [SignalDB Firebase Example](/examples/firebase/)
+
+If you have any questions or need help, feel free to ask a question on [Github](https://github.com/maxnowack/signaldb/discussions).

docs/replication/http/index.md

@@ -0,0 +1,75 @@
+---
+head:
+- - link
+ - rel: canonical
+ href: https://signaldb.js.org/replication/http/
+---
+# Replicating Data with External HTTP REST API in SignalDB
+
+If you've familiarized yourself with the [Replication Overview](/replication/), you're likely already acquainted with the process of achieving replication using an external HTTP REST API.
+
+This page is dedicated to guiding you through the utilization of your existing HTTP REST API for data replication with SignalDB.
+
+## Setup
+
+To initiate data replication with an external HTTP REST API, you'll first need to create your Collection utilizing the specialized `ReplicatedCollection` class. In the following example, we'll illustrate this process using a straightforward todo list collection.
+
+```js
+const Todos = new ReplicatedCollection({
+ pull: async () => {
+ // We're fetching the todos from the API in the pull method
+ // and returning the items to be added to the collection
+ const items = await fetch('https://api.example.com/todos').then(res => res.json())
+ return { items }
+ },
+ push: async (changes) => {
+ // In the push method, we're sending the changes to the API
+ // We have to differentiate between added, modified, and removed items
+ await Promise.all([
+ // For added items, we're sending a POST request with the item data in the body
+ ...changes.added.map(async (item) => {
+ await fetch('https://api.example.com/todos', {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify({
+ id: item.id,
+ text: item.text,
+ completed: item.completed,
+ }),
+ })
+ }),
+
+ // For modified items, we're sending a PATCH request with the item data in the body
+ // You maybe have to change it to PUT or something else depending on your API
+ ...changes.modified.map(async (item) => {
+ await fetch(`https://api.example.com/todos/${item.id}`, {
+ method: 'PATCH',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify({
+ text: item.text,
+ completed: item.completed,
+ }),
+ })
+ }),
+
+ // For removed items, we're sending a DELETE request
+ ...changes.removed.map(async (item) => {
+ await fetch(`https://api.example.com/todos/${item.id}`, {
+ method: 'DELETE',
+ })
+ }),
+ ])
+ },
+})
+```
+That's it! You've successfully set up a collection that replicates data with an external HTTP REST API.
+
+## Next Steps
+
+Make sure you take a look at our [HTTP Replication Example](/examples/replication-http/) to see a full example of how you can replicate data with an external HTTP REST API.
+
+If you have any questions or need help, feel free to ask a question on [Github](https://github.com/maxnowack/signaldb/discussions).

docs/replication/index.md

@@ -4,13 +4,40 @@ head:
  - rel: canonical
  href: https://signaldb.js.org/replication/
 ---
-# Replication
+# Data Replication in SignalDB
 
-Data replication is a planned feature and not implemented yet. At the moment, data replication can be achieved by using a persistence adapter for Supabase, Appwrite, Firebase or RxDB and using their replication functionality.
+For seamless integration of your app with remote services, SignalDB offers robust data replication capabilities. Whether you're building a local app or sharing data across multiple clients, SignalDB's modular replication system ensures efficient data synchronization.
 
-* [RxDB Persistence Adapter](/data-persistence/rxdb/)
-* [Firebase Persistence Adapter](/data-persistence/firebase/)
-* [Appwrite Persistence Adapter](/data-persistence/appwrite/)
-* [Supabase Persistence Adapter](/data-persistence/supabase/)
+Central to SignalDB's replication functionality is the `ReplicatedCollection` class. This specialized class streamlines the replication process, allowing you to effortlessly replicate data to any remote service.
 
-You can discuss the implementation of replication in the [GitHub issue](https://github.com/maxnowack/signaldb/issues/395).
+The usage of the `ReplicatedCollection` is really simple:
+
+```js
+const Todos = new ReplicatedCollection({
+ pull: async () => {
+ // The pull method is for fetching data from the remote service
+ // similar to the persistence adapters, you have two options to return the fetched data
+
+ // You can return the data directly
+ // return { items: [...] }
+
+ // Or you can return only the changes
+ // return { changes: { added: [...], modified: [...], removed: [...] } }
+ },
+ push: async (changes, items) => {
+ // The push method is called when the local data has changed
+ // As the first parameter you get the changes in the format { added: [...], modified: [...], removed: [...] }
+ // As the second parameter you also get all items in the collection, if you need them
+ // in the push method, no return value is expected
+ },
+ registerRemoteChange: async (onChange) => {
+ // The registerRemoteChange method is for registering a callback that is called when the remote data has changed
+ // The callback takes no parameters. After you called the onChange callback, the pull method is called
+ },
+
+ // You can also optionally specify a persistence adapter
+ // If a persistence adapter is used, the data is loaded first and will be updated after the server data is fetched
+ // If the data will be updated, the data will be saved to the persistence adapter and pushed to the server simultaneously
+ persistence: createLocalStorageAdapter('todos'),
+})
+```

docs/replication/other/index.md

@@ -0,0 +1,14 @@
+---
+head:
+- - link
+ - rel: canonical
+ href: https://signaldb.js.org/replication/other/
+---
+# Other Replication Options
+
+If the provided replication options don't suit your needs, you can always implement your own replication logic. SignalDB provides a flexible API that allows you to create custom replication logic with any external data source. You can take a look at the [`ReplicatedCollection` class](https://github.com/maxnowack/signaldb/blob/main/packages/signaldb/src/ReplicatedCollection.ts) to get started.
+
+Another option is to use the [RxDB Persistence Adapter](/data-persistence/rxdb/), which allows you to use the replication functionality of RxDB together with SignalDB. The replication protocol of RxDB is currently more powerful and maybe fills your needs better.
+
+For guidance on implementing custom replication logic or integrating SignalDB with your backend, don't hesitate to engage with the community on [Github](https://github.com/maxnowack/signaldb/discussions).
+```

docs/replication/supabase/index.md

@@ -0,0 +1,13 @@
+---
+head:
+- - link
+ - rel: canonical
+ href: https://signaldb.js.org/replication/supabase/
+---
+# Integrate SignalDB with [Supabase](https://supabase.io/)
+
+Supabase is an open-source Firebase alternative that provides a variety of services, including a real-time database, authentication, and more. SignalDB can be integrated with Supabase to provide real-time data synchronization across multiple clients.
+
+Checkout our example to learn how to integrate SignalDB with Supabase: [SignalDB Supabase Example](/examples/supabase/)
+
+If you have any questions or need help, feel free to ask a question on [Github](https://github.com/maxnowack/signaldb/discussions).