@automerge/automerge-repo-solid-primitives 2.2.0

package/dist/makeDocumentProjection.d.ts

@@ -0,0 +1,8 @@
+import { Doc, DocHandle } from '@automerge/automerge-repo/slim';
+
+/**
+ * make a fine-grained live view of a document from its handle.
+ * @param handle an Automerge
+ * [DocHandle](https://automerge.org/automerge-repo/classes/_automerge_automerge_repo.DocHandle.html)
+ */
+export default function makeDocumentProjection<T extends object>(handle: DocHandle<T>): Doc<T>;

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import { Repo } from '@automerge/automerge-repo/slim';
+
+export interface UseDocHandleOptions {
+    repo?: Repo;
+    "~skipInitialValue"?: boolean;
+}
+export type MaybeAccessor<T> = T | (() => T);

package/dist/useDocHandle.d.ts

@@ -0,0 +1,15 @@
+import { AutomergeUrl, DocHandle } from '@automerge/automerge-repo/slim';
+import { Resource } from 'solid-js';
+import { MaybeAccessor, UseDocHandleOptions } from './types.js';
+
+/**
+ * get a
+ * [DocHandle](https://automerge.org/automerge-repo/classes/_automerge_automerge_repo.DocHandle.html)
+ * from an
+ * [AutomergeUrl](https://automerge.org/automerge-repo/types/_automerge_automerge_repo.AutomergeUrl.html)
+ * as a
+ * [Resource](https://docs.solidjs.com/reference/basic-reactivity/create-resource).
+ * Waits for the handle to be
+ * [ready](https://automerge.org/automerge-repo/variables/_automerge_automerge_repo.HandleState-1.html).
+ */
+export default function useDocHandle<T>(url: MaybeAccessor<AutomergeUrl | undefined>, options?: UseDocHandleOptions): Resource<DocHandle<T> | undefined>;

package/dist/useDocument.d.ts

@@ -0,0 +1,9 @@
+import { AutomergeUrl, Doc, DocHandle } from '@automerge/automerge-repo/slim';
+import { MaybeAccessor, UseDocHandleOptions } from './types.js';
+import { Accessor, Resource } from 'solid-js';
+
+/**
+ * get a fine-grained live view of a document, and its handle, from a URL.
+ * @param url a function that returns a url
+ */
+export default function useDocument<T extends object>(url: MaybeAccessor<AutomergeUrl | undefined>, options?: UseDocHandleOptions): [Accessor<Doc<T> | undefined>, Resource<DocHandle<T> | undefined>];

package/dist/useRepo.d.ts

@@ -0,0 +1,4 @@
+import { Repo } from '@automerge/automerge-repo/slim';
+
+/** grab the repo from the {@link RepoContext} */
+export default function useRepo(): Repo;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@automerge/automerge-repo-solid-primitives",
+  "version": "2.2.0",
+  "description": "Access Automerge Repo in your SolidJS application",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc --noEmit && vite build",
+    "test": "vitest run",
+    "watch": "npm-watch build",
+    "visualize": "VISUALIZE=true vite build"
+  },
+  "author": "chee <chee@rabbits.computer>",
+  "license": "MIT",
+  "devDependencies": {
+    "@automerge/automerge": "3.0.0",
+    "@automerge/automerge-repo": "2.2.0",
+    "@solidjs/testing-library": "^0.8.9",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/user-event": "^14.5.2",
+    "rollup-plugin-visualizer": "^5.9.3",
+    "solid-js": "^1.9.4",
+    "vite-plugin-dts": "^3.9.1",
+    "vite-plugin-solid": "^2.11.0"
+  },
+  "peerDependencies": {
+    "@automerge/automerge": "3.0.0",
+    "solid-js": "^1.9.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/automerge/automerge-repo.git"
+  },
+  "homepage": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo-solid-primitives",
+  "publishConfig": {
+    "access": "public"
+  },
+  "watch": {
+    "build": {
+      "patterns": "./src/**/*",
+      "extensions": [
+        ".ts"
+      ]
+    }
+  },
+  "gitHead": "0eab1c635365712017d7ccc000e7cd92f14e7143"
+}

package/readme.md

@@ -0,0 +1,139 @@
+# Solid Automerge
+
+<a href="https://www.solidjs.com/"> <img alt="" src=.assets/solid.png width=22
+height=22> Solid </a> primitives for <a
+href="https://automerge.org/docs/repositories/"> <img alt=""
+src=.assets/automerge.png width=22 height=22>Automerge</a> .
+
+```sh
+pnpm add solidjs @automerge/automerge-repo
+pnpm add solid-automerge
+```
+
+or, say:
+
+```sh
+deno add --npm solidjs @automerge/vanillajs
+deno add jsr:@chee/solid-automerge
+```
+
+## useDocument ✨
+
+Get a fine-grained live view of an automerge document from its URL.
+
+When the handle receives changes, it converts the incoming automerge patch ops
+to precise solid store updates, giving you fine-grained reactivity that's
+consistent across space and time.
+
+Returns `[doc, handle]`.
+
+```ts
+useDocument<T>(
+    () => AutomergeURL,
+    options?: {repo: Repo}
+): [Doc<T>, DocHandle<T>]
+```
+
+```tsx
+// example
+const [url, setURL] = createSignal<AutomergeUrl>(props.url)
+const [doc, handle] = useDocument(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).
+
+## createDocumentProjection
+
+Get a fine-grained live view from a signal automerge `DocHandle`.
+
+Underlying primitive for [`useDocument`](#usedocument-).
+
+Works with [`useHandle`](#usehandle).
+
+```ts
+createDocumentProjection<T>(() => AutomergeUrl): Doc<T>
+```
+
+```tsx
+// example
+const handle = repo.find(url)
+const doc = makeDocumentProjection<{ items: { title: string }[] }>(handle)
+
+// subscribes fine-grained to doc.items[1].title
+return <h1>{doc.items[1].title}</h1>
+```
+
+## makeDocumentProjection
+
+Just like `createDocumentProjection`, but without a reactive input.
+
+Underlying primitive for [`createDocumentProjection`](#createDocumentProjection).
+
+```ts
+makeDocumentProjection<T>(handle: Handle<T>): Doc<T>
+```
+
+```tsx
+// example
+const handle = repo.find(url)
+const doc = makeDocumentProjection<{ items: { title: string }[] }>(handle)
+
+// subscribes fine-grained to doc.items[1].title
+return <h1>{doc.items[1].title}</h1>
+```
+
+## useDocHandle
+
+Get a [DocHandle](https://automerge.org/docs/repositories/dochandles/) from the
+repo as a
+[resource](https://docs.solidjs.com/reference/basic-reactivity/create-resource).
+
+Perfect for handing to `createDocumentProjection`.
+
+```ts
+useDocHandle<T>(
+    () => AnyDocumentId,
+    options?: {repo: Repo}
+): Resource<Handle<T>>
+```
+
+```tsx
+const handle = useDocHandle(id, { repo })
+// or
+const handle = useDocHandle(id)
+```
+
+The `repo` option can be left out if you are using [RepoContext](#repocontext).
+
+## context
+
+If you prefer the context pattern for some reason, you can pass the repo higher
+up in your app with `RepoContext`
+
+### `RepoContext`
+
+A convenience context for Automerge-Repo Solid apps. Optional: if you prefer you
+can pass a repo as an option to `useDocHandle` and `useDocument`.
+
+```tsx
+<RepoContext.Provider repo={Repo}>
+  <App />
+</RepoContext.Provider>
+```
+
+### `useRepo`
+
+Get the repo from the [context](#repocontext).
+
+```ts
+useRepo(): Repo
+```
+
+#### e.g.
+
+```ts
+const repo = useRepo()
+```

package/src/autoproduce.ts

@@ -0,0 +1,18 @@
+import type { DocHandleChangePayload } from "@automerge/automerge-repo/slim"
+import { applyPatches } from "@automerge/automerge/slim"
+
+/**
+ * convert automerge patches to solid producer operations
+ * @param payload the
+ * [DocHandleChangePayload](https://automerge.org/automerge-repo/interfaces/_automerge_automerge_repo.DocHandleChangePayload.html)
+ * from the handle.on("change
+ * @returns a callback for an immer-like function. e.g.
+ * [produce](https://docs.solidjs.com/reference/store-utilities/produce) for
+ * [Solid
+ * Stores](https://docs.solidjs.com/reference/store-utilities/create-store)
+ */
+export default function autoproduce<T>(
+  payload: DocHandleChangePayload<T>
+): (doc: T) => void {
+  return (doc: T) => applyPatches(doc, payload.patches)
+}

package/src/context.ts

@@ -0,0 +1,11 @@
+import type { Repo } from "@automerge/automerge-repo/slim"
+import { createContext, type Context } from "solid-js"
+
+/**
+ * a [context](https://docs.solidjs.com/concepts/context) that provides access
+ * to an Automerge Repo. you don't need this, you can pass the repo in the
+ * second arg to the functions that need it.
+ */
+export const RepoContext: Context<Repo | null> = createContext<Repo | null>(
+  null
+)

package/src/createDocumentProjection.ts

@@ -0,0 +1,19 @@
+import { createMemo, type Accessor } from "solid-js"
+import { type DocHandle, type Doc } from "@automerge/automerge-repo/slim"
+import makeDocumentProjection from "./makeDocumentProjection.js"
+
+/**
+ * get a fine-grained live view of a document from a handle. 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 createDocumentProjection<T extends object>(
+  handle: Accessor<DocHandle<T> | undefined>
+): Accessor<Doc<T> | undefined> {
+  const projection = createMemo<Doc<T> | undefined>(() => {
+    const unwrappedHandle = typeof handle == "function" ? handle() : handle
+    return unwrappedHandle && makeDocumentProjection<T>(unwrappedHandle)
+  })
+  return projection
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { default as autoproduce } from "./autoproduce.js"
+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 useRepo } from "./useRepo.js"
+export { RepoContext } from "./context.js"

package/src/makeDocumentProjection.ts

@@ -0,0 +1,73 @@
+import { onCleanup } from "solid-js"
+import type {
+  Doc,
+  DocHandle,
+  DocHandleChangePayload,
+} from "@automerge/automerge-repo/slim"
+import autoproduce from "./autoproduce.js"
+import { createStore, produce, reconcile, type Store } from "solid-js/store"
+import { applyPatches, diff, getHeads } from "@automerge/automerge/slim"
+
+const cache = new WeakMap<
+  DocHandle<unknown>,
+  {
+    refs: number
+    store: Store<Doc<unknown>>
+    cleanup(): void
+  }
+>()
+
+function initial<T>(handle: DocHandle<T>): T {
+  const template = {} as T
+  applyPatches(template, diff(handle.doc(), [], getHeads(handle.doc())))
+  return template
+}
+
+/**
+ * make a fine-grained live view of a document from its handle.
+ * @param handle an Automerge
+ * [DocHandle](https://automerge.org/automerge-repo/classes/_automerge_automerge_repo.DocHandle.html)
+ */
+export default function makeDocumentProjection<T extends object>(
+  handle: DocHandle<T>
+): Doc<T> {
+  onCleanup(() => {
+    const item = cache.get(handle)!
+    if (!item) return
+    if (!item.refs--) {
+      item.cleanup()
+    }
+  })
+
+  if (cache.has(handle)) {
+    const item = cache.get(handle)!
+    item.refs++
+    return item.store as T
+  }
+
+  const [doc, set] = createStore<T>(initial(handle))
+
+  cache.set(handle, {
+    refs: 0,
+    store: doc,
+    cleanup() {
+      handle.off("change", patch)
+      handle.off("delete", ondelete)
+      // https://github.com/chee/solid-automerge/pull/5
+      cache.delete(handle)
+    },
+  })
+
+  function patch(payload: DocHandleChangePayload<T>) {
+    set(produce(autoproduce(payload)))
+  }
+
+  function ondelete() {
+    set(reconcile({} as T))
+  }
+
+  handle.on("change", patch)
+  handle.on("delete", ondelete)
+
+  return doc
+}

package/src/types.ts

@@ -0,0 +1,9 @@
+import type { Repo } from "@automerge/automerge-repo/slim"
+
+export interface UseDocHandleOptions {
+  repo?: Repo
+  // @internal
+  "~skipInitialValue"?: boolean
+}
+
+export type MaybeAccessor<T> = T | (() => T)

package/src/useDocHandle.ts

@@ -0,0 +1,90 @@
+import type {
+  AutomergeUrl,
+  DocHandle,
+  DocumentId,
+  HandleState,
+} from "@automerge/automerge-repo/slim"
+import {
+  createEffect,
+  createResource,
+  useContext,
+  type Resource,
+} from "solid-js"
+import { RepoContext } from "./context.js"
+import type { MaybeAccessor, UseDocHandleOptions } from "./types.js"
+const readyStates = ["ready", "deleted", "unavailable"] as HandleState[]
+const badStates = ["deleted", "unavailable"] as HandleState[]
+
+/**
+ * get a
+ * [DocHandle](https://automerge.org/automerge-repo/classes/_automerge_automerge_repo.DocHandle.html)
+ * from an
+ * [AutomergeUrl](https://automerge.org/automerge-repo/types/_automerge_automerge_repo.AutomergeUrl.html)
+ * as a
+ * [Resource](https://docs.solidjs.com/reference/basic-reactivity/create-resource).
+ * Waits for the handle to be
+ * [ready](https://automerge.org/automerge-repo/variables/_automerge_automerge_repo.HandleState-1.html).
+ */
+export default function useDocHandle<T>(
+  url: MaybeAccessor<AutomergeUrl | undefined>,
+  options?: UseDocHandleOptions
+): Resource<DocHandle<T> | undefined> {
+  const contextRepo = useContext(RepoContext)
+
+  if (!options?.repo && !contextRepo) {
+    throw new Error("use outside <RepoContext> requires options.repo")
+  }
+
+  const repo = (options?.repo || contextRepo)!
+
+  function getExistingHandle() {
+    if (options?.["~skipInitialValue"]) return undefined
+    const unwrappedURL = typeof url == "function" ? url() : url
+    if (!unwrappedURL) return undefined
+    try {
+      const documentId = new URL(unwrappedURL).pathname as DocumentId
+      const existingHandle = repo.handles[documentId]
+      if (existingHandle?.isReady()) {
+        return existingHandle as DocHandle<T>
+      }
+    } catch (error) {
+      console.error("Error parsing URL:", error)
+    }
+  }
+
+  const [handle, { mutate }] = createResource(
+    url,
+    async url => {
+      const handle = await repo.find<T>(url, {
+        allowableStates: readyStates,
+      })
+      const reject = (state: HandleState) =>
+        Promise.reject(new Error(`document not available: [${state}]`))
+
+      if (handle.isReady()) {
+        return handle
+      } else if (handle.inState(badStates)) {
+        return reject(handle.state)
+      }
+
+      return handle.whenReady(readyStates).then(() => {
+        if (handle.isReady()) {
+          return handle
+        }
+        return reject(handle.state)
+      })
+    },
+    {
+      initialValue: getExistingHandle(),
+    }
+  )
+
+  createEffect(() => {
+    const unwrappedURL = typeof url == "function" ? url() : url
+    if (!unwrappedURL) {
+      mutate()
+    }
+  })
+
+  return handle
+}

package/src/useDocument.ts

@@ -0,0 +1,21 @@
+import type {
+  AutomergeUrl,
+  Doc,
+  DocHandle,
+} from "@automerge/automerge-repo/slim"
+import createDocumentProjection from "./createDocumentProjection.js"
+import useDocHandle from "./useDocHandle.js"
+import type { MaybeAccessor, UseDocHandleOptions } from "./types.js"
+import type { Accessor, Resource } from "solid-js"
+
+/**
+ * get a fine-grained live view of a document, and its handle, from a URL.
+ * @param url a function that returns a url
+ */
+export default function useDocument<T extends object>(
+  url: MaybeAccessor<AutomergeUrl | undefined>,
+  options?: UseDocHandleOptions
+): [Accessor<Doc<T> | undefined>, Resource<DocHandle<T> | undefined>] {
+  const handle = useDocHandle<T>(url, options)
+  return [createDocumentProjection<T>(handle), handle] as const
+}

package/src/useRepo.ts

@@ -0,0 +1,10 @@
+import type { Repo } from "@automerge/automerge-repo/slim"
+import { RepoContext } from "./context.js"
+import { useContext } from "solid-js"
+
+/** grab the repo from the {@link RepoContext} */
+export default function useRepo(): Repo {
+  const repo = useContext(RepoContext)
+  if (!repo) throw new Error("Please wrap me in a <RepoContext value={repo}>")
+  return repo
+}