@automerge/automerge-repo-svelte-store 2.0.0-beta.5 → 2.0.0-beta.6

package/README.md

@@ -1,54 +1,204 @@
 # Svelte store for Automerge Repo
 
+A reactive Svelte store for Automerge documents. Compatible with Svelte 3, 4, and 5.
+
+## Installation
+
+```bash
+npm install @automerge/automerge-repo-svelte-store
+```
+
 ## Example Usage
 
-For a working example, see the [Svelte counter demo](../automerge-repo-demo-counter-svelte/).
+### Basic Usage
+
+```svelte
+<script>
+  import { Repo } from "@automerge/automerge-repo"
+  import { createAutomergeStore } from "@automerge/automerge-repo-svelte-store"
 
-`App.svelte`
+  // Create a repo
+  const repo = new Repo({
+    // Configuration...
+  })
+
+  // Create a store from the repo
+  const automergeStore = createAutomergeStore(repo)
+
+  // Load or create a document
+  let documentStore = null
+
+  async function loadDocument(url) {
+    documentStore = await automergeStore.find(url)
+  }
+
+  async function createDocument() {
+    documentStore = await automergeStore.create({ count: 0 })
+  }
+
+  // Update the document
+  function incrementCounter() {
+    if (documentStore) {
+      documentStore.change(doc => {
+        doc.count = (doc.count || 0) + 1
+      })
+    }
+  }
+</script>
+```
+
+### Using with Svelte Context (recommended)
 
 ```svelte
-<script lang="ts">
+<!-- App.svelte -->
+<script>
   import { Repo } from "@automerge/automerge-repo"
-  import Counter from './lib/Counter.svelte'
   import { setContextRepo } from "@automerge/automerge-repo-svelte-store"
+  import Counter from './Counter.svelte'
 
-  const repo = new Repo({ /* repo config */ })
+  const repo = new Repo({
+    // Configuration...
+  })
 
-  // Make the `Repo` available to child components (via Svelte's `setContext`).
+  // Make repo available to child components
   setContextRepo(repo)
 
-  const docId = repo.create()
+  // Create a document asynchronously
+  let docUrl = null
+
+  async function setupDoc() {
+    const handle = await repo.create({ count: 0 })
+    docUrl = handle.url
+  }
+
+  setupDoc()
 </script>
 
-<main>
-  <div class="card">
-    <Counter {docId}/>
-  </div>
-</main>
+{#if docUrl}
+  <Counter {docUrl} />
+{:else}
+  <p>Creating document...</p>
+{/if}
 ```
 
-`Counter.svelte`
+```svelte
+<!-- Counter.svelte -->
+<script>
+  import { document } from "@automerge/automerge-repo-svelte-store"
+  import { onMount } from "svelte"
+
+  export let docUrl
+
+  // The document store - initially null
+  let docStore = null
+
+  // Load the document on mount
+  onMount(async () => {
+    // document() is async and returns a Promise
+    docStore = await document(docUrl)
+  })
+
+  function increment() {
+    if (!docStore) return
+
+    // Access the document using the Svelte store $ syntax
+    docStore.change(doc => {
+      doc.count = (doc.count || 0) + 1
+    })
+  }
+</script>
+
+{#if docStore}
+  <button on:click={increment}>
+    Count: {$docStore.count || 0}
+  </button>
+{:else}
+  <p>Loading document...</p>
+{/if}
+```
+
+### Using with Svelte 5 Runes
+
+With Svelte 5, you can use the store with runes syntax for a more ergonomic experience:
 
 ```svelte
-<script lang="ts">
-  import type { DocumentId } from "@automerge/automerge-repo"
+<script>
   import { document } from "@automerge/automerge-repo-svelte-store"
 
-  export let docId: DocumentId
+  export let docUrl
+
+  // Initialize state
+  let docStore = $state(null)
+  let loading = $state(true)
+  let error = $state(null)
+  let count = $derived(docStore?.$doc?.count || 0)
+
+  // Load document when component initializes
+  $effect(() => {
+    async function loadDocument() {
+      try {
+        loading = true
+        docStore = await document(docUrl)
+        loading = false
+      } catch (err) {
+        console.error("Failed to load document:", err)
+        error = err
+        loading = false
+      }
+    }
+
+    loadDocument()
+  })
 
-  // `document` calls `getContextRepo` internally to access the closest `Repo`.
-  // alternatively, you may pass in a specific repo as the second parameter
-  const doc = document<{count?: number}>(docId)
-  const increment = () => {
-    doc.change((d) => d.count = (d.count || 0) + 1)
+  function increment() {
+    if (docStore) {
+      docStore.change(doc => {
+        doc.count = (doc.count || 0) + 1
+      })
+    }
   }
 </script>
 
-<button on:click={increment}>
-  count is {$doc?.count || 0}
-</button>
+{#if loading}
+  <p>Loading document...</p>
+{:else if error}
+  <p>Error: {error.message}</p>
+{:else}
+  <button on:click={increment}>
+    Count: {count}
+  </button>
+{/if}
 ```
 
+## API Reference
+
+### `createAutomergeStore(repo)`
+
+Creates an Automerge store factory from a repo instance.
+
+### `setContextRepo(repo)`
+
+Sets the Automerge repo in the current component's context.
+
+### `getContextRepo()`
+
+Gets the Automerge repo from the current component's context.
+
+### `document(docIdOrUrl, repoInstance?)`
+
+Convenience method to load a document from the repo in context or a provided repo.
+**Important:** This function returns a Promise that resolves to the document store.
+
+## Store API
+
+The document store returned by `find()` and `create()` implements Svelte's writable store contract with these additional methods:
+
+- `change(fn)`: Make changes to the document
+- `url`: Get the document URL
+- `documentId`: Get the document ID
+- `handle`: Access the underlying Automerge document handle
+
 ## Contributors
 
-Originally written by Dylan MacKenzie ([@ecstatic-morse](https://github.com/ecstatic-morse)).
+Originally written by Dylan MacKenzie (@ecstatic-morse).
+Updated for Svelte 5 compatibility by the Automerge team.

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import type { AutomergeUrl, ChangeFn, Doc, DocHandle, DocumentId, Repo } from "@automerge/automerge-repo/slim";
+import { type Writable } from "svelte/store";
+/**
+ * Set the Automerge Repo in the Svelte context
+ * @param repo The Automerge Repo instance
+ */
+export declare function setContextRepo(repo: Repo): void;
+/**
+ * Get the Automerge Repo from the Svelte context
+ * @returns The Automerge Repo instance
+ */
+export declare function getContextRepo(): Repo;
+/**
+ * The Automerge document store interface
+ */
+export interface AutomergeDocumentStore<T> extends Writable<Doc<T> | null> {
+    /**
+     * Make changes to the document
+     * @param changeFn Function that modifies the document
+     */
+    change(changeFn: ChangeFn<T>): void;
+    /**
+     * The URL of the document
+     */
+    readonly url: AutomergeUrl;
+    /**
+     * The ID of the document
+     */
+    readonly documentId: DocumentId;
+    /**
+     * The underlying Automerge document handle
+     */
+    readonly handle: DocHandle<T>;
+}
+/**
+ * Creates an Automerge-repo store using standard Svelte stores
+ * @param repo A configured Automerge Repo instance
+ * @returns API for interacting with Automerge-repo
+ */
+export declare function createAutomergeStore(repo: Repo): {
+    find: <T>(automergeUrl: AutomergeUrl) => Promise<AutomergeDocumentStore<T> | null>;
+    create: <T>(initialContent?: any) => Promise<AutomergeDocumentStore<T>>;
+    delete: (automergeUrl: AutomergeUrl) => Promise<void>;
+    getRepo: () => Repo;
+};
+/**
+ * Create a document store from a document ID or URL
+ * Uses the repo from context if no repo is provided
+ * @param docIdOrUrl The document ID or URL
+ * @param repoInstance Optional Automerge Repo instance
+ * @returns A promise resolving to the document store
+ */
+export declare function document<T>(docIdOrUrl: DocumentId | AutomergeUrl, repoInstance?: Repo): Promise<AutomergeDocumentStore<T> | null>;

package/dist/index.js

@@ -0,0 +1,112 @@
+import { getContext, setContext } from "svelte";
+import { writable } from "svelte/store";
+// Store the repo in context for easy access
+const REPO_CONTEXT_KEY = Symbol("automerge-repo");
+/**
+ * Set the Automerge Repo in the Svelte context
+ * @param repo The Automerge Repo instance
+ */
+export function setContextRepo(repo) {
+    setContext(REPO_CONTEXT_KEY, repo);
+}
+/**
+ * Get the Automerge Repo from the Svelte context
+ * @returns The Automerge Repo instance
+ */
+export function getContextRepo() {
+    const repo = getContext(REPO_CONTEXT_KEY);
+    if (!repo) {
+        throw new Error("No Automerge Repo found in context. Did you call setContextRepo?");
+    }
+    return repo;
+}
+/**
+ * Creates an Automerge-repo store using standard Svelte stores
+ * @param repo A configured Automerge Repo instance
+ * @returns API for interacting with Automerge-repo
+ */
+export function createAutomergeStore(repo) {
+    if (!repo) {
+        throw new Error("A Repo instance is required");
+    }
+    /**
+     * Find a document by URL and create a reactive wrapper
+     */
+    const find = async (automergeUrl) => {
+        const handle = await repo.find(automergeUrl);
+        if (!handle)
+            return null;
+        return createDocumentStore(handle);
+    };
+    /**
+     * Create a new document and wrap it with reactive state
+     */
+    const create = async (initialContent = {}) => {
+        const handle = await repo.create(initialContent);
+        return createDocumentStore(handle);
+    };
+    /**
+     * Delete a document
+     */
+    const deleteDocument = async (automergeUrl) => {
+        repo.delete(automergeUrl);
+    };
+    /**
+     * Create a reactive document store for a handle
+     */
+    function createDocumentStore(handle) {
+        // Create a writable store with the current document
+        const { subscribe, set } = writable(handle.doc());
+        // Set up change listener
+        const onChange = ({ doc }) => {
+            set(doc);
+        };
+        // Subscribe to changes
+        handle.on("change", onChange);
+        // Create the store implementation
+        const store = {
+            subscribe,
+            set,
+            update: updater => {
+                const currentDoc = handle.doc();
+                const newValue = updater(currentDoc);
+                set(newValue);
+            },
+            // Method to make changes to the document
+            change(changeFn) {
+                return handle.change(changeFn);
+            },
+            // Metadata accessors
+            get url() {
+                return handle.url;
+            },
+            get documentId() {
+                return handle.documentId;
+            },
+            // Access to the underlying handle
+            get handle() {
+                return handle;
+            },
+        };
+        return store;
+    }
+    // Return the store API
+    return {
+        find,
+        create,
+        delete: deleteDocument,
+        getRepo: () => repo,
+    };
+}
+/**
+ * Create a document store from a document ID or URL
+ * Uses the repo from context if no repo is provided
+ * @param docIdOrUrl The document ID or URL
+ * @param repoInstance Optional Automerge Repo instance
+ * @returns A promise resolving to the document store
+ */
+export function document(docIdOrUrl, repoInstance) {
+    const repo = repoInstance || getContextRepo();
+    const store = createAutomergeStore(repo);
+    return store.find(docIdOrUrl);
+}

package/package.json

@@ -1,21 +1,35 @@
 {
   "name": "@automerge/automerge-repo-svelte-store",
-  "version": "2.0.0-beta.5",
+  "version": "2.0.0-beta.6",
   "description": "A Svelte store containing your automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo-svelte-store",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "svelte": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
-    "build": "",
-    "watch": "npm-watch build"
+    "build": "svelte-package",
+    "watch": "svelte-package --watch"
   },
   "peerDependencies": {
-    "@automerge/automerge": "^2.2.8",
-    "svelte": "^3.0.0 || ^4.0.0"
+    "svelte": "^3.0.0 || ^4.0.0 || ^5.0.0"
   },
   "dependencies": {
-    "@automerge/automerge-repo": "2.0.0-beta.5"
+    "@automerge/automerge-repo": "2.0.0-beta.6"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.11",
+    "typescript": "^5.0.0"
   },
   "watch": {
     "build": {
@@ -28,5 +42,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "0a1f8195dbe0a84c21611c5f58003b68f35b9dc1"
+  "gitHead": "5f68e5e1bb41c5953d2024df2454becf755c38b8"
 }

package/src/lib/index.ts

@@ -0,0 +1,175 @@
+import type {
+  AutomergeUrl,
+  ChangeFn,
+  Doc,
+  DocHandle,
+  DocumentId,
+  Repo,
+} from "@automerge/automerge-repo/slim"
+
+import { getContext, setContext } from "svelte"
+import { writable, type Writable } from "svelte/store"
+
+// Store the repo in context for easy access
+const REPO_CONTEXT_KEY = Symbol("automerge-repo")
+
+/**
+ * Set the Automerge Repo in the Svelte context
+ * @param repo The Automerge Repo instance
+ */
+export function setContextRepo(repo: Repo): void {
+  setContext(REPO_CONTEXT_KEY, repo)
+}
+
+/**
+ * Get the Automerge Repo from the Svelte context
+ * @returns The Automerge Repo instance
+ */
+export function getContextRepo(): Repo {
+  const repo = getContext<Repo>(REPO_CONTEXT_KEY)
+  if (!repo) {
+    throw new Error(
+      "No Automerge Repo found in context. Did you call setContextRepo?"
+    )
+  }
+  return repo
+}
+
+/**
+ * The Automerge document store interface
+ */
+export interface AutomergeDocumentStore<T> extends Writable<Doc<T> | null> {
+  /**
+   * Make changes to the document
+   * @param changeFn Function that modifies the document
+   */
+  change(changeFn: ChangeFn<T>): void
+
+  /**
+   * The URL of the document
+   */
+  readonly url: AutomergeUrl
+
+  /**
+   * The ID of the document
+   */
+  readonly documentId: DocumentId
+
+  /**
+   * The underlying Automerge document handle
+   */
+  readonly handle: DocHandle<T>
+}
+
+/**
+ * Creates an Automerge-repo store using standard Svelte stores
+ * @param repo A configured Automerge Repo instance
+ * @returns API for interacting with Automerge-repo
+ */
+export function createAutomergeStore(repo: Repo) {
+  if (!repo) {
+    throw new Error("A Repo instance is required")
+  }
+
+  /**
+   * Find a document by URL and create a reactive wrapper
+   */
+  const find = async <T>(
+    automergeUrl: AutomergeUrl
+  ): Promise<AutomergeDocumentStore<T> | null> => {
+    const handle = await repo.find<T>(automergeUrl)
+    if (!handle) return null
+    return createDocumentStore<T>(handle)
+  }
+
+  /**
+   * Create a new document and wrap it with reactive state
+   */
+  const create = async <T>(
+    initialContent: any = {}
+  ): Promise<AutomergeDocumentStore<T>> => {
+    const handle = await repo.create<T>(initialContent)
+    return createDocumentStore<T>(handle)
+  }
+
+  /**
+   * Delete a document
+   */
+  const deleteDocument = async (automergeUrl: AutomergeUrl) => {
+    repo.delete(automergeUrl)
+  }
+
+  /**
+   * Create a reactive document store for a handle
+   */
+  function createDocumentStore<T>(
+    handle: DocHandle<T>
+  ): AutomergeDocumentStore<T> {
+    // Create a writable store with the current document
+    const { subscribe, set } = writable<Doc<T> | null>(handle.doc())
+
+    // Set up change listener
+    const onChange = ({ doc }: { doc: Doc<T> }) => {
+      set(doc)
+    }
+
+    // Subscribe to changes
+    handle.on("change", onChange)
+
+    // Create the store implementation
+    const store: AutomergeDocumentStore<T> = {
+      subscribe,
+      set,
+      update: updater => {
+        const currentDoc = handle.doc()
+        const newValue = updater(currentDoc)
+        set(newValue)
+      },
+
+      // Method to make changes to the document
+      change(changeFn: ChangeFn<T>) {
+        return handle.change(changeFn)
+      },
+
+      // Metadata accessors
+      get url() {
+        return handle.url
+      },
+
+      get documentId() {
+        return handle.documentId
+      },
+
+      // Access to the underlying handle
+      get handle() {
+        return handle
+      },
+    }
+
+    return store
+  }
+
+  // Return the store API
+  return {
+    find,
+    create,
+    delete: deleteDocument,
+    getRepo: () => repo,
+  }
+}
+
+/**
+ * Create a document store from a document ID or URL
+ * Uses the repo from context if no repo is provided
+ * @param docIdOrUrl The document ID or URL
+ * @param repoInstance Optional Automerge Repo instance
+ * @returns A promise resolving to the document store
+ */
+export function document<T>(
+  docIdOrUrl: DocumentId | AutomergeUrl,
+  repoInstance?: Repo
+): Promise<AutomergeDocumentStore<T> | null> {
+  const repo = repoInstance || getContextRepo()
+  const store = createAutomergeStore(repo)
+  return store.find<T>(docIdOrUrl as AutomergeUrl)
+}

package/src/index.ts

@@ -1,102 +0,0 @@
-/**
- * # Svelte store for Automerge Repo
- *
- * ## Example Usage
- *
- * For a working example, see the [Svelte counter demo](../automerge-repo-demo-counter-svelte/).
- *
- * @example
- *
- * ```svelte
- * // App.svelte
- * <script lang="ts">
- *   import { Repo } from "@automerge/automerge-repo"
- *   import Counter from './lib/Counter.svelte'
- *   import { setContextRepo } from "@automerge/automerge-repo-svelte-store"
- *
- *   const repo = new Repo({storage: new SomeStorage() })
- *
- *   // Make the `Repo` available to child components (via Svelte's `setContext`).
- *   setContextRepo(repo)
- *
- *   const docId = repo.create()
- * </script>
- *
- * <main>
- *   <div class="card">
- *     <Counter {docId}/>
- *   </div>
- * </main>
- * ```
- *
- *
- * ```svelte
- * // Counter.svelte`
- * <script lang="ts">
- *   import type { DocumentId } from "@automerge/automerge-repo"
- *   import { document } from "@automerge/automerge-repo-svelte-store"
- *
- *   export let docId: DocumentId
- *
- *   // `document` calls `getContextRepo` internally to access the closest `Repo`.
- *   // alternatively, you may pass in a specific repo as the second parameter
- *   const doc = document<{count?: number}>(docId)
- *   const increment = () => {
- *     doc.change((d) => d.count = (d.count || 0) + 1)
- *   }
- * </script>
- *
- * <button on:click={increment}>
- *   count is {$doc?.count || 0}
- * </button>
- * ```
- *
- * ## Contributors
- * Originally written by Dylan MacKenzie ([@ecstatic-morse](https://github.com/ecstatic-morse)).
- *  * @packageDocumentation
- **/
-
-import type { ChangeFn, Doc } from "@automerge/automerge/slim/next"
-import {
-  AutomergeUrl,
-  DocHandleChangePayload,
-  Repo,
-} from "@automerge/automerge-repo/slim"
-import { getContext, setContext } from "svelte"
-import { writable } from "svelte/store"
-
-const ContextRepoKey = Symbol("svelte-context-automerge-repo")
-
-export function getContextRepo(): Repo {
-  return getContext<Repo>(ContextRepoKey)
-}
-
-export function setContextRepo(repo: Repo) {
-  setContext(ContextRepoKey, repo)
-}
-
-/**
- *  A Svelte store for an Automerge document.
- *
- *  @param {AutomergeUrl} documentId - The Automerge document ID
- *  @param {Repo=} repo - (Optional) The Automerge repo to use. If not provided, the repo will be retrieved from context.
- *
- *  @returns A Svelte store for the Automerge document.
- */
-
-export function document<T>(documentId: AutomergeUrl, repo?: Repo) {
-  repo = repo ?? getContextRepo()
-  const handle = repo.find<T>(documentId)
-  const { set, subscribe } = writable<Doc<T>>(handle.doc(), () => {
-    const onChange = (h: DocHandleChangePayload<T>) => set(h.doc)
-    handle.addListener("change", onChange)
-    return () => handle.removeListener("change", onChange)
-  })
-
-  return {
-    subscribe,
-    change: (fn: ChangeFn<T>) => {
-      handle.change(fn)
-    },
-  }
-}

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "jsx": "react",
-    "module": "NodeNext",
-    "moduleResolution": "Node16",
-    "declaration": true,
-    "declarationMap": true,
-    "outDir": "./dist",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": true
-  },
-  "include": ["src/**/*.ts"]
-}

package/typedoc.json

@@ -1,5 +0,0 @@
-{
-  "extends": ["../../typedoc.base.json"],
-  "entryPoints": ["src/index.ts"],
-  "readme": "none"
-}