@graffiti-garden/api 0.4.4 → 0.5.0

package/src/2-types.ts

@@ -12,9 +12,7 @@ import type { Operation as JSONPatchOperation } from "fast-json-patch";
  * or properties that emerge in the Graffiti [folksonomy](https://en.wikipedia.org/wiki/Folksonomy)
  * to promote interoperability.
  *
- * The {@link name | `name`}, {@link actor | `actor`}, and {@link source | `source`}
- * properties together uniquely describe the {@link GraffitiLocation | object's location}
- * and can be {@link Graffiti.locationToUri | converted to a globally unique URI}.
+ * The object is globally addressable via its {@link uri | `uri`}.
  *
  * The {@link channels | `channels`} and {@link allowed | `allowed`} properties
  * enable the object's creator to shape the visibility of and access to their object.
@@ -78,21 +76,23 @@ export interface GraffitiObjectBase {
   actor: string;
 
   /**
-   * A name for the object. This name is not globally unique but it is unique when
-   * combined with the {@link actor | `actor`} and {@link source | `source`}.
-   * Often times it is not specified by the user and randomly generated during {@link Graffiti.put | creation}.
-   * If an object is created with the same `name`, `actor`, and `source` as an existing object,
-   * the existing object will be replaced with the new object.
-   */
-  name: string;
-
-  /**
-   * The URI of the source that stores the object. In some decentralized implementations,
-   * it can represent the server or [pod](https://en.wikipedia.org/wiki/Solid_(web_decentralization_project)#Design)
-   * that a user has delegated to store their objects. In others it may represent the distributed
-   * storage network that the object is stored on.
+   * A globally unique identifier for the object. It can be used to point to
+   * an object or to retrieve the object directly with {@link Graffiti.get}.
+   * If an object is {@link Graffiti.put | put} with the same URI
+   * as an existing object, the existing object will be replaced with the new object.
+   *
+   * The URI is generated on creation and include sufficient randomness to prevent collisions
+   * and guessing. The URI starts with "scheme", just like web URLs start with `http` or `https`, to indicate
+   * to indicate the particular Graffiti implementation. This allows for applications
+   * to pull from multiple coexisting Graffiti implementations without collision.
+   * Existing schemes include `graffiti:local:` for objects stored locally
+   * (see the [local implementation](https://github.com/graffiti-garden/implementation-local))
+   * and `graffiti:remote:` for objects stored on Graffiti-specific web servers (see the
+   * [remote implementation](https://github.com/graffiti-garden/implementation-remote)).
+   * Options available in the future might include `graffiti:solid:` for objects stored on Solid servers
+   * or `graffiti:p2p:` for objects stored on a peer-to-peer network.
    */
-  source: string;
+  uri: string;
 
   /**
    * The time the object was last modified, measured in milliseconds since January 1, 1970.
@@ -135,38 +135,23 @@ export const GraffitiObjectJSONSchema = {
     value: { type: "object" },
     channels: { type: "array", items: { type: "string" } },
     allowed: { type: "array", items: { type: "string" }, nullable: true },
+    uri: { type: "string" },
     actor: { type: "string" },
-    name: { type: "string" },
-    source: { type: "string" },
     lastModified: { type: "number" },
     tombstone: { type: "boolean" },
   },
   additionalProperties: false,
-  required: [
-    "value",
-    "channels",
-    "actor",
-    "name",
-    "source",
-    "lastModified",
-    "tombstone",
-  ],
+  required: ["value", "channels", "actor", "uri", "lastModified", "tombstone"],
 } as const satisfies JSONSchema;
 
 /**
- * This is a subset of properties from {@link GraffitiObjectBase} that uniquely
- * identify an object's location: {@link GraffitiObjectBase.actor | `actor`},
- * {@link GraffitiObjectBase.name | `name`}, and {@link GraffitiObjectBase.source | `source`}.
- * Attempts to create an object with the same `actor`, `name`, and `source`
- * as an existing object will replace the existing object (see {@link Graffiti.put}).
- *
- * This location can be converted to
- * a globally unique URI using {@link Graffiti.locationToUri}.
+ * This is an object containing only the {@link GraffitiObjectBase.uri | `uri`}
+ * property of a {@link GraffitiObjectBase | GraffitiObject}.
+ * It is used as a utility type so that users can call {@link Graffiti.get},
+ * {@link Graffiti.patch}, or {@link Graffiti.delete} directly on an object
+ * rather than on `object.uri`.
  */
-export type GraffitiLocation = Pick<
-  GraffitiObjectBase,
-  "actor" | "name" | "source"
->;
+export type GraffitiLocation = Pick<GraffitiObjectBase, "uri">;
 
 /**
  * This object is a subset of {@link GraffitiObjectBase} that a user must construct locally before calling {@link Graffiti.put}.
@@ -176,12 +161,8 @@ export type GraffitiLocation = Pick<
  * This local object must have a {@link GraffitiObjectBase.value | `value`} and {@link GraffitiObjectBase.channels | `channels`}
  * and may optionally have an {@link GraffitiObjectBase.allowed | `allowed`} property.
  *
- * It may also contain any of the {@link GraffitiLocation } properties: {@link GraffitiObjectBase.actor | `actor`},
- * {@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 GraffitiSession | `session` } will be used.
- * If no `source` is provided, one may be inferred by the depending on implementation.
+ * It may also include a {@link GraffitiObjectBase.uri | `uri`} property to specify the
+ * URI of an existing object to replace. If no `uri` is provided, one will be generated during object creation.
  *
  * This object does not need a {@link GraffitiObjectBase.lastModified | `lastModified`} or {@link GraffitiObjectBase.tombstone | `tombstone`}
  * property since these are automatically generated by the Graffiti system.
@@ -204,8 +185,7 @@ export const GraffitiPutObjectJSONSchema = {
 } as const satisfies JSONSchema;
 
 /**
- * This object contains information that
- * {@link GraffitiObjectBase.source | `source`}s can
+ * This object contains information that the underlying implementation can
  * use to verify that a user has permission to operate a
  * particular {@link GraffitiObjectBase.actor | `actor`}.
  * This object is required of all {@link Graffiti} methods
@@ -289,10 +269,12 @@ export interface GraffitiPatch {
  *
  * Errors are returned within the stream rather than as
  * exceptions that would halt the entire stream. This is because
- * some implementations may pull data from multiple
- * {@link GraffitiObjectBase.source | `source`}s
+ * some implementations may pull data from multiple sources
  * including some that may be unreliable. In many cases,
  * these errors can be safely ignored.
+ * The `origin` property of the error object indicates the
+ * source of the error including its scheme and other
+ * implementation-specific details (e.g. domain name).
  *
  * The stream is an [`AsyncGenerator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
  * that can be iterated over using `for await` loops or calling `next` on the generator.
@@ -305,7 +287,7 @@ export type GraffitiStream<TValue, TReturn = void> = AsyncGenerator<
     }
   | {
       error: Error;
-      source: string;
+      origin: string;
     },
   TReturn
 >;

package/src/3-errors.ts

@@ -61,3 +61,11 @@ export class GraffitiErrorInvalidUri extends Error {
     Object.setPrototypeOf(this, GraffitiErrorInvalidUri.prototype);
   }
 }
+
+export class GraffitiErrorUnrecognizedUriScheme extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "GraffitiErrorUnrecognizedUriScheme";
+    Object.setPrototypeOf(this, GraffitiErrorUnrecognizedUriScheme.prototype);
+  }
+}

package/tests/crud.ts

@@ -5,7 +5,6 @@ import type {
   GraffitiPatch,
   JSONSchema,
 } from "@graffiti-garden/api";
-import type { FromSchema } from "json-schema-to-ts";
 import {
   GraffitiErrorNotFound,
   GraffitiErrorSchemaMismatch,
@@ -48,7 +47,7 @@ export const graffitiCRUDTests = (
         const previous = await graffiti.put<{}>({ value, channels }, session);
         expect(previous.value).toEqual({});
         expect(previous.channels).toEqual([]);
-        expect(previous.allowed).toBeUndefined();
+        expect(previous.allowed).toEqual([]);
         expect(previous.actor).toEqual(session.actor);
 
         // Get it back
@@ -56,9 +55,8 @@ export const graffitiCRUDTests = (
         expect(gotten.value).toEqual(value);
         expect(gotten.channels).toEqual([]);
         expect(gotten.allowed).toBeUndefined();
-        expect(gotten.name).toEqual(previous.name);
+        expect(gotten.uri).toEqual(previous.uri);
         expect(gotten.actor).toEqual(previous.actor);
-        expect(gotten.source).toEqual(previous.source);
         expect(gotten.lastModified).toEqual(previous.lastModified);
 
         // Replace it
@@ -66,14 +64,17 @@ export const graffitiCRUDTests = (
           something: "goodbye, world~ :c",
         };
         const beforeReplaced = await graffiti.put<{}>(
-          { ...previous, value: newValue, channels: [] },
+          {
+            uri: previous.uri,
+            value: newValue,
+            channels: [],
+          },
           session,
         );
         expect(beforeReplaced.value).toEqual(value);
         expect(beforeReplaced.tombstone).toEqual(true);
-        expect(beforeReplaced.name).toEqual(previous.name);
+        expect(beforeReplaced.uri).toEqual(previous.uri);
         expect(beforeReplaced.actor).toEqual(previous.actor);
-        expect(beforeReplaced.source).toEqual(previous.source);
         expect(beforeReplaced.lastModified).toBeGreaterThanOrEqual(
           gotten.lastModified,
         );
@@ -95,22 +96,14 @@ export const graffitiCRUDTests = (
         // Get a tombstone
         const final = await graffiti.get(afterReplaced, {});
         expect(final).toEqual(beforeDeleted);
-      });
 
-      it("get non-existant", async () => {
-        const putted = await graffiti.put<{}>(randomPutObject(), session);
-        await expect(
-          graffiti.get(
-            {
-              ...putted,
-              name: randomString(),
-            },
-            {},
-          ),
-        ).rejects.toBeInstanceOf(GraffitiErrorNotFound);
+        // Delete it again
+        await expect(graffiti.delete(final, session)).rejects.toThrow(
+          GraffitiErrorNotFound,
+        );
       });
 
-      it("put, get, delete with wrong actor", async () => {
+      it("put, delete, patch with wrong actor", async () => {
         await expect(
           graffiti.put<{}>(
             { value: {}, channels: [], actor: session2.actor },
@@ -123,6 +116,17 @@ export const graffitiCRUDTests = (
           session2,
         );
 
+        await expect(
+          graffiti.put<{}>(
+            {
+              uri: putted.uri,
+              value: {},
+              channels: [],
+            },
+            session1,
+          ),
+        ).rejects.toThrow(GraffitiErrorForbidden);
+
         await expect(graffiti.delete(putted, session1)).rejects.toThrow(
           GraffitiErrorForbidden,
         );
@@ -132,6 +136,36 @@ export const graffitiCRUDTests = (
         );
       });
 
+      it("put, patch, delete object that is not allowed", async () => {
+        const putted = await graffiti.put<{}>(
+          {
+            value: {},
+            channels: [],
+            allowed: [],
+          },
+          session1,
+        );
+
+        await expect(
+          graffiti.put(
+            {
+              uri: putted.uri,
+              value: {},
+              channels: [],
+            },
+            session2,
+          ),
+        ).rejects.toThrow(GraffitiErrorNotFound);
+
+        await expect(graffiti.patch({}, putted, session2)).rejects.toThrow(
+          GraffitiErrorNotFound,
+        );
+
+        await expect(graffiti.delete(putted, session2)).rejects.toThrow(
+          GraffitiErrorNotFound,
+        );
+      });
+
       it("put and get with schema", async () => {
         const schema = {
           properties: {

package/tests/discover.ts

@@ -89,7 +89,7 @@ export const graffitiDiscoverTests = (
       expect(value.lastModified).toEqual(putted.lastModified);
     });
 
-    for (const prop of ["name", "actor", "lastModified"] as const) {
+    for (const prop of ["actor", "lastModified"] as const) {
       it(`discover for ${prop}`, async () => {
         const object1 = randomPutObject();
         const putted1 = await graffiti.put<{}>(object1, session1);
@@ -109,8 +109,8 @@ export const graffitiDiscoverTests = (
         });
 
         const value = await nextStreamValue(iterator);
-        expect(value.name).toEqual(putted1.name);
-        expect(value.name).not.toEqual(putted2.name);
+        expect(value.uri).toEqual(putted1.uri);
+        expect(value.uri).not.toEqual(putted2.uri);
         expect(value.value).toEqual(object1.value);
         await expect(iterator.next()).resolves.toHaveProperty("done", true);
       });
@@ -123,7 +123,7 @@ export const graffitiDiscoverTests = (
       await new Promise((r) => setTimeout(r, 20));
       const putted2 = await graffiti.put<{}>(object, session);
 
-      expect(putted1.name).not.toEqual(putted2.name);
+      expect(putted1.uri).not.toEqual(putted2.uri);
       expect(putted1.lastModified).toBeLessThan(putted2.lastModified);
 
       const gtIterator = graffiti.discover([object.channels[0]], {
@@ -142,7 +142,7 @@ export const graffitiDiscoverTests = (
         },
       });
       const value1 = await nextStreamValue(gtIteratorEpsilon);
-      expect(value1.name).toEqual(putted2.name);
+      expect(value1.uri).toEqual(putted2.uri);
       expect(await gtIteratorEpsilon.next()).toHaveProperty("done", true);
       const gteIterator = graffiti.discover(object.channels, {
         properties: {
@@ -153,7 +153,7 @@ export const graffitiDiscoverTests = (
         },
       });
       const value = await nextStreamValue(gteIterator);
-      expect(value.name).toEqual(putted2.name);
+      expect(value.uri).toEqual(putted2.uri);
       expect(await gteIterator.next()).toHaveProperty("done", true);
       const gteIteratorEpsilon = graffiti.discover(object.channels, {
         properties: {
@@ -181,7 +181,7 @@ export const graffitiDiscoverTests = (
         },
       });
       const value3 = await nextStreamValue(ltIteratorEpsilon);
-      expect(value3.name).toEqual(putted1.name);
+      expect(value3.uri).toEqual(putted1.uri);
       expect(await ltIteratorEpsilon.next()).toHaveProperty("done", true);
 
       const lteIterator = graffiti.discover(object.channels, {
@@ -192,7 +192,7 @@ export const graffitiDiscoverTests = (
         },
       });
       const value2 = await nextStreamValue(lteIterator);
-      expect(value2.name).toEqual(putted1.name);
+      expect(value2.uri).toEqual(putted1.uri);
       expect(await lteIterator.next()).toHaveProperty("done", true);
 
       const lteIteratorEpsilon = graffiti.discover(object.channels, {
@@ -481,8 +481,8 @@ export const graffitiDiscoverTests = (
         const object2 = randomPutObject();
         const replaced = await graffiti.put<{}>(
           {
-            ...putted,
             ...object2,
+            uri: putted.uri,
           },
           session,
         );
@@ -535,11 +535,21 @@ export const graffitiDiscoverTests = (
 
     it("put concurrently and discover one", async () => {
       const object = randomPutObject();
-      object.name = randomString();
 
-      const putPromises = Array(100)
+      // Put a first one to get a URI
+      const putted = await graffiti.put<{}>(object, session);
+
+      const putPromises = Array(99)
         .fill(0)
-        .map(() => graffiti.put<{}>(object, session));
+        .map(() =>
+          graffiti.put<{}>(
+            {
+              ...object,
+              uri: putted.uri,
+            },
+            session,
+          ),
+        );
       await Promise.all(putPromises);
 
       const iterator = graffiti.discover(object.channels, {});

package/tests/index.ts

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

package/tests/orphans.ts

@@ -27,7 +27,7 @@ export const graffitiOrphanTests = (
       const orphanIterator1 = graffiti.recoverOrphans({}, session);
       for await (const orphan of orphanIterator1) {
         if (orphan.error) continue;
-        existingOrphans.push(orphan.value.name);
+        existingOrphans.push(orphan.value.uri);
       }
 
       const object = randomPutObject();
@@ -37,9 +37,8 @@ export const graffitiOrphanTests = (
       let numResults = 0;
       for await (const orphan of orphanIterator2) {
         if (orphan.error) continue;
-        if (orphan.value.name === putted.name) {
+        if (orphan.value.uri === putted.uri) {
           numResults++;
-          expect(orphan.value.source).toBe(putted.source);
           expect(orphan.value.lastModified).toBe(putted.lastModified);
         }
       }
@@ -62,14 +61,14 @@ export const graffitiOrphanTests = (
         },
         session,
       );
-      expect(putNotOrphan.name).toBe(putOrphan.name);
+      expect(putNotOrphan.uri).toBe(putOrphan.uri);
       expect(putNotOrphan.lastModified).toBeGreaterThan(putOrphan.lastModified);
 
       const orphanIterator = graffiti.recoverOrphans({}, session);
       let numResults = 0;
       for await (const orphan of orphanIterator) {
         if (orphan.error) continue;
-        if (orphan.value.name === putOrphan.name) {
+        if (orphan.value.uri === putOrphan.uri) {
           numResults++;
           expect(orphan.value.tombstone).toBe(true);
           expect(orphan.value.lastModified).toBe(putNotOrphan.lastModified);

package/dist/tests/location.d.ts

@@ -1,3 +0,0 @@
-import type { Graffiti } from "@graffiti-garden/api";
-export declare const graffitiLocationTests: (useGraffiti: () => Pick<Graffiti, "locationToUri" | "uriToLocation">) => void;
-//# sourceMappingURL=location.d.ts.map

package/dist/tests/location.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../tests/location.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIrD,eAAO,MAAM,qBAAqB,GAChC,aAAa,MAAM,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAAC,SAmCrE,CAAC"}

package/tests/location.ts

@@ -1,42 +0,0 @@
-import { it, expect, describe } from "vitest";
-import type { Graffiti } from "@graffiti-garden/api";
-import { GraffitiErrorInvalidUri } from "@graffiti-garden/api";
-import { randomString } from "./utils";
-
-export const graffitiLocationTests = (
-  useGraffiti: () => Pick<Graffiti, "locationToUri" | "uriToLocation">,
-) => {
-  describe.concurrent("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);
-    });
-  });
-};