Skip to content

Commit

Permalink
rearrange synchronize and query docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@sportdeath
sportdeath committed Feb 2, 2025
1 parent 7ed8ac9 commit aec29ae
Show file tree
Hide file tree
Showing 2 changed files with 122 additions and 119 deletions.
234 changes: 117 additions & 117 deletions src/1-api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ import type { JSONSchema4 } from "json-schema";
*
* There are several different implementations of this Graffiti API available,
* including a [federated implementation](https://github.com/graffiti-garden/implementation-federated),
* that lets users choose where their data is stored,
* and a [local implementation](https://github.com/graffiti-garden/implementation-local)
* that can be used for testing and development. In our design of Graffiti, this API is our
* primary focus as it is the layer that shapes the experience
Expand Down Expand Up @@ -237,12 +238,11 @@ import type { JSONSchema4 } from "json-schema";
* Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},
* and {@link delete | deleting} {@link GraffitiObjectBase | Graffiti objects}.
* @groupDescription Query Methods
* Methods for retrieving multiple {@link GraffitiObjectBase | Graffiti objects} at a time.
* Methods that retrieve or accumulate information about 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.
* Methods for for converting Graffiti objects to and from URIs.
*/
export abstract class Graffiti {
/**
Expand Down Expand Up @@ -498,90 +498,21 @@ export abstract class Graffiti {
>;

/**
* 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}, {@link discover}, and {@link recoverOrphans}
* 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 synchronizeDiscover} 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 synchronizeDiscover} 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 Synchronize Methods
*/
abstract synchronizeDiscover<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?: GraffitiSession | null,
): GraffitiStream<GraffitiObject<Schema>>;

/**
* This method has the same signature as {@link get} but, like {@link synchronizeDiscover},
* it listens for changes made via {@link put}, {@link patch}, and {@link delete} or
* fetched from {@link get}, {@link discover}, and {@link recoverOrphans} and then
* streams appropriate changes to provide a responsive and consistent user experience.
*
* Unlike {@link get}, which returns a single result, this method continuously
* listens for changes which are output as an asynchronous {@link GraffitiStream}.
* Discovers objects not contained in *any*
* {@link GraffitiObjectBase.channels | `channels`}
* that were created by the querying {@link GraffitiObjectBase.actor | `actor`}
* and match the given [JSON Schema](https://json-schema.org).
* Unlike {@link discover}, this method will not return objects created by other users.
*
* @group Synchronize Methods
*/
abstract synchronizeGet<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?: GraffitiSession | null,
): GraffitiStream<GraffitiObject<Schema>>;

/**
* This method has the same signature as {@link recoverOrphans} but,
* like {@link synchronizeDiscover}, it listens for changes made via
* {@link put}, {@link patch}, and {@link delete} or fetched from
* {@link get}, {@link discover}, and {@link recoverOrphans} and then
* streams appropriate changes to provide a responsive and consistent user experience.
* This method is not useful for most applications, but necessary for
* getting a global view of all a user's Graffiti data or debugging
* channel usage.
*
* Unlike {@link recoverOrphans}, 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.
* It's return value is the same as {@link discover}.
*
* @group Synchronize Methods
* @group Query Methods
*/
abstract synchronizeRecoverOrphans<Schema extends JSONSchema4>(
abstract recoverOrphans<Schema extends JSONSchema4>(
/**
* A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.
*/
Expand All @@ -591,7 +522,12 @@ export abstract class Graffiti {
* {@link GraffitiObjectBase.actor | `actor`}.
*/
session: GraffitiSession,
): GraffitiStream<GraffitiObject<Schema>>;
): GraffitiStream<
GraffitiObject<Schema>,
{
tombstoneRetention: number;
}
>;

/**
* Returns statistics about all the {@link GraffitiObjectBase.channels | `channels`}
Expand All @@ -601,7 +537,7 @@ export abstract class Graffiti {
* global view of all their Graffiti data or to debug
* channel usage.
*
* @group Utilities
* @group Query Methods
*
* @returns A stream of all {@link GraffitiObjectBase.channels | `channel`}s
* that the {@link GraffitiObjectBase.actor | `actor`} has posted to.
Expand All @@ -623,38 +559,6 @@ export abstract class Graffiti {
lastModified: number;
}>;

/**
* Discovers objects not contained in *any*
* {@link GraffitiObjectBase.channels | `channels`}
* that were created by the querying {@link GraffitiObjectBase.actor | `actor`}
* and match the given [JSON Schema](https://json-schema.org).
* Unlike {@link discover}, this method will not return objects created by other users.
*
* This method is not useful for most applications, but necessary for
* getting a global view of all a user's Graffiti data or debugging
* channel usage.
*
* It's return value is the same as {@link discover}.
*
* @group Utilities
*/
abstract recoverOrphans<Schema extends JSONSchema4>(
/**
* A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.
*/
schema: Schema,
/**
* An implementation-specific object with information to authenticate the
* {@link GraffitiObjectBase.actor | `actor`}.
*/
session: GraffitiSession,
): GraffitiStream<
GraffitiObject<Schema>,
{
tombstoneRetention: number;
}
>;

/**
* Begins the login process. Depending on the implementation, this may
* involve redirecting the user to a login page or opening a popup,
Expand Down Expand Up @@ -726,6 +630,102 @@ export abstract class Graffiti {
* @group Session Management
*/
abstract readonly sessionEvents: EventTarget;

/**
* 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}, {@link discover}, and {@link recoverOrphans}
* 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 synchronizeDiscover} 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 synchronizeDiscover} 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 Synchronize Methods
*/
abstract synchronizeDiscover<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?: GraffitiSession | null,
): GraffitiStream<GraffitiObject<Schema>>;

/**
* This method has the same signature as {@link get} but, like {@link synchronizeDiscover},
* it listens for changes made via {@link put}, {@link patch}, and {@link delete} or
* fetched from {@link get}, {@link discover}, and {@link recoverOrphans} and then
* streams appropriate changes to provide a responsive and consistent user experience.
*
* Unlike {@link get}, which returns a single result, this method continuously
* listens for changes which are output as an asynchronous {@link GraffitiStream}.
*
* @group Synchronize Methods
*/
abstract synchronizeGet<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?: GraffitiSession | null,
): GraffitiStream<GraffitiObject<Schema>>;

/**
* This method has the same signature as {@link recoverOrphans} but,
* like {@link synchronizeDiscover}, it listens for changes made via
* {@link put}, {@link patch}, and {@link delete} or fetched from
* {@link get}, {@link discover}, and {@link recoverOrphans} and then
* streams appropriate changes to provide a responsive and consistent user experience.
*
* Unlike {@link recoverOrphans}, 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.
*
* @group Synchronize Methods
*/
abstract synchronizeRecoverOrphans<Schema extends JSONSchema4>(
/**
* A [JSON Schema](https://json-schema.org) that orphaned objects must satisfy.
*/
schema: Schema,
/**
* An implementation-specific object with information to authenticate the
* {@link GraffitiObjectBase.actor | `actor`}.
*/
session: GraffitiSession,
): GraffitiStream<GraffitiObject<Schema>>;
}

/**
Expand Down
7 changes: 5 additions & 2 deletions src/2-types.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -310,8 +310,11 @@ export type GraffitiLogoutEvent = CustomEvent<
* and restore any previously active sessions.
* Successful session restores will be returned in parallel as
* their own {@link GraffitiLoginEvent} events.
* This event optionally return an `href` property
* if there were any redirects during the restoration process.
*
* This event optionally returns an `href` property
* representing the URL the user originated a login request
* from, which may be useful for redirecting the user back to
* the page they were on after login.
* The event name to listen for is `initialized`.
*/
export type GraffitiSessionInitializedEvent = CustomEvent<
Expand Down

0 comments on commit aec29ae

Please sign in to comment.