@automerge/automerge-repo-solid-primitives 2.5.4 → 2.5.6

package/dist/makeDocSignal.d.ts

@@ -0,0 +1,10 @@
+import { Accessor } from 'solid-js';
+import { Doc, DocHandle } from '@automerge/automerge-repo/slim';
+
+/**
+ * a light coarse-grained primitive when you care only _that_ a doc has changed,
+ * and not _how_.
+ * @param handle an Automerge
+ * [DocHandle](https://automerge.org/automerge-repo/classes/_automerge_automerge_repo.DocHandle.html)
+ */
+export default function makeDocSignal<T extends object>(handle: DocHandle<T>): Accessor<Doc<T> | undefined>;

package/dist/useDocSignal.d.ts

@@ -0,0 +1,10 @@
+import { AutomergeUrl, Doc, DocHandle } from '@automerge/automerge-repo/slim';
+import { MaybeAccessor, UseDocHandleOptions } from './types.js';
+import { Accessor, Resource } from 'solid-js';
+
+/**
+ * a light coarse-grained primitive when you care only _that_ a doc has changed,
+ * and not _how_. returns [doc, handle] from a URL.
+ * @param url a function that returns a url
+ */
+export default function useDocSignal<T extends object>(url: MaybeAccessor<AutomergeUrl | undefined>, options?: UseDocHandleOptions): [Accessor<Doc<T> | undefined>, Resource<DocHandle<T> | undefined>];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo-solid-primitives",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "Access Automerge Repo in your SolidJS application",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
   "license": "MIT",
   "devDependencies": {
     "@automerge/automerge": "3.0.0",
-    "@automerge/automerge-repo": "2.5.4",
+    "@automerge/automerge-repo": "2.5.6",
     "@solidjs/testing-library": "^0.8.10",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/user-event": "^14.5.2",
@@ -43,5 +43,5 @@
       ]
     }
   },
-  "gitHead": "70e3703e39f7151dbc446e865d9f9753f132ab3a"
+  "gitHead": "38d06b9d9ef0bbe1e0693d3b859015f38897f34b"
 }

package/readme.md

@@ -75,6 +75,60 @@ const doc = makeDocumentProjection<{ items: { title: string }[] }>(handle)
 return <h1>{doc.items[1].title}</h1>
 ```
 
+## useDocSignal
+
+A light coarse-grained primitive when you care only _that_ a doc has changed,
+and not _how_. Returns `[doc, handle]`.
+
+```ts
+useDocSignal<T>(
+    () => AutomergeURL,
+    options?: {repo: Repo}
+): [Accessor<Doc<T>>, Resource<DocHandle<T>>]
+```
+
+```tsx
+// example
+const [url, setURL] = createSignal<AutomergeUrl>(props.url)
+const [doc, handle] = useDocSignal(url, { repo })
+
+const inc = () => handle()?.change(d => d.count++)
+return <button onclick={inc}>{doc()?.count}</button>
+```
+
+The `{repo}` option can be left out if you are using [RepoContext](#repocontext).
+
+## createDocSignal
+
+A light coarse-grained primitive when you care only _that_ a doc has changed,
+and not _how_. Takes a signal `DocHandle`.
+
+Underlying primitive for [`useDocSignal`](#usedocsignal).
+
+Works with [`useDocHandle`](#usedochandle).
+
+```ts
+createDocSignal<T>(() => DocHandle<T>): Accessor<Doc<T>>
+```
+
+## makeDocSignal
+
+Just like `createDocSignal`, but without a reactive input.
+
+Underlying primitive for [`createDocSignal`](#createdocsignal).
+
+```ts
+makeDocSignal<T>(handle: DocHandle<T>): Accessor<Doc<T>>
+```
+
+```tsx
+// example
+const handle = repo.find(url)
+const doc = makeDocSignal<{ count: number }>(handle)
+
+return <span>{doc()?.count}</span>
+```
+
 ## useDocHandle
 
 Get a [DocHandle](https://automerge.org/docs/repositories/dochandles/) from the

package/src/createDocSignal.ts

@@ -0,0 +1,33 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js"
+import { createSignal } from "solid-js"
+import type { Doc, DocHandle } from "@automerge/automerge-repo/slim"
+
+/**
+ * a light coarse-grained primitive when you care only _that_ a doc has changed,
+ * and not _how_. works with {@link useDocHandle}.
+ * @param handle an accessor (signal/resource) of a
+ * [DocHandle](https://automerge.org/automerge-repo/classes/_automerge_automerge_repo.DocHandle.html)
+ */
+export default function createDocSignal<T extends object>(
+  handle: Accessor<DocHandle<T> | undefined>
+): Accessor<Doc<T> | undefined> {
+  const [signal, setSignal] = createSignal<Doc<T> | undefined>(handle()?.doc())
+
+  createEffect(() => {
+    const h = handle()
+
+    function update() {
+      setSignal(() => h?.doc() as Doc<T> | undefined)
+    }
+
+    // sync the signal with the current handle's doc
+    update()
+
+    if (h) {
+      h.on("change", update)
+      onCleanup(() => h.off("change", update))
+    }
+  })
+
+  return signal
+}

package/src/index.ts

@@ -3,5 +3,8 @@ export { default as useDocument } from "./useDocument.js"
 export { default as useDocHandle } from "./useDocHandle.js"
 export { default as makeDocumentProjection } from "./makeDocumentProjection.js"
 export { default as createDocumentProjection } from "./createDocumentProjection.js"
+export { default as makeDocSignal } from "./makeDocSignal.js"
+export { default as createDocSignal } from "./createDocSignal.js"
+export { default as useDocSignal } from "./useDocSignal.js"
 export { default as useRepo } from "./useRepo.js"
 export { RepoContext } from "./context.js"

package/src/makeDocSignal.ts

@@ -0,0 +1,24 @@
+import { onCleanup, type Accessor } from "solid-js"
+import { createSignal } from "solid-js"
+import type { Doc, DocHandle } from "@automerge/automerge-repo/slim"
+
+/**
+ * a light coarse-grained primitive when you care only _that_ a doc has changed,
+ * and not _how_.
+ * @param handle an Automerge
+ * [DocHandle](https://automerge.org/automerge-repo/classes/_automerge_automerge_repo.DocHandle.html)
+ */
+export default function makeDocSignal<T extends object>(
+  handle: DocHandle<T>
+): Accessor<Doc<T> | undefined> {
+  const [signal, setSignal] = createSignal<Doc<T> | undefined>(handle.doc())
+
+  function update() {
+    setSignal(() => handle.doc() as Doc<T> | undefined)
+  }
+
+  handle.on("change", update)
+  onCleanup(() => handle.off("change", update))
+
+  return signal
+}

package/src/useDocSignal.ts

@@ -0,0 +1,22 @@
+import type {
+  AutomergeUrl,
+  Doc,
+  DocHandle,
+} from "@automerge/automerge-repo/slim"
+import useDocHandle from "./useDocHandle.js"
+import createDocSignal from "./createDocSignal.js"
+import type { MaybeAccessor, UseDocHandleOptions } from "./types.js"
+import type { Accessor, Resource } from "solid-js"
+
+/**
+ * a light coarse-grained primitive when you care only _that_ a doc has changed,
+ * and not _how_. returns [doc, handle] from a URL.
+ * @param url a function that returns a url
+ */
+export default function useDocSignal<T extends object>(
+  url: MaybeAccessor<AutomergeUrl | undefined>,
+  options?: UseDocHandleOptions
+): [Accessor<Doc<T> | undefined>, Resource<DocHandle<T> | undefined>] {
+  const handle = useDocHandle<T>(url, options)
+  return [createDocSignal<T>(handle), handle] as const
+}

package/test/useDocSignal.test.tsx

@@ -0,0 +1,302 @@
+import { type PeerId, Repo, type AutomergeUrl } from "@automerge/automerge-repo"
+import { renderHook, testEffect } from "@solidjs/testing-library"
+import { describe, expect, it, vi } from "vitest"
+import { RepoContext } from "../src/context.js"
+import { createEffect, createSignal, type ParentComponent } from "solid-js"
+import useDocSignal from "../src/useDocSignal.js"
+
+interface ExampleDoc {
+  key: string
+  array: number[]
+  nested: { title: string }
+}
+
+describe("useDocSignal", () => {
+  function setup() {
+    const repo = new Repo({
+      peerId: "bob" as PeerId,
+    })
+
+    const create = () =>
+      repo.create<ExampleDoc>({
+        key: "value",
+        array: [1, 2, 3],
+        nested: { title: "hello" },
+      })
+
+    const wrapper: ParentComponent = props => {
+      return (
+        <RepoContext.Provider value={repo}>
+          {props.children}
+        </RepoContext.Provider>
+      )
+    }
+
+    return {
+      repo,
+      wrapper,
+      create,
+      options: { repo },
+    }
+  }
+
+  it("should return the initial document value", async () => {
+    const { create, options } = setup()
+
+    await testEffect(done => {
+      const [doc] = useDocSignal<ExampleDoc>(create().url, options)
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()?.key).toBe("value")
+          done()
+        }
+        return run + 1
+      })
+    })
+  })
+
+  it("should notify on a property change", async () => {
+    const { create, options } = setup()
+
+    await testEffect(done => {
+      const [doc, handle] = useDocSignal<ExampleDoc>(create().url, options)
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()?.key).toBe("value")
+          handle()?.change(doc => (doc.key = "hello world!"))
+        } else if (run == 1) {
+          expect(doc()?.key).toBe("hello world!")
+          handle()?.change(doc => (doc.key = "friday night!"))
+        } else if (run == 2) {
+          expect(doc()?.key).toBe("friday night!")
+          done()
+        }
+        return run + 1
+      })
+    })
+  })
+
+  it("should return the handle as the second element", async () => {
+    const { create, options } = setup()
+    const created = create()
+
+    await testEffect(done => {
+      const [, handle] = useDocSignal<ExampleDoc>(created.url, options)
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(handle()).not.toBe(undefined)
+          expect(handle()?.url).toBe(created.url)
+          done()
+        }
+        return run + 1
+      })
+    })
+  })
+
+  it("should update when an array element changes", async () => {
+    const { create, options } = setup()
+
+    await testEffect(done => {
+      const [doc, handle] = useDocSignal<ExampleDoc>(create().url, options)
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()?.array).toEqual([1, 2, 3])
+          handle()?.change(doc => doc.array.push(4))
+        } else if (run == 1) {
+          expect(doc()?.array).toEqual([1, 2, 3, 4])
+          done()
+        }
+        return run + 1
+      })
+    })
+  })
+
+  it("should update when a nested property changes", async () => {
+    const { create, options } = setup()
+
+    await testEffect(done => {
+      const [doc, handle] = useDocSignal<ExampleDoc>(create().url, options)
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()?.nested.title).toBe("hello")
+          handle()?.change(doc => (doc.nested.title = "world"))
+        } else if (run == 1) {
+          expect(doc()?.nested.title).toBe("world")
+          done()
+        }
+        return run + 1
+      })
+    })
+  })
+
+  it("should work with a signal url", async () => {
+    const { create, wrapper } = setup()
+    const [url, setURL] = createSignal<AutomergeUrl>()
+    const {
+      result: [doc, handle],
+      owner,
+    } = renderHook(useDocSignal<ExampleDoc>, {
+      initialProps: [url],
+      wrapper,
+    })
+
+    const done = testEffect(done => {
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()).toBeUndefined()
+          setURL(create().url)
+        } else if (run == 1) {
+          expect(doc()?.key).toBe("value")
+          handle()?.change(doc => (doc.key = "hello world!"))
+        } else if (run == 2) {
+          expect(doc()?.key).toBe("hello world!")
+          setURL(create().url)
+        } else if (run == 3) {
+          expect(doc()?.key).toBe("value")
+          done()
+        }
+        return run + 1
+      })
+    }, owner!)
+    return done
+  })
+
+  it("should clear the signal when the url returns to nothing", async () => {
+    const { create, options } = setup()
+    const [url, setURL] = createSignal<AutomergeUrl>()
+
+    const done = testEffect(done => {
+      const [doc, handle] = useDocSignal<ExampleDoc>(url, options)
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(handle()).toBe(undefined)
+          setURL(create().url)
+        } else if (run == 1) {
+          expect(doc()?.key).toBe("value")
+          expect(handle()).not.toBe(undefined)
+          setURL(undefined)
+        } else if (run == 2) {
+          expect(handle()).toBe(undefined)
+          setURL(create().url)
+        } else if (run == 3) {
+          expect(doc()?.key).toBe("value")
+          expect(handle()).not.toBe(undefined)
+          done()
+        }
+        return run + 1
+      })
+    })
+    return done
+  })
+
+  it("should work without a context if given a repo in options", async () => {
+    const { create, repo } = setup()
+
+    await testEffect(done => {
+      const [doc] = useDocSignal<ExampleDoc>(create().url, { repo })
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()?.key).toBe("value")
+          done()
+        }
+        return run + 1
+      })
+    })
+  })
+
+  it("should be coarse-grained: any change triggers re-read of the whole doc", async () => {
+    const { create, options } = setup()
+
+    const signalFn = vi.fn()
+
+    await testEffect(done => {
+      const [doc, handle] = useDocSignal<ExampleDoc>(create().url, options)
+      createEffect((run: number = 0) => {
+        signalFn(doc()?.key, doc()?.array)
+        if (run == 0) {
+          expect(doc()?.key).toBe("value")
+          expect(doc()?.array).toEqual([1, 2, 3])
+          // Change only the array — should still trigger the signal
+          handle()?.change(doc => doc.array.push(4))
+        } else if (run == 1) {
+          // The whole doc is refreshed, so we see the array change
+          expect(doc()?.array).toEqual([1, 2, 3, 4])
+          // key remains unchanged
+          expect(doc()?.key).toBe("value")
+          // Now change only the key
+          handle()?.change(doc => (doc.key = "updated"))
+        } else if (run == 2) {
+          expect(doc()?.key).toBe("updated")
+          expect(doc()?.array).toEqual([1, 2, 3, 4])
+          done()
+        }
+        return run + 1
+      })
+    })
+
+    // The signal callback should have been called 3 times (once per run)
+    expect(signalFn).toHaveBeenCalledTimes(3)
+  })
+
+  it("should work with a slow handle", async () => {
+    const { repo } = setup()
+
+    const slowHandle = repo.create({
+      key: "slow",
+      array: [],
+      nested: { title: "slow" },
+    })
+    const originalFind = repo.find.bind(repo)
+    repo.find = vi.fn().mockImplementation(async (...args) => {
+      await new Promise(resolve => setTimeout(resolve, 100))
+      // @ts-expect-error i'm ok i promise
+      return await originalFind(...args)
+    })
+
+    const done = testEffect(done => {
+      const [doc] = useDocSignal<ExampleDoc>(() => slowHandle.url, {
+        repo,
+        "~skipInitialValue": true,
+      })
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()?.key).toBeUndefined()
+        } else if (run == 1) {
+          expect(doc()?.key).toBe("slow")
+          done()
+        }
+        return run + 1
+      })
+    })
+    repo.find = originalFind
+    return done
+  })
+
+  it("should not apply updates from a previous handle after url changes", async () => {
+    const { create, options } = setup()
+    const h1 = create()
+    const h2 = create()
+
+    const [url, setURL] = createSignal<AutomergeUrl>(h1.url)
+
+    const done = testEffect(done => {
+      const [doc, handle] = useDocSignal<ExampleDoc>(url, options)
+      createEffect((run: number = 0) => {
+        if (run == 0) {
+          expect(doc()?.key).toBe("value")
+          // Switch to h2
+          setURL(h2.url)
+        } else if (run == 1) {
+          expect(doc()?.key).toBe("value")
+          // Change h2
+          handle()?.change(doc => (doc.key = "from h2"))
+        } else if (run == 2) {
+          expect(doc()?.key).toBe("from h2")
+          done()
+        }
+        return run + 1
+      })
+    })
+    return done
+  })
+})