From 7b75f61374541e9e55899098fe30b4ef6bba671e Mon Sep 17 00:00:00 2001 From: Dominik Korittki <23359034+dkorittki@users.noreply.github.com> Date: Fri, 12 Dec 2025 14:49:54 +0100 Subject: [PATCH 1/2] feat: add variables and arguments usage docs --- docs/docs.json | 3 +- docs/router/cosmo-streams/custom-modules.mdx | 4 + .../custom-modules/general-usage.mdx | 119 ++++++++++++++++++ 3 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 docs/router/cosmo-streams/custom-modules/general-usage.mdx 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..28224fa5 --- /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 for all available hooks" +icon: "gear" +--- + +This documentation page covers concepts that are common to all available Cosmo Streams handlers. + +## Operation Variables + +If variables are used in the operation, you can access them using the `Variables` method on the `OperationContext` interface. + +```go +variables := ctx.Operation().Variables() +``` + +```graphql +subscription($customerId: Int!) { + orderUpdates(customerId: $customerId) { + id + } +} +``` + +Provided variables: + +```json +{ + "customerId": 123 +} +``` + +Inside your handler, you can access the variables using the `Variables` method. + +```go +variables := ctx.Operation().Variables() +customerId := variables.Get("customerId").GetInt() // = 123 +``` + +## Operation Arguments + +In case no variables are used in the operation, or there is no control over the variables, +you can access the operation arguments using the `OperationContext` interface, too. + +```go +arguments := ctx.Operation().Arguments() +``` + +Suppose you have an operation with multiple arguments + +```graphql +subscription { + orderUpdates(customerId: "123", status: PENDING) { + id + items(first: 5, sortBy: "price") { name } + } +} +``` + +In order to access the subscription argument `customerId`, you need to use the `Get` method. +```go +customerId := ctx.Operation().Arguments().Get("orderUpdates", "customerId").GetStringBytes() +``` + +Since `orderUpdates` is the root field, you can also write the code with a more general approach + +```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() +``` + +In order to access an argument of a nested field, like the `sortBy` argument of the `items` field, +you need to use the dot notation to access the nested field. + +```go +sortBy := ctx.Operation().Arguments().Get("orderUpdates.items", "sortBy").GetStringBytes() +``` + +If you use an alias for a field, you need to use the alias as the key to access the argument. + +```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 access more complex arguments, like arrays and 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() +``` \ No newline at end of file From 982a2bd417fc8f86e75a78057501e7fb2bb1ba6d Mon Sep 17 00:00:00 2001 From: Dominik Korittki <23359034+dkorittki@users.noreply.github.com> Date: Fri, 12 Dec 2025 14:58:05 +0100 Subject: [PATCH 2/2] chore: rephrase --- .../custom-modules/general-usage.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/router/cosmo-streams/custom-modules/general-usage.mdx b/docs/router/cosmo-streams/custom-modules/general-usage.mdx index 28224fa5..4ea48035 100644 --- a/docs/router/cosmo-streams/custom-modules/general-usage.mdx +++ b/docs/router/cosmo-streams/custom-modules/general-usage.mdx @@ -1,14 +1,14 @@ --- title: "General Usage" -description: "General usage of Cosmo Streams Custom Modules for all available hooks" +description: "General usage of Cosmo Streams Custom Modules across all available hooks" icon: "gear" --- -This documentation page covers concepts that are common to all available Cosmo Streams handlers. +This page describes concepts that are shared across all Cosmo Streams handlers and apply to every available hook. ## Operation Variables -If variables are used in the operation, you can access them using the `Variables` method on the `OperationContext` interface. +If your operation defines variables, you can access them through the `Variables` method on the `OperationContext` interface. ```go variables := ctx.Operation().Variables() @@ -22,7 +22,7 @@ subscription($customerId: Int!) { } ``` -Provided variables: +Example variables payload: ```json { @@ -30,7 +30,7 @@ Provided variables: } ``` -Inside your handler, you can access the variables using the `Variables` method. +Inside your handler, you can retrieve the variables using the `Variables` method: ```go variables := ctx.Operation().Variables() @@ -39,14 +39,14 @@ customerId := variables.Get("customerId").GetInt() // = 123 ## Operation Arguments -In case no variables are used in the operation, or there is no control over the variables, -you can access the operation arguments using the `OperationContext` interface, too. +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() ``` -Suppose you have an operation with multiple arguments +Consider an operation that defines multiple arguments: ```graphql subscription { @@ -57,12 +57,13 @@ subscription { } ``` -In order to access the subscription argument `customerId`, you need to use the `Get` method. +To access the `customerId` argument of the subscription field, use the `Get` method: + ```go customerId := ctx.Operation().Arguments().Get("orderUpdates", "customerId").GetStringBytes() ``` -Since `orderUpdates` is the root field, you can also write the code with a more general approach +Because `orderUpdates` is the root field, you can also resolve the field name dynamically: ```go // For OnPublishEvent handler @@ -71,18 +72,17 @@ rootFieldName := ctx.PublishEventConfiguration().RootFieldName() // For OnReceiveEvent and SubscriptionOnStart handler rootFieldName := ctx.SubscriptionEventConfiguration().RootFieldName() - customerId := ctx.Operation().Arguments().Get(rootFieldName, "customerId").Value() ``` -In order to access an argument of a nested field, like the `sortBy` argument of the `items` field, -you need to use the dot notation to access the nested field. +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() ``` -If you use an alias for a field, you need to use the alias as the key to access the argument. +When a field uses an alias, the alias must be used as the key when accessing its arguments. ```graphql subscription { @@ -99,7 +99,7 @@ cheapestItemsSortBy := ctx.Operation().Arguments().Get("orderUpdates.cheapestIte newestItemsSortBy := ctx.Operation().Arguments().Get("orderUpdates.newestItems", "sortBy").GetStringBytes() ``` -You can also access more complex arguments, like arrays and objects. +You can also work with more complex argument types, such as arrays and input objects. ```graphql subscription { @@ -116,4 +116,4 @@ statuses := arguments.Get("orderUpdates", "statuses").GetArray() filter := arguments.Get("orderUpdates", "filter").GetObject() minTotal := filter.Get("minTotal").GetInt() currency := filter.Get("currency").GetStringBytes() -``` \ No newline at end of file +```