This group contains methods that listen for changes made via post, and delete or fetched from get, discover, or continueDiscover and then streams appropriate changes to provide a responsive and consistent user experience.
Wraps a Graffiti API instance to provide the synchronize methods. The GraffitiSyncrhonize class rather than the Graffiti class must be used for all functions for the synchronize methods to work.
The Graffiti API instance to wrap.
Optionaloptions: GraffitiSynchronizeOptionsProtectedajv_Protected ReadonlycallbacksProtected ReadonlygraffitiProtected ReadonlyoptionsProtectedobjectProtectedobjectProtectedsynchronizeOptionalsession: GraffitiSession | nullProtectedsynchronizeStreams changes made to any object in any channel and made by any user. You may want to use it in conjuction with GraffitiSynchronizeOptions.omniscient to get a global view of all Graffiti objects passing through the system. This is useful for building a client-side cache, for example.
Be careful using this method. Without additional filters it can expose the user to content out of context.
Optionalsession: GraffitiSession | nullThis method has the same signature as discover but listens for changes made via post and delete or fetched from get, discover, and continueDiscover and then streams appropriate changes to provide a responsive and consistent user experience.
Unlike discover, this method continuously listens for changes
and will not terminate unless the user calls the return method on the iterator
or breaks out of the loop.
Optionalsession: GraffitiSession | nullThis method has the same signature as get but listens for changes made via post, and delete or fetched from get, discover, and continueDiscover and then streams appropriate changes to provide a responsive and consistent user experience.
Unlike get, which returns a single result, this method continuously listens for changes which are output as an asynchronous stream, similar to discover.
Optionalsession: GraffitiSession | nullDeletes an object from a given url
that had previously been posted.
The deleting actor must be the same as the
actor that created the object.
The location of the object to delete.
An implementation-specific object with information to authenticate the
actor.
GraffitiErrorNotFound if the object does not exist, has already been deleted,
or the actor is not allowed to access it.
GraffitiErrorForbidden if the actor
is not the same actor as the one who created the object.
Retrieves an object from a given url matching
the provided schema.
If the retreiving actor is not
the object's actor,
the object's allowed and
channels properties are
not revealed, similar to a BCC email.
The location of the object to get.
The JSON schema to validate the retrieved object against.
Optionalsession: GraffitiSession | nullReturns the retrieved object.
GraffitiErrorNotFound if the object does not exist, has been deleted, or the actor is not
allowed to access it.
GraffitiErrorSchemaMismatch if the retrieved object does not match the provided schema.
Creates a new object.
An object to post, minus its url and
actor, which will be assigned once posted.
This object is statically type-checked against the JSON schema that can be optionally provided
as the generic type parameter. It is recommended to use a schema to
ensure that the posted object matches subsequent get or discover
methods.
An implementation-specific object with information to authenticate the
actor.
Returns the object that has been posted, complete with its
assigned url and
actor.
Continues a GraffitiObjectStream from a given
cursor string.
The continuation will return new objects that have been posted
that match the original stream, and also returns the
urls of objects that
have been deleted, as marked by a tombstone.
The cursor allows the client to
serialize the state of the stream and continue it later.
However this method loses any typing information that was
present in the original stream. For better type safety
and when serializing is not necessary, use the
continue method
instead, which is returned along with the cursor at the
end of the original stream.
GraffitiErrorForbidden if the actor
provided in the session is not the same as the actor
that initiated the original stream.
Discovers objects created by any actor that are contained
in at least one of the given channels
and match the given JSON Schema.
Objects are returned asynchronously as they are discovered but the stream
will end once all leads have been exhausted.
The GraffitiObjectStream ends by returning a
continue method and a
cursor string,
each of which can be be used to poll for new objects.
The continue method preserves the type safety of the stream and the cursor
string can be serialized to continue the stream after an application is closed
and reopened.
discover will not return objects that the querying actor
is not 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 channels
not specified by the discover method will not be revealed. This masking happens
before the object is validated against the supplied schema.
Since different implementations may fetch data from multiple sources there is no guarentee on the order that objects are returned in.
The channels that objects must be associated with.
A JSON Schema that objects must satisfy.
Optionalsession: GraffitiSession | nullReturns a stream of objects that match the given channels
and JSON Schema.
Deletes media previously posted to a given URL.
A globally unique identifier and locator for the media.
An implementation-specific object with information to authenticate the
actor.
GraffitiErrorNotFound if no media at that URL exists.
GraffitiErrorForbidden if the actor
provided in the session is not the same as the actor that posted
the media.
Retrieves media from the given media URL, adhering to the given requirements.
A globally unique identifier and locator for the media.
A set of requirements the retrieved media must meet.
Optionalaccept?: stringA list of acceptable media types for the retrieved media, formatted as like an HTTP Accept header
OptionalmaxBytes?: numberThe maximum acceptable size, in bytes, of the media.
Optionalsession: GraffitiSession | nullAn implementation-specific object with information to authenticate the
actor.
The URL of the retrieved media, as a Blob
and the actor that posted it.
GraffitiErrorNotFound if no media at that URL exists.
GraffitiErrorTooLarge if the media exceeds the given maxBytes.
GraffitiErrorNotAcceptable if the media does not match the given
accept specification.
Uploads media data, such as an image or video.
Unlike structured objects,
media is not indexed for discovery and
must be retrieved by its exact URL using getMedia
Optionalallowed?: string[] | nullThe binary data of the media to be uploaded, along with its media type, formatted as a Blob.
An implementation-specific object with information to authenticate the
actor.
The URL that the media was posted to.
Retrieves the human-readable handle associated with the given actor. The handle may change over time and so it should be used for display purposes only.
The inverse of handleToActor.
A human-readable handle for the given actor.
GraffitiErrorNotFound if a handle cannot be found for the given actor.
Retrieves the actor ID associated with the given handle.
The inverse of actorToHandle.
The actor ID for the given handle.
GraffitiErrorNotFound if there is no actor with the given handle.
Begins the login process. Depending on the implementation, this may involve redirecting to a login page or opening a popup, so it should always be called in response to a gesture, such as clicking a button, due to the feature-gating browser security feature.
The session object is returned
asynchronously via sessionEvents
as a GraffitiLoginEvent with event type login.
Optionalactor: stringA suggested actor to login as. For example, if a user tries to edit a post but are not logged in, the interface can infer that they might want to log in as the actor who created the post they are attempting to edit.
Even if provided, the implementation should allow the user to log in as a different actor if they choose.
Begins the logout process for a particular session. 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 gesture, such as clicking a button, due to the feature-gating browser security feature.
A confirmation will be returned asynchronously via
sessionEvents
as a GraffitiLogoutEvent as event type logout.
The session object to logout.
An event target that can be used to listen for the following events and their corresponding event types:
login - GraffitiLoginEventlogout - GraffitiLogoutEventinitialized - GraffitiSessionInitializedEvent
Wraps the Graffiti API so that changes made or received in one part of an application are automatically routed to other parts of the application. This is an important tool for building responsive and consistent user interfaces, and is built upon to make the Graffiti Vue Plugin and possibly other front-end libraries in the future.
See a live example.
Specifically, this library provides the following synchronize methods to correspond with each of the following Graffiti API methods:
Whenever a change is made via post and delete or received from get, discover, and continueDiscover, those changes are forwarded to the appropriate synchronize method. Each synchronize method returns an iterator that streams these changes continually until the user calls
returnon the iterator orbreaks out of the loop, allowing for live updates without additional polling.Example 1: Suppose a user publishes a post using post. If the feed displaying that user's posts is using 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 get or discover), then 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.
Additionally, the library supplies a synchronizeAll method that can be used to stream all the Graffiti changes that an application is aware of, which can be used for caching or history building.
The source code for this library is available on GitHub.