@graffiti-garden/wrapper-synchronize 0.2.3 → 1.0.2

package/src/index.ts

@@ -1,28 +1,26 @@
 import type Ajv from "ajv";
-import { Graffiti } from "@graffiti-garden/api";
 import type {
+  Graffiti,
   GraffitiSession,
   JSONSchema,
+  GraffitiObjectBase,
   GraffitiObjectStream,
   GraffitiObjectStreamContinueEntry,
   GraffitiObjectStreamContinue,
-  GraffitiObject,
+  GraffitiObjectUrl,
 } from "@graffiti-garden/api";
-import type { GraffitiObjectBase } from "@graffiti-garden/api";
-import { Repeater } from "@repeaterjs/repeater";
-import type { applyPatch } from "fast-json-patch";
 import {
-  applyGraffitiPatch,
+  GraffitiErrorNotFound,
   compileGraffitiObjectSchema,
   isActorAllowedGraffitiObject,
   maskGraffitiObject,
   unpackObjectUrl,
-} from "@graffiti-garden/implementation-local/utilities";
+} from "@graffiti-garden/api";
+import { Repeater } from "@repeaterjs/repeater";
 export type * from "@graffiti-garden/api";
 
 export type GraffitiSynchronizeCallback = (
-  oldObject: GraffitiObjectStreamContinueEntry<{}>,
-  newObject?: GraffitiObjectStreamContinueEntry<{}>,
+  object: GraffitiObjectStreamContinueEntry<{}>,
 ) => void;
 
 export interface GraffitiSynchronizeOptions {
@@ -48,23 +46,24 @@ export interface GraffitiSynchronizeOptions {
  * the [Graffiti Vue Plugin](https://vue.graffiti.garden/variables/GraffitiPlugin.html)
  * and possibly other front-end libraries in the future.
  *
- * Specifically, it provides the following *synchronize*
- * methods for each of the following API methods:
+ * [See a live example](/example).
+ *
+ * Specifically, this library provides the following *synchronize*
+ * methods to correspond with each of the following Graffiti API methods:
  *
  * | API Method | Synchronize Method |
  * |------------|--------------------|
  * | {@link get} | {@link synchronizeGet} |
  * | {@link discover} | {@link synchronizeDiscover} |
- * | {@link recoverOrphans} | {@link synchronizeRecoverOrphans} |
  *
- * Whenever a change is made via {@link put}, {@link patch}, and {@link delete} or
- * received from {@link get}, {@link discover}, and {@link recoverOrphans},
+ * Whenever a change is made via {@link post} and {@link delete} or
+ * received from {@link get}, {@link discover}, and {@link continueDiscover},
  * those changes are forwarded to the appropriate synchronize method.
  * Each synchronize method returns an iterator that streams these changes
  * continually until the user calls `return` on the iterator or `break`s out of the loop,
  * allowing for live updates without additional polling.
  *
- * Example 1: Suppose a user publishes a post using {@link put}. If the feed
+ * Example 1: Suppose a user publishes a post using {@link post}. If the feed
  * displaying that user's posts is using {@link synchronizeDiscover} to listen for changes,
  * then the user's new post will instantly appear in their feed, giving the UI a
  * responsive feel.
@@ -75,25 +74,34 @@ export interface GraffitiSynchronizeOptions {
  * all instance's of that friend's name in the user's application instantly,
  * providing a consistent user experience.
  *
- * @groupDescription Synchronize Methods
+ * Additionally, the library supplies a {@link synchronizeAll} method that can be used
+ * to stream all the Graffiti changes that an application is aware of, which can be used
+ * for caching or history building.
+ *
+ * The source code for this library is [available on GitHub](https://github.com/graffiti-garden/wrapper-synchronize/).
+ *
+ * @groupDescription 0 - Synchronize Methods
  * This group contains methods that listen for changes made via
- * {@link put}, {@link patch}, and {@link delete} or fetched from
- * {@link get}, {@link discover}, and {@link recoverOrphans} and then
+ * {@link post}, and {@link delete} or fetched from
+ * {@link get}, {@link discover}, or {@link continueDiscover} and then
  * streams appropriate changes to provide a responsive and consistent user experience.
  */
-export class GraffitiSynchronize extends Graffiti {
+export class GraffitiSynchronize implements Graffiti {
   protected ajv_: Promise<Ajv> | undefined;
-  protected applyPatch_: Promise<typeof applyPatch> | undefined;
   protected readonly graffiti: Graffiti;
   protected readonly callbacks = new Set<GraffitiSynchronizeCallback>();
   protected readonly options: GraffitiSynchronizeOptions;
 
-  channelStats: Graffiti["channelStats"];
   login: Graffiti["login"];
   logout: Graffiti["logout"];
   sessionEvents: Graffiti["sessionEvents"];
+  postMedia: Graffiti["postMedia"];
+  getMedia: Graffiti["getMedia"];
+  deleteMedia: Graffiti["deleteMedia"];
+  actorToHandle: Graffiti["actorToHandle"];
+  handleToActor: Graffiti["handleToActor"];
 
-  get ajv() {
+  protected get ajv() {
     if (!this.ajv_) {
       this.ajv_ = (async () => {
         const { default: Ajv } = await import("ajv");
@@ -103,16 +111,6 @@ export class GraffitiSynchronize extends Graffiti {
     return this.ajv_;
   }
 
-  get applyPatch() {
-    if (!this.applyPatch_) {
-      this.applyPatch_ = (async () => {
-        const { applyPatch } = await import("fast-json-patch");
-        return applyPatch;
-      })();
-    }
-    return this.applyPatch_;
-  }
-
   /**
    * Wraps a Graffiti API instance to provide the synchronize methods.
    * The GraffitiSyncrhonize class rather than the Graffiti class
@@ -126,13 +124,16 @@ export class GraffitiSynchronize extends Graffiti {
     graffiti: Graffiti,
     options?: GraffitiSynchronizeOptions,
   ) {
-    super();
     this.options = options ?? {};
     this.graffiti = graffiti;
-    this.channelStats = graffiti.channelStats.bind(graffiti);
     this.login = graffiti.login.bind(graffiti);
     this.logout = graffiti.logout.bind(graffiti);
     this.sessionEvents = graffiti.sessionEvents;
+    this.postMedia = graffiti.postMedia.bind(graffiti);
+    this.getMedia = graffiti.getMedia.bind(graffiti);
+    this.deleteMedia = graffiti.deleteMedia.bind(graffiti);
+    this.actorToHandle = graffiti.actorToHandle.bind(graffiti);
+    this.handleToActor = graffiti.handleToActor.bind(graffiti);
   }
 
   protected synchronize<Schema extends JSONSchema>(
@@ -140,39 +141,32 @@ export class GraffitiSynchronize extends Graffiti {
     channels: string[],
     schema: Schema,
     session?: GraffitiSession | null,
+    seenUrls: Set<string> = new Set<string>(),
   ): AsyncGenerator<GraffitiObjectStreamContinueEntry<Schema>> {
-    const seenUrls = new Set<string>();
-
     const repeater = new Repeater<GraffitiObjectStreamContinueEntry<Schema>>(
       async (push, stop) => {
         const validate = compileGraffitiObjectSchema(await this.ajv, schema);
-        const callback: GraffitiSynchronizeCallback = (
-          oldObjectRaw,
-          newObjectRaw,
-        ) => {
-          for (const objectRaw of [newObjectRaw, oldObjectRaw]) {
-            if (objectRaw?.tombstone) {
-              if (seenUrls.has(objectRaw.object.url)) {
-                push(objectRaw);
-              }
-            } else if (
-              objectRaw &&
-              matchObject(objectRaw.object) &&
-              (this.options.omniscient ||
-                isActorAllowedGraffitiObject(objectRaw.object, session))
-            ) {
-              // Deep clone the object to prevent mutation
-              const object = JSON.parse(
-                JSON.stringify(objectRaw.object),
-              ) as GraffitiObject<{}>;
-              if (!this.options.omniscient) {
-                maskGraffitiObject(object, channels, session);
-              }
-              if (validate(object)) {
-                push({ object });
-                seenUrls.add(object.url);
-                break;
-              }
+        const callback: GraffitiSynchronizeCallback = (objectUpdate) => {
+          if (objectUpdate?.tombstone) {
+            if (seenUrls.has(objectUpdate.object.url)) {
+              push(objectUpdate);
+            }
+          } else if (
+            objectUpdate &&
+            matchObject(objectUpdate.object) &&
+            (this.options.omniscient ||
+              isActorAllowedGraffitiObject(objectUpdate.object, session))
+          ) {
+            // Deep clone the object to prevent mutation
+            const object = JSON.parse(
+              JSON.stringify(objectUpdate.object),
+            ) as GraffitiObjectBase;
+            if (!this.options.omniscient) {
+              maskGraffitiObject(object, channels, session);
+            }
+            if (validate(object)) {
+              push({ object });
+              seenUrls.add(object.url);
             }
           }
         };
@@ -183,13 +177,15 @@ export class GraffitiSynchronize extends Graffiti {
       },
     );
 
-    return repeater;
+    return (async function* () {
+      for await (const i of repeater) yield i;
+    })();
   }
 
   /**
    * This method has the same signature as {@link discover} but listens for
-   * changes made via {@link put}, {@link patch}, and {@link delete} or
-   * fetched from {@link get}, {@link discover}, and {@link recoverOrphans}
+   * changes made via {@link post} and {@link delete} or
+   * fetched from {@link get}, {@link discover}, and {@link continueDiscover}
    * and then streams appropriate changes to provide a responsive and
    * consistent user experience.
    *
@@ -197,12 +193,13 @@ export class GraffitiSynchronize extends Graffiti {
    * and will not terminate unless the user calls the `return` method on the iterator
    * or `break`s out of the loop.
    *
-   * @group Synchronize Methods
+   * @group 0 - Synchronize Methods
    */
   synchronizeDiscover<Schema extends JSONSchema>(
-    ...args: Parameters<typeof Graffiti.prototype.discover<Schema>>
+    channels: string[],
+    schema: Schema,
+    session?: GraffitiSession | null,
   ): AsyncGenerator<GraffitiObjectStreamContinueEntry<Schema>> {
-    const [channels, schema, session] = args;
     function matchObject(object: GraffitiObjectBase) {
       return object.channels.some((channel) => channels.includes(channel));
     }
@@ -211,48 +208,32 @@ export class GraffitiSynchronize extends Graffiti {
 
   /**
    * This method has the same signature as {@link get} but
-   * listens for changes made via {@link put}, {@link patch}, and {@link delete} or
-   * fetched from {@link get}, {@link discover}, and {@link recoverOrphans} and then
+   * listens for changes made via {@link post}, and {@link delete} or
+   * fetched from {@link get}, {@link discover}, and {@link continueDiscover} and then
    * streams appropriate changes to provide a responsive and consistent user experience.
    *
    * Unlike {@link get}, which returns a single result, this method continuously
    * listens for changes which are output as an asynchronous stream, similar
    * to {@link discover}.
    *
-   * @group Synchronize Methods
+   * @group 0 - Synchronize Methods
    */
   synchronizeGet<Schema extends JSONSchema>(
-    ...args: Parameters<typeof Graffiti.prototype.get<Schema>>
+    objectUrl: string | GraffitiObjectUrl,
+    schema: Schema,
+    session?: GraffitiSession | null | undefined,
   ): AsyncGenerator<GraffitiObjectStreamContinueEntry<Schema>> {
-    const [objectUrl, schema, session] = args;
     const url = unpackObjectUrl(objectUrl);
     function matchObject(object: GraffitiObjectBase) {
       return object.url === url;
     }
-    return this.synchronize<Schema>(matchObject, [], schema, session);
-  }
-
-  /**
-   * This method has the same signature as {@link recoverOrphans} but
-   * listens for changes made via
-   * {@link put}, {@link patch}, and {@link delete} or fetched from
-   * {@link get}, {@link discover}, and {@link recoverOrphans} and then
-   * streams appropriate changes to provide a responsive and consistent user experience.
-   *
-   * Unlike {@link recoverOrphans}, this method continuously listens for changes
-   * and will not terminate unless the user calls the `return` method on the iterator
-   * or `break`s out of the loop.
-   *
-   * @group Synchronize Methods
-   */
-  synchronizeRecoverOrphans<Schema extends JSONSchema>(
-    ...args: Parameters<typeof Graffiti.prototype.recoverOrphans<Schema>>
-  ): AsyncGenerator<GraffitiObjectStreamContinueEntry<Schema>> {
-    const [schema, session] = args;
-    function matchObject(object: GraffitiObjectBase) {
-      return object.actor === session.actor && object.channels.length === 0;
-    }
-    return this.synchronize<Schema>(matchObject, [], schema, session);
+    return this.synchronize<Schema>(
+      matchObject,
+      [],
+      schema,
+      session,
+      new Set<string>([url]),
+    );
   }
 
   /**
@@ -264,6 +245,8 @@ export class GraffitiSynchronize extends Graffiti {
    *
    * Be careful using this method. Without additional filters it can
    * expose the user to content out of context.
+   *
+   * @group 0 - Synchronize Methods
    */
   synchronizeAll<Schema extends JSONSchema>(
     schema: Schema,
@@ -273,12 +256,11 @@ export class GraffitiSynchronize extends Graffiti {
   }
 
   protected async synchronizeDispatch(
-    oldObject: GraffitiObjectStreamContinueEntry<{}>,
-    newObject?: GraffitiObjectStreamContinueEntry<{}>,
+    objectUpdate: GraffitiObjectStreamContinueEntry<{}>,
     waitForListeners = false,
   ) {
     for (const callback of this.callbacks) {
-      callback(oldObject, newObject);
+      callback(objectUpdate);
     }
     if (waitForListeners) {
       // Wait for the listeners to receive
@@ -306,63 +288,43 @@ export class GraffitiSynchronize extends Graffiti {
   }
 
   get: Graffiti["get"] = async (...args) => {
-    const object = await this.graffiti.get(...args);
-    this.synchronizeDispatch({ object });
-    return object;
-  };
-
-  put: Graffiti["put"] = async (...args) => {
-    const oldObject = await this.graffiti.put<{}>(...args);
-    const partialObject = args[0];
-    const newObject: GraffitiObjectBase = {
-      ...oldObject,
-      value: partialObject.value,
-      channels: partialObject.channels,
-      allowed: partialObject.allowed,
-    };
-    await this.synchronizeDispatch(
-      {
-        tombstone: true,
-        object: oldObject,
-      },
-      {
-        object: newObject,
-      },
-      true,
-    );
-    return oldObject;
+    try {
+      const object = await this.graffiti.get(...args);
+      this.synchronizeDispatch({ object });
+      return object;
+    } catch (error) {
+      if (error instanceof GraffitiErrorNotFound) {
+        this.synchronizeDispatch({
+          tombstone: true,
+          object: { url: unpackObjectUrl(args[0]) },
+        });
+      }
+      throw error;
+    }
   };
 
-  patch: Graffiti["patch"] = async (...args) => {
-    const oldObject = await this.graffiti.patch(...args);
-    const newObject: GraffitiObjectBase = { ...oldObject };
-    for (const prop of ["value", "channels", "allowed"] as const) {
-      applyGraffitiPatch(await this.applyPatch, prop, args[0], newObject);
-    }
-    await this.synchronizeDispatch(
-      {
-        tombstone: true,
-        object: oldObject,
-      },
-      {
-        object: newObject,
-      },
-      true,
-    );
-    return oldObject;
+  post: Graffiti["post"] = async (...args) => {
+    // @ts-ignore
+    const object = await this.graffiti.post(...args);
+    await this.synchronizeDispatch({ object }, true);
+    return object;
   };
 
   delete: Graffiti["delete"] = async (...args) => {
-    const oldObject = await this.graffiti.delete(...args);
-    await this.synchronizeDispatch(
-      {
-        tombstone: true,
-        object: oldObject,
-      },
-      undefined,
-      true,
-    );
-    return oldObject;
+    const update = {
+      tombstone: true,
+      object: { url: unpackObjectUrl(args[0]) },
+    } as const;
+    try {
+      const oldObject = await this.graffiti.delete(...args);
+      await this.synchronizeDispatch(update, true);
+      return oldObject;
+    } catch (error) {
+      if (error instanceof GraffitiErrorNotFound) {
+        await this.synchronizeDispatch(update, true);
+      }
+      throw error;
+    }
   };
 
   protected objectStreamContinue<Schema extends JSONSchema>(
@@ -375,14 +337,13 @@ export class GraffitiSynchronize extends Graffiti {
         if (result.done) {
           const { continue: continue_, cursor } = result.value;
           return {
-            continue: () => this_.objectStreamContinue<Schema>(continue_()),
+            continue: (session?: GraffitiSession | null) =>
+              this_.objectStreamContinue<Schema>(continue_(session)),
             cursor,
           };
         }
         if (!result.value.error) {
-          this_.synchronizeDispatch(
-            result.value as GraffitiObjectStreamContinueEntry<{}>,
-          );
+          this_.synchronizeDispatch(result.value);
         }
         yield result.value;
       }
@@ -408,13 +369,8 @@ export class GraffitiSynchronize extends Graffiti {
     return this.objectStream<(typeof args)[1]>(iterator);
   };
 
-  recoverOrphans: Graffiti["recoverOrphans"] = (...args) => {
-    const iterator = this.graffiti.recoverOrphans(...args);
-    return this.objectStream<(typeof args)[0]>(iterator);
-  };
-
-  continueObjectStream: Graffiti["continueObjectStream"] = (...args) => {
-    // TODO!!
-    return this.graffiti.continueObjectStream(...args);
+  continueDiscover: Graffiti["continueDiscover"] = (...args) => {
+    const iterator = this.graffiti.continueDiscover(...args);
+    return this.objectStreamContinue<{}>(iterator);
   };
 }