diff --git a/docs/docs.json b/docs/docs.json index 2abfffc7..719018ec 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -245,7 +245,8 @@ "router/cosmo-streams/custom-modules", "router/cosmo-streams/custom-modules/subscription-on-start", "router/cosmo-streams/custom-modules/on-receive-event", - "router/cosmo-streams/custom-modules/on-publish-event" + "router/cosmo-streams/custom-modules/on-publish-event", + "router/cosmo-streams/custom-modules/general-usage" ] } ] diff --git a/docs/router/cosmo-streams/custom-modules.mdx b/docs/router/cosmo-streams/custom-modules.mdx index d40ac79e..e333c985 100644 --- a/docs/router/cosmo-streams/custom-modules.mdx +++ b/docs/router/cosmo-streams/custom-modules.mdx @@ -19,3 +19,7 @@ The Cosmo Streams system provides three main hook interfaces that you can implem - [`SubscriptionOnStartHandler`](/router/cosmo-streams/custom-modules/subscription-on-start): Called when a client subscribes - [`OnReceiveEventHandler`](/router/cosmo-streams/custom-modules/on-receive-event): Called when events are received from a message broker - [`OnPublishEventHandler`](/router/cosmo-streams/custom-modules/on-publish-event): Called when events are going to be sent to a message broker + +For more information about each individual hook, please refer to the respective documentation page. + +For a general usage of Custom Modules, please refer to the [General Usage](/router/cosmo-streams/custom-modules/general-usage) documentation page. \ No newline at end of file diff --git a/docs/router/cosmo-streams/custom-modules/general-usage.mdx b/docs/router/cosmo-streams/custom-modules/general-usage.mdx new file mode 100644 index 00000000..4ea48035 --- /dev/null +++ b/docs/router/cosmo-streams/custom-modules/general-usage.mdx @@ -0,0 +1,119 @@ +--- +title: "General Usage" +description: "General usage of Cosmo Streams Custom Modules across all available hooks" +icon: "gear" +--- + +This page describes concepts that are shared across all Cosmo Streams handlers and apply to every available hook. + +## Operation Variables + +If your operation defines variables, you can access them through the `Variables` method on the `OperationContext` interface. + +```go +variables := ctx.Operation().Variables() +``` + +```graphql +subscription($customerId: Int!) { + orderUpdates(customerId: $customerId) { + id + } +} +``` + +Example variables payload: + +```json +{ + "customerId": 123 +} +``` + +Inside your handler, you can retrieve the variables using the `Variables` method: + +```go +variables := ctx.Operation().Variables() +customerId := variables.Get("customerId").GetInt() // = 123 +``` + +## Operation Arguments + +If no variables are defined in the operation, or if you do not control the variables, +you can access arguments directly via the `OperationContext` interface. + +```go +arguments := ctx.Operation().Arguments() +``` + +Consider an operation that defines multiple arguments: + +```graphql +subscription { + orderUpdates(customerId: "123", status: PENDING) { + id + items(first: 5, sortBy: "price") { name } + } +} +``` + +To access the `customerId` argument of the subscription field, use the `Get` method: + +```go +customerId := ctx.Operation().Arguments().Get("orderUpdates", "customerId").GetStringBytes() +``` + +Because `orderUpdates` is the root field, you can also resolve the field name dynamically: + +```go +// For OnPublishEvent handler +rootFieldName := ctx.PublishEventConfiguration().RootFieldName() + +// For OnReceiveEvent and SubscriptionOnStart handler +rootFieldName := ctx.SubscriptionEventConfiguration().RootFieldName() + +customerId := ctx.Operation().Arguments().Get(rootFieldName, "customerId").Value() +``` + +To access arguments on nested fields, such as the `sortBy` argument of the `items` field, +use dot notation to reference the nested path. + +```go +sortBy := ctx.Operation().Arguments().Get("orderUpdates.items", "sortBy").GetStringBytes() +``` + +When a field uses an alias, the alias must be used as the key when accessing its arguments. + +```graphql +subscription { + orderUpdates(customerId: "123", status: PENDING) { + id + cheapestItems: items(first: 3, sortBy: "price") { name } + newestItems: items(first: 3, sortBy: "createdAt") { name } + } +} +``` + +```go +cheapestItemsSortBy := ctx.Operation().Arguments().Get("orderUpdates.cheapestItems", "sortBy").GetStringBytes() +newestItemsSortBy := ctx.Operation().Arguments().Get("orderUpdates.newestItems", "sortBy").GetStringBytes() +``` + +You can also work with more complex argument types, such as arrays and input objects. + +```graphql +subscription { + orderUpdates(statuses: ["pending", "shipped"], filter: { minTotal: 100, currency: "USD" }) { + id + } +} +``` + +```go +arguments := ctx.Operation().Arguments() + +statuses := arguments.Get("orderUpdates", "statuses").GetArray() +filter := arguments.Get("orderUpdates", "filter").GetObject() +minTotal := filter.Get("minTotal").GetInt() +currency := filter.Get("currency").GetStringBytes() +```