@graffiti-garden/api 0.0.1

package/README.md

@@ -0,0 +1,22 @@
+# Graffiti API
+
+The Graffiti API makes it possible to build social applications that are flexible and interoperable.
+This repository contains the abstract API and it's documentation.
+
+[View the Documentation](https://api.graffiti.garden/classes/Graffiti.html)
+
+## Building the Documentation
+
+To build the [TypeDoc](https://typedoc.org/) documentation, run the following commands:
+
+```bash
+npm run install
+npm run docs
+```
+
+Then run a local server to view the documentation:
+
+```bash
+cd docs
+npx http-server
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@graffiti-garden/api",
+  "version": "0.0.1",
+  "description": "The heart of Graffiti",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tests": "./tests/index.ts"
+  },
+  "files": [
+    "src",
+    "tests",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "author": "Theia Henderson",
+  "license": "GPL-3.0-or-later",
+  "scripts": {
+    "docs": "typedoc --options typedoc.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graffiti-garden/api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/graffiti-garden/api/issues"
+  },
+  "homepage": "https://api.graffiti.garden/classes/Graffiti.html",
+  "devDependencies": {
+    "@types/json-schema": "^7.0.15",
+    "ajv": "^8.17.1",
+    "fast-json-patch": "^3.1.1",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.26.11",
+    "vitest": "^2.1.8"
+  }
+}

package/src/api.ts

@@ -0,0 +1,348 @@
+import type {
+  GraffitiLocation,
+  GraffitiObject,
+  GraffitiObjectBase,
+  GraffitiPatch,
+  GraffitiSessionBase,
+  GraffitiPutObject,
+  GraffitiStream,
+} from "./types";
+import type { JSONSchema4 } from "json-schema";
+
+/**
+ * This API describes a small but mighty set of methods that
+ * can be used to create many different kinds of social media applications,
+ * all of which can interoperate.
+ * These methods should satisfy all of an application's needs for
+ * the communication, storage, and access management of social data.
+ * The rest of the application can be built with standard client-side
+ * user interface tools to present and interact with the data.
+ *
+ * There are several different implementations of this Graffiti API available,
+ * including a decentralized implementation and a local implementation
+ * that can be used for testing. In the design of Graffiti we prioritized
+ * the design of this API first as it is the layer that shapes the experience
+ * of developing applications. While different implementations provide tradeoffs between
+ * 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
+ * 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`}
+ * (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`}
+ * that the object is associated with.
+ *
+ * The "social" part of the API is the {@link discover} method, which allows
+ * an application to query for objects made by other users.
+ * This function only returns objects that are associated with one or more
+ * of the {@link GraffitiObjectBase.channels | `channels`}
+ * provided by a querying application. This helps to prevent
+ * [context collapse](https://en.wikipedia.org/wiki/Context_collapse) and
+ * allows users to express their intended audience, even in an interoperable
+ * environment.
+ *
+ * Additionally, {@link synchronize} keeps track of changes to data
+ * from any of the aforementioned methods and routes these changes internally
+ * to provide a consistent user experience.
+ *
+ * Finally, other utility functions provide simple type conversions and
+ * allow users to find objects "lost" to forgotten or misspelled channels.
+ *
+ * @groupDescription CRUD Operations
+ * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},
+ * and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.
+ * @groupDescription Query Operations
+ * Methods for retrieving multiple {@link GraffitiObjectBase | Graffiti objects} at a time.
+ * @groupDescription Utilities
+ * Methods for for converting Graffiti objects to and from URIs
+ * and for finding lost objects.
+ */
+export abstract class Graffiti {
+  /**
+   * Converts a {@link GraffitiLocation} object containing a
+   * {@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},
+   * and {@link GraffitiObjectBase.source | `source`} into a globally unique URI.
+   * The form of this URI is implementation dependent.
+   *
+   * Its exact inverse is {@link uriToLocation}.
+   *
+   * @group Utilities
+   */
+  abstract locationToUri(location: GraffitiLocation): string;
+
+  /**
+   * Parses a globally unique Graffiti URI into a {@link GraffitiLocation}
+   * object containing a {@link GraffitiObjectBase.name | `name`},
+   * {@link GraffitiObjectBase.actor | `actor`}, and {@link GraffitiObjectBase.source | `source`}.
+   *
+   * Its exact inverse is {@link locationToUri}.
+   *
+   * @group Utilities
+   */
+  abstract uriToLocation(uri: string): GraffitiLocation;
+
+  /**
+   * An alias of {@link locationToUri}
+   *
+   * @group Utilities
+   */
+  objectToUri(object: GraffitiObjectBase) {
+    return this.locationToUri(object);
+  }
+
+  /**
+   * Creates a new {@link GraffitiObjectBase | object} or replaces an existing object.
+   * An object can only be replaced by the same {@link GraffitiObjectBase.actor | `actor`}
+   * that created it.
+   *
+   * Replacement occurs when the {@link GraffitiLocation} properties of the supplied object
+   * ({@link GraffitiObjectBase.name | `name`}, {@link GraffitiObjectBase.actor | `actor`},
+   * 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
+   * 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
+   */
+  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.
+     */
+    object: GraffitiPutObject<Schema>,
+    /**
+     * An implementation-specific object with information to authenticate the
+     * {@link GraffitiObjectBase.actor | `actor`}.
+     */
+    session: GraffitiSessionBase,
+  ): Promise<GraffitiObjectBase>;
+
+  /**
+   * Retrieves an object from a given location.
+   * 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.
+   *
+   * The retrieved object is also type-checked against the provided [JSON schema](https://json-schema.org/)
+   * otherwise an error is thrown.
+   *
+   * @group CRUD Operations
+   */
+  abstract get<Schema extends JSONSchema4>(
+    /**
+     * The location of the object to get.
+     */
+    locationOrUri: GraffitiLocation | string,
+    /**
+     * The JSON schema to validate the retrieved object against.
+     */
+    schema: Schema,
+    /**
+     * An implementation-specific object with information to authenticate the
+     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,
+     * the retrieved object's {@link GraffitiObjectBase.allowed | `allowed`}
+     * property must be `undefined`.
+     */
+    session?: GraffitiSessionBase,
+  ): Promise<GraffitiObject<Schema>>;
+
+  /**
+   * Patches an existing object at a given location.
+   * The patching {@link GraffitiObjectBase.actor | `actor`} must be the same as the
+   * `actor` that created the object.
+   *
+   * @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
+   */
+  abstract patch(
+    /**
+     * A collection of [JSON Patch](https://jsonpatch.com) operations
+     * to apply to the object. See {@link GraffitiPatch} for more information.
+     */
+    patch: GraffitiPatch,
+    /**
+     * The location of the object to patch.
+     */
+    locationOrUri: GraffitiLocation | string,
+    /**
+     * An implementation-specific object with information to authenticate the
+     * {@link GraffitiObjectBase.actor | `actor`}.
+     */
+    session: GraffitiSessionBase,
+  ): Promise<GraffitiObjectBase>;
+
+  /**
+   * Deletes an object from a given location.
+   * The deleting {@link GraffitiObjectBase.actor | `actor`} must be the same as the
+   * `actor` that created the object.
+   *
+   * @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
+   */
+  abstract delete(
+    /**
+     * The location of the object to delete.
+     */
+    locationOrUri: GraffitiLocation | string,
+    /**
+     * An implementation-specific object with information to authenticate the
+     * {@link GraffitiObjectBase.actor | `actor`}.
+     */
+    session: GraffitiSessionBase,
+  ): 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)
+   *
+   * 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.
+   *
+   * {@link discover} can be used in conjunction with {@link synchronize}
+   * to provide a responsive and consistent user experience.
+   *
+   * @group Query Operations
+   */
+  abstract discover<Schema extends JSONSchema4>(
+    /**
+     * The {@link GraffitiObjectBase.channels | `channels`} that objects must be associated with.
+     */
+    channels: string[],
+    /**
+     * A [JSON Schema](https://json-schema.org) that objects must satisfy.
+     */
+    schema: Schema,
+    /**
+     * An implementation-specific object with information to authenticate the
+     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,
+     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}
+     * property will be returned.
+     */
+    session?: GraffitiSessionBase,
+  ): GraffitiStream<GraffitiObject<Schema>>;
+
+  /**
+   * 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} or {@link discover} and then streams appropriate
+   * changes to provide a responsive and consistent user experience.
+   *
+   * Unlike {@link discover}, 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.
+   *
+   * Example 1: Suppose a user publishes a post using {@link put}. If the feed
+   * displaying that user's posts is using {@link synchronize} to listen for changes,
+   * then the user's new post will instantly appear in their feed, giving the UI a
+   * responsive feel.
+   *
+   * Example 2: Suppose one of a user's friends changes their name. As soon as the
+   * user's application receives one notice of that change (using {@link get}
+   * or {@link discover}), then {@link synchronize} listeners can be used to update
+   * all instance's of that friend's name in the user's application instantly,
+   * providing a consistent user experience.
+   *
+   * @group Query Operations
+   */
+  abstract synchronize<Schema extends JSONSchema4>(
+    /**
+     * The {@link GraffitiObjectBase.channels | `channels`} that the objects must be associated with.
+     */
+    channels: string[],
+    /**
+     * A [JSON Schema](https://json-schema.org) that objects must satisfy.
+     */
+    schema: Schema,
+    /**
+     * An implementation-specific object with information to authenticate the
+     * {@link GraffitiObjectBase.actor | `actor`}. If no `session` is provided,
+     * only objects that have no {@link GraffitiObjectBase.allowed | `allowed`}
+     * property will be returned.
+     */
+    session?: GraffitiSessionBase,
+  ): GraffitiStream<GraffitiObject<Schema>>;
+
+  /**
+   * Returns a list of all {@link GraffitiObjectBase.channels | `channels`}
+   * that an {@link GraffitiObjectBase.actor | `actor`} has posted to.
+   * This is not very useful for most applications, but
+   * necessary for certain applications where a user wants a
+   * global view of all their Graffiti data or to debug
+   * channel usage.
+   *
+   * @group Utilities
+   *
+   * @returns A stream the {@link GraffitiObjectBase.channels | `channel`}s
+   * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.
+   * The `lastModified` field is the time that the user last modified an
+   * object in that channel. The `count` field is the number of objects
+   * that the user has posted to that channel.
+   */
+  abstract listChannels(
+    /**
+     * An implementation-specific object with information to authenticate the
+     * {@link GraffitiObjectBase.actor | `actor`}.
+     */
+    session: GraffitiSessionBase,
+  ): GraffitiStream<{
+    channel: string;
+    source: string;
+    lastModified: Date;
+    count: number;
+  }>;
+
+  /**
+   * Returns a list of all {@link GraffitiObjectBase | objects} a user has posted that are
+   * not associated with any {@link GraffitiObjectBase.channels | `channel`}, i.e. orphaned objects.
+   * This is not very useful for most applications, but
+   * necessary for certain applications where a user wants a
+   * global view of all their Graffiti data or to debug
+   * channel usage.
+   *
+   * @group Utilities
+   *
+   * @returns A stream of the {@link GraffitiObjectBase.name | `name`}
+   * and {@link GraffitiObjectBase.source | `source`} of the orphaned objects
+   * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.
+   * The {@link GraffitiObjectBase.lastModified | lastModified} field is the
+   * time that the user last modified the orphan and the
+   * {@link GraffitiObjectBase.tombstone | `tombstone`} field is `true`
+   * if the object has been deleted.
+   */
+  abstract listOrphans(session: GraffitiSessionBase): GraffitiStream<{
+    name: string;
+    source: string;
+    lastModified: Date;
+    tombstone: boolean;
+  }>;
+}
+
+/**
+ * This is a factory function that produces an instance of
+ * the {@link Graffiti} class. Since the Graffiti class is
+ * abstract, factory functions provide an easy way to
+ * swap out different implementations.
+ */
+export type UseGraffiti = () => Graffiti;

package/src/errors.ts

@@ -0,0 +1,14 @@
+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";
+  }
+}

package/src/index.ts

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

package/src/sync.ts

@@ -0,0 +1,58 @@
+import type { JSONSchema4 } from "json-schema";
+import { Graffiti } from "./api";
+import type {
+  GraffitiObject,
+  GraffitiObjectBase,
+  GraffitiSessionBase,
+} from "./types";
+import Ajv from "ajv";
+import { applyPatch } from "fast-json-patch";
+
+export abstract class GraffitiSynchronized extends Graffiti {
+  protected readonly ajv = new Ajv();
+  protected readonly changes = new EventTarget();
+  protected dispatchChanges(
+    oldObject: GraffitiObjectBase,
+    newObject?: GraffitiObjectBase,
+  ) {
+    this.changes.dispatchEvent(
+      new CustomEvent("change", {
+        detail: {
+          oldObject,
+          newObject,
+        },
+      }),
+    );
+  }
+
+  protected abstract _patch(
+    ...args: Parameters<Graffiti["patch"]>
+  ): ReturnType<Graffiti["patch"]>;
+
+  async patch(
+    ...args: Parameters<Graffiti["patch"]>
+  ): ReturnType<Graffiti["patch"]> {
+    const oldObject = await this._patch(...args);
+    const newObject: GraffitiObjectBase = { ...oldObject, tombstone: false };
+    for (const prop of ["value", "channels", "allowed"] as const) {
+      const ops = args[0][prop];
+      if (!ops || !ops.length) continue;
+      const result = applyPatch(newObject[prop], ops, false, false).newDocument;
+    }
+    this.dispatchChanges(oldObject, newObject);
+    return oldObject;
+  }
+
+  // synchronize<Schema extends JSONSchema4>(
+  //   ...args: Parameters<Graffiti["synchronize"]>
+  // ): ReturnType<Graffiti["synchronize"]> {
+  // const validate = this.ajv.compile(schema);
+  // const matchOptions = {
+  //   ifModifiedSince: options?.ifModifiedSince,
+  //   channels,
+  // };
+  // const repeater = new Repeater < {
+  // }
+  //   GraffitiObject<Schema>>(
+  // }
+}

package/src/types.ts

@@ -0,0 +1,254 @@
+import { type JTDDataType } from "ajv/dist/core";
+import type { Operation as JSONPatchOperation } from "fast-json-patch";
+
+/**
+ * Objects are the atomic unit in Graffiti that can represent both data (*e.g.* a social media post or profile)
+ * and activities (*e.g.* a like or follow).
+ * Objects are created and modified by a single {@link actor | `actor`}.
+ *
+ * Most of an object's content is stored in its {@link value | `value`} property, which can be any JSON
+ * object. However, we recommend using properties from the
+ * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/)
+ * 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 {@link channels | `channels`} and {@link allowed | `allowed`} properties
+ * enable the object's creator to shape the visibility of and access to their object.
+ *
+ * The {@link tombstone | `tombstone`} and {@link lastModified | `lastModified`} properties are for
+ * caching and synchronization.
+ */
+export interface GraffitiObjectBase {
+  /**
+   * The object's content as freeform JSON. We recommend using properties from the
+   * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/)
+   * or properties that emerge in the Graffiti [folksonomy](https://en.wikipedia.org/wiki/Folksonomy)
+   * to promote interoperability.
+   */
+  value: {};
+
+  /**
+   * An array of URIs the creator associates with the object. Objects can only be found by querying
+   * one of the object's channels using the
+   * {@link Graffiti.discover} method. This allows creators to express the intended audience of their object
+   * which helps to prevent [context collapse](https://en.wikipedia.org/wiki/Context_collapse) even
+   * in the highly interoperable ecosystem that Graffiti envisions. For example, channel URIs may be:
+   * - A user's own {@link actor | `actor`} URI. Putting an object in this channel is a way to broadcast
+   * the object to the user's followers, like posting a tweet.
+   * - The URI of a Graffiti post. Putting an object in this channel is a way to broadcast to anyone viewing
+   * the post, like commenting on a tweet.
+   * - A URI representing a topic. Putting an object in this channel is a way to broadcast to anyone interested
+   * in that topic, like posting in a subreddit.
+   */
+  channels: string[];
+
+  /**
+   * An optional array of {@link actor | `actor`} URIs that the creator allows to access the object.
+   * If no `allowed` array is provided, the object can be accessed by anyone (so long as they
+   * also know the right {@link channels | `channel` } to look in). An object can always be accessed by its creator, even if
+   * the `allowed` array is empty.
+   *
+   * The `allowed` array is not revealed to users other than the creator, like
+   * a BCC email. A user may choose to add a `to` property to the object's {@link value | `value`} to indicate
+   * other recipients, however this is not enforced by Graffiti and may not accurately reflect the actual `allowed` array.
+   *
+   * `allowed` can be combined with {@link channels | `channels`}. For example, to send someone a direct message
+   * the sender should put their object in the channel of the recipient's {@link actor | `actor`} URI to notify them of the message and also add
+   * the recipient's {@link actor | `actor`} URI to the `allowed` array to prevent others from seeing the message.
+   */
+  allowed?: string[];
+
+  /**
+   * The URI of the `actor` that {@link Graffiti.put | created } the object. This `actor` also has the unique permission to
+   * {@link Graffiti.patch | modify} or {@link Graffiti.delete | delete} the object.
+   *
+   * We borrow the term actor from the ActivityPub because
+   * [like in ActivityPub](https://www.w3.org/TR/activitypub/#h-note-0)
+   * there is not necessarily a one-to-one mapping between actors and people/users.
+   * Multiple people can share the same actor or one person can have multiple actors.
+   * Actors can also be bots.
+   *
+   * In Graffiti, actors are always globally unique URIs which
+   * allows them to also function as {@link channels | `channels`}.
+   */
+  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.
+   */
+  source: string;
+
+  /**
+   * The time the object was last modified. This is used for caching and synchronization.
+   * It can also be used to sort objects in a user interface but in many cases it would be better to
+   * use a `createdAt` property in the object's {@link value | `value`} to indicate when the object was created
+   * rather than when it was modified.
+   */
+  lastModified: Date;
+
+  /**
+   * A boolean indicating whether the object has been deleted.
+   * Depending on implementation, objects stay available for some time after deletion to allow for synchronization.
+   */
+  tombstone: boolean;
+}
+
+/**
+ * This type constrains the {@link GraffitiObjectBase} type to adhere to a
+ * particular [JSON schema](https://json-schema.org/).
+ * This allows for static type-checking of an object's {@link GraffitiObjectBase.value | `value`}
+ * which is otherwise a freeform JSON object.
+ *
+ * Schema-aware objects are returned by {@link Graffiti.get} and {@link Graffiti.discover}.
+ */
+export type GraffitiObject<Schema> = GraffitiObjectBase & JTDDataType<Schema>;
+
+/**
+ * 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}.
+ */
+export type GraffitiLocation = Pick<
+  GraffitiObjectBase,
+  "actor" | "name" | "source"
+>;
+
+/**
+ * This object is a subset of {@link GraffitiObjectBase} that a user must construct locally before calling {@link Graffiti.put}.
+ * This local copy does not require system-generated properties and may be statically typed with
+ * a [JSON schema](https://json-schema.org/) to prevent the accidental creation of erroneous objects.
+ *
+ * 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 GraffitiSessionBase | `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`}
+ * property since these are automatically generated by the Graffiti system.
+ */
+export type GraffitiPutObject<Schema> = Pick<
+  GraffitiObjectBase,
+  "value" | "channels" | "allowed"
+> &
+  Partial<GraffitiLocation> &
+  JTDDataType<Schema>;
+
+/**
+ * This object contains information that
+ * {@link GraffitiObjectBase.source | `source`}s 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
+ * 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.
+ * However it is likely that the `session` object must contain other
+ * implementation-specific properties.
+ * For example, a Solid implementation might include a
+ * [`fetch`](https://docs.inrupt.com/developer-tools/api/javascript/solid-client-authn-browser/functions.html#fetch)
+ * function. A distributed implementation may include
+ * a cryptographic signature.
+ *
+ * It may also include other implementation specific properties
+ * that provide hints for performance or security.
+ */
+export interface GraffitiSessionBase {
+  /**
+   * The {@link GraffitiObjectBase.actor | `actor`} a user wants to authenticate with.
+   */
+  actor: string;
+  /**
+   * Other implementation-specific properties go here.
+   */
+  [key: string]: any;
+}
+
+/**
+ * This is the format for patches that modify {@link GraffitiObjectBase} objects
+ * using the {@link Graffiti.patch} method. The patches must
+ * be an array of [JSON Patch](https://jsonpatch.com) operations.
+ * Patches can only be applied to the
+ * {@link GraffitiObjectBase.value | `value`}, {@link GraffitiObjectBase.channels | `channels`},
+ * and {@link GraffitiObjectBase.allowed | `allowed`} properties since the other
+ * properties either describe the object's location or are automatically generated.
+ * (See also {@link GraffitiPutObject}).
+ */
+export interface GraffitiPatch {
+  /**
+   * An array of [JSON Patch](https://jsonpatch.com) operations to
+   * modify the object's {@link GraffitiObjectBase.value | `value`}. The resulting
+   * `value` must still be a JSON object.
+   */
+  value?: JSONPatchOperation[];
+
+  /**
+   * An array of [JSON Patch](https://jsonpatch.com) operations to
+   * modify the object's {@link GraffitiObjectBase.channels | `channels`}. The resulting
+   * `channels` must still be an array of strings.
+   */
+  channels?: JSONPatchOperation[];
+
+  /**
+   * An array of [JSON Patch](https://jsonpatch.com) operations to
+   * modify the object's {@link GraffitiObjectBase.allowed | `allowed`} property. The resulting
+   * `allowed` property must still be an array of strings or `undefined`.
+   */
+  allowed?: JSONPatchOperation[];
+}
+
+/**
+ * This type represents a stream of data that are
+ * returned by Graffiti's query-like operations such as
+ * {@link Graffiti.discover} and {@link Graffiti.listChannels}.
+ *
+ * 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
+ * including some that may be unreliable. In many cases,
+ * these errors can be safely ignored.
+ *
+ * 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.
+ * The stream can be terminated by breaking out of a loop calling `return` on the generator.
+ */
+export type GraffitiStream<T> = AsyncGenerator<
+  | {
+      error: false;
+      value: T;
+    }
+  | {
+      error: true;
+      value: Error;
+      source: string;
+    },
+  void,
+  void
+>;

package/tests/location.spec.ts

@@ -0,0 +1,16 @@
+import { it, expect } from "vitest";
+import type { UseGraffiti } from "../src/index";
+
+export const locationTests = (useGraffiti: UseGraffiti) => {
+  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);
+  });
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "lib": ["esnext", "dom"],
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src"]
+}