@graffiti-garden/wrapper-vue 0.7.2 → 1.0.3

package/src/components/ObjectInfo.vue

@@ -0,0 +1,127 @@
+<script setup lang="ts">
+import type { GraffitiObjectBase, GraffitiSession } from "@graffiti-garden/api";
+import ActorToHandle from "./ActorToHandle.vue";
+import { useGraffiti } from "../globals";
+import { ref } from "vue";
+
+defineProps<{
+    object: GraffitiObjectBase | null | undefined;
+}>();
+
+const graffiti = useGraffiti();
+const deleting = ref(false);
+async function deleteObject(
+    object: GraffitiObjectBase,
+    session: GraffitiSession,
+) {
+    deleting.value = true;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    if (
+        confirm(
+            "Are you sure you want to delete this object? It cannot be undone.",
+        )
+    ) {
+        await graffiti.delete(object, session);
+    }
+    deleting.value = false;
+}
+</script>
+
+<template>
+    <article v-if="object" :data-url="object.url">
+        <header>
+            <h2>Graffiti Object</h2>
+
+            <dl>
+                <dt>Object URL</dt>
+                <dd>
+                    <code>{{ object.url }}</code>
+                </dd>
+
+                <dt>Actor</dt>
+                <dd>
+                    <code>{{ object.actor }}</code>
+                </dd>
+
+                <dt>Handle</dt>
+                <dd>
+                    <ActorToHandle :actor="object.actor" />
+                </dd>
+            </dl>
+        </header>
+
+        <section>
+            <h3>Content</h3>
+            <pre>{{ object.value }}</pre>
+        </section>
+
+        <section>
+            <h3>Allowed Actors</h3>
+
+            <p v-if="!Array.isArray(object.allowed)">
+                <em>Public</em>
+            </p>
+            <p v-else-if="object.allowed.length === 0">
+                <em>Noone</em>
+            </p>
+            <ul>
+                <li v-for="actor in object.allowed" :key="actor">
+                    <dl>
+                        <dt>Actor</dt>
+                        <dd>
+                            <code>{{ actor }}</code>
+                        </dd>
+                        <dt>Handle</dt>
+                        <dd>
+                            <ActorToHandle :actor="actor" />
+                        </dd>
+                    </dl>
+                </li>
+            </ul>
+        </section>
+
+        <section>
+            <h3>Channels</h3>
+
+            <ul v-if="object.channels?.length">
+                <li v-for="channel in object.channels" :key="channel">
+                    <code>{{ channel }}</code>
+                </li>
+            </ul>
+            <p v-else>
+                <em>No channels</em>
+            </p>
+        </section>
+
+        <footer>
+            <nav>
+                <ul>
+                    <li v-if="$graffitiSession.value?.actor === object.actor">
+                        <button
+                            :disabled="deleting"
+                            @click="
+                                deleteObject(object, $graffitiSession.value)
+                            "
+                        >
+                            {{ deleting ? "Deleting..." : "Delete" }}
+                        </button>
+                    </li>
+                </ul>
+            </nav>
+        </footer>
+    </article>
+
+    <article v-else-if="object === null">
+        <header>
+            <h2>Graffiti Object</h2>
+        </header>
+        <p><em>Object not found</em></p>
+    </article>
+
+    <article v-else>
+        <header>
+            <h2>Graffiti Object</h2>
+        </header>
+        <p><em>Loading...</em></p>
+    </article>
+</template>

package/src/composables/actor-to-handle.ts

@@ -0,0 +1,32 @@
+import type { MaybeRefOrGetter } from "vue";
+import { useGraffiti } from "../globals";
+import { useResolveString } from "./resolve-string";
+
+/**
+ * The [Graffiti.actorToHandle](https://api.graffiti.garden/classes/Graffiti.html#actortohandle)
+ * method as a reactive [composable](https://vuejs.org/guide/reusability/composables.html)
+ * for use in the Vue [composition API](https://vuejs.org/guide/introduction.html#composition-api).
+ *
+ * Its corresponding renderless component is {@link GraffitiActorToHandle}.
+ *
+ * The arguments of this composable are the same as Graffiti.actorToHandle,
+ * only they can also be [Refs](https://vuejs.org/api/reactivity-core.html#ref)
+ * or [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description).
+ * As they change the output will automatically update.
+ * Reactivity only triggers when the root array or object changes,
+ * not when the elements or properties change.
+ * If you need deep reactivity, wrap your argument in a getter.
+ *
+ * @returns
+ * - `handle`: A [ref](https://vuejs.org/api/reactivity-core.html#ref) that contains
+ * the retrieved handle, if it exists. If the handle cannot be found, the result
+ * is `null`. If the handle is still being fetched, the result is `undefined`.
+ */
+export function useGraffitiActorToHandle(actor: MaybeRefOrGetter<string>) {
+  const graffiti = useGraffiti();
+  const { output } = useResolveString(
+    actor,
+    graffiti.actorToHandle.bind(graffiti),
+  );
+  return { handle: output };
+}

package/src/composables/discover.ts

@@ -0,0 +1,202 @@
+import type {
+  GraffitiObject,
+  GraffitiObjectStreamContinue,
+  GraffitiObjectStreamContinueEntry,
+  GraffitiObjectStreamError,
+  GraffitiObjectStreamReturn,
+  GraffitiSession,
+  JSONSchema,
+} from "@graffiti-garden/api";
+import { GraffitiErrorNotFound } from "@graffiti-garden/api";
+import type { MaybeRefOrGetter, Ref } from "vue";
+import { ref, toValue, watch, onScopeDispose } from "vue";
+import { useGraffitiSynchronize } from "../globals";
+
+/**
+ * The [Graffiti.discover](https://api.graffiti.garden/classes/Graffiti.html#discover)
+ * method as a reactive [composable](https://vuejs.org/guide/reusability/composables.html)
+ * for use in the Vue [composition API](https://vuejs.org/guide/introduction.html#composition-api).
+ *
+ * Its corresponding renderless component is {@link GraffitiDiscover}.
+ *
+ * The arguments of this composable are largely the same as Graffiti.discover,
+ * only they can also be [Refs](https://vuejs.org/api/reactivity-core.html#ref)
+ * or [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description).
+ * There is one additional optional argument `autopoll`, which when `true`,
+ * will automatically poll for new objects.
+ * As they change the arguments change, the output will automatically update.
+ * Reactivity only triggers when the root array or object changes,
+ * not when the elements or properties change.
+ * If you need deep reactivity, wrap your argument in a getter.
+ *
+ * @returns
+ * - `objects`: A [ref](https://vuejs.org/api/reactivity-core.html#ref) that contains
+ * an array of Graffiti objects.
+ * - `poll`: A function that can be called to manually check for objects.
+ * - `isFirstPoll`: A boolean [ref](https://vuejs.org/api/reactivity-core.html#ref)
+ * that indicates if the *first* poll after a change of arguments is currently running.
+ * It may be used to show a loading spinner or disable a button, or it can be watched
+ * to know when the `objects` array is ready to use.
+ */
+export function useGraffitiDiscover<Schema extends JSONSchema>(
+  channels: MaybeRefOrGetter<string[]>,
+  schema: MaybeRefOrGetter<Schema>,
+  session?: MaybeRefOrGetter<GraffitiSession | undefined | null>,
+  /**
+   * Whether to automatically poll for new objects.
+   */
+  autopoll: MaybeRefOrGetter<boolean> = false,
+) {
+  const graffiti = useGraffitiSynchronize();
+
+  // Output
+  const objectsRaw: Map<string, GraffitiObject<Schema>> = new Map();
+  const objects: Ref<GraffitiObject<Schema>[]> = ref([]);
+  let poll_ = async () => {};
+  const poll = async () => poll_();
+  const isFirstPoll = ref(true);
+
+  // Maintain iterators for disposal
+  let syncIterator: AsyncGenerator<GraffitiObjectStreamContinueEntry<Schema>>;
+  let discoverIterator: GraffitiObjectStreamContinue<Schema>;
+  onScopeDispose(() => {
+    syncIterator?.return(null);
+    discoverIterator?.return({
+      continue: () => discoverIterator,
+      cursor: "",
+    });
+  });
+
+  const refresh = ref(0);
+  function restartWatch(timeout = 0) {
+    setTimeout(() => {
+      refresh.value++;
+    }, timeout);
+  }
+  watch(
+    () => ({
+      args: [toValue(channels), toValue(schema), toValue(session)] as const,
+      refresh: refresh.value,
+    }),
+    ({ args }, _prev, onInvalidate) => {
+      // Reset the output
+      objectsRaw.clear();
+      objects.value = [];
+      isFirstPoll.value = true;
+
+      // Initialize new iterators
+      const mySyncIterator = graffiti.synchronizeDiscover<Schema>(...args);
+      syncIterator = mySyncIterator;
+      let myDiscoverIterator: GraffitiObjectStreamContinue<Schema>;
+
+      // Set up automatic iterator cleanup
+      let active = true;
+      onInvalidate(() => {
+        active = false;
+        mySyncIterator.return(null);
+        myDiscoverIterator?.return({
+          continue: () => discoverIterator,
+          cursor: "",
+        });
+      });
+
+      // Start to synchronize in the background
+      // (all polling results will go through here)
+      let batchFlattenPromise: Promise<void> | undefined = undefined;
+      (async () => {
+        for await (const result of mySyncIterator) {
+          if (!active) break;
+          if (result.tombstone) {
+            objectsRaw.delete(result.object.url);
+          } else {
+            objectsRaw.set(result.object.url, result.object);
+          }
+          // Flatten objects in batches to prevent
+          // excessive re-rendering
+          if (!batchFlattenPromise) {
+            batchFlattenPromise = new Promise<void>((resolve) => {
+              setTimeout(() => {
+                if (active) {
+                  objects.value = Array.from(objectsRaw.values());
+                }
+                batchFlattenPromise = undefined;
+                resolve();
+              }, 50);
+            });
+          }
+        }
+      })();
+
+      // Then set up a polling function
+      let polling = false;
+      let continueFn: GraffitiObjectStreamReturn<Schema>["continue"] = () =>
+        graffiti.discover<Schema>(...args);
+      poll_ = async () => {
+        if (polling || !active) return;
+        polling = true;
+
+        // Try to start the iterator
+        try {
+          myDiscoverIterator = continueFn(args[2]);
+        } catch (e) {
+          // Discovery is lazy so this should not happen,
+          // wait a bit before retrying
+          return restartWatch(5000);
+        }
+        if (!active) return;
+        discoverIterator = myDiscoverIterator;
+
+        while (true) {
+          let result: IteratorResult<
+            | GraffitiObjectStreamContinueEntry<Schema>
+            | GraffitiObjectStreamError,
+            GraffitiObjectStreamReturn<Schema>
+          >;
+          try {
+            result = await myDiscoverIterator.next();
+          } catch (e) {
+            if (e instanceof GraffitiErrorNotFound) {
+              // The cursor has expired, we need to start from scratch.
+              return restartWatch();
+            } else {
+              // If something else went wrong, wait a bit before retrying
+              return restartWatch(5000);
+            }
+          }
+          if (!active) return;
+          if (result.done) {
+            continueFn = result.value.continue;
+            break;
+          } else if (result.value.error) {
+            // Non-fatal errors do not stop the stream
+            console.error(result.value.error);
+          }
+        }
+
+        // Wait for sync to receive updates
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        // And wait for pending results to be flattened
+        if (batchFlattenPromise) await batchFlattenPromise;
+
+        if (!active) return;
+        polling = false;
+        isFirstPoll.value = false;
+        if (toValue(autopoll)) poll();
+      };
+      poll();
+    },
+    { immediate: true },
+  );
+
+  // Start polling if autopoll turns true
+  watch(
+    () => toValue(autopoll),
+    (value) => value && poll(),
+  );
+
+  return {
+    objects,
+    poll,
+    isFirstPoll,
+  };
+}

package/src/composables/get-media.ts

@@ -0,0 +1,116 @@
+import type {
+  GraffitiMedia,
+  GraffitiMediaRequirements,
+  GraffitiSession,
+} from "@graffiti-garden/api";
+import { GraffitiErrorNotFound } from "@graffiti-garden/api";
+import type { MaybeRefOrGetter, Ref } from "vue";
+import { ref, toValue, watch, onScopeDispose } from "vue";
+import { useGraffitiSynchronize } from "../globals";
+
+/**
+ * The [Graffiti.getMedia](https://api.graffiti.garden/classes/Graffiti.html#getMedia)
+ * method as a reactive [composable](https://vuejs.org/guide/reusability/composables.html)
+ * for use in the Vue [composition API](https://vuejs.org/guide/introduction.html#composition-api).
+ *
+ * Its corresponding renderless component is {@link GraffitiGetMedia}.
+ *
+ * The arguments of this composable are the same as Graffiti.getMedia,
+ * only they can also be [Refs](https://vuejs.org/api/reactivity-core.html#ref)
+ * or [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description).
+ * As they change the output will automatically update.
+ * Reactivity only triggers when the root array or object changes,
+ * not when the elements or properties change.
+ * If you need deep reactivity, wrap your argument in a getter.
+ *
+ * @returns
+ * - `media`: A [ref](https://vuejs.org/api/reactivity-core.html#ref) that contains
+ * the retrieved Graffiti media, if it exists. The media will include a `dataUrl` property
+ * that can be used to directly display the media in a template. If the media has been deleted,
+ * the result is `null`. If the media is still being fetched, the result is `undefined`.
+ * - `poll`: A function that can be called to manually check if the media has changed.
+ */
+export function useGraffitiGetMedia(
+  url: MaybeRefOrGetter<string>,
+  requirements: MaybeRefOrGetter<GraffitiMediaRequirements>,
+  session?: MaybeRefOrGetter<GraffitiSession | undefined | null>,
+): {
+  media: Ref<(GraffitiMedia & { dataUrl: string }) | null | undefined>;
+  poll: () => Promise<void>;
+} {
+  const graffiti = useGraffitiSynchronize();
+  const media = ref<(GraffitiMedia & { dataUrl: string }) | null | undefined>(
+    undefined,
+  );
+
+  // The "poll counter" is a hack to get
+  // watch to refresh
+  const pollCounter = ref(0);
+  let pollPromise: Promise<void> | null = null;
+  let resolvePoll = () => {};
+  function poll() {
+    if (pollPromise) return pollPromise;
+    pollCounter.value++;
+    // Wait until the watch finishes and calls
+    // "pollResolve" to finish the poll
+    pollPromise = new Promise<void>((resolve) => {
+      resolvePoll = () => {
+        pollPromise = null;
+        resolve();
+      };
+    });
+    return pollPromise;
+  }
+  watch(
+    () => ({
+      args: [toValue(url), toValue(requirements), toValue(session)] as const,
+      pollCounter: pollCounter.value,
+    }),
+    async ({ args }, _prev, onInvalidate) => {
+      // Revoke the data URL to prevent a memory leak
+      if (media.value?.dataUrl) {
+        URL.revokeObjectURL(media.value.dataUrl);
+      }
+      media.value = undefined;
+
+      let active = true;
+      onInvalidate(() => {
+        active = false;
+      });
+
+      try {
+        const { data, actor, allowed } = await graffiti.getMedia(...args);
+        if (!active) return;
+        const dataUrl = URL.createObjectURL(data);
+        media.value = {
+          data,
+          dataUrl,
+          actor,
+          allowed,
+        };
+      } catch (e) {
+        if (!active) return;
+        if (e instanceof GraffitiErrorNotFound) {
+          media.value = null;
+        } else {
+          console.error(e);
+        }
+      } finally {
+        resolvePoll();
+      }
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(() => {
+    resolvePoll();
+    if (media.value?.dataUrl) {
+      URL.revokeObjectURL(media.value.dataUrl);
+    }
+  });
+
+  return {
+    media,
+    poll,
+  };
+}

package/src/composables/get.ts

@@ -0,0 +1,109 @@
+import type {
+  GraffitiObject,
+  GraffitiObjectUrl,
+  GraffitiObjectStreamContinueEntry,
+  GraffitiSession,
+  JSONSchema,
+} from "@graffiti-garden/api";
+import { GraffitiErrorNotFound } from "@graffiti-garden/api";
+import type { MaybeRefOrGetter, Ref } from "vue";
+import { ref, toValue, watch, onScopeDispose } from "vue";
+import { useGraffitiSynchronize } from "../globals";
+
+/**
+ * The [Graffiti.get](https://api.graffiti.garden/classes/Graffiti.html#get)
+ * method as a reactive [composable](https://vuejs.org/guide/reusability/composables.html)
+ * for use in the Vue [composition API](https://vuejs.org/guide/introduction.html#composition-api).
+ *
+ * Its corresponding renderless component is {@link GraffitiGet}.
+ *
+ * The arguments of this composable are the same as Graffiti.get,
+ * only they can also be [Refs](https://vuejs.org/api/reactivity-core.html#ref)
+ * or [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description).
+ * As they change the output will automatically update.
+ * Reactivity only triggers when the root array or object changes,
+ * not when the elements or properties change.
+ * If you need deep reactivity, wrap your argument in a getter.
+ *
+ * @returns
+ * - `object`: A [ref](https://vuejs.org/api/reactivity-core.html#ref) that contains
+ * the retrieved Graffiti object, if it exists. If the object cannot be found,
+ * the result is `null`. If the object is still being fetched, the result is `undefined`.
+ * - `poll`: A function that can be called to manually check if the object has changed.
+ */
+export function useGraffitiGet<Schema extends JSONSchema>(
+  url: MaybeRefOrGetter<GraffitiObjectUrl | string>,
+  schema: MaybeRefOrGetter<Schema>,
+  session?: MaybeRefOrGetter<GraffitiSession | undefined | null>,
+): {
+  object: Ref<GraffitiObject<Schema> | null | undefined>;
+  poll: () => Promise<void>;
+} {
+  const graffiti = useGraffitiSynchronize();
+
+  const object: Ref<GraffitiObject<Schema> | null | undefined> = ref(undefined);
+  let poll_ = async () => {};
+  const poll = async () => poll_();
+
+  let iterator: AsyncGenerator<GraffitiObjectStreamContinueEntry<Schema>>;
+  onScopeDispose(() => {
+    iterator?.return(null);
+  });
+
+  watch(
+    () => [toValue(url), toValue(schema), toValue(session)] as const,
+    (args, _prev, onInvalidate) => {
+      // Reset the object value (undefined = "loading")
+      object.value = undefined;
+
+      // Initialize a new iterator
+      const myIterator = graffiti.synchronizeGet<Schema>(...args);
+      iterator = myIterator;
+
+      // Make sure to dispose of the iterator when invalidated
+      let active = true;
+      onInvalidate(() => {
+        active = false;
+        myIterator.return(null);
+      });
+
+      // Listen to the iterator in the background,
+      // it will receive results from polling below
+      (async () => {
+        for await (const result of myIterator) {
+          if (!active) return;
+          if (result.tombstone) {
+            object.value = null;
+          } else {
+            object.value = result.object;
+          }
+        }
+      })();
+
+      // Then set up a polling function
+      let polling = false;
+      poll_ = async () => {
+        if (polling || !active) return;
+        polling = true;
+        try {
+          await graffiti.get<Schema>(...args);
+        } catch (e) {
+          if (!(e instanceof GraffitiErrorNotFound)) {
+            console.error(e);
+          }
+        }
+
+        // Wait for sync to receive the update
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        polling = false;
+      };
+      poll();
+    },
+    { immediate: true },
+  );
+
+  return {
+    object,
+    poll,
+  };
+}

package/src/composables/handle-to-actor.ts

@@ -0,0 +1,32 @@
+import type { MaybeRefOrGetter } from "vue";
+import { useGraffiti } from "../globals";
+import { useResolveString } from "./resolve-string";
+
+/**
+ * The [Graffiti.handleToActor](https://api.graffiti.garden/classes/Graffiti.html#handletoactor)
+ * method as a reactive [composable](https://vuejs.org/guide/reusability/composables.html)
+ * for use in the Vue [composition API](https://vuejs.org/guide/introduction.html#composition-api).
+ *
+ * Its corresponding renderless component is {@link GraffitiHandleToActor}.
+ *
+ * The arguments of this composable are the same as Graffiti.handleToActor,
+ * only they can also be [Refs](https://vuejs.org/api/reactivity-core.html#ref)
+ * or [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#description).
+ * As they change the output will automatically update.
+ * Reactivity only triggers when the root array or object changes,
+ * not when the elements or properties change.
+ * If you need deep reactivity, wrap your argument in a getter.
+ *
+ * @returns
+ * - `actor`: A [ref](https://vuejs.org/api/reactivity-core.html#ref) that contains
+ * the retrieved actor, if it exists. If the actor cannot be found, the result
+ * is `null`. If the actor is still being fetched, the result is `undefined`.
+ */
+export function useGraffitiHandleToActor(handle: MaybeRefOrGetter<string>) {
+  const graffiti = useGraffiti();
+  const { output } = useResolveString(
+    handle,
+    graffiti.handleToActor.bind(graffiti),
+  );
+  return { actor: output };
+}

package/src/composables/resolve-string.ts

@@ -0,0 +1,46 @@
+import { GraffitiErrorNotFound } from "@graffiti-garden/api";
+import type { MaybeRefOrGetter } from "vue";
+import { ref, toValue, watch } from "vue";
+
+export function useResolveString(
+  input: MaybeRefOrGetter<string>,
+  resolve: (input: string) => Promise<string>,
+) {
+  const output = ref<string | null | undefined>(undefined);
+
+  watch(
+    () => toValue(input),
+    async (input, _prev, onInvalidate) => {
+      let active = true;
+      onInvalidate(() => {
+        active = false;
+      });
+
+      output.value = undefined;
+
+      try {
+        const resolved = await resolve(input);
+        if (active) output.value = resolved;
+      } catch (err) {
+        if (!active) return;
+
+        if (err instanceof GraffitiErrorNotFound) {
+          output.value = null;
+        } else {
+          console.error(err);
+        }
+      }
+    },
+    { immediate: true },
+  );
+
+  return {
+    output,
+  };
+}
+
+export function displayOutput(output: string | null | undefined) {
+  if (output === undefined) return "Loading...";
+  if (output === null) return "Not found";
+  return output;
+}