@graffiti-garden/api 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graffiti-garden/api",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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",
@@ -29,6 +30,7 @@
   "homepage": "https://api.graffiti.garden/classes/Graffiti.html",
   "devDependencies": {
     "@types/json-schema": "^7.0.15",
+    "@types/node": "^22.10.5",
     "ajv": "^8.17.1",
     "fast-json-patch": "^3.1.1",
     "tslib": "^2.8.1",

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

@@ -6,7 +6,7 @@ import type {
   GraffitiSessionBase,
   GraffitiPutObject,
   GraffitiStream,
-} from "./types";
+} from "./2-types";
 import type { JSONSchema4 } from "json-schema";
 
 /**
@@ -131,7 +131,7 @@ 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.
@@ -191,6 +191,9 @@ 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, a
+   * {@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`}
@@ -212,17 +215,36 @@ export abstract class Graffiti {
   ): 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` operation 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 operation
+   * 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.
    *
+   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
+   * and [JSON Schema](https://json-schema.org).
+   *
    * @group Query Operations
    */
   abstract discover<Schema extends JSONSchema4>(
@@ -345,4 +367,4 @@ export abstract class Graffiti {
  * abstract, factory functions provide an easy way to
  * swap out different implementations.
  */
-export type UseGraffiti = () => Graffiti;
+export type GraffitiFactory = () => Graffiti;

package/src/3-errors.ts

@@ -0,0 +1,7 @@
+export class GraffitiErrorNotFound extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "GraffitiErrorNotFound";
+    Object.setPrototypeOf(this, GraffitiErrorNotFound.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,250 @@
+import { it, expect } from "vitest";
+import type {
+  GraffitiFactory,
+  GraffitiSessionBase,
+  GraffitiPatch,
+} from "../src/index";
+
+export const graffitiCRUDTests = (
+  useGraffiti: GraffitiFactory,
+  useSession1: () => GraffitiSessionBase,
+  useSession2: () => GraffitiSessionBase,
+) => {
+  it("put, get, delete", async () => {
+    const graffiti = useGraffiti();
+    const session = useSession1();
+    const value = {
+      something: "hello, world~ c:",
+    };
+    const channels = ["world"];
+
+    // 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();
+  });
+
+  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 bad 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();
+  });
+
+  it("put and get with empty access control", async () => {
+    const graffiti = useGraffiti();
+    const session1 = useSession1();
+    const session2 = useSession2();
+
+    const value = {
+      um: "hi",
+    };
+    const allowed = ["asdf"];
+    const channels = ["helloooo"];
+    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 = ["asdf", session2.actor, "1234"];
+    const channels = ["helloooo"];
+    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("patch channels", async () => {
+    const graffiti = useGraffiti();
+    const session = useSession1();
+
+    const putted = await graffiti.put(
+      { value: {}, channels: ["helloooo"] },
+      session,
+    );
+
+    const patch: GraffitiPatch = {
+      channels: [{ op: "replace", path: "/0", value: "goodbye" }],
+    };
+    await graffiti.patch(patch, putted, session);
+    const gotten = await graffiti.get(putted, {}, session);
+    expect(gotten.channels).toEqual(["goodbye"]);
+    await graffiti.delete(putted, session);
+  });
+};

package/tests/index.ts

@@ -0,0 +1,2 @@
+export * from "./location";
+export * from "./crud";

package/tests/{location.spec.ts → location.ts}

@@ -1,7 +1,7 @@
 import { it, expect } from "vitest";
-import type { UseGraffiti } from "../src/index";
+import type { GraffitiFactory } from "../src/index";
 
-export const locationTests = (useGraffiti: UseGraffiti) => {
+export const graffitiLocationTests = (useGraffiti: GraffitiFactory) => {
   it("url and location", async () => {
     const graffiti = useGraffiti();
     const location = {

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";
-  }
-}