@automerge/automerge-repo-react-hooks 0.1.2 → 0.1.4-alpha.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { useDocument } from "./useDocument.js";
+export { useBootstrap } from './useBootstrap.js';
 export { useHandle } from "./useHandle.js";
 export { RepoContext, useRepo } from "./useRepo.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { useDocument } from "./useDocument.js";
+export { useBootstrap } from './useBootstrap.js';
 export { useHandle } from "./useHandle.js";
 export { RepoContext, useRepo } from "./useRepo.js";

package/dist/useBootstrap.d.ts

@@ -0,0 +1,28 @@
+import { DocHandle, Repo } from "@automerge/automerge-repo";
+export declare const setHash: (hash: string, pushState?: boolean) => void;
+export declare const useHash: () => string;
+/**
+ * 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.
+ * 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.
+ *
+ * @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)
+ * @returns {DocHandle} The document handle
+ */
+interface UseBootstrapOptions<T> {
+    key?: string;
+    onNoDocument?: (repo: Repo) => DocHandle<T>;
+    onInvalidDocumentId?(repo: Repo, error: Error): DocHandle<T>;
+}
+export declare const useBootstrap: <T>({ key, onNoDocument, onInvalidDocumentId, }?: UseBootstrapOptions<T>) => DocHandle<T>;
+export {};
+//# sourceMappingURL=useBootstrap.d.ts.map

package/dist/useBootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBootstrap.d.ts","sourceRoot":"","sources":["../src/useBootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAc,IAAI,EAAE,MAAM,2BAA2B,CAAA;AAKvE,eAAO,MAAM,OAAO,SAAU,MAAM,8BAUnC,CAAA;AAGD,eAAO,MAAM,OAAO,cAQnB,CAAA;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,UAAU,mBAAmB,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAA;IAC3C,mBAAmB,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;CAC7D;AAED,eAAO,MAAM,YAAY,2FAgCxB,CAAA"}

package/dist/useBootstrap.js

@@ -0,0 +1,66 @@
+import { useEffect, useState, useMemo } from "react";
+import { useRepo } from "./useRepo.js";
+// Set URL hash
+export const setHash = (hash, pushState = false) => {
+    // Update URL hash
+    history[pushState ? "pushState" : "replaceState"]("", "", "#" + hash);
+    // Send fake hashchange event
+    window.dispatchEvent(new HashChangeEvent("hashchange", {
+        newURL: window.location.origin + window.location.pathname + hash,
+        oldURL: window.location.href,
+    }));
+};
+// Get current URL hash
+export const useHash = () => {
+    const [hashValue, setHashValue] = useState(window.location.hash);
+    useEffect(() => {
+        const handler = () => void setHashValue(window.location.hash);
+        window.addEventListener("hashchange", handler);
+        return () => void window.removeEventListener("hashchange", handler);
+    }, []);
+    return hashValue;
+};
+// Get a key from a query-param-style URL hash
+const getQueryParamValue = (key, hash) => new URLSearchParams(hash.substr(1)).get(key);
+const setQueryParamValue = (key, value, hash) => {
+    const u = new URLSearchParams(hash.substr(1));
+    u.set(key, value);
+    return u.toString();
+};
+const getDocumentId = (key, hash) => key && (getQueryParamValue(key, hash) || localStorage.getItem(key));
+const setDocumentId = (key, documentId) => {
+    if (key) {
+        // Only set URL hash if document ID changed
+        if (documentId !== getQueryParamValue(key, window.location.hash))
+            setHash(setQueryParamValue(key, documentId, window.location.hash));
+    }
+    if (key)
+        localStorage.setItem(key, documentId);
+};
+export const useBootstrap = ({ key = "documentId", onNoDocument = repo => repo.create(), onInvalidDocumentId, } = {}) => {
+    const repo = useRepo();
+    const hash = useHash();
+    // Try to get existing document; else create a new one
+    const handle = useMemo(() => {
+        const existingDocumentId = getDocumentId(key, hash);
+        try {
+            return existingDocumentId
+                ? repo.find(existingDocumentId)
+                : onNoDocument(repo);
+        }
+        catch (error) {
+            // Presumably the documentId was invalid
+            if (existingDocumentId && onInvalidDocumentId)
+                return onInvalidDocumentId(repo, error);
+            // Forward other errors
+            throw error;
+        }
+    }, [hash, repo, onNoDocument, onInvalidDocumentId]);
+    // Update hashroute & localStorage on changes
+    useEffect(() => {
+        if (handle) {
+            setDocumentId(key, handle.documentId);
+        }
+    }, [hash, handle]);
+    return handle;
+};

package/dist/useDocument.js

@@ -8,7 +8,7 @@ export function useDocument(documentId) {
         if (!handle)
             return;
         handle.value().then(v => setDoc(v));
-        const onPatch = (h) => setDoc(h.after);
+        const onPatch = (h) => setDoc(h.patchInfo.after);
         handle.on("patch", onPatch);
         const cleanup = () => {
             handle.removeListener("patch", onPatch);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo-react-hooks",
-  "version": "0.1.2",
+  "version": "0.1.4-alpha.0",
   "description": "Hooks to access an Automerge Repo from your react app.",
   "repository": "https://github.com/automerge/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -13,7 +13,7 @@
     "watch": "npm-watch"
   },
   "dependencies": {
-    "@automerge/automerge-repo": "^0.1.2"
+    "@automerge/automerge-repo": "^0.1.4-alpha.0"
   },
   "watch": {
     "build": {
@@ -26,5 +26,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "a6313d0e6de2951c98ecffd4a6f01b82c46613e3"
+  "gitHead": "9a431d695250ea3ee2e58b4d60d2fb6a90c904e4"
 }

package/src/index.ts

@@ -1,3 +1,4 @@
 export { useDocument } from "./useDocument.js"
+export { useBootstrap } from './useBootstrap.js'
 export { useHandle } from "./useHandle.js"
 export { RepoContext, useRepo } from "./useRepo.js"

package/src/useBootstrap.ts

@@ -0,0 +1,106 @@
+import { DocHandle, DocumentId, Repo } from "@automerge/automerge-repo"
+import { useEffect, useState, useMemo } from "react"
+import { useRepo } from "./useRepo.js"
+
+// Set URL hash
+export const setHash = (hash: string, pushState = false) => {
+  // Update URL hash
+  history[pushState ? "pushState" : "replaceState"]("", "", "#" + hash)
+  // Send fake hashchange event
+  window.dispatchEvent(
+    new HashChangeEvent("hashchange", {
+      newURL: window.location.origin + window.location.pathname + hash,
+      oldURL: window.location.href,
+    })
+  )
+}
+
+// Get current URL hash
+export const useHash = () => {
+  const [hashValue, setHashValue] = useState(window.location.hash)
+  useEffect(() => {
+    const handler = () => void setHashValue(window.location.hash)
+    window.addEventListener("hashchange", handler)
+    return () => void window.removeEventListener("hashchange", handler)
+  }, [])
+  return hashValue
+}
+
+// Get a key from a query-param-style URL hash
+const getQueryParamValue = (key: string, hash) =>
+  new URLSearchParams(hash.substr(1)).get(key)
+
+const setQueryParamValue = (key: string, value, hash): string => {
+  const u = new URLSearchParams(hash.substr(1))
+  u.set(key, value)
+  return u.toString()
+}
+
+const getDocumentId = (key, hash) =>
+  key && (getQueryParamValue(key, hash) || localStorage.getItem(key))
+
+const setDocumentId = (key, documentId) => {
+  if (key) {
+    // Only set URL hash if document ID changed
+    if (documentId !== getQueryParamValue(key, window.location.hash))
+      setHash(setQueryParamValue(key, documentId, window.location.hash))
+  }
+  if (key) localStorage.setItem(key, documentId)
+}
+
+/**
+ * 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.
+ * 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.
+ *
+ * @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)
+ * @returns {DocHandle} The document handle
+ */
+interface UseBootstrapOptions<T> {
+  key?: string
+  onNoDocument?: (repo: Repo) => DocHandle<T>
+  onInvalidDocumentId?(repo: Repo, error: Error): DocHandle<T>
+}
+
+export const useBootstrap = <T>({
+  key = "documentId",
+  onNoDocument = repo => repo.create(),
+  onInvalidDocumentId,
+}: 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 existingDocumentId = getDocumentId(key, hash)
+    try {
+      return existingDocumentId
+        ? repo.find(existingDocumentId as DocumentId)
+        : onNoDocument(repo)
+    } catch (error) {
+      // Presumably the documentId was invalid
+      if (existingDocumentId && onInvalidDocumentId)
+        return onInvalidDocumentId(repo, error)
+      // Forward other errors
+      throw error
+    }
+  }, [hash, repo, onNoDocument, onInvalidDocumentId])
+
+  // Update hashroute & localStorage on changes
+  useEffect(() => {
+    if (handle) {
+      setDocumentId(key, handle.documentId)
+    }
+  }, [hash, handle])
+
+  return handle
+}

package/src/useDocument.ts

@@ -14,7 +14,7 @@ export function useDocument<T>(documentId?: DocumentId) {
 
     handle.value().then(v => setDoc(v))
 
-    const onPatch = (h: DocHandlePatchPayload<T>) => setDoc(h.after)
+    const onPatch = (h: DocHandlePatchPayload<T>) => setDoc(h.patchInfo.after)
     handle.on("patch", onPatch)
     const cleanup = () => {
       handle.removeListener("patch", onPatch)