Documentation Improvement by adding an example and description for initialEvent for custom subscriptions

[AC4G]

Over the last few days I've been trying to create a custom subscription that sends the data directly after connecting. However, there is no example in the documentation of an initial event or any evidence that there is an interface for it. The default behavior of an custom subscription is that it only fetches the previous data and the new data (on insert) after an event was been triggered on the database side.

I only got the information about the initialEvent from the discord server:

• By providing the initialEvent argument to @pgSubscription(...) in typeDefs you can pass to it the function which you want to be executed on connection establishment the same way as currentUserTopicFromContext from the docs to topic:

currentUserUpdated: UserSubscriptionPayload @pgSubscription(topic: ${embed(
   currentUserTopicFromContext,
)})

with initialEvent:

currentUserUpdated: UserSubscriptionPayload @pgSubscription(topic: ${embed(
   currentUserTopicFromContext,
)}, initialEvent: ${embed(
   onInitialEvent, //the function that you want to be executed
)})

The function that you want to be executed in initialEvent has the same structure as currentUserTopicFromContext:

const onInitialEvent = async (_args, context, _resolveInfo) => {
   // do something
  return {}; // return an object 
}

Now because returning an empty object was the solution for my problem (get already existing data on connection establishment), I didn't dig any deeper on what arguments I can give to the object to control the behavior and what operations can be done in the initialEvent function. This can be added additionally to the documentation.

Adding description for initialEvent and examples for it to the documentation to make it clear that something like that exists would help allot.

[benjie]

Indeed, this is why in V5 we've integrated the website into the source repository so that the documentation is tightly coupled with landing the feature.

If someone wants to take on adding this to the documentation it should just be a case of using the "Suggest improvement/edit this page" at the top of the page, probably this page: https://www.graphile.org/postgraphile/subscriptions/

The object you return is the "event" object; it is equivalent to the payload that you'd pass to the pg_notify() call.