@automerge/automerge-repo-react-hooks 1.0.3 → 1.0.4

package/dist/useBootstrap.d.ts

@@ -6,25 +6,25 @@ export interface UseBootstrapOptions<T> {
     key?: string;
     /** Function returning a document handle called if lookup fails. Defaults to repo.create() */
     onNoDocument?: (repo: Repo) => DocHandle<T>;
-    /** Function to call if documentId is invalid */
-    onInvalidDocumentId?(repo: Repo, error: Error): DocHandle<T>;
+    /** Function to call if automerge URL is invalid */
+    onInvalidAutomergeUrl?(repo: Repo, error: Error): DocHandle<T>;
 }
 /**
  * This hook is used to set up a single document as the base of an app session.
  * This is a common pattern for simple multiplayer apps with shareable URLs.
  *
- * It will first check for the document ID in the URL hash:
- *   //myapp/#documentId=[document ID]
- * Failing that, it will check for a `documentId` key in localStorage.
+ * It will first check for the automergeUrl in the URL hash:
+ *   //myapp/#automergeUrl=[document URL]
+ * Failing that, it will check for a `automergeUrl` key in localStorage.
  * Failing that, it will call onNoDocument, expecting a handle to be returned.
  *
  * The URL and localStorage will then be updated.
- * Finally, it will return the document ID.
+ * Finally, it will return the Automerge document's URL.
  *
  * @param {string?} props.key Key to use for the URL hash and localStorage
  * @param {function?} props.fallback Function returning a document handle called if lookup fails. Defaults to repo.create()
- * @param {function?} props.onInvalidDocumentId Function to call if documentId is invalid; signature (error) => (repo, onCreate)
+ * @param {function?} props.onInvalidAutomergeUrl Function to call if URL is invalid; signature (error) => (repo, onCreate)
  * @returns {DocHandle} The document handle
  */
-export declare const useBootstrap: <T>({ key, onNoDocument, onInvalidDocumentId, }?: UseBootstrapOptions<T>) => DocHandle<T>;
+export declare const useBootstrap: <T>({ key, onNoDocument, onInvalidAutomergeUrl, }?: UseBootstrapOptions<T>) => DocHandle<T>;
 //# sourceMappingURL=useBootstrap.d.ts.map

package/dist/useBootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBootstrap.d.ts","sourceRoot":"","sources":["../src/useBootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,IAAI,EAGL,MAAM,2BAA2B,CAAA;AAKlC,eAAO,MAAM,OAAO,SAAU,MAAM,8BAUnC,CAAA;AAGD,eAAO,MAAM,OAAO,cAQnB,CAAA;AAwBD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6FAA6F;IAC7F,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAC3C,gDAAgD;IAChD,mBAAmB,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;CAC7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,2FAgCxB,CAAA"}
+{"version":3,"file":"useBootstrap.d.ts","sourceRoot":"","sources":["../src/useBootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAqB,MAAM,2BAA2B,CAAA;AAK9E,eAAO,MAAM,OAAO,SAAU,MAAM,8BAUnC,CAAA;AAGD,eAAO,MAAM,OAAO,cAQnB,CAAA;AAwBD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6FAA6F;IAC7F,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAC3C,mDAAmD;IACnD,qBAAqB,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;CAC/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,6FA8BxB,CAAA"}

package/dist/useBootstrap.js

@@ -1,4 +1,3 @@
-import { generateAutomergeUrl, } from "@automerge/automerge-repo";
 import { useEffect, useState, useMemo } from "react";
 import { useRepo } from "./useRepo.js";
 // Set URL hash
@@ -28,56 +27,54 @@ const setQueryParamValue = (key, value, hash) => {
     u.set(key, value);
     return u.toString();
 };
-const getDocumentId = (key, hash) => key && (getQueryParamValue(key, hash) || localStorage.getItem(key));
-const setDocumentId = (key, documentId) => {
+const getAutomergeUrl = (key, hash) => key && (getQueryParamValue(key, hash) || localStorage.getItem(key));
+const setAutomergeUrl = (key, automergeUrl) => {
     if (key) {
-        // Only set URL hash if document ID changed
-        if (documentId !== getQueryParamValue(key, window.location.hash))
-            setHash(setQueryParamValue(key, documentId, window.location.hash));
+        // Only set URL hash if automerge URL changed
+        if (automergeUrl !== getQueryParamValue(key, window.location.hash))
+            setHash(setQueryParamValue(key, automergeUrl, window.location.hash));
     }
     if (key)
-        localStorage.setItem(key, documentId);
+        localStorage.setItem(key, automergeUrl);
 };
 /**
  * This hook is used to set up a single document as the base of an app session.
  * This is a common pattern for simple multiplayer apps with shareable URLs.
  *
- * It will first check for the document ID in the URL hash:
- *   //myapp/#documentId=[document ID]
- * Failing that, it will check for a `documentId` key in localStorage.
+ * It will first check for the automergeUrl in the URL hash:
+ *   //myapp/#automergeUrl=[document URL]
+ * Failing that, it will check for a `automergeUrl` key in localStorage.
  * Failing that, it will call onNoDocument, expecting a handle to be returned.
  *
  * The URL and localStorage will then be updated.
- * Finally, it will return the document ID.
+ * Finally, it will return the Automerge document's URL.
  *
  * @param {string?} props.key Key to use for the URL hash and localStorage
  * @param {function?} props.fallback Function returning a document handle called if lookup fails. Defaults to repo.create()
- * @param {function?} props.onInvalidDocumentId Function to call if documentId is invalid; signature (error) => (repo, onCreate)
+ * @param {function?} props.onInvalidAutomergeUrl Function to call if URL is invalid; signature (error) => (repo, onCreate)
  * @returns {DocHandle} The document handle
  */
-export const useBootstrap = ({ key = "documentId", onNoDocument = repo => repo.create(), onInvalidDocumentId, } = {}) => {
+export const useBootstrap = ({ key = "automergeUrl", onNoDocument = repo => repo.create(), onInvalidAutomergeUrl, } = {}) => {
     const repo = useRepo();
     const hash = useHash();
     // Try to get existing document; else create a new one
     const handle = useMemo(() => {
-        const documentId = getDocumentId(key, hash);
+        const url = getAutomergeUrl(key, hash);
         try {
-            return documentId
-                ? repo.find(generateAutomergeUrl({ documentId }))
-                : onNoDocument(repo);
+            return url ? repo.find(url) : onNoDocument(repo);
         }
         catch (error) {
-            // Presumably the documentId was invalid
-            if (documentId && onInvalidDocumentId)
-                return onInvalidDocumentId(repo, error);
+            // Presumably the URL was invalid
+            if (url && onInvalidAutomergeUrl)
+                return onInvalidAutomergeUrl(repo, error);
             // Forward other errors
             throw error;
         }
-    }, [hash, repo, onNoDocument, onInvalidDocumentId]);
+    }, [hash, repo, onNoDocument, onInvalidAutomergeUrl]);
     // Update hashroute & localStorage on changes
     useEffect(() => {
         if (handle) {
-            setDocumentId(key, handle.documentId);
+            setAutomergeUrl(key, handle.url);
         }
     }, [hash, handle]);
     return handle;

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@automerge/automerge-repo-react-hooks",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Hooks to access an Automerge Repo from your react app.",
-  "repository": "https://github.com/automerge/automerge-repo",
+  "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo-react-hooks",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
   "license": "MIT",
-  "private": false,
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
@@ -17,18 +16,18 @@
     "@automerge/automerge": "^2.1.0"
   },
   "dependencies": {
-    "@automerge/automerge-repo": "^1.0.3",
-    "eventemitter3": "^5.0.0",
+    "@automerge/automerge-repo": "^1.0.4",
+    "eventemitter3": "^5.0.1",
     "react": "^18.2.0",
     "react-usestateref": "^1.0.8"
   },
   "devDependencies": {
+    "@automerge/automerge": "^2.1.0",
     "@testing-library/react": "^14.0.0",
-    "@vitejs/plugin-react": "^4.0.2",
+    "@vitejs/plugin-react": "^3.0.0",
     "jsdom": "^22.1.0",
-    "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "vite-plugin-top-level-await": "^1.3.1",
+    "vite-plugin-top-level-await": "^1.3.0",
     "vite-plugin-wasm": "^3.2.2",
     "vitest": "^0.33.0"
   },
@@ -43,5 +42,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "4f3391cd33cd0cabfebde48dbd56749ddb6922da"
+  "gitHead": "17fd5260f9af3e65da636fef084e8c04d6c4bed0"
 }

package/src/useBootstrap.ts

@@ -1,9 +1,4 @@
-import {
-  DocHandle,
-  Repo,
-  type DocumentId,
-  generateAutomergeUrl,
-} from "@automerge/automerge-repo"
+import { DocHandle, Repo, type AutomergeUrl } from "@automerge/automerge-repo"
 import { useEffect, useState, useMemo } from "react"
 import { useRepo } from "./useRepo.js"
 
@@ -41,16 +36,16 @@ const setQueryParamValue = (key: string, value, hash): string => {
   return u.toString()
 }
 
-const getDocumentId = (key: string, hash: string) =>
+const getAutomergeUrl = (key: string, hash: string) =>
   key && (getQueryParamValue(key, hash) || localStorage.getItem(key))
 
-const setDocumentId = (key: string, documentId: DocumentId) => {
+const setAutomergeUrl = (key: string, automergeUrl: AutomergeUrl) => {
   if (key) {
-    // Only set URL hash if document ID changed
-    if (documentId !== getQueryParamValue(key, window.location.hash))
-      setHash(setQueryParamValue(key, documentId, window.location.hash))
+    // Only set URL hash if automerge URL changed
+    if (automergeUrl !== getQueryParamValue(key, window.location.hash))
+      setHash(setQueryParamValue(key, automergeUrl, window.location.hash))
   }
-  if (key) localStorage.setItem(key, documentId)
+  if (key) localStorage.setItem(key, automergeUrl)
 }
 
 export interface UseBootstrapOptions<T> {
@@ -58,55 +53,53 @@ export interface UseBootstrapOptions<T> {
   key?: string
   /** Function returning a document handle called if lookup fails. Defaults to repo.create() */
   onNoDocument?: (repo: Repo) => DocHandle<T>
-  /** Function to call if documentId is invalid */
-  onInvalidDocumentId?(repo: Repo, error: Error): DocHandle<T>
+  /** Function to call if automerge URL is invalid */
+  onInvalidAutomergeUrl?(repo: Repo, error: Error): DocHandle<T>
 }
 
 /**
  * This hook is used to set up a single document as the base of an app session.
  * This is a common pattern for simple multiplayer apps with shareable URLs.
  *
- * It will first check for the document ID in the URL hash:
- *   //myapp/#documentId=[document ID]
- * Failing that, it will check for a `documentId` key in localStorage.
+ * It will first check for the automergeUrl in the URL hash:
+ *   //myapp/#automergeUrl=[document URL]
+ * Failing that, it will check for a `automergeUrl` key in localStorage.
  * Failing that, it will call onNoDocument, expecting a handle to be returned.
  *
  * The URL and localStorage will then be updated.
- * Finally, it will return the document ID.
+ * Finally, it will return the Automerge document's URL.
  *
  * @param {string?} props.key Key to use for the URL hash and localStorage
  * @param {function?} props.fallback Function returning a document handle called if lookup fails. Defaults to repo.create()
- * @param {function?} props.onInvalidDocumentId Function to call if documentId is invalid; signature (error) => (repo, onCreate)
+ * @param {function?} props.onInvalidAutomergeUrl Function to call if URL is invalid; signature (error) => (repo, onCreate)
  * @returns {DocHandle} The document handle
  */
 export const useBootstrap = <T>({
-  key = "documentId",
+  key = "automergeUrl",
   onNoDocument = repo => repo.create(),
-  onInvalidDocumentId,
+  onInvalidAutomergeUrl,
 }: UseBootstrapOptions<T> = {}): DocHandle<T> => {
   const repo = useRepo()
   const hash = useHash()
 
   // Try to get existing document; else create a new one
   const handle = useMemo((): DocHandle<T> => {
-    const documentId = getDocumentId(key, hash) as DocumentId | undefined
+    const url = getAutomergeUrl(key, hash) as AutomergeUrl | undefined
     try {
-      return documentId
-        ? repo.find(generateAutomergeUrl({ documentId }))
-        : onNoDocument(repo)
+      return url ? repo.find(url) : onNoDocument(repo)
     } catch (error) {
-      // Presumably the documentId was invalid
-      if (documentId && onInvalidDocumentId)
-        return onInvalidDocumentId(repo, error)
+      // Presumably the URL was invalid
+      if (url && onInvalidAutomergeUrl)
+        return onInvalidAutomergeUrl(repo, error)
       // Forward other errors
       throw error
     }
-  }, [hash, repo, onNoDocument, onInvalidDocumentId])
+  }, [hash, repo, onNoDocument, onInvalidAutomergeUrl])
 
   // Update hashroute & localStorage on changes
   useEffect(() => {
     if (handle) {
-      setDocumentId(key, handle.documentId)
+      setAutomergeUrl(key, handle.url)
     }
   }, [hash, handle])