@graffiti-garden/api 0.0.3 → 0.0.5

package/README.md

@@ -20,3 +20,28 @@ Then run a local server to view the documentation:
 cd docs
 npx http-server
 ```
+
+## Testing
+
+We have written a number of unit tests to verify implementations of the API with [vitest](https://vitest.dev/).
+To use them, create a test file in that ends in `*.spec.ts` and format it as follows:
+
+```typescript
+import { graffitiCRUDTests } from "@graffiti-garden/api/tests";
+
+const useGraffiti = () => new MyGraffitiImplementation();
+// Fill in with implementation-specific information
+// to provide to valid actor sessions for the tests
+// to use as identities.
+const useSession1 = () => ({ actor: "someone" });
+const useSession2 = () => ({ actor: "someoneelse" });
+
+// Run the tests
+graffitiCRUDTests(useGraffiti, useSession1, useSession2);
+```
+
+Then run the tests in the root of your directory with:
+
+```bash
+npx vitest
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graffiti-garden/api",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "The heart of Graffiti",
   "type": "module",
   "main": "src/index.ts",
@@ -17,7 +17,8 @@
   "author": "Theia Henderson",
   "license": "GPL-3.0-or-later",
   "scripts": {
-    "docs": "typedoc --options typedoc.json"
+    "docs": "typedoc --options typedoc.json",
+    "prepublishOnly": "npm install"
   },
   "repository": {
     "type": "git",

package/src/{api.ts → 1-api.ts}

@@ -3,10 +3,10 @@ import type {
   GraffitiObject,
   GraffitiObjectBase,
   GraffitiPatch,
-  GraffitiSessionBase,
+  GraffitiSession,
   GraffitiPutObject,
   GraffitiStream,
-} from "./types";
+} from "./2-types";
 import type { JSONSchema4 } from "json-schema";
 
 /**
@@ -26,10 +26,10 @@ import type { JSONSchema4 } from "json-schema";
  * other important properties (e.g. privacy, security, scalability), those properties
  * are useless if the system as a whole is unusable. Build APIs before protocols!
  *
- * The first group of methods are like standard CRUD operations that
+ * The first group of methods are like standard CRUD methods that
  * allow applications to {@link put}, {@link get}, {@link patch}, and {@link delete}
  * {@link GraffitiObjectBase} objects. The main difference between these
- * methods and standard database operations is that an {@link GraffitiObjectBase.actor | `actor`}
+ * methods and standard database methods is that an {@link GraffitiObjectBase.actor | `actor`}
  * (essentially a user) can only modify objects that they created.
  * Applications may also specify an an array of actors that are {@link GraffitiObjectBase.allowed | `allowed`}
  * to access the object and an array of {@link GraffitiObjectBase.channels | `channels`}
@@ -51,11 +51,13 @@ import type { JSONSchema4 } from "json-schema";
  * Finally, other utility functions provide simple type conversions and
  * allow users to find objects "lost" to forgotten or misspelled channels.
  *
- * @groupDescription CRUD Operations
+ * @groupDescription CRUD Methods
  * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},
  * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.
- * @groupDescription Query Operations
+ * @groupDescription Query Methods
  * Methods for retrieving multiple {@link GraffitiObjectBase | Graffiti objects} at a time.
+ * @groupDescription Session Management
+ * Methods and properties for logging in and out of a Graffiti implementation.
  * @groupDescription Utilities
  * Methods for for converting Graffiti objects to and from URIs
  * and for finding lost objects.
@@ -103,27 +105,27 @@ export abstract class Graffiti {
    * and {@link GraffitiObjectBase.source | `source`}) exactly match the location of an existing object.
    *
    * @returns The object that was replaced if one exists or an object with
-   * with a `null` {@link GraffitiObjectBase.value | `value`} if this operation
+   * with a `null` {@link GraffitiObjectBase.value | `value`} if this method
    * created a new object.
    * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}
    * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}
    * field updated to the time of replacement/creation.
    *
-   * @group CRUD Operations
+   * @group CRUD Methods
    */
   abstract put<Schema>(
     /**
      * The object to be put. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided
      * as the generic type parameter. We highly recommend providing a schema to
      * ensure that the PUT object matches subsequent {@link get} or {@link discover}
-     * operations.
+     * methods.
      */
     object: GraffitiPutObject<Schema>,
     /**
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
-    session: GraffitiSessionBase,
+    session: GraffitiSession,
   ): Promise<GraffitiObjectBase>;
 
   /**
@@ -131,12 +133,12 @@ export abstract class Graffiti {
    * If no object exists at that location or if the retrieving
    * {@link GraffitiObjectBase.actor | `actor`} is not the creator or included in
    * the object's {@link GraffitiObjectBase.allowed | `allowed`} property,
-   * an error is thrown.
+   * a {@link GraffitiErrorNotFound} is thrown.
    *
    * The retrieved object is also type-checked against the provided [JSON schema](https://json-schema.org/)
-   * otherwise an error is thrown.
+   * otherwise a {@link GraffitiErrorSchemaMismatch} is thrown.
    *
-   * @group CRUD Operations
+   * @group CRUD Methods
    */
   abstract get<Schema extends JSONSchema4>(
     /**
@@ -153,7 +155,7 @@ export abstract class Graffiti {
      * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}
      * property must be `undefined`.
      */
-    session?: GraffitiSessionBase,
+    session?: GraffitiSession,
   ): Promise<GraffitiObject<Schema>>;
 
   /**
@@ -167,7 +169,7 @@ export abstract class Graffiti {
    * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}
    * field updated to the time of deletion.
    *
-   * @group CRUD Operations
+   * @group CRUD Methods
    */
   abstract patch(
     /**
@@ -183,7 +185,7 @@ export abstract class Graffiti {
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
-    session: GraffitiSessionBase,
+    session: GraffitiSession,
   ): Promise<GraffitiObjectBase>;
 
   /**
@@ -191,13 +193,16 @@ export abstract class Graffiti {
    * The deleting {@link GraffitiObjectBase.actor | `actor`} must be the same as the
    * `actor` that created the object.
    *
+   * If the object does not exist or has already been deleted,
+   * {@link GraffitiErrorNotFound} is thrown.
+   *
    * @returns The object that was deleted if one exists or an object with
    * with a `null` {@link GraffitiObjectBase.value | `value`} otherwise.
    * The object will have a {@link GraffitiObjectBase.tombstone | `tombstone`}
    * field set to `true` and a {@link GraffitiObjectBase.lastModified | `lastModified`}
    * field updated to the time of deletion.
    *
-   * @group CRUD Operations
+   * @group CRUD Methods
    */
   abstract delete(
     /**
@@ -208,22 +213,41 @@ export abstract class Graffiti {
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
-    session: GraffitiSessionBase,
+    session: GraffitiSession,
   ): Promise<GraffitiObjectBase>;
 
   /**
-   * Returns a stream of {@link GraffitiObjectBase | objects}
-   * that are contained in at least one of the given {@link GraffitiObjectBase.channels | `channels`}
-   * and match the given [JSON Schema](https://json-schema.org)
+   * Discovers objects created by any user that are contained
+   * in at least one of the given {@link GraffitiObjectBase.channels | `channels`}
+   * and match the given [JSON Schema](https://json-schema.org).
    *
    * Objects are returned asynchronously as they are discovered but the stream
    * will end once all leads have been exhausted.
    * The method must be polled again for new objects.
    *
+   * `discover` will not return objects that the {@link GraffitiObjectBase.actor | `actor`}
+   * is not {@link GraffitiObjectBase.allowed | `allowed`} to access.
+   * If the actor is not the creator of a discovered object,
+   * the allowed list will be masked to only contain the querying actor if the
+   * allowed list is not `undefined` (public). Additionally, if the actor is not the
+   * creator of a discovered object, any {@link GraffitiObjectBase.channels | `channels`}
+   * not specified by the `discover` method will not be revealed. This masking happens
+   * before the supplied schema is applied.
+   *
+   * Since different implementations may fetch data from multiple sources there is
+   * no guarentee on the order that objects are returned in. Additionally, the method
+   * may return objects that have been deleted but with a
+   * {@link GraffitiObjectBase.tombstone | `tombstone`} field set to `true` for
+   * cache invalidation purposes. Implementations must make aware when, if ever,
+   * tombstoned objects are removed.
+   *
    * {@link discover} can be used in conjunction with {@link synchronize}
    * to provide a responsive and consistent user experience.
    *
-   * @group Query Operations
+   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
+   * and [JSON Schema](https://json-schema.org).
+   *
+   * @group Query Methods
    */
   abstract discover<Schema extends JSONSchema4>(
     /**
@@ -240,7 +264,7 @@ export abstract class Graffiti {
      * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}
      * property will be returned.
      */
-    session?: GraffitiSessionBase,
+    session?: GraffitiSession,
   ): GraffitiStream<GraffitiObject<Schema>>;
 
   /**
@@ -264,7 +288,7 @@ export abstract class Graffiti {
    * all instance's of that friend's name in the user's application instantly,
    * providing a consistent user experience.
    *
-   * @group Query Operations
+   * @group Query Methods
    */
   abstract synchronize<Schema extends JSONSchema4>(
     /**
@@ -281,7 +305,7 @@ export abstract class Graffiti {
      * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}
      * property will be returned.
      */
-    session?: GraffitiSessionBase,
+    session?: GraffitiSession,
   ): GraffitiStream<GraffitiObject<Schema>>;
 
   /**
@@ -305,7 +329,7 @@ export abstract class Graffiti {
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
-    session: GraffitiSessionBase,
+    session: GraffitiSession,
   ): GraffitiStream<{
     channel: string;
     source: string;
@@ -331,12 +355,77 @@ export abstract class Graffiti {
    * {@link GraffitiObjectBase.tombstone | `tombstone`} field is `true`
    * if the object has been deleted.
    */
-  abstract listOrphans(session: GraffitiSessionBase): GraffitiStream<{
+  abstract listOrphans(session: GraffitiSession): GraffitiStream<{
     name: string;
     source: string;
     lastModified: Date;
     tombstone: boolean;
   }>;
+
+  /**
+   * Begins the login process. Depending on the implementation, this may
+   * involve redirecting the user to a login page or opening a popup,
+   * so it should always be called in response to a user action.
+   *
+   * The {@link GraffitiSession | session} object is returned
+   * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}
+   * as a {@link GraffitiLoginEvent}.
+   *
+   * @group Session Management
+   */
+  abstract login(
+    /**
+     * An optional actor to prompt the user to login as. For example,
+     * if a session expired and the user is trying to reauthenticate,
+     * or if the user entered their username in an application-side login form.
+     *
+     * If not provided, the implementation should prompt the user to
+     * supply an actor ID along with their other login information
+     * (e.g. password).
+     */
+    actor?: string,
+    /**
+     * An arbitrary string that will be returned with the
+     * {@link GraffitiSession | session} object
+     * when the login process is complete.
+     * See {@link GraffitiLoginEvent}.
+     */
+    state?: string,
+  ): Promise<void>;
+
+  /**
+   * Begins the logout process. Depending on the implementation, this may
+   * involve redirecting the user to a logout page or opening a popup,
+   * so it should always be called in response to a user action.
+   *
+   * A confirmation will be returned asynchronously via
+   * {@link Graffiti.sessionEvents | sessionEvents}
+   * as a {@link GraffitiLogoutEvent}.
+   *
+   * @group Session Management
+   */
+  abstract logout(
+    /**
+     * The {@link GraffitiSession | session} object to logout.
+     */
+    session: GraffitiSession,
+    /**
+     * An arbitrary string that will be returned with the
+     * when the logout process is complete.
+     * See {@link GraffitiLogoutEvent}.
+     */
+    state?: string,
+  ): Promise<void>;
+
+  /**
+   * An event target that can be used to listen for `login`
+   * and `logout` events. They are custom events of types
+   * {@link GraffitiLoginEvent`} and {@link GraffitiLogoutEvent }
+   * respectively.
+   *
+   * @group Session Management
+   */
+  abstract readonly sessionEvents: EventTarget;
 }
 
 /**

package/src/{types.ts → 2-types.ts}

@@ -146,7 +146,7 @@ export type GraffitiLocation = Pick<
  * {@link GraffitiObjectBase.name | `name`}, and {@link GraffitiObjectBase.source | `source`}.
  * If the location provided exactly matches an existing object, the existing object will be replaced.
  * If no `name` is provided, one will be randomly generated.
- * If no `actor` is provided, the `actor` from the supplied {@link GraffitiSessionBase | `session` } will be used.
+ * If no `actor` is provided, the `actor` from the supplied {@link GraffitiSession | `session` } will be used.
  * If no `source` is provided, one may be inferred by the depending on implementation.
  *
  * This object does not need a {@link GraffitiObjectBase.lastModified | `lastModified`} or {@link GraffitiObjectBase.tombstone | `tombstone`}
@@ -168,7 +168,7 @@ export type GraffitiPutObject<Schema> = Pick<
  * that modify objects and optional for methods that read objects.
  *
  * At a minimum the `session` object must contain the
- * {@link GraffitiSessionBase.actor | `actor`} URI the user wants to authenticate with.
+ * {@link GraffitiSession.actor | `actor`} URI the user wants to authenticate with.
  * However it is likely that the `session` object must contain other
  * implementation-specific properties.
  * For example, a Solid implementation might include a
@@ -179,7 +179,7 @@ export type GraffitiPutObject<Schema> = Pick<
  * It may also include other implementation specific properties
  * that provide hints for performance or security.
  */
-export interface GraffitiSessionBase {
+export interface GraffitiSession {
   /**
    * The {@link GraffitiObjectBase.actor | `actor`} a user wants to authenticate with.
    */
@@ -241,14 +241,45 @@ export interface GraffitiPatch {
  */
 export type GraffitiStream<T> = AsyncGenerator<
   | {
-      error: false;
+      error?: undefined;
       value: T;
     }
   | {
-      error: true;
-      value: Error;
+      error: Error;
       source: string;
     },
-  void,
   void
 >;
+
+/**
+ * The event type produced in {@link Graffiti.sessionEvents}
+ * when a user logs in manually from {@link Graffiti.login}
+ * or when their session is restored from a previous login.
+ * The event name to listen for is `login`.
+ */
+export type GraffitiLoginEvent = CustomEvent<
+  {
+    state?: string;
+  } & (
+    | {
+        error: Error;
+        session?: undefined;
+      }
+    | {
+        error?: undefined;
+        session: GraffitiSession;
+      }
+  )
+>;
+
+/**
+ * The event type produced in {@link Graffiti.sessionEvents}
+ * when a user logs out either manually with {@link Graffiti.logout}
+ * or when their session times out or otherwise becomes invalid.
+ * The event name to listen for is `logout`.
+ */
+export type GraffitiLogoutEvent = CustomEvent<{
+  actor: string;
+  state?: string;
+  error?: Error;
+}>;

package/src/3-errors.ts

@@ -0,0 +1,63 @@
+export class GraffitiErrorUnauthorized extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorUnauthorized";
+    Object.setPrototypeOf(this, GraffitiErrorUnauthorized.prototype);
+  }
+}
+
+export class GraffitiErrorForbidden extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorForbidden";
+    Object.setPrototypeOf(this, GraffitiErrorForbidden.prototype);
+  }
+}
+
+export class GraffitiErrorNotFound extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorNotFound";
+    Object.setPrototypeOf(this, GraffitiErrorNotFound.prototype);
+  }
+}
+
+export class GraffitiErrorInvalidSchema extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorInvalidSchema";
+    Object.setPrototypeOf(this, GraffitiErrorInvalidSchema.prototype);
+  }
+}
+
+export class GraffitiErrorSchemaMismatch extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorSchemaMismatch";
+    Object.setPrototypeOf(this, GraffitiErrorSchemaMismatch.prototype);
+  }
+}
+
+export class GraffitiErrorPatchTestFailed extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorPatchTestFailed";
+    Object.setPrototypeOf(this, GraffitiErrorPatchTestFailed.prototype);
+  }
+}
+
+export class GraffitiErrorPatchError extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorPatchError";
+    Object.setPrototypeOf(this, GraffitiErrorPatchError.prototype);
+  }
+}
+
+export class GraffitiErrorInvalidUri extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorInvalidUri";
+    Object.setPrototypeOf(this, GraffitiErrorInvalidUri.prototype);
+  }
+}

package/src/index.ts

@@ -1,3 +1,4 @@
-export * from "./types";
+export * from "./1-api";
+export * from "./2-types";
+export * from "./3-errors";
 export type { JSONSchema4 } from "json-schema";
-export * from "./api";

package/tests/crud.ts

@@ -0,0 +1,483 @@
+import { it, expect, describe } from "vitest";
+import {
+  type GraffitiFactory,
+  type GraffitiSession,
+  type GraffitiPatch,
+  GraffitiErrorNotFound,
+  GraffitiErrorSchemaMismatch,
+  GraffitiErrorInvalidSchema,
+  GraffitiErrorForbidden,
+  GraffitiErrorPatchTestFailed,
+  GraffitiErrorPatchError,
+} from "../src/index";
+import { randomPutObject, randomString } from "./utils";
+
+export const graffitiCRUDTests = (
+  useGraffiti: GraffitiFactory,
+  useSession1: () => GraffitiSession,
+  useSession2: () => GraffitiSession,
+) => {
+  describe("CRUD", () => {
+    it("put, get, delete", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+      const value = {
+        something: "hello, world~ c:",
+      };
+      const channels = [randomString(), randomString()];
+
+      // Put the object
+      const previous = await graffiti.put({ value, channels }, session);
+      expect(previous.value).toEqual({});
+      expect(previous.channels).toEqual([]);
+      expect(previous.allowed).toBeUndefined();
+      expect(previous.actor).toEqual(session.actor);
+
+      // Get it back
+      const gotten = await graffiti.get(previous, {});
+      expect(gotten.value).toEqual(value);
+      expect(gotten.channels).toEqual([]);
+      expect(gotten.allowed).toBeUndefined();
+      expect(gotten.name).toEqual(previous.name);
+      expect(gotten.actor).toEqual(previous.actor);
+      expect(gotten.source).toEqual(previous.source);
+      expect(gotten.lastModified.getTime()).toEqual(
+        previous.lastModified.getTime(),
+      );
+
+      // Replace it
+      const newValue = {
+        something: "goodbye, world~ :c",
+      };
+      const beforeReplaced = await graffiti.put(
+        { ...previous, value: newValue, channels: [] },
+        session,
+      );
+      expect(beforeReplaced.value).toEqual(value);
+      expect(beforeReplaced.tombstone).toEqual(true);
+      expect(beforeReplaced.name).toEqual(previous.name);
+      expect(beforeReplaced.actor).toEqual(previous.actor);
+      expect(beforeReplaced.source).toEqual(previous.source);
+      expect(beforeReplaced.lastModified.getTime()).toBeGreaterThan(
+        gotten.lastModified.getTime(),
+      );
+
+      // Get it again
+      const afterReplaced = await graffiti.get(previous, {});
+      expect(afterReplaced.value).toEqual(newValue);
+      expect(afterReplaced.lastModified.getTime()).toEqual(
+        beforeReplaced.lastModified.getTime(),
+      );
+      expect(afterReplaced.tombstone).toEqual(false);
+
+      // Delete it
+      const beforeDeleted = await graffiti.delete(afterReplaced, session);
+      expect(beforeDeleted.tombstone).toEqual(true);
+      expect(beforeDeleted.value).toEqual(newValue);
+      expect(beforeDeleted.lastModified.getTime()).toBeGreaterThan(
+        beforeReplaced.lastModified.getTime(),
+      );
+
+      // Try to get it and fail
+      await expect(graffiti.get(afterReplaced, {})).rejects.toThrow(
+        GraffitiErrorNotFound,
+      );
+    });
+
+    it("put, get, delete with wrong actor", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      await expect(
+        graffiti.put(
+          { value: {}, channels: [], actor: session2.actor },
+          session1,
+        ),
+      ).rejects.toThrow(GraffitiErrorForbidden);
+
+      await expect(
+        graffiti.delete(
+          {
+            name: "asdf",
+            source: "asdf",
+            actor: session2.actor,
+          },
+          session1,
+        ),
+      ).rejects.toThrow(GraffitiErrorForbidden);
+
+      await expect(
+        graffiti.patch(
+          {},
+          {
+            name: "asdf",
+            source: "asdf",
+            actor: session2.actor,
+          },
+          session1,
+        ),
+      ).rejects.toThrow(GraffitiErrorForbidden);
+    });
+
+    it("put and get with schema", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const schema = {
+        properties: {
+          value: {
+            properties: {
+              something: {
+                type: "string",
+              },
+              another: {
+                type: "integer",
+              },
+            },
+          },
+        },
+      } as const;
+
+      const goodValue = {
+        something: "hello",
+        another: 42,
+      } as const;
+
+      const putted = await graffiti.put<typeof schema>(
+        {
+          value: goodValue,
+          channels: [],
+        },
+        session,
+      );
+
+      const gotten = await graffiti.get(putted, schema);
+      expect(gotten.value.something).toEqual(goodValue.something);
+      expect(gotten.value.another).toEqual(goodValue.another);
+    });
+
+    it("put and get with invalid schema", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const putted = await graffiti.put({ value: {}, channels: [] }, session);
+      await expect(
+        graffiti.get(putted, {
+          properties: {
+            value: {
+              //@ts-ignore
+              type: "asdf",
+            },
+          },
+        }),
+      ).rejects.toThrow(GraffitiErrorInvalidSchema);
+    });
+
+    it("put and get with wrong schema", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const putted = await graffiti.put(
+        {
+          value: {
+            hello: "world",
+          },
+          channels: [],
+        },
+        session,
+      );
+
+      await expect(
+        graffiti.get(putted, {
+          properties: {
+            value: {
+              properties: {
+                hello: {
+                  type: "number",
+                },
+              },
+            },
+          },
+        }),
+      ).rejects.toThrow(GraffitiErrorSchemaMismatch);
+    });
+
+    it("put and get with empty access control", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      const value = {
+        um: "hi",
+      };
+      const allowed = [randomString()];
+      const channels = [randomString()];
+      const putted = await graffiti.put({ value, allowed, channels }, session1);
+
+      // Get it with authenticated session
+      const gotten = await graffiti.get(putted, {}, session1);
+      expect(gotten.value).toEqual(value);
+      expect(gotten.allowed).toEqual(allowed);
+      expect(gotten.channels).toEqual(channels);
+
+      // But not without session
+      await expect(graffiti.get(putted, {})).rejects.toThrow();
+
+      // Or the wrong session
+      await expect(graffiti.get(putted, {}, session2)).rejects.toThrow();
+    });
+
+    it("put and get with specific access control", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      const value = {
+        um: "hi",
+      };
+      const allowed = [randomString(), session2.actor, randomString()];
+      const channels = [randomString()];
+      const putted = await graffiti.put(
+        {
+          value,
+          allowed,
+          channels,
+        },
+        session1,
+      );
+
+      // Get it with authenticated session
+      const gotten = await graffiti.get(putted, {}, session1);
+      expect(gotten.value).toEqual(value);
+      expect(gotten.allowed).toEqual(allowed);
+      expect(gotten.channels).toEqual(channels);
+
+      // But not without session
+      await expect(graffiti.get(putted, {})).rejects.toThrow();
+
+      const gotten2 = await graffiti.get(putted, {}, session2);
+      expect(gotten2.value).toEqual(value);
+      // They should only see that is is private to them
+      expect(gotten2.allowed).toEqual([session2.actor]);
+      // And not see any channels
+      expect(gotten2.channels).toEqual([]);
+    });
+
+    it("patch value", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const value = {
+        something: "hello, world~ c:",
+      };
+      const putted = await graffiti.put({ value, channels: [] }, session);
+
+      const patch: GraffitiPatch = {
+        value: [
+          { op: "replace", path: "/something", value: "goodbye, world~ :c" },
+        ],
+      };
+      const beforePatched = await graffiti.patch(patch, putted, session);
+      expect(beforePatched.value).toEqual(value);
+      expect(beforePatched.tombstone).toBe(true);
+
+      const gotten = await graffiti.get(putted, {});
+      expect(gotten.value).toEqual({
+        something: "goodbye, world~ :c",
+      });
+      expect(beforePatched.lastModified.getTime()).toBe(
+        gotten.lastModified.getTime(),
+      );
+
+      await graffiti.delete(putted, session);
+    });
+
+    it("deep patch", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const value = {
+        something: {
+          another: {
+            somethingElse: "hello",
+          },
+        },
+      };
+      const putted = await graffiti.put(
+        { value: value, channels: [] },
+        session,
+      );
+
+      const beforePatch = await graffiti.patch(
+        {
+          value: [
+            {
+              op: "replace",
+              path: "/something/another/somethingElse",
+              value: "goodbye",
+            },
+          ],
+        },
+        putted,
+        session,
+      );
+      const gotten = await graffiti.get(putted, {});
+
+      expect(beforePatch.value).toEqual(value);
+      expect(gotten.value).toEqual({
+        something: {
+          another: {
+            somethingElse: "goodbye",
+          },
+        },
+      });
+    });
+
+    it("patch channels", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const channelsBefore = [randomString()];
+      const channelsAfter = [randomString()];
+
+      const putted = await graffiti.put(
+        { value: {}, channels: channelsBefore },
+        session,
+      );
+
+      const patch: GraffitiPatch = {
+        channels: [{ op: "replace", path: "/0", value: channelsAfter[0] }],
+      };
+      const patched = await graffiti.patch(patch, putted, session);
+      expect(patched.channels).toEqual(channelsBefore);
+      const gotten = await graffiti.get(putted, {}, session);
+      expect(gotten.channels).toEqual(channelsAfter);
+      await graffiti.delete(putted, session);
+    });
+
+    it("patch 'increment' with test", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const putted = await graffiti.put(
+        {
+          value: {
+            counter: 1,
+          },
+          channels: [],
+        },
+        session,
+      );
+
+      const previous = await graffiti.patch(
+        {
+          value: [
+            { op: "test", path: "/counter", value: 1 },
+            { op: "replace", path: "/counter", value: 2 },
+          ],
+        },
+        putted,
+        session,
+      );
+      expect(previous.value).toEqual({ counter: 1 });
+      const result = await graffiti.get(previous, {
+        properties: {
+          value: {
+            properties: {
+              counter: {
+                type: "integer",
+              },
+            },
+          },
+        },
+      });
+      expect(result.value.counter).toEqual(2);
+
+      await expect(
+        graffiti.patch(
+          {
+            value: [
+              { op: "test", path: "/counter", value: 1 },
+              { op: "replace", path: "/counter", value: 3 },
+            ],
+          },
+          putted,
+          session,
+        ),
+      ).rejects.toThrow(GraffitiErrorPatchTestFailed);
+    });
+
+    it("invalid patch", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+      const object = randomPutObject();
+      const putted = await graffiti.put(object, session);
+
+      await expect(
+        graffiti.patch(
+          {
+            value: [
+              { op: "add", path: "/root", value: [] },
+              { op: "add", path: "/root/2", value: 2 }, // out of bounds
+            ],
+          },
+          putted,
+          session,
+        ),
+      ).rejects.toThrow(GraffitiErrorPatchError);
+    });
+
+    it("patch channels to be wrong", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+      const object = randomPutObject();
+      object.allowed = [randomString()];
+      const putted = await graffiti.put(object, session);
+
+      const patches: GraffitiPatch[] = [
+        {
+          channels: [{ op: "replace", path: "", value: null }],
+        },
+        {
+          channels: [{ op: "replace", path: "", value: {} }],
+        },
+        {
+          channels: [{ op: "replace", path: "", value: ["hello", ["hi"]] }],
+        },
+        {
+          channels: [{ op: "add", path: "/0", value: 1 }],
+        },
+        {
+          value: [{ op: "replace", path: "", value: "not an object" }],
+        },
+        {
+          value: [{ op: "replace", path: "", value: null }],
+        },
+        {
+          value: [{ op: "replace", path: "", value: [] }],
+        },
+        {
+          allowed: [{ op: "replace", path: "", value: {} }],
+        },
+        {
+          allowed: [{ op: "replace", path: "", value: ["hello", ["hi"]] }],
+        },
+      ];
+
+      for (const patch of patches) {
+        await expect(graffiti.patch(patch, putted, session)).rejects.toThrow(
+          GraffitiErrorPatchError,
+        );
+      }
+
+      const gotten = await graffiti.get(putted, {}, session);
+      expect(gotten.value).toEqual(object.value);
+      expect(gotten.channels).toEqual(object.channels);
+      expect(gotten.allowed).toEqual(object.allowed);
+      expect(gotten.lastModified.getTime()).toEqual(
+        putted.lastModified.getTime(),
+      );
+    });
+  });
+};

package/tests/discover.ts

@@ -0,0 +1,32 @@
+import { it, expect, describe } from "vitest";
+import { type GraffitiFactory, type GraffitiSession } from "../src/index";
+import { randomString, randomValue, randomPutObject } from "./utils";
+
+export const graffitiDiscoverTests = (
+  useGraffiti: GraffitiFactory,
+  useSession1: () => GraffitiSession,
+  useSession2: () => GraffitiSession,
+) => {
+  describe("discover", () => {
+    it("discover single", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+      const object = randomPutObject();
+
+      const putted = await graffiti.put(object, session);
+
+      const queryChannels = [randomString(), object.channels[0]];
+      const iterator = graffiti.discover(queryChannels, {});
+      const result = (await iterator.next()).value;
+      if (!result || result.error) throw new Error();
+      expect(result.value.value).toEqual(object.value);
+      expect(result.value.channels).toEqual([object.channels[0]]);
+      expect(result.value.allowed).toBeUndefined();
+      expect(result.value.actor).toEqual(session.actor);
+      expect(result.value.tombstone).toBe(false);
+      expect(result.value.lastModified).toEqual(putted.lastModified);
+      const result2 = await iterator.next();
+      expect(result2.done).toBe(true);
+    });
+  });
+};

package/tests/index.ts

@@ -1 +1,4 @@
 export * from "./location";
+export * from "./crud";
+export * from "./synchronize";
+export * from "./discover";

package/tests/location.ts

@@ -1,16 +1,39 @@
-import { it, expect } from "vitest";
-import type { GraffitiFactory } from "../src/index";
+import { it, expect, describe } from "vitest";
+import { GraffitiErrorInvalidUri, type GraffitiFactory } from "../src/index";
+import { randomString } from "./utils";
 
 export const graffitiLocationTests = (useGraffiti: GraffitiFactory) => {
-  it("url and location", async () => {
-    const graffiti = useGraffiti();
-    const location = {
-      name: "12345",
-      actor: "https://example.com/actor",
-      source: "https://example.com/source",
-    };
-    const uri = graffiti.locationToUri(location);
-    const location2 = graffiti.uriToLocation(uri);
-    expect(location).toEqual(location2);
+  describe("URI and location conversion", () => {
+    it("location to uri and back", async () => {
+      const graffiti = useGraffiti();
+      const location = {
+        name: randomString(),
+        actor: randomString(),
+        source: randomString(),
+      };
+      const uri = graffiti.locationToUri(location);
+      const location2 = graffiti.uriToLocation(uri);
+      expect(location).toEqual(location2);
+    });
+
+    it("collision resistance", async () => {
+      const graffiti = useGraffiti();
+      const location1 = {
+        name: randomString(),
+        actor: randomString(),
+        source: randomString(),
+      };
+      for (const prop of ["name", "actor", "source"] as const) {
+        const location2 = { ...location1, [prop]: randomString() };
+        const uri1 = graffiti.locationToUri(location1);
+        const uri2 = graffiti.locationToUri(location2);
+        expect(uri1).not.toEqual(uri2);
+      }
+    });
+
+    it("random URI should not be a valid location", async () => {
+      const graffiti = useGraffiti();
+      expect(() => graffiti.uriToLocation("")).toThrow(GraffitiErrorInvalidUri);
+    });
   });
 };

package/tests/synchronize.ts

@@ -0,0 +1,262 @@
+import { it, expect, describe } from "vitest";
+import { type GraffitiFactory, type GraffitiSession } from "../src/index";
+import { randomPutObject, randomString } from "./utils";
+import { randomInt } from "crypto";
+
+export const graffitiSynchronizeTests = (
+  useGraffiti: GraffitiFactory,
+  useSession1: () => GraffitiSession,
+  useSession2: () => GraffitiSession,
+) => {
+  describe("synchronize", () => {
+    it("get", async () => {
+      const graffiti1 = useGraffiti();
+      const session = useSession1();
+
+      const object = randomPutObject();
+      const channels = object.channels.slice(1);
+      const putted = await graffiti1.put(object, session);
+
+      const graffiti2 = useGraffiti();
+      const next = graffiti2.synchronize(channels, {}).next();
+      const gotten = await graffiti2.get(putted, {}, session);
+
+      const result = (await next).value;
+      if (!result || result.error) {
+        throw new Error("Error in synchronize");
+      }
+      expect(result.value.value).toEqual(object.value);
+      expect(result.value.channels).toEqual(channels);
+      expect(result.value.tombstone).toBe(false);
+      expect(result.value.lastModified.getTime()).toEqual(
+        gotten.lastModified.getTime(),
+      );
+    });
+
+    it("put", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const beforeChannel = randomString();
+      const afterChannel = randomString();
+      const sharedChannel = randomString();
+
+      const oldValue = { hello: "world" };
+      const oldChannels = [beforeChannel, sharedChannel];
+      const putted = await graffiti.put(
+        {
+          value: oldValue,
+          channels: oldChannels,
+        },
+        session,
+      );
+
+      // Start listening for changes...
+      const before = graffiti.synchronize([beforeChannel], {}).next();
+      const after = graffiti.synchronize([afterChannel], {}).next();
+      const shared = graffiti.synchronize([sharedChannel], {}).next();
+
+      // Replace the object
+      const newValue = { goodbye: "world" };
+      const newChannels = [afterChannel, sharedChannel];
+      await graffiti.put(
+        {
+          ...putted,
+          value: newValue,
+          channels: newChannels,
+        },
+        session,
+      );
+
+      const beforeResult = (await before).value;
+      const afterResult = (await after).value;
+      const sharedResult = (await shared).value;
+      if (
+        !beforeResult ||
+        beforeResult.error ||
+        !afterResult ||
+        afterResult.error ||
+        !sharedResult ||
+        sharedResult.error
+      ) {
+        throw new Error("Error in synchronize");
+      }
+
+      expect(beforeResult.value.value).toEqual(oldValue);
+      expect(beforeResult.value.channels).toEqual([beforeChannel]);
+      expect(beforeResult.value.tombstone).toBe(true);
+      expect(afterResult.value.value).toEqual(newValue);
+      expect(afterResult.value.channels).toEqual([afterChannel]);
+      expect(afterResult.value.tombstone).toBe(false);
+      expect(sharedResult.value.value).toEqual(newValue);
+      expect(sharedResult.value.channels).toEqual([sharedChannel]);
+      expect(sharedResult.value.tombstone).toBe(false);
+      expect(beforeResult.value.lastModified.getTime()).toEqual(
+        afterResult.value.lastModified.getTime(),
+      );
+      expect(sharedResult.value.lastModified.getTime()).toEqual(
+        afterResult.value.lastModified.getTime(),
+      );
+    });
+
+    it("patch", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const beforeChannel = randomString();
+      const afterChannel = randomString();
+      const sharedChannel = randomString();
+
+      const oldValue = { hello: "world" };
+      const oldChannels = [beforeChannel, sharedChannel];
+      const putted = await graffiti.put(
+        {
+          value: oldValue,
+          channels: oldChannels,
+        },
+        session,
+      );
+
+      // Start listening for changes...
+      const before = graffiti.synchronize([beforeChannel], {}).next();
+      const after = graffiti.synchronize([afterChannel], {}).next();
+      const shared = graffiti.synchronize([sharedChannel], {}).next();
+
+      await graffiti.patch(
+        {
+          value: [
+            {
+              op: "add",
+              path: "/something",
+              value: "new value",
+            },
+          ],
+          channels: [
+            {
+              op: "add",
+              path: "/-",
+              value: afterChannel,
+            },
+            {
+              op: "remove",
+              path: `/${oldChannels.indexOf(beforeChannel)}`,
+            },
+          ],
+        },
+        putted,
+        session,
+      );
+
+      const beforeResult = (await before).value;
+      const afterResult = (await after).value;
+      const sharedResult = (await shared).value;
+      if (
+        !beforeResult ||
+        beforeResult.error ||
+        !afterResult ||
+        afterResult.error ||
+        !sharedResult ||
+        sharedResult.error
+      ) {
+        throw new Error("Error in synchronize");
+      }
+
+      const newValue = { ...oldValue, something: "new value" };
+      const newChannels = [sharedChannel, afterChannel];
+      expect(beforeResult.value.value).toEqual(oldValue);
+      expect(beforeResult.value.channels).toEqual([beforeChannel]);
+      expect(beforeResult.value.tombstone).toBe(true);
+      expect(afterResult.value.value).toEqual(newValue);
+      expect(afterResult.value.channels).toEqual([afterChannel]);
+      expect(afterResult.value.tombstone).toBe(false);
+      expect(sharedResult.value.value).toEqual(newValue);
+      expect(sharedResult.value.channels).toEqual([sharedChannel]);
+      expect(sharedResult.value.tombstone).toBe(false);
+      expect(beforeResult.value.lastModified.getTime()).toEqual(
+        afterResult.value.lastModified.getTime(),
+      );
+      expect(sharedResult.value.lastModified.getTime()).toEqual(
+        afterResult.value.lastModified.getTime(),
+      );
+    });
+
+    it("delete", async () => {
+      const graffiti = useGraffiti();
+      const session = useSession1();
+
+      const channels = [randomString(), randomString(), randomString()];
+
+      const oldValue = { hello: "world" };
+      const oldChannels = [randomString(), ...channels.slice(1)];
+      const putted = await graffiti.put(
+        {
+          value: oldValue,
+          channels: oldChannels,
+        },
+        session,
+      );
+
+      const next = graffiti.synchronize(channels, {}).next();
+
+      graffiti.delete(putted, session);
+
+      const result = (await next).value;
+      if (!result || result.error) {
+        throw new Error("Error in synchronize");
+      }
+      expect(result.value.tombstone).toBe(true);
+      expect(result.value.value).toEqual(oldValue);
+      expect(result.value.channels).toEqual(
+        channels.filter((c) => oldChannels.includes(c)),
+      );
+    });
+
+    it("not allowed", async () => {
+      const graffiti = useGraffiti();
+      const session1 = useSession1();
+      const session2 = useSession2();
+
+      const allChannels = [randomString(), randomString(), randomString()];
+      const channels = allChannels.slice(1);
+
+      const creatorNext = graffiti.synchronize(channels, {}, session1).next();
+      const allowedNext = graffiti.synchronize(channels, {}, session2).next();
+      const noSession = graffiti.synchronize(channels, {}).next();
+
+      const value = {
+        hello: "world",
+      };
+      const allowed = [randomString(), session2.actor];
+      await graffiti.put({ value, channels: allChannels, allowed }, session1);
+
+      // Expect no session to time out!
+      await expect(
+        Promise.race([
+          noSession,
+          new Promise((resolve, rejects) =>
+            setTimeout(rejects, 100, "Timeout"),
+          ),
+        ]),
+      ).rejects.toThrow("Timeout");
+
+      const creatorResult = (await creatorNext).value;
+      const allowedResult = (await allowedNext).value;
+
+      if (
+        !creatorResult ||
+        creatorResult.error ||
+        !allowedResult ||
+        allowedResult.error
+      ) {
+        throw new Error("Error in synchronize");
+      }
+
+      expect(creatorResult.value.value).toEqual(value);
+      expect(creatorResult.value.allowed).toEqual(allowed);
+      expect(creatorResult.value.channels).toEqual(allChannels);
+      expect(allowedResult.value.value).toEqual(value);
+      expect(allowedResult.value.allowed).toEqual([session2.actor]);
+      expect(allowedResult.value.channels).toEqual(channels);
+    });
+  });
+};

package/tests/utils.ts

@@ -0,0 +1,22 @@
+import type { GraffitiPutObject } from "../src";
+
+export function randomString(): string {
+  const array = new Uint8Array(16);
+  crypto.getRandomValues(array);
+  return Array.from(array)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function randomValue() {
+  return {
+    [randomString()]: randomString(),
+  };
+}
+
+export function randomPutObject(): GraffitiPutObject<{}> {
+  return {
+    value: randomValue(),
+    channels: [randomString(), randomString()],
+  };
+}

package/src/errors.ts

@@ -1,14 +0,0 @@
-class GraffitiUnauthorizedError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "UnauthorizedError";
-    Object.setPrototypeOf(this, GraffitiUnauthorizedError.prototype);
-  }
-}
-
-class ForbiddenError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ForbiddenError";
-  }
-}