@graffiti-garden/api 0.0.4 → 0.0.6

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.4",
+  "version": "0.0.6",
   "description": "The heart of Graffiti",
   "type": "module",
   "main": "src/index.ts",

package/src/1-api.ts

@@ -3,7 +3,7 @@ import type {
   GraffitiObject,
   GraffitiObjectBase,
   GraffitiPatch,
-  GraffitiSessionBase,
+  GraffitiSession,
   GraffitiPutObject,
   GraffitiStream,
 } from "./2-types";
@@ -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>;
 
   /**
@@ -134,9 +136,9 @@ export abstract class Graffiti {
    * 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,7 +193,7 @@ 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
+   * 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
@@ -200,7 +202,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 delete(
     /**
@@ -211,7 +213,7 @@ export abstract class Graffiti {
      * An implementation-specific object with information to authenticate the
      * {@link GraffitiObjectBase.actor | `actor`}.
      */
-    session: GraffitiSessionBase,
+    session: GraffitiSession,
   ): Promise<GraffitiObjectBase>;
 
   /**
@@ -229,11 +231,11 @@ export abstract class Graffiti {
    * 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
+   * 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 operation
+   * 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,
@@ -245,7 +247,7 @@ export abstract class Graffiti {
    * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
    * and [JSON Schema](https://json-schema.org).
    *
-   * @group Query Operations
+   * @group Query Methods
    */
   abstract discover<Schema extends JSONSchema4>(
     /**
@@ -262,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>>;
 
   /**
@@ -286,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>(
     /**
@@ -303,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>>;
 
   /**
@@ -327,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;
@@ -353,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/2-types.ts

@@ -95,12 +95,12 @@ export interface GraffitiObjectBase {
   source: string;
 
   /**
-   * The time the object was last modified. This is used for caching and synchronization.
+   * The time the object was last modified in [ISO format](https://fits.gsfc.nasa.gov/iso-time.html). 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;
+  lastModified: string;
 
   /**
    * A boolean indicating whether the object has been deleted.
@@ -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

@@ -1,7 +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) {
+  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);
+  }
+}